.
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+3x1 −
x0
ay=y3 −
3y2+3y1 −
y0
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.