dmColor(3dm) dmColor(3dm) NAME dmColor - 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: 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. 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 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 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. 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 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); /**/ 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 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. #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 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 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 ALSO dmColorConvert(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