diff options
Diffstat (limited to 'offapi/com/sun/star/rendering/XCanvas.idl')
| -rw-r--r-- | offapi/com/sun/star/rendering/XCanvas.idl | 666 |
1 files changed, 666 insertions, 0 deletions
diff --git a/offapi/com/sun/star/rendering/XCanvas.idl b/offapi/com/sun/star/rendering/XCanvas.idl new file mode 100644 index 000000000..e393854b7 --- /dev/null +++ b/offapi/com/sun/star/rendering/XCanvas.idl @@ -0,0 +1,666 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ +#ifndef __com_sun_star_rendering_XCanvas_idl__ +#define __com_sun_star_rendering_XCanvas_idl__ + +#include <com/sun/star/uno/XInterface.idl> +#include <com/sun/star/lang/IllegalArgumentException.idl> +#include <com/sun/star/geometry/RealPoint2D.idl> +#include <com/sun/star/geometry/RealBezierSegment2D.idl> +#include <com/sun/star/geometry/RealRectangle2D.idl> +#include <com/sun/star/geometry/Matrix2D.idl> +#include <com/sun/star/rendering/ViewState.idl> +#include <com/sun/star/rendering/RenderState.idl> +#include <com/sun/star/rendering/FontRequest.idl> +#include <com/sun/star/rendering/FontInfo.idl> +#include <com/sun/star/rendering/Texture.idl> +#include <com/sun/star/rendering/StringContext.idl> +#include <com/sun/star/rendering/StrokeAttributes.idl> +#include <com/sun/star/rendering/VolatileContentDestroyedException.idl> +#include <com/sun/star/beans/PropertyValue.idl> + + +module com { module sun { module star { module geometry { + interface XMapping2D; +}; }; }; }; + +module com { module sun { module star { module rendering { + +interface XCanvasFont; +interface XPolyPolygon2D; +interface XCachedPrimitive; +interface XBitmap; +interface XGraphicDevice; +interface XTextLayout; + +/** Central interface for rendering.<p> + + This is the central interface for graphical output production, and + the place where all draw methods are located.<p> + + Some notes are in order to explain the concepts used here. The + XCanvas interface is free of client-modifiable state, + i.e. it can be used safely and without external synchronization in + a multi-threaded environment. On the other hand, this implies that + for nearly every canvas operation, external state is + required. This is provided by ViewState and + RenderState in a unified fashion, supplemented by a + few extra state parameters for some methods (e.g. textured + polygons or text rendering).<p> + + When used careless, this scheme can be inefficient to some extend, + because internally, view, render and other states have to be + combined before rendering. This is especially expensive for + complex clip polygons, i.e. when both ViewState and + RenderState have a complex clip polygon set, which + have to be intersected before rendering. It is therefore + recommended to combine ViewState and + RenderState already at the client side, when objects + are organized in a hierarchical way: the classic example are + grouped draw shapes, whose parent group object imposes a + common clipping and a common transformation on its siblings. The + group object would therefore merge the ViewState and + the RenderState it is called with into a new + ViewState, and call its siblings with a + RenderState containing only the local offset (and no + extra clipping).<p> + + Further on, this stateless nature provides easy ways for + caching. Every non-trivial operation on XCanvas can + return a cache object, which, when called to redraw, renders the + primitive usually much more quickly than the original method. Note + that such caching is a lot more complicated, should the actual + rendering a method yields depend on internal state (which is the + case e.g. for the + ::com::sun::star::awt::XGraphics + interface). Please note, though, that deciding whether to return + an XCachedPrimitive is completely up to the + implementation - don't rely on the methods returning something + (this is because there might be cases when returning such a cache + object will actually be a pessimization, since it involves memory + allocation and comparisons).<p> + + Things that need more than a small, fixed amount of data are + encapsulated in own interfaces, e.g. polygons and bitmaps. You + can, in principle, roll your own implementations of these + interfaces, wrap it around your internal representation of + polygons and bitmaps, and render them. It might just not be overly + fast, because the XCanvas would need to convert for + each render call. It is therefore recommended to create such + objects via the XGraphicDevice factory (to be + retrieved from every canvas object via the + getDevice() call) - they will then internally + optimize to the underlying graphics subsystem.<p> + + @since OOo 2.0 + */ +interface XCanvas : ::com::sun::star::uno::XInterface +{ + /** Clear the whole canvas area.<p> + + This method clears the whole canvas area to the device default + color (e.g. white for a printer, transparent for an + XCustomSprite). + */ + void clear(); + + /** Draw a point in device resolution on the device. + + @param aPoint + The point to draw. + + @param aViewState + The view state to be used when drawing this point. + + @param aRenderState + The render state to be used when drawing this point. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + void drawPoint( [in] ::com::sun::star::geometry::RealPoint2D aPoint, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Draw a line in device resolution width (i.e. one device pixel + wide). + + @param aStartPoint + The start point of the line to draw. + + @param aEndPoint + The end point of the line to draw. + + @param aViewState + The view state to be used when drawing this line. + + @param aRenderState + The render state to be used when drawing this line. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + void drawLine( [in] ::com::sun::star::geometry::RealPoint2D aStartPoint, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Draw a cubic Bezier curve in device resolution width (i.e. one + device pixel wide). + + @param aBezierSegment + The start and the two control points of the Bezier curve. + + @param aEndPoint + The end point of the Bezier curve. + + @param aViewState + The view state to be used when drawing this curve. + + @param aRenderState + The render state to be used when drawing this curve. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + void drawBezier( [in] ::com::sun::star::geometry::RealBezierSegment2D aBezierSegment, [in] ::com::sun::star::geometry::RealPoint2D aEndPoint, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Draw a poly-polygon in device resolution line width (i.e. the + lines are one device pixel wide). + + @param xPolyPolygon + The poly-polygon to draw. + + @param aViewState + The view state to be used when drawing this polygon. + + @param aRenderState + The render state to be used when drawing this polygon. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XCachedPrimitive drawPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Stroke each polygon of the provided poly-polygon with the + specified stroke attributes.<p> + + This method considers the stroking of all polygons as an + atomic operation in relation to the RenderState's + CompositeOperationy operation. That means, + overlapping strokes from distinct polygons will look exactly + as overlapping segments of the same polygon, even with + transparency.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when stroking this polygon. + + @param aRenderState + The render state to be used when stroking this polygon. + + @param aStrokeAttributes + Further attributes used to parameterize the stroking. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XCachedPrimitive strokePolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Stroke each polygon of the provided poly-polygon with the + specified stroke attributes, fill the stroked outline + with the specified texture graphics.<p> + + This method considers the stroking of all polygons as an + atomic operation in relation to the RenderState's + CompositeOp operation. That means, overlapping + strokes from distinct polygons will look exactly as + overlapping segments of the same polygon, even with + transparency.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when strokes this polygon. + + @param aRenderState + The render state to be used when stroking this polygon. + + @param aTextures + A sequence of texture definitions, with which to fill the + stroked area. + + @param aStrokeAttributes + Further attributes used to parameterize the stroking. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + XCachedPrimitive strokeTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> aTextures, [in] StrokeAttributes aStrokeAttributes ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + + /** Stroke each polygon of the provided poly-polygon with the + specified stroke attributes, fill the stroked outline + with the specified texture graphics, map the texture to the + outline via the specified texture mapping.<p> + + This method considers the stroking of all polygons as an + atomic operation in relation to the RenderState's + CompositeOp operation. That means, overlapping + strokes from distinct polygons will look exactly as + overlapping segments of the same polygon, even with + transparency. + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when stroking this polygon. + + @param aRenderState + The render state to be used when stroking this polygon. + + @param aTextures + A sequence of texture definitions, with which to fill the + stroked area. + + @param xMapping + A bilinear mapping function which defines the warping of the + textures on the output area. + + @param aStrokeAttributes + Further attributes used to parameterize the stroking. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + 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 ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + + // [TODO: Method misplaced at this interface?] + + /** Query the polygonal representation of the stroke outlines, as + it would be generated by the strokePolyPolygon methods.<p> + + This method can be used to e.g. set a clipping which covers the same + area as a stroke.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when generating the outline. + + @param aRenderState + The render state to be used when generating the outline. + + @param aStrokeAttributes + Further attributes used to parameterize the stroking. + + @return a poly-polygon describing the outline of the stroked + area. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XPolyPolygon2D queryStrokeShapes( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] StrokeAttributes aStrokeAttributes ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Fill the given poly-polygon.<p> + + This method fills the given poly-polygon according to the + RenderState's color and the poly-polygon's fill + rule.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when filling this polygon. + + @param aRenderState + The render state to be used when filling this polygon. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XCachedPrimitive fillPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Fill the given poly-polygon with a texture.<p> + + This method fills the given poly-polygon according to the + RenderState's color, the given textures and + poly-polygon's fill rule.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when filling this polygon. + + @param aRenderState + The render state to be used when filling this polygon. + + @param xTextures + A sequence of texture definitions, with which to fill the + polygonal area. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + XCachedPrimitive fillTexturedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + + /** Fill the given poly-polygon with a mapped texture.<p> + + This method fills the given poly-polygon according to the + RenderState's color, the given textures and + poly-polygon's fill rule. The texture is mapped to the + poly-polygon's interior via the given texture mapping.<p> + + @param xPolyPolygon + The poly-polygon to render. + + @param aViewState + The view state to be used when filling this polygon. + + @param aRenderState + The render state to be used when filling this polygon. + + @param xTextures + A sequence of texture definitions, with which to fill the + polygonal area. + + @param xMapping + A bilinear mapping function which defines the warping of the + textures on the output area. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + XCachedPrimitive fillTextureMappedPolyPolygon( [in] XPolyPolygon2D xPolyPolygon, [in] ViewState aViewState, [in] RenderState aRenderState, [in] sequence<Texture> xTextures, [in] ::com::sun::star::geometry::XMapping2D xMapping ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + + /** Create a suitable font for the specified font description. + + @param aFontRequest + + @param aExtraFontProperties + Additional font properties to be applied when selecting this + font. Normally, you should not need this parameter. Currently, + the following property is recognized: + + - EmphasisMark: long integer that represents the emphasis mark. + @see ::com::sun::star::awt::FontEmphasisMark + + @param aFontMatrix + Font-specific transformation matrix, which affects both the + glyphs as well as the advancement. + + @returns the requested font, or an invalid reference, if the + request failed. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the parameters is not within the allowed range. + */ + XCanvasFont createFont( [in] FontRequest aFontRequest, [in] sequence< ::com::sun::star::beans::PropertyValue > aExtraFontProperties, [in] ::com::sun::star::geometry::Matrix2D aFontMatrix ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Query font information, specific to this canvas.<p> + + @param aFilter + Filter parameter to reduce the list of returned fonts. Every + member of FontInfo that is not the empty string + or the "don't care" value restricts the list of returned fonts + to contain only those that have the specified attribute. + + @param aFontProperties + This interface can provide additional font properties to + filter the list of available fonts against. + + @returns the list of fonts matching the filter set. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the font properties are invalid or not recognized, + or if one of the FontInfo members is not within + the permitted range. + */ + sequence< FontInfo > queryAvailableFonts( [in] FontInfo aFilter, [in] sequence< ::com::sun::star::beans::PropertyValue > aFontProperties ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Draw the text given by the substring of the specified string + with the given font.<p> + + The local origin of this output operation is either the left + end of the text baseline, for textDirection equal + LEFT_TO_RIGHT, or the right end of the baseline, for + textDirection equal to RIGHT_TO_LEFT, respectively.<p> + + @param aText + The text to output. + + @param xFont + The font retrieved from this canvas to be used when drawing + the text. + + @param aViewState + The view state to be used when drawing this text. + + @param aRenderState + The render state to be used when drawing this text. + + @param nTextDirection + A value from the TextDirection collection, + denoting the main writing direction for this string. The main + writing direction determines the origin of the text output, + i.e. the left edge for left-to-right and the right edge for + right-to-left text. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XCachedPrimitive drawText( [in] StringContext aText, [in] XCanvasFont xFont, [in] ViewState aViewState, [in] RenderState aRenderState, [in] byte nTextDirection ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Draw the formatted text given by the text layout.<p> + + The glyphs as represented by the text layout are always output + with the reference position being the leftmost edge of the + layout object's baseline. If the layout contains more than one + baseline, the baseline of the first strong character in + logical order is used here (strong in this context means that + the character can be unambiguously assigned to a Unicode + script).<p> + + @param xLayoutetText + An interface to the readily layouted text, obtained from a + XCanvasFont created at this canvas. The text + layout already carries intrinsic font information. + + @param aViewState + The view state to be used when drawing this text. + + @param aRenderState + The render state to be used when drawing this text. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + */ + XCachedPrimitive drawTextLayout( [in] XTextLayout xLayoutetText, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException); + + + /** Render the given bitmap.<p> + + This method renders the bitmap, at a position and shape as + specified by the combined view and render transformations. For + fast render speed, the bitmap should be created by the + corresponding XGraphicDevice's + XGraphicDevice::createCompatibleBitmap() + method.<p> + + @param xBitmap + The bitmap to render. + + @param aViewState + The view state to be used when drawing this text. + + @param aRenderState + The render state to be used when drawing this text. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + XCachedPrimitive drawBitmap( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + /** Render the given bitmap, with a global color modulation.<p> + + This method renders the bitmap, at a position and shape as + specified by the combined view and render transformations. For + fast render speed, the bitmap should be created by the + corresponding XGraphicDevice's + XGraphicDevice::createCompatibleBitmap() + method. The bitmap's color channel values are multiplied with + the device color values as specified in the render state.<p> + + @param xBitmap + The bitmap to render. + + @param aViewState + The view state to be used when drawing this text. + + @param aRenderState + The render state to be used when drawing this text. The device + color entry in the render state is multiplied with every pixel + color value, and only the result is rendered into the + canvas. If, for example, the bitmap should be rendered with + increased global transparency, set all device color channels + to 1.0, except for the alpha channel, which should be set to + the desired transparency. + + @return a handle to the cached rendering output. + + @throws com::sun::star::lang::IllegalArgumentException + if one of the view and render state parameters are outside the + specified range. + + @throws VolatileContentDestroyedException + if a texture bitmap was volatile, and the content was + destroyed before the rendering could take place. + */ + XCachedPrimitive drawBitmapModulated( [in] XBitmap xBitmap, [in] ViewState aViewState, [in] RenderState aRenderState ) + raises (com::sun::star::lang::IllegalArgumentException, + VolatileContentDestroyedException); + + + /** Request the associated graphic device for this canvas.<p> + + A graphic device provides methods specific to the underlying + output device capabilities, which are common for all canvases + rendering to such a device. This includes device resolution, + color space, or bitmap formats. + + @return the associated XGraphicDevice. + */ + XGraphicDevice getDevice(); +}; + +}; }; }; }; + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |