Synopsis
Allocate a child buffer from a specific region of the parent buffer.
Format
MIL_ID MbufChild2d(ParentBufId, OffX, OffY, SizeX, SizeY, BufIdPtr)
| MIL_ID ParentBufId; | Parent buffer identifier |
| long OffX; | X pixel offset relative to the parent buffer |
| long OffY; | Y pixel offset relative to the parent buffer |
| long SizeX; | Child buffer width |
| long SizeY; | Child buffer height |
| MIL_ID *BufIdPtr; | Storage location for child buffer identifier |
Description
This function allocates a child buffer from a two-dimensional region of all bands of the specified, previously allocated data buffer. The child buffer is not allocated its own memory space; it remains part of the parent buffer. 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, 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 from the specified region in each color band. To allocate a child region in one specific band, or specifically in all bands, use MbufChildColor2d instead of MbufChild2d.
When this buffer is no longer required, it can be released, using MbufFree.
The ParentBufId parameter specifies the identifier of the parent buffer.
The OffX and OffY parameters specify the horizontal and vertical pixel offsets of the top-left pixel of the child buffer in relation to the top-left parent buffer coordinate. The given offsets must be within the width and height of the parent buffer.
The SizeX and SizeY parameters specify the width and height of the child buffer starting from the specified offsets OffX and OffY, respectively.
The BufIdPtr parameter specifies the address of the variable in which the child buffer identifier is to be written. Since the MbufChild2d 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.
See also