A form is a self-contained description of any arbitrary
geometric graphics, text, or raster graphics that are to be imaged multiple
times, either on one page or on several pages.
A form is defined at the structure level via a RESOURCE DEFINITION, and
is bound to the value of an INTERNAL RESOURCE IDENTIFIER in a RESOURCE DECLARATION.
The appearance of a form is described by a Procedure
that executes imaging operators. The FindResource operator
is used in content to obtain a form, which is represented in content by a Form
Object, and is imaged by providing the Form Object as an operand to
the ExecuteForm operator.
There is no Form Object type in SPDL;
rather the term is used as a convenient term to describe both references to
the particular objects of type Dictionary which represent
a form and its associated parameters (and are obtained via the FindResource
operator) and to the Dictionaries themselves. That is, Form Object will be used
both for the DictionaryReference and the Dictionary; which is intended will
be clear from context.
The remainder of this clause specifies the contents of Form Dictionaries
and the semantics of the ExecuteForm operator.
A form is represented by a Form Object, which is a reference to a Form Dictionary
with prescribed contents which fully describes
the form to be imaged. The form is defined in its own coordinate system, the
form coordinate
system, which is defined by concatenating the value bound to the
Matrix
key in the Form Dictionary with the CurrentTransformation each time
the Form Objects's PaintProc (the Procedure in the Form
Dictionary that images the form) is executed. The BBox parameter
in the Form Dictionary is interpreted in the form coordinate system; the PaintProc
is executed in that coordinate system.
The following subclauses describe the contents of a Form Dictionary. In
addition to the contents described below, the Form Dictionary can also contain
other (constant) information that is required by the PaintProc
(see ).
BBox
The mandatory key/value pair <BBox: Vector>
is a 4-element Vector of type Number specifying the bounding
box of the form in the form coordinate
system. This bounding box is used to clip the form. The four elements of the
Vector specify the lower left x, lower left y, upper right x, and upper right
y coordinates of the bounding box:
[ llx lly urx ury]
Matrix
The mandatory key/value pair <Matrix: Transformation>
is the Transformation to be concatenated with the CurrentTransformation
to produce the Transformation that defines the form coordinate system.
PaintProc
The mandatory key/value pair <PaintProc: Procedure>
specifies the Procedure used to paint the form. PaintProc takes
one operand
<FormDict: DictionaryReference>
where FormDict is a reference to the Form Dictionary containing
PaintProc, and returns no results. The effect of executing
PaintProc is to image one instance of the form. The
Context of Interpretation for PaintProc is described in
.
If PaintProc executes the ImageRasterElement
or MaskBitMap imaging operators, none of the underlying
Data Sources for the operator may be DataSource::Document.
If any of the underlying Data Sources is a StreamObject derived from an external
data source, the execution of the FindResource operator
to obtain the StreamObject shall occur within PaintProc.
Because it is expected that many implementations will optimize
execution
by maintaining a cache of recently used forms, PaintProc
may be executed at unpredictable times and in unpredictable contexts. Therefore
PaintProc should rely only on the operators
in SystemDict, on the contents of its FormDict
operand, and the Graphics State Variables not set to their default values according
to . It should always produce the same results.
It should have no side effects besides painting the form.
UniqueID
The optional key/value pair <UniqueID: Identifier>
is designed to uniquely identify, for caching purposes, a form that is to be
used by multiple documents.
To avoid the possible waste of memory resources in caching implementations,
a Form Dictionary for a form that is specified and used within a single
document should not contain this key.
Implementation
The key/value pair <Implementation: Any> is added to
the Form Dictionary by the ExecuteForm operator. It is
intended to be used
by implementations to store information to aid in the caching of the form.
The type and value of this key are implementation-dependent. If an key/value
pair whose key is Implementation is placed in a Form Dictionary
by the TOKENSEQUENCE that defines the Dictionary, its value may be overwritten
by the ExecuteForm operator.
A Form Object to be used as an operand to the ExecuteForm
operator is obtained via execution of the FindResource operator.
The FindResource operator
takes as an operand an INTERNAL RESOURCE IDENTIFIER that has been
previously bound to a Form resource in structure by a RESOURCE DECLARATION,
and returns a Form Object.
The FindResource operator does not examine
the Form Dictionary referenced by the Form Object
to ensure that the required keys are present and of the correct type; this
function is performed by the ExecuteForm operator.
A form is imaged via execution of the ExecuteForm operator,
which in turn
executes the PaintProc in the Form Objects's Form Dictionary.
Prior to executing the ExecuteForm operator, a document
should set appropriate
parameters in the graphics state; in particular, it should alter the CurrentTransformation
in order to control the position, size, and orientation of the form in User
Coordinate Space.
Before execution of the PaintProc, the following
Graphics State Variables are reset to their default values (see
for the default value for each):
- CurrentDashPattern
- CurrentMiterLimit
- CurrentPath
- CurrentPosition
- CurrentStrokeEnd
- CurrentStrokeJoin
- CurrentStrokeWidth
If some other value than the default value of the above Graphics
State Variables is desired, additional key/value pairs may be defined in the
Form Dictionary to represent Graphics State Variable values or other information
that can be used by the PaintProc in imaging the form.
The rest of the Virtual Machine State in which the PaintProc
executes is implementation-dependent.
In some implementations, part or all of the remainder of the
Virtual Machine State may be inherited from the Virtual Machine State
at the time of execution of the ExecuteForm operator.
The specification of the ExecuteForm operator and its
semantics includes the specification
of conditions which may cause content exceptions to be raised as a result of
interpretation of the operator. Content exceptions and exception handling
are defined in . In addition to the operator-specific exceptions,
there are generic exceptions which may be raised during the interpretation of
almost any operator. These generic exceptions and their semantics are described
in .
The ExecuteForm operator accepts one operand
<FormObject: DictionaryReference>
where Form Object is obtained via execution
of the FindResource operator. The operator returns no
results. The graphical output produced by ExecuteForm is
defined by the PaintProc Procedure
(see ) in the Form Object's Form Dictionary.
If this is the first invocation of ExecuteForm for the
form, ExecuteForm first verifies that the Form Dictionary contains
the required keys. It then adds the
Implementation key/value pair (see ) and reduces
the access attribute of the Dictionary to at least ReadOnly.
Because on some implementations the ExecuteForm
operator may alter the contents of the Dictionary, the reduction of the access
attribute of the Dictionary is performed to prevent subsequent content operators
from
modifying the contents of the Dictionary. Implementations which do not wish
to allow any subsequent access to the contents of the Dictionary (except via
executions of ExecuteForm) may reduce the access attribute
of the Dictionary to ExecuteOnly.
If any of the required key/value pairs are missing from the Form Dictionary
operand of the ExecuteForm operator, RaiseError shall
be invoked with UndefinedKey as its operand.
ExecuteForm may call the PaintProc
to image the form. It shall call the PaintProc the
first time that ExecuteForm is called with a given Form
Object and whenever changes to the Graphics State since the last time the PaintProc
was called would effect how the form was imaged. Changes to the translation
components of the CurrentTransformation Graphics State
Variable do not effect how the form will be imaged. When ExecuteForm needs to
call the PaintProc Procedure
(rather than using a cached representation to image the form), it pushes the
Form Object on the operand stack, then performs the equivalent of
the following:
SaveGraphicsState
% The following procedure resets the Graphics State Variables
specified in to their default values;
% the code for this Procedure is obvious. The values of all
other Graphics State Variables are taken
% from the inherited Graphics State.
SetGStateVariables
% Concatenate Form Dictionary's Matrix with
CurrentTransformation
Dup /Matrix Get Concat
% Stack has: Form-Dictionary llx lly urx ury (for BBox)
Dup /BBox Get VectorLoad Pop
% Stack has: Form-Dictionary llx lly width height
Exchange 3 Index Subtract
Exchange 2 Index Subtract
% Clip to form bounding box; ends with NewPath
RectClip
% Execute PaintProc
Dup /PaintProc Get Execute
RestoreGraphicsState
The PaintProc Procedure is expected to consume the
DictionaryReference operand and to execute a sequence of
imaging operators to paint the
form.The execution of PaintProc should depend only on
the contents of the Form Dictionary and UserDict plus the Graphics State Variables
not set to their default values according to ,.
The PaintProc shall always produce the same output,
given the same values for the Graphics State Variables not set to their default
values according to , independent of the number of
times it is called and independent,
for example, of the contents of UserDict. The
document should not expect any particular execution of ExecuteForm
to cause
execution of the specified PaintProc.
If Form Object is not a reference to a Dictionary
obtained via execution of the FindResource operator,
RaiseError shall be invoked with UndefinedResource
as its operand.