Patterns
When operators such as FillPath, StrokePath,
and ShowString paint areas of the page
with the current color, they ordinarily apply a single color that covers the
areas uniformly. Sometimes it is desirable to apply a logical ink that consists
of a repeating figure instead of a simple color. Such a repeating figure is
called a pattern. This clause describes the creation
and use of patterns.
Creation and Use of Patterns
Painting with a pattern means replicating, or tiling,
a small graphical figure
(called a pattern cell) at fixed intervals in x and
y so as to cover the areas to be painted. The
appearance of a pattern cell is defined by an arbitrary Procedure; it can
include graphical elements such as filled areas, text, and sampled
raster graphics images. The shape of a pattern cell need not be rectangular,
and the spacing of tiles can differ from the size of the pattern
cell. Patterns can be used to create various graphical textures, such as
weaves, brick walls, and similar geometrical tilings.
Although the document normally does not have access to
or knowledge of the device pixel space on any given implementation, the description
of the tiling mechanism for patterns, and the related controls available to
the document, requires that this clause make reference to a device pixel
space.
Painting with a pattern is a four-step Procedure:
- Describe the pattern. This is done by creating
a special-use Dictionary with prescribed contents,
called a Pattern Dictionary, that contains
information about the pattern. A crucial key/value pair in the Dictionary is
the PaintProc,
a Procedure that can be executed to paint a single pattern
cell. This Dictionary is constructed via a RESOURCE DEFINITION, and is made
available to content via the FindResource operator.
- Instantiate the pattern. The MakePattern operator
copies a Pattern Dictionary and produces an instance of the pattern
(in the form of a readonly Pattern Dictionary) that is locked to the RCS. In
other words, the size of a pattern cell
and the phase of the tiling in relation to device pixels are determined by the
CurrentTransformation at the time MakePattern
is executed. The pattern itself is unaffected
by subsequent changes to the Graphics State
Variables. All subsequent executions of the readonly Pattern Dictionary's
PaintProc will use the same values for the Graphics State Variables
as existed at the time the MakePattern operator was executed.
- Select the pattern as the current color. The
operator SetPatternColor installs a pattern as the current
color.
- Invoke imaging operators, such as FillPath,
StrokePath, MaskBitMap, or ShowString. All
areas that normally would be painted with a uniform color are
instead tiled with the pattern cell. To accomplish this, the Pattern Dictionary's
PaintProc is executed to obtain the pattern cell; which
is then tiled on the current page as many times as necessary. It is expected
that some implementations will optimize execution by maintaining a cache of
recently used pattern cells.
Pattern Dictionaries
The Pattern Dictionary defines
- the type of pattern being created,
- the Procedure which paints the pattern cell,
- the clip for the pattern cell, and
- controls for tiling the pattern cell.
The pattern cell is described in its own coordinate system, the pattern
coordinate system, which is defined by concatenating the Transformation
operand
of the MakePattern operator with the CurrentTransformation
at the time MakePattern is executed. The
tiling and clipping parameters are interpreted in the pattern coordinate system;
the Procedure which paints the pattern cell is executed in that coordinate system.
The following subclauses describe the mandatory key/value pairs in a Pattern
Dictionary. The Pattern Dictionary can also contain other (constant) information
that is required by the PaintProc. All key/value pairs except
Implementation can appear in a Pattern Dictionary (a reference
to which is an operand to the MakePattern operator).
PaintType
The mandatory key/value pair <PaintType: Cardinal>
determines how the color of the pattern cell is to be specified.
The valid values for PaintType are shown in .
ValuePaintType
1Colored pattern. The PaintProc
itself specifies the color space(s) and color(s) used to paint the pattern
cell. The PaintProc must select a color space before
performing any imaging operators
2Mask pattern. The PaintProc
does not specify any color space or color information; instead,
the entire pattern cell is painted with a separately specified color each time
the pattern is used. In effect, the PaintProc describes a mask
through which the current color is to be poured. The PaintProc must
not execute any of the color operators (this includes all operators in
), the SetTransfer operator, the SetPatternColor
operator, or the ImageRasterElement operator. Use of
the MaskBitMap operator is permitted, since it does not
specify any color information
PaintProc
The mandatory key/value pair <PaintProc: Procedure>
specifies the Procedure used to paint a pattern cell. PaintProc
takes one operand
<PatternDict: DictionaryReference>
where PatternDict references the Pattern Dictionary
containing PaintProc. PaintProc returns no results.
The effect of executing PaintProc is to draw one pattern cell.
The Graphics State in which PaintProc executes
is the Graphics State at the time when the pattern was instantiated via execution
of the MakePattern operator, including the CurrentTransformation
at that time as modified by concatenating it with the Transformation
operand to the MakePattern operator.
If PaintProc executes the ImageRasterElement
or MaskBitMap operators, none of the underlying Data Sources
for the operation 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 must occur within PaintProc.
Because it is expected that some implementations will optimize execution
by maintaining a cache of recently used pattern cells, PaintProc
may be executed at unpredictable times and in unpredictable contexts. Therefore
PaintProc should rely only on the operators
in SystemDict and on the contents of its PatternDict
operand, and should always produce the same results. For further restrictions
on the operators which may be performed
by PaintProc, see the description of PaintType
in .
BBox
The mandatory key/value pair <BBox: VectorReference>
is a reference to a 4-element
Vector, each element of which is of type Number, specifying
the bounding box of the pattern cell, measured
in the pattern cell coordinate system. This bounding box is used to clip the
pattern cell. 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]
XStep
The mandatory key/value pair <XStep: Number> specifies
the desired horizontal spacing between pattern cells, measured in the pattern
cell coordinate system.
The values of XStep and YStep can differ
from the dimensions of the pattern cell implied by the BBox
key/value pair; this permits tiling with irregularly-shaped figures.
YStep
The mandatory key/value pair <YStep: Number>specifies
the desired vertical spacing between pattern cells, measured in the pattern
cell coordinate system.
The values of XStep and YStep
can differ from the
dimensions of the pattern cell implied by the BBox
key/value pair; this permits tiling with irregularly-shaped figures.
Tiling
The placement of pattern cells in the tiling is based on the location of
one key pattern cell, which is then displaced by multiples of XStep
and YStep in order to replicate the pattern
cell. The origin of the key pattern
cell coincides with the origin of the coordinate system defined by concatenating
the Transformation operand of the
MakePattern operator with the CurrentTransformation at the
time MakePattern is executed. Thus,
the phase of the tiling can be controlled by the translation components
of the Transformation operand. This tiling is frozen;
that is, whenever the Pattern Dictionary created by
MakePattern is used for painting, the same tiling
is used, regardless of intervening changes to the CurrentTransformation.
TilingType
The mandatory key/value pair <TilingType: Cardinal>
controls
adjustments to this tiling in order to quantize it to the device pixel grid.
The valid values for TilingType are shown in .
ValueTilingType
1Constant spacing. Pattern cells are spaced
consistently, that is, by a multiple of a device pixel. To achieve this, the
MakePattern operator may need to distort the
pattern slightly, by making small adjustments to XStep,
YStep,
and the Transformation operand to the MakePattern
operator. The amount of distortion shall not exceed one device
pixel.
2No distortion. The pattern cell is not distorted,
but the spacing between pattern cells may vary by as much as one device pixel
in both x and y dimensions when the pattern is painted. This achieves the spacing
requested by XStep and YStep
on average, but not for individual pattern cells.
3Constant spacing and faster tiling.
Like TilingType 1, but with additional distortion of
the pattern cell permitted in order to
enable a more efficient implementation. The amount of additional distortion
allowed is implementation-specific.
Implementation
The key/value pair <Implementation: Any> is
added to
the Pattern Dictionary by the MakePattern operator. It
is intended to be used
by implementations to store information to aid in proper tiling and possibly
caching of the pattern. The type and value of this key/value pair are implementation-dependent.
If this key is present in a Pattern Dictionary presented to the
MakePattern operator, its value may be overwritten by
the MakePattern operator.
Pattern Semantics
The number of and nature of the operands required by the SetPatternColor
operator depends on the type of pattern (colored or mask) being used. The
semantics of the SetPatternColor operator for each pattern
type are specified
in and , respectively.
Colored Patterns
A colored pattern is one whose color is self-contained. As part of painting
the pattern cell, the PaintProc explicitly sets the
colors of all graphical elements that it paints. A single pattern cell can
contain elements that are painted different colors; it can also contain sampled
gray-scale or color images.
The operands required by the SetPatternColor operator
to select a colored pattern are
<PatternDict: DictionaryReference>
where PatternDict references a Pattern Dictionary
obtained via execution of the MakePattern operator on
a Pattern Dictionary whose
PaintType
is 1.
Mask Patterns
A mask pattern is one that does not have any inherent color;
instead, the color must be specified separately whenever the pattern is used.
This provides a way to tile different regions of the page with pattern cells
having the same shape but different colors. The pattern's
PaintProc does not explicitly specify any colors; it
cannot contain sampled gray-scale or color images (but it may use the
MaskBitMap operator).
The operands required by the SetPatternColor operator
to select a mask pattern, and a color
with which to paint the mask pattern, are
<PatternDict: DictionaryReference>
<compn: Any>
. . .
<comp1: Any>
where PatternDict references a Pattern Dictionary
obtained via execution of the MakePattern operator whose
PaintType
is 2, and the remaining operands are the appropriate components to select
the color to be used to paint the pattern in the underlying color space. The
underlying color space is the color space
which is the value of the CurrentColorSpace Graphics State Variable
(as specified by the most recent execution of the SetColorSpace
operator in the current context of execution).
Executing the SetColorSpace
operator after the SetPatternColor
operator both changes CurrentColorSpace and initializes CurrentColor
removing the pattern that was current.
Obtaining a Prototype Pattern Dictionary for Use in Content
A reference to a Pattern Dictionary to be used as an operand to the
MakePattern operator is obtained via execution of the
FindResource operator.
The FindResource operator takes as an operand the value
of an INTERNAL RESOURCE IDENTIFIER that has
been previously bound to a Pattern resource in structure by a RESOURCE DECLARATION,
and returns a reference to a Pattern Dictionary .
The FindResource operator does not examine
the Pattern Dictionary
to ensure that the required key/value pairs are present
and of the correct type; this
function is performed by the MakePattern operator.
Operators
The specification of these operators and their semantics includes the specification
of conditions which may cause content exceptions to be raised as a result of
interpretation of the operators. Content exceptions and exception handling
are defined in . In addition to these 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 .
MakePattern
The MakePattern operator takes two operands
<T: Transformation>
<PatternDictionary: DictionaryReference>
and returns one result
<NewPatternDict: DictionaryReference>
where PatternDictionary is obtained via execution
of the FindResource operator. If PatternDictionary
is not a reference to a Dictionary obtained
via execution of the FindResource operator, RaiseError
shall be invoked with UndefinedResource as its operand.
The set of mandatory key/value pairs is checked. If any keys are missing, RaiseError
shall be invoked with UndefinedKey as its operand.
If the key is present but the value bound to it is of the wrong type, RaiseError
shall be invoked with TypeCheck as its operand. If
the key is present and the type is correct but the bound value is out of range,
RaiseError shall be invoked with RangeCheck
as its operand.
The pattern coordinate system is constructed
from the current Graphics State as follows:
- The operand T is concatenated with
a copy of the CurrentTransformation in the current Graphics
State. The resulting Transformation is then
adjusted to ensure that the device pixel
space can be tiled properly with a pattern cell of the given size in accordance
with the TilingType specified in PatternDictionary.
- The CurrentPath is set to the null path, as if
by execution of the NewPath operator.
- The CurrentClippingRegion is replaced by the pattern
cell bounding box (defined by
the BBox key/value pair in PatternDictionary).
This description is intended to specify the semantics
of the MakePattern operator only; it is not intended to
specify how implementations
satisfy the semantics for patterns.
MakePattern then makes a new copy of PatternDictionary,
adds the Implementation key/value pair, reduces the
access attribute of the Dictionary
to at least ReadOnly, and pushes it onto the Operand
Stack.
Because on some implementations the MakePattern
operator may further alter the contents of the Dictionary, the reduction of
the access attribute of the Dictionary is performed to prevent subsequent content
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 SetPatternColor) may reduce the access
attribute of the Dictionary to ExecuteOnly.
SetPatternColor
The nature and number of operands required by the
SetPatternColor operator
depend upon the type of pattern (colored or mask) being set; these operands
are described in and
. The SetPatternColor
operator returns no results. The effect of executing the
SetPatternColor operator is to set the
value of the CurrentColor
Graphics State Variable as described in
If any of the required key/value pairs are missing from the Pattern Dictionary
operand of the SetPatternColor
operator, RaiseError shall be invoked with UndefinedKey
as its operand.