MgraRectAngle

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.