Synopsis
Allocate a child data buffer within a color parent buffer.
Format
MIL_ID MbufChildColor2d(ParentBufId, Band, OffX, OffY, SizeX, SizeY, BufIdPtr)
| MIL_ID ParentBufId; | Parent buffer identifier |
| long Band; | Index of the color band |
| long OffX; | X pixel offset relative to parent buffer |
| long OffY; | Y pixel offset relative to parent buffer |
| long SizeX; | X dimension |
| long SizeY; | Y dimension |
| 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 a two-dimensional region of one or all 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 used in the same circumstances as its parent buffer. A child buffer inherits its type and attributes from the parent buffer.
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 a band index from 0 to (number of bands of the parent buffer – 1) or to a predefined value: M_RED, M_GREEN, M_BLUE, or M_ALL_BAND. The specified color band should be valid in the parent buffer. When M_ALL_BAND is specified, the child buffer is allocated with the same number of bands as the parent buffer.
If the parent buffer is in a HLS (hue, luminance, and saturation) format, Band can be set to: M_HUE, M_LUMINANCE, M_SATURATION, or M_ALL_BAND.
The OffX parameter specifies the horizontal pixel offset of the child buffer in relation to the parent buffer starting coordinate. The offset must be within the width of the parent buffer.
The OffY parameter specifies the vertical pixel offset of the child buffer in relation to the parent buffer starting coordinate. The offset must be within the height of the parent buffer.
The SizeX parameter specifies the width of the child buffer, starting from the specified offset OffX.
The SizeY parameter specifies the height of the child buffer, starting from the specified offset OffY.
The BufIdPtr parameter specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChildColor2d 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.
Return 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 MbufCopyColor2d to extract or insert a specific color band from a color data buffer.
See also
MbufAllocColor, MbufChild1d, MbufChild2d, MbufChildColor, MbufCopyColor2d, MbufFree