GPIGuide - Graphics Orders: Difference between revisions
| Line 468: | Line 468: | ||
===Comment=== | ===Comment=== | ||
This order enables data to be stored within a segment. | |||
====Syntax==== | |||
;Comment (GCOMT) | |||
: X'01' (LEN, DATA[LEN]) | |||
====Parameters==== | |||
;LEN (GLENGTH1) | |||
: Length of following data. | |||
;DATA[LEN] (GBIT8) | |||
: Comment data. | |||
====Remarks==== | |||
This order is treated as a no-operation. | |||
===End Area=== | ===End Area=== | ||
===End Element=== | ===End Element=== | ||
Revision as of 03:25, 7 April 2025
Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation
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
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
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
- 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
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.
Bitblt
- Syntax
This order copies a rectangle of a bit map into DOCS.
Bitblt (GBBLT)
X'D6' (LEN, FLAGS, MIX, BMID, TRANS, P1, P2, SOURCE1X, SOURCE1Y, SOURCE2X, SOURCE2Y)
- Parameters
- LEN (GLENGTH1)
- Length of following data.
- FLAGS (GBIT16)
- Reserved.
- 0x0000
- Only valid value.
- MIX (GBIT16)
- Mix mode.
- Values are:
- 0x00CC
- Source.
- 0x00C0
- Source and pattern.
- 0x00CA
- Source where pattern1.
- 0x000C
- Source where pattern0.
- 0x00E2
- Pattern where source1.
- 0x00B8
- Pattern where source0.
- Other
- Reserved values.
- BMID (GHBITMAP)
- Bit-map identifier.
- TRANS (GBIT32)
- Transfer mode.
- Values are:
- 0x00000000
- OR
- 0x01000000
- AND
- 0x02000000
- Ignore
- Other
- Reserved values.
- P1 (GPOINT)
- Target rectangle bottom-left corner.
- P2 (GPOINT)
- Target rectangle top-right corner.
- SOURCE1X (GLONG)
- Source rectangle bottom-left corner, x-coordinate.
- SOURCE1Y (GLONG)
- Source rectangle bottom-left corner, y-coordinate.
- SOURCE2X (GLONG)
- Source rectangle top-right corner, x-coordinate.
- SOURCE2Y (GLONG)
- Source rectangle top-right corner, y-coordinate.
Box at Given Position/Box at Current Position
This order defines a box with square or round corners, drawn with its first corner at a given position.
Syntax
- Box at Given Position (GBOX)
- X'C0' (LEN, CONTROL, RES, P0, P1, HAXIS, VAXIS)
- Box at Current Position (GCBOX)
- X'80' (LEN, CONTROL, RES, P1, HAXIS, VAXIS)
Parameters
- LEN (GLENGTH1)
- Length of following data.
- CONTROL
- Internal flags.
- RES1 (GBIT1)
- Reserved value, must be 0.
- FILL (GBIT1)
- Values:
- 0 No fill
- 1 Fill.
- BOUNDARY (GBIT1)
- Values:
- 0 No boundary
- 1 Boundary.
- RES2 (GBIT5)
- Reserved value, must be 0.
- RES (GBIT8)
- Reserved value, must be 0.
- P0 (GPOINT)
- Coordinate data of box origin.
- This parameter is only present in a Box at Given Position order.
- P1 (GPOINT)
- Coordinate data of box corner.
- HAXIS (GROSOL)
- Length of horizontal axis of ellipse.
- VAXIS (GROSOL)
- Length of vertical axis of ellipse.
Call Segment
This order calls one segment from another.
Syntax
- Call Segment (GCALLS)
- X'07' (LEN, RES, SEGNAME)
Parameters
- LEN (GLENGTH1)
- Length of following data.
- 0x06
- Only valid value.
- RES (GBIT16)
- Reserved value, must be 0.
- SEGNAME (GLONG)
- Name of segment that is to be called.
- The name cannot be 0.
Character String at Given Position/Character String at Current Position
These orders draw a character string at a given position or at the current position.
Syntax
- Character String at Given Position (GCHST)
- X'C3' (LEN, P0, CP)
- Character String at Current Position (GCCHST)
- X'83' (LEN, CP)
Parameters
- LEN (GLENGTH1)
- Length of following data.
- P0 (GPOINT)
- Point at which the character string is to be placed.
- This parameter is only present in a Character String at Given Position order.
- CP (GSTR)
- Code points of each character in the string.
Character String Extended at Given Position/Character String Extended at Current Position
This order defines a character string to be drawn at a given position.
Syntax
- Character String Extended at Given Position (GCHSTE)
- X'FEF0' (LEN1, P0, FLAGS, RES, P1, P2, LEN2, CP, PAD, VECT)
- Character String Extended at Current Position (GCCHSTE)
- X'FEB0' (LEN1, FLAGS, RES, P1, P2, LEN2, CP, PAD, VECT)
Parameters
- LEN1 (GLENGTH2)
- Length of following data.
- P0 (GPOINT)
- Point at which the character string is to be placed.
- This parameter is only present in a Character String Extended at Given Position order.
- FLAGS
- Extra functions:
- RECT (GBIT1)
- Values:
- 0 Do not draw background rectangle
- 1 Draw background rectangle.
- CLIP (GBIT1)
- Values:
- 0 Do not clip to rectangle
- 1 Clip to rectangle.
- RES1 (GBIT1)
- Reserved value, must be 0.
- LVCP (GBIT1)
- Values:
- 0 Move current position
- 1 Leave current position.
- RES2 (GBIT4)
- Reserved value, must be 0.
- RES (GBIT8)
- Reserved value, must be 0.
- P1 (GPOINT)
- Coordinate data of rectangle corner.
- P2 (GPOINT)
- Coordinate data of rectangle corner.
- LEN2 (GLENGTH2)
- Length of code-point data.
- CP (GSTR)
- Code-point data.
- PAD (GBIT8)
- Pad byte.
- Only needs to be included if CP is an odd number of bytes.
- VECT (GROSOL)
- IN (0) Vector of character increments.
- VECT is a vector of n elements, where n is the number of code points present in the CP parameter.
Character String Move at Given Position/Character String Move at Current Position
This order draws a character string starting from a given position and moves the current position to the end of the string.
Syntax
- Character String Move at Given Position (GCHSTM)
- X'F1' (LEN, P0, CP)
- Character String Move at Current Position (GCCHSTM)
- X'B1' (LEN, CP)
Parameters
- LEN (GLENGTH1)
- Length of following data.
- P0 (GPOINT)
- Point at which the character string is to be placed.
- This parameter is only present in a Character String Move at Given Position order.
- CP (GSTR)
- Code points of each character in the string.
Close Figure
This order delimits the end of a closed figure.
Syntax
- Close Figure (GCLFIG)
- X'7D' (RES)
Parameters
- RES (GBIT8)
- Reserved value, must be 0.
Comment
This order enables data to be stored within a segment.
Syntax
- Comment (GCOMT)
- X'01' (LEN, DATA[LEN])
Parameters
- LEN (GLENGTH1)
- Length of following data.
- DATA[LEN] (GBIT8)
- Comment data.
Remarks
This order is treated as a no-operation.