1/**************************************************************
2 *
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements.  See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership.  The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License.  You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied.  See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 *
20 *************************************************************/
21
22
23#ifndef __com_sun_star_rendering_XCanvas_idl__
24#define __com_sun_star_rendering_XCanvas_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
30#include <com/sun/star/lang/IllegalArgumentException.idl>
31#endif
32#ifndef __com_sun_star_geometry_RealPoint2D_idl__
33#include <com/sun/star/geometry/RealPoint2D.idl>
34#endif
35#ifndef __com_sun_star_geometry_RealBezierSegment2D_idl__
36#include <com/sun/star/geometry/RealBezierSegment2D.idl>
37#endif
38#ifndef __com_sun_star_geometry_RealRectangle2D_idl__
39#include <com/sun/star/geometry/RealRectangle2D.idl>
40#endif
41#ifndef __com_sun_star_geometry_Matrix2D_idl__
42#include <com/sun/star/geometry/Matrix2D.idl>
43#endif
44#ifndef __com_sun_star_rendering_ViewState_idl__
45#include <com/sun/star/rendering/ViewState.idl>
46#endif
47#ifndef __com_sun_star_rendering_RenderState_idl__
48#include <com/sun/star/rendering/RenderState.idl>
49#endif
50#ifndef __com_sun_star_rendering_FontRequest_idl__
51#include <com/sun/star/rendering/FontRequest.idl>
52#endif
53#ifndef __com_sun_star_rendering_FontInfo_idl__
54#include <com/sun/star/rendering/FontInfo.idl>
55#endif
56#ifndef __com_sun_star_rendering_Texture_idl__
57#include <com/sun/star/rendering/Texture.idl>
58#endif
59#ifndef __com_sun_star_rendering_StringContext_idl__
60#include <com/sun/star/rendering/StringContext.idl>
61#endif
62#ifndef __com_sun_star_rendering_StrokeAttributes_idl__
63#include <com/sun/star/rendering/StrokeAttributes.idl>
64#endif
65#ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
66#include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
67#endif
68
69#ifndef __com_sun_star_beans_PropertyValue_idl__
70#include <com/sun/star/beans/PropertyValue.idl>
71#endif
72
73
74module com {  module sun {  module star {  module geometry {
75    published interface XMapping2D;
76}; }; }; };
77
78module com { module sun { module star { module rendering {
79
80published interface XCanvasFont;
81published interface XPolyPolygon2D;
82published interface XCachedPrimitive;
83published interface XBitmap;
84published interface XGraphicDevice;
85published interface XTextLayout;
86
87/** Central interface for rendering.<p>
88
89    This is the central interface for graphical output production, and
90    the place where all draw methods are located.<p>
91
92    Some notes are in order to explain the concepts used here. The
93    <type>XCanvas</type> interface is free of client-modifiable state,
94    i.e. it can be used safely and without external synchronization in
95    a multi-threaded environment. On the other hand, this implies that
96    for nearly every canvas operation, external state is
97    required. This is provided by <type>ViewState</type> and
98    <type>RenderState</type> in a unified fashion, supplemented by a
99    few extra state parameters for some methods (e.g. textured
100    polygons or text rendering).<p>
101
102    When used careless, this scheme can be inefficient to some extend,
103    because internally, view, render and other states have to be
104    combined before rendering. This is especially expensive for
105    complex clip polygons, i.e. when both <type>ViewState</type> and
106    <type>RenderState</type> have a complex clip polygon set, which
107    have to be intersected before rendering. It is therefore
108    recommended to combine <type>ViewState</type> and
109    <type>RenderState</type> already at the client side, when objects
110    are organized in a hierarchical way: the classic example are
111    grouped draw shapes, whose parent group object imposes a
112    common clipping and a common transformation on its siblings. The
113    group object would therefore merge the <type>ViewState</type> and
114    the <type>RenderState</type> it is called with into a new
115    <type>ViewState</type>, and call its siblings with a
116    <type>RenderState</type> containing only the local offset (and no
117    extra clipping).<p>
118
119    Furtheron, this stateless nature provides easy ways for
120    caching. Every non-trivial operation on <type>XCanvas</type> can
121    return a cache object, which, when called to redraw, renders the
122    primitive usually much more quickly than the original method. Note
123    that such caching is a lot more complicated, should the actual
124    rendering a method yields depend on internal state (which is the
125    case e.g. for the
126    <type
127    scope="::com::sun::star::drawing">::com::sun::star::drawing::XGraphics</type>
128    interface).  Please note, though, that deciding whether to return
129    an <type>XCachedPrimitive</type> is completely up to the
130    implementation - don't rely on the methods returning something
131    (this is because there might be cases when returning such a cache
132    object will actually be a pessimization, since it involves memory
133    allocation and comparisons).<p>
134
135    Things that need more than a small, fixed amount of data are
136    encapsulated in own interfaces, e.g. polygons and bitmaps. You
137    can, in principle, roll your own implementations of these
138    interfaces, wrap it around your internal representation of
139    polygons and bitmaps, and render them. It might just not be overly
140    fast, because the <type>XCanvas</type> would need to convert for
141    each render call. It is therefore recommended to create such
142    objects via the <type>XGraphicDevice</type> factory (to be
143    retrieved from every canvas object via the
144    <member>getDevice()</member> call) - they will then internally
145    optimize to the underlying graphics subsystem.<p>
146
147    @since OpenOffice 2.0
148 */
149published interface XCanvas : ::com::sun::star::uno::XInterface
150{
151    /** Clear the whole canvas area.<p>
152
153        This method clears the whole canvas area to the device default
154        color (e.g. white for a printer, transparent for an
155        <type>XCustomSprite</type>).
156     */
157    void                clear();
158
159     /** Draw a point in device resolution on the device.
160
161        @param aPoint
162        The point to draw.
163
164        @param aViewState
165        The viewstate to be used when drawing this point.
166
167        @param aRenderState
168        The renderstate to be used when drawing this point.
169
170        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
171        if one of the view and renderstate parameters are outside the
172        specified range.
173     */
174    void				drawPoint( [in] ::com::sun::star::geometry::RealPoint2D aPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
175        raises (com::sun::star::lang::IllegalArgumentException);
176
177    //-------------------------------------------------------------------------
178
179    /** Draw a line in device resolution width (i.e. one device	pixel
180        wide).
181
182        @param aStartPoint
183        The start point of the line to draw.
184
185        @param aEndPoint
186        The end point of the line to draw.
187
188        @param aViewState
189        The viewstate to be used when drawing this line.
190
191        @param aRenderState
192        The renderstate to be used when drawing this line.
193
194        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
195        if one of the view and renderstate parameters are outside the
196        specified range.
197     */
198    void				drawLine( [in] ::com::sun::star::geometry::RealPoint2D aStartPoint, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
199        raises (com::sun::star::lang::IllegalArgumentException);
200
201    //-------------------------------------------------------------------------
202
203    /** Draw a cubic bezier curve in device resolution width (i.e. one
204        device pixel wide).
205
206        @param aBezierSegment
207        The start and the two control points of the bezier curve.
208
209        @param aEndPoint
210        The end point of the bezier curve.
211
212        @param aViewState
213        The viewstate to be used when drawing this curve.
214
215        @param aRenderState
216        The renderstate to be used when drawing this curve.
217
218        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
219        if one of the view and renderstate parameters are outside the
220        specified range.
221     */
222    void				drawBezier( [in] ::com::sun::star::geometry::RealBezierSegment2D aBezierSegment, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState )
223        raises (com::sun::star::lang::IllegalArgumentException);
224
225    //-------------------------------------------------------------------------
226
227    /** Draw a poly-polygon in device resolution line width (i.e. the
228        lines are one device pixel wide).
229
230        @param xPolyPolygon
231        The poly-polygon to draw.
232
233        @param aViewState
234        The viewstate to be used when drawing this polygon.
235
236        @param aRenderState
237        The renderstate to be used when drawing this polygon.
238
239        @return a handle to the cached rendering output.
240
241        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
242        if one of the view and renderstate parameters are outside the
243        specified range.
244     */
245    XCachedPrimitive	drawPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState )
246        raises (com::sun::star::lang::IllegalArgumentException);
247
248    //-------------------------------------------------------------------------
249
250    /** Stroke each polygon of the provided poly-polygon with the
251        specified stroke attributes.<p>
252
253        This method considers the stroking of all polygons as an
254        atomic operation in relation to the <type>RenderState</type>'s
255        <type>CompositeOperationy</type> operation. That means,
256        overlapping strokes from distinct polygons will look exactly
257        as overlapping segments of the same polygon, even with
258        transparency.<p>
259
260        @param xPolyPolygon
261        The poly-polygon to render.
262
263        @param aViewState
264        The viewstate to be used when stroking this polygon.
265
266        @param aRenderState
267        The renderstate to be used when stroking this polygon.
268
269        @param aStrokeAttributes
270        Further attributes used to parameterize the stroking.
271
272        @return a handle to the cached rendering output.
273
274        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
275        if one of the view and renderstate parameters are outside the
276        specified range.
277     */
278    XCachedPrimitive	strokePolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes )
279        raises (com::sun::star::lang::IllegalArgumentException);
280
281    //-------------------------------------------------------------------------
282
283    /** Stroke each polygon of the provided poly-polygon with the
284        specified stroke attributes, fill the stroked outline
285        with the specified texture graphics.<p>
286
287        This method considers the stroking of all polygons as an
288        atomic operation in relation to the <type>RenderState</type>'s
289        <type>CompositeOp</type> operation. That means, overlapping
290        strokes from distinct polygons will look exactly as
291        overlapping segments of the same polygon, even with
292        transparency.<p>
293
294        @param xPolyPolygon
295        The poly-polygon to render.
296
297        @param aViewState
298        The viewstate to be used when strokes this polygon.
299
300        @param aRenderState
301        The renderstate to be used when stroking this polygon.
302
303        @param aTextures
304        A sequence of texture definitions, with which to fill the
305        stroked area.
306
307        @param aStrokeAttributes
308        Further attributes used to parameterize the stroking.
309
310        @return a handle to the cached rendering output.
311
312        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
313        if one of the view and renderstate parameters are outside the
314        specified range.
315
316        @throws <type>VolatileContentDestroyedException</type>
317        if a texture bitmap was volatile, and the content was
318        destroyed before the rendering could take place.
319     */
320    XCachedPrimitive	strokeTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> aTextures, [in] StrokeAttributes aStrokeAttributes )
321        raises (com::sun::star::lang::IllegalArgumentException,
322                VolatileContentDestroyedException);
323
324    //-------------------------------------------------------------------------
325
326    /** Stroke each polygon of the provided poly-polygon with the
327        specified stroke attributes, fill the stroked outline
328        with the specified texture graphics, map the texture to the
329        outline via the specified texture mapping.<p>
330
331        This method considers the stroking of all polygons as an
332        atomic operation in relation to the <type>RenderState</type>'s
333        <type>CompositeOp</type> operation. That means, overlapping
334        strokes from distinct polygons will look exactly as
335        overlapping segments of the same polygon, even with
336        transparency.
337
338        @param xPolyPolygon
339        The poly-polygon to render.
340
341        @param aViewState
342        The viewstate to be used when stroking this polygon.
343
344        @param aRenderState
345        The renderstate to be used when stroking this polygon.
346
347        @param aTextures
348        A sequence of texture definitions, with which to fill the
349        stroked area.
350
351        @param xMapping
352        A bilinear mapping function which defines the warping of the
353        textures on the output area.
354
355        @param aStrokeAttributes
356        Further attributes used to parameterize the stroking.
357
358        @return a handle to the cached rendering output.
359
360        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
361        if one of the view and renderstate parameters are outside the
362        specified range.
363
364        @throws <type>VolatileContentDestroyedException</type>
365        if a texture bitmap was volatile, and the content was
366        destroyed before the rendering could take place.
367     */
368    XCachedPrimitive	strokeTextureMappedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> aTextures, [in] ::com::sun::star::geometry::XMapping2D xMapping, [in] StrokeAttributes aStrokeAttributes )
369        raises (com::sun::star::lang::IllegalArgumentException,
370                VolatileContentDestroyedException);
371
372    //-------------------------------------------------------------------------
373
374    //  [TODO: Method misplaced at this interface?]
375
376    /** Query the polygonal representation of the stroke outlines, as
377        it would be generated by the strokePolyPolygon methods.<p>
378
379        This method can be used to e.g. set a clipping which covers the same
380        area as a stroke.<p>
381
382        @param xPolyPolygon
383        The poly-polygon to render.
384
385        @param aViewState
386        The viewstate to be used when generating the outline.
387
388        @param aRenderState
389        The renderstate to be used when generating the outline.
390
391        @param aStrokeAttributes
392        Further attributes used to parameterize the stroking.
393
394        @return a poly-polygon describing the outline of the stroked
395        area.
396
397        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
398        if one of the view and renderstate parameters are outside the
399        specified range.
400     */
401    XPolyPolygon2D          queryStrokeShapes( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes )
402        raises (com::sun::star::lang::IllegalArgumentException);
403
404    //-------------------------------------------------------------------------
405
406    /** Fill the given poly-polygon.<p>
407
408        This method fills the given poly-polygon according to the
409        <type>RenderState</type>'s color and the poly-polygon's fill
410        rule.<p>
411
412        @param xPolyPolygon
413        The poly-polygon to render.
414
415        @param aViewState
416        The viewstate to be used when filling this polygon.
417
418        @param aRenderState
419        The renderstate to be used when filling this polygon.
420
421        @return a handle to the cached rendering output.
422
423        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
424        if one of the view and renderstate parameters are outside the
425        specified range.
426     */
427    XCachedPrimitive	fillPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState )
428        raises (com::sun::star::lang::IllegalArgumentException);
429
430    //-------------------------------------------------------------------------
431
432    /** Fill the given poly-polygon with a texture.<p>
433
434        This method fills the given poly-polygon according to the
435        <type>RenderState</type>'s color, the given textures and
436        poly-polygon's fill rule.<p>
437
438        @param xPolyPolygon
439        The poly-polygon to render.
440
441        @param aViewState
442        The viewstate to be used when filling this polygon.
443
444        @param aRenderState
445        The renderstate to be used when filling this polygon.
446
447        @param aTextures
448        A sequence of texture definitions, with which to fill the
449        polygonal area.
450
451        @return a handle to the cached rendering output.
452
453        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
454        if one of the view and renderstate parameters are outside the
455        specified range.
456
457        @throws <type>VolatileContentDestroyedException</type>
458        if a texture bitmap was volatile, and the content was
459        destroyed before the rendering could take place.
460    */
461    XCachedPrimitive	fillTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures )
462        raises (com::sun::star::lang::IllegalArgumentException,
463                VolatileContentDestroyedException);
464
465    //-------------------------------------------------------------------------
466
467    /** Fill the given poly-polygon with a mapped texture.<p>
468
469        This method fills the given poly-polygon according to the
470        <type>RenderState</type>'s color, the given textures and
471        poly-polygon's fill rule. The texture is mapped to the
472        poly-polygon's interior via the given texture mapping.<p>
473
474        @param xPolyPolygon
475        The poly-polygon to render.
476
477        @param aViewState
478        The viewstate to be used when filling this polygon.
479
480        @param aRenderState
481        The renderstate to be used when filling this polygon.
482
483        @param aTextures
484        A sequence of texture definitions, with which to fill the
485        polygonal area.
486
487        @param xMapping
488        A bilinear mapping function which defines the warping of the
489        textures on the output area.
490
491        @return a handle to the cached rendering output.
492
493        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
494        if one of the view and renderstate parameters are outside the
495        specified range.
496
497        @throws <type>VolatileContentDestroyedException</type>
498        if a texture bitmap was volatile, and the content was
499        destroyed before the rendering could take place.
500     */
501    XCachedPrimitive	fillTextureMappedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures, [in] ::com::sun::star::geometry::XMapping2D xMapping )
502        raises (com::sun::star::lang::IllegalArgumentException,
503                VolatileContentDestroyedException);
504
505    //-------------------------------------------------------------------------
506
507    /** Create a suitable font for the specified font description.
508
509        @param aFontRequest
510
511        @param aExtraFontProperties
512        Additional font properties to be applied when selecting this
513        font. Normally, you should not need this parameter. Currently,
514        the following properties are recognized:
515        <ul>
516
517            <il>Kerning: a <type>double</type> between 0 and 1, where
518            0 completely disables kerning. Whether kerning is on or
519            off by default is font-dependent.</il>
520
521            <il>IsEmphasisMarks: a <type>boolean</type>, where <TRUE/>
522            enables automatic placements of emphasis marks, e.g. for
523            Hebrew. The default value, if this property is not
524            specified, is <FALSE/>.</il>
525
526            <il>ExpandedSpacing: a <type>double</type> value which is added
527            between all cell distances for this font. The default value for
528            this property is zero. Use negative values for condensed output,
529            and positive values for expanded output.</il>
530
531            <il>OptionalLayoutFeatures: a sequence of <type
532            scope=::com::sun::star::beans>PropertyValue</type> listing
533            font-specific optional layout features, like glyph
534            variants.</il>
535
536        </ul>
537
538        @param aFontMatrix
539        Font-specific transformation matrix, which affects both the
540        glyphs as well as the advancement.
541
542        @returns the requested font, or an invalid reference, if the
543        request failed.
544
545        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
546        if one of the parameters is not within the allowed range.
547     */
548    XCanvasFont				createFont( [in] FontRequest aFontRequest, [in] sequence< ::com::sun::star::beans::PropertyValue > aExtraFontProperties, [in] ::com::sun::star::geometry::Matrix2D aFontMatrix )
549        raises (com::sun::star::lang::IllegalArgumentException);
550
551    //-------------------------------------------------------------------------
552
553    /** Query font information, specific to this canvas.<p>
554
555        @param aFilter
556        Filter parameter to reduce the list of returned fonts. Every
557        member of <type>FontInfo</type> that is not the empty string
558        or the "don't care" value restricts the list of returned fonts
559        to contain only those that have the specified attribute.
560
561        @param xFontProperties
562        This interface can provide additional font properties to
563        filter the list of available fonts against.
564
565        @returns the list of fonts matching the filter set.
566
567        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
568        if one of the font properties are invalid or not recognized,
569        or if one of the <type>FontInfo</type> members is not within
570        the permitted range.
571     */
572    sequence< FontInfo >	queryAvailableFonts( [in] FontInfo aFilter, [in] sequence< ::com::sun::star::beans::PropertyValue > aFontProperties )
573        raises (com::sun::star::lang::IllegalArgumentException);
574
575    //-------------------------------------------------------------------------
576
577    /** Draw the text given by the substring of the specified string
578        with the given font.<p>
579
580        The local origin of this output operation is either the left
581        end of the text baseline, for textDirection equal
582        LEFT_TO_RIGHT, or the right end of the baseline, for
583        textDirection equal to RIGHT_TO_LEFT, respectively.<p>
584
585        @param aText
586        The text to output.
587
588        @param xFont
589        The font retrieved from this canvas to be used when drawing
590        the text.
591
592        @param aViewState
593        The viewstate to be used when drawing this text.
594
595        @param aRenderState
596        The renderstate to be used when drawing this text.
597
598        @param nTextDirection
599        A value from the <type>TextDirection</type> collection,
600        denoting the main writing direction for this string. The main
601        writing direction determines the origin of the text output,
602        i.e. the left edge for left-to-right and the right edge for
603        right-to-left text.
604
605        @return a handle to the cached rendering output.
606
607        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
608        if one of the view and renderstate parameters are outside the
609        specified range.
610     */
611    XCachedPrimitive		drawText( [in] StringContext aText, [in] XCanvasFont xFont, [in] ViewState aViewState, [in] RenderState aRenderState, [in] byte nTextDirection )
612        raises (com::sun::star::lang::IllegalArgumentException);
613
614    //-------------------------------------------------------------------------
615
616    /** Draw the formatted text given by the text layout.<p>
617
618        The glyphs as represented by the text layout are always output
619        with the reference position being the leftmost edge of the
620        layout object's baseline. If the layout contains more than one
621        baseline, the baseline of the first strong character in
622        logical order is used here (strong in this context means that
623        the character can be unambiguously assigned to a unicode
624        script).<p>
625
626        @param xLayoutetText
627        An interface to the readily layouted text, obtained from a
628        <type>XCanvasFont</type> created at this canvas. The text
629        layout already carries intrinsic font information.
630
631        @param aViewState
632        The viewstate to be used when drawing this text.
633
634        @param aRenderState
635        The renderstate to be used when drawing this text.
636
637        @return a handle to the cached rendering output.
638
639        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
640        if one of the view and renderstate parameters are outside the
641        specified range.
642     */
643    XCachedPrimitive		drawTextLayout( [in] XTextLayout xLayoutetText, [in] ViewState aViewState, [in] RenderState aRenderState )
644        raises (com::sun::star::lang::IllegalArgumentException);
645
646    //-------------------------------------------------------------------------
647
648    /** Render the given bitmap.<p>
649
650        This method renders the bitmap, at a position and shape as
651        specified by the combined view and render transformations. For
652        fast render speed, the bitmap should be created by the
653        corresponding <type>XGraphicDevice</type>'s
654        <member>XGraphicDevice::createCompatibleBitmap()</member>
655        method.<p>
656
657        @param xBitmap
658        The bitmap to render.
659
660        @param aViewState
661        The viewstate to be used when drawing this text.
662
663        @param aRenderState
664        The renderstate to be used when drawing this text.
665
666        @return a handle to the cached rendering output.
667
668        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
669        if one of the view and renderstate parameters are outside the
670        specified range.
671
672        @throws <type>VolatileContentDestroyedException</type>
673        if a texture bitmap was volatile, and the content was
674        destroyed before the rendering could take place.
675     */
676    XCachedPrimitive		drawBitmap( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState )
677        raises (com::sun::star::lang::IllegalArgumentException,
678                VolatileContentDestroyedException);
679
680    /** Render the given bitmap, with a global color modulation.<p>
681
682        This method renders the bitmap, at a position and shape as
683        specified by the combined view and render transformations. For
684        fast render speed, the bitmap should be created by the
685        corresponding <type>XGraphicDevice</type>'s
686        <member>XGraphicDevice::createCompatibleBitmap()</member>
687        method. The bitmap's color channel values are multiplied with
688        the device color values as specified in the render state.<p>
689
690        @param xBitmap
691        The bitmap to render.
692
693        @param aViewState
694        The viewstate to be used when drawing this text.
695
696        @param aRenderState
697        The renderstate to be used when drawing this text. The device
698        color entry in the renderstate is multiplied with every pixel
699        color value, and only the result is rendered into the
700        canvas. If, for example, the bitmap should be rendered with
701        increased global transparency, set all device color channels
702        to 1.0, except for the alpha channel, which should be set to
703        the desired transparency.
704
705        @return a handle to the cached rendering output.
706
707        @throws <type>com::sun::star::lang::IllegalArgumentException</type>
708        if one of the view and renderstate parameters are outside the
709        specified range.
710
711        @throws <type>VolatileContentDestroyedException</type>
712        if a texture bitmap was volatile, and the content was
713        destroyed before the rendering could take place.
714     */
715    XCachedPrimitive		drawBitmapModulated( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState )
716        raises (com::sun::star::lang::IllegalArgumentException,
717                VolatileContentDestroyedException);
718
719    //-------------------------------------------------------------------------
720
721    /** Request the associated graphic device for this canvas.<p>
722
723        A graphic device provides methods specific to the underlying
724        output device capabilities, which are common for all canvases
725        rendering to such a device. This includes device resolution,
726        color space, or bitmap formats.
727
728        @return the associated <type>XGraphicDevice</type>.
729     */
730    XGraphicDevice			getDevice();
731};
732
733//=============================================================================
734
735/// Service providing an <type>XCanvas</type> interface
736service Canvas: XCanvas;
737
738}; }; }; };
739
740#endif
741