GPIGuide - Graphics Functions

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

GPI Guide and Reference

How to Use the GPI Guide and Reference Graphics Functions Data Types Graphics Orders Graphics Orders Data Types Errors Area and Polygon Primitives Bit Maps Creating and Drawing Retained Graphics Character String Primitives Clipping and Boundary Determination Color and Mix Attributes Correlation Coordinate Spaces and Transformations Editing Retained Graphics and Graphics Segments Fonts Graphics Attributes Line and Arc Primitives Marker Primitives Matrix Multiplication Metafiles Print Job Submission and Manipulation Presentation Spaces and Device Contexts Paths Regions Notices Glossary

GPI coordinate values that are in world or model space are passed in variables of data type LONG. For a presentation space of format GPIF_LONG (see GpiCreatePS), the signed value must be contained within the low-order 28 bits.

For a presentation space with a format of GPIF_SHORT, the signed value must be contained within the low-order 16 bits. Coordinates that exceed this limit are truncated without error, when stored in a segment. As a consequence, a large positive number may appear as a negative number.

In both instances, after transformation to media space (that is, device space, possibly including a translation for the window origin), coordinate values must be in the range -32 768 through +32 767.

The PMERR_COORDINATE_OVERFLOW error condition occurs if a coordinate is too large to be handled.

Region coordinates must be within the range -32 767 through +32 765.

Matrix Parameter Values

These GPI functions define transforms:

GpiSetSegmentTransformMatrix

GpiSetModelTransformMatrix

GpiCallSegmentMatrix

GpiSetViewingTransformMatrix

GpiSetDefaultViewMatrix

GpiCreatePS

GpiSetPageViewport.

Note

The last two functions define the device transform; the page viewport may be defaulted.

Concatenation of transform matrixes can occur as the transform is specified, for example, if TRANSFORM_ADD is specified. Concatenation also occurs during drawing, between the various transforms in the viewing pipeline.

During the process of concatenation, it is possible for the matrix parameter overflow error, PMERR_INV_MATRIX_ELEMENT, to occur. This error is raised if either of the following conditions occurs for any intermediate value during the concatenation arithmetic (see, for example, GpiSetSegmentTransformMatrix for an explanation of matrix element numbers):

• Any of the matrix elements 1, 2, 4, or 5 is greater than 32 767 or less than -32 768 (ñ1 for a GPIF_SHORT format presentation space), or

• Either of elements 7 or 8 is greater than 134 217 727 (2 -1) or less than -134 217 728 (-2) (greater than 32 767 or less than -32 768 for a GPIF_SHORT format presentation space).

Rounding Errors

In general for graphics coordinates, when non-unity transforms (apart from simple translation) are involved, rounding errors occur. For example, adding the coordinates of one point to a delta value, to produce the coordinates of a second point (all in world coordinates) does not always map to the same device pel as if the computation had been done in device coordinates. Such errors can be avoided if calculations are done in device coordinates, or if there are no scaling (or rotational, or shear) elements in the transforms. Alternatively, the problems can be reduced, though not eliminated, by defining very fine world coordinates.

Drawing Process Check Errors

Some GPI functions involve processing buffers of graphics orders or retained graphics segments (the data for which consists of graphics orders). These functions can give rise to Drawing Process Check (DPC) errors if an order is found that either is not valid in its context or that contains invalid data. If this happens, processing of the function stops and the error is recorded. Note that orders up to the one found to be in error are processed by the function, and output occurs if drawing is being performed.

Each function that can return these errors has Drawing Process Check errors in its error condition list. The full list of DPC errors is:

PMERR_INV_IN_AREA PMERR_INV_IN_PATH

PMERR_INV_IN_ELEMENT

PMERR_ALREADY_IN_ELEMENT

PMERR_STOP_DRAW_OCCURRED (warning)

PMERR_PATH_INCOMPLETE

PMERR_AREA_INCOMPLETE

PMERR_IMAGE_INCOMPLETE

PMERR_INV_ORDER_LENGTH

PMERR_NOT_IN_IMAGE

PMERR_NOT_IN_AREA

PMERR_NOT_IN_ELEMENT

PMERR_NOT_IN_PATH

PMERR_INSUFFICIENT_MEMORY

PMERR_SEG_CALL_STACK_EMPTY

PMERR_SEG_CALL_STACK_FULL

PMERR_TRUNCATED_ORDER

PMERR_CALLED_SEG_NOT_FOUND

PMERR_DYNAMIC_SEG_SEQ_ERROR

PMERR_PROLOG_ERROR

PMERR_INV_IN_VECTOR_SYMBOL

Functions

The GPI Functions are listed here

GPI Function Context

A number of the GPI error conditions indicate that a function has been used in the wrong context. This appendix lists every function and shows, for each one, whether it can be used:

• In a micro presentation space
• While there is an open segment bracket
• While there is an open area bracket
• While there is an open element bracket
• While there is an open path bracket.

A yes (Yes) means that a function can be used; a no (No) means that it cannot. There are some additional qualifiers in the form of superscript numbers. These generally indicate some further restriction on the context in which a function can be called, and are explained at the end of this appendix.

Where GPI Functions Can Be Called

Gpi Function	Micro PS	Segment Bracket	Area Bracket	Element Bracket	Path Bracket
GpiAnimatePalette	Yes(8,9)	Yes	No	Yes	No
GpiAssociate	No	Yes	No(7)	Yes(6)	No(7)
GpiBeginArea	Yes	Yes	No	Yes	No
GpiBeginElement	No	Yes	Yes	No	Yes
GpiBeginPath	Yes	Yes	No	Yes	No
GpiBitBlt	Yes	Yes	No	Yes	No
GpiBox	Yes	Yes	Yes	Yes	Yes
GpiCallSegmentMatrix	No	Yes	Yes	Yes	Yes
GpiCharString	Yes	Yes	No	Yes	Yes
GpiCharStringAt	Yes	Yes	No	Yes	Yes
GpiCharStringPos	Yes	Yes	No	Yes	Yes
GpiCharStringPosAt	Yes	Yes	No	Yes	Yes
GpiCloseFigure	Yes	Yes	No	Yes	Yes
GpiCloseSegment	No	Yes	No(7)	Yes	No(7)
GpiCombineRegion	Yes	Yes	No	Yes	No
GpiComment	Yes	Yes	Yes	Yes	Yes
GpiConvert	Yes	Yes	Yes	Yes	Yes
GpiConvertWithMatrix	Yes	Yes	Yes	Yes	Yes
GpiCopyMetaFile	Yes	Yes	Yes	Yes	Yes
GpiCorrelateChain	No	Yes	No	No	No
GpiCorrelateFrom	No	Yes	No	No	No
GpiCorrelateSegment	No	Yes	No	No	No
GpiCreateBitmap	Yes	Yes	Yes	Yes	Yes
GpiCreateLogColorTable	Yes	Yes	No	Yes	No
GpiCreateLogFont	Yes	Yes	No	No	Yes
GpiCreatePalette	Yes	Yes	Yes	Yes	Yes
GpiCreatePS	-	-	-	-	-
GpiCreateRegion	Yes	Yes	No	Yes	No
GpiDeleteBitmap	Yes	Yes	Yes	Yes	Yes
GpiDeleteElement	No	Yes(3)	Yes(3)	No	Yes(3)
GpiDeleteElementRange	No	Yes(3)	Yes(3)	No	Yes(3)
GpiDeleteElementsBetweenLabels	No	Yes(3)	Yes(3)	No	Yes(3)
GpiDeleteMetaFile	Yes	Yes	Yes	Yes	Yes
GpiDeletePalette	Yes(9)	Yes	Yes	Yes	Yes
GpiDeleteSegment	No	Yes	Yes	Yes	Yes
GpiDeleteSegments	No	Yes	Yes	Yes	Yes
GpiDeleteSetId	Yes	Yes	No	Yes	Yes
GpiDestroyPS	Yes(1)	Yes	Yes	Yes	Yes
GpiDestroyRegion	Yes	Yes	No	Yes	No
GpiDrawBits	Yes(10)	Yes	Yes	Yes	Yes
GpiDrawChain	No	Yes	No	No	No
GpiDrawDynamics	No	Yes	No	No	No
GpiDrawFrom	No	Yes	No	No	No
GpiDrawSegment	No	Yes	No	No	No
GpiElement	No	Yes	Yes	No	Yes
GpiEndArea	Yes	Yes	Yes	Yes	No
GpiEndElement	No	Yes	Yes	Yes	Yes
GpiEndPath	Yes	Yes	No	Yes	Yes
GpiEqualRegion	Yes	Yes	No	Yes	No
GpiErase	Yes	Yes	No	Yes	No
GpiErrorSegmentData	No	Yes	Yes	Yes	Yes
GpiExcludeClipRectangle	Yes	Yes	No	Yes	No
GpiFillPath	Yes	Yes	No	Yes	No
GpiFullArc	Yes	Yes	Yes	Yes	Yes
GpiGetData	No	Yes(5)	Yes	Yes	Yes
GpiImage	Yes	Yes	No	Yes	No
GpiIntersectClipRectangle	Yes	Yes	No	Yes	No
GpiLabel	No	Yes	Yes	No	Yes
GpiLine	Yes	Yes	Yes	Yes	Yes
GpiLoadBitmap	Yes	Yes	Yes	Yes	Yes
GpiLoadFonts	Yes	Yes	Yes	Yes	Yes
GpiLoadMetaFile	Yes	Yes	Yes	Yes	Yes
GpiLoadPublicFonts	Yes	Yes	Yes	Yes	Yes
GpiMarker	Yes	Yes	No	Yes	Yes
GpiModifyPath	Yes	Yes	No	Yes	No
GpiMove	Yes	Yes	Yes	Yes	Yes
GpiOffsetClipRegion	Yes	Yes	No	Yes	No
GpiOffsetElementPointer	No	Yes(3)	Yes(3)	No	Yes(3)
GpiOffsetRegion	Yes	Yes	No	Yes	No
GpiOpenSegment	No	No	No(7)	Yes(6)	No(7)
GpiOutlinePath	Yes	Yes	No	Yes	No
GpiPaintRegion	Yes	Yes	No	Yes	No
GpiPartialArc	Yes	Yes	Yes	Yes	Yes
GpiPathToRegion	Yes	Yes	Yes	Yes	No
GpiPlayMetaFile	Yes	No	No	No	No
GpiPointArc	Yes	Yes	Yes	Yes	Yes
GpiPolyFillet	Yes	Yes	Yes	Yes	Yes
GpiPolyFilletSharp	Yes	Yes	Yes	Yes	Yes
GpiPolygons	Yes	Yes	No	Yes	No
GpiPolyLine	Yes	Yes	Yes	Yes	Yes
GpiPolyLineDisjoint	Yes	Yes	Yes	Yes	Yes
GpiPolyMarker	Yes	Yes	No	Yes	Yes
GpiPolySpline	Yes	Yes	Yes	Yes	Yes
GpiPop	No	Yes	Yes	Yes	Yes
GpiPtInRegion	Yes	Yes	No	Yes	No
GpiPtVisible	Yes	Yes	No	Yes	No
GpiPutData	No	Yes	Yes	Yes	Yes
GpiQueryArcParams	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryAttrMode	No	Yes	Yes	Yes	Yes
GpiQueryAttrs	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryBackColor	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryBackMix	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryBitmapBits	Yes	Yes(4)	No	Yes	No
GpiQueryBitmapDimension	Yes	Yes	Yes	Yes	Yes
GpiQueryBitmapHandle	Yes	Yes	Yes	Yes	Yes
GpiQueryBitmapInfoHeader	Yes	Yes	Yes	Yes	Yes
GpiQueryBitmapParameters	Yes	Yes	Yes	Yes	Yes
GpiQueryBoundaryData	Yes	Yes	Yes	Yes	Yes
GpiQueryCharAngle	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharBox	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharBreakExtra	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharDirection	Yes	Yes	No	Yes	Yes
GpiQueryCharExtra	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharMode	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharSet	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharShear	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharStringPos	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryCharStringPosAt	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryClipBox	Yes	Yes	Yes	Yes	Yes
GpiQueryClipRegion	Yes	Yes	Yes	Yes	Yes
GpiQueryColor	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryColorData	Yes	Yes	Yes	Yes	Yes
GpiQueryColorIndex	Yes	Yes	Yes	Yes	Yes
GpiQueryCp	Yes	Yes	Yes	Yes	Yes
GpiQueryCurrentPosition	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryDefArcParams	Yes	Yes	Yes	Yes	Yes
GpiQueryDefAttrs	Yes	Yes	Yes	Yes	Yes
GpiQueryDefaultViewMatrix	Yes	Yes	Yes	Yes	Yes
GpiQueryDefCharBox	Yes	Yes	Yes	Yes	Yes
GpiQueryDefTag	Yes	Yes	Yes	Yes	Yes
GpiQueryDefViewingLimits	Yes	Yes	Yes	Yes	Yes
GpiQueryDevice	Yes	Yes	Yes	Yes	Yes
GpiQueryDeviceBitmapFormats	Yes	Yes	Yes	Yes	Yes
GpiQueryDrawControl	Yes	Yes	Yes	Yes	Yes
GpiQueryDrawingMode	No	Yes	Yes	Yes	Yes
GpiQueryEditMode	No	Yes	Yes	Yes	Yes
GpiQueryElement	No	Yes(3)	Yes(3)	Yes(3)	Yes(3)
GpiQueryElementPointer	No	Yes(3)	Yes(3)	Yes(3)	Yes(3)
GpiQueryElementType	No	Yes(3)	Yes(3)	Yes(3)	Yes(3)
GpiQueryFaceString	Yes	Yes	Yes	Yes	Yes
GpiQueryFontAction	Yes	Yes	Yes	Yes	Yes
GpiQueryFontMetrics	Yes	Yes	Yes	Yes	Yes
GpiQueryFonts	Yes	Yes	Yes	Yes	Yes
GpiQueryFullFontFileDescs	Yes	Yes	Yes	Yes	Yes
GpiQueryGraphicsField	Yes	Yes	Yes	Yes	Yes
GpiQueryInitialSegmentAttrs	No	Yes	Yes	Yes	Yes
GpiQueryKerningPairs	Yes	Yes	Yes	Yes	Yes
GpiQueryLineEnd	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryLineJoin	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryLineType	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryLineWidth	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryLineWidthGeom	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryLogColorTable	Yes	Yes	Yes	Yes	Yes
GpiQueryLogicalFont	Yes	Yes	Yes	Yes	Yes
GpiQueryMarker	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryMarkerSet	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryMetaFileBits	Yes	Yes	Yes	Yes	Yes
GpiQueryMetaFileLength	Yes	Yes	Yes	Yes	Yes
GpiQueryMix	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryModelTransformMatrix	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryNearestColor	Yes	Yes	Yes	Yes	Yes
GpiQueryNumberSetIds	Yes	Yes	Yes	Yes	Yes
GpiQueryPageViewport	Yes	Yes	Yes	Yes	Yes
GpiQueryPalette	Yes	Yes	Yes	Yes	Yes
GpiQueryPaletteInfo	Yes	Yes	Yes	Yes	Yes
GpiQueryPattern	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryPatternRefPoint	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryPatternSet	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryPel	Yes	Yes	Yes	Yes	Yes
GpiQueryPickAperturePosition	Yes	Yes	Yes	Yes	Yes
GpiQueryPickApertureSize	Yes	Yes	Yes	Yes	Yes
GpiQueryPS	Yes	Yes	Yes	Yes	Yes
GpiQueryRealColors	Yes	Yes	Yes	Yes	Yes
GpiQueryRegionBox	Yes	Yes	Yes	Yes	Yes
GpiQueryRegionRects	Yes	Yes	Yes	Yes	Yes
GpiQueryRGBColor	Yes	Yes	Yes	Yes	Yes
GpiQuerySegmentAttrs	No	Yes	Yes	Yes	Yes
GpiQuerySegmentNames	No	Yes	Yes	Yes	Yes
GpiQuerySegmentPriority	No	Yes	Yes	Yes	Yes
GpiQuerySegmentTransformMatrix	No	Yes	Yes	Yes	Yes
GpiQuerySetIds	Yes	Yes	Yes	Yes	Yes
GpiQueryStopDraw	No	Yes	Yes	Yes	Yes
GpiQueryTag	No	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryTextAlignment	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryTextBox	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryViewingLimits	Yes	Yes(2)	Yes(2)	Yes(2)	Yes(2)
GpiQueryViewingTransformMatrix	No	Yes	Yes	Yes	Yes
GpiQueryWidthTable	Yes	Yes	Yes	Yes	Yes
GpiRectInRegion	Yes	Yes	No	Yes	No
GpiRectVisible	Yes	Yes	No	Yes	No
GpiRemoveDynamics	No	Yes	No	No	No
GpiResetBoundaryData	Yes	Yes	Yes	Yes	Yes
GpiResetPS	Yes	Yes	Yes(6)	Yes(6)	Yes(6)
GpiRestorePS	Yes	Yes(4)	No	Yes(4)	No
GpiRotate	Yes	Yes	Yes	Yes	Yes
GpiSaveMetaFile	Yes	Yes	Yes	Yes	Yes
GpiSavePS	Yes	Yes(4)	No	Yes(4)	No
GpiScale	Yes	Yes	Yes	Yes	Yes
GpiSelectPalette	Yes	Yes	No	Yes	Yes
GpiSetArcParams	Yes	Yes	Yes	Yes	Yes
GpiSetAttrMode	No	Yes	Yes	Yes	Yes
GpiSetAttrs	Yes	Yes	No	Yes	Yes
GpiSetBackColor	Yes	Yes	No	Yes	No
GpiSetBackMix	Yes	Yes	No	Yes	No
GpiSetBitmap	Yes	Yes	No	Yes	No
GpiSetBitmapBits	Yes	Yes	No	Yes	No
GpiSetBitmapDimension	Yes	Yes	Yes	Yes	Yes
GpiSetBitmapId	Yes	Yes	Yes	Yes	Yes
GpiSetCharAngle	Yes	Yes	No	Yes	Yes
GpiSetCharBox	Yes	Yes	No	Yes	Yes
GpiSetCharBreakExtra	Yes	Yes	Yes	Yes	Yes
GpiSetCharDirection	Yes	Yes	No	Yes	Yes
GpiSetCharExtra	Yes	Yes	Yes	Yes	Yes
GpiSetCharMode	Yes	Yes	No	Yes	Yes
GpiSetCharSet	Yes	Yes	No	Yes	Yes
GpiSetCharShear	Yes	Yes	No	Yes	Yes
GpiSetClipPath	Yes	Yes	No	Yes	No
GpiSetClipRegion	Yes	Yes	No	Yes	No
GpiSetColor	Yes	Yes	No	Yes	Yes
GpiSetCp	Yes	Yes	No	Yes	Yes
GpiSetCurrentPosition	Yes	Yes	Yes	Yes	Yes
GpiSetDefArcParams	Yes	Yes	Yes	Yes	Yes
GpiSetDefAttrs	Yes	Yes	Yes	Yes	Yes
GpiSetDefaultViewMatrix	Yes	Yes	No	Yes	No
GpiSetDefTag	Yes	Yes	Yes	Yes	Yes
GpiSetDefViewingLimits	Yes	Yes	Yes	Yes	Yes
GpiSetDrawControl	Yes	No	No	No	No
GpiSetDrawingMode	No	No	No	No	No
GpiSetEditMode	No	Yes	Yes	No	Yes
GpiSetElementPointer	No	Yes(2)	Yes(2)	No	Yes(2)
GpiSetElementPointerAtLabel	No	Yes(2)	Yes(2)	No	Yes(2)
GpiSetGraphicsField	Yes	Yes	No	Yes	No
GpiSetInitialSegmentAttrs	No	Yes	Yes	Yes	Yes
GpiSetLineEnd	Yes	Yes	No	Yes	Yes
GpiSetLineJoin	Yes	Yes	No	Yes	Yes
GpiSetLineType	Yes	Yes	No	Yes	Yes
GpiSetLineWidth	Yes	Yes	No	Yes	Yes
GpiSetLineWidthGeom	Yes	Yes	No	Yes	No
GpiSetMarker	Yes	Yes	No	Yes	Yes
GpiSetMarkerBox	Yes	Yes	No	Yes	Yes
GpiSetMarkerSet	Yes	Yes	No	Yes	Yes
GpiSetMetaFileBits	Yes	Yes	Yes	Yes	Yes
GpiSetMix	Yes	Yes	No	Yes	Yes
GpiSetModelTransformMatrix	Yes	Yes	Yes	Yes	Yes
GpiSetPageViewport	Yes	Yes	No	Yes	No
GpiSetPaletteEntries	Yes(8)	Yes	No	Yes	Yes
GpiSetPattern	Yes	Yes	No	Yes	No
GpiSetPatternRefPoint	Yes	Yes	No	Yes	No
GpiSetPatternSet	Yes	Yes	No	Yes	No
GpiSetPickAperturePosition	Yes	Yes	No	Yes	No
GpiSetPickApertureSize	Yes	Yes	No	Yes	No
GpiSetPS	Yes	Yes	No	Yes	No
GpiSetRegion	Yes	Yes	Yes	Yes	Yes
GpiSetSegmentAttrs	Yes	Yes	No	Yes	No
GpiSetSegmentPriority	No	Yes	Yes	Yes	Yes
GpiSetSegmentTransformMatrix	No	No(5)	Yes	No	Yes
GpiSetStopDraw	No	Yes	Yes	Yes	Yes
GpiSetTag	No	Yes	Yes	Yes	Yes
GpiSetTextAlignment	No	Yes	No	Yes	Yes
GpiSetViewingLimits	Yes	Yes	Yes	Yes	Yes
GpiSetViewingTransformMatrix	Yes	Yes	No	Yes	No
GpiStrokePath	No	No	No	Yes	No
GpiTranslate	Yes	Yes	No	Yes	No
GpiUnloadFonts	Yes	Yes	Yes	Yes	Yes
GpiUnloadPublicFonts	Yes	Yes	Yes	Yes	Yes
GpiUnloadPublicFonts	Yes	Yes	Yes	Yes	Yes
GpiWCBitBlt	Yes	Yes	Yes	Yes	Yes

Notes

1. Not valid to a cached micro presentation space.
2. Valid only when the actual drawing mode is draw or draw-and-retain. The actual drawing mode is determined as shown in the following table:

The Current Drawing Mode

GpiSetDrawingMode parameter	Context
	Chained Segment	Unchained Segment	Outside Segment
DM_DRAWANDRETAIN	draw-and-retain	retain	draw
DM_RETAIN	retain	retain	draw
DM_DRAW	draw	retain	draw

For example, if the current drawing mode parameter is DM_RETAIN, and primitives are being drawn outside a segment, then the actual drawing mode is draw.

1. Valid only when the actual drawing mode (see note 2) is retain.
2. Valid only when the actual drawing mode (see note 2) is draw.
3. Not valid if the specified segment is the current open segment.
4. Bracket (path, element, or area) is ended without error.
5. Severity is Warning.
6. If associated with a metafile, only the final values are recorded in the metafile.
7. Palette must not be current.
8. Device context must be able to support bit map operations.