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





Extension/Length Coding Format

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.