MgraDots

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

Dots are based on the points positioned at PosXArrayPtr and PosYArrayPtr. The dots inherit all the relevant settings of the specified graphics context, such as the foreground color (see MgraAlloc() for default context settings). If part of the dots fall 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().

The coordinates of the dots 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 MgraDots() an uncalibrated image, the function will generate an error.

To create a single dot without the option of creating multiple dots, use MgraDot().

Note that prior to MIL 9.0, this function only supported integer positions; the PosXArrayPtr and PosYArrayPtr 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), MgraDots() is available as an inline function which automatically calls MgraDotsDouble(), MgraDotsInt32(), and, MgraDotsInt64() depending on whether PosXArrayPtr and PosYArrayPtr receive arrays of type MIL_DOUBLE, MIL_INT32, or MIL_INT64, respectively. To maintain backwards compatibility when using a C compiler (*.c), MgraDots() maps to MgraDotsInt32() when working on a 32-bit system, or MgraDotsInt64() when working on a 64-bit system; you must explicitly call MgraDotsDouble() to pass PosXArrayPtr and PosYArrayPtr arrays of type MIL_DOUBLE. If you are an advanced user and want to retrieve a pointer to MgraDots(), you must use the Double, Int64, or Int32 version of this function, since MgraDots() 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 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.