GPIGuide - Graphics Attributes

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

Every graphics presentation space has a set of graphics attributes. A normal presentation space has a larger set of graphics attributes than a micro or cached micro presentation space. (Segment-related attributes, for example, do not apply in micro presentation spaces.) These attributes all have default values, which means that they always have an effect on graphics, even if you have not explicitly specified their values. The attributes can be broken into two general groups. The first group comprises those attributes that form a part of the picture and that can vary as the picture is drawn. These are:

• All primitive attributes
• The segment attributes
• The primitive tag
• The current position
• The viewing window
• The clipping path
• The model and segment transformations
• The viewing transformation.

With the exception of the segment attributes and the viewing transformation, these attributes are reset to their default values at the start of a root segment, unless the fast-chaining attribute is set. If the fast-chaining attribute is set, their values cannot be guaranteed. You should, therefore, explicitly set any attribute values required in the segment. Similarly, the values of these attributes cannot be guaranteed following a call to:

• Any GpiDraw... function
• Any GpiCorrelate... function
• GpiCallSegmentMatrix
• GpiCloseSegment

Therefore, if any of these functions is followed by primitives outside a segment, you should explicitly set required attribute values. When GpiCloseSegment is followed by GpiOpenSegment (and also between any two segments in the chain), the fast-chaining attribute determines what happens to the current values of these attributes. The viewing transformation and the segment attributes are unaffected by fast-chaining.

These attributes take effect when graphics are sent to an output device, not when graphics are defined. For this reason, the calls to GpiQuery that retrieve the current values of these attributes are invalid in retain mode. The majority of the group-one attribute-setting functions cause graphics orders to be added to the current segment.

The second group of attributes defines the environment in which the picture is drawn. These attributes do not normally vary as the picture is drawn, but have an overall effect on the result of any drawing or correlation operation. This group includes:

• Default viewing transformation
• Page viewport
• Graphics field
• Clipping region
• Pick-aperture size
• Drawing controls

The functions to GpiQuery that retrieve the current values of these attributes are valid in all drawing modes. None of the group-two attribute-setting functions causes graphics orders to be added to the current segment.

The following table lists the graphics attributes, identifies the GPI function or functions that you use to change current settings, and lists the default value of each one. Note that these default values are the initial settings. The table also indicates whether the attribute is a group-one or a group-two attribute.

Graphics Attribute	GPI Function	Default Value	Group One	Group Two
Arc parameters	GpiSetArcParams	(1,1,0,0)	Yes
Foreground color	GpiSetColor(1)	CLR_DEFAULT (device-dependent)	Yes
Foreground mix	GpiSetMix(1)	FM_DEFAULT (overpaint)	Yes
Background color	GpiSetBackColor(1)	CLR_DEFAULT (device-dependent)	Yes
Background mix	GpiSetBackMix(1)	BM_DEFAULT (leave-alone)	Yes
Character angle	GpiSetCharAngle(1)	(1,0)	Yes
Character box	GpiSetCharBox(1)	Device-dependent	Yes
Character direction	GpiSetCharDirection(1)	CHDIRN_DEFAULT (left to right)	Yes
Character mode	GpiSetCharMode(1)	CM_DEFAULT (mode 1)	Yes
Character set	GpiSetCharSet(1)	LCID_DEFAULT (system font)	Yes
Character shear	GpiSetCharShear(1)	(0,1)	Yes
Line end	GpiSetLineEnd(1)	LINEEND_DEFAULT (flat)	Yes
Line join	GpiSetLineJoin(1)	LINEJOIN_DEFAULT (beveled)	Yes
Line type	GpiSetLineType(1)	LINETYPE_DEFAULT (solid)	Yes
Line width	GpiSetLineWidth(1)	LINEWIDTH_DEFAULT (1.0)	Yes
Geometric line width	GpiSetLineWidthGeom(1)	1	Yes
Marker	GpiSetMarker(1)	MARKSYM_DEFAULT (cross)	Yes
Marker box	GpiSetMarkerBox(1)	Device-dependent	Yes
Marker set	GpiSetMarkerSet(1)	LCID_DEFAULT (system marker set)	Yes
Pattern	GpiSetPattern(1)	PATSYM_DEFAULT (solid)	Yes
Pattern reference point	GpiSetPatternRefPoint(1)	(0,0)	Yes
Pattern set	GpiSetPatternSet(1)	LCID_DEFAULT (system pattern set)	Yes
Model transformation	GpiSetModelTransformMatrix	Identity	Yes
Instance transformation	GpiCallSegmentMatrix	Identity	Yes
Segment transformation	GpiSetSegmentTransformMatrix	Identity	Yes
Viewing transformation	GpiSetViewingTransformMatrix	Identity	Yes
Default viewing transformation	GpiSetDefaultViewMatrix	Identity		Yes
Page viewport	GpiSetPageViewport	Device-dependent		Yes
Clipping path	GpiSetClipPath	No clipping	Yes
Viewing window	GpiSetViewingLimits	No clipping	Yes
Graphics field	GpiSetGraphicsField	No clipping		Yes
Clipping region	GpiSetClipRegion	No clipping		Yes
Tag	GpiSetTag	0	Yes
Segment attributes	GpiSetInitialSegmentAttrs, GpiSetSegmentAttrs	ATTR_DETECTABLE - OFF ATTR_VISIBLE - ON ATTR_CHAINED - ON ATTR_DYNAMIC - OFF ATTR_FASTCHAIN - ON ATTR_PROP_DETECTABLE - ON ATTR_PROP_VISIBLE - ON	Yes
Pick-aperture size	GpiSetPickAperturePosition	Device-dependent		Yes
Current position	GpiSetCurrentPosition, GpiMove	(0,0)	Yes
Drawing controls	GpiSetDrawControl	DCTL_ERASE - OFF DCTL_DISPLAY - ON DCTL_BOUNDARY - OFF DCTL_DYNAMIC - OFF DCTL_CORRELATE - OFF		Yes

Notes

1. Can also be set using GpiSetAttrs.
2. Is also updated indirectly by most primitive-drawing functions.

Each of the following functions causes all group-one and group-two graphics attributes to be set to their default values:

• GpiCreatePS
• GpiSetPS
• GpiResetPS, if GRES_ALL or GRES_SEGMENTS is specified
• WinGetPS
• WinGetScreenPS
• WinBeginPaint, with a NULL presentation space handle

In specific circumstances, some of the GPI functions modify the group-one attributes and thus make their values unpredictable. Therefore, when you call any of these functions, you should respecify attribute values that have a particular importance to your application. For example, if the current foreground color is CLR_RED before you call GpiDrawChain, you cannot always rely on the current color remaining CLR_RED when GpiDrawChain completes. If you want to continue working in red, respecify the color when GpiDrawChain completes. In general, the functions that affect group-one-attribute values are those related to the drawing and correlation of retained graphics, and to the creation, closing, and deletion of graphics segments.

With the exception of the viewing transformation and the segment attributes, the default values of these attributes apply to all primitive-drawing that occurs outside a segment bracket.

The following function sets the group-one attributes to their default values, and in addition sets the current clipping region and page viewport to their default values:

• GpiAssociate

Each of the following functions makes the group-one-attribute values unpredictable:

• GpiCloseSegment
• GpiCorrelateChain
• GpiCorrelateFrom
• GpiCorrelateSegment
• GpiErase
• GpiCallSegmentMatrix
• GpiDrawDynamics
• GpiRemoveDynamics

Note: In the last two functions (GpiDrawDynamics and GpiRemoveDynamics), the foreground-mix value is always set to FM_XOR, and the background-mix value is always set to BM_LEAVEALONE.

Each of the following functions makes group-one-attribute values unpredictable if a segment to be deleted is open when the function is called:

• GpiDeleteSegments
• GpiDeleteSegment

Each of the following functions makes group-one-attribute values unpredictable if there is no open segment when the function is called:

• GpiDrawChain
• GpiDrawFrom
• GpiDrawSegment

If there is an open segment when any of these functions is called, and that segment was the last one drawn, then group-one-attribute values are unaffected. If, however, dynamic segments were caused to be redrawn by the same function, group-one-attribute values are made unpredictable. This occurs because dynamic segments are always drawn after nondynamic segments.