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:

Pattern Dictionaries

The Pattern Dictionary defines

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.