Jump to content

GPIGuide - Graphics Functions

From EDM2

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

GPI Guide and Reference
  1. How to Use the GPI Guide and Reference
  2. Graphics Functions
  3. Data Types
  4. Graphics Orders
  5. Graphics Orders Data Types
  6. Errors
  7. Area and Polygon Primitives
  8. Bit Maps
  9. Creating and Drawing Retained Graphics
  10. Character String Primitives
  11. Clipping and Boundary Determination
  12. Color and Mix Attributes
  13. Correlation
  14. Coordinate Spaces and Transformations
  15. Editing Retained Graphics and Graphics Segments
  16. Fonts
  17. Graphics Attributes
  18. Line and Arc Primitives
  19. Marker Primitives
  20. Matrix Multiplication
  21. Metafiles
  22. Print Job Submission and Manipulation
  23. Presentation Spaces and Device Contexts
  24. Paths
  25. Regions
  26. Notices
  27. Glossary

Coordinates

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.