offapi/com/sun/star/rendering/XIntegerBitmapColorSpace.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: XIntegerBitmapColorSpace.idl,v $
  10  * $Revision: 1.2 $
  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_XIntegerBitmapColorSpace_idl__
  31 #define __com_sun_star_rendering_XIntegerBitmapColorSpace_idl__
  32
  33 #ifndef __com_sun_star_rendering_XColorSpace_idl__
  34 #include <com/sun/star/rendering/XColorSpace.idl>
  35 #endif
  36
  37 module com { module sun { module star { module rendering {
  38
  39 /** A color space for integer bitmap formats<p>
  40
  41     This interface encapsulates all information specific to a certain
  42     integer bitmap color space, like for example 1555 ARGB. Note that
  43     the individual elements of the integer color representation
  44     sequence need not correspond to the color space's components -
  45     instead, the color components might be packed back-to-back into
  46     those bytes, as they appear in the raw bitmap data.<p>
  47  */
  48 interface XIntegerBitmapColorSpace : XColorSpace
  49 {
  50     /** Query number of bits used per bitmap pixel.<p>
  51
  52         This method yields the total number of bits used for a color
  53         value. At the associated <type>XIntegerBitmap</type>, the
  54         <member>XIntegerBitmap::setPixel()</member> method will expect
  55         a sequence of ceil(BitsPerPixel/8) bytes, and the
  56         <member>XIntegerReadOnlyBitmap::getPixel()</member> will
  57         return that number of bytes. Similarly, the color conversion
  58         expect input data in multiples of ceil(BitsPerPixel/8), and
  59         also return converted data in chunks of this.<p>
  60      */
  61     long                     getBitsPerPixel();
  62
  63     /** Query the number of bits used for each component.<p>
  64
  65         This method returnes a sequence of integers, each denoting the
  66         number of bits occupied by the respective component. The sum
  67         of all component bits must be less or equal than the value
  68         returned from <member>getBitsPerPixel()</member>. If the sum is
  69         less, excess bits are always kept in the most significant bits
  70         of a pixel. Color components will appear in the byte sequences
  71         returned from the <type>XIntegerBitmap</type> methods in the
  72         order defined here, with the first element starting from the
  73         least significant bits of the pixel, etc.<p>
  74
  75         @example For the typical 32 bit RGBA color data, the four
  76         values would all contain the value eight. For a 16 bit 1555
  77         ARGB format, with mask values 0x8000 for alpha, 0x7C for red,
  78         0x3E for green and 0x1F for blue, the values would be 5, 5, 5,
  79         1, in that order.
  80      */
  81     sequence<long>           getComponentBitCounts();
  82
  83     /** Query whether color data bytes need to be swapped.<p>
  84
  85         @return <TRUE/>, This method returns the endiannes of the color
  86         data. The value is one of the <type>Endianness</type>
  87         constants. If color data is represented using more than one
  88         byte, the actual channel positions are specified using bit
  89         positions. Therefore, depending on the architecture, the
  90         actual color data bytes might need to get swapped, for the
  91         bits to align properly.<p>
  92
  93         @example with a 16 bit 565 RGB format, written on a big endian
  94         architecture, a destination machine using little endian CPU
  95         will need to swap the bytes, in order to keep the green
  96         channel bits together.
  97      */
  98     byte                     getEndianness();
  99
 100
 101     /** Convert integer bitmap color to generic IEEE double device
 102         color of another color space.<p>
 103
 104         Color values are properly rounded and clipped, to be valid in
 105         the target color space.<p>
 106
 107         @param deviceColor Sequence of device color components. Is
 108         permitted to contain more than one device color element,
 109         therefore, batch conversion of multiple color values is
 110         possible.<p>
 111
 112         @return the corresponding sequence of device colors in the
 113         target color space
 114
 115         @throws a
 116         <type>com::sun::star::lang::IllegalArgumentException</type>,
 117         if the input sequence does not match the device color format.
 118      */
 119     sequence<ColorComponent> convertFromIntegerColorSpace( [in] sequence<byte> deviceColor, [in] XColorSpace targetColorSpace )
 120         raises (com::sun::star::lang::IllegalArgumentException);
 121
 122     /** Convert integer bitmap color to integer bitmap color of
 123         another integer bitmap color space.<p>
 124
 125         Color values are properly rounded and clipped, to be valid in
 126         the target color space.<p>
 127
 128         @param deviceColor Sequence of device color components. Is
 129         permitted to contain more than one device color element,
 130         therefore, batch conversion of multiple color values is
 131         possible.<p>
 132
 133         @return the corresponding sequence of device colors in the
 134         target color space
 135
 136         @throws a
 137         <type>com::sun::star::lang::IllegalArgumentException</type>,
 138         if the input sequence does not match the device color format.
 139      */
 140     sequence<byte>           convertToIntegerColorSpace( [in] sequence<byte> deviceColor, [in] XIntegerBitmapColorSpace targetColorSpace )
 141         raises (com::sun::star::lang::IllegalArgumentException);
 142
 143     /** Convert color value in this color space to sRGB color values.<p>
 144
 145         Any information not representable in the <type>RGBColor</type>
 146         struct is discarded during the conversion. This includes alpha
 147         information.  Color values are properly rounded and clipped,
 148         to be valid in the target color space.<p>
 149
 150         @param deviceColor Sequence of device color components. Is
 151         permitted to contain more than one device color element,
 152         therefore, batch conversion of multiple color values is
 153         possible.
 154
 155         @return the corresponding sequence of sRGB colors.
 156
 157         @see <member>XIntegerBitmapColorSpace::convertIntegerToARGB</member>
 158
 159         @throws a
 160         <type>com::sun::star::lang::IllegalArgumentException</type>,
 161         if the input sequence does not match the device color format.
 162      */
 163     sequence<RGBColor>       convertIntegerToRGB( [in] sequence<byte> deviceColor )
 164         raises (com::sun::star::lang::IllegalArgumentException);
 165
 166     /** Convert color value in this color space to sRGB color values,
 167         with linear alpha.<p>
 168
 169         If the given input color does not carry alpha information, an
 170         alpha value of 1.0 (fully opaque) is assumed.  Color values
 171         are properly rounded and clipped, to be valid in the target
 172         color space.<p>
 173
 174         @param deviceColor Sequence of device color components. Is
 175         permitted to contain more than one device color element,
 176         therefore, batch conversion of multiple color values is
 177         possible.
 178
 179         @return the corresponding sequence of sRGB colors.
 180
 181         @throws a
 182         <type>com::sun::star::lang::IllegalArgumentException</type>,
 183         if the input sequence does not match the device color format.
 184      */
 185     sequence<ARGBColor>      convertIntegerToARGB( [in] sequence<byte> deviceColor )
 186         raises (com::sun::star::lang::IllegalArgumentException);
 187
 188     /** Convert color value in this color space to premultiplied sRGB
 189         color values, with linear alpha.<p>
 190
 191         If the given input color does not carry alpha information, an
 192         alpha value of 1.0 (fully opaque) is assumed.  Color values
 193         are properly rounded and clipped, to be valid in the target
 194         color space. The resulting individual RGB color values are
 195         premultiplied by the alpha value (e.g. if alpha is 0.5, each
 196         color value has only half of the original intensity).<p>
 197
 198         @param deviceColor Sequence of device color components. Is
 199         permitted to contain more than one device color element,
 200         therefore, batch conversion of multiple color values is
 201         possible.
 202
 203         @return the corresponding sequence of sRGB colors.
 204
 205         @throws a
 206         <type>com::sun::star::lang::IllegalArgumentException</type>,
 207         if the input sequence does not match the device color format.
 208      */
 209     sequence<ARGBColor>      convertIntegerToPARGB( [in] sequence<byte> deviceColor )
 210         raises (com::sun::star::lang::IllegalArgumentException);
 211
 212     /** Convert sRGB color to an integer representation in this color
 213         space.<p>
 214
 215         If this color space conveys alpha information, it is assumed
 216         be fully opaque for the given rgb color value.  Color values
 217         are properly rounded and clipped, to be valid in the target
 218         color space.<p>
 219
 220         @param deviceColor Sequence of sRGB color components. Is
 221         permitted to contain more than one color element, therefore,
 222         batch conversion of multiple color values is possible.
 223
 224         @return the corresponding sequence of device colors.
 225
 226         @throws a
 227         <type>com::sun::star::lang::IllegalArgumentException</type>,
 228         if the input sequence does not match the device color format.
 229      */
 230     sequence<byte>           convertIntegerFromRGB( [in] sequence<RGBColor> rgbColor )
 231         raises (com::sun::star::lang::IllegalArgumentException);
 232
 233     /** Convert sRGB color with linear alpha into this color space.<p>
 234
 235         If this color space does not convey alpha information, the
 236         specified alpha value is silently ignored.  Color values are
 237         properly rounded and clipped, to be valid in the target color
 238         space.<p>
 239
 240         @param deviceColor Sequence of sRGB color components. Is
 241         permitted to contain more than one color element, therefore,
 242         batch conversion of multiple color values is possible.
 243
 244         @return the corresponding sequence of device colors.
 245
 246         @throws a
 247         <type>com::sun::star::lang::IllegalArgumentException</type>,
 248         if the input sequence does not match the device color format.
 249      */
 250     sequence<byte>           convertIntegerFromARGB( [in] sequence<ARGBColor> rgbColor )
 251         raises (com::sun::star::lang::IllegalArgumentException);
 252
 253     /** Convert premultiplied sRGB color with linear alpha into this
 254        color space.<p>
 255
 256         If this color space does not convey alpha information, the
 257         specified alpha value is silently ignored.  Color values are
 258         properly rounded and clipped, to be valid in the target color
 259         space.<p>
 260
 261         @param deviceColor Sequence of sRGB color components. Is
 262         permitted to contain more than one color element, therefore,
 263         batch conversion of multiple color values is possible. The
 264         individual RGB color values are assumed to be premultiplied by
 265         the alpha value already.
 266
 267         @return the corresponding sequence of device colors.
 268
 269         @throws a
 270         <type>com::sun::star::lang::IllegalArgumentException</type>,
 271         if the input sequence does not match the device color format.
 272      */
 273     sequence<byte>           convertIntegerFromPARGB( [in] sequence<ARGBColor> rgbColor )
 274         raises (com::sun::star::lang::IllegalArgumentException);
 275 };
 276
 277 }; }; }; };
 278
 279 #endif