Color Profiles

The following API calls implement the colorprofile ... end colorprofile blocks in .mi scene files, which attach a name to a profile.

miColor_profile *mi_api_colorprofile_begin(
    char            *name)          /* name of color profile */

Begin the definition of a color profile named name, and return a pointer to the new color profile. The caller should set the following fields: space describes the color space associated with the color profile. Valid color spaces are miCPROF_RGB, miCPROF_NTSC, miCPROF_HDTV, miCPROF_SHARP, miCPROF_CIEXYZ, miCPROF_CIEXYY, miCPROF_LINERGB, miCPROF_BOXRGB, miCPROF_CUSTOM. For custom color spaces the bit defined by miCPROF_CID_NOT_ENOUGH needs also to be set in the space field. It is recommended to use the routine mi_api_colorprofile_space to set the space field.

The caller may set the following fields: white_adapt should be set to true if a white adaption is requested when transforming to other color spaces. If this value is false, then the white point intrinsic to the color space is used. white contains the CIE XYZ coordinates of the white point assigned to the color space. Other fields should only be set through the provided interface routines below.

miUint1 mi_api_colorprofile_space(
    char            *name)          /* name of color space */

may be used to set the space field of the current color profile. The routine parses the name string describing the name of a color space and returns the value to be used for the space field. The routine will release the memory associated with its parameter. Valid argument strings are "rgb", "hdtv", "ntsc", "ciexyz", "ciexyy", "linergb", "boxrgb", and "sharp". There is no string for sRGB, since this color space differs from the HDTV standard only by the gamma correction.

void mi_api_colorprofile_gamma(
    miScalar        gamma,      /* gamma corr. exponent */
    miScalar        offset,     /* below gamma corr. is linear */
    miBoolean       force)      /* allow values < 1 */

is used to assign a gamma correction to the current color profile. The gamma correction mapping associated with color spaces like HDTV or sRGB are not just exponentiation, since electronic circuits cannot properly deal with infinite slopes at the origin. Hence, gamma corrections are often assumed to be linear below a certain threshold offset value. This routine takes such models into account and will set all gamma parameters in the color profile. If the force argument is set to true, then values of the gammma exponent below 1.0 will be directly used, else the reciprocal value is used for exponents below 1.0.

void mi_api_colorprofile_white(
    miColor         *white,          /* return white point */
    int             temperature,     /* color temperature */
    miScalar        intensity)       /* intensity of white */

Caculates the CIE XYZ coordinates of a white point given by the color temperature associated with CIE D illuminant. Valid temperatures are between 4000 and 25000 Kelvin. A value of 6500 Kelvin corresponds to the color temperature of an average overcast sky (D65 illuminant). The provided temperature is used to calculate an associated color. This color may be scaled to the provided intensity.

miBoolean mi_api_colorprofile_custom(
    miColor_profile *cprof,         /* color profile */
    miMatrix        m)              /* custom transform */

If the space field is set for a custum color profile, then this routine may be called to set the color space transformation matrix and its inverse for the passed in color profile. The routine will only use the upper 3 by 3 sub-matrix and assume that this matrix describes the transform from CIE XYZ space to the custom color space. After all fields are defined, call mi_api_colorprofile_end.

miTag mi_api_colorprofile_end()

Completes the definition of a color profile.

Copyright © 1986, 2013 NVIDIA Corporation