Click here to show toolbars of the Web Online Help System: show toolbars
 

| Customize Help
| Save Settings

MdispAlloc


Function Map
Syntax
Description
Parameters
- SystemId
Table: For specifying the system
- DispNum
Table: For specifying the display device
Table: For specifying the position of the device to use for an exclusive display
- DispFormat
Table: For specifying the default display format
Table: For network displays
Table: For exclusive displays, or for auxiliary displays that don't use an encoder
Table: For auxiliary displays (with encoder)
- InitFlag
Table: For specifying the display type
+ combination: For controlling where and how the display is allocated
- DisplayIdPtr
Return value
Compilation information
Synopsis
Allocate a display.
Syntax
MIL_ID MdispAlloc(
MIL_ID SystemId, //in
MIL_INT DispNum, //in
MIL_CONST_TEXT_PTR DispFormat, //in
MIL_INT64 InitFlag, //in
MIL_ID *DisplayIdPtr //out
)
Description

This function allocates a display on the specified system so that it can be used by subsequent MIL display functions. Use MdispSelect() to select the image buffer to display. Note that the buffer and the display should be allocated on the same system.

In general, the display is presented on the computer running the main MIL application; however there are two ways to display an image buffer on the remote computer, depending on your application requirements:

  • When developing a Distributed MIL controlling application and you allocate a display on a DMIL remote system, you can select image buffers allocated on that DMIL remote system to the display. By default, these buffers are displayed on the master computer. However, to display the buffers on the remote computer, combine M_EXCLUSIVE, M_AUXILIARY, or M_WINDOWED with M_REMOTE_DISPLAY when allocating the display. This type of display is referred to as a remote display.

  • When developing a MIL application and wanting to publish a display so that image buffers selected to the display can be viewed at any remote computer in, for example, a web browser, use M_NETWORK when allocating the display. This type of display is referred to as a network display.

[Matrox Iris GTR (requires Update 28); Matrox Iris GT]

There can be 31 network displays allocated simultaneously.

When a display is no longer required, you should free it, using MdispFree().

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 system on which to allocate the display. This parameter should be set to one of the following values:

function map For specifying the 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().
DispNum INQ

Specifies the device to use for image display.

For a non-exclusive display or for an exclusive display that you want MIL to choose the display device, set this parameter to the following value:

function map For specifying the display device
Click to summarizeValue Description
Click to summarize M_DEFAULT

Specifies that MIL will use the most appropriate device for display purposes. If your imaging board has a display section, and it is available, MIL will typically use it for display purposes.

(summarize)

For an exclusive display for which you want to specify the position of the display device in screen arrangements of up to 3x3 screens, this parameter can be set to a combination of the following values.

function map For specifying the position of the device to use for an exclusive display
Click to summarizeValue Description
Click to summarize M_BOTTOM

Specifies to use the bottom-most device for an exclusive display. Note that this option cannot be combined with M_TOP.

(summarize)
Click to summarize M_CENTER

Specifies to use the center device for an exclusive display.
Click to summarize M_LEFT

Specifies to use the left-most device for an exclusive display. Note that this option cannot be combined with M_RIGHT.

(summarize)
Click to summarize M_RIGHT

Specifies to use the right-most device for an exclusive display. Note that this option cannot be combined with M_LEFT.

(summarize)
Click to summarize M_TOP

Specifies to use the top-most device for an exclusive display. Note that this option cannot be combined with M_BOTTOM.

(summarize)
DispFormat INQ

Specifies the format of the display. For windowed displays, this parameter has no effect and should be set to "M_DEFAULT". For exclusive or auxiliary displays, this parameter specifies the screen resolution. For network displays, this parameter specifies the color format in which to transmit the data.

For any type of display, this parameter can be set to the following value:

function map For specifying the default display format
Click to summarizeValue Description
Click to summarize MIL_TEXT("M_DEFAULT") 1

Specifies the default display format. For windowed displays, this is the only supported setting. For exclusive or auxiliary displays, this specifies the default video configuration format (VCF), which can be set during installation and later modified using the MILConfig utility (Defaults tab). For network displays, this is the same as "M_REMOTEVIEW".

(summarize)

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

When programming for your Matrox Iris GT with MIL in Embedded Compact, there is no local display to show the images or other data. The only displays available are network displays, which are displayed on the client computer (in a web page). Your Matrox Iris GT with MIL in Embedded Compact does not support windowed, exclusive, or auxiliary displays. Your Matrox Iris GT with MIL in XPe does not have these limitations.

For network displays, the DispFormat parameter can be set to one of the following values:

function map For network displays
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize MIL_TEXT("M_REMOTEVIEW") 1

Sets the display format to the most appropriate type of display available.

This is the default value.

(summarize)
‡ f t
Click to summarize MIL_TEXT("M_REMOTEVIEW_MONO") 1

Sets the display format to monochrome.

 ‡ f t
Click to summarize MIL_TEXT("M_REMOTEVIEW_PSEUDO") 1

Sets the display format to pseudo-color. To display the monochrome data in color, you must allocate your display with this setting. This will map images through a LUT upon display.

This display format can support a default 256 monochrome LUT with upper and lower 10 LUT entries programmed with Windows reserved 32-bit color values. Note that this default LUT cannot be changed.

(summarize)
‡ f t
Click to summarize MIL_TEXT("M_REMOTEVIEW_RGB") 1

Sets the display format to RGB.

 ‡ f t

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

For exclusive displays and for auxiliary displays that don't use an encoder, the DispFormat parameter can be set to the following:

function map For exclusive displays, or for auxiliary displays that don't use an encoder
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_CURRENT_RESOLUTION

Specifies to use the current resolution of the screen. This option is only available for a M_EXCLUSIVE display.

(summarize)
‡ b c e g h l m n o s
Click to summarize MIL_TEXT("vcf-file-name.vcf") 1

Specifies the name of the video configuration format (VCF) that defines the resolution and refresh rate to use. The file typically has a VCF extension. The drive, directory, and name of the file must be specified, for example: "C:\mydirectory\myfile".

For a file on the remote computer (under Distributed MIL), the path and file name must be preceded by "remote:///" (for example, "remote:///C:\mydirectory\myfile").

The file name string can be specified in, for example, the "1024x768x32@60hz.vcf" format. For the current list of video configuration format (VCF) files, see the MATROX IMAGING\DRIVERS\HOST\VCF folder.

(summarize)
‡ b c e g h l m n o s

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

For auxiliary displays that use the encoder in the on-board display section of the Matrox imaging board, the DispFormat parameter can be set to one of the following.

Note that encoders on other display boards are not supported.

function map For auxiliary displays (with encoder)
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize MIL_TEXT("M_NTSC") 1

Enables the encoder in composite format with colorburst.

This display format will produce both composite and Y/C outputs.

(summarize)
‡ n
Click to summarize MIL_TEXT("M_NTSC_RGB") 1

Enables the encoder in RGB format with synchronization on green.

 ‡ n
Click to summarize MIL_TEXT("M_NTSC_YC") 1

Enables the encoder in Y/C format with colorburst.

This display format will produce both composite and Y/C outputs.

(summarize)
‡ n
Click to summarize MIL_TEXT("M_PAL") 1

Enables the encoder in composite format with colorburst.

This display format will produce both composite and Y/C outputs.

(summarize)
‡ n
Click to summarize MIL_TEXT("M_PAL_RGB") 1

Enables the encoder in RGB format with synchronization on green.

 ‡ n
Click to summarize MIL_TEXT("M_PAL_YC") 1

Enables the encoder in Y/C format with colorburst.

This display format will produce both composite and Y/C outputs.

(summarize)
‡ n

1 If you are passing the value in a variable, don't enclose it in MIL_TEXT().

InitFlag INQ

Specifies your display's type. This parameter can be set to one of the following:

function map For specifying the display type
Click to summarizeValue Description MIL system-specific
tooltip (‡)
Click to summarize M_DEFAULT

Specifies the default display type, which can be set using the MILConfig utility. Typically, the default display type is M_WINDOWED.

(summarize)
‡ a b c d e f g h i j k l m n o p q r s t u
Click to summarize M_AUXILIARY +

Specifies to present the image buffer selected for display on a dedicated screen that is not a Windows desktop screen. The image buffer is presented at the top-left corner on an auxiliary screen.

Auxiliary displays are only supported when using an imaging board with a display section (such as Matrox Vio). It is possible to have more than one auxiliary display. Note, however, that only one auxiliary display is possible per graphics controller.

Auxiliary displays are supported regardless of the hardware-acceleration display mode. Note that Matrox Vio cannot drive your desktop screen.

(summarize)
‡ n
Click to summarize M_EXCLUSIVE +

Specifies to present the image buffer selected for display full-screen, without a windowed border, in one of Windows desktop screens. The image buffer is presented at the center of the screen.

Exclusive displays work with any graphic controller and are compatible with all video hardware acceleration modes.

To use an exclusive display, your Windows desktop should be using more than one screen. Allocating an exclusive display on the main screen might not be convenient; if you do so, the MIL exclusive display will hide third-party applications designed to start on the main screen and hide the Windows taskbar if it is displayed the main screen.

(summarize)
‡ a b c d e f g h i j k l m n o p q r s t u
Click to summarize M_NETWORK

Specifies to publish the display on your network so that the selected image buffer can be presented in, for example, a web browser on the remote computer.

 ‡ f t
Click to summarize M_WINDOWED +

Specifies to present the image buffer selected for display in its own window on the Windows desktop screen(s). The display window is tracked and updated with the image buffer selected for display; that is, if the window moves or is occluded, the window is updated with the image buffer accordingly.

(summarize)
‡ a b c d e f g h i j k l m n o p q r s t u
Combination value for M_AUXILIARY; M_EXCLUSIVE; M_WINDOWED.

You can add the following value to the above-mentioned values to set where and how the display is allocated.

function map For controlling where and how the display is allocated
Click to summarizeCombination value Description MIL system-specific
tooltip (‡)
Click to summarize M_REMOTE_DISPLAY

Specifies that the display is displayed on the remote computer. This setting is only available when the display is allocated on a DMIL remote system. If the display is allocated on a DMIL remote system but this setting is not specified, the display is presented on the local computer.

To present the display on the remote computer, the Distributed MIL server cannot be running as a service; you must start it manually. To do so, assuming that Distributed MIL has already been installed during the setup, you must logon to the remote computer and, from the MILConfig utility, push the Start Server button, found in the Server Settings pane under the Distributed MIL item. For more information, see the Setting up the Distributed MIL server on remote computers subsection of the Preparing computers for Distributed MIL section of Chapter 31: Distributed MIL.

(summarize)
‡ a b c e g h j k l m n o p q r s
DisplayIdPtr

Specifies the address of the variable in which to write the display identifier. Since the MdispAlloc() function also returns the display 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 display identifier if the allocation is successful. If allocation fails, M_NULL is returned.
Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll; mildisplay.dll.
DEFAULT HOST DEFAULT BOTTOM CENTER LEFT RIGHT TOP DEFAULT" REMOTEVIEW" REMOTEVIEW MONO" REMOTEVIEW PSEUDO" REMOTEVIEW RGB" CURRENT RESOLUTION NTSC" NTSC RGB" NTSC YC" PAL" PAL RGB" PAL YC" DEFAULT AUXILIARY EXCLUSIVE NETWORK WINDOWED REMOTE DISPLAY EXCLUSIVE