Geometric Graphics Operators

Model for Geometric Graphics

Shapes are defined geometrically in terms of paths. Paths are composed of path segments, which in turn are composed of path elements as defined in .

Two path elements are connected (1) if they are in sequence in any path segment or (2) if they are the initial and final path elements of a closed path segment. The point at which two path elements connect is called a connection point.

A closed path segment is one for which the end point of the last path element coincides with and is connected to the start point of the initial path element. A closed path is one consisting solely of closed path segments.

Paths are constructed by primitive operators and retained in the Graphics State Variable CurrentPath. A path segment is begun by SetPosition and may be extended by operators such as LineTo and CurveTo. The CurrentPath can be obtained by GetPath and set by SetPath, and is cleared to the null path by the NewPath operator or by the imaging and clipping operators. Several of the imaging operators, RectangleFill and RectangleStroke, and the clipping operator RectangleClip construct a path in conjunction with their other activities.

Paths are given geometrical interpretation only when they are used to specify a mask or a clipping region. At this time the points which define the path are interpreted as defining geometry in the User Coordinate System. The imaging operators StrokePath, FillPath, FillPathEvenOdd, RectangleFill, RectangleStroke, and the clipping operators ClipPath, ClipPathEven and RectangleClip convert this geometry to the Reference Coordinate System by applying the CurrentTransformation. The geometric shapes which result from the execution of these operators are specified by the operator definitions.

Path Construction and Manipulation Operators

This subclause describes the operators used to construct and directly manipulate paths. All path construction operators that affect the value of the CurrentPath Graphics State Variable also implicitly set the value of the CurrentPosition Graphics State Variable to the end point of the current path. A null path has no current point and when a null path is created, the value of the CurrentPosition Graphics State Variable is undefined.

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 .

AppendPath

The AppendPath imaging operator takes one operand

  • <path: PathReference> and returns no results. It appends a copy of the Path referenced by path to the Path referenced by the value of the CurrentPath Graphics State Variable. The CurrentPosition Graphics State Variable is set to the end point of the last path segment in the appended Path.

    ArcToClockwise

    The ArcToClockwise imaging operator takes five operands

  • <t2: Number>
  • <t1: Number>
  • <r: Number>
  • <y: Number>
  • <x: Number> and returns no results. It creates a new path element consisting of a directed circular arc whose
    • center is (x, y);
    • radius is r;
    • start point is the point whose polar coordinates relative to (x, y) are (r, t1);
    • end point is the point whose polar coordinates relative to (x, y) are (r, t2),
    • direction is clockwise.

    The CurrentPosition Graphics State Variable is set to that end point.

    If the CurrentPath is the null path, ArcToClockwise begins a new path segment consisting of the start point of the new path element followed by the new path element.

    If the CurrentPath is not the null path, and if the start point of the new path element coincides with the end point of the last segment of the CurrentPath, the path element is appended to that path segment. Otherwise, if the start point of the new path element does not coincide with the end point of the last segment of the CurrentPath, ArcToClockwise appends to the CurrentPath a line segment whose start point is the end point of the last segment of the CurrentPath and whose end point is the start point of the new path element, then appends the new path element to the line segment.

    ArcToCounterClockwise

    The ArcToCounterClockwise imaging operator has the same semantics as the ArcToClockwise operator (see ), but draws a counterclockwise arc. Specifically, the ArcToCounterClockwise operator takes five operands

  • <t2: Number>
  • <t1: Number>
  • <r: Number>
  • <y: Number>
  • <x: Number> and returns no results. It creates a new path element consisting of a directed circular arc whose
    • center is (x, y);
    • radius is r;
    • start point is the point whose polar coordinates relative to (x, y) are (r, t1);
    • end point is the point whose polar coordinates relative to (x, y) are (r, t2),
    • direction is counterclockwise.

    The CurrentPosition Graphics State Variable is set to that end point.

    If the CurrentPath is the null path, ArcToCounterClockwise begins a new path segment consisting of the start point of the new path element followed by the new path element.

    If the CurrentPath is not the null path, and if the start point of the new path element coincides with the end point of the last segment of the CurrentPath, the path element is appended to that path segment. Otherwise, if the start point of the new path element does not coincide with the end point of the last segment of the CurrentPath, ArcToCounterClockwise appends to the CurrentPath a line segment whose start point is the end point of the last segment of the CurrentPath and whose end point is the start point of the new path element, then appends the new path element to the line segment.

    ClosePathSegment

    The ClosePathSegment imaging operator takes no operand and returns no results. If the current path segment is already closed, or if CurrentPath is the null path, ClosePathSegment has no effect. Otherwise, if (cpsbx, cpsby) are the UCS coordinates of the start point of the last path segment of the CurrentPath, ClosePathSegment is equivalent to {cpsbx cpsby LineTo }, with the additional property that the initial path element of the last path segment is connected to the new final path element of that path segment at the start point of the initial path element and the end point of the new path element. The CurrentPosition Graphics State Variable is set to the point with UCS coordinates (cpsbx, cpsby). A closed path does not result from causing the end point of the last path element of a path segment to coincide with the start point of that path segment; such a path is still an open path and, when used with the StrokePath operator, appropriate stroke ends will be realized at the start and end points of that path segment (see ). For round stroke ends, the result may be indistinguishable from round joins applied to the connection points of the path segment.

    Appending another path element to the CurrentPath immediately after a ClosePathSegment operator will begin a new path segment, even if it is drawn from the end point reached by ClosePathSegment.

    CurveTo

    The CurveTo imaging operator takes six operands

  • <y3: Number>
  • <x3: Number>
  • <y2: Number>
  • <x2: Number>
  • <y1: Number>
  • <x1: Number> and returns no results. It appends a new path element consisting of a Bézier curve to the last path segment of the CurrentPath Graphics State Variable. The start point of this path element is the end point of the last path segment of the CurrentPath. The end point of the path element has UCS coordinates (x3, y3). The CurrentPosition Graphics State Variable is set to that end point. The path element has two Bézier control points whose UCS coordinates are (x1, y1) and (x2, y2).

    More precisely, if the end point on the last path segment of CurrentPath is (x0, y0), the new path element consists of the points on the parametric curve represented by the equations

  • x = axt3 + bxt2 + cxt + dx
  • y = ayt3 + byt2 + cyt + dy

    for 0 ≤ t ≤ 1, where

  • ax=x3 − 3x2+3x1x0
  • ay=y3 − 3y2+3y1y0
  • bx=3x2 − 6x1+3x0
  • by=3y2 − 6y1+3y0
  • cx=3x1 − 3x0
  • cy=3y1 − 3y0
  • dx=x0 dy=y0 the new path element is tangent to the line segment from (x0, y0) to (x1, y1) at its start point and is tangent to the line segment from (x2, y2) to (x3, y3) at its end point, provided those points are distinct.

    If CurrentPath is the null path, RaiseError shall be invoked with NoCurrentPosition as its operand.

    CurveToRelative

    The CurveToRelative imaging operator takes six operands

  • <y3: Number>
  • <x3: Number>
  • <y2: Number>
  • <x2: Number>
  • <y1: Number>
  • <x1: Number> and returns no results. If (cpsx, cpsy) is the UCS point which corresponds to the end point of the last path segment of the CurrentPath, CurveToRelative appends a new path element consisting of a Bézier curve to the last path segment of the CurrentPath Graphics State Variable. The start point of this path element is the end point of the last path segment of the CurrentPath. The end point of the path element has UCS coordinates (cpsx+x3, cpsy+y3). The CurrentPosition Graphics State Variable is set to that end point. The path element has two Bézier control points whose UCS coordinates are (cpsx+x2, cpsy+y2) and (cpsx+x3, cpsy+y3). The equations for this curve are as given in .

    If CurrentPath is the null path, RaiseError shall be invoked with NoCurrentPosition as its operand.

    GetPath

    The GetPath imaging operator takes no operands and returns one result

  • <path: PathReference> where path is a reference to a copy of the Path that is referenced by the value of the CurrentPath Graphics State Variable. CurrentPath is not affected by GetPath.

    GlyphToPath

    The GlyphToPath imaging operator takes two operands

  • <fill: Boolean>
  • <glyphstr: GlyphString> and returns no results. GlyphToPath appends to the CurrentPath a set of path segments which describe the glyph shapes as they would be presented by the ShowString operator (see ). If the value of fill is true, the path segments are constructed in such a way as to make them suitable for filling or clipping via the FillPath or one of the ClipPath operators. If the value of fill is false, the path segments are constructed in such a way as to make them suitable only for being stroked via the StrokePath operator. The CurrentPosition Graphics State Variable is set to the end point of the last generated path segment added to the CurrentPath. The effect of applying the StrokePath operator to a path suitable for filling, or of applying the FillPath or one of the two ClipPath operators to a path suitable for stroking, is not defined by this International Standard and may result in an exception being raised.

    If CurrentPath is the null path, RaiseError shall be invoked with NoCurrentPosition as its operand.

    LineTo

    The LineTo imaging operator takes two operands

  • <y: Number>
  • <x: Number>
  • and returns no results. It appends a new path element consisting of a straight line segment, whose start point is the end point of the last path segment of the CurrentPath and whose end point has UCS coordinates (x, y), to the CurrentPath Graphics State Variable. The CurrentPosition Graphics State Variable is set to that end point.

    If CurrentPath is the null path, RaiseError shall be invoked with NoCurrentPosition as its operand.

    LineToRelative

    The LineToRelative imaging operator takes two operands

  • <y: Number>
  • <x: Number> and returns no results. If (cpsx, cpsy) is the UCS point which corresponds to the end point of the last segment of the CurrentPath, LineToRelative appends a new path element to the last segment of the CurrentPath consisting of a straight line segment, whose start point is the end point of the last path segment of the CurrentPath and whose end point has UCS coordinates (cpsx+x, cpsy+ y). The CurrentPosition Graphics State Variable is set to that end point.

    If CurrentPath is the null path, RaiseError shall be invoked with NoCurrentPosition as its operand.

    NewPath

    The NewPath operator takes no operands and returns no results. It sets the Graphics State Variable CurrentPath to the null path, and makes the value of the CurrentPosition Graphics State Variable undefined.

    OutlineStroke

    The OutlineStroke imaging operator takes no operands and returns no results. It replaces the value of the CurrentPath Graphics State Variable with a path that exactly encloses the shape that would result if the StrokePath operator were applied to the CurrentPath. The path resulting from OutlineStroke is suitable as the implicit operand to FillPath or ClipPath. In general, this path is not suitable for StrokePath, as it may contain interior path elements or disconnected path segments that are produced by OutlineStroke's stroke to outline conversion process. If OutlineStrokeapplied to the CurrentPath would not affect the page image, then the CurrentPath is set to the null path, and the value of the CurrentPosition Graphics State Variable shall be undefined.

    SetPath

    The SetPath imaging operator takes one operand

  • <path: PathReference> and returns no results. It sets the value of the CurrentPath Graphics State Variable to a reference to a copy of the Path referenced by path. The CurrentPosition Graphics State Variable is set to the end point of the last path segment of the Path referenced by path.

    Stroking and Filling Operators

    This subclause describes the operators used to stroke and fill the regions described by paths. 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 .

    FillPath

    The FillPath imaging operator accepts no operands and returns no results. It performs an imaging activity using a mask defined using the CurrentPath Graphics State Variable. It sets the value of CurrentPath to the null path and makes the CurrentPosition Graphics State Variable be undefined.

    In performing the imaging activity, FillPath implicitly closes any open path segments and defines a mask which includes the interior and boundary of the resulting shape determined according to the non-zero winding rule. The mask is then used with the CurrentColor and CurrentClippingRegion to add an image element to the current page image.

    The effect of executing the FillPath operator when the CurrentPath consists of a single line segment is equivalent to {0 SetStrokeWidth StrokePath}.

    FillPathEvenOdd

    The FillPathEvenOdd imaging operator accepts no operands and returns no results. It performs an imaging activity using a mask defined using the CurrentPath Graphics State Variable. It sets the value of CurrentPath to the null path and makes the CurrentPosition Graphics State Variable be undefined.

    In performing the imaging activity, FillPathEvenOdd implicitly closes any open path segments and defines a mask which includes the interior and boundary of the resulting shape determined according to the even/odd winding rule. The mask is then used with the CurrentColor and CurrentClippingRegion to add an image element to the current page image.

    The effect of executing the FillPathEvenOdd operator when the CurrentPath consists of a single line segment is equivalent to {0 SetStrokeWidth StrokePath}.

    StrokePath

    The StrokePath imaging operator accepts no operands and returns no results. It performs an imaging activity using a mask defined by CurrentPath, CurrentDashPattern, CurrentMiterLimit, CurrentStrokeAdjust, CurrentStrokeWidth, CurrentStrokeJoin, and CurrentStrokeEnd as specified below. It sets the value of CurrentPath to the null path and makes the CurrentPosition Graphics State Variable be undefined.

    In performing the imaging activity, StrokePath constructs a mask in the User Coordinate Space, transforms the mask to Reference Coordinate Space using the CurrentTransformation, and paints an image element using this mask, the CurrentColor, and the CurrentClippingRegion. In performing these functions, StrokePath

    • transforms the CurrentPath to User Coordinate Space using the inverse of the CurrentTransformation;
    • constructs a shape in the User Coordinate System as described below;
    • transforms this shape to Reference Coordinate Space using the CurrentTransformation;
    • paints an image element using
      • a mask whose interior and boundary is the shape described above,
      • the CurrentColor,
      • the CurrentClippingRegion.
    Examples of Dash Patterns

    The shape constructed in the second step is either a solid line or a dashed line along each of the path segments, depending on the value of CurrentDashPattern (see ). If the Vector component of CurrentDashPattern is the empty Vector, the shape is constructed by

    • widening each path segment to width CurrentStrokeWidth uniformly in the UCS in such a way that the resultant widened line is longitudinally bisected by the original path segment;
    • applying the stroke end features specified by CurrentStrokeEnd (as shown in ) to the ends of each path segment;
    • applying the join features specified by CurrentStrokeJoin (as shown in ), and possibly as modified by CurrentMiterLimit (see ) to connection points of a path segment.

    If the value of the CurrentStrokeWidth Graphics State Variable is 0, the actual stroke width used is the smallest width the presentation device is capable of producing.

    The actual width of the stroke may also differ from the value of CurrentStrokeWidth if the value of the CurrentStrokeAdjust Graphics State Variable is true; If the value of CurrentStrokeAdjust is true, the stroke width and the coordinates of a stroke are automatically adjusted as necessary to produce lines of uniform thickness, and whose widths are no more than ± half a pixel different from the requested width (as determined by the value of the CurrentStrokeWidth Graphics State Variable).

    If the Vector component of CurrentDashPattern is non-empty, a new path is constructed in User Coordinate System and a shape is constructed using that path as described above.

    If the value of the CurrentDashPattern Graphics State Variable is

  • <v: Vector><x: Number> then the new path is obtained from the transformation of the CurrentPath to User Coordinate System generated in the first step as follows:
    • The Vector v is interpreted as a sequence of distances along the transformation of the CurrentPath to User Coordinate Space. These distances alternately specify the length of a dash and the length of a gap between dashes. The contents of v are used cyclically for as many values and as many cycles as needed (see Figure 11).
    • The Number x is interpreted as an offset into the sequence of distances specified by the cyclic use of v. Before beginning to stroke a path, the elements of v are cycled through adding up the sum of the elements (dash lengths and gap lengths) until a total distance of x has been used. The lengths used to generate the dash pattern are the remainder of the element after the offset x has been subtracted from it plus the succeeding lengths taken from the cyclic processing of v.
    • The new path consists of a sequence of path segments which are those parts of the transformation of the CurrentPath to User Coordinate Space which correspond to the dash elements obtained from CurrentDashPattern.

    If the result of the transformation of the CurrentPath to User Coordinate Space contains no displacement from the start point of the path, the path is said to have zero length. Stroking a path with no path elements does not affect the page image. Thus the code fragment {NewPath x y SetPosition StrokePath} produces no marks on the current page. Stroking a zero length path will also not affect the page image unless the CurrentStrokeEnd Graphics State Variable specifies round stroke ends; in this case the stroke ends will appear when the path is stroked.

    Effect of CurrentMiterLimit on Stroke Joins

    At any given corner (a connection point between two non-tangential path elements), the miter length is the distance from the point at which the inner edges of the stroke (as constructed in User Coordinate System by the StrokePath operator) intersect to the point at which the outside edges of the stroke intersect. This distance increases as the angle between the path elements decreases.

    The CurrentMiterLimit Graphics State Variable value is employed to prevent this distance, the diagonal length of the miter, from exceeding a desired maximum length when the value of the CurrentStrokeJoin specifies that the StrokePath operator use miter joins. When the ratio of the miter length of a given join to the actual stroke width exceeds the CurrentMiterLimit, the StrokePath operator constructs the stroke for the join as if the value of the CurrentStrokeJoin Graphics State Variable specified a bevel join rather than a miter join. The formula for the ratio of the miter length to the stroke width is

  • miter length / stroke width = 1 / sin(angle/2) where angle is the angle of the intersection of the two path elements.

    Rectangular Fill and Stroke Operators

    There are two operators which combine defining a path and either stroking or filling that path.

    RectangleFill

    The RectangleFill imaging operator takes four operands

  • <height: Number>
  • <width: Number>
  • <y: Number>
  • <x: Number> and returns no results. It creates a new closed rectangular path with one path segment, fills its and destroys the path all without reading or altering the CurrentPath Graphics State Variable or the CurrentPosition Graphics State Variable.

    Under the assumption that height and width are positive, the RectangleFill operator is equivalent to the following procedure:

  • {
  • SaveGraphicsState
  • % Start a new path for the rectangle
  • NewPath
  • % Position at one corner
  • x y SetPosition
  • % Draw lines to other corner
  • width 0 LineToRelative
  • 0 height LineToRelative
  • % Add final two sides of rectangle
  • width Negate 0 LineToRelative
  • ClosePathSegment
  • % Fill the result
  • FillPath
  • % Erase all trace of the rectangle path
  • RestoreGraphicsState
  • }

    RectangleStroke

    The RectangleStroke imaging operator takes either four operands

  • <height: Number>
  • <width: Number>
  • <y: Number>
  • <x: Number> or five operands
  • <matrix: Transformation>
  • <height: Number>
  • <width: Number>
  • <y: Number>
  • <x: Number> and returns no results. It creates a new closed rectangular path with one path segment, strokes its and destroys the path all without reading or altering the CurrentPath Graphics State Variable or the CurrentPosition Graphics State Variable.

    If the matrix operand is present, the RectangleStroke operator concatenates matrix to the CTM after defining the rectangular path, but before stroking that path. The matrix applies to the strokewidth and dash pattern, if any, but not to the path itself.

    Under the assumption that height and width are positive, the RectangleStroke operator is equivalent to the following procedure:

  • {
  • SaveGraphicsState
  • % Start a new path for the rectangle
  • NewPath
  • %Position at one corner
  • x y SetPosition
  • % Draw lines to other corner
  • width 0 LineToRelative
  • 0 height LineToRelative
  • % Add final two sides of rectangle
  • width Negate 0 LineToRelative
  • ClosePathSegment
  • % Change CTM if matrix operand present
  • matrix Concat
  • % Stroke the result
  • StrokePath
  • % Erase all trace of the rectangle path
  • RestoreGraphicsState
  • }

    Graphics State Variable Operators

    This subclause describes the operators used to obtain and affect the values of the Graphics State Variables that control various parameters of the stroking and filling processes.

    GetDashPattern

    The GetDashPattern operator takes no operands and returns two results

  • <offset: Number>
  • <pattern: VectorReference> where pattern is a reference to a Vector in which the elements are of type Number and the two results together form the current value of the CurrentDashPattern Graphics State Variable in the Graphics State.

    GetMiterLimit

    The GetMiterLimit operator takes no operands and returns one result

  • <limit: Number> where limit is the value of the CurrentMiterLimit Graphics State Variable in the Graphics State.

    GetStrokeAdjust

    The GetStrokeAdjust operator takes no operands and returns one result

  • <adjust: Boolean>

    where adjust is the value of the CurrentStrokeAdjust Graphics State Variable in the Graphics State.

    GetStrokeEnd

    The GetStrokeEnd operator takes no operands and returns one result

  • <end: Number> where end is the value of the CurrentStrokeEnd Graphics State Variable in the Graphics State.

    GetStrokeJoin

    The GetStrokeJoin operator takes no operands and returns one result

  • <join: Number> where join is the value of the CurrentStrokeJoin Graphics State Variable in the Graphics State.

    GetStrokeWidth

    The GetStrokeWidth operator takes no operands and returns one result

  • <width: Number> where width is the value of the CurrentStrokeWidth Graphics State Variable in the Graphics State.

    SetDashPattern

    The SetDashPattern operator takes two operands

  • <offset: Number>
  • <pattern: VectorReference> where pattern is a reference to a Vector in which the elements are of type Number and returns no results. It sets theCurrentDashPattern Graphics State Variable to <pattern><offset>. The effect of CurrentDashPattern is defined by the semantics of the StrokePath operator.

    SetMiterLimit

    The SetMiterLimit operator takes one operand

  • <x: Number> and returns no results. It sets the CurrentMiterLimit Graphics State Variable to x, where x shall have value greater than or equal to 1. The effect of CurrentMiterLimit is defined in .

    SetStrokeAdjust

    The SetStrokeAdjust operator takes one operand

  • <adjust: Boolean> and returns no results. It sets the value of the CurrentStrokeAdjust Graphics State Variable to the value of adjust. The effect of CurrentStrokeAdjust is defined in the semantics of the StrokePath operator. Stroke End Features

    SetStrokeEnd

    The SetStrokeEnd operator takes one operand

  • <n: Cardinal> where n = 0, 1, or 2, and returns no results. It sets the CurrentStrokeEnd Graphics State Variable to one of the following as shown in . Valuestroke ends 0Selects butt stroke ends. The stroke is squared off at the end point of the path; there is no projection beyond the path 1Selects round stroke ends. A circle with diameter equal to the line width is drawn around the end point and filled in 2Selects projecting square stroke ends. The stroke continues beyond the end point of the path for a distance equal to half the line width, and is squared off

    The effect of CurrentStrokeEnd on the mask generated by StrokePath is shown in .

    SetStrokeJoin

    The SetStrokeJoin operator takes one operand

  • <n: Cardinal> where n= 0, 1, or 2, and returns no results. It sets the CurrentStrokeJoin Graphics State Variable to one of the following as shown in . Valuemiter join 0Selects miter join. The outer edges of the strokes are extended until they meet 1Selects round join. A circle with diameter equal to the CurrentStrokeWidth is drawn around the point where the path elements connect and is filled in 2Selects bevel join. The connected path elements are finished with butt stroke ends; then the triangle defined by the outside endpoints of the butt stroke ends and the connection point is filled

    The effect of CurrentStrokeJoin on the mask generated by StrokePath is shown in . Stroke Join Features

    SetStrokeWidth

    The SetStrokeWidth operator takes one operand

  • <x: Number> and returns no results. It sets the CurrentStrokeWidth Graphics State Variable to x. The effect of CurrentStrokeWidth is defined by the StrokePath operator.