offapi/com/sun/star/rendering/XColorSpace.idl

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