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