Synopsis
Allocate a 1D data buffer.
Format
MIL_ID MbufAlloc1d(SystemId, SizeX, DataType, Attribute, BufIdPtr)
| MIL_ID SystemId; | System identifier |
| long SizeX; | X dimension |
| long DataType; | Pixel depth and range |
| long Attribute; | Buffer attribute |
| MIL_ID *BufIdPtr; | Storage location for buffer identifier |
Description
This function allocates a one-dimensional data buffer on the specified system.
After allocating a buffer, we recommend that you check if the operation was successful, using MappGetError or by verifying that the buffer identifier returned is not M_NULL. When a buffer is no longer required, release it, using MbufFree.
The SystemId parameter specifies the system on which the buffer will be allocated. This parameter must be set to a valid system identifier, M_DEFAULT_HOST or M_DEFAULT. To use the default Host system of the current MIL application, specify M_DEFAULT_HOST. If you specify M_DEFAULT, MIL will select the most appropriate system on which to allocate the buffer (it can be the Host system or any already allocated system).
The SizeX parameter specifies the buffer width in the units appropriate for the selected type of buffer attributes. For example, if the buffer has a LUT buffer attribute, specify the number of LUT entries to allocate.
The DataType parameter specifies a combination of two values: the depth and range of the data. Express the depth in bits and give the data range as one of the following:
| Data Type | Description | Depth (in bits) |
| M_SIGNED | Signed data | 8, 16, or 32 |
| M_UNSIGNED | Unsigned data (default) | 1, 8, 16, or 32 |
| M_FLOAT | Floating point data | 32 |
For example, when allocating a 8-bit unsigned buffer, you would set the DataType parameter to (8 + M_UNSIGNED).
The Attribute parameter defines the buffer usage. The system uses this information to determine where to allocate the buffer in physical memory. For example, to allocate a LUT buffer, you should set the Attribute parameter to M_LUT. Set this parameter to one of the following:
| Attribute | Description |
| M_IMAGE | Image buffer. |
| M_LUT | Look up table. |
| M_KERNEL | Convolution kernel for convolution functions. |
| M_STRUCT_ELEMENT | Structuring element for morphology functions. |
When allocating an image buffer (M_IMAGE), you must also specify the intended purpose of this buffer by combining M_IMAGE with one or more of the following:
| Purpose | Description |
| M_DISP | An image buffer that can be displayed. |
| M_GRAB | An image buffer in which to grab data. |
| M_PROC | An image buffer that can be processed. |
The BufIdPtr parameter specifies the address of the variable in which the buffer identifier is to be written. Since the MbufAlloc1d function also returns the 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 buffer identifier. If allocation fails, M_NULL is returned.
Status
Current limitation:
- For M_KERNEL and M_LUT data buffers, the data type must be 8, 16, or 32-bit integer or floating point.
- For M_STRUCT_ELEMENT data buffers, the data type must be 32-bit integer or floating point.
See also