Allocate a color data buffer.


MIL_ID MbufAllocColor(SystemId, SizeBand, SizeX, SizeY, DataType, Attribute, 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
MIL_ID *BufIdPtr; Storage location for buffer identifier


This function allocates a data buffer with multiple color bands on the specified system. This type of buffer allows the representation of color images (for example, RGB).

This function creates buffers that have a two-dimensional surface for each specified color band. You can use MbufAlloc1d and MbufAlloc2d to create single band one- or two-dimensional data buffers, respectively.

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 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).

Note, you cannot allocate a 1-bit (binary) LUT buffer.

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_PAGED Force the buffer in pageable memory.
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_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_RGB24+M_PLANAR Force 24-bit pixels in RGB 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 planar format.
M_YUV16+M_PACKED Force YUV16 packed (4:2:2) format.

The BufIdPtr parameter specifies the address of the variable in which the buffer identifier is to be written. Since the MbufAllocColor 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

MbufAlloc1d, MbufAlloc2d, MbufFree