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_XColorSpace_idl__
24#define __com_sun_star_rendering_XColorSpace_idl__
25
26#ifndef __com_sun_star_uno_XInterface_idl__
27#include <com/sun/star/uno/XInterface.idl>
28#endif
29#ifndef __com_sun_star_lang_IllegalArgumentException_idl__
30#include <com/sun/star/lang/IllegalArgumentException.idl>
31#endif
32#ifndef __com_sun_star_beans_PropertyValue_idl__
33#include <com/sun/star/beans/PropertyValue.idl>
34#endif
35#ifndef __com_sun_star_rendering_ColorProfile_idl__
36#include <com/sun/star/rendering/ColorProfile.idl>
37#endif
38
39module com { module sun { module star { module rendering {
40
41/// Shorthand for the device-dependent color components, and easier to read
42published typedef double ColorComponent;
43published typedef sequence<ColorComponent> Color;
44
45//=============================================================================
46
47/// RGB color triplet
48published struct RGBColor
49{
50    /// Red component. Valid range is [0,1.0]
51    ColorComponent Red;
52    /// Green component. Valid range is [0,1.0]
53    ColorComponent Green;
54    /// Blue component. Valid range is [0,1.0]
55    ColorComponent Blue;
56};
57
58//=============================================================================
59
60/// ARGB color quad
61published struct ARGBColor
62{
63    /** Alpha component.<p>
64
65        Valid range is [0,1.0], with 0.0 denoting fully transparent,
66        and 1.0 fully opaque.
67     */
68    ColorComponent Alpha;
69    /// Red component. Valid range is [0,1.0]
70    ColorComponent Red;
71    /// Green component. Valid range is [0,1.0]
72    ColorComponent Green;
73    /// Blue component. Valid range is [0,1.0]
74    ColorComponent Blue;
75};
76
77//=============================================================================
78
79/** Information how to interpret certain color data.<p>
80
81    This interface encapsulates all information that is necessary to
82    interpret color data, by defining a describing color space, like
83    for example CMYK or sRGB. You can either convert between this and
84    an arbitrary other colorspace, or into the standard RGB or ARGB
85    formats (because those are so overwhelmingly common in computer
86    graphics).<p>
87
88    All canvas interfaces standardize to sequences of IEEE doubles for
89    color representation. As this is overly verbose when used for
90    bitmap data, derived interfaces exist,
91    e.g. <type>XIntegerBitmapColorSpace</type>, which use sequences of
92    integers for color representation.<p>
93 */
94published interface XColorSpace
95{
96    /** Query type of this color space.<p>
97
98        @return a value from the <type>ColorSpaceType</type> constant
99        group.
100     */
101    byte                     getType();
102
103    /** Query the kind for each color component.<p>
104
105        Color space components tend to correspond to physical
106        attributes like the amount of one specific colorant contained
107        in the final output color. This method returns a sequence of
108        tags, specifying for each component of a color value, to what
109        color attribute (if any) it corresponds. The values must be
110        one of the <type>ColorComponentTag</type> constants.<p>
111
112        At the same time, the number of elements in this sequence
113        corresponds to the number of color channels for this color
114        space.<p>
115
116        @example For the standard RGB color space, ComponentTags
117        consists of three elements, containing RGB_RED, RGB_GREEN and
118        RGB_BLUE tags, respectively
119     */
120    sequence<byte>           getComponentTags();
121
122    /** Query rendering intent of this color space.<p>
123
124        @return a value from the <type>RenderingIntent</type> constant
125        group.
126     */
127    byte                     getRenderingIntent();
128
129    /** Query various optional properties from the color space.<p>
130
131        If this color space has an ICC color profile, the sequence
132        contains an element named ICCProfile. Some color spaces also
133        have properties Gamma, Whitepoint and Blackpoint. Background
134        information for these is available <a
135        href="http://en.wikipedia.org/wiki/Color_temperature">here</a>.
136     */
137    sequence< ::com::sun::star::beans::PropertyValue > getProperties();
138
139
140    //=============================================================================
141
142    /** Convert to color of another color space.<p>
143
144        @param deviceColor Sequence of device color components. Is
145        permitted to contain more than one device color element,
146        therefore, batch conversion of multiple color values is
147        possible.
148
149        @return the corresponding sequence of device colors in the
150        target color space (e.g. <type>sequence<double></type> or
151        <type>sequence<byte></type>).
152
153        @throws a
154        <type>com::sun::star::lang::IllegalArgumentException</type>,
155        if the input sequence does not match the device color format
156        (e.g. if the number of components is wrong)
157     */
158    sequence<ColorComponent> convertColorSpace( [in] sequence<ColorComponent> deviceColor, [in] XColorSpace targetColorSpace )
159        raises (com::sun::star::lang::IllegalArgumentException);
160
161    /** Convert color value in this color space to sRGB color values.<p>
162
163        Any information not representable in the <type>RGBColor</type>
164        struct is discarded during the conversion. This includes alpha
165        information.
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 colors in the sRGB color
173        space.
174
175        @throws a
176        <type>com::sun::star::lang::IllegalArgumentException</type>,
177        if the input sequence does not match the device color format.
178
179        @see <member>convertToARGB</member>
180     */
181    sequence<RGBColor>       convertToRGB( [in] sequence<ColorComponent> deviceColor )
182        raises (com::sun::star::lang::IllegalArgumentException);
183
184    /** Convert color value in this color space to sRGB color values, with linear alpha.<p>
185
186        If the given input color does not carry alpha information, an
187        alpha value of 1.0 (fully opaque) is assumed.
188
189        @param deviceColor Sequence of device color components. Is
190        permitted to contain more than one device color element,
191        therefore, batch conversion of multiple color values is
192        possible.
193
194        @return the corresponding sequence of colors in the sRGB color
195        space.
196
197        @throws a
198        <type>com::sun::star::lang::IllegalArgumentException</type>,
199        if the input sequence does not match the device color format.
200     */
201    sequence<ARGBColor>      convertToARGB( [in] sequence<ColorComponent> deviceColor )
202        raises (com::sun::star::lang::IllegalArgumentException);
203
204    /** Convert color value in this color space to premultiplied sRGB
205       color values, with linear alpha.<p>
206
207        If the given input color does not carry alpha information, an
208        alpha value of 1.0 (fully opaque) is assumed. The resulting
209        individual RGB color values are premultiplied by the alpha
210        value (e.g. if alpha is 0.5, each color value has only half of
211        the original intensity).<p>
212
213        @param deviceColor Sequence of device color components. Is
214        permitted to contain more than one device color element,
215        therefore, batch conversion of multiple color values is
216        possible.
217
218        @return the corresponding sequence of colors in the sRGB color
219        space.
220
221        @throws a
222        <type>com::sun::star::lang::IllegalArgumentException</type>,
223        if the input sequence does not match the device color format.
224     */
225    sequence<ARGBColor>      convertToPARGB( [in] sequence<ColorComponent> deviceColor )
226        raises (com::sun::star::lang::IllegalArgumentException);
227
228    /** Convert sRGB color to a representation in this color space.<p>
229
230        If this color space conveys alpha information, it is assumed
231        be fully opaque for the given rgb color value.
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<ColorComponent> convertFromRGB( [in] sequence<RGBColor> rgbColor )
244        raises (com::sun::star::lang::IllegalArgumentException);
245
246    /** Convert sRGB color with linear alpha into this color space.<p>
247
248        If this color space does not convey alpha information, the
249        specified alpha value is silently ignored.
250
251        @param rgbColor Sequence of sRGB color components. Is
252        permitted to contain more than one color element, therefore,
253        batch conversion of multiple color values is possible.
254
255        @return the corresponding sequence of device colors.
256
257        @throws a
258        <type>com::sun::star::lang::IllegalArgumentException</type>,
259        if the input sequence does not match the device color format.
260     */
261    sequence<ColorComponent> convertFromARGB( [in] sequence<ARGBColor> rgbColor )
262        raises (com::sun::star::lang::IllegalArgumentException);
263
264    /** Convert premultiplied sRGB color with linear alpha into this
265       color space.<p>
266
267        If this color space does not convey alpha information, the
268        specified alpha value is silently ignored.
269
270        @param rgbColor Sequence of sRGB color components. Is
271        permitted to contain more than one color element, therefore,
272        batch conversion of multiple color values is possible. The
273        individual color values are assumed to be premultiplied by the
274        alpha value.
275
276        @return the corresponding sequence of device colors.
277
278        @throws a
279        <type>com::sun::star::lang::IllegalArgumentException</type>,
280        if the input sequence does not match the device color format.
281     */
282    sequence<ColorComponent> convertFromPARGB( [in] sequence<ARGBColor> rgbColor )
283        raises (com::sun::star::lang::IllegalArgumentException);
284};
285
286}; }; }; };
287
288#endif
289