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.
Retrieved from "https://www.edm2.com/index.php?title=GPIGuide_-_Graphics_Functions&oldid=81966"