The data buffer attribute indicates the buffer type and its intended usage. MIL uses this information to determine the most appropriate location in physical memory in which to allocate the buffer, and how to handle the buffer. A data buffer can be one of the following types:
M_IMAGE. Image buffers are used to store grabbed images.
M_LUT. Lookup table buffers are used to store lookup table data.
M_KERNEL. Kernel buffers define the filters used by convolution functions.
M_STRUCT_ELEMENT. Structuring element buffers are used to store the structuring element data for morphology functions.
M_ARRAY. Array buffers store array type data.
When allocating an image buffer (M_IMAGE), you must give more information about its intended usage. An image buffer can be any combination of the following:
A buffer that can be displayed (M_DISP).
A buffer that can be processed (M_PROC).
A buffer in which data can be grabbed (M_GRAB).
A buffer in which data is stored in a compressed format (M_COMPRESS).
For example, to allocate an image buffer that can be displayed and used for processing, its attribute should be given as:
M_IMAGE + M_DISP + M_PROC + M_GRAB.
The M_KERNEL and M_STRUCT_ELEMENT attributes are not required to work under MIL-Lite.
When a displayable buffer is allocated and selected for display (MbufAlloc...() with M_DISP, and then MdispSelect()), multiple buffers are maintained: one in Host memory for processing purposes, and other internal buffers in display or non-paged memory (maintained directly or using the normal Windows mechanisms) for display purposes (not necessarily the same size). When the Host buffer is modified, its associated internal buffers in display/non-paged memory are automatically updated. When displaying a buffer, both the buffer and the display should be allocated on the same system.
Buffers with the M_GRAB attribute are allocated in MIL non-paged (DMA) memory, which is physically contiguous. An advantage of non-paged memory is that a bus mastering device can write to it without the help of the Host CPU. If a system does not support grab buffers (for example, M_SYSTEM_HOST), you could still allocate a buffer on such a system in physically contiguous and non-paged memory by giving it an M_NON_PAGED attribute instead.
When grabbing a single frame into a displayable buffer, MIL grabs into the Host memory version of the buffer and then updates the display of the buffer. When grabbing continuously, the grab will typically bypass the specified buffer, and grab into an intermediate temporary display buffer (in display or Host non-paged memory) to minimize CPU usage and improve performance. Only the last frame grabbed is written into the selected buffer.
It is possible to force the internal representation of a data buffer using internal storage format specifiers, such as M_PACKED or M_PLANAR, which force the data buffer to be in a packed or planar format, respectively. Refer to MbufAllocColor() for a complete list of internal format specifiers.
If you try to use a data buffer in a situation that is not appropriate for its allocated attributes, an error message is generated and the operation is not performed. For example, if you try to display a buffer without an M_DISP attribute with MdispSelect(), an error message will be generated.
By default, all Matrox Imaging boards allocate buffers in shared Host memory instead of on-board memory. On these boards, on-board memory is typically limited in size and Host memory can be accessed much faster than on-board memory. Changing the default location for your buffer's allocation is typically done only when dealing with large buffers or limited amounts of memory. In most cases using the default memory storage locations will produce the best results. The following memory storage locations are available:
M_HOST_MEMORY. Stores the buffer in Host memory. Note that in all cases, M_HOST_MEMORY is the same as M_OFF_BOARD.
M_ON_BOARD. Stores the buffer in memory located on your Matrox Imaging board.
M_OFF_BOARD. Stores the buffer in memory located off your Matrox Imaging board.
M_MAPPABLE. Stores the buffer in non-paged memory that is not mapped to Host memory. The Host memory mapping can be controlled using MbufControl() with M_MAP.
M_VIDEO_MEMORY. Stores the buffer in display memory.
Using on-board memory can improve performance when all buffers are allocated and processed on-board. This is beneficial when using a GPU of your display board for processing (GPU system), or when using fast-processing memory.
There are three types of on-board memory available for some Matrox Imaging boards:
M_FAST_MEMORY. Available only on a limited number of boards. In the case of Matrox Radient, M_FAST_MEMORY forces the buffer in the QDR-II SRAM fast-processing memory.
M_SHARED. Available in all boards with an FPGA, this forces the buffer in memory that is mapped on the PCI bus. Note that shared memory is only available on-board.
Unshared memory. This is the default memory location for all boards with a FPGA. The buffer is stored in unmapped memory.
When dealing with many very large buffers that cannot all be mapped in Host memory at the same time, allocate the buffers as M_MAPPABLE so that they can be mapped and unmapped as needed. A mappable buffer is allocated in non-paged Host memory. By default the buffer will have a physical address, but not a Host address. Use MbufControl() with M_MAP to enable or disable the mapping.
There are two types of memory locations available to all Matrox Imaging boards:
M_PAGED. Forces the buffer into paged memory. Note that this value cannot be used with M_MAPPABLE.
M_NON_PAGED. Forces the buffer into non-paged memory.
Paging memory at allocation divides the available computer memory into small portions where the page is the smallest building block. Paging memory helps reduce the amount of external fragmentation and thus little memory is wasted. Use the MILConfig utility to set the amount of Non-paged memory available to your system. The rest of the memory is available for paging memory. Whenever possible, use the default settings for paged and non-paged memory.
If there is insufficient memory of the appropriate type to allocate a buffer with the specified attributes, the function generates an error and does not allocate the buffer.