MgraRectAngle

See also

User Guide:

Defining and adding models to your Model Finder context Defining and adding models to your Pattern Matching context Drawing graphics

Reference:

MbufAlloc1d MbufInquire MgraAlloc MgraAllocList MgraControl MgraControlList MgraInquire MgraInquireList MgraRect MgraRectFill MthrAlloc

Availability

Available in MIL-Lite

Available in MIL

Available on Windows

Available on Linux

Not supported on:

Not supported on Matrox Indio (Update 53 or Update 68) (w)

Not supported on Matrox Concord PoE with ToE (Update 82) (z)

Fully supported on:

Fully supported on Host system (a)

Fully supported on Matrox GigE Vision driver (MIL 10, Update 25, Update 54, or Update 85)* (c)

Fully supported on Matrox Morphis (g)

Fully supported on Matrox Morphis QxT (h)

Fully supported on Matrox Orion HD (i)

Fully supported on Matrox Radient eCL (j)

Fully supported on Matrox Radient eV-CXP (MIL 10 or Update 29)* (k)

Fully supported on Matrox Solios eA/XA (l)

Fully supported on Matrox Solios ecl/xcl/ev-cl (m)

Fully supported on Matrox USB3 Vision driver (Update 19) (o)

Fully supported on Matrox RadientPro-CL (Update 7) (p)

Fully supported on Matrox Radient eV-CL (Update 27 or 74) (r)

Fully supported on Matrox Iris GTR (Update 28 or Update 68) (t)

Fully supported on Matrox Clarity UHD (Update 36 or 76) (u)

Fully supported on Matrox GenTL driver (Update 34) (v)

Fully supported on Matrox Rapixo CXP (Update 75 or Update 84) (y)

Fully supported on Matrox Rapixo CL Pro (Update 96) (aa)

* Refer to the MIL system-specific information
in the MIL Reference for the minimum update required.

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/GPm

Available on Matrox Supersight

Function map

Examples

Function Map

Table:

For specifying the 2D graphics context

- DestImageBufIdOrGraListId

- XPos

- YPos

- Width

- Height

- Angle

- ControlFlag

Table:	For specifying how to draw or add the rectangle
+ combination:	For specifying whether the rectangle is filled

Type-specific versions of the function when using a C compiler under 64-bit

Compilation information

Synopsis

Draw a rectangle in an image with optional rotation and fill color, or add it to a 2D 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 2D 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 2D 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 2D graphics context settings, use MgraControl() or MgraInquire(). To modify or inquire 2D 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 26: 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 2D 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 2D 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.

Note that when using a C compiler (not a C++ or other compiler) in 64-bit mode, MgraRectAngle() internally calls the MIL_DOUBLE version of this function (MgraRectAngleDouble()). If you need to pass integer values, call the MIL_INT64 version of this function (MgraRectAngleInt64()).

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

ContextGraId

Specifies the identifier of the 2D graphics context. This parameter must be set to one of the following values:

For specifying the 2D graphics context
Value	Description
M_DEFAULT	Specifies that the default 2D graphics context of the current MIL application is used. Note that there is a different default 2D graphics context for each thread. (summarize) Specifies that the default 2D graphics context of the current MIL application is used. (more details...)
MIL 2D graphics context identifier	Specifies a valid 2D 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 2D graphics list in which to add the rectangle. You must have allocated the image buffer or the 2D 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 2D graphics list.

For specifying how to draw or add the rectangle
Value	Description
M_DEFAULT	Same as M_CORNER_AND_DIMENSION.
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) Specifies that the rectangle is drawn according to its center position, as defined by the specified coordinates. (more details...)
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) Specifies that the rectangle is drawn according to the position of its top-left corner, as defined by the specified coordinates. (more details...)

Combination value 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.

For specifying whether the rectangle is filled
Combination value	Description
M_FILLED	Specifies that the rectangle is filled with specified foreground color (MgraControl() or MgraControlList() with M_COLOR).

Type-specific versions of the function when using a C compiler under 64-bit

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)

Details

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)

Details

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.