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