| MIL 10 Reference
| Customize Help
| Save Settings

MgraRectAngle



See also
Availability
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
Synopsis
Draw a rectangle in an image with optional rotation and fill color, or add it to a graphics list.
Syntax
void MgraRectAngle(
MIL_ID ContextGraId, //in
MIL_ID DestImageBufIdOrGraListId, //in
MIL_DOUBLE XPos, //in
MIL_DOUBLE YPos, //in
MIL_DOUBLE Width, //in
MIL_DOUBLE Height, //in
MIL_DOUBLE Angle, //in
MIL_INT64 ControlFlag //in
)
Description

This function draws a rectangle destructively (raster-based) in the specified image with an optional rotation and fill color. Alternatively, this function can add a vector-based version of a rectangle to the specified graphics list, allowing you to, for example, non-destructively annotate a display without pixelation effects upon scaling.

The rectangle is created using a point (XPos, YPos), a width (Width), a height (Height), and an angle of rotation (Angle). The rectangle inherits all the relevant settings of the specified graphics context, such as the foreground color (see MgraAlloc() for default context settings). If part of the rectangle falls outside of the specified area (image or display), that part is clipped off.

To modify or inquire graphics context settings, use MgraControl() or MgraInquire(). To modify or inquire graphics list settings, use MgraControlList() or MgraInquireList().

A rectangle's coordinates, dimensions, and angle are interpreted with respect to the input coordinate system, specified using MgraControl() or MgraControlList() with M_INPUT_UNITS. An angle interpreted with respect to the pixel coordinate system is always measured counter-clockwise. For information on the angle's direction of rotation when interpreting the angle with respect to the relative coordinate system, see the Angle convention in MIL subsection of the Working with real-world units section of Chapter 25: Calibrating your camera setup. Note that if you set your input coordinate system to M_WORLD and you pass MgraRectAngle() an uncalibrated image or the drawing target of the graphics list is uncalibrated, the function will generate an error.

To create a filled rectangle that is not rotated, use MgraRectFill(). To create a rectangle that is not rotated or filled, use MgraRect().

Unlike most other functions that modify a MIL object, you can call this function concurrently from multiple threads on the same MIL graphics list (DestImageBufIdOrGraListId) without using an M_MUTEX object, as long as all the other parameters of the concurrent calls do not also share data.

When compiling C code in 64-bit mode, MgraRectAngle() internally calls the MIL_INT64 version of this function (MgraRectAngleInt64()). If you need to pass floating-point values, call the MIL_DOUBLE version of this function (MgraRectAngleDouble()).
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. 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().

DestImageBufIdOrGraListId

Specifies the identifier of a valid image buffer in which to draw the rectangle or the identifier of a valid graphics list in which to add the rectangle. You must have allocated the image buffer or the graphics list using MbufAlloc...() or MgraAllocList(), respectively.

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

XPos

Specifies the X-coordinate of the rectangle's position in the input coordinate system.

YPos

Specifies the Y-coordinate of the rectangle's position in the input coordinate system.

Width INQ

Specifies the width of the rectangle, relative to the input coordinate system.

Height INQ

Specifies the height of the rectangle, relative to the input coordinate system.

Angle INQ

Specifies the angle with which to rotate the rectangle, in degrees, relative to the input coordinate system. The rectangle will either be rotated around its center (when using M_CENTER_AND_DIMENSION) or its top-left corner (when using M_CORNER_AND_DIMENSION).

ControlFlag INQ

Specifies how to draw the rectangle in the image or add the rectangle to the graphics list.

function map For specifying how to draw or add the rectangle
CollapseValue Description
Collapse M_DEFAULT

Same as M_CORNER_AND_DIMENSION.

Collapse M_CENTER_AND_DIMENSION +

Specifies that the rectangle is drawn according to its center position, as defined by the specified coordinates. Coordinates are set with the XPos and YPos parameters.

(summarize)
Collapse M_CORNER_AND_DIMENSION +

Specifies that the rectangle is drawn according to the position of its top-left corner, as defined by the specified coordinates. Coordinates are set with the XPos and YPos parameters.

(summarize)
Combination constant for any of the possible values of the ControlFlag parameter.

You can add the following value to the above-mentioned values to set whether the rectangle is filled.

function map For specifying whether the rectangle is filled
CollapseCombination value Description
Collapse M_FILLED

Specifies that the rectangle is filled with specified foreground color (MgraControl() or MgraControlList() with M_COLOR).

Type-specific versions of the function
void MgraRectAngleDouble (MIL_ID ContextGraId, MIL_ID DestImageBufIdOrGraListId, MIL_DOUBLE XPos, MIL_DOUBLE YPos, MIL_DOUBLE Width, MIL_DOUBLE Height, MIL_DOUBLE Angle, MIL_INT64 ControlFlag)
Parameters

ContextGraId

See ContextGraId of the main function for a description.

DestImageBufIdOrGraListId

See DestImageBufIdOrGraListId of the main function for a description.

XPos

See XPos of the main function for a description.

YPos

See YPos of the main function for a description.

Width

See Width of the main function for a description.

Height

See Height of the main function for a description.

Angle

See Angle of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

void MgraRectAngleInt64 (MIL_ID ContextGraId, MIL_ID DestImageBufIdOrGraListId, MIL_INT64 XPos, MIL_INT64 YPos, MIL_INT64 Width, MIL_INT64 Height, MIL_DOUBLE Angle, MIL_INT64 ControlFlag)
Parameters

ContextGraId

See ContextGraId of the main function for a description.

DestImageBufIdOrGraListId

See DestImageBufIdOrGraListId of the main function for a description.

XPos

See XPos of the main function for a description.

YPos

See YPos of the main function for a description.

Width

See Width of the main function for a description.

Height

See Height of the main function for a description.

Angle

See Angle of the main function for a description.

ControlFlag

See ControlFlag of the main function for a description.

Compilation information
Header Include mil.h.
Library Use mil.lib.
DLL Requires mil.dll.
DEFAULT NONE DEFAULT CENTER AND DIMENSION CORNER AND DIMENSION FILLED