Function Name: Convert Color To Given Model

Definition

This function converts a color data value in one color model to the equivalent color data value in another color model. The three color models supported by this function are CMY (Cyan Magenta Yellow), HSV (Hue Saturation Value) and RGB (Red Green Blue).

The color model conversion algorithms are based on the algorithms published in 13.3.2, "The CMY Model", and 13.3.4, "The HSV Model" in Computer Graphics: Principles and Practice - Second Edition in C, by James D. Foley, Andries van Dam, Steven K. Feiner, and John F. Hughes, published by Addison-Wesley Publishing Company (Reprinted with corrections November 1992, November 1993, and July 1995), Copyright 1996, 1990 by Addison-Wesley Publishing Company, Inc.

All incoming data values are expected to be between 0.0 and 1.0, inclusive; the only exception is the value for Hue in the HSV color model, which is expected to be between 0.0 and 360.0, inclusive (360.0 will be automatically converted to 0.0).

The value of SE_POSITIVE_INFINITY will be returned for the Hue value of 'undefined'. When converting from HSV to any other system, if the Saturation value is 0.0, then the Hue value is ignored.

CMYK, HLS, YIQ SUPPORT NOTE: Support for the CMYK (Cyan Magenta Yellow blacK), HLS (Hue Lightness Saturation), and YIQ color models is provided as a convenience, but it is provided in separate functions, e.g. the SE_CMYtoCMYK() and SE_CMYKtoCMY() functions.

Returns

SE_COLOR_NULL_PTR_OUT_PARAMETER - if new_color_ptr was NULL.

SE_COLOR_INVALID_ORIGINAL_COLOR - if original_color_ptr is NULL or if it is not a pointer to a valid set of Color Data values. In this case, *new_color_ptr is not modified.

SE_COLOR_INVALID_NEW_COLOR_MODEL - if new_color_model does not contain a legal value (must be SE_RGB_MODEL, SE_CMY_MODEL, or SE_HSV_MODEL). In this case, *new_color_ptr is not modified.

Prototype

Parameters Notes

original_color_ptr

 a pointer to the incoming color, the color to convert

new_color_model

 the target color model.  RGB, CMY, or HSV.

new_color_ptr

 a pointer to where the converted color will be stored.  This can be
 the same location that original_color_ptr points to, but it does not
 have to be.