Skip to main content

MbufChildColor2d

Allocate a child data buffer within a parent buffer.

Syntax​

AIL_ID MbufChildColor2d(
    AIL_ID   ParentBufId,  //in
    AIL_INT  Band,         //in
    AIL_INT  OffX,         //in
    AIL_INT  OffY,         //in
    AIL_INT  SizeX,        //in
    AIL_INT  SizeY,        //in
    AIL_ID * BufIdPtr      //out
)

Description​

This function allocates a child data buffer within the specified, previously allocated, parent data buffer. It selects a two-dimensional region in one or all of the bands of the parent data buffer and allocates the region as a child of that buffer.

The child buffer is not allocated in its own memory space; it remains part of the parent buffer. Therefore, any modification to the child buffer affects the parent and vice versa. Note, a parent buffer can have several child buffers.

A child buffer is considered a data buffer in its own right. It can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.

If a child buffer is allocated using a parent buffer with an ROI, set using MbufSetRegion, the child buffer inherits the parent buffer's ROI. You can also set an ROI in a child buffer directly. Note that the ROI of the child buffer is only accessible using the child buffer's Aurora Imaging Library identifier.

After allocating the child buffer, you should check if the operation was successful, using MappGetError or by verifying that the child buffer identifier returned is not M_NULL (or nullptr ifM_UNIQUE_ID was specified).

When the child buffer is no longer required, release it usingMbufFreeunless M_UNIQUE_ID was specified during allocation; if M_UNIQUE_ID was specified, the smart identifier manages the child buffer's lifetime and you must not manually free it.

Parameters​

ParentBufId (in, AIL_ID)​

Specifies the identifier of the parent buffer.

Band (in, AIL_INT)​

Specifies the band of the parent data buffer from which to allocate the child data buffer. The specified band should be valid in the parent buffer.

For specifying the band

ValueDescription
M_ALL_BANDSSpecifies all bands (for multi-band parent buffers). That is, M_ALL_BANDS allocates a child buffer with the same number of bands as the parent buffer.
M_BLUESpecifies the blue color band (for RGB parent buffers).
M_GREENSpecifies the green color band (for RGB parent buffers).
M_HUESpecifies the hue band (for HSL and HSV parent buffers).
M_LUMINANCESpecifies the luminance band (for HSL parent buffers).
M_REDSpecifies the red color band (for RGB parent buffers).
M_SATURATIONSpecifies the saturation band (for HSL and HSV parent buffers).
M_USpecifies the U band (for YUV parent buffers). Note that the dimensions of the child buffer must not exceed the dimensions of the U band of the parent.
M_VSpecifies the V band (for YUV and HSV parent buffers). Note that the dimensions of the child buffer must not exceed the dimensions of the V band of the parent.
M_YSpecifies the Y band (for YUV parent buffers).
0 <= Value < #bandsSpecifies the index of the band to use.

The relationship between index value and band for RGB, HSL, HSV, and YUV buffers is the following:

0Corresponds to the red band (for RGB parent buffers), the hue band (for HSL and HSV parent buffers), and the Y band (for YUV parent buffers).
1Corresponds to the green band (for RGB parent buffers), the saturation band (for HSL and HSV parent buffers), and the U band (for YUV parent buffers).
2Corresponds to the blue band (for RGB parent buffers), the luminance band (for HSL parent buffers), and the V band (for YUV and HSV parent buffers).

OffX (in, AIL_INT)​

Specifies the horizontal offset of the child buffer, relative to the parent buffer's top-left pixel. The offset must be within the width of the parent buffer.

OffY (in, AIL_INT)​

Specifies the vertical offset of the child buffer, relative to the parent buffer's top-left pixel. The offset must be within the height of the parent buffer.

SizeX (in, AIL_INT)​

Specifies the width of the child buffer.

SizeY (in, AIL_INT)​

Specifies the height of the child buffer.

BufIdPtr *(out, AIL_ID)​

Specifies the address of the variable in which to write the child buffer identifier or specifies the data type that the function should use to return the child buffer identifier.

For retrieving the identifier or specifying how to return it

ValueDescription
M_NULLSpecifies that you will use this function's return value to obtain the identifier of the allocated child buffer; in this case, a standard Aurora Imaging Library identifier of type AIL_ID is returned.
M_UNIQUE_IDSpecifies that you will use this function's return value to obtain the identifier of the allocated child buffer; in this case, an Aurora Imaging Library smart identifier of type _AIL_UNIQUE_BUF_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 child buffer (it is freed automatically). For more information, see Aurora Imaging Library smart identifiers.
Address in which to write the identifierSpecifies the address of an AIL_ID in which to write the identifier of the allocated child buffer.

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

Return Value​

Type: AIL_ID

The returned value is the child buffer identifier either as a standard identifier (AIL_ID) or a smart identifier (AIL_UNIQUE_BUF_ID). If allocation fails, M_NULL is returned (or nullptr ifM_UNIQUE_ID was specified).

Copyright © 2026 Zebra Technologies.