MIL_ID SystemId, | //in |
MIL_INT SizeX, | //in |
MIL_INT SizeY, | //in |
MIL_INT Type, | //in |
MIL_INT64 Attribute, | //in |
MIL_INT64 ControlFlag, | //in |
MIL_INT Pitch, | //in |
const void *DataPtr, | //in |
MIL_ID *BufIdPtr | //out |
This function creates a two-dimensional data buffer that maps to a user-specified data array, or another existing buffer, and associates it with a specific MIL system.
This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.
It is generally better to leave buffer allocation, data loading, and memory control to MIL (MbufAlloc2d(), MbufGet2d(), MbufPut2d()), since MIL might require special memory attributes (such as non-paged memory) or alignment to associate the buffer with a particular target system.
You must allocate the appropriate memory before calling MbufCreate2d() and you must free the created buffer when no longer required, using MbufFree() before freeing the memory. Using MbufFree() on a buffer created with MbufCreate2d() will free the internal structure required for a mapped buffer, but it will not free the memory used. MbufInquire() can be used to get the pointer to the data of a MIL allocated buffer.
Note that to map a buffer to on-board memory with a different system, the on-board memory must be in shared memory, unless the created buffer is created on the same system. See your MIL Hardware-specific Notes for more information regarding shared memory.
Specifies the MIL system on which to create the buffer.
This parameter should be set to one of the following values:
For specifying the MIL
system
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_DEFAULT_HOST |
Specifies the default Host system of the current MIL application. |
||||||||||||||||||||||||||||||||||||||
MIL system identifier |
Specifies a valid system identifier, previously allocated using MsysAlloc(). |
Specifies the buffer width.
When dealing with monochrome (1-band) buffers, the buffer width must be a multiple of 4.
For specifying the buffer
width
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_DEFAULT |
Specifies that the buffer width is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID. |
||||||||||||||||||||||||||||||||||||||
Value |
Specifies buffer width. (more details...) |
Specifies the buffer height.
For specifying the buffer
height
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_DEFAULT |
Specifies that the buffer height is identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID. |
||||||||||||||||||||||||||||||||||||||
Value |
Specifies the buffer height. (more details...) |
Specifies a combination of two values: data type and data depth per band. Specify the depth of the buffer per band as one of the following:
For specifying the data depth of the
buffer
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_DEFAULT |
Specifies that the buffer data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID. |
||||||||||||||||||||||||||||||||||||||
1 + |
Specifies a 1-bit (packed binary) buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
8 + |
Specifies an 8-bit buffer. |
||||||||||||||||||||||||||||||||||||||
16 + |
Specifies a 16-bit buffer. |
||||||||||||||||||||||||||||||||||||||
32 + |
Specifies a 32-bit buffer. |
You can add one of the following values to the above-mentioned values to set the data type.
Supported data types depend on the specified depth.
For specifying the data type of the
buffer
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
||||||||||||||||||||||||||||||||||||||
M_FLOAT |
Specifies that the type of data is floating-point. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_SIGNED |
Specifies that the type of data is signed. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_UNSIGNED |
Specifies that the type of data is unsigned. (more details...) |
Specifies the buffer usage. This allows you to specify the type of buffer, intended purpose, compression type, storage format, data direction, location, internal storage format, memory type, and overscan region of the created buffer; all of which provides additional information for other MIL functions.
This function should be used with caution because, when using physical addresses, it provides direct access to any of your computer's memory mapped devices; when using logical addresses, memory protection errors could result.
This parameter should be set to one of the values below.
For specifying the buffer
usage
|
|||||||||||||||||||||||||||||||||||||||
Value |
Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_ARRAY + |
Specifies a buffer to store array type data. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_IMAGE + |
Specifies a buffer to store image data. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
Only single-band (monochrome) buffers with a depth of 8 or 16 bits can have an M_IMAGE attribute. |
† | d | |||||||||||||||||||||||||||||||||||||
M_KERNEL + |
[For
essential MIL-Lite information, see remarks ]
Specifies a kernel buffer to store a custom filter for convolution functions. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_LUT + |
Specifies a buffer to store lookup table data. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_STRUCT_ELEMENT + |
[For
essential MIL-Lite information, see remarks ]
Specifies a buffer to store structuring element data for morphology functions. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s |
You must add one or more of the following values to the above-mentioned value to set the intended purpose of this buffer.
Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.
For specifying the intended purpose of
the image buffer
|
|||||||||||||||||||||||||||||||||||||||
Combination value |
Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_COMPRESS + |
[For
essential MIL-Lite information, see remarks ]
Specifies an image buffer that can hold compressed data. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_DISP |
Specifies an image buffer that can be displayed. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
Single-band display buffers with a depth greater than 16 bits cannot be allocated. Three-band display buffers can only be allocated with 8 bits per band. |
† | f | |||||||||||||||||||||||||||||||||||||
M_GRAB |
Specifies an image buffer in which to grab data. (more details...) |
† | a | b | c | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | |||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
Only single-band (monochrome) buffers with a depth of 8 or 16 bits can have an M_GRAB attribute. |
† | c | j | k | l | m | o | p | q | r | s | ||||||||||||||||||||||||||||
Only single-band (monochrome) buffers with a depth of 8 bits can have an M_GRAB attribute. |
† | b | f | g | h | n | |||||||||||||||||||||||||||||||||
M_PROC + |
Specifies an image buffer that can be processed. |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s |
You can add the following value to the above-mentioned value to set the allocation of an overscan region.
Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.
For allocating an overscan
region
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
||||||||||||||||||||||||||||||||||||||
M_ALLOCATION_OVERSCAN |
Specifies that the buffer is allocated with an overscan region. (more details...) |
You can add one of the following values to the above-mentioned value to set the compression type.
The image buffer's data depth dictates which compression type can be selected.
Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.
For specifying the compression
type INQ
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
||||||||||||||||||||||||||||||||||||||
M_JPEG2000_LOSSLESS |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG2000 lossless data. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_JPEG2000_LOSSY |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG2000 lossy data. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_JPEG_LOSSLESS |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG lossless data. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_JPEG_LOSSLESS_INTERLACED |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG lossless data in separate fields. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_JPEG_LOSSY |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG lossy data. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_JPEG_LOSSY_INTERLACED |
[For
essential MIL-Lite information, see remarks ]
Specifies that the buffer will be used to hold JPEG lossy data in separate fields. (more details...) |
You can add one of the following values to the above-mentioned value to set a storage format and a location specifier.
MIL will interpret the created buffer according to the specified intended usage attribute. The source buffer's actual storage format can differ. If a specific internal format is required, it should be specified.
For specifying a storage format and a
location specifier
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_DIB |
[This is
only applicable to Windows]
Specifies that the buffer to be a DIB buffer. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_DIRECTX |
[This is
only applicable to Windows]
Specifies that the buffer to be a DirectX surface. |
† | a | b | c | d | e | g | h | i | j | k | l | m | n | o | p | q | r | s | |||||||||||||||||||
M_GDI |
Specifies that the buffer to be compatible with GDI. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
M_LINUX_MXIMAGE |
[This is
only applicable to Linux]
Specifies that the buffer to be an X11 Ximage. |
† | a | b | c | d | e | g | h | i | j | k | l | m | n | o | p | q | r | s |
You can add the following value to the above-mentioned values to specify a location for a buffer that is FPGA accessible.
Note that the following value cannot be used with M_COMPRESS, M_DIB, M_DIRECTX, M_GDI, or M_LINUX_MXIMAGE.
For specifying that the buffer is
FPGA accessible
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_FPGA_ACCESSIBLE + |
Specifies that the buffer is in a bank of memory that is accessible from the Processing FPGA. (more details...) |
† | j | l | m | p | r |
You can add one of the following values to the above-mentioned values to set a location for a buffer.
For specifying a location for a
buffer
|
|||||||||||||||||||||||||||||||||||||||
Combination value |
Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_HOST_MEMORY |
Specifies that the buffer is in Host memory. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
This is a MIL system specific default value. | † | a | b | c | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||||
M_MAPPABLE |
Specifies that the buffer is in non-paged memory that can be set in the address space of the process (Host memory). (more details...) |
† | a | b | c | e | f | g | h | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||||
M_OFF_BOARD |
Specifies that the buffer is not in on-board memory. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
To ensure that an M_OFF_BOARD buffer can be used by the bus master transfer section of the board, the buffer must be created in non-paged memory (M_OFF_BOARD + M_NON_PAGED or M_HOST_MEMORY + M_NON_PAGED). |
† | f | g | h | i | j | l | m | n | p | r | ||||||||||||||||||||||||||||
M_ON_BOARD + |
Specifies that the buffer in on-board memory. (more details...) |
† | f | g | h | i | j | k | l | m | n | p | q | r | |||||||||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
By default, all on-board buffers are allocated in memory that is not mapped on the PCI bus. This unshared memory cannot be accessed by the Host or any system other than the one on which it was allocated. See combination values below (M_SHARED) to change this default behavior. |
† | j | k | l | m | p | q | r | |||||||||||||||||||||||||||||||
This is only available for grab buffers (M_GRAB). |
† | f | |||||||||||||||||||||||||||||||||||||
This is only available for image buffers (M_IMAGE). |
† | g | h | i | k | n | |||||||||||||||||||||||||||||||||
This is only available for image (M_IMAGE) and LUT buffers (M_LUT). |
† | j | l | m | p | q | r | ||||||||||||||||||||||||||||||||
M_VIDEO_MEMORY |
[This is
only applicable to Windows]
Specifies that the buffer is in (off-screen) display memory of your graphics controller. (more details...) |
† | a | b | c | d | e | f | g | h | i | j | k | l | m | n | o | p | q | r | s | ||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
Buffers cannot be created in video memory when any of the following attributes are used: M_COMPRESS, M_DIB, M_GDI, M_NON_PAGED, or M_PHYSICAL_ADDRESS. |
† | d | |||||||||||||||||||||||||||||||||||||
This is a MIL system specific default value. | † | d |
You can add one of the following values to the above-mentioned values to specify a specific bank of on-board memory.
Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.
For specifying a specific
on-board memory bank
|
|||||||||||||||||||||||||||||||||||||||
Combination value |
Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_MEMORY_BANK_0 |
Specifies that the buffer is in memory bank 0 of memory that is accessible from the Processing FPGA. (more details...) |
† | j | k | l | m | p | q | r | ||||||||||||||||||||||||||||||
M_MEMORY_BANK_1 |
Specifies that the buffer is in memory bank 1 of memory that is accessible from the Processing FPGA. (more details...) |
† | j | l | m | p | r | ||||||||||||||||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
Memory bank 1 is SRAM memory. This is the default memory bank for an on-board buffer created with the M_PROC + M_FAST_MEMORY attribute. |
† | j | p | r | |||||||||||||||||||||||||||||||||||
M_MEMORY_BANK_2 |
Specifies that the buffer is in memory bank 2 of memory that is accessible from the Processing FPGA. (more details...) |
† | l | m |
You can add one of the following values to the above-mentioned values to set a location in a specific type of memory.
For specifying a location in a
specific type of memory
|
|||||||||||||||||||||||||||||||||||||||
Combination value |
Description
|
MIL system-specific tooltip (†) |
|||||||||||||||||||||||||||||||||||||
M_FAST_MEMORY |
Specifies that the buffer is created in the fastest memory available. (more details...) |
† | j | l | m | p | r | ||||||||||||||||||||||||||||||||
MIL system specific | |||||||||||||||||||||||||||||||||||||||
For Matrox Solios eA/XA and eCL/XCL, the fasted memory available is the SRAM. If SRAM is not present on your Matrox Solios, SDRAM will be used instead. |
† | l | m | ||||||||||||||||||||||||||||||||||||
M_SHARED |
Specifies that the buffer is in shared processing memory. (more details...) |
† | j | k | l | m | p | q | r |
You can add one of the following values to the above-mentioned values to set the attribute of the specified physical memory type.
Note that this value must not conflict with the attribute of the specified physical memory to which it is mapped. Such a conflict can result in errors that MIL cannot catch.
For specifying the attribute of
the specified physical memory type
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
||||||||||||||||||||||||||||||||||||||
M_NON_PAGED |
Specifies that the buffer is in MIL-reserved, non-pageable memory. |
||||||||||||||||||||||||||||||||||||||
M_PAGED |
Specifies that the buffer is in pageable memory. |
Specifies the physical nature of the buffer. This parameter can be set to one of the values below.
For specifying the physical
nature of the buffer
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_HOST_ADDRESS + |
Specifies that DataPtr is a logical address that points to the data. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_MIL_ID + |
Specifies that the new buffer maps to an existing source buffer. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_PHYSICAL_ADDRESS + |
Specifies that DataPtr is a physical address that points to the data. (more details...) |
You must add one of the following values to the above-mentioned values to set how the pitch is measured.
For specifying how the pitch is
measured
|
|||||||||||||||||||||||||||||||||||||||
Combination value | Description
|
||||||||||||||||||||||||||||||||||||||
M_PITCH |
Specifies that the pitch is in pixels. (more details...) |
||||||||||||||||||||||||||||||||||||||
M_PITCH_BYTE |
Specifies that the pitch is in bytes. |
Specifies the size of the pitch. The pitch is the number of pixels or bytes (as specified by the ControlFlag parameter) between the start of any two adjacent rows of the buffer. The actual length of a row in the buffer, in physical memory, might be different from the value of the SizeX parameter (for example, due to use of buffer overscan).
Note that your code should not make assumptions about the actual pitch of the source memory. If the memory was allocated using an MbufAlloc...() function, use MbufInquire() with M_PITCH or M_PITCH_BYTE to establish the required pitch.
For specifying the size of the
pitch
|
|||||||||||||||||||||||||||||||||||||||
Value | Description
|
||||||||||||||||||||||||||||||||||||||
M_DEFAULT |
Specifies that when dealing with a 1-bit buffer, the pitch is a multiple of 4 bytes; otherwise the pitch equals the SizeX parameter. |
||||||||||||||||||||||||||||||||||||||
Value |
Specifies the pitch in pixels or bytes (as determined by the ControlFlag parameter). (more details...) |
Specifies the MIL identifier of a buffer, or a pointer to the data array, to which to map the created MIL buffer.
When the ControlFlag parameter is set to M_MIL_ID, DataPtr specifies the MIL identifier of the source buffer.
When the ControlFlag parameter is set to M_HOST_ADDRESS, DataPtr specifies a logical address that points to the data.
When the ControlFlag parameter is set to M_PHYSICAL_ADDRESS, DataPtr specifies a physical address that points to the data.
Header | Include mil.h. |
Library | Use mil.lib. |
DLL | Requires mil.dll. |