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:

           Only valid value. 
       BOUNDARY (GBIT1)
           Boundary-line draw indicator:

           Do not draw boundary lines
           Draw boundary lines. 
       INSIDE (GBIT1)
           Mode shading:

           Alternate mode
           Winding mode. 
       RES2 (GBIT5)
           Reserved value, must be 0.

Set Pattern Set/Push and Set Pattern Set

Set Pattern Symbol/Push and Set Pattern Symbol Set Pick Identifier/Push and Set Pick Identifier Set Segment Boundary Set Stroke Line Width/Push and Set Stroke Line Width Set Text Alignment/Push and Set Text Alignment Set Viewing Transform Set Viewing Window/Push and Set Viewing Window Sharp Fillet at Given Position/Sharp Fillet at Current Position