| MIL 10 Reference
| Customize Help
| Save Settings

McolAlloc



See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
Previous
Synopsis
Allocate a color matching context or a relative color calibration context.
Syntax
MIL_ID McolAlloc(
MIL_ID SystemId, //in
MIL_INT64 ContextType, //in
MIL_INT64 SourceColorSpace, //in
MIL_ID ColorSpaceProfileId, //in
MIL_INT64 ControlFlag, //in
MIL_ID *ContextIdPtr //out
)
Description

This function allocates a color matching context or a relative color calibration context on the specified system. When you no longer require the context, release its memory using McolFree().

The context contains all the information necessary to perform McolMatch() (for color matching) or McolTransform() (for relative color calibration), including global context settings and color-samples. To add color-samples to a context, use McolDefine(). To adjust context and color-sample settings, use McolControl() and McolSetMethod().

MIL considers all color data to be the same as the context's color space, regardless of the color attributes of the data's buffer (MbufAllocColor()). For relative color calibration, color must be RGB (8-bit).

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
SystemId INQ

Specifies the system on which to allocate the context. This parameter should be set to one of the following values:

function map For specifying the system
CollapseValue Description
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.

Collapse MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().

ContextType

Specifies the type of context. This parameter must be set to one of the following values:

function map For specifying the context
CollapseValue Description
Collapse M_COLOR_CALIBRATION_RELATIVE

Specifies a context for transforming color data using relative color calibration (McolTransform()).

Collapse M_COLOR_MATCHING

Specifies a context for color matching (McolMatch()).

SourceColorSpace INQ

Specifies the source color space of the context. In general, all color data required for the color operation should be the same as the source color space. For example, if you specify an M_RGB source color space, color-samples (McolDefine()) and target or source images (McolMatch() or McolTransform()) should also typically be RGB.

This parameter should be set to one of the following values. Unless otherwise specified, values apply to both color matching and relative color calibration contexts.

function map For specifying the color space
CollapseValue Description
Collapse M_DEFAULT

Same as M_RGB.

Collapse M_CIELAB

Specifies a CIELAB (or LAB) color space. This is only for color matching contexts.

M_CIELAB is based on the color's luminance (L), its position between red and green (A), and its position between yellow and blue (B). Store the components of CIELAB data in color buffers as follows: the L component in band 0, the A component in band 1, and the B component in band 2.

(summarize)
Collapse M_HSL

Specifies an HSL color space. This is only for color matching contexts.

M_HSL is based on the color's hue (H), saturation (S), and luminance (L). Store the components of HSL data in color buffers as follows: the H component in band 0, the S component in band 1, and the L component in band 2.

(summarize)
Collapse M_RGB

Specifies an RGB color space.

M_RGB is based on the color's red (R), green (G), and blue (B) components. Store the components of RGB data in color buffers as follows: the R component in band 0, the G component in band 1, and the B component in band 2.

For color matching, when setting the color operation strategy with McolSetMethod(), you can also specify that, for internal calculations, you want to convert your RGB data to CIELAB before the match operation (McolMatch()).

(summarize)
ColorSpaceProfileId

Specifies the context's color space profile. This is the standard MIL uses to interpret the source color space data when performing an internal conversion between two distinct color spaces before the match operation (for example, specifying a CIELAB conversion mode with McolSetMethod() prior to calling McolMatch()). Unless you are performing such a conversion for the match, the color space profile standard has no effect.

This parameter must be set to the following value:

function map For specifying the context's color space profile
CollapseValue Description
Collapse M_DEFAULT

Specifies to use standard RGB specifications (sRGB), as defined by the International Electrotechnical Commission (IEC) Project Team 61966-2-1.

ControlFlag

Reserved for future expansion and must be set to M_DEFAULT.

ContextIdPtr

Specifies the address of the variable in which to write the context identifier. Since McolAlloc() also returns the context identifier, you can set this parameter to M_NULL.

Return value
The returned value is the context's identifier if the allocation is successful. If allocation fails, M_NULL is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib; milcolor.lib.
DLL Requires mil.dll; milcolor.dll.
DEFAULT HOST COLOR CALIBRATION RELATIVE COLOR MATCHING DEFAULT CIELAB HSL RGB DEFAULT