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