• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

Chapter 4. Graphics > Graphics State

4.3. Graphics State

A PDF consumer application maintains an internal data structure called the graphics state that holds current graphics control parameters. These parameters define the global framework within which the graphics operators execute. For example, the f (fill) operator implicitly uses the current color parameter, and the S (stroke) operator additionally uses the current line width parameter from the graphics state.

The graphics state is initialized at the beginning of each page with the values specified in Tables 4.2 and 4.3. Table 4.2 lists those graphics state parameters that are device-independent and are appropriate to specify in page descriptions. The parameters listed in Table 4.3 control details of the rendering (scan conversion) process and are device-dependent; a page description that is intended to be device-independent should not modify these parameters.

Table 4.2. Device-independent graphics state parameters
PARAMETERTYPEVALUE
CTMarrayThe current transformation matrix, which maps positions from user coordinates to device coordinates (see Section 4.2, “Coordinate Systems”). This matrix is modified by each application of the coordinate transformation operator, cm. Initial value: a matrix that transforms default user coordinates to device coordinates.
clipping path(internal)The current clipping path, which defines the boundary against which all output is to be cropped (see Section 4.4.3, “Clipping Path Operators”). Initial value: the boundary of the entire imageable portion of the output page.
color spacename or arrayThe current color space in which color values are to be interpreted (see Section 4.5, “Color Spaces”). There are two separate color space parameters: one for stroking and one for all other painting operations. Initial value: DeviceGray.
color(various)The current color to be used during painting operations (see Section 4.5, “Color Spaces”). The type and interpretation of this parameter depend on the current color space; for most color spaces, a color value consists of one to four numbers. There are two separate color parameters: one for stroking and one for all other painting operations. Initial value: black.
text state(various)A set of nine graphics state parameters that pertain only to the painting of text. These include parameters that select the font, scale the glyphs to an appropriate size, and accomplish other effects. The text state parameters are described in Section 5.2, “Text State Parameters and Operators.”
line widthnumberThe thickness, in user space units, of paths to be stroked (see “Line Width” on page 185). Initial value: 1.0.
line capintegerA code specifying the shape of the endpoints for any open path that is stroked (see “Line Cap Style” on page 186). Initial value: 0, for square butt caps.
line joinintegerA code specifying the shape of joints between connected segments of a stroked path (see “Line Join Style” on page 186). Initial value: 0, for mitered joins.
miter limitnumberThe maximum length of mitered line joins for stroked paths (see “Miter Limit” on page 187). This parameter limits the length of “spikes” produced when line segments join at sharp angles. Initial value: 10.0, for a miter cutoff below approximately 11.5 degrees.
dash patternarray and numberA description of the dash pattern to be used when paths are stroked (see “Line Dash Pattern” on page 187). Initial value: a solid line.
rendering intentnameThe rendering intent to be used when converting CIE-based colors to device colors (see “Rendering Intents” on page 231). Initial value: RelativeColorimetric.
stroke adjustmentboolean(PDF 1.2) A flag specifying whether to compensate for possible rasterization effects when stroking a path with a line width that is small relative to the pixel resolution of the output device (see Section 6.5.4, “Automatic Stroke Adjustment”). Note that this is considered a device-independent parameter, even though the details of its effects are device-dependent. Initial value: false.
blend modename or array(PDF 1.4) The current blend mode to be used in the transparent imaging model (see Sections 7.2.4, “Blend Mode,” and 7.5.2, “Specifying Blending Color Space and Blend Mode”). This parameter is implicitly reset to its initial value at the beginning of execution of a transparency group XObject (see Section 7.5.5, “Transparency Group XObjects”). Initial value: Normal.
soft maskdictionary or name(PDF 1.4) A soft-mask dictionary (see “Soft-Mask Dictionaries” on page 520) specifying the mask shape or mask opacity values to be used in the transparent imaging model (see “Source Shape and Opacity” on page 495 and “Mask Shape and Opacity” on page 518), or the name None if no such mask is specified. This parameter is implicitly reset to its initial value at the beginning of execution of a transparency group XObject (see Section 7.5.5, “Transparency Group XObjects”). Initial value: None.
alpha constantnumber(PDF 1.4) The constant shape or constant opacity value to be used in the transparent imaging model (see “Source Shape and Opacity” on page 495 and “Constant Shape and Opacity” on page 519). There are two separate alpha constant parameters: one for stroking and one for all other painting operations. This parameter is implicitly reset to its initial value at the beginning of execution of a transparency group XObject (see Section 7.5.5, “Transparency Group XObjects”). Initial value: 1.0.
alpha sourceboolean(PDF 1.4) A flag specifying whether the current soft mask and alpha constant parameters are to be interpreted as shape values (true) or opacity values (false). This flag also governs the interpretation of the SMask entry, if any, in an image dictionary (see Section 4.8.4, “Image Dictionaries”). Initial value: false.


Table 4.3. Device-dependent graphics state parameters
PARAMETERTYPEVALUE
overprintboolean(PDF 1.2) A flag specifying (on output devices that support the overprint control feature) whether painting in one set of colorants should cause the corresponding areas of other colorants to be erased (false) or left unchanged (true); see Section 4.5.6, “Overprint Control.” In PDF 1.3, there are two separate overprint parameters: one for stroking and one for all other painting operations. Initial value: false.
overprint modenumber(PDF 1.3) A code specifying whether a color component value of 0 in a DeviceCMYK color space should erase that component (0) or leave it unchanged (1) when overprinting (see Section 4.5.6, “Overprint Control”). Initial value: 0.
black generationfunction or name(PDF 1.2) A function that calculates the level of the black color component to use when converting RGB colors to CMYK (see Section 6.2.3, “Conversion from DeviceRGB to DeviceCMYK”). Initial value: installation-dependent.
undercolor removalfunction or name(PDF 1.2) A function that calculates the reduction in the levels of the cyan, magenta, and yellow color components to compensate for the amount of black added by black generation (see Section 6.2.3, “Conversion from DeviceRGB to DeviceCMYK”). Initial value: installation-dependent.
transferfunction, array, or name(PDF 1.2) A function that adjusts device gray or color component levels to compensate for nonlinear response in a particular output device (see Section 6.3, “Transfer Functions”). Initial value: installation-dependent.
halftonedictionary, stream, or name(PDF 1.2) A halftone screen for gray and color rendering, specified as a halftone dictionary or stream (see Section 6.4, “Halftones”). Initial value: installation-dependent.
flatnessnumberThe precision with which curves are to be rendered on the output device (see Section 6.5.1, “Flatness Tolerance”). The value of this parameter gives the maximum error tolerance, measured in output device pixels; smaller numbers give smoother curves at the expense of more computation and memory use. Initial value: 1.0.
smoothnessnumber(PDF 1.3) The precision with which color gradients are to be rendered on the output device (see Section 6.5.2, “Smoothness Tolerance”). The value of this parameter gives the maximum error tolerance, expressed as a fraction of the range of each color component; smaller numbers give smoother color transitions at the expense of more computation and memory use. Initial value: installation-dependent.


Some graphics state parameters are set with specific PDF operators, some are set by including a particular entry in a graphics state parameter dictionary, and some can be specified either way. The current line width, for example, can be set either with the w operator or (in PDF 1.3) with the LW entry in a graphics state parameter dictionary, whereas the current color is set only with specific operators, and the current halftone is set only with a graphics state parameter dictionary. It is expected that all future graphics state parameters will be specified with new entries in the graphics state parameter dictionary rather than with new operators.

In general, the operators that set graphics state parameters simply store them unchanged for later use by the painting operators. However, some parameters have special properties or behavior:

  • Most parameters must be of the correct type or have values that fall within a certain range.

  • Parameters that are numeric values, such as the current color, line width, and miter limit, are forced into valid range, if necessary. However, they are not adjusted to reflect capabilities of the raster output device, such as resolution or number of distinguishable colors. Painting operators perform such adjustments, but the adjusted values are not stored back into the graphics state.

  • Paths are internal objects that are not directly represented in PDF.

Note

As indicated in Tables 4.2 and 4.3, some of the parameters—color space, color, and overprint—have two values, one used for stroking (of paths and text objects) and one for all other painting operations. The two parameter values can be set independently, allowing for operations such as combined filling and stroking of the same path with different colors. Except where noted, a term such as current color should be interpreted to refer to whichever color parameter applies to the operation being performed. When necessary, the individual color parameters are distinguished explicitly as the stroking color and the nonstroking color.


4.3.1. Graphics State Stack

A well-structured PDF document typically contains many graphical elements that are essentially independent of each other and sometimes nested to multiple levels. The graphics state stack allows these elements to make local changes to the graphics state without disturbing the graphics state of the surrounding environment. The stack is a LIFO (last in, first out) data structure in which the contents of the graphics state can be saved and later restored using the following operators:

  • The q operator pushes a copy of the entire graphics state onto the stack.

  • The Q operator restores the entire graphics state to its former value by popping it from the stack.

These operators can be used to encapsulate a graphical element so that it can modify parameters of the graphics state and later restore them to their previousvalues. Occurrences of the q and Q operators must be balanced within a given content stream (or within the sequence of streams specified in a page dictionary's Contents array).

4.3.2. Details of Graphics State Parameters

This section gives details of several of the device-independent graphics state parameters listed in Table 4.2.

Line Width

The line width parameter specifies the thickness of the line used to stroke a path. It is a non-negative number expressed in user space units; stroking a path entails painting all points whose perpendicular distance from the path in user space is less than or equal to half the line width. The effect produced in device space depends on the current transformation matrix (CTM) in effect at the time the path is stroked. If the CTM specifies scaling by different factors in the horizontal and vertical dimensions, the thickness of stroked lines in device space will vary according to their orientation. The actual line width achieved can differ from the requested width by as much as 2 device pixels, depending on the positions of lines with respect to the pixel grid. Automatic stroke adjustment can be used to ensure uniform line width; see Section 6.5.4, “Automatic Stroke Adjustment.”

A line width of 0 denotes the thinnest line that can be rendered at device resolution: 1 device pixel wide. However, some devices cannot reproduce 1-pixel lines, and on high-resolution devices, they are nearly invisible. Since the results of rendering such zero-width lines are device-dependent, their use is not recommended.

Line Cap Style

The line cap style specifies the shape to be used at the ends of open subpaths (and dashes, if any) when they are stroked. Table 4.4 shows the possible values.

Table 4.4. Line cap styles
STYLEAPPEARANCEDESCRIPTION
0

Butt cap. The stroke is squared off at the endpoint of the path. There is no projection beyond the end of the path.

1

Round cap. A semicircular arc with a diameter equal to the line width is drawn around the endpoint and filled in.

2

Projecting square cap. The stroke continues beyond the endpoint of the path for a distance equal to half the line width and is squared off.


Line Join Style

The line join style specifies the shape to be used at the corners of paths that are stroked. Table 4.5 shows the possible values. Join styles are significant only at points where consecutive segments of a path connect at an angle; segments that meet or intersect fortuitously receive no special treatment.

Table 4.5. Line join styles
STYLEAPPEARANCEDESCRIPTION
0

Miter join. The outer edges of the strokes for the two segments are extended until they meet at an angle, as in a picture frame. If the segments meet at too sharp an angle (as defined by the miter limit parameter—see “Miter Limit,” above), a bevel join is used instead.

1

Round join. An arc of a circle with a diameter equal to the line width is drawn around the point where the two segments meet, connecting the outer edges of the strokes for the two segments. This pieslice-shaped figure is filled in, producing a rounded corner.

2

Bevel join. The two segments are finished with butt caps (see “Line Cap Style” on page 186) and the resulting notch beyond the ends of the segments is filled with a triangle.


Note

The definition of round join was changed in PDF 1.5. In rare cases, the implementation of the previous specification could produce unexpected results.


Miter Limit

When two line segments meet at a sharp angle and mitered joins have been specified as the line join style, it is possible for the miter to extend far beyond the thickness of the line stroking the path. The miter limit imposes a maximum on the ratio of the miter length to the line width (see Figure 4.7). When the limit is exceeded, the join is converted from a miter to a bevel.

Figure 4.7. Miter length


The ratio of miter length to line width is directly related to the angle ϕ between the segments in user space by the following formula:


For example, a miter limit of 1.414 converts miters to bevels for ϕ less than 90 degrees, a limit of 2.0 converts them for ϕ less than 60 degrees, and a limit of 10.0 converts them for ϕ less than approximately 11.5 degrees.

Line Dash Pattern

The line dash pattern controls the pattern of dashes and gaps used to stroke paths. It is specified by a dash array and a dash phase. The dash array's elements are numbers that specify the lengths of alternating dashes and gaps; the dash phase specifies the distance into the dash pattern at which to start the dash. The elements of both the dash array and the dash phase are expressed in user space units.

Before beginning to stroke a path, the dash array is cycled through, adding up the lengths of dashes and gaps. When the accumulated length equals the value specified by the dash phase, stroking of the path begins, and the dash array is used cyclically from that point onward. Table 4.6 shows examples of line dash patterns. As can be seen from the table, an empty dash array and zero phase can be used to restore the dash pattern to a solid line.

Table 4.6. Examples of line dash patterns
DASH ARRAY AND PHASEAPPEARANCEDESCRIPTION
[ ]0No dash; solid, unbroken lines
[3] 03 units on, 3 units off, …
[2] 11 on, 2 off, 2 on, 2 off, …
[2 1] 02 on, 1 off, 2 on, 1 off, …
[3 5] 62 off, 3 on, 5 off, 3 on, 5 off, …
[2 3] 111 on, 3 off, 2 on, 3 off, 2 on, …


Dashed lines wrap around curves and corners just as solid stroked lines do. The ends of each dash are treated with the current line cap style, and corners within dashes are treated with the current line join style. A stroking operation takes no measures to coordinate the dash pattern with features of the path; it simply dispenses dashes and gaps along the path in the pattern defined by the dash array.

When a path consisting of several subpaths is stroked, each subpath is treated independently—that is, the dash pattern is restarted and the dash phase is reapplied to it at the beginning of each subpath.

4.3.3. Graphics State Operators

Table 4.7 shows the operators that set the values of parameters in the graphics state. (See also the color operators listed in Table 4.24 and the text state operators in Table 5.2 on page 368.)

Table 4.7. Graphics state operators
OPERANDSOPERATORDESCRIPTION
qSave the current graphics state on the graphics state stack (see “Graphics State Stack” on page 184).
QRestore the graphics state by removing the most recently saved state from the stack and making it the current state (see “Graphics State Stack” on page 184).
a b c d e fcmModify the current transformation matrix (CTM) by concatenating the specified matrix (see Section 4.2.1, “Coordinate Spaces”). Although the operands specify a matrix, they are written as six separate numbers, not as an array.
lineWidthwSet the line width in the graphics state (see “Line Width” on page 185).
lineCapJSet the line cap style in the graphics state (see “Line Cap Style” on page 186).
lineJoinjSet the line join style in the graphics state (see “Line Join Style” on page 186).
miterLimitMSet the miter limit in the graphics state (see “Miter Limit” on page 187).
dashArray dashPhasedSet the line dash pattern in the graphics state (see “Line Dash Pattern” on page 187).
intentri(PDF 1.1) Set the color rendering intent in the graphics state (see “Rendering Intents” on page 231).
flatnessiSet the flatness tolerance in the graphics state (see Section 6.5.1, “Flatness Tolerance”). flatness is a number in the range 0 to 100; a value of 0 specifies the output device's default flatness tolerance.
dictNamegs(PDF 1.2) Set the specified parameters in the graphics state. dictName is the name of a graphics state parameter dictionary in the ExtGState subdictionary of the current resource dictionary (see the next section).


4.3.4. Graphics State Parameter Dictionaries

While some parameters in the graphics state can be set with individual operators, as shown in Table 4.7, others cannot. The latter can only be set with the generic graphics state operator gs (PDF 1.2). The operand supplied to this operator is the name of a graphics state parameter dictionary whose contents specify the values of one or more graphics state parameters. This name is looked up in the ExtGState subdictionary of the current resource dictionary. (The name ExtGState, for extended graphics state, is a vestige of earlier versions of PDF.)

Note

The graphics state parameter dictionary is also used by type 2 patterns, which do not have a content stream in which the graphics state operators could be invoked (see Section 4.6.3, “Shading Patterns”).


Each entry in the parameter dictionary specifies the value of an individual graphics state parameter, as shown in Table 4.8. All entries need not be present for every invocation of the gs operator; the supplied parameter dictionary may include any combination of parameter entries. The results of gs are cumulative; parameter values established in previous invocations persist until explicitly overridden. Note that some parameters appear in both Tables 4.7 and 4.8; these parameters can be set either with individual graphics state operators or with gs. It is expected that any future extensions to the graphics state will be implemented by adding new entries to the graphics state parameter dictionary rather than by introducing new graphics state operators.

Table 4.8. Entries in a graphics state parameter dictionary
KEYTYPEDESCRIPTION
Typename(Optional) The type of PDF object that this dictionary describes; must be ExtGState for a graphics state parameter dictionary.
LWnumber(Optional; PDF 1.3) The line width (see “Line Width” on page 185).
LCinteger(Optional; PDF 1.3) The line cap style (see “Line Cap Style” on page 186).
LJinteger(Optional; PDF 1.3) The line join style (see “Line Join Style” on page 186).
MLnumber(Optional; PDF 1.3) The miter limit (see “Miter Limit” on page 187).
Darray(Optional; PDF 1.3) The line dash pattern, expressed as an array of the form [dashArraydashPhase], where dashArray is itself an array and dashPhase is an integer (see “Line Dash Pattern” on page 187).
RIname(Optional; PDF 1.3) The name of the rendering intent (see “Rendering Intents” on page 231).
OPboolean(Optional) A flag specifying whether to apply overprint (see Section 4.5.6, “Overprint Control”). In PDF 1.2 and earlier, there is a single overprint parameter that applies to all painting operations. Beginning with PDF 1.3, there are two separate overprint parameters: one for stroking and one for all other painting operations. Specifying an OP entry sets both parameters unless there is also an op entry in the same graphics state parameter dictionary, in which case the OP entry sets only the overprint parameter for stroking.
opboolean(Optional; PDF 1.3) A flag specifying whether to apply overprint (see Section 4.5.6, “Overprint Control”) for painting operations other than stroking. If this entry is absent, the OP entry, if any, sets this parameter.
OPMinteger(Optional; PDF 1.3) The overprint mode (see Section 4.5.6, “Overprint Control”).
Fontarray(Optional; PDF 1.3) An array of the form [fontsize], where font is an indirect reference to a font dictionary and size is a number expressed in text space units. These two objects correspond to the operands of the Tf operator (see Section 5.2, “Text State Parameters and Operators”); however, the first operand is an indirect object reference instead of a resource name.
BGfunction(Optional) The black-generation function, which maps the interval [0.01.0] to the interval [0.01.0] (see Section 6.2.3, “Conversion from DeviceRGB to DeviceCMYK”).
BG2function or name(Optional; PDF 1.3) Same as BG except that the value may also be the name Default, denoting the black-generation function that was in effect at the start of the page. If both BG and BG2 are present in the same graphics state parameter dictionary, BG2 takes precedence.
UCRfunction(Optional) The undercolor-removal function, which maps the interval [0.0 1.0] to the interval [-1.0 1.0] (see Section 6.2.3, “Conversion from DeviceRGB to DeviceCMYK”).
UCR2function or name(Optional; PDF 1.3) Same as UCR except that the value may also be the name Default, denoting the undercolor-removal function that was in effect at the start of the page. If both UCR and UCR2 are present in the same graphics state parameter dictionary, UCR2 takes precedence.
TRfunction, array, or name(Optional) The transfer function, which maps the interval [0.0 1.0] to the interval [0.0 1.0] (see Section 6.3, “Transfer Functions”). The value is either a single function (which applies to all process colorants) or an array of four functions (which apply to the process colorants individually). The name Identity may be used to represent the identity function.
TR2function, array, or name(Optional; PDF 1.3) Same as TR except that the value may also be the name Default, denoting the transfer function that was in effect at the start of the page. If both TR and TR2 are present in the same graphics state parameter dictionary, TR2 takes precedence.
HTdictionary, stream, or name(Optional) The halftone dictionary or stream (see Section 6.4, “Halftones”) or the name Default, denoting the halftone that was in effect at the start of the page.
FLnumber(Optional; PDF 1.3) The flatness tolerance (see Section 6.5.1, “Flatness Tolerance”).
SMnumber(Optional; PDF 1.3) The smoothness tolerance (see Section 6.5.2, “Smoothness Tolerance”).
SAboolean(Optional) A flag specifying whether to apply automatic stroke adjustment (see Section 6.5.4, “Automatic Stroke Adjustment”).
BMname or array(Optional; PDF 1.4) The current blend mode to be used in the transparent imaging model (see Sections 7.2.4, “Blend Mode,” and 7.5.2, “Specifying Blending Color Space and Blend Mode”).
SMaskdictionary or name(Optional; PDF 1.4) The current soft mask, specifying the mask shape or mask opacity values to be used in the transparent imaging model (see “Source Shape and Opacity” on page 495 and “Mask Shape and Opacity” on page 518).

Note

Although the current soft mask is sometimes referred to as a “soft clip,” altering it with the gs operator completely replaces the old value with the new one, rather than intersecting the two as is done with the current clipping path parameter (see Section 4.4.3, “Clipping Path Operators”).

CAnumber(Optional; PDF 1.4) The current stroking alpha constant, specifying the constant shape or constant opacity value to be used for stroking operations in the transparent imaging model (see “Source Shape and Opacity” on page 495 and “Constant Shape and Opacity” on page 519).
canumber(Optional; PDF 1.4) Same as CA, but for nonstroking operations.
AISboolean(Optional; PDF 1.4) The alpha source flag (“alpha is shape”), specifying whether the current soft mask and alpha constant are to be interpreted as shape values (true) or opacity values (false).
TKboolean(Optional; PDF 1.4) The text knockout flag, which determines the behavior of overlapping glyphs within a text object in the transparent imaging model (see Section 5.2.7, “Text Knockout”).


Example 4.1 shows two graphics state parameter dictionaries. In the first, automatic stroke adjustment is turned on, and the dictionary includes a transfer function that inverts its value, f (x) … 1 − x. In the second, overprint is turned off, and the dictionary includes a parabolic transfer function, f (x) … (2x − 1) 2, with a sample of 21 values. The domain of the transfer function, [0.0 1.0], is mapped to [0 20], and the range of the sample values, [0 255], is mapped to the range of the transfer function, [0.0 1.0].

Example 4.1.

10 0 obj                          % Page object
   << /Type /Page
      /Parent 5 0 R
      /Resources 20 0 R
      /Contents 40 0 R
   >>
endobj

20 0 obj                          % Resource dictionary for page
   << /ProcSet [/PDF /Text]
      /Font << /F1 25 0 R >>
      /ExtGState << /GS1 30 0 R
                    /GS2 35 0 R
                >>
   >>
endobj

30 0 obj                          % First graphics state parameter dictionary
   << /Type /ExtGState
      /SA true
      /TR 31 0 R
   >>
endobj

31 0 obj                          % First transfer function
   << /FunctionType 0
      /Domain [0.0 1.0]
      /Range [0.0 1.0]
      /Size 2
      /BitsPerSample 8
      /Length 7
      /Filter /ASCIIHexDecode
   >>
stream
01 00>
endstream
endobj

35 0 obj                          % Second graphics state parameter dictionary
   << /Type /ExtGState
      /OP false
      /TR36 0 R
   >>
endobj

36 0 obj                          % Second transfer function
   << /FunctionType 0
      /Domain [0.0 1.0]
      /Range [0.0 1.0]
      /Size 21
      /BitsPerSample 8
      /Length 63
      /Filter /ASCIIHexDecode
   >>
stream
FF CE A3 7C 5B 3F 28 16 0A 02 00 02 0A 16 28 3F 5B 7C A3 CE FF >
endstream
endobj


					  

  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint