Synopsis
Create a color data buffer.
Format
MIL_ID MbufCreateColor(SystemId, SizeBand, SizeX, SizeY, DataType, Attribute, ControlFlag, Pitch, ArrayOfDataPtr, BufIdPtr)
| MIL_ID SystemId; | System identifier |
| long SizeBand; | Number of color bands |
| long SizeX; | X dimension |
| long SizeY; | Y dimension |
| long DataType; | Pixel depth and range |
| long Attribute; | Buffer attributes |
| long ControlFlag; | Creation control flag |
| long Pitch; | Value of pitch, if necessary |
| void *ArrayOfDataPtr; | Array of data buffer pointers |
| MIL_ID *BufIdPtr; | Storage location for buffer identifier |
Description
This function creates a color data buffer that maps to a user-specified data array and associates it with a specific MIL system. This function should be used with great care. It is generally better to leave buffer allocation, data loading, and memory control to MIL (MbufAllocColor, MbufGetColor, MbufPutColor), since MIL might require special memory attributes (such as non-paged memory) or alignment in order to associate the buffer with a particular target system. MbufInquire can be used to get the pointer to a MIL allocated buffer.
The appropriate memory must be allocated by the user before calling MbufCreateColor and freed when no longer required, after calling MbufFree.
The SystemId parameter specifies the MIL system with which the buffer will be associated. 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 with which to associate the buffer (it can be the Host system or any already allocated system).
The SizeBand parameter specifies the number of (xy) surfaces (also called color bands) that the buffer should have in order to represent the color components of an object. When acquiring or processing monochrome images, the buffer requires only one color band. For RGB color images, it requires three color bands. The possible range for this parameter is 1 to n. However, there are generally either 1 or 3 bands.
The SizeX and SizeY parameters specify the buffer width and height, respectively, in the units appropriate for the selected buffer attribute. For example, if the buffer has an image buffer attribute, width and height are specified in pixels.
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. This parameter should be set to M_LUT or to M_IMAGE + specifier. The specifier can be one or more of the following:
Usage specifiers:
| M_DISP | An image buffer that can be displayed. |
| M_GRAB | An image buffer in which to grab data from input devices. |
| M_PROC | An image buffer that can be processed. |
For example, to allocate an image buffer that can be processed and displayed, you should set the Attribute parameter to
M_IMAGE + M_PROC + M_DISP.
Board-dependent location specifiers:
| M_ON_BOARD | Force the buffer in the system memory. |
| M_OFF_BOARD | Force the buffer in the Host memory. |
| M_OVR | Force the buffer in the overlay display surface. |
| M_NON_PAGED | Force the buffer in non-pageable memory. |
| M_SINGLE | Force a unique copy of the buffer. |
Board-dependent internal storage format specifiers:
| M_DDRAW | Force the buffer to be a DDraw surface. |
| M_DIB | Force the buffer to be a DIB buffer. |
| M_FLIP | Force the buffer to be top down (DIB). |
| M_NO_FLIP | Force the buffer to be top up. |
| M_PACKED | Force the buffer bands to be packed. |
| M_PLANAR | Force the buffer bands to be planar. |
| M_RGB15+M_PACKED | Force 16-bit pixels in XRGB 1555 format. |
| M_RGB16+M_PACKED | Force 16-bit pixels in RGB 565 format. |
| M_BGR24+M_PACKED | Force 24-bit pixels in BGR 888 format. |
| M_BGR24+M_PLANAR | Force 24-bit pixels in BGR 888 planar format. |
| M_BGR32+M_PACKED | Force 32-bit pixels in BGRX 8888 format. |
| M_YUV9+M_PLANAR | Force YUV9 planar format. |
| M_YUV12+M_PLANAR | Force YUV12 planar format. |
| M_YUV16+M_PLANAR | Force YUV16 planat format. |
| M_YUV16+M_PACKED | Force YUV16 packed (4:2:2) format. |
The ControlFlag parameter specifies the physical nature of the buffer. It can be set to one of the following:
| ControlFlag | Description |
| M_DEFAULT | Same as M_HOST_ADDRESS+M_PITCH. The pitch is the width (size X) of the buffer. |
| M_HOST_ADDRESS+M_PITCH | The data pointer is the Host CPU address of the data buffer. The pitch is in pixels. |
| M_HOST_ADDRESS+M_PITCH_BYTE | The data pointer is the Host CPU address. The pitch is in bytes. |
| M_PHYSICAL_ADDRESS+M_PITCH | The data pointer is the physical address of the data buffer in memory. The pitch is in pixels. |
| M_PHYSICAL_ADDRESS+M_PITCH_BYTE | The data pointer is the physical address of the data buffer in memory. The pitch is in bytes. |
The Pitch parameter specifies the pitch in pixels or bytes (as determined by ControlFlag) or M_DEFAULT. The pitch is the length of the buffer’s memory (not data) line.
The ArrayOfDataPtr parameter is the address of an array of pointers. These pointers are the addresses of the data buffers to which to map the created MIL buffer. For a planar buffer, one pointer per band must be provided. For a packed buffer, a pointer to the packed data must be provided.
The BufIdPtr parameter specifies the address of the variable in which the buffer identifier is to be written. Since the MbufCreateColor 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.
See also