Filters
Filter values by
Object Type
  • Array buffer
  • Image buffer
    • Image buffer that supports compression
  • Kernel buffer
  • LUT buffer
  • Structuring element buffer
| Customize Help
| Save Settings

MbufCreate2d


Function Map
Syntax
Description
Parameters
- SystemId
Table: For specifying the MIL system
- SizeX
Table: For specifying the buffer width
- SizeY
Table: For specifying the buffer height
- Type
Table: For specifying the data depth of the buffer
+ combination: For specifying the data type of the buffer
- Attribute
Table: For specifying the buffer usage
+ combination: For specifying the intended purpose of the image buffer
+ combination: For specifying the compression type
+ combination: For specifying location information
- ControlFlag
Table: For specifying the physical nature of the buffer
+ combination: For specifying how the pitch is measured
- Pitch
Table: For specifying the size of the pitch
- DataPtr
- BufIdPtr
Return value
Remarks
Compilation information
Synopsis
Create a two-dimensional data buffer.
Syntax
MIL_ID MbufCreate2d(
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
)
Description

This function creates a two-dimensional data buffer using memory at a specified location, 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.

[Matrox Radient eCL; Matrox Radient eV-CL (introduced U27); Matrox Radient eV-CXP (introduced M10); Matrox RadientPro-CL (Update 7); Matrox Rapixo CL Pro (Update 96); Matrox Rapixo CXP (introduced U75); Matrox Solios eA/XA; Matrox Solios ecl/xcl/ev-cl]

Note that to create a buffer mapped to on-board memory, it must be shared memory. See your MIL Hardware-specific Notes for more information regarding shared memory.

Note that this function reference has not been updated for a MIL system added during a MIL update. Refer to the MIL system's release note to see which MIL system’s documentation you should use in its place and any possible differences.
Parameters
This function is not supported on the selected boards.
This function reference has not been updated for the selected MIL system. To show the content of this page, choose a second MIL system; refer to the MIL system's release note to see which MIL system’s documentation to choose and any possible differences.
Parameters
SystemId INQ

Specifies the MIL system on which to create the buffer.

This parameter should be set to one of the following values:

function map For specifying the MIL system
Click to summarizeValue Description
Click to summarize M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Click to summarize MIL system identifier

Specifies a valid system identifier, previously allocated using MsysAlloc().
SizeX INQ

Specifies the buffer width.

function map For specifying the buffer width
Click to summarizeValue Description
Click to summarize 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.
Click to summarize Value

Specifies buffer width. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, width is specified in pixels.

(summarize)
SizeY INQ

Specifies the buffer height.

function map For specifying the buffer height
Click to summarizeValue Description
Click to summarize 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.
Click to summarize Value

Specifies the buffer height. The units are determined by the selected buffer attribute. For example, if the buffer has an image buffer attribute, height is specified in pixels.

(summarize)
Type INQ

Specifies a combination of two values: data type and data depth. Specify the depth of the buffer as one of the following:

function map For specifying the data depth of the buffer
Click to summarizeValue Description
Click to summarize 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.
Click to summarize 1 +

Specifies a 1-bit (packed binary) buffer. Note that you cannot allocate a 1-bit LUT, kernel, or structuring element buffer.

(summarize)
Click to summarize 8 +

Specifies an 8-bit buffer.
Click to summarize 16 +

Specifies a 16-bit buffer.
Click to summarize 32 +

Specifies a 32-bit buffer.
Combination values for the values listed in For specifying the data depth of the 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.

function map For specifying the data type of the buffer
Click to summarize
Combination value		 Description
Click to summarize M_FLOAT

Specifies that the type of data is floating-point. The valid data depth is 32 bits.

(summarize)
Click to summarize M_SIGNED

Specifies that the type of data is signed. The valid data depths are 8, 16 or 32 bits.

(summarize)
Click to summarize M_UNSIGNED

Specifies that the type of data is unsigned. The valid data depths are 1, 8, 16 or 32 bits.

This is the default value.

(summarize)
Attribute INQ

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.

Set this parameter to one of the following values:

function map For specifying the buffer usage
Click to summarizeValue Description
Click to summarize M_ARRAY +

Specifies a buffer to store array type data. Note that some functions take an M_ARRAY buffer rather than a user-defined array.

(summarize)
Click to summarize M_IMAGE +

Specifies a buffer to store image data.


You must specify a combination value from the following table:
(summarize)
Click to summarize M_KERNEL +
[For essential MIL-Lite information, see remarks ]

Specifies a kernel buffer to store a custom filter for convolution functions.

The depth must be 8, 16, or 32-bit integer or floating-point.

(summarize)
Click to summarize M_LUT +

Specifies a buffer to store lookup table data.

The valid data depths are 8, 16, or 32-bit.

(summarize)
Click to summarize M_STRUCT_ELEMENT +
[For essential MIL-Lite information, see remarks ]

Specifies a buffer to store structuring element data for morphology functions.

The data depth must be 32-bit. If signed, the range is -32768 to +32767. If unsigned, the range is 0 to +32767. Note that the data can be set to M_DONT_CARE to ignore specific structuring elements.

(summarize)
Combination values for M_IMAGE.

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.

function map For specifying the intended purpose of the image buffer
Click to summarize
Combination value		 Description MIL system-specific
tooltip (‡)
Click to summarize M_COMPRESS +
[For essential MIL-Lite information, see remarks ]

Specifies an image buffer that can hold compressed data. Note that a buffer with this attribute cannot have the M_SIGNED data type.

If M_COMPRESS is specified, the underlying data must already be compressed with the specified compression type. The Type SizeX and SizeY parameters must also be set to the exact size of the compressed image stored in the underlying data. It is not possible to create a compressed buffer mapped on to only part of a compressed image.

When mapping buffers for operations that require a source and destination buffer, and one of the buffers has an M_COMPRESS attribute, the data will be compressed or decompressed depending on the attributes of the destination buffer. If both the source and destination buffers have M_COMPRESS specifiers but different compression types, the data will be re-compressed according to the settings of the destination buffer.

Note that buffers created from preallocated memory with the M_COMPRESS attribute should typically only be passed to MIL functions as a source. If you pass a compressed buffer created from preallocated memory as a destination for a MIL function, an error will be generated if the compressed size in memory of the function output is not the same as the size of the allocated memory. This is true even if the ControlFlag parameter is set to M_MIL_ID.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize M_DISP

Specifies an image buffer that can be displayed.

 ‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Click to summarize M_GRAB

Specifies an image buffer in which to grab data. This type of buffer is usually allocated in MIL-reserved, physically contiguous, non-paged memory.

The physical nature of the buffers (using the ControlFlag) must be set to M_PHYSICAL_ADDRESS.

(summarize)
‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
MIL system specific

Single-band (monochrome) buffers must have a depth of 8 bits or 16 bits to have an M_GRAB attribute.

 ‡ c
M10		 j k
M10		 l m o p r
U27		 v y
U75		 aa

Single-band (monochrome) buffers must have a depth of 8 bits to have an M_GRAB attribute.

 ‡ g h t
U28
Click to summarize M_PROC

Specifies an image buffer that can be processed.

 ‡ a c
M10		 g h i j k
M10		 l m o p r
U27		 t
U28		 u
U36		 v y
U75		 aa
Combination values for M_COMPRESS.

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 compression format of the underlying data.

function map For specifying the compression type INQ
Click to summarize
Combination value		 Description
Click to summarize M_JPEG2000_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG2000 lossless data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Click to summarize M_JPEG2000_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG2000 lossy data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Click to summarize M_JPEG_LOSSLESS
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossless data. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Click to summarize 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. The supported data formats are: 1-band, 8- or 16-bit data.

(summarize)
Click to summarize M_JPEG_LOSSY
[For essential MIL-Lite information, see remarks ]

Specifies that the buffer will be used to hold JPEG lossy data. The supported data format is 1-band, 8-bit data.

This is the default value.

(summarize)
Click to summarize 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. The supported data format is 1-band, 8-bit data.

(summarize)
Combination value for any of the possible values of the Attribute parameter.

You can add the following value to the above-mentioned values to set whether the buffer is mapped to Host memory by default.

This value is only available when ControlFlag is set to M_PHYSICAL_ADDRESS, or M_MIL_ID if DataPtr specifies a buffer with a physical address (that is, MbufInquire() with M_PHYSICAL_ADDRESS does not return M_NULL).

function map For specifying location information
Click to summarizeCombination value Description
Click to summarize M_MAPPABLE

Specifies that the buffer is not mapped to Host memory when it is created (that is, by default the buffer will have a physical address, but not a Host address). Use MbufControl() with M_MAP to enable or disable mapping the buffer to Host memory.

This setting is useful when dealing with many large buffers that cannot all be mapped in Host memory at the same time. By creating a M_MAPPABLE buffer, it can be mapped and unmapped as needed.

(summarize)
ControlFlag

Specifies the physical nature of the buffer. This parameter can be set to one of the values below.

function map For specifying the physical nature of the buffer
Click to summarizeValue Description
Click to summarize M_HOST_ADDRESS +

Specifies that DataPtr is a logical address that points to the data.

Note that when using logical addresses, memory protection errors could result.

Note that you can use MbufInquire() with M_HOST_ADDRESS to get the logical address of a MIL allocated buffer.


You must specify a combination value from the following table:
(summarize)
Click to summarize M_MIL_ID +

Specifies that the new buffer maps to an existing source buffer. DataPtr points to the MIL identifier of the source buffer.


You must specify a combination value from the following table:
(summarize)
Click to summarize M_PHYSICAL_ADDRESS +

Specifies that DataPtr is a physical address that points to the data.

Note that using physical addresses provides direct access to any of your computer's memory mapped devices.

Note that you can use MbufInquire() with M_PHYSICAL_ADDRESS to get the physical address of a MIL allocated buffer.

This setting must be used for all buffers with the M_GRAB attribute.


You must specify a combination value from the following table:
(summarize)
Combination values for the values listed in For specifying the physical nature of the buffer.

You must add one of the following values to the above-mentioned values to set how the pitch is measured.

function map For specifying how the pitch is measured
Click to summarizeCombination value Description
Click to summarize M_PITCH

Specifies that the pitch is in pixels.
Click to summarize M_PITCH_BYTE

Specifies that the pitch is in bytes.
Pitch INQ

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.

function map For specifying the size of the pitch
Click to summarizeValue Description
Click to summarize 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.
Click to summarize Value

Specifies the pitch in pixels or bytes (as determined by the ControlFlag parameter).
DataPtr

Specifies the MIL identifier of the buffer, or a pointer to the data array, on 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.

BufIdPtr

Specifies the address of the variable in which the buffer identifier is to be written. Since the MbufCreate2d() function also returns the buffer identifier, you can set this parameter to M_NULL. If allocation fails, M_NULL is written as the identifier.

Return value
The returned value is the buffer identifier. If allocation fails, an identifier of 0 is returned.
Remarks
  • [MIL-Lite]
    Note that during development and at runtime, compression support, particularly for an M_COMPRESS buffer type, requires the presence of a MIL license that grants access to the compression/decompression package. This access is only granted by default with the development license dongle for the full version of MIL. In other cases, you must purchase access to this package separately.
  • [MIL-Lite]
    You can allocate an image buffer with an M_KERNEL or an M_STRUCT_ELEMENT attribute with MIL-Lite. However, these attributes are not required to work under MIL-Lite.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST DEFAULT DEFAULT DEFAULT FLOAT SIGNED UNSIGNED ARRAY IMAGE KERNEL LUT STRUCT ELEMENT COMPRESS DISP GRAB PROC JPEG2000 LOSSLESS JPEG2000 LOSSY JPEG LOSSLESS JPEG LOSSLESS INTERLACED JPEG LOSSY JPEG LOSSY INTERLACED MAPPABLE HOST ADDRESS MIL ID PHYSICAL ADDRESS PITCH PITCH BYTE DEFAULT DEFAULT DEFAULT DEFAULT ARRAY IMAGE KERNEL LUT STRUCT ELEMENT