| Customize Help

Source and destination image buffers


Before using a PU, you must specify the appropriate source and destination image buffers for the command. Some PUs do not produce image data and, therefore, they do not require destination image buffers. To specify the source and destination buffers, use MfpgaSetSource() and MfpgaSetDestination(), respectively. These functions require that you pass the handle of the buffer and not its identifier. To get the handle of the buffer, you must call MfuncInquire() with M_BUFFER_INFO.

All PUs have documented limitations on the types of buffers from which they can receive data using their stream input port(s). They also have documented limitations on the buffers to which they can transmit data from their stream output port(s). You must keep these limitations in mind when allocating your buffer(s). MfpgaSetDestination() and MfpgaSetSource() will not automatically convert the buffers so that they are appropriate for the operation. For more information, refer to the PU documentation available in the Matrox FPGA Components Reference help file.

Note that processing can typically be performed by the Processing FPGA if the source buffer is allocated on-board, the destination buffer is allocated in non-paged Host memory or on-board, and the FPGA configuration includes a path from the PU(s) to the memory banks in which the specified source and destination buffers are located. In the case of Matrox imaging boards with on-board processors, destination buffers cannot be in Host memory; only on-board destination buffers are supported.

When allocating your image buffers for a Processing FPGA operation (MbufAlloc...()), you can have MIL automatically select the optimal memory location, which is accessible to the Processing FPGA, for the image buffers. To do so, add M_FPGA_ACCESSIBLE to the other required attributes (for example, M_PROC + M_GRAB). Note that although the buffers will be allocated in memory accessible to the Processing FPGA, you must ensure that a path between the PU and the buffers is available.

To explicitly allocate your buffer in a specific memory location that is accessible to the Processing FPGA, you can add one of the following attributes to M_FPGA_ACCESSIBLE. Note that by explicitly allocating your buffer in a specific memory location, you can make your code less portable to other boards with a different number of memory banks or Host memory restrictions. However, you might obtain some performance benefits.

  • M_ON_BOARD. Explicitly allocates the buffer in on-board memory.

  • M_HOST_MEMORY. Explicitly allocates the buffer in Host memory.

  • M_MEMORY_BANK_n. Explicitly specifies the on-board memory bank in which to allocate your image buffer. The variable n specifies the rank of the on-board memory bank in which your image must be allocated.

Note that M_MEMORY_BANK_n is not supported on Matrox imaging boards with on-board processors; you must use other buffer attributes to force the allocation of the buffer into a specific memory bank (for example, M_FPGA_ACCESSIBLE + M_FAST_MEMORY).

When allocating your image buffers, special care should be taken regarding the buffer width because certain Matrox boards have limitations on the width of allocated buffers. For instance on Matrox Solios, the width of buffers allocated in acquisition memory must be a multiple of 64 bytes and the width of destination buffers on the Host must be a multiple of 8 bytes.

Note that in general, child buffers are not supported; only color-band child buffers are supported.

If you want to route the stream output of one PU to the stream input port of another PU, you will have to cascade the PUs using the appropriate functions. For more information on these functions, see the Cascaded and parallel processing section later in this chapter.