Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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: */