| MIL 10 Reference
| Customize Help
| Save Settings

MstrDraw


See also
Availability
Not available in MIL-Lite
Available in MIL

Available on Windows
Available on Linux

Available on Non-Matrox computer
Available on Matrox 4Sight-X
Available on Matrox 4Sight GP
Available on Matrox Supersight
function map Function map
Examples
MstrControl
MstrEditFont
Synopsis
Draw specific features of the String Reader context or String Reader results.
Syntax
void MstrDraw(
MIL_ID ContextGraId, //in
MIL_ID ContextOrResultStrId, //in
MIL_ID DstImageBufOrListGraId, //in
MIL_INT64 Operation, //in
MIL_INT Index, //in
const void *CharListPtr, //in
MIL_INT64 ControlFlag //in
)
Description

This function draws specific features of the String Reader context or String Reader results in the destination image buffer or specified graphics list.

After each drawing operation, the optimal image size that was needed for that operation is recorded in the String Reader context or result buffer (depending on what is passed) and can be inquired using MstrInquire with M_DRAW_LAST_SIZE_X and M_DRAW_LAST_SIZE_Y. When M_NULL is passed as the destination image (DstImageBufOrListGraId parameter), this function only records the optional image size for the specified drawing operation; that is, the drawing operation is not performed. This can be useful if, for example, you only want to get the optimal image buffer size for the drawing operation.

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 if there is complementary information.
Parameters
This function is not supported on the selected boards.
Parameters
ContextGraId

Specifies the identifier of the graphics context to use when drawing. This parameter must be set to one of the following values:

function map For specifying the graphics context
CollapseValue Description
Collapse M_DEFAULT

Specifies that the default graphics context of the current MIL application is used.

Note that there is a different default graphics context for each thread.

(summarize)
Collapse MIL graphics context identifier

Specifies a valid graphics context identifier, which you have allocated using MgraAlloc().
ContextOrResultStrId

Specifies the String Reader context or String Reader result buffer from which to extract the features to draw. The String Reader context or result buffer must have been previously allocated on the system using MstrAlloc() or MstrAllocResult(), respectively.

DstImageBufOrListGraId

Specifies the identifier of the destination image buffer or graphics list in which to draw. The buffer can be any valid MIL image buffer allocated using MbufAlloc...(). The graphics list must be previously allocated using MgraAllocList(). By drawing into a display's overlay buffer or associating the graphics list with the display, you can also annotate an image non-destructively.

When ContextOrResultStrId is set to the identifier of a String Reader context and the Operation parameter is set to M_DRAW_CHAR, this parameter can be set to any valid MIL image buffer, a graphics list, or M_NULL. In any other case, this parameter can be set to the indentifier of an image buffer or a graphics list.

If specifying an image buffer, it must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

When this parameter is set to M_NULL, this function only records the optional image size for the specified drawing operation; that is, the drawing operation is not performed.

Operation

Specifies the type of operation to perform.

The following Operation parameter value can only be set for a String Reader context.

function map For a font-based context
CollapseValue Description
Collapse M_DRAW_CHAR

Draws a character representation of the font in the destination image. Characters are drawn from left to right, and from top to bottom. Characters that fall outside the destination image are clipped.

The characters are drawn according to their draw box margin, set using MstrControl() with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y. This margin will determine the amount of white space between each character that is drawn.

Note that this operation is only available if using a font-based context.

The graphics context cannot have its input units set to world units (MgraControl() with M_INPUT_UNITS set to M_WORLD) when drawing with this operation in either an image buffer or a graphics list. If drawing in a zoomed and offset region, only integer values must be used (MgraControl() with M_DRAW_OFFSET_X, M_DRAW_OFFSET_Y, M_DRAW_ZOOM_X, and M_DRAW_ZOOM_Y set to integer values).

(summarize)

The following Operation parameter values can only be set for a String Reader result buffer. Note that these values can be added together to draw multiple features at once.

Unless otherwise specified, you can use these operations if results were obtained using either a font-based or a fontless context.

When applicable, features are always drawn at the location read in the target with the correct angle, scale, and aspect ratio.

function map For a result buffer
CollapseValue Description
Collapse M_DRAW_MIL_FONT_STRING

Draws all the characters of the String Reader result(s) under the bottom left corner of the string bounding box (M_DRAW_STRING_BOX). The font associated with the graphics context is used to draw the characters.

(summarize)
Collapse M_DRAW_STRING

Draws all the characters of String Reader result(s).

Note that this operation is only available if the results were obtained using a font-based context.

The graphics context cannot have its input units set to world units (MgraControl() with M_INPUT_UNITS set to M_WORLD) when drawing with this operation in either an image buffer or a graphics list. If drawing in a zoomed and offset region, only integer values must be used (MgraControl() with M_DRAW_OFFSET_X, M_DRAW_OFFSET_Y, M_DRAW_ZOOM_X, and M_DRAW_ZOOM_Y set to integer values).

(summarize)
Collapse M_DRAW_STRING_BOX

Draws a box around the string that is read in the target. Note that the bounding box of the string is the bounding box of all the string's characters, including the draw margin (set with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y in MstrControl()).

(summarize)
Collapse M_DRAW_STRING_CHAR_BOX

Draws all the character boxes of the String Reader result(s). The character box drawn is the bounding box of the character plus the draw margin (set with M_DRAW_BOX_MARGIN_X and M_DRAW_BOX_MARGIN_Y in MstrControl()).

(summarize)
Collapse M_DRAW_STRING_CHAR_POSITION

Draws a cross at the center of gravity of each string's character.
Collapse M_DRAW_STRING_CONTOUR

Draws the contour of all the characters of the result(s) of the string(s) read.

Note that this operation is only available if the results were obtained using a font-based context.

The graphics context cannot have its input units set to world units (MgraControl() with M_INPUT_UNITS set to M_WORLD) when drawing with this operation in either an image buffer or a graphics list. If drawing in a zoomed and offset region, only integer values must be used (MgraControl() with M_DRAW_OFFSET_X, M_DRAW_OFFSET_Y, M_DRAW_ZOOM_X, and M_DRAW_ZOOM_Y set to integer values).

(summarize)
Index

Specifies the index of the font feature or result feature to draw.

Set this parameter to one of the following values:

function map For specifying the font or result
CollapseValue Description
Collapse M_DEFAULT

Draws the default features for either fonts or results.

For a String Reader context, the default value is the same as M_FONT_INDEX().

For a String Reader result, the default value is the same as M_ALL.

(summarize)
Collapse

Draws the features of a specific font.

Note that this operation is only available if using a font-based context.

(summarize)
Parameters

This parameter specifies the index of the font. Set this parameter to the following:
M_ALL

Specifies all fonts.
0 <= Value < 255

Specifies a specific font.
Collapse M_ALL

Draws the features of all results.
Collapse Value >= 0

Draws the features of a specific result.
CharListPtr

Specifies an explicit list of valid characters to draw, at the specified position. This is an optional, null-terminated string.

This parameter is not needed when drawing results and should be set to M_NULL.

Characters will be drawn in the order given in the CharListPtr parameter. To draw the characters on multiple lines, a space character must be inserted to separate the strings included in the null-terminated terminated string.

The array of strings must be of the right type for the encoding scheme selected (MstrControl() with M_ENCODING). At preprocessing time, each character in an explicit character list must exist in at least one of the fonts of the constraint.

ControlFlag

Specifies where in the destination image buffer to draw.

For a String Reader result, this parameter must be set to M_DEFAULT.

For a String Reader context, set this parameter to one of the following values:

function map For specifying where to draw
CollapseValue Description
Collapse M_DEFAULT

Draws characters from the center of the top-left pixel of the destination image buffer; or, if drawing in a graphics list, from the center of the top-left pixel of the image used at the time of annotation.
Collapse M_ORIGINAL

Draws characters at the same offset as their original position in the definition image, for user-defined characters (set using MstrEditFont() with M_USER_DEFINED). Note that characters that are not user-defined (for example, TrueType) will be drawn at an offset of 0.

To ascertain where user-defined characters are located in the definition image, you must draw the user-defined characters in an overlay on top of the definition image. That is to say, you must draw the characters on top of their original location. For more information, refer to M_DEFINITION_OFFSET_X and M_DEFINITION_OFFSET_Y in MstrInquire().

(summarize)
Compilation information
Header Include mil.h.
Library Use mil.lib; milstr.lib.
DLL Requires mil.dll; milstr.dll.
DEFAULT PROC NONE DRAW CHAR DRAW MIL FONT STRING DRAW STRING DRAW STRING BOX DRAW STRING CHAR BOX DRAW STRING CHAR POSITION DRAW STRING CONTOUR DEFAULT ALL ALL DEFAULT ORIGINAL FONT BASED