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