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

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19 #ifndef __com_sun_star_rendering_XColorSpace_idl__
  20 #define __com_sun_star_rendering_XColorSpace_idl__
  21
  22 #include <com/sun/star/uno/XInterface.idl>
  23 #include <com/sun/star/lang/IllegalArgumentException.idl>
  24 #include <com/sun/star/beans/PropertyValue.idl>
  25 #include <com/sun/star/rendering/ColorProfile.idl>
  26 #include <com/sun/star/rendering/ColorComponent.idl>
  27 #include <com/sun/star/rendering/RGBColor.idl>
  28 #include <com/sun/star/rendering/ARGBColor.idl>
  29
  30 module com { module sun { module star { module rendering {
  31
  32 /** Information how to interpret certain color data.<p>
  33
  34     This interface encapsulates all information that is necessary to
  35     interpret color data, by defining a describing color space, like
  36     for example CMYK or sRGB. You can either convert between this and
  37     an arbitrary other color space, or into the standard RGB or ARGB
  38     formats (because those are so overwhelmingly common in computer
  39     graphics).<p>
  40
  41     All canvas interfaces standardize to sequences of IEEE doubles for
  42     color representation. As this is overly verbose when used for
  43     bitmap data, derived interfaces exist,
  44     e.g. XIntegerBitmapColorSpace, which use sequences of
  45     integers for color representation.<p>
  46  */
  47 interface XColorSpace
  48 {
  49     /** Query type of this color space.<p>
  50
  51         @return a value from the ColorSpaceType constant
  52         group.
  53      */
  54     byte                     getType();
  55
  56     /** Query the kind for each color component.<p>
  57
  58         Color space components tend to correspond to physical
  59         attributes like the amount of one specific colorant contained
  60         in the final output color. This method returns a sequence of
  61         tags, specifying for each component of a color value, to what
  62         color attribute (if any) it corresponds. The values must be
  63         one of the ColorComponentTag constants.<p>
  64
  65         At the same time, the number of elements in this sequence
  66         corresponds to the number of color channels for this color
  67         space.<p>
  68
  69         @remark For the standard RGB color space, ComponentTags
  70         consists of three elements, containing RGB_RED, RGB_GREEN and
  71         RGB_BLUE tags, respectively
  72      */
  73     sequence<byte>           getComponentTags();
  74
  75     /** Query rendering intent of this color space.<p>
  76
  77         @return a value from the RenderingIntent constant
  78         group.
  79      */
  80     byte                     getRenderingIntent();
  81
  82     /** Query various optional properties from the color space.<p>
  83
  84         If this color space has an ICC color profile, the sequence
  85         contains an element named ICCProfile. Some color spaces also
  86         have properties Gamma, Whitepoint and Blackpoint. Background
  87         information for these is available <a
  88         href="http://en.wikipedia.org/wiki/Color_temperature">here</a>.
  89      */
  90     sequence< ::com::sun::star::beans::PropertyValue > getProperties();
  91
  92
  93
  94     /** Convert to color of another color space.<p>
  95
  96         @param deviceColor Sequence of device color components. Is
  97         permitted to contain more than one device color element,
  98         therefore, batch conversion of multiple color values is
  99         possible.
 100
 101         @param targetColorSpace the color space to convert to.
 102
 103         @return the corresponding sequence of device colors in the
 104         target color space (e.g. `sequence<double>` or
 105         `sequence<byte>`).
 106
 107         @throws a
 108         com::sun::star::lang::IllegalArgumentException,
 109         if the input sequence does not match the device color format
 110         (e.g. if the number of components is wrong)
 111      */
 112     sequence<ColorComponent> convertColorSpace( [in] sequence<ColorComponent> deviceColor, [in] XColorSpace targetColorSpace )
 113         raises (com::sun::star::lang::IllegalArgumentException);
 114
 115     /** Convert color value in this color space to sRGB color values.<p>
 116
 117         Any information not representable in the RGBColor
 118         struct is discarded during the conversion. This includes alpha
 119         information.
 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.
 125
 126         @return the corresponding sequence of colors in the sRGB color
 127         space.
 128
 129         @throws a
 130         com::sun::star::lang::IllegalArgumentException,
 131         if the input sequence does not match the device color format.
 132
 133         @see convertToARGB()
 134      */
 135     sequence<RGBColor>       convertToRGB( [in] sequence<ColorComponent> deviceColor )
 136         raises (com::sun::star::lang::IllegalArgumentException);
 137
 138     /** Convert color value in this color space to sRGB color values, with linear alpha.<p>
 139
 140         If the given input color does not carry alpha information, an
 141         alpha value of 1.0 (fully opaque) is assumed.
 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 colors in the sRGB color
 149         space.
 150
 151         @throws a
 152         com::sun::star::lang::IllegalArgumentException,
 153         if the input sequence does not match the device color format.
 154      */
 155     sequence<ARGBColor>      convertToARGB( [in] sequence<ColorComponent> deviceColor )
 156         raises (com::sun::star::lang::IllegalArgumentException);
 157
 158     /** Convert color value in this color space to premultiplied sRGB
 159        color values, with linear alpha.<p>
 160
 161         If the given input color does not carry alpha information, an
 162         alpha value of 1.0 (fully opaque) is assumed. The resulting
 163         individual RGB color values are premultiplied by the alpha
 164         value (e.g. if alpha is 0.5, each color value has only half of
 165         the original intensity).<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 colors in the sRGB color
 173         space.
 174
 175         @throws a
 176         com::sun::star::lang::IllegalArgumentException,
 177         if the input sequence does not match the device color format.
 178      */
 179     sequence<ARGBColor>      convertToPARGB( [in] sequence<ColorComponent> deviceColor )
 180         raises (com::sun::star::lang::IllegalArgumentException);
 181
 182     /** Convert sRGB color to a representation in this color space.<p>
 183
 184         If this color space conveys alpha information, it is assumed
 185         be fully opaque for the given RGB color value.
 186
 187         @param rgbColor Sequence of sRGB color components. Is
 188         permitted to contain more than one color element, therefore,
 189         batch conversion of multiple color values is possible.
 190
 191         @return the corresponding sequence of device colors.
 192
 193         @throws a
 194         com::sun::star::lang::IllegalArgumentException,
 195         if the input sequence does not match the device color format.
 196      */
 197     sequence<ColorComponent> convertFromRGB( [in] sequence<RGBColor> rgbColor )
 198         raises (com::sun::star::lang::IllegalArgumentException);
 199
 200     /** Convert sRGB color with linear alpha into this color space.<p>
 201
 202         If this color space does not convey alpha information, the
 203         specified alpha value is silently ignored.
 204
 205         @param rgbColor Sequence of sRGB color components. Is
 206         permitted to contain more than one color element, therefore,
 207         batch conversion of multiple color values is possible.
 208
 209         @return the corresponding sequence of device colors.
 210
 211         @throws a
 212         com::sun::star::lang::IllegalArgumentException,
 213         if the input sequence does not match the device color format.
 214      */
 215     sequence<ColorComponent> convertFromARGB( [in] sequence<ARGBColor> rgbColor )
 216         raises (com::sun::star::lang::IllegalArgumentException);
 217
 218     /** Convert premultiplied sRGB color with linear alpha into this
 219        color space.<p>
 220
 221         If this color space does not convey alpha information, the
 222         specified alpha value is silently ignored.
 223
 224         @param rgbColor Sequence of sRGB color components. Is
 225         permitted to contain more than one color element, therefore,
 226         batch conversion of multiple color values is possible. The
 227         individual color values are assumed to be premultiplied by the
 228         alpha value.
 229
 230         @return the corresponding sequence of device colors.
 231
 232         @throws a
 233         com::sun::star::lang::IllegalArgumentException,
 234         if the input sequence does not match the device color format.
 235      */
 236     sequence<ColorComponent> convertFromPARGB( [in] sequence<ARGBColor> rgbColor )
 237         raises (com::sun::star::lang::IllegalArgumentException);
 238 };
 239
 240 }; }; }; };
 241
 242 #endif
 243
 244 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */