dmColor(3dm)dmColor(3dm)NAMEdmColor - The Silicon Graphics Color Space Library (CSL)
SYNOPSIS
#include <dmedia/dm_color.h>
-ldmedia
DESCRIPTION
The Color Space Library (CSL) provides a simple, yet powerful, means of
converting images between color spaces (models), packings, subsamplings
and datatypes and/or performing some operation on the image data, such as
adjusting its contrast. The CSL adopts the concept of a "color
converter" for which the source and destination images' parameters are
specified as well as various conversion parameters. The image parameters
are supplied via a DMparams using the calls dmColorSetSrcParams and
dmColorSetDstParams. Conversion parameters are set via the
dmColorSetConvParams call. In most cases, only the source and
destination packings need to be specified as all other values will
default to appropriate values (e.g. CCIR601). Image color spaces
supported are: RGB, YCrCb, and Y (Luminance).
Image parameters include:
Height
Width
Packing
Datatype
Order
Orientation
Mirror
Bias and Scale (per component)
Minimum and Maximum (per component)
Gamma Curve Coefficients (per component)
Gamma Table Entries (per component)
Primaries and whitepoint
Conversion parameters include:
Contrast
Brightness
Saturation
Hue
Default alpha
RGB bias and scale (per component)
YCrCb subsample filtering
FUNCTIONS
All the CSL functions return an error value describing the outcome of the
operation, except dmColorGetErrorString. The CSL includes the following
functions:
Page 1
dmColor(3dm)dmColor(3dm)
Parameters and DMparams
=======================
dmColorSetSrcParams, dmColorGetSrcParams
Sets/gets the source image parameters via DMparams.
dmColorSetDstParams, dmColorGetDstParams
Sets/gets the destination image parameters via DMparams.
dmColorSetConvParams, dmColorGetConvParams
Sets/gets the conversion parameters via DMparams.
Conversion Parameters
=====================
dmColorSetContrast, dmColorGetContrast
Sets/gets the contrast multiplier. Contrast=1 implies normal
contrast (default), Contrast=2 implies double contrast, etc.
dmColorSetBrightness, dmColorGetBrightness
Sets/gets the brightness delta value. Brightness=0 implies no
brightness change (default). Useful range is [-1..+1] corresponding
to [black..white].
dmColorSetSaturation, dmColorGetSaturation
Sets/gets the saturation multiplier. Saturation=1 implies normal
saturation (default). Saturation=2 implies double color saturation.
dmColorSetHue, dmColorGetHue
Sets/gets the hue rotation. Angle is specified in radians. Hue=0
implies no hue rotation (default). The effective range is -pi..+pi.
dmColorSetDefaultAlpha, dmColorGetDefaultAlpha
Sets/gets the default alpha value of the source image. This is the
alpha value used if no specific alpha exists for each pixel. For
example, a default alpha is required when converting from CbYCrY to
ABGR.
dmColorSetSubsamplingFilter, dmColorGetSubsamplingFilter
Sets/gets the type of filter used to convert between different
subsamplings.
Information Routines
====================
dmColorGetSrcSize
Gets the source image size in bytes.
dmColorGetDstSize
Gets the destination image size in bytes.
Page 2
dmColor(3dm)dmColor(3dm)
Manager Routines
================
dmColorCreate
Creates and initializes the color converter. This must always be
the first call on a converter before any other dmColor call is
invoked.
dmColorDestroy
Destroys the converter and returns any allocated memory to the
system. After the call returns, the converter is invalid and should
not be used.
dmColorPrecompute
Before a specific color space conversion is effected, some
precomputation by the CSL is required. This will usually occur when
the first dmColorConvert is invoked. dmColorPrecompute may be used
to move this overhead outside the loop.
dmColorConvert
Performs the actual conversion. For performance reasons, this is
the only dmColor call which should reside in the inner loop.
Error Handling Routines
=======================
dmColorGetError
Returns the value of the error flag.
dmColorGetErrorString
Returns an error message.
TYPES
The CSL includes the following type:
DMcolorconverter
DMcolorconverter describes an image conversion. A DMcolorconverter
typed variable is used as the first parameter of every dmColor call;
except dmColorGetErrorString. The number of converters is only
limited by memory, and each is totally independent of any other.
CONSTANTS
The CSL supports the following tokens defined in <dmedia/dm_image.h>:
DM_IMAGE_WIDTH
DM_IMAGE_HEIGHT
DM_IMAGE_PACKING: DM_IMAGE_PACKING_RGB
DM_IMAGE_PACKING_BGR
DM_IMAGE_PACKING_RGBX
DM_IMAGE_PACKING_RGBA
DM_IMAGE_PACKING_XRGB
Page 3
dmColor(3dm)dmColor(3dm)
DM_IMAGE_PACKING_ARGB
DM_IMAGE_PACKING_XBGR
DM_IMAGE_PACKING_ABGR
DM_IMAGE_PACKING_XRGB1555
DM_IMAGE_PACKING_RGBA5551
DM_IMAGE_PACKING_CbYCr
DM_IMAGE_PACKING_CbYCrA
DM_IMAGE_PACKING_CbYCrY
DM_IMAGE_PACKING_CbYCrYYY
DM_IMAGE_PACKING_LUMINANCE
DM_IMAGE_PACKING_LUMINANCE_ALPHA
DM_IMAGE_DATATYPE: DM_IMAGE_DATATYPE_BIT
DM_IMAGE_DATATYPE_CHAR
DM_IMAGE_DATATYPE_SHORT10L
DM_IMAGE_DATATYPE_SHORT10R
DM_IMAGE_DATATYPE_SHORT12L
DM_IMAGE_DATATYPE_SHORT12R
DM_IMAGE_ORDER: DM_IMAGE_ORDER_INTERLEAVED
DM_IMAGE_ORDER_SEQUENTIAL
DM_IMAGE_ORDER_SEPARATE
DM_IMAGE_ORIENTATION: DM_IMAGE_TOP_TO_BOTTOM
DM_IMAGE_BOTTOM_TO_TOP
DM_IMAGE_MIRROR: DM_IMAGE_LEFT_TO_RIGHT
DM_IMAGE_RIGHT_TO_LEFT
DM_IMAGE_COMPONENT_1
DM_IMAGE_COMPONENT_2
DM_IMAGE_COMPONENT_3
DM_IMAGE_COMPONENT_ALPHA
DM_IMAGE_COMPONENT_ALL
DM_IMAGE_BIAS
DM_IMAGE_SCALE
DM_IMAGE_MIN
DM_IMAGE_MAX
DM_IMAGE_GAMMA
DM_IMAGE_GAMMA_TB
DM_IMAGE_GAMMA_TS
DM_IMAGE_GAMMA_A
DM_IMAGE_GAMMA_B
DM_IMAGE_GAMMA_C
DM_IMAGE_GAMMA_TABLE
DM_IMAGE_PRIMARY_RED_x
DM_IMAGE_PRIMARY_RED_y
DM_IMAGE_PRIMARY_GREEN_x
DM_IMAGE_PRIMARY_GREEN_y
DM_IMAGE_PRIMARY_BLUE_x
DM_IMAGE_PRIMARY_BLUE_y
DM_IMAGE_WHITEPOINT_x
DM_IMAGE_WHITEPOINT_y
DM_COLOR_CONV_CONTRAST
DM_COLOR_CONV_BRIGHTNESS
DM_COLOR_CONV_SATURATION
DM_COLOR_CONV_HUE
Page 4
dmColor(3dm)dmColor(3dm)
DM_COLOR_CONV_DEFAULT_ALPHA
DM_COLOR_CONV_SUBSAMPLING_FILTER
DM_COLOR_CONV_RED_BIAS
DM_COLOR_CONV_RED_SCALE
DM_COLOR_CONV_GREEN_BIAS
DM_COLOR_CONV_GREEN_SCALE
DM_COLOR_CONV_BLUE_BIAS
DM_COLOR_CONV_BLUE_SCALE
DM_COLOR_CONV_TRANSFORM_MATRIX
Packing and Order
Packing refers to the relative ordering of the components within the
image data. For example, ARGB, RGBA, ABGR are various combinations of
storing pixel information using the RGB model with an associated alpha
value. Here is a descriptive example of how order affects the data:
ABGR packing:
Interleaved: ABGRABGRABGR
Sequential: AAABBBGGGRRR on a per line basis
Separate: AAABBBGGGRRR on a per image basis
CbYCr packing:
Interleaved: CbYCrCbYCrCbYCr
Sequential: CbCbCbYYYCrCrCr on a per line basis
Separate: CbCbCbYYYCrCrCr on a per image basis
CbYCrY packing:
Interleaved: CbYCrYCbYCrYCbYCrY
Sequential: CbCbCbYYYYYYCrCrCr on a per line basis
Separate: CbCbCbYYYYYYCrCrCr on a per image basis
CbYCrYYY packing:
Interleaved: CbYCrYYYCbYCrYYYCbYCrYYY
Sequential: CbCbCbYYYYYYYYYYYYCrCrCr on a per line basis
Separate: CbCbCbYYYYYYYYYYYYCrCrCr on a per image basis
Note: Sequential 420 YCrCb data (CbYCrYYY packing) stores the Cb for rows
N and N+1, followed by the Y for row N followed by the Y for row N+1
followed by the Cr for rows N and N+1.
Note: Separate 420 YCrCb data (CbYCrYYY packing) stores the Cb for rows 0
thru' N-1, followed by the Y for row 0 thru' N-1, followed by the Cr for
rows 0 thru' N-1.
Datatype
The datatype refers to the number of bits used to represent each
component and the alignment of those bits in the case of 10 and 12-
bit components. In the case of the XRGB1555 and RGBA5551 packings,
the entire pixel fits into 16 bits. This packing is considered to
be DM_IMAGE_DATATYPE_BIT. The default datatype is
DM_IMAGE_DATATYPE_CHAR.
Page 5
dmColor(3dm)dmColor(3dm)
DM_IMAGE_DATATYPE_BIT Non-uniform # bits per component
DM_IMAGE_DATATYPE_CHAR 8 bits per component
DM_IMAGE_DATATYPE_SHORT10L 10 bits per component - left aligned
DM_IMAGE_DATATYPE_SHORT10R 10 bits per component - right aligned
DM_IMAGE_DATATYPE_SHORT12L 12 bits per component - left aligned
DM_IMAGE_DATATYPE_SHORT12R 12 bits per component - right aligned
Components
Component parameters are contained within a DMparams which is itself
an element of the image DMparams. DM_IMAGE_COMPONENT_ALL is a
convenience token which allows a single DMparams to define the
parameters for all the components, including alpha, using a single
DMparams. If a DM_IMAGE_COMPONENT_ALL DMparams exists, then those
parameters are set for each component. Thereafter, each individual
component's DMparams is dealt with.
DM_IMAGE_COMPONENT_1 Component 1
DM_IMAGE_COMPONENT_2 Component 2
DM_IMAGE_COMPONENT_3 Component 3
DM_IMAGE_COMPONENT_ALPHA Component alpha
DM_IMAGE_COMPONENT_ALL All components
Subsample Filtering
Three types of subsample filtering exist:
DM_COLOR_SUBSAMPLINGFILTER_TYPE0 (default): The chroma is replicated or
eliminated depending on the subsampling of the source and destination
images. This is the fastest, yet the most inaccurate. Aliasing can
occur in images containing high frequencies.
DM_COLOR_SUBSAMPLINGFILTER_TYPE1: Linear interpolation and a 3-tap
filter are used. Type 1 filtering has a minimal impact on performance,
yet produces excellent results and can significantly reduce the aliasing
effect. 422 and 444 subsamplings are supported.
DM_COLOR_SUBSAMPLINGFILTER_TYPE2: The recommended CCIR filters are
applied. Type 2 incurs a performance hit. 422 and 444 subsamplings are
supported.
AUTOMAGIC PROPAGATION
Automagic propagation refers to the automatic setting of defaults
pertaining to a parameter change. For example, if the datatype is set,
the CSL will automatically set the bias, scale, and minimum and maximum
values. Automagic propagation uses defaults as described in the DEFAULTS
section.
The CSL will automagically set the following:
Parameter explicitly set Parameter implicitly set by CSL
Packing Datatype
Page 6
dmColor(3dm)dmColor(3dm)
Datatype Bias and Scale
Min and max
GAMMA CORRECTION
Gamma correction is effected on each channel of both source and
destination RGB data. Using the Color Space Library, there are two ways
of defining gamma:
1. Gamma Curve Coefficients
Each channel is calculated by:
X = X * TS if X < TB
X = ((X+A)*B)^gamma + C otherwise
where X is either R, G, or B. The toe break (TB) and toe slope (TS) are
definable as well as the variables A, B, C which allow excellent control
of the correction curve. Note that if X = X^gamma is required, simply set
TB = TS = A = C = 0, and B = 1. The offset C can be used to increase or
decrease the saturation of R, G, or B of source or destination RGB data.
Gamma has no affect on YCrCb data. Each channel is normalized.
Therefore, the mapping occurs from [0..1] to [0..1]. If the entries of
the gamma table have been set, the gamma curve coefficients are ignored.
2. Gamma Table Entries
Gamma tables allow the exact specification of an arbitrary gamma curve.
A gamma table is defined by setting a DMfloatarray, and calling
dmParamsSetParams with DM_IMAGE_GAMMA_TABLE to set the component's
DMparams. If a gamma table have been defined, the gamma curve
coefficients are ignored. The table is defined for [0..1]. Intermediate
values are interpolated. For example, to define red's gamma table having
a X and Y intercept of 1; i.e. y = -x + 1, the following code would be
used:
#include <dmedia/dm_color.h>
#include <dmedia/dm_params.h>
void SetGammaTable (DMcolorconverter converter)
{
double dGammaTable [2] = {1, 0};
DMparams *imageParams,
*compParams;
DMfloatarray gammaTable;
dmParamsCreate (&imageParams);
dmParamsCreate (&compParams);
/**/
gammaTable.elemCount = 2;
gammaTable.elems = dGammaTable;
dmParamsSetFloatArray (compParams, DM_IMAGE_GAMMA_TABLE, &gammaTable);
/**/
dmParamsSetParams (imageParams, DM_IMAGE_COMPONENT_1, compParams);
dmColorSetDstParams (converter, imageParams);
Page 7
dmColor(3dm)dmColor(3dm)
/**/
dmParamsDestroy (compParams);
dmParamsDestroy (imageParams);
}
DEFAULTS
Defaults are used when a converter is created using dmColorCreate, when
the packing changes, or when the datatype changes. In addition,
automagic propagation applies these defaults.
Name Type Default Comments
Height int 0 Must be set non-negative
Width int 0 Must be set non-negative
Packing type RGBA
Datatype type BYTE 8 bits per component
Gamma double 1.0 Assume no gamma correction
Gamma Toe Break double 0.0 Have no toe slope
Gamma Toe Slope double 0.0 No slope anyway
Gamma A, C double 0.0 See "Gamma Correction"
Gamma B double 1.0 See "Gamma Correction"
Contrast double 1.0 1.0 times normal contrast
Brightness double 0.0 0.0 brightness change
Saturation double 1.0 1.0 times normal saturation
Hue double 0.0 0.0 hue rotation
Primaries double CCIR 709
Whitepoint double D65
DM_IMAGE_DATATYPE_BIT defaults
Alpha float 1 May be clipped by MinMax
BiasScale float [0..31] For RGB in RGBA5551
[0..1] For alpha in RGBA5551
MinMax float [0..31] For RGB in RGBA5551
[0..1] For alpha in RGBA5551
DM_IMAGE_DATATYPE_CHAR defaults
Alpha float 255 May be clipped by MinMax
BiasScale float [0..255] For RGB in RGB
[0..255] For Y in LUMINANCE
[16..235] For Y in YCrCb
[16..240] For CrCb in YCrCb
[0..255] For alpha in RGB
[0..255] For alpha in LUMINANCE
[0..255] For alpha in YCrCb
MinMax float [0..255] For RGB in RGB
[0..255] For Y in LUMINANCE
[1..254] For YCrCb in YCrCb
[0..255] For alpha in RGB
[0..255] For alpha in LUMINANCE
[1..254] For alpha in YCrCb
Page 8
dmColor(3dm)dmColor(3dm)
DM_IMAGE_DATATYPE_SHORT10L and DM_IMAGE_DATATYPE_SHORT10R defaults
Alpha float 1023 May be clipped by MinMax
BiasScale float [0..1023] For RGB in RGB
[0..1023] For Y in LUMINANCE
[64..940] For Y in YCrCb
[64..960] For CrCb in YCrCb
[0..1023] For alpha in RGB
[0..1023] For alpha in LUMINANCE
[0..1023] For alpha in YCrCb
MinMax float [0..1023] For RGB in RGB
[0..1023] For Y in LUMINANCE
[4..1019] For YCrCb in YCrCb
[0..1023] For alpha in RGB
[0..1023] For alpha in LUMINANCE
[4..1019] For alpha in YCrCb
DM_IMAGE_DATATYPE_SHORT12L and DM_IMAGE_DATATYPE_SHORT12R defaults
Alpha float 4095 May be clipped by MinMax
BiasScale float [0..4095] For RGB in RGB
[0..4095] For Y in LUMINANCE
[256..3760] For Y in YCrCb
[256..3840] For CrCb in YCrCb
[0..4095] For alpha in RGB
[0..4095] For alpha in LUMINANCE
[0..4095] For alpha in YCrCb
MinMax float [0..4095] For RGB in RGB
[0..4095] For Y in LUMINANCE
[16..4079] For YCrCb in YCrCb
[0..4095] For alpha in RGB
[0..4095] For alpha in LUMINANCE
[16..4079] For alpha in YCrCb
ERRORS
See dmColorGetError and dmColorGetErrorString.
DM_COLOR_ERROR_NONE No error.
DM_COLOR_ERROR_OUT_OF_MEMORY Out of memory!
DM_COLOR_ERROR_INVALID_CONVERTER Invalid converter!
DM_COLOR_ERROR_INVALID_SRC Invalid source pointer!
DM_COLOR_ERROR_INVALID_DST Invalid destination pointer!
DM_COLOR_ERROR_INVALID_TOKEN Invalid token!
DM_COLOR_ERROR_INVALID_VALUE Invalid value!
DM_COLOR_ERROR_INVALID_DIMENSION Invalid dimension!
DM_COLOR_ERROR_INVALID_TRANSFORM Invalid transform!
EXAMPLE CODE
Each conversion is defined by a separate converter. This converter may
be used repeatedly on one or more images. For example, the code below
will convert a 640x480 image in the YCrCb color space with a CbYCrY
packing (i.e. 4:2:2 subsampling) to a 640x480 image with an XBGR packing.
Error checking has been omitted for clarity.
Page 9
dmColor(3dm)dmColor(3dm)
#include <stdlib.h>
#include <dmedia/dm_color.h>
#include <dmedia/dm_image.h>
#include <dmedia/dm_params.h>
void DisplayImages (int iNumImages)
{
int i, /* Used to loop through the images. */
iDstSize; /* Number of bytes in dst image. */
void *pDstImage; /* Pointer to the dst image. */
DMparams *params; /* Stores the image parameters. */
DMcolorconverter converter; /* The actual converter. */
dmColorCreate (&converter);
dmParamsCreate (¶ms);
dmParamsSetEnum (params, DM_IMAGE_WIDTH, 640);
dmParamsSetEnum (params, DM_IMAGE_HEIGHT, 480);
dmParamsSetEnum (params,
DM_IMAGE_PACKING,
DM_IMAGE_PACKING_CbYCrY);
dmColorSetSrcParams (converter,
params);
dmParamsSetEnum (params,
DM_IMAGE_PACKING,
DM_IMAGE_PACKING_XBGR);
dmColorSetDstParams (converter,
params);
dmParamsDestroy (params);
dmColorGetDstSize (converter, &iDstSize);
/*
Allocate a block of memory large enough to store the destination image.
*/
pDstImage = malloc (iDstSize);
for (i = 0; i < iNumImages; i++)
{
dmColorConvert (converter,
Images [i],
pDstImage);
DisplayImage (pDstImage); /* Not in this library! */
}
free (pDstImage);
dmColorDestroy (converter);
}
Note: It is suggested that (at least) the return values of dmColorCreate
and malloc are checked. Removed in this example for the sake of clarity.
IN-PLACE CONVERSIONS
In-place routines are ones in which the srcImage and dstImage pointers
are equal, and hence point to the same memory block. In-place
conversions have two major advantages; namely, memory for only one image
needs to be allocated, and the conversion can be faster due to cache
Page 10
dmColor(3dm)dmColor(3dm)
behavior. Listed below are conditions which must hold for an in-place
call to dmColorConvert to be successful. If the conditions below are not
satisfied, the results of an in-place conversions are unpredictable.
1. SrcOrder == DstOrder
2. SrcDataType == DstDataType
3. SrcOrientation == DstOrientation
4. dmColorGetSrcSize == dmColorGetDstSize
Note: Condition 3 is relaxed for the special case routines.
SPECIAL CASE ROUTINES
Several of the more commonly used routines have been optimized. This is
transparent to the user of the library, except for the higher
performance. These routines can perform in-place vertical and horizontal
flips (i.e. change the image orientation and mirror). All have both
source and destination data types of DM_IMAGE_DATATYPE_CHAR, and
subsampling filter of type 0. The routines are:
XBGR/ABGR to XBGR
Conditions: Both source and destination images must have interleaved
order.
XRGB/ARGB/XBGR/ABGR to XRGB/ARGB/XBGR/ABGR, excluding X*** to A***
Conditions: Both source and destination images must have interleaved
order. No conversion on RGBA components.
LUMINANCE to 32-bit RGB packings
Conditions: None
LUMINANCE to LUMINANCE
Conditions: None
CbYCrA (444) to XBGR
Conditions: Both source and destination images must have interleaved
order.
CbYCrY (422) to XBGR
Conditions: Source images must have interleaved or separate order.
Destination images must have interleaved order.
CbYCrYYY (420) to XBGR
Conditions: Source order must be separate and destination order must be
interleaved. Must have even height and width.
OpenGL COMPATABILITY
Calling dmColorGetConvParams will set the params list with details of the
current conversion parameters. One of these parameters passed back in
the params list is DM_COLOR_CONV_TRANSFORM_MATRIX. This matrix defines
any color model, contrast, brightness, saturation, hue, bias, scale,
colorimetry, whitepoint, and RGB changes. Note that min, max, and gamma
are not included. The matrix is of type DMfloatarray and holds the
Page 11
dmColor(3dm)dmColor(3dm)
glLoadMatrix compatable transform matrix in column major format:
Column Major: |a0 a4 a8 a12|
| |
|a1 a5 a9 a13|
| |
|a2 a6 a10 a14|
| |
|a3 a7 a11 a15|
KNOWN BUGS
None.
SEE ALSOdmColorConvert(3dm)dmColorCreate(3dm)dmColorDestroy(3dm)dmColorGetBrightness(3dm)dmColorGetContrast(3dm)dmColorGetDefaultAlpha(3dm)dmColorGetDstParams(3dm)dmColorGetDstSize(3dm)dmColorGetError(3dm)dmColorGetErrorString(3dm)dmColorGetHue(3dm)dmColorGetSaturation(3dm)dmColorGetSrcParams(3dm)dmColorGetSrcSize(3dm)dmColorGetSubsamplingFilter(3dm)dmColorGetConvParams(3dm)dmColorPrecompute(3dm)dmColorSetBrightness(3dm)dmColorSetContrast(3dm)dmColorSetDefaultAlpha(3dm)dmColorSetDstParams(3dm)dmColorSetHue(3dm)dmColorSetSaturation(3dm)dmColorSetSrcParams(3dm)dmColorSetSubsamplingFilter(3dm)dmColorSetConvParams(3dm)glLoadMatrix(3G)glPixelTransfer(3G)glMatrixMode(3G)
Page 12
