Mapping a data buffer to user-allocated memory

---

• See also
User Guide:
Multiple systems
Reference:
MbufAlloc1d MbufControl MbufCreate2d MbufCreateColor MbufInquire
Availability
Available in MIL-Lite


Available in MIL
Previous
Next

Instead of allocating new memory to a buffer using MbufAlloc...(), you can create a buffer from the memory at a specified location, using MbufCreate2d() to create a monochrome data buffer and MbufCreateColor() to create a color data buffer. In these cases, MIL does not allocate any memory; it uses the memory that you provide.

When creating a buffer with MbufCreateColor(), you can pass an array of data pointers. For packed color buffers, you can pass an array of one pointer; for planar buffers, you can pass an array with the same number of pointers as the number of bands in the buffer. When creating a buffer with MbufCreate2d(), you can pass the address of the data. The address(es) can be either logical or physical. If you want to use the buffer for grabbing, the address(es) must be physical (grab buffers must be allocated in physically contiguous and always present memory, that is, non-paged).

The MbufCreate...() functions must be used with caution because, when using physical addresses, these functions provide direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.

You can use MbufInquire() with the M_HOST_ADDRESS or M_PHYSICAL_ADDRESS inquire type to determine the Host's logical address or the physical address of a buffer's data, respectively. Note that the physical address is not necessarily an address in Host memory. It could be an address in on-board memory. If an on-board buffer is mapped to the Host, you can use the MbufInquire() function with the M_HOST_ADDRESS inquire type to determine the Host address to which it is mapped.

Both MbufCreate2d() and MbufCreateColor() can also be used to create a buffer that maps to an already existing buffer. When mapping to an existing buffer, pass the MIL identifier of the buffer to MbufCreate2d() or to MbufCreateColor(). Note that on some Matrox frame grabbers, on-board buffers are allocated in unshared memory by default. In this case, MbufCreate2d() and MbufCreateColor() are not supported, unless creating the buffer on the same system.

There are several instances when memory mapping is useful. A particularly useful instance is when processing and displaying an interlaced grab in a time critical application. In this case, you could use a displayable image buffer to store and display the grabbed data. Then, to process each field as it is grabbed, you could use a buffer that is mapped to the odd field of the displayable image buffer (Buffer 1) and a buffer that is mapped to the even field (Buffer 2).

Create Buffers 1 and 2 as follows:

Buffer 1 (Odd field):

Buffer 2 (Even field):

In general, MIL automatically issues a display update after a displayed buffer has been modified. However, if a buffer selected on the display is modified using a mapped buffer, its display is not updated until you notify it of the change using the M_MODIFIED setting in MbufControl().

For another instance where creating buffers is useful, see the Multiple systems section of Chapter 2: Building an application.