McolAlloc

Board	Supported
Host System	Yes
V4L2	Yes
Clarity UHD	Yes
Concord PoE	No
GenTL	Yes
GevIQ	Yes
GigE Vision	Yes
Indio	No
Iris GTX	Yes
Radient eV-CL	Yes
Rapixo CL	Yes
Rapixo CoF	Yes
Rapixo CXP	Yes
USB3 Vision	Yes

Allocate a color matching context or a relative color calibration context.

Syntax

AIL_ID McolAlloc(
    AIL_ID    SysId,                //in
    AIL_INT64 ContextType,          //in
    AIL_INT64 SourceColorSpace,     //in
    AIL_ID    ColorSpaceProfileId,  //in
    AIL_INT64 ControlFlag,          //in
    AIL_ID *  ContextIdPtr          //out
)

Description

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.

Aurora Imaging Library 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).

When the color matching context or relative color calibration context is no longer required, release it usingMcolFreeunless M_UNIQUE_ID was specified during allocation; if M_UNIQUE_ID was specified, the smart identifier manages the context's lifetime and you must not manually free it.

Parameters

SysId (in, AIL_ID)

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

For specifying the system

Value	Description
M_DEFAULT_HOST	Specifies the default Host system of the current Aurora Imaging Library application.
System identifier	Specifies a valid system identifier, previously allocated using MsysAlloc.

ContextType (in, AIL_INT64)

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

For specifying the context

Value	Description
M_COLOR_CALIBRATION_RELATIVE	Allocates a relative color calibration context for use with McolTransform.
M_COLOR_MATCHING	Allocates a color matching context for use with McolMatch.

SourceColorSpace (in, AIL_INT64)

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.

For specifying the color space

Value	Description
M_DEFAULT	Same as M_RGB.
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. | | 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. | | 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). |

ColorSpaceProfileId (in, AIL_ID)

Specifies the context's color space profile. This is the standard Aurora Imaging Library 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 McolSetMethodprior to calling McolMatch). Unless you are performing such a conversion for the match, the color space profile standard has no effect.

For specifying the context's color space profile

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

ControlFlag (in, AIL_INT64)

Reserved for future expansion and must be set to M_DEFAULT.

ContextIdPtr *(out, AIL_ID)

Specifies the address of the variable in which to write the color matching context or relative calibration context identifier or specifies the data type that the function should use to return the color matching context or relative calibration context identifier.

For retrieving the identifier or specifying how to return it

Value	Description
M_NULL	Specifies that you will use this function's return value to obtain the identifier of the allocated color matching context or relative

                          color calibration context; in this case, a standard Aurora Imaging Library identifier of type _AIL_ID_ is returned. |

| M_UNIQUE_ID | Specifies that you will use this function's return value to obtain the identifier of the allocated color matching context or relative color calibration context; in this case, an Aurora Imaging Library smart identifier of type _AIL_UNIQUE_COL_ID_is returned instead of a standard Aurora Imaging Library identifier.This setting is only available when using C++11 (or later).An Aurora Imaging Library smart identifier manages the lifespan of the Aurora Imaging Library object it owns (similar to a std::unique_ptr). Note, you can use an Aurora Imaging Library smart identifier as though it were a standard Aurora Imaging Library identifier, except that you cannot use it to manually free the color matching context or relative color calibration context (it is freed automatically). For more information, see Aurora Imaging Library smart identifiers. | | Address in which to write the calibration context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated relative color calibration context.

If allocation fails, M_NULL is written as the identifier. | | Address in which to write the color matching context identifier | Specifies the address of an AIL_ID in which to write the identifier of the allocated color matching context.

If allocation fails, M_NULL is written as the identifier. |

Return Value

Type: AIL_ID

The returned value is the color matching context or relative calibration context identifier either as a standard identifier (AIL_ID) or a smart identifier (AIL_UNIQUE_COL_ID). If allocation fails, M_NULL is returned (or nullptr ifM_UNIQUE_ID was specified).