offapi/com/sun/star/rendering/XGraphicDevice.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_rendering_XGraphicDevice_idl__
  20 #define __com_sun_star_rendering_XGraphicDevice_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/lang/IllegalArgumentException.idl>
  24 #include <com/sun/star/geometry/IntegerSize2D.idl>
  25 #include <com/sun/star/geometry/RealSize2D.idl>
  26 #include <com/sun/star/rendering/XLinePolyPolygon2D.idl>
  27 #include <com/sun/star/rendering/XBezierPolyPolygon2D.idl>
  28 #include <com/sun/star/rendering/XColorSpace.idl>
  29 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  30
  31 module com { module sun { module star { module rendering {
  32
  33 interface XBitmap;
  34 interface XVolatileBitmap;
  35 interface XBufferController;
  36
  37 /* TODO: There's obviously a concept called window missing here, where
  38    methods such as bufferController, fullscreen mode etc . belong
  39    to. But see below
  40  */
  41
  42 /** This interface provides access to a graphic device, such as a
  43     printer, or a screen device. Every canvas (@see XCanvas) has
  44     exactly one associated graphic device, into which its output is
  45     rendered.
  46
  47     For a typical windowing system, the graphic device is equivalent
  48     to a distinct OS window, with its own clipped output area,
  49     fullscreen and double-buffering attributes. That is, even if one
  50     can have multiple canvases per system window, they all share the
  51     same graphic device and thus e.g. fullscreen state. If the OS
  52     restrictions are in such a way that fullscreen or double-buffering
  53     is screen-exclusive, i.e. that per screen, only one object can
  54     have this state, it might even be that all windows on the screen
  55     share a common graphic device.
  56  */
  57 interface XGraphicDevice : ::com::sun::star::uno::XInterface
  58 {
  59     /** Query the controller for multi buffering functionality on this
  60         graphic device.
  61
  62         If there is no such functionality available, the NULL
  63         reference is returned.
  64      */
  65     XBufferController                           getBufferController();
  66
  67
  68     /** Query the color space interface for this graphic device.
  69
  70         This is to be used when interpreting or setting device color
  71         values.
  72      */
  73     XColorSpace                                 getDeviceColorSpace();
  74
  75
  76     /** Query the physical resolution of the device in pixel per
  77         millimeter.
  78
  79         A special floating point value of +infinity here indicates
  80         "unknown", i.e. at the time of rendering undetermined or
  81         possibly infinite resolution along the corresponding
  82         direction.
  83      */
  84     ::com::sun::star::geometry::RealSize2D  getPhysicalResolution();
  85
  86
  87     /** Query the physical dimensions of the device in millimeter.
  88
  89         A special floating point value of +infinity here indicates
  90         "unknown", i.e. at the time of rendering undetermined or
  91         possibly infinite resolution along the corresponding
  92         direction.
  93
  94         @see XBitmap::getSize()
  95      */
  96     ::com::sun::star::geometry::RealSize2D  getPhysicalSize();
  97
  98
  99     /** Create a line poly-polygon which can internally use
 100         device-optimized representations already.
 101
 102         @param points
 103         The points of the poly-polygon, in a separate array for every polygon.
 104      */
 105     XLinePolyPolygon2D              createCompatibleLinePolyPolygon( [in] sequence< sequence< ::com::sun::star::geometry::RealPoint2D > > points );
 106
 107
 108     /** Create a Bezier poly-polygon which can internally use
 109         device-optimized representations already.
 110
 111         @param points
 112         The points of the poly-polygon, in a separate array for every polygon.
 113      */
 114     XBezierPolyPolygon2D            createCompatibleBezierPolyPolygon( [in] sequence< sequence< ::com::sun::star::geometry::RealBezierSegment2D > > points );
 115
 116
 117     /** Create a bitmap whose memory layout and sample model is
 118         compatible to the graphic device.
 119
 120         @param size
 121         Size of the requested bitmap in pixel. Both components of the
 122         size must be greater than 0
 123      */
 124     XBitmap                         createCompatibleBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 125         raises (com::sun::star::lang::IllegalArgumentException);
 126
 127
 128     /** Create a volatile bitmap that is usable with this graphic device.
 129
 130         A volatile bitmap's difference in comparison to a plain bitmap
 131         (e.g. generated via createCompatibleBitmap()) is the fact that
 132         its content might vanish at any point in time (making any
 133         operation with them produce a
 134         VolatileContentDestroyedException). The benefit,
 135         on the other hand, is that they might be easy to
 136         hardware-accelerate on certain platforms, without the need to
 137         keep a safety copy of the content internally.
 138
 139         @param size
 140         Size of the requested bitmap in pixel. Both components of the
 141         size must be greater than 0
 142      */
 143     XVolatileBitmap                 createVolatileBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 144         raises (com::sun::star::lang::IllegalArgumentException);
 145
 146
 147     /** Create a bitmap with alpha channel whose memory layout and
 148         sample model is compatible to the graphic device.
 149
 150         @param size
 151         Size of the requested bitmap in pixel. Both components of the
 152         size must be greater than 0
 153      */
 154     XBitmap                         createCompatibleAlphaBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 155         raises (com::sun::star::lang::IllegalArgumentException);
 156
 157
 158     /** Create a volatile bitmap with alpha channel that is usable
 159         with this graphic device.
 160
 161         A volatile bitmap's difference in comparison to a plain bitmap
 162         (e.g. generated via createCompatibleBitmap()) is the fact that
 163         its content might vanish at any point in time (making any
 164         operation with them produce a
 165         VolatileContentDestroyedException). The benefit,
 166         on the other hand, is that they might be easy to
 167         hardware-accelerate on certain platforms, without the need to
 168         keep a safety copy of the content internally.
 169
 170         @param size
 171         Size of the requested bitmap in pixel. Both components of the
 172         size must be greater than 0
 173      */
 174     XVolatileBitmap                 createVolatileAlphaBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 175         raises (com::sun::star::lang::IllegalArgumentException);
 176
 177
 178     /** Get a reference to this device's parametric polygon factory.
 179
 180         @return a reference to this device's parametric polygon
 181         factory. Although it is possible to use parametric polygons on
 182         all canvases, regardless of the associated graphic device,
 183         this is not advisable: each canvas implementation is free to
 184         internally generate optimized parametric polygons, which can
 185         be used more directly for e.g. texturing operations.
 186
 187         Available services (all canvas implementations should provide
 188         this minimal set, though are free to add more; just check the
 189         getAvailableServiceNames() on the returned interface):
 190
 191         - Gradients - all gradients need to support two construction
 192           parameters, "Colors" being a `sequence&lt; Color &gt;`
 193           and "Stops" being a `sequence&lt; double &gt;`. Both must
 194           have the same length, and at least two elements. See
 195           http://www.w3.org/TR/SVG11/pservers.html#GradientStops for
 196           the semantics of gradient stops and colors.
 197           Required gradient services:
 198
 199           - "LinearGradient" - the gradient varies linearly between
 200             the given colors. without coordinate system
 201             transformation, the color interpolation happens in
 202             increasing x direction, and is constant in y
 203             direction. Equivalent to svg linear gradient
 204             http://www.w3.org/TR/SVG11/pservers.html#LinearGradients
 205
 206           - "EllipticalGradient" - this gradient has zeroth color
 207             index in the middle, and varies linearly between center
 208             and final color. The services takes an additional
 209             parameter named "AspectRatio" of double
 210             (width divided by height), if this aspect ratio is 1, the
 211             gradient is circular. If it's not 1, the gradient is
 212             elliptical, with the special twist that the aspect ratio
 213             is maintained also for the center color: the gradient will
 214             not collapse into a single point, but become a line of
 215             center color. If "AspectRatio" is missing, or equal to 1,
 216             this gradient yields similar results as the svg radial
 217             gradient
 218             http://www.w3.org/TR/SVG11/pservers.html#RadialGradients
 219
 220           - "RectangularGradient" - this gradient has zeroth color
 221             index in the middle, and varies linearly between center
 222             and final color via rectangular boxes
 223             around the center point. The services takes an additional
 224             parameter named "AspectRatio" of double
 225             (width divided by height), if this aspect ratio is 1, the
 226             gradient is quadratic. If it's not 1, the gradient is
 227             rectangular, with the special twist that the aspect ratio
 228             is maintained also for the center color: the gradient will
 229             not collapse into a single point, but become a line of
 230             center color.
 231
 232         - Hatch patterns - Required hatch services:
 233
 234           - "VerticalLineHatch" - this hatching consists of vertical lines
 235           - "OrthogonalLinesHatch" - this hatching consists of
 236             crossing vertical and horizontal lines
 237           - "ThreeCrossingLinesHatch" - this hatching consists of
 238             vertical and horizontal lines plus diagonal lines from
 239             left, top to bottom, right.
 240           - "FourCrossingLinesHatch" - this hatching consists of
 241             vertical and horizontal lines plus diagonal lines in both
 242             directions.
 243      */
 244     com::sun::star::lang::XMultiServiceFactory getParametricPolyPolygonFactory();
 245
 246
 247     /** Tells whether this graphic device has a full screen mode,
 248         i.e. whether a window can cover the whole screen exclusively.
 249      */
 250     boolean                         hasFullScreenMode();
 251
 252
 253     /** Enter or leave the fullscreen mode, if possible. The return
 254         value denotes the success of the operation.
 255
 256         @attention depending on the underlying operating system,
 257         fullscreen mode can be left without a enterFullScreenMode(
 258         false ) call.
 259      */
 260     boolean                         enterFullScreenMode( [in] boolean bEnter );
 261 };
 262
 263 }; }; }; };
 264
 265 #endif
 266
 267 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */