Synopsis
Allocate a child data buffer within a color parent buffer.
Format
MIL_ID MbufChildColor(ParentBufId, Band, BufIdPtr)
| MIL_ID ParentBufId; | Parent buffer identifier |
| long Band; | Index of the color band |
| MIL_ID *BufIdPtr; | Storage location for child buffer identifier |
Description
This function allocates a child data buffer within the specified, previously allocated color parent data buffer. It selects one of the color bands of the data buffer to be allocated as a child of that buffer.
The child buffer is not allocated 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 color child buffer is considered a data buffer in its own right. It can be any color band of its parent buffer, and can be used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.
Note that when the parent buffer is multi-band, this function allocates a multi-band child buffer. The child is created in each color band. To allocate a child in one specific band, or specifically in all bands, use MbufChildColor2d instead of MbufChildColor.
When this buffer is no longer required, release it, using MbufFree.
The ParentBufId parameter specifies the identifier of the parent buffer.
The Band parameter specifies the index of the color band of the parent data buffer on which to allocate the child data buffer. This parameter can be set to the band index from 0 to (number of bands of the parent buffer – 1) or to a predefined value: M_RED, M_GREEN, M_BLUE. The specified color band should be valid in the parent buffer.
If the parent buffer is in a HLS (hue, luminance, and saturation) format, the band can be set to: M_HUE, M_LUMINANCE, or M_SATURATION.
The BufIdPtr parameter specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChildColor function also returns the child buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.
Returned value
The returned value is the child buffer identifier. If allocation fails, M_NULL is returned.
Status
Current limitations:
- Some hardware systems do not support child buffers in the band dimension. Use MbufCopyColor to extract or insert a specific color band from a color data buffer.
See also