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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2000, 2010 Oracle and/or its affiliates.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * This file is part of OpenOffice.org.
  10  *
  11  * OpenOffice.org is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU Lesser General Public License version 3
  13  * only, as published by the Free Software Foundation.
  14  *
  15  * OpenOffice.org is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU Lesser General Public License version 3 for more details
  19  * (a copy is included in the LICENSE file that accompanied this code).
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * version 3 along with OpenOffice.org.  If not, see
  23  * <http://www.openoffice.org/license.html>
  24  * for a copy of the LGPLv3 License.
  25  *
  26  ************************************************************************/
  27 #ifndef __com_sun_star_rendering_XGraphicDevice_idl__
  28 #define __com_sun_star_rendering_XGraphicDevice_idl__
  29
  30 #ifndef __com_sun_star_uno_XInterface_idl__
  31 #include <com/sun/star/uno/XInterface.idl>
  32 #endif
  33 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  34 #include <com/sun/star/lang/IllegalArgumentException.idl>
  35 #endif
  36 #ifndef __com_sun_star_geometry_IntegerSize2D_idl__
  37 #include <com/sun/star/geometry/IntegerSize2D.idl>
  38 #endif
  39 #ifndef __com_sun_star_geometry_RealSize2D_idl__
  40 #include <com/sun/star/geometry/RealSize2D.idl>
  41 #endif
  42 #ifndef __com_sun_star_rendering_XLinePolyPolygon2D_idl__
  43 #include <com/sun/star/rendering/XLinePolyPolygon2D.idl>
  44 #endif
  45 #ifndef __com_sun_star_rendering_XBezierPolyPolygon2D_idl__
  46 #include <com/sun/star/rendering/XBezierPolyPolygon2D.idl>
  47 #endif
  48 #ifndef __com_sun_star_rendering_XColorSpace_idl__
  49 #include <com/sun/star/rendering/XColorSpace.idl>
  50 #endif
  51 #ifndef __com_sun_star_lang_XMultiServiceFactory_idl__
  52 #include <com/sun/star/lang/XMultiServiceFactory.idl>
  53 #endif
  54
  55 module com { module sun { module star { module rendering {
  56
  57 interface XBitmap;
  58 interface XVolatileBitmap;
  59 interface XBufferController;
  60
  61 /* TODO: There's obviously a concept called window missing here, where
  62    methods such as bufferController, fullscreen mode etc . belong
  63    to. But see below
  64  */
  65
  66 /** This interface provides access to a graphic device, such as a
  67     printer, or a screen device. Every canvas (@see XCanvas) has
  68     exactly one associated graphic device, into which its output is
  69     rendered.
  70
  71     For a typical windowing system, the graphic device is equivalent
  72     to a distinct OS window, with it's own clipped output area,
  73     fullscreen and double-buffering attributes. That is, even if one
  74     can have multiple canvases per system window, they all share the
  75     same graphic device and thus e.g. fullscreen state. If the OS
  76     restrictions are in such a way that fullscreen or double-buffering
  77     is screen-exclusive, i.e. that per screen, only one object can
  78     have this state, it might even be that all windows on the screen
  79     share a common graphic device.
  80  */
  81 interface XGraphicDevice : ::com::sun::star::uno::XInterface
  82 {
  83     /** Query the controller for multi buffering functionality on this
  84         graphic device.
  85
  86         If there is no such functionality available, the NULL
  87         reference is returned.
  88      */
  89     XBufferController                           getBufferController();
  90
  91     //-------------------------------------------------------------------------
  92
  93     /** Query the color space interface for this graphic device.
  94
  95         This is to be used when interpreting or setting device color
  96         values.
  97      */
  98     XColorSpace                                 getDeviceColorSpace();
  99
 100     //-------------------------------------------------------------------------
 101
 102     /** Query the physical resolution of the device in pixel per
 103         millimeter.
 104
 105         A special floating point value of +infinity here indicates
 106         'unknown', i.e. at the time of rendering undetermined or
 107         possibly infinite resolution along the corresponding
 108         direction.
 109      */
 110     ::com::sun::star::geometry::RealSize2D  getPhysicalResolution();
 111
 112     //-------------------------------------------------------------------------
 113
 114     /** Query the physical dimensions of the device in millimeter.
 115
 116         A special floating point value of +infinity here indicates
 117         'unknown', i.e. at the time of rendering undetermined or
 118         possibly infinite resolution along the corresponding
 119         direction.
 120
 121         @see XBitmap::getSize()
 122      */
 123     ::com::sun::star::geometry::RealSize2D  getPhysicalSize();
 124
 125     //-------------------------------------------------------------------------
 126
 127     /** Create a line poly-polygon which can internally use
 128         device-optimized representations already.
 129
 130         @param points
 131         The points of the poly-polygon, in a separate array for every polygon.
 132      */
 133     XLinePolyPolygon2D              createCompatibleLinePolyPolygon( [in] sequence< sequence< ::com::sun::star::geometry::RealPoint2D > > points );
 134
 135     //-------------------------------------------------------------------------
 136
 137     /** Create a bezier poly-polygon which can internally use
 138         device-optimized representations already.
 139
 140         @param points
 141         The points of the poly-polygon, in a separate array for every polygon.
 142      */
 143     XBezierPolyPolygon2D            createCompatibleBezierPolyPolygon( [in] sequence< sequence< ::com::sun::star::geometry::RealBezierSegment2D > > points );
 144
 145     //-------------------------------------------------------------------------
 146
 147     /** Create a bitmap whose memory layout and sample model is
 148         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                         createCompatibleBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 155         raises (com::sun::star::lang::IllegalArgumentException);
 156
 157     //-------------------------------------------------------------------------
 158
 159     /** Create a volatile bitmap that is usable 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         <type>VolatileContentDestroyedException</type>). 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                 createVolatileBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 175         raises (com::sun::star::lang::IllegalArgumentException);
 176
 177     //-------------------------------------------------------------------------
 178
 179     /** Create a bitmap with alpha channel whose memory layout and
 180         sample model is compatible to the graphic device.
 181
 182         @param size
 183         Size of the requested bitmap in pixel. Both components of the
 184         size must be greater than 0
 185      */
 186     XBitmap                         createCompatibleAlphaBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 187         raises (com::sun::star::lang::IllegalArgumentException);
 188
 189     //-------------------------------------------------------------------------
 190
 191     /** Create a volatile bitmap with alpha channel that is usable
 192         with this graphic device.
 193
 194         A volatile bitmap's difference in comparison to a plain bitmap
 195         (e.g. generated via createCompatibleBitmap()) is the fact that
 196         its content might vanish at any point in time (making any
 197         operation with them produce a
 198         <type>VolatileContentDestroyedException</type>). The benefit,
 199         on the other hand, is that they might be easy to
 200         hardware-accelerate on certain platforms, without the need to
 201         keep a safety copy of the content internally.
 202
 203         @param size
 204         Size of the requested bitmap in pixel. Both components of the
 205         size must be greater than 0
 206      */
 207     XVolatileBitmap                 createVolatileAlphaBitmap( [in] ::com::sun::star::geometry::IntegerSize2D size )
 208         raises (com::sun::star::lang::IllegalArgumentException);
 209
 210     //-------------------------------------------------------------------------
 211
 212     /** Get a reference to this device's parametric polygon factory.
 213
 214         @return a reference to this device's parametric polygon
 215         factory. Although it is possible to use parametric polygons on
 216         all canvases, regardless of the associated graphic device,
 217         this is not advisable: each canvas implementation is free to
 218         internally generate optimized parametric polygons, which can
 219         be used more directly for e.g. texturing operations.
 220
 221         <pre>
 222         Available services (all canvas implementations should provide
 223         this minimal set, though are free to add more; just check the
 224         getAvailableServiceNames() on the returned interface):
 225
 226         - Gradients - all gradients need to support two construction
 227           parameters, "Colors" being a <type>sequence<Color></type>
 228           and "Stops" being a <type>sequence<double></type>. Both must
 229           have the same length, and at least two elements. See
 230           http://www.w3.org/TR/SVG11/pservers.html#GradientStops for
 231           the semantics of gradient stops and colors.
 232           Required gradient services:
 233
 234           * "LinearGradient" - the gradient varies linearly between
 235             the given colors. without coordinate system
 236             transformation, the color interpolation happens in
 237             increasing x direction, and is constant in y
 238             direction. Equivalent to svg linear gradient
 239             http://www.w3.org/TR/SVG11/pservers.html#LinearGradients
 240
 241           * "EllipticalGradient" - this gradient has zeroth color
 242             index in the middle, and varies linearly between center
 243             and final color. The services takes an additional
 244             parameter named "AspectRatio" of <type>double</type>
 245             (width divided by height), if this aspect ratio is 1, the
 246             gradient is circular. If it's not 1, the gradient is
 247             elliptical, with the special twist that the aspect ratio
 248             is maintained also for the center color: the gradient will
 249             not collapse into a single point, but become a line of
 250             center color. If "AspectRatio" is missing, or equal to 1,
 251             this gradient yields similar results as the svg radial
 252             gradient
 253             http://www.w3.org/TR/SVG11/pservers.html#RadialGradients
 254
 255           * "RectangularGradient" - this gradient has zeroth color
 256             index in the middle, and varies linearly between center
 257             and final color via rectangular boxes
 258             around the center point. The services takes an additional
 259             parameter named "AspectRatio" of <type>double</type>
 260             (width divided by height), if this aspect ratio is 1, the
 261             gradient is quadratic. If it's not 1, the gradient is
 262             rectangular, with the special twist that the aspect ratio
 263             is maintained also for the center color: the gradient will
 264             not collapse into a single point, but become a line of
 265             center color.
 266
 267         - Hatch patterns - Required hatch services:
 268
 269           * "VerticalLineHatch" - this hatching consists of vertical lines
 270           * "OrthogonalLinesHatch" - this hatching consists of
 271             crossing vertical and horizontal lines
 272           * "ThreeCrossingLinesHatch" - this hatching consists of
 273             vertical and horizontal lines plus diagonal lines from
 274             left, top to bottom, right.
 275           * "FourCrossingLinesHatch" - this hatching consists of
 276             vertical and horizontal lines plus diagonal lines in both
 277             directions.
 278         </pre>
 279      */
 280     com::sun::star::lang::XMultiServiceFactory getParametricPolyPolygonFactory();
 281
 282     //-------------------------------------------------------------------------
 283
 284     /** Tells whether this graphic device has a full screen mode,
 285         i.e. whether a window can cover the whole screen exclusively.
 286      */
 287     boolean                         hasFullScreenMode();
 288
 289     //-------------------------------------------------------------------------
 290
 291     /** Enter or leave the fullscreen mode, if possible. The return
 292         value denotes the success of the operation.
 293
 294         @attention depending on the underlying operating system,
 295         fullscreen mode can be left without a enterFullScreenMode(
 296         false ) call.
 297      */
 298     boolean                         enterFullScreenMode( [in] boolean bEnter );
 299 };
 300
 301 }; }; }; };
 302
 303 #endif