MgraAllocList

This function allocates a graphics list, which holds graphics in vector (mathematical) form. Different graphics lists can coexist; use their identifier to specify which to use or change. When a graphics list is no longer required, you should release its memory, using MgraFree().

The graphics list can be used to annotate the display non-destructively, using MdispControl() with M_ASSOCIATED_GRAPHIC_LIST_ID. Since graphics in a graphics list are vector-based, you can zoom the display without the pixelation (loss of clarity) of the graphics. Also, if you add, modify, or delete graphics, the display can be immediately updated to reflect the changes. To set whether the display is automatically updated, use MdispControl() with M_UPDATE_GRAPHIC_LIST.

The graphics list can also be used to draw destructively in an image, using MgraDraw(). Once drawn, the graphics are raster-based and are part of the image buffer; they cannot be modified. Also, if this annotated image is displayed, zooming it will cause pixelation (loss of clarity) of the graphics and changes in line thickness. Using MgraDraw() is similar to using a graphics function (for example, MgraArc()) to draw destructively in an image.

Graphics can be added to the list using any of the Mgra...() graphics functions, such as MgraArc(). To remove all graphics from the list, use MgraClear(). You can also use MgraControlList() with M_DELETE to remove graphics (one or all) from the list.

When you add graphics to the list, they inherit the current settings of the specified graphics context (as described in MgraAlloc()); however, there is no link between the graphics list and the graphics context. Graphics already in the list are not affected by changes made to the context. To modify or inquire graphics list settings, use MgraControlList() and MgraInquireList().