GPIGuide - Graphics Orders

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

This section describes the format of the graphics orders.

Graphics orders are used in the following circumstances:

• Using GpiGetData or GpiPutData functions for bulk transfer of part or all of graphics segment data (unless this is simply being copied without being changed).
• Editing segments with GpiQueryElement and GpiElement.
• Generating metafiles (other than through the Presentation Manager API), or examining their contents. The data part of Graphics Data structured fields within the metafile (see "Metafile Data Format" in the Presentation Manager Programming Reference) consists of graphics orders.

When primitive or attribute functions (plus certain other functions) are specified at the programming interface, and the drawing mode (see GpiSetDrawingMode) is set to drawandretain, graphics orders are constructed and placed in the current graphics segment. One API call often causes a single order to be generated. Sometimes, however, several orders are necessary: an example of this is where a GpiPolyLine call is issued, which specifies more strokes than there is room for, in a single order.

In either case, the order or orders generated by a single API call comprise a single element, unless the application specifically starts an element using the GpiBeginElement function. In this case the element consists of all of the orders generated between this and the following GpiEndElement function. A GpiQueryElement function returns the orders that comprise an element; the application may edit these, and return them to the segment with GpiElement. The Begin Element - End Element orders that surround a multi-order element in the segment are never passed between the application and the system on GpiQueryElement and GpiElement functions. No double word or word alignment can be assumed for orders either within segments or during editing

Introduction to Graphics Orders

In the retain and draw-and-retain drawing modes, specific GPI functions (primitive-drawing and attribute-setting functions, plus some others) cause graphics orders to be stored in the current segment. A graphics order is a sequence of one or more bytes of data that describe a graphics function. There is typically a one-to-one correspondence between a GPI function and a graphics order. You do not need to understand the various formats and contents of the graphics orders, unless:

• You are using GpiGetData or GpiPutData for bulk transfer of data that you want to edit.
• You are simply copying data from one segment to another.
• You are using GpiElement to add data to a segment, or GpiQueryElement to retrieve data from a segment.
• You are examining the contents of a metafile.

Both the graphics orders and the metafile structure are described in the Presentation Manager. This appendix describes the header file PMORD.H, which has been provided to allow you to manipulate the graphics orders more easily.

The Graphics-Orders Header File (PMORD.H)

A set of helper constants, macros, and structures has been provided to help you decode and encode graphics orders. These items are defined in the header file PMORD.H.

There are four types of graphics orders. The first byte of each order, regardless of the graphics-order type, is the order code itself, which either partially or completely describes what follows. Depending on the order type, the graphics order can contain further information.

The four types of graphics order are:

1-Byte Order

The 1-byte order comprises a single byte:

   BYTE 1 : order code.

2-Byte Order

The 2-byte order consists of two bytes:

   BYTE 1 : order code
   BYTE 2 : associated value.

Long Order

The long order can comprise up to 257 bytes of information:

   BYTE 1     : order code
   BYTE 2     : length of order (0 to 255)
   BYTE 3-257 : associated value bytes depending on the order code.

There is a special long order (Escape) where:

   BYTE 3     : escape type
   BYTE 4     : escape identifier
   BYTE 5-257 : associated value bytes depending on the escape identifier.

Very Long Order

The very long order can comprise up to 65537 bytes of information:

   BYTE 1       : order code
   BYTE 2       : order qualifier
   BYTE 3       : length of order (most significant byte)
   BYTE 4       : length of order (least significant byte - length of order is 0 to 65535)
   BYTE 5-65537 : associated value bytes depending on the order qualifier.

There is a special very long order (Escape) where:

   BYTE 5       : escape type
   BYTE 6       : escape identifier
   BYTE 7-65537 : associated value bytes depending on the escape identifier.

Decoding Graphics Orders

The recommended way of decoding a buffer of graphics orders (in C language) is to use a pointer to address the first byte of the buffer, and then retrieve the graphics order it contains. To discover which of the four types of order you have, use the following macros:

• BYTE_ORDER (1-byte order)
• SHORT_ORDER (2-byte order)
• LONG_ORDER (long order)
• VLONG_ORDER (very long order).

These macros are defined in the header file PMORD.H. Each macro processes a single byte of data and returns a Boolean value (zero or nonzero). A zero value means that the order is not of that type. When you know the graphics-order type, you can establish the length of the order, and add the length to the pointer. You can then retrieve the next order in the buffer, and repeat the process until all data has been retrieved.

You can decode the graphics-order data itself by providing a routine for each of the order types, or a routine for each individual order:

• For a 1-byte graphic order, the decoding routine should simply return a length of 1.
• For a 2-byte graphic order, the decoding routine can use the overlay structure ORDER to decode the data. The routine should return a length of 2.
• For a long order, the decoding routine can use the overlay structure LORDER to decode the data. The length of the data is a variable value.
• For a very long order, the decoding routine can use the overlay structure VORDER to decode the data. The length of the data is a variable value.

The overlay structures ORDER, LORDER, and VORDER are defined in the header file PMORD.H.

You can build graphics orders using the same structures and order types that are used for decoding graphics orders.

Naming Conventions

The names of the graphics-order codes are in the form OCODE_Gxxx. The Gxxx abbreviation is the name of the individual order, and can be used for types, structures, and constants directly related to that order. In the header file, there is a comment on the same line as each of the orders that describes the order. For example, the Begin Area order (GBAR) is described in the header file as follows:

#define OCODE_GBAR     0x68  /* Begin area    */
#define GBAR_BOUNDARY  0xC0

Note:

In some structures, an S or an L is added to the name to differentiate between the short-coordinate form (16-bit) and the long-coordinate form (32-bit). For example, the Set Arc Parameters order (GSAP) is as follows:

#define OCODE_GSAP     0x22
#define OCODE_GPSAP    0x62

  typedef struct _ORDERS_GSAP {
    SHORT  p;
    SHORT  q;
    SHORT  r;
    SHORT  s;
  } ORDERS_GSAP;

  typedef struct _ORDERL_GSAP {
    LONG   p;
    LONG   q;
    LONG   r;
    LONG   s;
  } ORDERL_GSAP;

In this example, the structures ORDERS_GSAP and ORDERL_GSAP are shared by GSAP (set arc parameters) and GPSAP (push and set arc parameters). As a rule, there is structure sharing between the set and push-and-set forms of graphics orders.

There is structure-sharing between the current-position and the given-position forms of some orders. For example, the orders GCARC (arc at current position) and GARC (arc at given position) share a structure.

Arc at a Given Position/Arc at Current Position

Syntax

This order constructs an arc starting at a given position.

Arc at a Given Position (GARC)
X'C6' (LEN, P0, P1, P2)

Arc at Current Position (GCARC)
X'86' (LEN, P1, P2) 

Parameters

LEN (GLENGTH1)

Length of following data.

P0 (GPOINT)

Coordinate data of start point.

This parameter is only present in a Arc at a Given Position order.

P1 (GPOINT)

Coordinate data of intermediate point.

P2 (GPOINT)

Coordinate data of end point.

Begin Area

Syntax

This order indicates the start of a set of primitives that define an area boundary.

Begin Area (GBAR)
X'68' (FLAGS)

Parameters

FLAGS

Internal flags.

RES1 (GBIT1)

Reserved for migration:

1 Only valid value.

BOUNDARY (GBIT1)

Boundary-line draw indicator:

0 Do not draw boundary lines

1 Draw boundary lines.

INSIDE (GBIT1)

Mode shading:

0 Alternate mode

1 Winding mode.

RES2 (GBIT5)

Reserved value, must be 0.

Begin Element

Syntax

This order indicates the beginning of a set of primitives that define an element.

Begin Element (GBEL)

X'D2' (LEN, TYPE, DESCR)

Parameters

LEN (GLENGTH1)

Length of following data.

TYPE (GLONG)

Element type code.

Possible values are described in the following list:

0x0000FD01 Line bundle

0x0000FD02 Character bundle

0x0000FD03 Marker bundle

0x0000FD04 Area bundle

0x0000FD05 Image bundle

0x00000007 Call segment

0x00000081 Polyline

0x00000085 Polyfillet

0x000000A4 Polyfillet sharp

0x000000A5 Polyspline

0x00000082 Polymarker

0x00000087 Full arc

0x00000091 Image

0x000000B1 Character string at current position

0x000000F1 Character string at given position

0x81xxxxxx-0xFFxxxxxx Indicates user defined elements

Other Reserved values.

DESCR (GUNDF)

Element description data.

This is optional.

Begin Image at Given Position/Begin Image at Current Position

Syntax

These orders identify the start of an image definition at a given position or at the current position.

Begin Image at Given Position (GBIMG)

X'D1' (LEN, P0, FORMAT, RES, WIDTH, HEIGHT)

Begin Image at Current Position (GCBIMG)

X'91' (LEN, FORMAT, RES, WIDTH, HEIGHT)

Parameters

LEN (GLENGTH1)

Length of following data.

0x06 Only valid value.

P0 (GPOINT)

Point at which the image is to be placed.

This parameter is only present in a Begin Image at Given Position order.

FORMAT (GBIT8)

Format of the image data.

0x00 One bit in the data represents one image point on the usable area.

RES (GBIT8)

Reserved.:0x00 Only valid value.

WIDTH (GUSHORT370)

Width of the image data.

This is the width in pels.

0x00-0x07 Valid range of values.

HEIGHT (GUSHORT370)

Height of the image data.

This is the height in pels.

Begin Path

Syntax

This order sets the drawing process into path state.

Begin Path (GBPTH)
X'D0' (LEN, RES, PTHID)

Parameters

LEN (GLENGTH1)

Length of following data.

0x06 Only valid value.

RES (GBIT16)

Reserved.

0x0000 Only valid value.

PTHID (GLONG)

Path identifier.

0x00000001-0xFFFFFFFF Valid path identifiers.

Bezier Curve at Given Position/Bezier Curve at Current Poition

Syntax

This order generates a curve that starts at a given position.

Bezier Curve at Given Position (GBEZ) 
X'E5' (LEN, P0, P1, P2, P3, P4, P5, P6, PN-2, PN-1, PN) 

Bezier Curve at Current Poition (GCBEZ) 
X'A5' (LEN, P1, P2, P3, P4, P5, P6, PN-2, PN-1, PN) 

Parameters

LEN (GLENGTH1)

Length of following data.

P0 (GPOINT)

Coordinate data of first curve start.

This parameter is only present in a Bezier Curve at Given Position order.

P1 (GPOINT)

Coordinate data of first curve, first control point.

P2 (GPOINT)

Coordinate data of first curve, second control point.

P3 (GPOINT)

Coordinate data of first curve end.

P4 (GPOINT)

Coordinate data of second curve, first control point.

P5 (GPOINT)

Coordinate data of second curve, second control point

P6 (GPOINT)

Coordinate data of second curve end.

PN-2 (GPOINT)

Coordinate data of final curve, first control point

PN-1 (GPOINT)

Coordinate data of final curve, second control point

PN (GPOINT)

Coordinate data of final curve end.