MgraLines

MIL_ID ContextGraId,	//in
MIL_ID DstImageBufOrListGraId,	//in
MIL_INT NumberOfLinesOrVertices,	//in
const MIL_DOUBLE *XPtr,	//in
const MIL_DOUBLE *YPtr,	//in
const MIL_DOUBLE *X2Ptr,	//in
const MIL_DOUBLE *Y2Ptr,	//in
MIL_INT64 ControlFlag	//in

)

Description

This function draws one or more lines, a polyline, or a polygon destructively (raster-based) in the specified image. Alternatively, this function can add a vector-based version of the lines, polyline, or polygon to the specified 2D graphics list, allowing you to, for example, non-destructively annotate a display without pixelation effects upon scaling.

Lines, polylines, and polygons inherit all the relevant settings of the specified 2D graphics context, such as the foreground color. If part of a line, polyline, or polygon falls outside of the destination image (or, when drawn in a 2D graphics list, the associated display), that part is clipped off.

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

The coordinates of the lines, polyline, or polygon are interpreted with respect to the input coordinate system, specified using MgraControl() or MgraControlList() with M_INPUT_UNITS. Note that if you set your input coordinate system to M_WORLD and you pass MgraLines() an uncalibrated image, the function will generate an error.

To create a single line without the option of creating multiple lines, a polyline, or a polygon, use MgraLine().

Note that prior to MIL 9.0, this function only supported integer positions; the XPtr, YPtr, X2Ptr, and Y2Ptr parameters only accepted arrays of type long. As of MIL 9.0, this function includes support for positions with floating-point precision. To implement this change and maintain backwards compatibility when using a C++ compiler (*.cpp), MgraLines() is available as an inline function which automatically calls MgraLinesDouble(), MgraLinesInt64(), and MgraLinesInt32(), depending on whether XPtr, YPtr, X2Ptr, and Y2Ptr receive arrays of type MIL_DOUBLE, MIL_INT64, or MIL_INT32, respectively. To maintain backwards compatibility when using a C compiler (*.c), MgraLines() maps to MgraLinesInt32() when working on a 32-bit system, or MgraLinesInt64() when working on a 64-bit system; you must explicitly call MgraLinesDouble() to pass XPtr, YPtr, X2Ptr, and Y2Ptr arrays of type MIL_DOUBLE, respectively. If you are an advanced user and want to retrieve a pointer to MgraLines(), you must use the Double, Int64, or Int32 version of this function, since MgraLines() is actually a macro or an overloaded function.

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 (DstImageBufOrListGraId) 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), it is suggested to use the type-specific versions of this particular function, rather than the standard function prototype at the top of this page. An exhaustive list of type-specific versions of this function can be found at the bottom of this page.

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 the identifier of the 2D graphics context, which you have allocated using MgraAlloc().

DstImageBufOrListGraId

Specifies the identifier of a valid image buffer in which to draw the lines, polyline, or polygon or the identifier of a valid 2D graphics list in which to add the lines, polyline, or polygon. 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.

NumberOfLinesOrVertices

Specifies the number of lines to draw or add (M_LINE_LIST), or the number of vertices in the polyline or polygon to draw or add (M_POLYGON or M_POLYLINE), according to the array parameters (XPtr, YPtr, X2Ptr, and Y2Ptr).

When using a standard vector (std::vector) overload function in C++, you can pass M_DEFAULT to this parameter and MIL will automatically determine the size based on the number of items in the vector passed to the XPtr, YPtr, X2Ptr, or Y2Ptr parameter.

XPtr

Accepts the address of one of the following (see the Parameter associations section for specifics on which is expected):

array of type MIL_DOUBLE [optionally, in C++: a reference to a constant std::vector<MIL_DOUBLE> ]

Specifies the address of the array containing the X-coordinate(s) of the start of the lines, or containing the X-coordinates of the vertices in the polyline or polygon, in the input coordinate system. The number of elements in the array should be equal to the NumberOfLinesOrVertices parameter value.