Record Data
The Record Data area contains the actual record format information. This section of the File
Format Software Developer's Kit discusses the information that goes into the data area for a
given record, the coding format of the information, and so on.
Data Precision
The units of WPG coordinate data are stored in the Start_WPG record. Coordinate data values
are signed values indicating a location within a two-dimensional, right-hand, Cartesian
coordinate system. Positive X and Y values are located to the right and above the image origin.
Single-precision positional data uses short integer values ranging from -32768 to 32767.
Double-precision positional data uses fixed-point values ranging from -32768.00000 to
32767.99998. Double-precision data is stored in long integer formats. Although
double-precision positional data is defined by the format, WPCorp products (as currently
implemented) use the fractional portion for rounding only. Therefore, positional data must not
be defined in a small range (such as 0.21 to 1).
Angles are specified by signed, fixed-point values, with 16 bits of precision on both sides of the
radix. Positive angular displacement is counterclockwise from a standard position that is
horizontal and to the right of the center point of rotation.
Single-precision colors are specified by four bytes, with one byte each for red, green, blue, and
transparency. Double-precision colors are specified by four short integers, with one short integer
each for red, green, blue, and transparency:
Red Intensity | Green Intensity | Blue Intensity | Transparency | |
Single-Precision Color | bits 00-07 | bits 08-15 | bits 16-23 | bits 24-31 |
Double-Precision Color | bits 00-15 | bits 16-31 | bits 32-47 | bits 48-63 |
In a byte buffer, red is the first color encountered, followed by green, blue, and transparency.
Object Characterization
Certain WPG records contain 16 bits of characterization flags followed by optional data whose
inclusion depends on whether certain flag bits are set. The detailed record descriptions found
under Record Descriptions later in this section designate the records that contain a
characterization flag and the flag bits used with that record. The table below specifies the
definitions of the characterization flag bits.
Characterization Flags | |||
Bit | Name | Abbreviation | Description |
0 | Taper | TPR | Object is to be tapered (perspective). |
1 | Translate | TRN | Object is to be translated. |
2 | Skew | SKW | Object is to be skewed. |
3 | Scale | SCL | Object is to be scaled. |
4 | Rotate | ROT | Object is to be rotated. |
5 | Object_ID | OID | Object has a unique identifier. |
6 | Reserved | ||
7 | Edit_Lock | LCK | Edit locks are defined for object. |
8 | Reserved | ||
9 | Group_State | GRP | Group created by application, not to be ungrouped. This flag is set for a group record that keeps a shadow with a shadowed object or for a group record that keeps a user-defined line cap with the line. |
10 | Local_State | LOC | Attribute changes within the object apply only to the object. In other words, the attribute state that was in effect outside a particular object is unaffected by attribute changes made within the object. |
11 | Direction | DIR | Object's frame (outline) is drawn in the clockwise direction (for text paths and winding fill rule). |
12 | Path_Composition | PTH | Object's path is to be determined by the winding rule (instead of the alternating rule). |
13 | Fill | FIL | Object's interior is to be rendered with the current brush and gradient attributes. |
14 | Close | CLS | Object's frame (outline) is to be closed. This differentiates, for example, a polygon from a polyline. |
15 | Frame | FRM | Object is to be framed (outlined) with the current pen and line attributes. |
The most significant byte of the characterization flags (bits 8-15) contains bits defining two-state
rendition options. These bits need no further data to describe how the object is to be rendered.
The flag bits indicate that these options are either ON or OFF; therefore, these flags need no
other information. The least significant byte (bits 0-7) contains bit flags that indicate the
inclusion of additional data in the record.
Taper, Translate, Skew, Scale, Rotate, Object_ID, and Edit_Lock flags indicate that additional
data follows the Characterization flags. The table below shows the order this included data takes
(and its size) if all the characterization flag bits are set. Any bit not set indicates the
corresponding data is not present in the record.
Order of Optional Characterization Data Fields
{Edit lock flags}
[Object ID] (see Record Structure later in this section)
{Angle of rotation}
{Sxcos() transformation element}
{Sycos() transformation element}
{-Kxsin() transformation element}
{Kysin() transformation element}
{Tx transformation element (integer)}
[Tx transformation element (fraction)]
{Ty transformation element (integer)}
[Ty transformation element (fraction)]
{Px transformation element}
{Py transformation element}
Edit_Lock Flags
The Edit_Lock flags indicate that the record contains a long integer edit lock descriptor. Edit
locks disable editing actions from being performed on the object. The table below specifies the
Edit_Lock descriptor bit definitions.
Edit_Lock Flag Definitions | ||
Bit | Function | Description |
0 | Path Style | Path composition rule cannot be changed |
1 | Brush Pattern | Brush pattern cannot be changed |
2 | Brush Color | Brush color cannot be changed |
3 | Line Cap | Line caps cannot be changed |
4 | Line End | Line end style cannot be changed |
5 | Line Join | Line join style cannot be changed |
6 | Pen Width | Pen widths cannot be changed |
7 | Pen Pattern | Pen pattern cannot be changed |
8 | Pen Style | Pen style cannot be changed |
9 | Pen Color | Pen color cannot be changed |
10 | Font Style | Font style cannot be changed |
11 | Font Size | Font size cannot be changed |
12 | Font | Font cannot be changed |
13 | Reserved | |
14 | Shadow | Shadow cannot be changed |
15 | Extrusion | Extrusion cannot be changed |
16 | Reserved | |
17 | Reserved | |
18 | Reserved | |
19 | Reserved | |
20 | Reserved | |
21 | Reserved | |
22 | Group | Object cannot be ungrouped |
23 | Sequence | Object sequence cannot be changed |
24 | Delete | Object cannot be deleted |
25 | Modify | Object cannot be modified |
26 | Mirror | Object cannot be mirrored |
27 | Taper | Object cannot be tapered |
28 | Skew | Object cannot be skewed |
29 | Rotate | Object cannot be rotated |
30 | Size | Object cannot be sized |
31 | Move | Object cannot be moved |
Transformation Data (Taper, Translate, Skew, Scale, Rotate)
As mentioned before, the first five characterization flags are used for transformations and
indicate the presence of additional data following the characterization flags. This additional data
describes the transformation performed on an object. The order of this transformation data is
contained in the Order of Optional Characterization Data Fields table above, starting with the
Angle of Rotation field.
Transformations are described by a 3x3 transformation matrix such as the one shown in the
matrix equation above. All of the terms of the transformation matrix are fixed-point values. The
high short integer (16 bits) is the integer portion of a floating-point value. The low short integer
(16 bits) is the fractional portion of the floating-point value. In the Order of Optional
Characterization Data Fields table the terms Txand Ty have already been broken down into their
integer and fractional components. This is because, unlike the other transformation terms, these
two terms have a long integer (32 bits) instead of a short integer component to the left of the
decimal point.
Names of the matrix elements show only the relative positions of the terms of five simple
transformations: Rotate, Scale, Skew, Translate, and Taper (Perspective). They do not show the
method of computing transformation matrix data. Lack of transformation data implies an
identity matrix (a matrix that does not affect any number multiplied through it). One or more bits
set in the first five characterization flags indicates the inclusion of an angle of rotation or
indicates one or more pairs of transformation matrix elements that replace corresponding identity
matrix elements.
The table below shows the data that is included in the record when certain characterization flag
bits are set.
Transformation Flag Correspondence to Included Data | |
Flag Bit Set | Data that will be included |
Rotate | , Sxcos(), Sycos(), -Kxsin(), Kysin() |
Scale | Sxcos(), Sycos() |
Skew | -Kxsin(), Kysin() |
Translate | Tx, Ty |
Taper | Px, Py |
Notice in the table above that, for example, Rotate and Scale both include the term Sxcos() in
them. If both flag bits were set, there would only be one Sxcos() term included in the record.
Both Rotate and Scale would share the one term. This is true for any other overlapping terms
that appear in the table above. However, the table doesn't show the correct order in which the
data is put into the record. For this information, see the Order of Optional Characterization
Data Fields table earlier in this section.
Object Transformation
A record's transformation matrix is preconcatenated to the Current Transformation Matrix
(CTM) as shown in the left-hand equation below. The Group record (See Record Type 32 (0x20)
Group in the Record Descriptions section) combines one or more physical objects into one
logical object. Both the physical objects within the group and the group itself can have
transformation matrices. In this case the concatenation of the matrices is performed as shown in
the right-hand equation below.
(Obj)(CTM) (Obj)((Group)(CTM))
Data points that define an object are transformed through the resulting transformation matrix as follows:
Record Structure
The following record descriptions define the structure of the data associated with each WPG
image record type. Record descriptions also define the logical record structure by listing both
required and optional record extensions. Record extension syntax is as follows:
Extensions: | required records | (optional records) |
Field Precision
Three types of fields found within some of the following record types are marked with a dagger .
They are:
There are two options for the size of the data in each of these fields.
Position/size and color data types can be either single precision or double-precision. The
Start_WPG record specifies the choice for single precision or double-precision. Position and size
data have a 16-bit single-precision size and a 32-bit double-precision size. Color data uses four
bytes in single-precision size and four short integers in double-precision size.
The Object ID is a unique identifier for the record. An Object ID is optional data and is only
present if the Object_ID characterization flag is set. Its length can be either a short integer (16
bits) or a long integer (32 bits). Short integer ID values range from 0 to 32,767 (0x7FFF). Long
integer ID values range from 32,768 (0x8000) to 2,147,480,000 (0x7FFFFFFF). The Object ID
has one of the following structures.
For records with short integer IDs:
Short | Meaning |
1 | Short integer count: 0-32,767 (0x7FFF) |
For records with long integer IDs:
Short | Meaning |
1 | Long integer count, high short integer (high bit is set to indicate long integer length) |
2 | Long integer count, low short integer |
All field sizes marked with a dagger in the following record types are given for short integer IDs
and single-precision values. If a record contains a long integer ID or double-precision values,
sizes corresponding to marked fields will double.
Field Representation
In most of the following records, the fields of the record (the information enclosed by the byte,
short, or long integer marks) are shown indented, and bit flags are further indented under the field
they belong to. For example:
[data field]
<text flags data field>
bit 1: meaning 1
bit 2: meaning 2
[some other data field]
The indentation in the example above identifies the meaning of the bit flags used by the Text
Flags Data Field. In these cases, unless otherwise documented, if one of the labeled bits is set
(contains the value 1), the flag has the labeled meaning.
In a few records you may see something like the following:
{data field 1}
[data field 2]
[data field 3]
<data field 4>
<data field 5>
[data field 6]
In this case Data Field 3 and Data Field 4 do not exist in the record. The condition that causes
this to happen is documented in the Notes section of the record. The following two examples
show records that use both types of indentation.
[data field 1]
[data field 2]
[data flags]
bit 14: meaning 1
bit 15: meaning 2
<data field 3>
[data field 4]
[data field A]
<text flags>
bit 4: meaning 1
bit 5: meaning 2
bit 6: meaning 3
[data field B]
[data field C]
{data field D}
Since new records may be added to minor revisions of this format, applications should be programmed to skip over any unrecognized records and their extensions (and their extensions recursively). Since new fields may be added to the end of records in a minor revision, applications should key off the length field in the record header to know where the next record starts. Any unrecognized data between the currently-defined end of a record and the start of the next record should be ignored.