offapi/com/sun/star/rendering/XIntegerBitmapColorSpace.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_XIntegerBitmapColorSpace_idl__
  20 #define __com_sun_star_rendering_XIntegerBitmapColorSpace_idl__
  21
  22 #include <com/sun/star/rendering/XColorSpace.idl>
  23
  24 module com { module sun { module star { module rendering {
  25
  26 /** A color space for integer bitmap formats<p>
  27
  28     This interface encapsulates all information specific to a certain
  29     integer bitmap color space, like for example 1555 ARGB. Note that
  30     the individual elements of the integer color representation
  31     sequence need not correspond to the color space's components -
  32     instead, the color components might be packed back-to-back into
  33     those bytes, as they appear in the raw bitmap data.<p>
  34  */
  35 interface XIntegerBitmapColorSpace : XColorSpace
  36 {
  37     /** Query number of bits used per bitmap pixel.<p>
  38
  39         This method yields the total number of bits used for a color
  40         value. At the associated XIntegerBitmap, the
  41         XIntegerBitmap::setPixel() method will expect
  42         a sequence of ceil(BitsPerPixel/8) bytes, and the
  43         XIntegerReadOnlyBitmap::getPixel() will
  44         return that number of bytes. Similarly, the color conversion
  45         expect input data in multiples of ceil(BitsPerPixel/8), and
  46         also return converted data in chunks of this.<p>
  47      */
  48     long                     getBitsPerPixel();
  49
  50     /** Query the number of bits used for each component.<p>
  51
  52         This method returns a sequence of integers, each denoting the
  53         number of bits occupied by the respective component. The sum
  54         of all component bits must be less or equal than the value
  55         returned from getBitsPerPixel(). If the sum is
  56         less, excess bits are always kept in the most significant bits
  57         of a pixel. Color components will appear in the byte sequences
  58         returned from the XIntegerBitmap methods in the
  59         order defined here, with the first element starting from the
  60         least significant bits of the pixel, etc.<p>
  61
  62         @remark For the typical 32 bit RGBA color data, the four
  63         values would all contain the value eight. For a 16 bit 1555
  64         ARGB format, with mask values 0x8000 for alpha, 0x7C for red,
  65         0x3E for green and 0x1F for blue, the values would be 5, 5, 5,
  66         1, in that order.
  67      */
  68     sequence<long>           getComponentBitCounts();
  69
  70     /** Query whether color data bytes need to be swapped.<p>
  71
  72         @return `TRUE`, This method returns the endianness of the color
  73         data. The value is one of the Endianness
  74         constants. If color data is represented using more than one
  75         byte, the actual channel positions are specified using bit
  76         positions. Therefore, depending on the architecture, the
  77         actual color data bytes might need to get swapped, for the
  78         bits to align properly.<p>
  79
  80         @remark with a 16 bit 565 RGB format, written on a big endian
  81         architecture, a destination machine using little endian CPU
  82         will need to swap the bytes, in order to keep the green
  83         channel bits together.
  84      */
  85     byte                     getEndianness();
  86
  87
  88     /** Convert integer bitmap color to generic IEEE double device
  89         color of another color space.<p>
  90
  91         Color values are properly rounded and clipped, to be valid in
  92         the target color space.<p>
  93
  94         @param deviceColor Sequence of device color components. Is
  95         permitted to contain more than one device color element,
  96         therefore, batch conversion of multiple color values is
  97         possible.<p>
  98
  99         @param targetColorSpace the color space to convert to.
 100
 101         @return the corresponding sequence of device colors in the
 102         target color space
 103
 104         @throws a
 105         com::sun::star::lang::IllegalArgumentException,
 106         if the input sequence does not match the device color format.
 107      */
 108     sequence<ColorComponent> convertFromIntegerColorSpace( [in] sequence<byte> deviceColor, [in] XColorSpace targetColorSpace )
 109         raises (com::sun::star::lang::IllegalArgumentException);
 110
 111     /** Convert integer bitmap color to integer bitmap color of
 112         another integer bitmap color space.<p>
 113
 114         Color values are properly rounded and clipped, to be valid in
 115         the target color space.<p>
 116
 117         @param deviceColor Sequence of device color components. Is
 118         permitted to contain more than one device color element,
 119         therefore, batch conversion of multiple color values is
 120         possible.<p>
 121
 122         @param targetColorSpace the color space to convert to.
 123
 124         @return the corresponding sequence of device colors in the
 125         target color space
 126
 127         @throws a
 128         com::sun::star::lang::IllegalArgumentException,
 129         if the input sequence does not match the device color format.
 130      */
 131     sequence<byte>           convertToIntegerColorSpace( [in] sequence<byte> deviceColor, [in] XIntegerBitmapColorSpace targetColorSpace )
 132         raises (com::sun::star::lang::IllegalArgumentException);
 133
 134     /** Convert color value in this color space to sRGB color values.<p>
 135
 136         Any information not representable in the RGBColor
 137         struct is discarded during the conversion. This includes alpha
 138         information.  Color values are properly rounded and clipped,
 139         to be valid in the target color space.<p>
 140
 141         @param deviceColor Sequence of device color components. Is
 142         permitted to contain more than one device color element,
 143         therefore, batch conversion of multiple color values is
 144         possible.
 145
 146         @return the corresponding sequence of sRGB colors.
 147
 148         @see XIntegerBitmapColorSpace::convertIntegerToARGB()
 149
 150         @throws a
 151         com::sun::star::lang::IllegalArgumentException,
 152         if the input sequence does not match the device color format.
 153      */
 154     sequence<RGBColor>       convertIntegerToRGB( [in] sequence<byte> deviceColor )
 155         raises (com::sun::star::lang::IllegalArgumentException);
 156
 157     /** Convert color value in this color space to sRGB color values,
 158         with linear alpha.<p>
 159
 160         If the given input color does not carry alpha information, an
 161         alpha value of 1.0 (fully opaque) is assumed.  Color values
 162         are properly rounded and clipped, to be valid in the target
 163         color space.<p>
 164
 165         @param deviceColor Sequence of device color components. Is
 166         permitted to contain more than one device color element,
 167         therefore, batch conversion of multiple color values is
 168         possible.
 169
 170         @return the corresponding sequence of sRGB colors.
 171
 172         @throws a
 173         com::sun::star::lang::IllegalArgumentException,
 174         if the input sequence does not match the device color format.
 175      */
 176     sequence<ARGBColor>      convertIntegerToARGB( [in] sequence<byte> deviceColor )
 177         raises (com::sun::star::lang::IllegalArgumentException);
 178
 179     /** Convert color value in this color space to premultiplied sRGB
 180         color values, with linear alpha.<p>
 181
 182         If the given input color does not carry alpha information, an
 183         alpha value of 1.0 (fully opaque) is assumed.  Color values
 184         are properly rounded and clipped, to be valid in the target
 185         color space. The resulting individual RGB color values are
 186         premultiplied by the alpha value (e.g. if alpha is 0.5, each
 187         color value has only half of the original intensity).<p>
 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 sRGB colors.
 195
 196         @throws a
 197         com::sun::star::lang::IllegalArgumentException,
 198         if the input sequence does not match the device color format.
 199      */
 200     sequence<ARGBColor>      convertIntegerToPARGB( [in] sequence<byte> deviceColor )
 201         raises (com::sun::star::lang::IllegalArgumentException);
 202
 203     /** Convert sRGB color to an integer representation in this color
 204         space.<p>
 205
 206         If this color space conveys alpha information, it is assumed
 207         be fully opaque for the given RGB color value.  Color values
 208         are properly rounded and clipped, to be valid in the target
 209         color space.<p>
 210
 211         @param rgbColor Sequence of sRGB color components. Is
 212         permitted to contain more than one color element, therefore,
 213         batch conversion of multiple color values is possible.
 214
 215         @return the corresponding sequence of device colors.
 216
 217         @throws a
 218         com::sun::star::lang::IllegalArgumentException,
 219         if the input sequence does not match the device color format.
 220      */
 221     sequence<byte>           convertIntegerFromRGB( [in] sequence<RGBColor> rgbColor )
 222         raises (com::sun::star::lang::IllegalArgumentException);
 223
 224     /** Convert sRGB color with linear alpha into this color space.<p>
 225
 226         If this color space does not convey alpha information, the
 227         specified alpha value is silently ignored.  Color values are
 228         properly rounded and clipped, to be valid in the target color
 229         space.<p>
 230
 231         @param rgbColor Sequence of sRGB color components. Is
 232         permitted to contain more than one color element, therefore,
 233         batch conversion of multiple color values is possible.
 234
 235         @return the corresponding sequence of device colors.
 236
 237         @throws a
 238         com::sun::star::lang::IllegalArgumentException,
 239         if the input sequence does not match the device color format.
 240      */
 241     sequence<byte>           convertIntegerFromARGB( [in] sequence<ARGBColor> rgbColor )
 242         raises (com::sun::star::lang::IllegalArgumentException);
 243
 244     /** Convert premultiplied sRGB color with linear alpha into this
 245        color space.<p>
 246
 247         If this color space does not convey alpha information, the
 248         specified alpha value is silently ignored.  Color values are
 249         properly rounded and clipped, to be valid in the target color
 250         space.<p>
 251
 252         @param rgbColor Sequence of sRGB color components. Is
 253         permitted to contain more than one color element, therefore,
 254         batch conversion of multiple color values is possible. The
 255         individual RGB color values are assumed to be premultiplied by
 256         the alpha value already.
 257
 258         @return the corresponding sequence of device colors.
 259
 260         @throws a
 261         com::sun::star::lang::IllegalArgumentException,
 262         if the input sequence does not match the device color format.
 263      */
 264     sequence<byte>           convertIntegerFromPARGB( [in] sequence<ARGBColor> rgbColor )
 265         raises (com::sun::star::lang::IllegalArgumentException);
 266 };
 267
 268 }; }; }; };
 269
 270 #endif
 271
 272 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */