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

   1 /*************************************************************************
   2  *
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * Copyright 2008 by Sun Microsystems, Inc.
   6  *
   7  * OpenOffice.org - a multi-platform office productivity suite
   8  *
   9  * $RCSfile: XIntegerReadOnlyBitmap.idl,v $
  10  * $Revision: 1.3 $
  11  *
  12  * This file is part of OpenOffice.org.
  13  *
  14  * OpenOffice.org is free software: you can redistribute it and/or modify
  15  * it under the terms of the GNU Lesser General Public License version 3
  16  * only, as published by the Free Software Foundation.
  17  *
  18  * OpenOffice.org is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  21  * GNU Lesser General Public License version 3 for more details
  22  * (a copy is included in the LICENSE file that accompanied this code).
  23  *
  24  * You should have received a copy of the GNU Lesser General Public License
  25  * version 3 along with OpenOffice.org.  If not, see
  26  * <http://www.openoffice.org/license.html>
  27  * for a copy of the LGPLv3 License.
  28  *
  29  ************************************************************************/
  30 #ifndef __com_sun_star_rendering_XIntegerReadOnlyBitmap_idl__
  31 #define __com_sun_star_rendering_XIntegerReadOnlyBitmap_idl__
  32
  33 #ifndef __com_sun_star_lang_IllegalArgumentException_idl__
  34 #include <com/sun/star/lang/IllegalArgumentException.idl>
  35 #endif
  36 #ifndef __com_sun_star_lang_IndexOutOfBoundsException_idl__
  37 #include <com/sun/star/lang/IndexOutOfBoundsException.idl>
  38 #endif
  39 #ifndef __com_sun_star_geometry_IntegerPoint2D_idl__
  40 #include <com/sun/star/geometry/IntegerPoint2D.idl>
  41 #endif
  42 #ifndef __com_sun_star_geometry_IntegerRectangle2D_idl__
  43 #include <com/sun/star/geometry/IntegerRectangle2D.idl>
  44 #endif
  45 #ifndef __com_sun_star_rendering_IntegerBitmapLayout_idl__
  46 #include <com/sun/star/rendering/IntegerBitmapLayout.idl>
  47 #endif
  48 #ifndef __com_sun_star_rendering_XBitmap_idl__
  49 #include <com/sun/star/rendering/XBitmap.idl>
  50 #endif
  51 #ifndef __com_sun_star_rendering_VolatileContentDestroyedException_idl__
  52 #include <com/sun/star/rendering/VolatileContentDestroyedException.idl>
  53 #endif
  54
  55
  56 module com { module sun { module star { module rendering {
  57
  58 interface XBitmapPalette;
  59
  60 /** This is a specialized interface for bitmaps having integer color
  61     channels. In contrast to <type>XIntegerBitmap</type>, this
  62     interface only permits read-only access.<p>
  63
  64     Use this interface for e.g. bitmaps that are calculated
  65     on-the-fly, or that are pure functional, and thus cannot be
  66     modified.<p>
  67
  68     If you get passed an instance of
  69     <type>XIntegerReadOnlyBitmap</type> that also supports the
  70     <type>XVolatileBitmap</type> interface, things become a bit more
  71     complicated. When reading data, one has to check for both
  72     <type>VolatileContentDestroyedException</type> and mismatching
  73     <type>IntegerBitmapLayout</type> return values. If either of them
  74     occurs, the whole bitmap read operation should be repeated, if you
  75     need consistent information.<p>
  76  */
  77 interface XIntegerReadOnlyBitmap : XBitmap
  78 {
  79     /** Query the raw data of this bitmap.<p>
  80
  81         Query the raw data of this bitmap, in the format as defined by
  82         getMemoryLayout(). With the given rectangle, a subset of the
  83         whole bitmap can be queried. If the internal data format's
  84         pixel are not integer multiples of bytes (i.e. if one pixel
  85         occupies less than a byte), the leftover content of the bytes
  86         at the right of each scanline is filled with zeros. The
  87         details of the scanline padding are to be retrieved from the
  88         passed bitmap layout.<p>
  89
  90         Note that the bitmap memory layout might change over time for
  91         volatile bitmaps.<p>
  92
  93         @param bitmapLayout
  94         The memory layout the returned data is in. Note that the color
  95         space returned therein needs to always match the current color
  96         space as would have been returned by getMemoryLayout(). This
  97         is necessary to ensure correct operation under changing
  98         <type>XVolatileBitmap</type>.
  99
 100         @param rect
 101         A rectangle, within the bounds of the bitmap, to retrieve the
 102         contens from.
 103
 104         @throws <type>VolatileContentDestroyedException</type>
 105         if the bitmap is volatile, and the content has been destroyed by the system.
 106
 107         @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
 108         if parts of the given rectangle are outside the permissible
 109         bitmap area.
 110      */
 111     sequence<byte>              getData( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerRectangle2D rect )
 112         raises (com::sun::star::lang::IndexOutOfBoundsException,
 113                 VolatileContentDestroyedException);
 114
 115     //-------------------------------------------------------------------------
 116
 117     /** Get a single pixel of the bitmap, returning its color
 118         value.<p>
 119
 120         If the internal data format's pixel are not integer multiples
 121         of bytes (i.e. if one pixel occupies less than a byte - the
 122         case of more than one byte per pixel is not specified), the
 123         color value is returned in the least significant bits of the
 124         single byte returned as the color. The details of the returned
 125         pixel data are to be retrieved from the passed bitmap layout.<p>
 126
 127         Note that the bitmap memory layout might change for volatile
 128         bitmaps.<p>
 129
 130         @param bitmapLayout
 131         The memory layout the returned data is in. Note that the color
 132         space returned therein needs to always match the current color
 133         space as would have been returned by getMemoryLayout(). This
 134         is necessary to ensure correct operation under changing
 135         <type>XVolatileBitmap</type>.
 136
 137         @param pos
 138         A position, within the bounds of the bitmap, to retrieve the
 139         color from.
 140
 141         @throws <type>VolatileContentDestroyedException</type>
 142         if the bitmap is volatile, and the content has been destroyed by the system.
 143
 144         @throws <type>com::sun::star::lang::IndexOutOfBoundsException</type>
 145         if the given position is outside the permissible bitmap area.
 146      */
 147     sequence<byte>              getPixel( [out] IntegerBitmapLayout bitmapLayout, [in] ::com::sun::star::geometry::IntegerPoint2D pos )
 148         raises (com::sun::star::lang::IndexOutOfBoundsException,
 149                 VolatileContentDestroyedException);
 150
 151     //-------------------------------------------------------------------------
 152
 153     /** Query the memory layout for this bitmap.<p>
 154
 155         Please note that for volatile bitmaps, the memory layout might
 156         change between subsequent calls.<p>
 157      */
 158     IntegerBitmapLayout getMemoryLayout();
 159 };
 160
 161 }; }; }; };
 162
 163 #endif