Record Header
A graphics image is represented as an ordered sequence of drawing objects and their associated
attributes. Each drawing object (lines, curves, and so forth) has a specific record class and type
followed by data that describes the position and size of the object. Other records describe the
attributes of various objects (line styles, fill patterns, colors, and so forth).
WPG records have a record header followed by record data as shown in the following table.
Header | Data | ||||
Field Name | Class | Type | Extension | Length | Data |
Field Length (bytes) | 1 | 1 | 1,3 or 5 | 1,3 or 5 | Variable |
The record header contains four fields: Class, Type, Extension, and Length. The length of the
header remains between 4 and 12 bytes. The variable length of the Data field is given by the
header Length field. The Extension field makes it possible to group one or more physical records
into a logical record. The field contains a count of the number of additional records that, with the
current record, make up one logical record. If the count is zero, the logical record is composed of
just the current physical record. If the count is nonzero, the logical record is composed of
multiple physical records. Logical records can be nested. When this occurs, a logical record of
one or more physical records counts as one record to the Extension field of the next outermost
logical record.
Class
The class field lets records be categorized by the function they serve in the file. The following
list shows the possible record classes.
Class # | Class | Description |
1 (0x01) | Reserved | Not currently used |
2 (0x02) | Button | Record describes an application function button |
3 (0x03) | Page | Record describes the page color, shading, and so forth |
4 (0x04) | Client | Record describes a client object |
5 (0x05) | Backdrop | Record describes the backdrop on which an object is rendered |
6 (0x06) | Shadow | Record describes the shadow of an object |
7 (0x07) | Extrusion | Record describes the projection faces of an extruded object |
8 (0x08) | Line Cap | Record describes an object used to cap the end(s) of line |
9 (0x09) | Line Join | Record describes an object used to join the segments of a polyline |
1 (0x01) Reserved
Not currently used.
2 (0x02) Button
The Button class identifies objects with which a user can interact to initiate an application
function. For example, branching within an interactive presentation could be performed by
positioning a pointer on top of an icon and clicking a mouse button. The Button class identifies
the "icons" within an image.
3 (0x03) Page
The Page class is used only on the Color_Transfer, Brush_Gradient, Brush_Fore_Color,
Brush_Back_Color, and Brush_Pattern records (and the double-precision versions of these
records) to describe the page color. It must be stored as an extension to the Start_WPG record.
4 (0x04) Client
The Client class identifies records that describe an actual object. For example, the image
description of a shadowed object would contain some records describing the shadow and some
records describing the object. The records included to describe the shadow would be classified
as Shadow and the records describing the object would be classified as Client.
5 (0x05) Backdrop
A backdrop is an image that serves as a background to an object. Like a shadow, it stays
"attached" to the object; it would move if the object were moved. Records describing a backdrop
are classified as Backdrop.
6 (0x06) Shadow
A shadowed rectangle is described by five sets of records: Group record, Rendition and
Rectangle records, followed by more Rendition and Rectangle records. The Group record keeps
the rectangle attached to its shadow (using the GRP characterization flag). The first Rendition
and Rectangle records describe the shadow (the shadow is drawn first) and are classified as
Shadow. The second Rendition and Rectangle records are classified as Client.
7 (0x07) Extrusion
Extruded objects are a special class of three-dimensional objects. They are "block" objects
having a front and back face lying in parallel planes and a series of extrusion faces at right
angles. When image editing is restricted to 2D, additional records are needed to describe the
extrusion faces of the object. These records are classified as Extrusion.
8 (0x08) Line Cap
There are two types of line caps: predefined and user- defined. Predefined line caps are indexed
using the range 0-9 (see Document Defaults later in this section). Predefined line caps are only
displayed for wide lines. They are scaled to the width of the line and are positioned at the end of
the line. They are not displayed for closed objects. They inherit the same rendition attributes
that are set for the line. A predefined terminal line cap is not displayed if the line ends with the
pen up.
User-defined line caps are defined by the application or by the user, using a Line_Cap_Definition
record with the range 10-255 (0xA-0xFF). User-defined line caps are rendered for both thin lines
and wide lines. They are optionally scaled to the width of the line and are optionally rotated
based on the direction of the line (see the Line_Cap_Definitionrecord under Record Descriptions
later in this section). They are displayed whether the line is closed or not, although the
application can prevent this. They may have their own rendition attributes and thus do not
necessarily share the same attributes as the line. A user-defined terminal line cap is always
displayed, regardless of the pen style or the length of the line.
The Line_Cap_Definition record and the user-defined line cap types in the Line_Cap record are
provided for applications that need to edit graphics. Applications that only render the graphics
can ignore the Line_Cap_Definition record, and whenever the application sees a Line_Cap record
with a user-defined type, it should set the Line_Cap to the default Flat type. Whenever
user-defined line caps are used, there must be a group record (using the GRP characterization
flag) that contains in this order: (1) the Line_Cap record that sets the line cap type; (2) the line,
arc, curve, or other object that is to be capped; and (3) one or two objects of the line cap class and
their associated rendition attribute records, that provide all the information necessary to render
the line cap(s) for the line, arc, curve, and so forth. Graphics editing applications ignore any
objects with the line cap class.
9 (0x09) Line Join
The Line Join class operates in the same way that the Line Cap Class does. Again, there are
predefined line joins in the range 0-9, and there are user-defined line joins in the range 10-255
(0xA-0xFF). User-defined joins require a Line_Join_Definition record for graphics editing
applications. They also require a group with the appropriate rendering information for
applications that render graphics but do not provide graphics editing. Each join object must be
present within the group and must be tagged with the Line Join Class.
Type
The type field identifies various object and attribute records that together describe a graphical
image. The following table summarizes the record types.
Function | Type # | Type | Description |
Control | 1 (0x01) | Start_WPG | Start graphics |
2 (0x02) | End_WPG | End graphics | |
3 (0x03) | Form_Settings | Form layout definition | |
4 (0x04) | Ruler_Settings | Ruler settings definition | |
5 (0x05) | Grid_Settings | Grid settings definition | |
6 (0x06) | Layer | Start new layer | |
7 (0x07) | Reserved | ||
34 (0x22) | Font_Settings | Default font size and face | |
Definition | 8 (0x08) | Pen_Style_Definition | Pen style definition |
9 (0x09) | Pattern_Definition | Pen/brush pattern definition | |
10 (0x0A) | Comment | User comment | |
35 (0x23) | Line_Cap_Definition | Line cap definition (to be defined) | |
36 (0x24) | Line_Join_Definition | Line join definition (to be defined) | |
Rendition | 11 (0x0B) | Color_Transfer | Color transfer function definition |
12 (0x0C) | Color_Palette | Color palette definition | |
13 (0x0D) | DP_Color_Palette | Double-precision color palette definition | |
14 (0x0E) | Bitmap_Data | Bitmap data | |
15 (0x0F) | Text_Data | Text data | |
16 (0x10) | Chart_Style | Chart style definition | |
17 (0x11) | Chart_Data | Chart data | |
18 (0x12) | Object_Image | Object description | |
37 (0x25) | Pen_Fore_Color | Set pen foreground color | |
38 (0x26) | DP_Pen_Fore_Color | Set double-precision pen foreground color | |
39 (0x27) | Pen_Back_Color | Set pen background color | |
40 (0x28) | DP_Pen_Back_Color | Set double-precision pen background color | |
41 (0x29) | Pen_Style | Set pen style | |
42 (0x2A) | Pen_Pattern | Set pen pattern | |
43 (0x2B) | Pen_Size | Set pen size | |
44 (0x2C) | DP_Pen_Size | Set double-precision pen size | |
45 (0x2D) | Line_Cap | Set line cap type | |
46 (0x2E) | Line_Join | Set line join type | |
47 (0x2F) | Brush_Gradient | Set brush gradient attributes | |
48 (0x30) | DP_Brush_Gradient | Set double-precision brush gradient attributes | |
49 (0x31) | Brush_Fore_Color | Set brush foreground color(s) | |
50 (0x32) | DP_Brush_Fore_Color | Set double-precision brush foreground color(s) | |
51 (0x33) | Brush_Back_Color | Set brush background color | |
52 (0x34) | DP_Brush_Back_Color | Set double-precision brush background color | |
53 (0x35) | Brush_Pattern | Set brush pattern | |
Object | 19 (0x13) | Reserved | |
20 (0x14) | Reserved | ||
21 (0x15) | Polyline | Series of lines | |
22 (0x16) | Polyspline | Series of B-spline curves | |
23 (0x17) | Polycurve | Series of Bézier curves | |
24 (0x18) | Rectangle | Rectangle with rounded corners | |
25 (0x19) | Arc | Arc | |
26 (0x1A) | Compound_Polygon | Polygon with multiple paths (deferred filling) | |
27 (0x1B) | Bitmap | Bitmap image | |
28 (0x1C) | Text_Line | Text string on a line | |
29 (0x1D) | Text_Block | Text block | |
30 (0x1E) | Text_Path | Text string with curved baseline | |
31 (0x1F) | Chart | Chart | |
32 (0x20) | Group | Group of WPG image description records | |
33 (0x21) | Object_Capsule | Collection of object descriptions (multiple formats) | |
54 (0x36) | Horizontal_Line | Horizontal Line used for alignment | |
55 (0x37) | Vertical_Line | Vertical Line used for alignment |
The first and last record types for an image must be the Start_WPG and End_WPG records, respectively.
Since new types of fill patterns, pen style, gradients, and so forth may be added in a minor
revision, applications should handle new (unknown) types by setting the attribute to the default
(see Document Defaults later in this section) whenever an unknown type is encountered. Note
that this behavior is different from simply ignoring the new type.
When backward compatibility is important for new features, a mechanism is provided for
applications to specify multiple representations of the same data for applications that support
older revisions (minor numbers) of the file format (see the Object_Capsule record under Record
Descriptionslater in this section).
Extension
The Extension field tells how many other records are included with this record to describe a
"logical" image, such as the image of the shadowed rectangle described as an example of the
Shadow Class above. In this example, the Group record has the extensions of the two attribute
and the two rectangle records. Consequently, the extension value is 4.
Not all records can be used as extensions with all other records. In the record descriptions
information, the valid extensions for that record are listed after the record structure.
A record having extensions is not required to use the same class as its extensions.
The following illustration shows how you can have subgroups of records in a larger group. No
matter how many records are contained in a subgroup, the subgroup as a whole is counted as one
record in the extension field of the larger group. For example, the illistration below shows
records grouped three levels deep. At the topmost layer, the second-level subgroup is counted as
one record even though it has 11 physical records in it.
Record 1
Ext 3 |
Record 1 has two records and one sub-record group, so the extension has the value of 3. | ||
Record 2
Ext 0 | |||
Record 3
Ext 0 | |||
Record 4
Ext 4 |
Record 4 has three record and one sub-record group, so the extension has the value of 4. | ||
Record 5
Ext 0 | |||
Record 6
Ext 0 | |||
Record 7
Ext 0 | |||
Record 8
Ext 4 |
Record 8 has 4 records grouped with it, so its extension is 4. | ||
Record 9
Ext 0 | |||
Record 10
Ext 0 | |||
Record 11
Ext 0 | |||
Record 12
Ext |
Both the Extension and Length fields, called count fields, can be byte, short integer, or long
integer length. Byte count values range from 0 to 254 (0xFE). Short integer count values range
from 255 (0xFF) to 32,767 (0x7FFF). Long integer count values range from 32,768 (0x8000) to
134,217,727 (0x7FFFFFF). Count fields have one of the following structures:
For records with byte counts:
Byte Meaning
1 Byte count: 0-254 (0xFE)
For records with short integer counts:
Byte Meaning
1 255 (0xFF) (signals that a short or long integer count follows)
2 Short integer count, low byte
3 Short integer count, high byte - 0-127 (0x7F)
For records with long integer counts:
Byte Meaning
1 255 (0xFF) (signals that a short or long integer count follows)
2 Long integer count, low byte of high short integer
3 Long integer count, high byte of high short integer (high bit is set to indicate long integer length)
4 Long integer count, low byte of low short integer
5 Long integer count, high byte of low short integer
Code should be written to handle unknown record types by using the Extension and Length fields
to skip the associated information.
Length
The Length field contains the number of bytes in the data area of a record. This "byte count"
does not cover the class, type, or extension fields, or the length field itself. Nor does the length
include any extension records that may be connected with the record, or any other records that
are grouped with the initial record. For detailed information on the format of the length field, see
Extension/Length Coding Format above.