summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/rendering/XCanvas.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--offapi/com/sun/star/rendering/XCanvas.idl666
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: */