| MIL 10 Reference
| Customize Help
| Save Settings

MbufCreateColor


See also
Availability
Available in MIL-Lite with restrictions (see remarks)
Available in MIL

Available on Windows with restrictions
Available on Linux with restrictions

Partially supported on:
Partially supported on Host system
Partially supported on Matrox CronosPlus
Partially supported on Matrox GPU processing driver
Partially supported on Matrox GigE Vision driver
Partially supported on Matrox IEEE 1394 IIDC driver
Partially supported on Matrox Iris GT
Partially supported on Matrox Morphis
Partially supported on Matrox Morphis QxT
Partially supported on Matrox Orion HD
Partially supported on Matrox Radient eCL
Partially supported on Matrox Radient eV-CXP
Partially supported on Matrox Solios eA/XA
Partially supported on Matrox Solios ecl/xcl/ev-cl
Partially supported on Matrox USB3 Vision driver (requires Update 19)
Partially supported on Matrox Vio

For any information regarding a MIL system added during a MIL Update, see the MIL system’s release note

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MbufCreate2d
MbufDiskInquire
Synopsis
Create a color data buffer.
Syntax
MIL_ID MbufCreateColor(
MIL_ID SystemId, //in
MIL_INT SizeBand, //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
void **ArrayOfDataPtr, //in
MIL_ID *BufIdPtr //out
)
Description

This function creates a color 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 (MbufAllocColor(), MbufGetColor(), MbufPutColor()), 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 MbufCreateColor() and you must free the created buffer when no longer required, using MbufFree() before freeing the memory. Using MbufFree() on a buffer created with MbufCreateColor() will free the internal structure required for a mapped buffer, but it will not free the memory used.

If creating a 3-band buffer, be as specific as possible when setting the buffer attributes (using the Attribute parameter) and make sure to specify the color format of the buffer. The more information known about the associated buffer, the better the results.

[Matrox Solios eA/XA; Matrox Solios ecl/xcl/ev-cl]

Note that to map a buffer to on-board memory on a different system, the on-board memory must be shared memory, unless the created buffer is created on the same system. 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
CollapseValue Description
Collapse M_DEFAULT_HOST

Specifies the default Host system of the current MIL application.
Collapse MIL system identifier

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

Specifies the number of (x,y) surfaces (also called color bands) that the buffer should have to contain each color component of the data. When acquiring or processing monochrome images, the buffer requires only one color band. For RGB color images, it requires three color bands.

function map For specifying the number of surfaces
CollapseValue Description
Collapse M_DEFAULT

Specifies the same number color bands as the source buffer when the ControlFlag parameter is set to M_MIL_ID.
Collapse 1 <= Value <= 3

Specifies the number of bands. There are generally either 1 or 3 bands.

(summarize)
SizeX INQ

Specifies the buffer width.

[Matrox GPU processing driver]

When dealing with monochrome (1-band) buffers, the buffer width must be a multiple of 4.

function map For the buffer width
CollapseValue Description
Collapse 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.
Collapse Value

Specifies the 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 the buffer height
CollapseValue Description
Collapse 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.
Collapse 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 depth and data type, per band. Specify the depth of the buffer per band as one of the following:

function map For the depth of the buffer
CollapseValue Description
Collapse M_DEFAULT

Specifies that the data depth and type are identical to that of the source buffer when the ControlFlag parameter is set to M_MIL_ID.
Collapse 1 +

Specifies a 1-bit (packed binary) buffer. Note that you cannot create a 1-bit LUT buffer.

(summarize)
Collapse 8 +

Specifies an 8-bit buffer.
Collapse 16 +

Specifies a 16-bit buffer.
Collapse 32 +

Specifies a 32-bit buffer.
Combination constants for the values listed in For the depth of the buffer.

You can add one of the following values to the above-mentioned values to set the data type.

function map For specifying the data type
CollapseCombination value Description
Collapse M_FLOAT

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

(summarize)
Collapse M_SIGNED

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

(summarize)
Collapse 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
CollapseValue Description
MIL system-specific
tooltip (†)
Collapse 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)
† a b c d e f g h i j k l m n o p q r s
Collapse M_IMAGE +

Specifies a buffer to store image data.


You must specify a combination value from the following table:
(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

Single-band (monochrome) buffers with a depth of 8 or 16 bits can have an M_IMAGE attribute.

Three-band (BGR) unsigned packed buffers with a depth of 8 bits (M_BGR32) can have an M_IMAGE attribute.

 † d
Collapse M_LUT +

Specifies a buffer to store lookup table data.

The depth must be 8, 16, or 32-bit integer or floating-point and the internal storage format must be planar (M_PLANAR).

(summarize)
† a b c d e f g h i j k l m n o p q r s
Combination constants 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
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse 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.

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.


You must specify a combination value from the following table:
(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_DISP +

Specifies an image buffer that can be displayed.


You must specify a combination value from the following table:
(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_GRAB +

Specifies an image buffer in which to grab data.

For Host buffers (M_HOST_MEMORY), the maximum (total) number of grab (M_GRAB) buffers is restricted by the total amount of MIL-reserved, non-paged memory (specified at installation time or using the MILConfig utility).

For on-board buffers (M_ON_BOARD), maximum (total) number of grab (M_GRAB) buffers is restricted by the total amount of on-board memory.

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


You must specify a combination value from the following table:
(summarize)
† 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 and 3-band (color) buffers with a depth of 8 bits can have an M_GRAB attribute.

 † c j k l m o p q r s

Only single-band or 3-band buffers, with a depth of 8 bits, can have an M_GRAB attribute.

 † b g h n

Only single-band (monochrome) planar (M_PLANAR) buffers with a depth of 8 bits can have an M_GRAB attribute.

Only 3-band BGR (color) packed buffers with a depth of 32 bits can have an M_GRAB attribute (that is 32-bit buffers allocated with M_GRAB + M_BGR32 + M_PACKED). Note that 3-band buffers are only available when using a Matrox Iris GT300C, GT1200C, or GT1900C.

 † f
Collapse M_PROC +

Specifies an image buffer that can be processed.


You must specify a combination value from the following table:
(summarize)
† a b c d e f g h i j k l m n o p q r s
Combination constants 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 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 compression type INQ
CollapseCombination value Description
Collapse 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, and 3-band, 8- or 16-bit data in M_RGB24 + M_PLANAR, M_RGB48 + M_PLANAR, or M_YUV24 + M_PLANAR format.

(summarize)
Collapse 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, and 3-band, 8- or 16-bit data in M_RGB24, M_RGB48, M_YUV9, M_YUV12, M_YUV16 + M_PLANAR, or M_YUV24 format.

(summarize)
Collapse 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, and 3-band data in M_RGB24 or M_RGB48 format.

(summarize)
Collapse 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)
Collapse 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 formats are: 1-band 8-bit data, and 3-band 8-bit data in M_RGB24, M_YUV24, M_YUV12, M_YUV9, M_YUV16 + M_PLANAR, or M_YUV16 + M_PACKED format.

This is the default value.

(summarize)
Collapse 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 formats are: 1-band 8-bit data, and 3-band 8-bit data in M_YUV16 + M_PACKED format.

(summarize)
Combination constants for M_IMAGE.

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.

function map For specifying a storage format
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_DIB
[This is only applicable to Windows]

Specifies that the buffer to be a DIB buffer. This ensures that your buffer is stored with a DIB header. Use MbufInquire() with M_BITMAPINFO to return a pointer (LPBITMAPINFO) to the header of the MIL buffer.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse 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
Collapse M_GDI

Specifies that the buffer to be compatible with GDI.

When using a device context (using MbufControl() with M_DC_ALLOC) for drawing, the buffer should be internally stored in GDI format, and cannot be a child buffer.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse 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
Combination constant for the values listed in For specifying the buffer usage.

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.

function map For image and LUT buffers
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_FPGA_ACCESSIBLE +

Specifies that the buffer is in a bank of memory that is accessible from the Processing FPGA. The exact bank of on-board memory is determined by the other attributes used with this value.

If combined with the M_HOST_MEMORY attribute, the buffer is created in non-paged Host memory.

If combined with the M_GRAB, or M_PROC attribute, the Matrox Solios will createa buffer in memory bank 0.

If combined with the M_PROC attribute, the Matrox Solios will create a buffer in memory bank 1.

If combined with the M_PROC + M_FAST_MEMORY attribute, the Matrox Solios will create a buffer in memory bank 2.

(summarize)
† j l m p r
Combination constants for M_IMAGE.

You can add one of the following values to the above-mentioned value to set a storage format for color buffers.

When dealing with color buffers, you must specify the appropriate internal storage format of the buffer by adding one of the following values. Note that MIL needs this information to manipulate the data; for example, you do not want MIL to interpret a packed data buffer as a planar.

Note that it might be slower to use buffers that have been forced with one of these attributes. Although there is no right or wrong storage format to use, certain operations are optimized for some formats.

function map For specifying a storage format for color buffers INQ
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_PACKED +

Specifies that the buffer's bands are stored in packed format (color buffer only); that is, the pixel components are stored together (RGB RGB RGB...). Typically, packed buffers are used for display (M_DISP). Note that it might be slower to process buffers with the M_PACKED attribute. Also, note that you cannot allocate a packed LUT buffer.


You must specify a combination value from each of the following tables:
(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

Only 3-band BGR (color) packed buffers with a depth of 32 bits can have an M_GRAB attribute (that is 32-bit buffers allocated with M_GRAB + M_BGR32 + M_PACKED). Note that 3-band buffers are only available when using a Matrox Iris GT300C, GT1200C, or GT1900C.

 † f
Collapse M_PLANAR +

Specifies that the buffer's bands are stored in planar format (color buffer only); that is, each pixel is stored as three component planes (RRR... GGG... BBB...). Typically, planar buffers are used for processing (M_PROC).


You must specify a combination value from each of the following tables:
(summarize)
† a b d e f g h i j k l m n p q r
MIL system specific

Only single-band (monochrome) planar buffers with a depth of 8 bits can have an M_GRAB attribute.

 † f
Combination constants for M_PLANAR.

You must add one of the following values to the above-mentioned value to set a planar color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the specified physical memory.

[Matrox Iris GT]

Note that the following color buffer formats are only available when using a Matrox Iris GT300C, GT1200C, or GT1900C.

function map For specifying a planar color buffer format
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_RGB3

Specifies 3-bit color depth (RGB 1:1:1) planar pixels.

 † a b d e f g h i j k l m n p q r
Collapse M_RGB96

Specifies 96-bit color depth (RGB 32:32:32) planar pixels.

 † a b d e f g h i j k l m n p q r
Collapse M_YUV9

Specifies YUV9 planar standard.

 † a b d e f g h i j k l m n p q r
Collapse M_YUV12

Specifies YUV12 planar standard.

 † a b d e f g h i j k l m n p q r
Collapse M_YUV24

Specifies YUV24 planar standard.

 † a b d e f g h i j k l m n p q r
Combination constants for M_PACKED.

You must add one of the following values to the above-mentioned value to set a packed color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the specified physical memory.

[Matrox Iris GT]

Note that the following color buffer formats are only available when using a Matrox Iris GT300C, GT1200C, or GT1900C.

function map For specifying a packed color buffer format
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_BGR24

Specifies 24-bit color depth (BGR) packed pixels (BGRBGR).

(summarize)
† a b c e f g h i j k l m o p q r s
MIL system specific

This value can be used with grab (M_GRAB) buffers.

 † a b c e g h i j k l m o p q r s
Collapse M_BGR32

Specifies 32-bit color depth (BGR) packed pixels (BGRXBGRX). The most-significant byte is a "don't care" byte.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

This value can be used with grab (M_GRAB) buffers.

 † a b c e g h i j k l m n o p q r s

This value can be used with packed (M_PACKED) grab (M_GRAB) buffers only if a color DCF is used during the grab.

 † f
Collapse M_RGB15

Specifies 16-bit color depth packed pixels (XRGB 1:5:5:5).

Note that when accessing an M_RGB15 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_RGB16

Specifies 16-bit color depth packed pixels (RGB 5:6:5).

Note that when accessing an M_RGB16 + M_PACKED buffer as a 3-band 8-bit buffer, the least significant bits are set to 0.

(summarize)
† a b c d e f g h i j k l m n o p q r s
Collapse M_YUV16_UYVY

Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the UYVY order. For more information, see the YUV buffers section of Chapter 19: Data buffers.

(summarize)
† c e o s
MIL system specific

This value can be used with grab (M_GRAB) buffers.

 † c o s
Collapse M_YUV16_YUYV

Specifies YUV16 packed (4:2:2) pixels, whereby the components of each pixel are stored in the YUYV order. For more information, see the YUV buffers section of Chapter 19: Data buffers.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

This value can be used with grab (M_GRAB) buffers.

 † a b c e g h i j k l m n o p q r s
Combination constants for the values listed in For specifying the intended purpose of the image buffer; the values listed in For specifying a storage format for color buffers.

You must add one of the following values to the above-mentioned values to set a color buffer format.

Note that the values below cannot be used with grab buffers (M_GRAB), unless otherwise stated.

The specified format can differ from that of the specified physical memory.

[Matrox Iris GT]

Note that the following color buffer formats are only available when using a Matrox Iris GT300C, GT1200C, or GT1900C.

function map For specifying a packed or planar color buffer format
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_RGB24

Specifies 24-bit color depth (RGB 8:8:8) packed or planar pixels.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

This value can be used with planar (M_PLANAR) grab (M_GRAB) buffers.

 † j k l m p q r

This value can be used with Host (M_HOST_MEMORY) planar (M_PLANAR) grab (M_GRAB) buffers.

 † n

This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

 † c e n o s

Note that this value can only be used with buffers created on the Host (M_HOST_MEMORY).

 † n
Collapse M_RGB48

Specifies 48-bit color depth (RGB 16:16:16) planar pixels.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

 † c j k l m o p q r s

This value can be used with planar (M_PLANAR) grab (M_GRAB) buffers if the buffer is allocated on the Host (M_HOST_MEMORY) and not on-board.

 † j k l m p q r

This value can only be used with planar (M_PLANAR) buffers.

 † b d e g h
Collapse M_YUV16

Specifies YUV16 packed or planar (4:2:2) standard.

(summarize)
† a b c d e f g h i j k l m n o p q r s
MIL system specific

This value can be used with packed (M_PACKED) grab (M_GRAB) buffers.

 † a b e g h i j k l m n p q r
Combination constants for the values listed in For specifying the buffer usage.

You can add one of the following values to the above-mentioned values to set a location for a buffer.

function map For specifying a location
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_HOST_MEMORY

Specifies that the buffer is in Host memory.

(summarize)
† 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
Collapse M_MAPPABLE

Specifies that the buffer is in non-paged memory that can be set in the address space of the process (Host memory). By default, however it is not mapped to Host memory (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 the mapping 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.

Note that, if used with the M_PAGED attribute, an error will be generated.

(summarize)
† a b c e f g h i j k l m n o p q r s
Collapse M_OFF_BOARD

Specifies that the buffer is not in on-board memory.

(summarize)
† 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 l m n
Collapse M_ON_BOARD +

Specifies that the buffer in on-board memory.

(summarize)
† 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
Collapse M_VIDEO_MEMORY
[This is only applicable to Windows]

Specifies that the buffer is in (off-screen) display memory of your graphics controller.

If Direct3D hardware acceleration mode is being used for display, the buffer cannot be created in display memory when any of the following attributes are used: M_GRAB or M_NON_PAGED. This is also the case when using DirectDraw 7 hardware acceleration mode if also using a non-Matrox graphics controller.

If Direct3D hardware acceleration mode is being used for display and you create the buffer in display memory, you must use the lock-unlock mechanism to access the buffer (MbufControl() with M_LOCK / M_UNLOCK).

(summarize)
† 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 display 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
Combination constants for the values listed in For image and LUT buffers; and for the following value: M_ON_BOARD.

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.

function map For specifying a specific on-board memory bank
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_MEMORY_BANK_0

Specifies that the buffer is in memory bank 0 of memory that is accessible from the Processing FPGA.

Memory bank 0 is acquisition memory. This is the default memory bank for on-board buffer created with the M_GRAB or M_PROC attribute.

(summarize)
† j k l m p q r
Collapse M_MEMORY_BANK_1

Specifies that the buffer is in memory bank 1 of memory that is accessible from the Processing FPGA.

Memory bank 1 is SDRAM memory. If not available, an error is generated. This is the default memory bank for on-board buffer created with the M_GRAB or M_PROC attribute.

(summarize)
† 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
Collapse M_MEMORY_BANK_2

Specifies that the buffer is in memory bank 2 of memory that is accessible from the Processing FPGA.

Memory bank 2 is SRAM memory. This is the default memory bank for an on-board buffer created with the M_PROC + M_FAST_MEMORY attribute.

(summarize)
† l m
Combination constants for the values listed in For image and LUT buffers; and for the following value: M_ON_BOARD.

You can add one of the following values to the above-mentioned values to set a specific location in memory.

function map For on-board memory buffers, accessible by the FPGA
CollapseCombination value Description
MIL system-specific
tooltip (†)
Collapse M_FAST_MEMORY

Specifies that the buffer is created in the fastest memory available.

Use MbufInquire() with M_EXTENDED_FORMAT to establish if the buffer was created in fast processing memory.

This attribute can only be combined with M_FPGA_ACCESSIBLE. M_FAST_MEMORY is typically the same as using M_MEMORY_BANK_2.

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.

(summarize)
† j k l m p q r
Collapse M_SHARED

Specifies that the buffer is in shared processing memory. This memory is mapped on the PCI bus.

Note that this combination value can only be added to M_ON_BOARD.

(summarize)
† j k l m p q r
Combination constants for the values listed in For specifying the buffer usage.

You can add one of the following values to the above-mentioned values to set a type of 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.

function map For specifying a type of memory
CollapseCombination value Description
Collapse M_NON_PAGED

Specifies that the buffer is in MIL-reserved, non-pageable memory.
Collapse M_PAGED

Specifies that the buffer is in pageable memory.
Combination constant for M_PROC.

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.

function map For specifying overscan
CollapseCombination value Description
Collapse M_ALLOCATION_OVERSCAN

Specifies that the buffer has an overscan region.
ControlFlag

Specifies the physical nature of the buffer.

See the Parameter associations section for possible values that can be specified.

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
CollapseValue Description
Collapse 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.
Collapse Value

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

For an M_DIB buffer, if the pitch is in pixels (M_PITCH), the pitch must equal the SizeX parameter. If the pitch is in bytes (M_PITCH_BYTE), the pitch must be the next multiple of 4 that is larger or equal to (SizeX * bytes per pixel ).

(summarize)
ArrayOfDataPtr

Specifies one or more data pointers that address the memory to which to map the created MIL buffer.

When pointing to a planar buffer, one pointer per band must be provided. Pointers to a 3-band planar buffer must be ordered R-G-B or Y-U-V in the array. When pointing to a single-band buffer or a packed buffer, a pointer to the packed data must be provided.

See the Parameter associations section for possible values that can be specified.

BufIdPtr

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

Parameter associations

The table below lists possible values for the ControlFlag and ArrayOfDataPtr parameters.

function map For specifying the physical nature of the buffer
CollapseControlFlag Description
ArrayOfDataPtr
Collapse M_HOST_ADDRESS +

Specifies that a logical address 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)
Collapse Value

Specifies a logical address that points to the data.
Collapse M_MIL_ID +

Specifies that the new buffer maps to an existing source buffer.


You must specify a combination value from the following table:
(summarize)
Collapse MIL Array ID

Specifies the MIL identifier of the source array buffer.
Collapse MIL Image ID

Specifies the MIL identifier of the source image buffer.
Collapse MIL kernel ID

Specifies the MIL identifier of the source kernel buffer.
Collapse MIL LUT ID

Specifies the MIL identifier of the source LUT buffer.
Collapse MIL Structuring element ID

Specifies the MIL identifier of the source structuring element buffer.
Collapse M_PHYSICAL_ADDRESS +

Specifies that a physical address 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)
Collapse Value

Specifies a physical address points to the data.
Combination constants 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
CollapseCombination value Description
Collapse M_PITCH

Specifies that the pitch is in pixels.

This is the default value.

(summarize)
Collapse M_PITCH_BYTE

Specifies that the pitch is in bytes.
Return value
The returned value is the buffer identifier. If allocation fails, M_NULL is returned.
Remark
  • [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.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT HOST DEFAULT DEFAULT DEFAULT DEFAULT FLOAT SIGNED UNSIGNED ARRAY IMAGE LUT COMPRESS DISP GRAB PROC JPEG2000 LOSSLESS JPEG2000 LOSSY JPEG LOSSLESS JPEG LOSSLESS INTERLACED JPEG LOSSY JPEG LOSSY INTERLACED DIB DIRECTX GDI LINUX MXIMAGE FPGA ACCESSIBLE PACKED PLANAR RGB3 RGB96 YUV9 YUV12 YUV24 BGR24 BGR32 RGB15 RGB16 YUV16 UYVY YUV16 YUYV RGB24 RGB48 YUV16 HOST MEMORY MAPPABLE OFF BOARD ON BOARD VIDEO MEMORY MEMORY BANK 0 MEMORY BANK 1 MEMORY BANK 2 FAST MEMORY SHARED NON PAGED PAGED ALLOCATION OVERSCAN DEFAULT HOST ADDRESS MIL ID PHYSICAL ADDRESS PITCH PITCH BYTE ARRAY IMAGE IMAGE M COMPRESS LUT DEFAULT DEFAULT DEFAULT