.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Content 3pm"
.TH PDF::Builder::Content 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder::Content \- Methods for adding graphics and text to a PDF
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    # Start with a PDF page (new or opened)
\&    my $pdf = PDF::Builder\->new();
\&    my $page = $pdf\->page();
\&
\&    # Add new content object(s)
\&    my $content = $page\->gfx();
\&    #   and/or (as separate object name)
\&    my $content = $page\->text();
\&
\&    # Then call the methods below to add graphics and text to the page.
\&    # Note that negative coordinates can have unpredictable effects, so
\&    # keep your coordinates non\-negative!
.Ve
.PP
These methods add content to \fIstreams\fR output for text or graphics objects.
Unless otherwise restricted by a check that we are in or out of text mode,
many methods listed here apply equally to text and graphics streams. It is
possible that there \fIare\fR some which have no effect in one stream type or
the other, but are currently lacking a check to prevent them from being 
inserted into an inapplicable stream.
.SH "METHODS"
.IX Header "METHODS"
All public methods listed, \fIexcept as otherwise noted,\fR return \f(CW$self\fR.
.SS "Coordinate Transformations"
.IX Subsection "Coordinate Transformations"
The methods in this section change the coordinate system for the
current content object relative to the rest of the document.
\&\fBNote:\fR the changes are relative to the \fIoriginal\fR page coordinates (and 
thus, absolute), not to the previous position! Thus, \f(CW\*(C`translate(10, 10); 
translate(10, 10);\*(C'\fR ends up only moving the origin to \f(CW\*(C`[10, 10]\*(C'\fR, rather than 
to \f(CW\*(C`[20, 20]\*(C'\fR. There is one call, \f(CW\*(C`transform_rel()\*(C'\fR, which makes your changes 
\&\fIrelative\fR to the previous position.
.PP
If you call more than one of these methods, the \s-1PDF\s0 specification
recommends calling them in the following order: translate, rotate,
scale, skew.  Each change builds on the last, and you can get
unexpected results when calling them in a different order.
.PP
\&\fB\s-1CAUTION:\s0\fR a \fItext\fR object ($content) behaves a bit differently. Individual
translate, rotate, scale, and skew calls \fIcancel out\fR any previous settings.
If you want to combine multiple transformations for text, use the \f(CW\*(C`transform\*(C'\fR
call.
.ie n .IP "$content\->translate($dx,$dy)" 4
.el .IP "\f(CW$content\fR\->translate($dx,$dy)" 4
.IX Item "$content->translate($dx,$dy)"
Moves the origin along the x and y axes by 
\&\f(CW$dx\fR and \f(CW$dy\fR respectively.
.ie n .IP "$content\->rotate($degrees)" 4
.el .IP "\f(CW$content\fR\->rotate($degrees)" 4
.IX Item "$content->rotate($degrees)"
Rotates the coordinate system counter-clockwise (anti-clockwise) around the
current origin. Use a negative argument to rotate clockwise. Note that 360 
degrees will be treated as 0 degrees.
.Sp
\&\fBNote:\fR Unless you have already moved (translated) the origin, it is, and will
remain, at the lower left corner of the visible sheet. It will \fInot\fR
automatically shift to another corner. For example, a rotation of +90 degrees
(counter-clockwise) will leave the entire visible sheet in negative Y territory (0 at the left edge, \-original_width at the right edge), while X remains in
positive territory (0 at bottom, +original_height at the top edge).
.Sp
This \f(CW\*(C`rotate()\*(C'\fR call permits any angle. Do not confuse it with the \fIpage\fR
rotation \f(CW\*(C`rotate\*(C'\fR call, which only permits increments of 90 degrees (with
opposite sign!), but \fIdoes\fR shift the origin to another corner of the sheet.
.ie n .IP "$content\->scale($sx,$sy)" 4
.el .IP "\f(CW$content\fR\->scale($sx,$sy)" 4
.IX Item "$content->scale($sx,$sy)"
Scales (stretches) the coordinate systems along the x and y axes.
Separate multipliers are provided for x and y.
.ie n .IP "$content\->skew($skx,$sky)" 4
.el .IP "\f(CW$content\fR\->skew($skx,$sky)" 4
.IX Item "$content->skew($skx,$sky)"
Skews the coordinate system by \f(CW$skx\fR degrees 
(counter\-clockwise/anti\-clockwise) from
the x axis \fIand\fR \f(CW$sky\fR degrees (clockwise) from the y axis.
Note that 360 degrees will be treated the same as 0 degrees.
.ie n .IP "$content\->transform(%opts)" 4
.el .IP "\f(CW$content\fR\->transform(%opts)" 4
.IX Item "$content->transform(%opts)"
Use one or more of the given \f(CW%opts:\fR
.Sp
.Vb 8
\&    $content\->transform(
\&        \-translate => [$dx,$dy],
\&        \-rotate    => $degrees,
\&        \-scale     => [$sx,$sy],
\&        \-skew      => [$skx,$sky],
\&        \-matrix    => [$a, $b, $c, $d, $e, $f],
\&        \-point     => [$x,$y]
\&    )
.Ve
.Sp
A six element list may be given (\f(CW\*(C`\-matrix\*(C'\fR) for a 
further transformation matrix:
.Sp
.Vb 6
\&    $a = cos(rot) * scale factor for X 
\&    $b = sin(rot) * tan(skew for X)
\&    $c = \-sin(rot) * tan(skew for Y)
\&    $d = cos(rot) * scale factor for Y 
\&    $e = translation for X
\&    $f = translation for Y
.Ve
.Sp
Performs multiple coordinate transformations at once, in the order
recommended by the \s-1PDF\s0 specification (translate, rotate, scale, skew).
This is equivalent to making each transformation separately, \fIin the
indicated order\fR.
A matrix of 6 values may also be given (\f(CW\*(C`\-matrix\*(C'\fR). The transformation matrix 
is updated. 
A \f(CW\*(C`\-point\*(C'\fR may be given (a point to be multiplied [transformed] by the 
completed matrix).
.ie n .IP "$content\->transform_rel(%opts)" 4
.el .IP "\f(CW$content\fR\->transform_rel(%opts)" 4
.IX Item "$content->transform_rel(%opts)"
Makes transformations similarly to \f(CW\*(C`transform\*(C'\fR, except that it \fIadds\fR
to the previously set values, rather than \fIreplacing\fR them (except for 
\&\fIscale\fR, which \fBmultiplies\fR the new values with the old).
.Sp
Unlike \f(CW\*(C`transform\*(C'\fR, \f(CW\*(C`\-matrix\*(C'\fR and \f(CW\*(C`\-point\*(C'\fR are not supported.
.ie n .IP "$content\->matrix($a, $b, $c, $d, $e, $f)" 4
.el .IP "\f(CW$content\fR\->matrix($a, \f(CW$b\fR, \f(CW$c\fR, \f(CW$d\fR, \f(CW$e\fR, \f(CW$f\fR)" 4
.IX Item "$content->matrix($a, $b, $c, $d, $e, $f)"
\&\fI(Advanced)\fR Sets the current transformation matrix manually. Unless
you have a particular need to enter transformations manually, you
should use the \f(CW\*(C`transform\*(C'\fR method instead.
.Sp
.Vb 6
\& $a = cos(rot) * scale factor for X 
\& $b = sin(rot) * tan(skew for X)
\& $c = \-sin(rot) * tan(skew for Y)
\& $d = cos(rot) * scale factor for Y 
\& $e = translation for X
\& $f = translation for Y
.Ve
.Sp
In text mode, the text matrix is \fBreturned\fR. 
In graphics mode, \f(CW$self\fR is \fBreturned\fR.
.SS "Graphics State Parameters"
.IX Subsection "Graphics State Parameters"
The following calls also affect the \fBtext\fR state.
.ie n .IP "$content\->linewidth($width)" 4
.el .IP "\f(CW$content\fR\->linewidth($width)" 4
.IX Item "$content->linewidth($width)"
Sets the width of the stroke. This is the line drawn in graphics mode, or the 
\&\fIoutline\fR of a character in text mode (with appropriate \f(CW\*(C`render\*(C'\fR mode).
If no \f(CW$width\fR is given, the current setting is \fBreturned\fR. If the width is
being set, \f(CW$self\fR is \fBreturned\fR so that calls may be chained.
.ie n .IP "$content\->linecap($style)" 4
.el .IP "\f(CW$content\fR\->linecap($style)" 4
.IX Item "$content->linecap($style)"
Sets the style to be used at the end of a stroke. This applies to lines
which come to a free-floating end, \fInot\fR to \*(L"joins\*(R" (\*(L"corners\*(R") in 
polylines (see \f(CW\*(C`linejoin\*(C'\fR).
.RS 4
.IP "0 = Butt Cap" 4
.IX Item "0 = Butt Cap"
The stroke ends at the end of the path, with no projection.
.IP "1 = Round Cap" 4
.IX Item "1 = Round Cap"
A semicircular arc is drawn around the end of the path with a diameter equal to
the line width, and is filled in.
.IP "2 = Projecting Square Cap" 4
.IX Item "2 = Projecting Square Cap"
The stroke continues past the end of the path for half the line width.
.RE
.RS 4
.Sp
If no \f(CW$style\fR is given, the current setting is \fBreturned\fR. If the style is
being set, \f(CW$self\fR is \fBreturned\fR so that calls may be chained.
.RE
.ie n .IP "$content\->linejoin($style)" 4
.el .IP "\f(CW$content\fR\->linejoin($style)" 4
.IX Item "$content->linejoin($style)"
Sets the style of join to be used at corners of a path
(within a multisegment polyline).
.RS 4
.IP "0 = Miter Join" 4
.IX Item "0 = Miter Join"
The outer edges of the strokes extend until they meet, up to the limit
specified by \fImiterlimit\fR. If the limit would be surpassed, a \fIbevel\fR join
is used instead. For a given linewidth, the more acute the angle is (closer
to 0 degrees), the higher the ratio of miter length to linewidth will be, and 
that's what \fImiterlimit\fR controls.
.IP "1 = Round Join" 4
.IX Item "1 = Round Join"
A filled circle with a diameter equal to the \fIlinewidth\fR is drawn around the
corner point, producing a rounded corner. The arc will meet up with the sides
of the line in a smooth tangent.
.IP "2 = Bevel Join" 4
.IX Item "2 = Bevel Join"
A filled triangle is drawn to fill in the notch between the two strokes.
.RE
.RS 4
.Sp
If no \f(CW$style\fR is given, the current setting is \fBreturned\fR. If the style is
being set, \f(CW$self\fR is \fBreturned\fR so that calls may be chained.
.RE
.ie n .IP "$content\->miterlimit($ratio)" 4
.el .IP "\f(CW$content\fR\->miterlimit($ratio)" 4
.IX Item "$content->miterlimit($ratio)"
Sets the miter limit when the line join style is a \fImiter\fR join.
.Sp
The ratio is the maximum length of the miter (inner to outer corner) divided 
by the line width. Any miter above this ratio will be converted to a \fIbevel\fR 
join. The practical effect is that lines meeting at shallow
angles are chopped off instead of producing long pointed corners.
.Sp
The default miter limit is 10.0 (approximately 11.5 degree cutoff angle).
The smaller the limit, the larger the cutoff angle.
.Sp
If no \f(CW$ratio\fR is given, the current setting is \fBreturned\fR. If the ratio is
being set, \f(CW$self\fR is \fBreturned\fR so that calls may be chained.
.ie n .IP "$content\->\fBlinedash()\fR" 4
.el .IP "\f(CW$content\fR\->\fBlinedash()\fR" 4
.IX Item "$content->linedash()"
.PD 0
.ie n .IP "$content\->linedash($length)" 4
.el .IP "\f(CW$content\fR\->linedash($length)" 4
.IX Item "$content->linedash($length)"
.ie n .IP "$content\->linedash($dash_length, $gap_length, ...)" 4
.el .IP "\f(CW$content\fR\->linedash($dash_length, \f(CW$gap_length\fR, ...)" 4
.IX Item "$content->linedash($dash_length, $gap_length, ...)"
.ie n .IP "$content\->linedash(\-pattern => [$dash_length, $gap_length, ...], \-shift => $offset)" 4
.el .IP "\f(CW$content\fR\->linedash(\-pattern => [$dash_length, \f(CW$gap_length\fR, ...], \-shift => \f(CW$offset\fR)" 4
.IX Item "$content->linedash(-pattern => [$dash_length, $gap_length, ...], -shift => $offset)"
.PD
Sets the line dash pattern.
.Sp
If called without any arguments, a solid line will be drawn.
.Sp
If called with one argument, the dashes and gaps (strokes and
spaces) will have equal lengths.
.Sp
If called with two or more arguments, the arguments represent
alternating dash and gap lengths.
.Sp
If called with a hash of arguments, the \fI\-pattern\fR array may have one or
more elements, specifying the dash and gap lengths. 
A dash phase may be set (\fI\-shift\fR), which is a \fBpositive integer\fR
specifying the distance into the pattern at which to start the dashed line.
Note that if you wish to give a \fIshift\fR amount, using \f(CW\*(C`\-shift\*(C'\fR,
you need to use \f(CW\*(C`\-pattern\*(C'\fR instead of one or two elements.
.Sp
If an \fBodd\fR number of dash array elements are given, the list is repeated by 
the reader software to form an even number of elements (pairs).
.Sp
If a single argument of \fB\-1\fR is given, the current setting is \fBreturned\fR. 
This is an array consisting of two elements: an anonymous array containing the 
dash pattern (default: empty), and the shift (offset) amount (default: 0). 
If the dash pattern is being \fIset\fR, \f(CW$self\fR is \fBreturned\fR so that calls may 
be chained.
.ie n .IP "$content\->flatness($tolerance)" 4
.el .IP "\f(CW$content\fR\->flatness($tolerance)" 4
.IX Item "$content->flatness($tolerance)"
\&\fI(Advanced)\fR Sets the maximum variation in output pixels when drawing
curves. The defined range of \f(CW$tolerance\fR is 0 to 100, with 0 meaning \fIuse 
the device default flatness\fR. According to the \s-1PDF\s0 specification, you should 
not try to force visible line segments (the curve's approximation); results 
will be unpredictable. Usually, results for different flatness settings will be 
indistinguishable to the eye.
.Sp
The \f(CW$tolerance\fR value is silently clamped to be between 0 and 100.
.Sp
If no \f(CW$tolerance\fR is given, the current setting is \fBreturned\fR. If the 
tolerance is being set, \f(CW$self\fR is \fBreturned\fR so that calls may be chained.
.ie n .IP "$content\->egstate($object)" 4
.el .IP "\f(CW$content\fR\->egstate($object)" 4
.IX Item "$content->egstate($object)"
\&\fI(Advanced)\fR Adds an Extended Graphic State \fBobject\fR containing additional
state parameters.
.SS "Path Construction (Drawing)"
.IX Subsection "Path Construction (Drawing)"
.ie n .IP "$content\->move($x,$y)" 4
.el .IP "\f(CW$content\fR\->move($x,$y)" 4
.IX Item "$content->move($x,$y)"
Starts a new path at the specified coordinates.
Note that multiple x,y pairs \fIcan\fR be given, although this isn't that useful
(only the last pair would have an effect).
.ie n .IP "$content\->\fBclose()\fR" 4
.el .IP "\f(CW$content\fR\->\fBclose()\fR" 4
.IX Item "$content->close()"
Closes and ends the current path by extending a line from the current
position to the starting position.
.ie n .IP "$content\->\fBendpath()\fR" 4
.el .IP "\f(CW$content\fR\->\fBendpath()\fR" 4
.IX Item "$content->endpath()"
Ends the current path without explicitly enclosing it.
That is, unlike \f(CW\*(C`close\*(C'\fR, there is \fBno\fR line segment 
drawn back to the starting position.
.PP
\fIStraight line constructs\fR
.IX Subsection "Straight line constructs"
.PP
\&\fBNote:\fR None of these will actually be \fIvisible\fR until you call \f(CW\*(C`stroke\*(C'\fR or 
\&\f(CW\*(C`fill\*(C'\fR. They are merely setting up the path to draw.
.ie n .IP "$content\->line($x,$y)" 4
.el .IP "\f(CW$content\fR\->line($x,$y)" 4
.IX Item "$content->line($x,$y)"
.PD 0
.ie n .IP "$content\->line($x,$y, $x2,$y2,...)" 4
.el .IP "\f(CW$content\fR\->line($x,$y, \f(CW$x2\fR,$y2,...)" 4
.IX Item "$content->line($x,$y, $x2,$y2,...)"
.PD
Extends the path in a line from the \fIcurrent\fR coordinates to the
specified coordinates, and updates the current position to be the new
coordinates.
.Sp
Multiple additional \f(CW\*(C`[$x,$y]\*(C'\fR pairs are permitted, to draw joined multiple 
line segments. Note that this is \fBnot\fR equivalent to a polyline (see \f(CW\*(C`poly\*(C'\fR),
because the first \f(CW\*(C`[$x,$y]\*(C'\fR pair in a polyline is a \fImove\fR operation.
Also, the \f(CW\*(C`linecap\*(C'\fR setting will be used rather than the \f(CW\*(C`linejoin\*(C'\fR
setting for treating the ends of segments.
.ie n .IP "$content\->hline($x)" 4
.el .IP "\f(CW$content\fR\->hline($x)" 4
.IX Item "$content->hline($x)"
.PD 0
.ie n .IP "$content\->vline($y)" 4
.el .IP "\f(CW$content\fR\->vline($y)" 4
.IX Item "$content->vline($y)"
.PD
Shortcuts for drawing horizontal and vertical lines from the current
position. They are like \f(CW\*(C`line()\*(C'\fR, but to the new x and current y (\f(CW\*(C`hline\*(C'\fR),
or to the the current x and new y (\f(CW\*(C`vline\*(C'\fR).
.ie n .IP "$content\->poly($x1,$y1, ..., $xn,$yn)" 4
.el .IP "\f(CW$content\fR\->poly($x1,$y1, ..., \f(CW$xn\fR,$yn)" 4
.IX Item "$content->poly($x1,$y1, ..., $xn,$yn)"
This is a shortcut for creating a polyline path. It moves to \f(CW\*(C`[$x1,$y1]\*(C'\fR, and
then extends the path in line segments along the specified coordinates.
The current position is changed to the last \f(CW\*(C`[$x,$y]\*(C'\fR pair given.
.Sp
The difference between a polyline and a \f(CW\*(C`line\*(C'\fR with multiple \f(CW\*(C`[$x,$y]\*(C'\fR
pairs is that the first pair in a polyline are a \fImove\fR, while in a line
they are a \fIdraw\fR.
Also, \f(CW\*(C`linejoin\*(C'\fR instead of \f(CW\*(C`linecap\*(C'\fR is used to control the appearance
of the ends of line segments.
.ie n .IP "$content\->rect($x,$y, $w,$h)" 4
.el .IP "\f(CW$content\fR\->rect($x,$y, \f(CW$w\fR,$h)" 4
.IX Item "$content->rect($x,$y, $w,$h)"
.PD 0
.ie n .IP "$content\->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)" 4
.el .IP "\f(CW$content\fR\->rect($x1,$y1, \f(CW$w1\fR,$h1, ..., \f(CW$xn\fR,$yn, \f(CW$wn\fR,$hn)" 4
.IX Item "$content->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)"
.PD
This creates paths for one or more rectangles, with their lower left points
at \f(CW\*(C`[$x,$y]\*(C'\fR and specified widths (+x direction) and heights (+y direction). 
Negative widths and heights are permitted, which draw to the left (\-x) and 
below (\-y) the given corner point, respectively. 
The current position is changed to the \f(CW\*(C`[$x,$y]\*(C'\fR of the last rectangle given.
Note that this is the \fIstarting\fR point of the rectangle, not the end point.
.ie n .IP "$content\->rectxy($x1,$y1, $x2,$y2)" 4
.el .IP "\f(CW$content\fR\->rectxy($x1,$y1, \f(CW$x2\fR,$y2)" 4
.IX Item "$content->rectxy($x1,$y1, $x2,$y2)"
This creates a rectangular path, with \f(CW\*(C`[$x1,$y1]\*(C'\fR and \f(CW\*(C`[$x2,$y2]\*(C'\fR
specifying \fIopposite\fR corners. They can be Lower Left and Upper Right,
\&\fIor\fR Upper Left and Lower Right, in either order, so long as they are
diagonally opposite each other. 
The current position is changed to the \f(CW\*(C`[$x1,$y1]\*(C'\fR (first) pair.
.PP
\fICurved line constructs\fR
.IX Subsection "Curved line constructs"
.PP
\&\fBNote:\fR None of these will actually be \fIvisible\fR until you call \f(CW\*(C`stroke\*(C'\fR or 
\&\f(CW\*(C`fill\*(C'\fR. They are merely setting up the path to draw.
.ie n .IP "$content\->circle($xc,$yc, $radius)" 4
.el .IP "\f(CW$content\fR\->circle($xc,$yc, \f(CW$radius\fR)" 4
.IX Item "$content->circle($xc,$yc, $radius)"
This creates a circular path centered on \f(CW\*(C`[$xc,$yc]\*(C'\fR with the specified
radius. It does \fBnot\fR change the current position.
.ie n .IP "$content\->ellipse($xc,$yc, $rx,$ry)" 4
.el .IP "\f(CW$content\fR\->ellipse($xc,$yc, \f(CW$rx\fR,$ry)" 4
.IX Item "$content->ellipse($xc,$yc, $rx,$ry)"
This creates a closed elliptical path centered on \f(CW\*(C`[$xc,$yc]\*(C'\fR, with axis radii
(semidiameters) specified by \f(CW$rx\fR (x axis) and \f(CW$ry\fR (y axis), respectively.
It does not change the current position.
.ie n .IP "$content\->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)" 4
.el .IP "\f(CW$content\fR\->arc($xc,$yc, \f(CW$rx\fR,$ry, \f(CW$alpha\fR,$beta, \f(CW$move\fR, \f(CW$dir\fR)" 4
.IX Item "$content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)"
.PD 0
.ie n .IP "$content\->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)" 4
.el .IP "\f(CW$content\fR\->arc($xc,$yc, \f(CW$rx\fR,$ry, \f(CW$alpha\fR,$beta, \f(CW$move\fR)" 4
.IX Item "$content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)"
.PD
This extends the path along an arc of an ellipse centered at \f(CW\*(C`[$xc,$yc]\*(C'\fR.
The semidiameters of the elliptical curve are \f(CW$rx\fR (x axis) and \f(CW$ry\fR 
(y axis), respectively, and the arc sweeps from \f(CW$alpha\fR degrees to \f(CW$beta\fR
degrees. The current position is then set to the endpoint of the arc.
.Sp
Set \f(CW$move\fR to a \fItrue\fR value if this arc is the beginning of a new
path instead of the continuation of an existing path. Either way, the 
current position will be updated to the end of the arc.
Use \f(CW\*(C`$rx == $ry\*(C'\fR for a circular arc.
.Sp
The optional \f(CW$dir\fR arc sweep direction defaults to 0 (\fIfalse\fR), for a
counter\-clockwise/anti\-clockwise sweep. Set to 1 (\fItrue\fR) for a clockwise
sweep.
.ie n .IP "$content\->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)" 4
.el .IP "\f(CW$content\fR\->pie($xc,$yc, \f(CW$rx\fR,$ry, \f(CW$alpha\fR,$beta, \f(CW$dir\fR)" 4
.IX Item "$content->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)"
.PD 0
.ie n .IP "$content\->pie($xc,$yc, $rx,$ry, $alpha,$beta)" 4
.el .IP "\f(CW$content\fR\->pie($xc,$yc, \f(CW$rx\fR,$ry, \f(CW$alpha\fR,$beta)" 4
.IX Item "$content->pie($xc,$yc, $rx,$ry, $alpha,$beta)"
.PD
Creates a pie-shaped path from an ellipse centered on \f(CW\*(C`[$xc,$yc]\*(C'\fR.
The x\-axis and y\-axis semidiameters of the ellipse are \f(CW$rx\fR and \f(CW$ry\fR,
respectively, and the arc sweeps from \f(CW$alpha\fR degrees to \f(CW$beta\fR
degrees. 
It does not change the current position.
Depending on the sweep angles and direction, this can draw either the
pie \*(L"slice\*(R" or the remaining pie (with slice removed).
Use \f(CW\*(C`$rx == $ry\*(C'\fR for a circular pie.
Use a different \f(CW\*(C`[$xc,$yc]\*(C'\fR for the slice, to offset it from the remaining pie.
.Sp
The optional \f(CW$dir\fR arc sweep direction defaults to 0 (\fIfalse\fR), for a
counter\-clockwise/anti\-clockwise sweep. Set to 1 (\fItrue\fR) for a clockwise
sweep.
.Sp
This is a shortcut to draw a section of elliptical (or circular) arc and
connect it to the center of the ellipse or circle, to form a pie shape.
.ie n .IP "$content\->curve($cx1,$cy1, $cx2,$cy2, $x,$y)" 4
.el .IP "\f(CW$content\fR\->curve($cx1,$cy1, \f(CW$cx2\fR,$cy2, \f(CW$x\fR,$y)" 4
.IX Item "$content->curve($cx1,$cy1, $cx2,$cy2, $x,$y)"
This extends the path in a curve from the current point to \f(CW\*(C`[$x,$y]\*(C'\fR,
using the two specified \fIcontrol\fR points to create a cubic Bezier curve, and
updates the current position to be the new point (\f(CW\*(C`[$x,$y]\*(C'\fR).
.Sp
Within a \fBtext\fR object, the text's baseline follows the Bezier curve.
.Sp
Note that while multiple sets of three \f(CW\*(C`[x,y]\*(C'\fR pairs are permitted, these
are treated as \fIindependent\fR cubic Bezier curves. There is no attempt made to
smoothly blend one curve into the next!
.ie n .IP "$content\->qbspline($cx1,$cy1, $x,$y)" 4
.el .IP "\f(CW$content\fR\->qbspline($cx1,$cy1, \f(CW$x\fR,$y)" 4
.IX Item "$content->qbspline($cx1,$cy1, $x,$y)"
This extends the path in a curve from the current point to \f(CW\*(C`[$x,$y]\*(C'\fR,
using the two specified points to create a quadratic Bezier curve, and updates 
the current position to be the new point.
.Sp
Internally, these splines are one or more cubic Bezier curves (see \f(CW\*(C`curve\*(C'\fR) 
with the two control points synthesized from the two given points (a control 
point and the end point of a \fIquadratic\fR Bezier curve).
.Sp
Note that while multiple sets of two \f(CW\*(C`[x,y]\*(C'\fR pairs are permitted, these
are treated as \fIindependent\fR quadratic Bezier curves. There is no attempt 
made to smoothly blend one curve into the next!
.Sp
Further note that this \*(L"spline\*(R" does not match the common definition of
a spline being a \fIcontinuous\fR curve passing \fIthrough\fR \fBall\fR the given 
points! It is a piecewise non-continuous cubic Bezier curve. Use with care, and 
do not make assumptions about splines for you or your readers. You may wish
to use the \f(CW\*(C`bspline\*(C'\fR call to have a continuously smooth spline to pass through
all given points.
.Sp
Pairs of points (control point and end point) are consumed in a loop. If one 
point or coordinate is left over at the end, it is discarded (as usual practice
for excess data to a routine). There is no check for duplicate points or other 
degeneracies.
.ie n .IP "$content\->bspline($ptsRef, %opts)" 4
.el .IP "\f(CW$content\fR\->bspline($ptsRef, \f(CW%opts\fR)" 4
.IX Item "$content->bspline($ptsRef, %opts)"
.PD 0
.ie n .IP "$content\->bspline($ptsRef)" 4
.el .IP "\f(CW$content\fR\->bspline($ptsRef)" 4
.IX Item "$content->bspline($ptsRef)"
.PD
This extends the path in a curve from the current point to the end of a list
of coordinate pairs in the array referenced by \f(CW$ptsRef\fR. Smoothly continuous
cubic Bezier splines are used to create a curve that passes through \fIall\fR
the given points. Multiple control points are synthesized; they are not 
supplied in the call. The current position is updated to the last point.
.Sp
Internally, these splines are one cubic Bezier curve (see \f(CW\*(C`curve\*(C'\fR) per pair
of input points, with the two control points synthesized from the tangent 
through each point as set by the polyline that would connect each point to its
neighbors. The intent is that the resulting curve should follow reasonably 
closely a polyline that would connect the points, and should avoid any major 
excursions. See the discussions below for the handling of the control points
at the endpoints (current point and last input point). The point at the end
of the last line or curve drawn becomes the new current point.
.Sp
\&\f(CW%opts\fR
.RS 4
.IP "\-firstseg => '\fImode\fR'" 4
.IX Item "-firstseg => 'mode'"
where \fImode\fR is
.RS 4
.IP "curve" 4
.IX Item "curve"
This is the \fBdefault\fR behavior.
This forces the first segment (from the current point to the first given point)
to be drawn as a cubic Bezier curve. This means that the direction of the curve
coming off the current point is unconstrained (it will end up being a reflection
of the tangent at the first given point).
.IP "line1" 4
.IX Item "line1"
This forces the first segment (from the current point to the first given point)
to be drawn as a curve, with the tangent at the current point to be constrained 
as parallel to the polyline segment.
.IP "line2" 4
.IX Item "line2"
This forces the first segment (from the current point to the first given point)
to be drawn as a line segment. This also sets the tangent through the first
given point as a continuation of the line, as well as constraining the direction
of the line at the current point.
.IP "constraint1" 4
.IX Item "constraint1"
This forces the first segment (from the current point to the first given point)
to \fBnot\fR be drawn, but to be an invisible curve (like mode=line1) to leave
the tangent at the first given point unconstrained. A \fImove\fR will be made to 
the first given point, and the current point is otherwise ignored.
.IP "constraint2" 4
.IX Item "constraint2"
This forces the first segment (from the current point to the first given point)
to \fBnot\fR be drawn, but to be an invisible line (like mode=line2) to constrain
the tangent at the first given point. A \fImove\fR will be made to the first given
point, and the current point is otherwise ignored.
.RE
.RS 4
.RE
.IP "\-lastseg => '\fImode\fR'" 4
.IX Item "-lastseg => 'mode'"
where \fImode\fR is
.RS 4
.IP "curve" 4
.IX Item "curve"
This is the \fBdefault\fR behavior.
This forces the last segment (to the last given input point)
to be drawn as a cubic Bezier curve. This means that the direction of the curve
goin to the last point is unconstrained (it will end up being a reflection
of the tangent at the next-to-last given point).
.IP "line1" 4
.IX Item "line1"
This forces the last segment (to the last given input point) to be drawn as a 
curve with the the tangent through the last given point parallel to the 
polyline segment, thus constraining the direction of the line at the last 
point.
.IP "line2" 4
.IX Item "line2"
This forces the last segment (to the last given input point)
to be drawn as a line segment. This also sets the tangent through the 
next-to-last given point as a back continuation of the line, as well as 
constraining the direction of the line at the last point.
.IP "constraint1" 4
.IX Item "constraint1"
This forces the last segment (to the last given input point)
to \fBnot\fR be drawn, but to be an invisible curve (like mode=line1) to leave
the tangent at the next-to-last given point unconstrained. The last given 
input point is ignored, and next-to-last point becomes the new current point.
.IP "constraint2" 4
.IX Item "constraint2"
This forces the last segment (to the last given input point)
to \fBnot\fR be drawn, but to be an invisible line (like mode=line2) to constrain
the tangent at the next-to-last given point. The last given input point is
ignored, and next-to-last point becomes the new current point.
.RE
.RS 4
.RE
.IP "\-ratio => \fIn\fR" 4
.IX Item "-ratio => n"
\&\fIn\fR is the ratio of the length from a point to a control point to the length
of the polyline segment on that side of the given point. It must be greater
than 0.1, and the default is 0.3333 (1/3).
.IP "\-colinear => '\fImode\fR'" 4
.IX Item "-colinear => 'mode'"
This describes how to handle the middle segment when there are four or more 
colinear points in the input set. A \fImode\fR of 'line' specifies that a line 
segment will be drawn between each of the interior colinear points. A \fImode\fR 
of 'curve' (this is the default) will draw a Bezier curve between each of those 
points.
.Sp
\&\f(CW\*(C`\-colinear\*(C'\fR applies only to interior runs of colinear points, between curves. 
It does not apply to runs at the beginning or end of the point list, which are
drawn as line segments or linear constraints regardless of \fI\-firstseg\fR and 
\&\fI\-lastseg\fR settings.
.IP "\-debug => \fIN\fR" 4
.IX Item "-debug => N"
If \fIN\fR is 0 (the default), only the spline is returned. If it is greater than
0, a number of additional items will be drawn: (N>0) the points, (N>1) a green 
solid polyline connecting them, (N>2) blue original tangent lines at each 
interior point, and (N>3) red dashed lines and hollow points representing the 
Bezier control points.
.RE
.RS 4
.RE
.PP
\fISpecial cases\fR
.IX Subsection "Special cases"
.PP
Adjacent points which are duplicates are consolidated. 
An extra coordinate at the end of the input point list (not a full 
\&\f(CW\*(C`[x,y]\*(C'\fR pair) will, as usual, be ignored.
.IP "0 given points (after duplicate consolidation)" 4
.IX Item "0 given points (after duplicate consolidation)"
This leaves only the current point (unchanged), so it is a no-op.
.IP "1 given point (after duplicate consolidation)" 4
.IX Item "1 given point (after duplicate consolidation)"
This leaves the current point and one point, so it is rendered as a line,
regardless of \f(CW%opt\fR flags.
.IP "2 given points (after duplicate consolidation)" 4
.IX Item "2 given points (after duplicate consolidation)"
This leaves the current point, an intermediate point, and the end point. If
the three points are colinear, two line segments will be drawn. Otherwise, both
segments are curves (through the tangent at the intermediate point). If either
end segment mode is requested to be a line or constraint, it is treated as a 
\&\fBline1\fR mode request instead.
.IP "\fIN\fR colinear points at beginning or end" 4
.IX Item "N colinear points at beginning or end"
\&\fIN\fR colinear points at beginning or end of the point set causes \fIN\-1\fR line 
segments (\f(CW\*(C`line2\*(C'\fR or \f(CW\*(C`constraint2\*(C'\fR, regardless of the settings of 
\&\f(CW\*(C`\-firstseg\*(C'\fR, \f(CW\*(C`\-lastseg\*(C'\fR, and \f(CW\*(C`\-colinear\*(C'\fR.
.ie n .IP "$content\->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)" 4
.el .IP "\f(CW$content\fR\->bogen($x1,$y1, \f(CW$x2\fR,$y2, \f(CW$radius\fR, \f(CW$move\fR, \f(CW$larger\fR, \f(CW$reverse\fR)" 4
.IX Item "$content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)"
.PD 0
.ie n .IP "$content\->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)" 4
.el .IP "\f(CW$content\fR\->bogen($x1,$y1, \f(CW$x2\fR,$y2, \f(CW$radius\fR, \f(CW$move\fR, \f(CW$larger\fR)" 4
.IX Item "$content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)"
.ie n .IP "$content\->bogen($x1,$y1, $x2,$y2, $radius, $move)" 4
.el .IP "\f(CW$content\fR\->bogen($x1,$y1, \f(CW$x2\fR,$y2, \f(CW$radius\fR, \f(CW$move\fR)" 4
.IX Item "$content->bogen($x1,$y1, $x2,$y2, $radius, $move)"
.ie n .IP "$content\->bogen($x1,$y1, $x2,$y2, $radius)" 4
.el .IP "\f(CW$content\fR\->bogen($x1,$y1, \f(CW$x2\fR,$y2, \f(CW$radius\fR)" 4
.IX Item "$content->bogen($x1,$y1, $x2,$y2, $radius)"
.PD
(German for \fIbow\fR, as in a segment (arc) of a circle. This is a segment
of a circle defined by the intersection of two circles of a given radius, 
with the two intersection points as inputs. There are four possible resulting
arcs, which can be selected with \f(CW$larger\fR and \f(CW$reverse\fR.)
.Sp
This extends the path along an arc of a circle of the specified radius
between \f(CW\*(C`[$x1,$y1]\*(C'\fR to \f(CW\*(C`[$x2,$y2]\*(C'\fR. The current position is then set
to the endpoint of the arc (\f(CW\*(C`[$x2,$y2]\*(C'\fR).
.Sp
Set \f(CW$move\fR to a \fItrue\fR value if this arc is the beginning of a new
path instead of the continuation of an existing path. Note that the default 
(\f(CW$move\fR = \fIfalse\fR) is
\&\fInot\fR a straight line to \fIP1\fR and then the arc, but a blending into the curve
from the current point. It will often \fInot\fR pass through \fIP1\fR!
.Sp
Set \f(CW$larger\fR to a \fItrue\fR value to draw the larger (\*(L"outer\*(R") arc between the 
two points, instead of the smaller one. Both arcs are
drawn \fIclockwise\fR from \fIP1\fR to \fIP2\fR. The default value of \fIfalse\fR draws
the smaller arc.
.Sp
Set \f(CW$reverse\fR to a \fItrue\fR value to draw the mirror image of the
specified arc (flip it over, so that its center point is on the other
side of the line connecting the two points). Both arcs are drawn
\&\fIcounter-clockwise\fR from \fIP1\fR to \fIP2\fR. The default (\fIfalse\fR) draws 
clockwise arcs.
.Sp
The \f(CW$radius\fR value cannot be smaller than \fBhalf\fR the distance from 
\&\f(CW\*(C`[$x1,$y1]\*(C'\fR to \f(CW\*(C`[$x2,$y2]\*(C'\fR. If it is too small, the radius will be set to
half the distance between the points (resulting in an arc that is a
semicircle). This is a silent error.
.SS "Path Painting (Drawing)"
.IX Subsection "Path Painting (Drawing)"
.ie n .IP "$content\->\fBstroke()\fR" 4
.el .IP "\f(CW$content\fR\->\fBstroke()\fR" 4
.IX Item "$content->stroke()"
Strokes the current path.
.ie n .IP "$content\->fill($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->fill($use_even_odd_fill)" 4
.IX Item "$content->fill($use_even_odd_fill)"
Fill the current path's enclosed \fIarea\fR. 
It does \fInot\fR stroke the enclosing path around the area.
.Sp
If the path intersects with itself, the nonzero winding rule will be
used to determine which part of the path is filled in. This basically
fills in \fIeverything\fR inside the path. If you would prefer to use
the even-odd rule, pass a \fItrue\fR argument. This basically will fill
alternating closed sub-areas.
.Sp
See the \s-1PDF\s0 Specification, section 8.5.3.3, for more details on
filling.
.ie n .IP "$content\->fillstroke($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->fillstroke($use_even_odd_fill)" 4
.IX Item "$content->fillstroke($use_even_odd_fill)"
Fill the enclosed area and then stroke the current path.
.ie n .IP "$content\->clip($use_even_odd_fill)" 4
.el .IP "\f(CW$content\fR\->clip($use_even_odd_fill)" 4
.IX Item "$content->clip($use_even_odd_fill)"
.PD 0
.ie n .IP "$content\->\fBclip()\fR" 4
.el .IP "\f(CW$content\fR\->\fBclip()\fR" 4
.IX Item "$content->clip()"
.PD
Modifies the current clipping path by intersecting it with the current
path. Initially (a fresh page), the clipping path is the entire media. Each
definition of a path, and a \f(CW\*(C`clip()\*(C'\fR call, intersects the new path with the
existing clip path, so the resulting clip path is no larger than the new path, 
and may even be empty if the intersection is null.
.Sp
If any \f(CW$use_even_odd_fill\fR parameter is given, use even-odd fill (\fBW*\fR) 
instead of winding-rule fill (\fBW\fR). It is common usage to make the 
\&\f(CW\*(C`endpath()\*(C'\fR call (\fBn\fR) after the \f(CW\*(C`clip()\*(C'\fR call, to clear the path (unless 
you want to reuse that path, such as to fill and/or stroke it to show the clip 
path). If you want to clip text glyphs, it gets rather complicated, as a clip
port cannot be created within a text object (that will have an effect on text). 
See the object discussion in \*(L"Rendering Order\*(R" in PDF::Builder::Docs.
.Sp
.Vb 10
\& my $grfxC1 = $page\->gfx();
\& my $textC  = $page\->text();
\& my $grfxC2 = $page\->gfx();
\&  ...
\& $grfxC1\->save();
\& $grfxC1\->endpath();
\& $grfxC1\->rect(...);
\& $grfxC1\->clip();
\& $grfxC1\->endpath();
\&  ...
\& $textC\->  output text to be clipped
\&  ...
\& $grfxC2\->restore();
.Ve
.SS "Colors"
.IX Subsection "Colors"
.ie n .IP "$content\->fillcolor($color)" 4
.el .IP "\f(CW$content\fR\->fillcolor($color)" 4
.IX Item "$content->fillcolor($color)"
.PD 0
.ie n .IP "$content\->strokecolor($color)" 4
.el .IP "\f(CW$content\fR\->strokecolor($color)" 4
.IX Item "$content->strokecolor($color)"
.PD
Sets the fill (enclosed area) or stroke (path) color. The interior of text
characters are \fIfilled\fR, and (if ordered by \f(CW\*(C`render\*(C'\fR) the outline is
\&\fIstroked\fR.
.Sp
.Vb 5
\&    # Use a named color
\&    # \-> RGB color model
\&    # there are many hundreds of named colors defined in 
\&    # PDF::Builder::Resource::Colors
\&    $content\->fillcolor(\*(Aqblue\*(Aq);
\&
\&    # Use an RGB color (# followed by 3, 6, 9, or 12 hex digits)
\&    # \-> RGB color model
\&    # This maps to 0\-1.0 values for red, green, and blue
\&    $content\->fillcolor(\*(Aq#FF0000\*(Aq);   # red
\&
\&    # Use a CMYK color (% followed by 4, 8, 12, or 16 hex digits)
\&    # \-> CMYK color model
\&    # This maps to 0\-1.0 values for cyan, magenta, yellow, and black
\&    $content\->fillcolor(\*(Aq%FF000000\*(Aq);   # cyan
\&
\&    # Use an HSV color (! followed by 3, 6, 9, or 12 hex digits)
\&    # \-> RGB color model
\&    # This maps to 0\-360 degrees for the hue, and 0\-1.0 values for 
\&    # saturation and value
\&    $content\->fillcolor(\*(Aq!FF0000\*(Aq);
\&
\&    # Use an HSL color (& followed by 3, 6, 9, or 12 hex digits)
\&    # \-> L*a*b color model
\&    # This maps to 0\-360 degrees for the hue, and 0\-1.0 values for 
\&    # saturation and lightness. Note that 360 degrees = 0 degrees (wraps)
\&    $content\->fillcolor(\*(Aq&FF0000\*(Aq);
\&
\&    # Use an L*a*b color ($ followed by 3, 6, 9, or 12 hex digits)
\&    # \-> L*a*b color model
\&    # This maps to 0\-100 for L, \-100 to 100 for a and b
\&    $content\->fillcolor(\*(Aq$FF0000\*(Aq);
.Ve
.Sp
In all cases, if too few digits are given, the given digits
are silently right-padded with 0's (zeros). If an incorrect number 
of digits are given, the next lowest number of expected
digits are used, and the remaining digits are silently ignored.
.Sp
.Vb 3
\&    # A single number between 0.0 (black) and 1.0 (white) is an alternate way
\&    # of specifying a gray scale.
\&    $content\->fillcolor(0.5);
\&
\&    # Three array elements between 0.0 and 1.0 is an alternate way of specifying
\&    # an RGB color.
\&    $content\->fillcolor(0.3, 0.59, 0.11);
\&
\&    # Four array elements between 0.0 and 1.0 is an alternate way of specifying
\&    # a CMYK color.
\&    $content\->fillcolor(0.1, 0.9, 0.3, 1.0);
.Ve
.Sp
In all cases, if a number is less than 0, it is silently turned into a 0. If
a number is greater than 1, it is silently turned into a 1. This \*(L"clamps\*(R" all
values to the range 0.0\-1.0.
.Sp
.Vb 1
\&    # A single reference is treated as a pattern or shading space.
\&
\&    # Two or more entries with the first element a Perl reference, is treated 
\&    # as either an indexed colorspace reference plus color\-index(es), or 
\&    # as a custom colorspace reference plus parameter(s).
.Ve
.Sp
If no value was passed in, the current fill color (or stroke color) \fIarray\fR 
is \fBreturned\fR, otherwise \f(CW$self\fR is \fBreturned\fR.
.ie n .IP "$content\->shade($shade, @coord)" 4
.el .IP "\f(CW$content\fR\->shade($shade, \f(CW@coord\fR)" 4
.IX Item "$content->shade($shade, @coord)"
Sets the shading matrix.
.RS 4
.ie n .IP "$shade" 4
.el .IP "\f(CW$shade\fR" 4
.IX Item "$shade"
A hash reference that includes a \f(CW\*(C`name()\*(C'\fR method for the shade name.
.ie n .IP "@coord" 4
.el .IP "\f(CW@coord\fR" 4
.IX Item "@coord"
An array of 4 items: X\-translation, Y\-translation, 
X\-scaled and translated, Y\-scaled and translated.
.RE
.RS 4
.RE
.SS "External Objects"
.IX Subsection "External Objects"
.ie n .IP "$content\->image($image_object, $x,$y, $width,$height)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR,$y, \f(CW$width\fR,$height)" 4
.IX Item "$content->image($image_object, $x,$y, $width,$height)"
.PD 0
.ie n .IP "$content\->image($image_object, $x,$y, $scale)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR,$y, \f(CW$scale\fR)" 4
.IX Item "$content->image($image_object, $x,$y, $scale)"
.ie n .IP "$content\->image($image_object, $x,$y)" 4
.el .IP "\f(CW$content\fR\->image($image_object, \f(CW$x\fR,$y)" 4
.IX Item "$content->image($image_object, $x,$y)"
.ie n .IP "$content\->image($image_object)" 4
.el .IP "\f(CW$content\fR\->image($image_object)" 4
.IX Item "$content->image($image_object)"
.PD
.Vb 3
\&    # Example
\&    my $image_object = $pdf\->image_jpeg($my_image_file);
\&    $content\->image($image_object, 100, 200);
.Ve
.Sp
Places an image on the page in the specified location (specifies the lower 
left corner of the image). The default location is \f(CW\*(C`[0,0]\*(C'\fR.
.Sp
If coordinate transformations have been made (see \fICoordinate
Transformations\fR above), the position and scale will be relative to the
updated coordinates. Otherwise, \f(CW\*(C`[0,0]\*(C'\fR will represent the bottom left
corner of the page, and \f(CW$width\fR and \f(CW$height\fR will be measured at
72dpi.
.Sp
For example, if you have a 600x600 image that you would like to be
shown at 600dpi (i.e., one inch square), set the width and height to 72.
(72 Big Points is one inch)
.ie n .IP "$content\->formimage($form_object, $x,$y, $scaleX, $scaleY)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object, \f(CW$x\fR,$y, \f(CW$scaleX\fR, \f(CW$scaleY\fR)" 4
.IX Item "$content->formimage($form_object, $x,$y, $scaleX, $scaleY)"
.PD 0
.ie n .IP "$content\->formimage($form_object, $x,$y, $scale)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object, \f(CW$x\fR,$y, \f(CW$scale\fR)" 4
.IX Item "$content->formimage($form_object, $x,$y, $scale)"
.ie n .IP "$content\->formimage($form_object, $x,$y)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object, \f(CW$x\fR,$y)" 4
.IX Item "$content->formimage($form_object, $x,$y)"
.ie n .IP "$content\->formimage($form_object)" 4
.el .IP "\f(CW$content\fR\->formimage($form_object)" 4
.IX Item "$content->formimage($form_object)"
.PD
Places an XObject on the page in the specified location (giving the lower
left corner of the image) and scale (applied to the image's native height
and width). If no scale is given, use 1 for both X and Y. If one scale is 
given, use for both X and Y.  If two scales given, they are for (separately) 
X and Y. In general, you should not greatly distort an image by using greatly 
different scaling factors in X and Y, although it is now possible for when 
that effect is desirable. The \f(CW\*(C`$x,$y\*(C'\fR default is \f(CW\*(C`[0,0]\*(C'\fR.
.Sp
\&\fBNote\fR that while this method is named form \fIimage\fR, it is also used for the 
pseudoimages created by the barcode routines. Images are naturally dimensionless
(1 point square) and need at some point to be scaled up to the desired point 
size. Barcodes are naturally sized in points, and should be scaled at 
approximately \fI1\fR. Therefore, it would greatly overscale barcodes to multiply 
by image width and height \fIwithin\fR \f(CW\*(C`formimage\*(C'\fR, and require scaling of 
1/width and 1/height in the call. So, we leave scaling alone within 
\&\f(CW\*(C`formimage\*(C'\fR and have the user manually scale \fIimages\fR by the image width and 
height (in pixels) in the call to \f(CW\*(C`formimage\*(C'\fR.
.SS "Text"
.IX Subsection "Text"
\fIText State Parameters\fR
.IX Subsection "Text State Parameters"
.PP
All of the following parameters that take a size are applied before
any scaling takes place, so you don't need to adjust values to
counteract scaling.
.ie n .IP "$spacing = $content\->charspace($spacing)" 4
.el .IP "\f(CW$spacing\fR = \f(CW$content\fR\->charspace($spacing)" 4
.IX Item "$spacing = $content->charspace($spacing)"
Sets additional spacing between \fBcharacters\fR in a line. This is in \fIpoints\fR,
and is initially zero.
It may be positive to give an \fIexpanded\fR effect to words, or
it may be negative to give a \fIcondensed\fR effect to words.
If \f(CW$spacing\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$spacing\fR is not given, the current setting is \fBreturned\fR.
.Sp
\&\fB\s-1CAUTION:\s0\fR be careful about using \f(CW\*(C`charspace\*(C'\fR if you are using a connected
font. This might include Arabic, Devanagari, Latin cursive handwriting, and so 
on. You don't want to leave gaps between characters, or cause overlaps. For 
such fonts and typefaces, set the \f(CW\*(C`charspace\*(C'\fR spacing to 0.
.ie n .IP "$spacing = $content\->wordspace($spacing)" 4
.el .IP "\f(CW$spacing\fR = \f(CW$content\fR\->wordspace($spacing)" 4
.IX Item "$spacing = $content->wordspace($spacing)"
Sets additional spacing between \fBwords\fR in a line. This is in \fIpoints\fR and
is initially zero 
(i.e., just the width of the space, without anything extra). It may be negative
to close up sentences a bit. 
If \f(CW$spacing\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$spacing\fR is not given, the current setting is \fBreturned\fR.
.Sp
Note that it is a limitation of the \s-1PDF\s0 specification (as of version 1.7, 
section 9.3.3) that only spacing with an \s-1ASCII\s0 space (x20) is adjusted. Neither
required blanks (xA0) nor any multiple-byte spaces (including thin and wide
spaces) are currently adjusted.
.ie n .IP "$scale = $content\->hscale($scale)" 4
.el .IP "\f(CW$scale\fR = \f(CW$content\fR\->hscale($scale)" 4
.IX Item "$scale = $content->hscale($scale)"
Sets the percentage of horizontal text scaling (relative sizing, \fInot\fR 
spacing). This is initally 100 (percent, i.e., no scaling). A scale of greater 
than 100 will stretch the text, while less than 100 will compress it.
If \f(CW$scale\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$scale\fR is not given, the current setting is \fBreturned\fR.
.Sp
Note that scaling affects all of the character widths, interletter spacing, and
interword spacing. It is inadvisable to stretch or compress text by a large 
amount, as it will quickly make the text unreadable. If your objective is to 
justify text, you will usually be better off using \f(CW\*(C`charspace\*(C'\fR and \f(CW\*(C`wordspace\*(C'\fR
to expand (or slightly condense) a line to fill a desired width. Also see 
the \f(CW\*(C`text_justify()\*(C'\fR calls for this purpose.
.ie n .IP "$leading = $content\->lead($leading)" 4
.el .IP "\f(CW$leading\fR = \f(CW$content\fR\->lead($leading)" 4
.IX Item "$leading = $content->lead($leading)"
Sets the text leading, which is the distance between baselines. This
is initially \fBzero\fR (i.e., the lines will be printed on top of each
other). The unit of leading is points.
If \f(CW$leading\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$leading\fR is not given, the current setting is \fBreturned\fR.
.ie n .IP "$mode = $content\->render($mode)" 4
.el .IP "\f(CW$mode\fR = \f(CW$content\fR\->render($mode)" 4
.IX Item "$mode = $content->render($mode)"
Sets the text rendering mode.
.RS 4
.IP "0 = Fill text" 4
.IX Item "0 = Fill text"
.PD 0
.IP "1 = Stroke text (outline)" 4
.IX Item "1 = Stroke text (outline)"
.IP "2 = Fill, then stroke text" 4
.IX Item "2 = Fill, then stroke text"
.IP "3 = Neither fill nor stroke text (invisible)" 4
.IX Item "3 = Neither fill nor stroke text (invisible)"
.IP "4 = Fill text and add to path for clipping" 4
.IX Item "4 = Fill text and add to path for clipping"
.IP "5 = Stroke text and add to path for clipping" 4
.IX Item "5 = Stroke text and add to path for clipping"
.IP "6 = Fill, then stroke text and add to path for clipping" 4
.IX Item "6 = Fill, then stroke text and add to path for clipping"
.IP "7 = Add text to path for clipping" 4
.IX Item "7 = Add text to path for clipping"
.RE
.RS 4
.PD
.Sp
If \f(CW$mode\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$mode\fR is not given, the current setting is \fBreturned\fR.
.RE
.ie n .IP "$dist = $content\->rise($dist)" 4
.el .IP "\f(CW$dist\fR = \f(CW$content\fR\->rise($dist)" 4
.IX Item "$dist = $content->rise($dist)"
Adjusts the baseline up or down from its current location.  This is
initially zero. A \f(CW$dist\fR greater than 0 moves the baseline \fBup\fR the page
(y increases).
.Sp
Use this for creating superscripts or subscripts (usually along with an
adjustment to the font size).
If \f(CW$dist\fR is given, the current setting is replaced by that value and
\&\f(CW$self\fR is \fBreturned\fR (to permit chaining).
If \f(CW$dist\fR is not given, the current setting is \fBreturned\fR.
.ie n .IP "%state = $content\->textstate(charspace => $value, wordspace => $value, ...)" 4
.el .IP "\f(CW%state\fR = \f(CW$content\fR\->textstate(charspace => \f(CW$value\fR, wordspace => \f(CW$value\fR, ...)" 4
.IX Item "%state = $content->textstate(charspace => $value, wordspace => $value, ...)"
This is a shortcut for setting multiple text state parameters at once.
If any parameters are set, an \fIempty\fR hash is \fBreturned\fR.
This can also be used without arguments to retrieve the current text
state settings (a hash of the state is \fBreturned\fR).
.Sp
\&\fBNote:\fR This does not work with the \f(CW\*(C`save\*(C'\fR and \f(CW\*(C`restore\*(C'\fR commands.
.ie n .IP "$content\->font($font_object, $size)" 4
.el .IP "\f(CW$content\fR\->font($font_object, \f(CW$size\fR)" 4
.IX Item "$content->font($font_object, $size)"
Sets the font and font size.
.Sp
.Vb 4
\&    # Example (12 point Helvetica)
\&    my $pdf = PDF::Builder\->new();
\&    my $fontname = $pdf\->corefont(\*(AqHelvetica\*(Aq);
\&    $content\->font($fontname, 12);
.Ve
.PP
\fIPositioning Text\fR
.IX Subsection "Positioning Text"
.ie n .IP "$content\->distance($dx,$dy)" 4
.el .IP "\f(CW$content\fR\->distance($dx,$dy)" 4
.IX Item "$content->distance($dx,$dy)"
This moves to the start of the previously-written line, plus an offset by the 
given amounts, which are both required. \f(CW\*(C`[0,0]\*(C'\fR would overwrite the previous 
line, while \f(CW\*(C`[0,36]\*(C'\fR would place the new line 36pt \fIabove\fR the old line 
(higher y). The \f(CW$dx\fR moves to the right, if positive.
.Sp
\&\f(CW\*(C`distance\*(C'\fR is analogous to graphic's \f(CW\*(C`move\*(C'\fR, except that it is relative to
the beginning of the previous text write, not to the coordinate origin.
\&\fBNote\fR that subsequent text writes will be relative to this new starting
(left) point and Y position! E.g., if you give a non-zero \f(CW$dx\fR, subsequent
lines will be indented by that amount.
.ie n .IP "$content\->\fBcr()\fR" 4
.el .IP "\f(CW$content\fR\->\fBcr()\fR" 4
.IX Item "$content->cr()"
.PD 0
.ie n .IP "$content\->cr($vertical_offset)" 4
.el .IP "\f(CW$content\fR\->cr($vertical_offset)" 4
.IX Item "$content->cr($vertical_offset)"
.ie n .IP "$content\->\fBcr\fR\|(0)" 4
.el .IP "\f(CW$content\fR\->\fBcr\fR\|(0)" 4
.IX Item "$content->cr"
.PD
If passed without an argument, moves (down) to the start of the \fInext\fR line 
(distance set by \f(CW\*(C`lead\*(C'\fR). This is similar to \f(CW\*(C`nl()\*(C'\fR.
.Sp
If passed \fIwith\fR an argument, the \f(CW\*(C`lead\*(C'\fR distance is ignored and the next 
line starts that far \fIup\fR the page (positive value) or \fIdown\fR the page 
(negative value) from the current line. \*(L"Y\*(R" increases upward, so a negative
value would normally be used to get to the next line down.
.Sp
An argument of \fI0\fR would
simply return to the start of the present line, overprinting it with new text.
That is, it acts as a simple carriage return, without a linefeed.
.ie n .IP "$content\->\fBnl()\fR" 4
.el .IP "\f(CW$content\fR\->\fBnl()\fR" 4
.IX Item "$content->nl()"
.PD 0
.ie n .IP "$content\->nl($indent)" 4
.el .IP "\f(CW$content\fR\->nl($indent)" 4
.IX Item "$content->nl($indent)"
.ie n .IP "$content\->\fBnl\fR\|(0)" 4
.el .IP "\f(CW$content\fR\->\fBnl\fR\|(0)" 4
.IX Item "$content->nl"
.PD
Moves to the start of the next line (see \f(CW\*(C`lead\*(C'\fR). If \f(CW$indent\fR is not given,
or is 0, there is no indentation. Otherwise, indent by that amount (\fIout\fRdent
if a negative value). The unit of measure is hundredths of a \*(L"unit of text
space\*(R", or roughly 88 per em.
.ie n .IP "($tx,$ty) = $content\->\fBtextpos()\fR" 4
.el .IP "($tx,$ty) = \f(CW$content\fR\->\fBtextpos()\fR" 4
.IX Item "($tx,$ty) = $content->textpos()"
\&\fBReturns\fR the current text position on the page (where next write will happen) 
as an array.
.Sp
\&\fBNote:\fR This does not affect the \s-1PDF\s0 in any way. It only tells you where the
the next write will occur.
.ie n .IP "$width = $content\->advancewidth($string, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->advancewidth($string, \f(CW%opts\fR)" 4
.IX Item "$width = $content->advancewidth($string, %opts)"
.PD 0
.ie n .IP "$width = $content\->advancewidth($string)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->advancewidth($string)" 4
.IX Item "$width = $content->advancewidth($string)"
.PD
Options \f(CW%opts:\fR
.RS 4
.ie n .IP "font => $f3_TimesRoman" 4
.el .IP "font => \f(CW$f3_TimesRoman\fR" 4
.IX Item "font => $f3_TimesRoman"
Change the font used, overriding \f(CW$self\fR\->{' font'}. The font must have been
previously created (i.e., is not the name). Example: use Times-Roman.
.IP "fontsize => 12" 4
.IX Item "fontsize => 12"
Change the font size, overriding \f(CW$self\fR\->{' fontsize'}. Example: 12 pt font.
.IP "wordspace => 0.8" 4
.IX Item "wordspace => 0.8"
Change the additional word spacing, overriding \f(CW$self\fR\->\fBwordspace()\fR. 
Example: add 0.8 pt between words.
.IP "charspace => \-2.1" 4
.IX Item "charspace => -2.1"
Change the additional character spacing, overriding \f(CW$self\fR\->\fBcharspace()\fR. 
Example: subtract 2.1 pt between letters, to condense the text.
.IP "hscale => 125" 4
.IX Item "hscale => 125"
Change the horizontal scaling factor, overriding \f(CW$self\fR\->\fBhscale()\fR. 
Example: stretch text to 125% of its natural width.
.RE
.RS 4
.Sp
\&\fBReturns\fR the \fBwidth of the \f(CB$string\fB\fR based on all currently set text-state
attributes. These can optionally be overridden with \f(CW%opts\fR. \fINote that these
values temporarily \f(BIreplace\fI the existing values, \f(BInot\fI scaling them up or
down.\fR For example, if the existing charspace is 2, and you give in options
a value of 3, the value used is 3, not 5.
.Sp
\&\fBNote:\fR This does not affect the \s-1PDF\s0 in any way. It only tells you how much
horizontal space a text string will take up.
.RE
.PP
\fIRendering Text\fR
.IX Subsection "Rendering Text"
.PP
Single Lines
.IX Subsection "Single Lines"
.ie n .IP "$width = $content\->text($text, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text($text, \f(CW%opts\fR)" 4
.IX Item "$width = $content->text($text, %opts)"
.PD 0
.ie n .IP "$width = $content\->text($text)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->text($text)" 4
.IX Item "$width = $content->text($text)"
.PD
Adds text to the page (left justified). 
The width used (in points) is \fBreturned\fR.
.Sp
Options:
.RS 4
.ie n .IP "\-indent => $distance" 4
.el .IP "\-indent => \f(CW$distance\fR" 4
.IX Item "-indent => $distance"
Indents the text by the number of points (A value less than 0 gives an
\&\fIoutdent\fR).
.IP "\-underline => 'none'" 4
.IX Item "-underline => 'none'"
.PD 0
.IP "\-underline => 'auto'" 4
.IX Item "-underline => 'auto'"
.ie n .IP "\-underline => $distance" 4
.el .IP "\-underline => \f(CW$distance\fR" 4
.IX Item "-underline => $distance"
.ie n .IP "\-underline => [$distance, $thickness, ...]" 4
.el .IP "\-underline => [$distance, \f(CW$thickness\fR, ...]" 4
.IX Item "-underline => [$distance, $thickness, ...]"
.PD
Underlines the text. \f(CW$distance\fR is the number of units beneath the
baseline, and \f(CW$thickness\fR is the width of the line.
Multiple underlines can be made by passing several distances and
thicknesses. 
A value of 'none' means no underlining (is the default).
.Sp
Example:
.Sp
.Vb 5
\&    # 3 underlines:
\&    #   distance 4, thickness 1, color red
\&    #   distance 7, thickness 1.5, color yellow
\&    #   distance 11, thickness 2, color (strokecolor default)
\&    \-underline=>[4,[1,\*(Aqred\*(Aq],7,[1.5,\*(Aqyellow\*(Aq],11,2],
.Ve
.IP "\-strikethru => 'none'" 4
.IX Item "-strikethru => 'none'"
.PD 0
.IP "\-strikethru => 'auto'" 4
.IX Item "-strikethru => 'auto'"
.ie n .IP "\-strikethru => $distance" 4
.el .IP "\-strikethru => \f(CW$distance\fR" 4
.IX Item "-strikethru => $distance"
.ie n .IP "\-strikethru => [$distance, $thickness, ...]" 4
.el .IP "\-strikethru => [$distance, \f(CW$thickness\fR, ...]" 4
.IX Item "-strikethru => [$distance, $thickness, ...]"
.PD
Strikes through the text (like \s-1HTML\s0 \fIs\fR tag). A value of 'auto' places the
line about 30% of the font size above the baseline, or a specified \f(CW$distance\fR
(above the baseline) and \f(CW$thickness\fR (in points).
Multiple strikethroughs can be made by passing several distances and
thicknesses.
A value of 'none' means no strikethrough. It is the default.
.Sp
Example:
.Sp
.Vb 4
\&    # 2 strikethroughs:
\&    #   distance 4, thickness 1, color red
\&    #   distance 7, thickness 1.5, color yellow
\&    \-strikethru=>[4,[1,\*(Aqred\*(Aq],7,[1.5,\*(Aqyellow\*(Aq]],
.Ve
.RE
.RS 4
.RE
.ie n .IP "$width = $content\->textHS($HSarray, $settings, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->textHS($HSarray, \f(CW$settings\fR, \f(CW%opts\fR)" 4
.IX Item "$width = $content->textHS($HSarray, $settings, %opts)"
.PD 0
.ie n .IP "$width = $content\->textHS($HSarray, $settings)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->textHS($HSarray, \f(CW$settings\fR)" 4
.IX Item "$width = $content->textHS($HSarray, $settings)"
.PD
Takes an array of hashes produced by HarfBuzz::Shaper and outputs them to the
\&\s-1PDF\s0 output file. HarfBuzz outputs glyph CIDs and positioning information. 
It may rearrange and swap characters (glyphs), and the result may bear no
resemblance to the original Unicode point list. You should see 
examples/HarfBuzz.pl, which shows a number of examples with Latin and non-Latin 
text, as well as vertical writing. 
examples/resources/HarfBuzz_example.pdf is available in case you want to see 
some examples and don't yet have HarfBuzz::Shaper installed.
.RS 4
.ie n .IP "$HSarray" 4
.el .IP "\f(CW$HSarray\fR" 4
.IX Item "$HSarray"
This is the reference to array of hashes produced by HarfBuzz::Shaper, normally 
unchanged after being created (but \fIcan\fR be modified). See 
\&\*(L"Using Shaper\*(R" in PDF::Builder::Docs for some things that can be done.
.ie n .IP "$settings" 4
.el .IP "\f(CW$settings\fR" 4
.IX Item "$settings"
This a reference to a hash of various pieces of information that \f(CW\*(C`textHS()\*(C'\fR 
needs in order to function. They include:
.RS 4
.IP "script => 'script_name'" 4
.IX Item "script => 'script_name'"
This is the standard 4 letter code (e.g., 'Latn') for the script (alphabet and
writing system) you're using. Currently, only Latn (Western writing systems)
do kerning, and 'Latn' is the default. HarfBuzz::Shaper will usually be able to 
figure out from the Unicode points used what the script is, and you might be 
able to use the \f(CW\*(C`set_script()\*(C'\fR call to override its guess. However, 
PDF::Builder and HarfBuzz::Shaper do not talk to each other about the script 
being used.
.IP "features => array_of_features" 4
.IX Item "features => array_of_features"
This item is \fBrequired\fR, but may be empty, e.g., 
\&\f(CW\*(C`$settings\->{\*(Aqfeatures\*(Aq} = ();\*(C'\fR.
It can include switches using the standard HarfBuzz naming, and a + or \-
switch, such as '\-liga' to turn \fBoff\fR ligatures. '\-liga' and '\-kern', to turn
off ligatures and kerning, are the only features supported currently. \fBNote\fR
that this is separate from any switches for features that you send to 
HarfBuzz::Shaper (with \f(CW\*(C`$hb\->add_features()\*(C'\fR, etc.) when you run it 
(before \f(CW\*(C`textHS()\*(C'\fR).
.IP "language => 'language_code'" 4
.IX Item "language => 'language_code'"
This item is optional and currently does not appear to have any substantial
effect with HarfBuzz::Shaper. It is the standard code for the
language to be used, such as 'en' or 'en_US'. You might need to define this for
HarfBuzz::Shaper, in case that system can't surmise the language rules to be 
used.
.IP "dir => 'flag'" 4
.IX Item "dir => 'flag'"
Tell \f(CW\*(C`textHS()\*(C'\fR whether this text is to be written in a Left-To-Right manner 
(\fBL\fR, the \fBdefault\fR), Right-To-Left (\fBR\fR), Top-To-Bottom (\fBT\fR), or 
Bottom-To-Top (\fBB\fR). From the script used (Unicode points), HarfBuzz::Shaper 
can usually figure out what direction to write text in. Also, HarfBuzz::Shaper 
does not share its information with PDF::Builder \*(-- you need to separately 
specify the direction, unless you want to accept the default \s-1LTR\s0 direction. You 
\&\fIcan\fR use HarfBuzz::Shaper's \f(CW\*(C`get_direction()\*(C'\fR call (in addition to 
\&\f(CW\*(C`get_language()\*(C'\fR and \f(CW\*(C`get_script()\*(C'\fR) to see what HarfBuzz thinks is the 
correct text direction. \f(CW\*(C`set_direction()\*(C'\fR may be used to override Shaper's
guess as to the direction.
.Sp
By the way, if the direction is \s-1RTL,\s0 HarfBuzz will reverse the text and return 
an array with the last character first (to be written \s-1LTR\s0). Likewise, for \s-1BTT,\s0 
HarfBuzz will reverse the text and return a string to be written from the top 
down. Languages which are normally written horizontally are usually set 
vertically with direction \s-1TTB.\s0 If setting text vertically, ligatures and 
kerning, as well as character connectivity for cursive scripts, are 
automatically turned off, so don't let the direction default to \s-1LTR\s0 or \s-1RTL\s0 in 
the Shaper call, and then try to fix it up in \f(CW\*(C`textHS()\*(C'\fR.
.IP "align => 'flag'" 4
.IX Item "align => 'flag'"
Given the current output location, align the
text at the \fBB\fReginning of the line (left for \s-1LTR,\s0 right for \s-1RTL\s0), \fBC\fRentered
at the location, or at the \fBE\fRnd of the line (right for \s-1LTR,\s0 left for \s-1RTL\s0).
The default is \fBB\fR. \fBC\fRentered is analogous to using \f(CW\*(C`text_center()\*(C'\fR, and
\&\fBE\fRnd is analogous to using \f(CW\*(C`text_right()\*(C'\fR. Similar alignments are done for
\&\s-1TTB\s0 and \s-1BTT.\s0
.IP "dump => flag" 4
.IX Item "dump => flag"
Set to 1, it prints out positioning and glyph \s-1CID\s0 information (to \s-1STDOUT\s0) for
each glyph in the chunk. The default is 0 (no information dump).
.IP "\-minKern => amount (default 1)" 4
.IX Item "-minKern => amount (default 1)"
If the amount of kerning (font character width \fIdiffers from\fR glyph ax value) 
is \fIlarger\fR than this many character grid units, use the unaltered ax for the
width (\f(CW\*(C`textHS()\*(C'\fR will output a kern amount in the \s-1TJ\s0 operation). Otherwise,
ignore kerning and use ax of the actual character width. The intent is to avoid
bloating the \s-1PDF\s0 code with unnecessary tiny kerning adjustments in the \s-1TJ\s0 
operation.
.RE
.RS 4
.RE
.ie n .IP "%opts" 4
.el .IP "\f(CW%opts\fR" 4
.IX Item "%opts"
This a hash of options.
.RS 4
.IP "\-underline => underlining_instructions" 4
.IX Item "-underline => underlining_instructions"
See \f(CW\*(C`text()\*(C'\fR for available instructions.
.IP "\-strikethru => strikethrough_instructions" 4
.IX Item "-strikethru => strikethrough_instructions"
See \f(CW\*(C`text()\*(C'\fR for available instructions.
.IP "\-strokecolor => line_color" 4
.IX Item "-strokecolor => line_color"
Color specification (e.g., 'green', '#FF3377') for underline or strikethrough,
if not given in an array with their instructions.
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
Text is sent \fIseparately\fR to HarfBuzz::Shaper in 'chunks' ('segments') of a 
single script (alphabet), a
single direction (\s-1LTR, RTL, TTB,\s0 or \s-1BTT\s0), a single font file, 
and a single font size. A 
chunk may consist of a large amount of text, but at present, \f(CW\*(C`textHS()\*(C'\fR can 
only output a single line. For long lines that need to be split into 
column-width lines, the best way may be to take the array of hashes returned by
HarfBuzz::Shaper and split it into smaller chunks at spaces and other 
whitespace. You may have to query the font to see what the glyph CIDs are for 
space and anything else used.
.Sp
It is expected that when \f(CW\*(C`textHS()\*(C'\fR is called, that the font and font size
have already been set in PDF::Builder code, as this information is needed to
interpret what HarfBuzz::Shaper is returning, and to write it to the \s-1PDF\s0 file.
Needless to say, the font should be opened from the same file as was given
to HarfBuzz::Shaper (\f(CW\*(C`ttfont()\*(C'\fR only, with .ttf or .otf files), and the font
size must be the same. The appropriate location on the page must also already
have been specified.
.Sp
\&\fB\s-1NOTE:\s0\fR as HarfBuzz::Shaper is still in its early days, it is possible that
there will be major changes in its \s-1API.\s0 We hope that all changes will be 
upwardly compatible, but do not control this package and cannot guarantee that
there will not be any incompatible changes that in turn require changes to
PDF::Builder (\f(CW\*(C`textHS()\*(C'\fR).
.RE
.ie n .IP "$width = $content\->advancewidthHS($HSarray, $settings, %opts)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->advancewidthHS($HSarray, \f(CW$settings\fR, \f(CW%opts\fR)" 4
.IX Item "$width = $content->advancewidthHS($HSarray, $settings, %opts)"
.PD 0
.ie n .IP "$width = $content\->advancewidthHS($HSarray, $settings)" 4
.el .IP "\f(CW$width\fR = \f(CW$content\fR\->advancewidthHS($HSarray, \f(CW$settings\fR)" 4
.IX Item "$width = $content->advancewidthHS($HSarray, $settings)"
.PD
Returns text chunk width (in points) for Shaper-defined glyph array.
This is the horizontal width for \s-1LTR\s0 and \s-1RTL\s0 direction, and the vertical
height for \s-1TTB\s0 and \s-1BTT\s0 direction.
\&\fBNote:\fR You must define the font and font size \fIbefore\fR calling 
\&\f(CW\*(C`advancewidthHS()\*(C'\fR.
.RS 4
.ie n .IP "$HSarray" 4
.el .IP "\f(CW$HSarray\fR" 4
.IX Item "$HSarray"
The array reference of glyphs created by the HarfBuzz::Shaper call. 
See \f(CW\*(C`textHS()\*(C'\fR for details.
.ie n .IP "$settings" 4
.el .IP "\f(CW$settings\fR" 4
.IX Item "$settings"
the hash reference of settings. See \f(CW\*(C`textHS()\*(C'\fR for details.
.RS 4
.IP "dir => 'L' etc." 4
.IX Item "dir => 'L' etc."
the direction of the text, to know which \*(L"advance\*(R" value to sum up.
.RE
.RS 4
.RE
.ie n .IP "%opts" 4
.el .IP "\f(CW%opts\fR" 4
.IX Item "%opts"
Options. Unlike \f(CW\*(C`advancewidth()\*(C'\fR, you
cannot override the font, font size, etc. used by HarfBuzz::Shaper to calculate
the glyph list.
.RS 4
.IP "\-doKern => flag (default 1)" 4
.IX Item "-doKern => flag (default 1)"
If 1, cancel minor kerns per \f(CW\*(C`\-minKern\*(C'\fR setting. This flag should be 0 (false)
if \fB\-kern\fR was passed to HarfBuzz::Shaper (do not kern text).
This is treated as 0 if an ax override setting is given.
.IP "\-minKern => amount (default 1)" 4
.IX Item "-minKern => amount (default 1)"
If the amount of kerning (font character width \fIdiffers from\fR glyph ax value) 
is \fIlarger\fR than this many character grid units, use the unaltered ax for the
width (\f(CW\*(C`textHS()\*(C'\fR will output a kern amount in the \s-1TJ\s0 operation). Otherwise,
ignore kerning and use ax of the actual character width. The intent is to avoid
bloating the \s-1PDF\s0 code with unnecessary tiny kerning adjustments in the \s-1TJ\s0 
operation.
.RE
.RS 4
.RE
.RE
.RS 4
.Sp
Returns total width in points.
.RE
.SS "Advanced Methods"
.IX Subsection "Advanced Methods"
.ie n .IP "$content\->\fBsave()\fR" 4
.el .IP "\f(CW$content\fR\->\fBsave()\fR" 4
.IX Item "$content->save()"
Saves the current \fIgraphics\fR state on a \s-1PDF\s0 stack. See \s-1PDF\s0 definition 8.4.2 
through 8.4.4 for details. This includes the line width, the line cap style, 
line join style, miter limit, line dash pattern, stroke color, fill color,
current transformation matrix, current clipping port, flatness, and dictname.
This method applies to both \fItext\fR and \fIgfx\fR objects.
.ie n .IP "$content\->\fBrestore()\fR" 4
.el .IP "\f(CW$content\fR\->\fBrestore()\fR" 4
.IX Item "$content->restore()"
Restores the most recently saved graphics state (see \f(CW\*(C`save\*(C'\fR),
removing it from the stack. You cannot \fIrestore\fR the graphics state (pop it off
the stack) unless you have done at least one \fIsave\fR (pushed it on the stack).
This method applies to both \fItext\fR and \fIgfx\fR objects.
.ie n .IP "$content\->add(@content)" 4
.el .IP "\f(CW$content\fR\->add(@content)" 4
.IX Item "$content->add(@content)"
Add raw content (arbitrary string(s)) to the \s-1PDF\s0 stream. 
You will generally want to use the other methods in this class instead,
unless this is in order to implement some \s-1PDF\s0 operation that PDF::Builder
does not natively support. An array of multiple strings may be given; 
they will be concatenated with spaces between them.
.Sp
Be careful when doing this, as you are dabbling in the black arts, 
directly setting \s-1PDF\s0 operations!
.Sp
One interesting use is to split up an overly long object stream that is giving 
your editor problems when exploring a \s-1PDF\s0 file. Add a newline \fBadd(\*(L"\en\*(R")\fR 
every few hundred bytes of output or so, to do this. Note that you must use 
double quotes (quotation marks), rather than single quotes (apostrophes).
.Sp
Use extreme care if inserting \fB\s-1BT\s0\fR and \fB\s-1ET\s0\fR markers into the \s-1PDF\s0 stream.
You may want to use \f(CW\*(C`textstart()\*(C'\fR and \f(CW\*(C`textend()\*(C'\fR calls instead, and even
then, there are many side effects either way. It is generally not useful 
to suspend text mode with ET/textend and BT/textstart, but it is possible, 
if you \fIreally\fR need to do it.
.Sp
Another, useful, case is when your input \s-1PDF\s0 is from the \fBChrome browser\fR 
printing a page to \s-1PDF\s0 with
headers and/or footers. In some versions, this leaves the \s-1PDF\s0 page with a
strange scaling (such as the page height in points divided by 3300) and the 
Y\-axis flipped so 0 is at the top. This causes problems when trying to add
additional text or graphics in a new text or graphics record, where text is 
flipped (mirrored) upsidedown and at the wrong end of the page. If this 
happens, you might be able to cure it by adding
.Sp
.Vb 8
\&    $scale = .23999999; # example, 792/3300, examine PDF or experiment!
\&     ...
\&    if ($scale != 1) {
\&        my @pageDim = $page\->mediabox();     # e.g., 0 0 612 792
\&        my $size_page = $pageDim[3]/$scale;  # 3300 = 792/.23999999
\&        my $invScale = 1.0/$scale;           # 4.16666684
\&        $text\->add("$invScale 0 0 \-$invScale 0 $size_page cm");
\&    }
.Ve
.Sp
as the first output to the \f(CW$text\fR stream. Unfortunately, it is difficult to
predict exactly what \f(CW$scale\fR should be, as it may be 3300 units per page, or
a fixed amount. You may need to examine an uncompressed \s-1PDF\s0 file stream to 
see what is being used. It \fImight\fR be possible to get the input (original) 
\&\s-1PDF\s0 into a string and look for a certain pattern of \*(L"cm\*(R" output
.Sp
.Vb 1
\&    .2399999 0 0 \-.23999999 0 792 cm
.Ve
.Sp
or similar, which is not within a save/restore (q/Q). If the stream is 
already compressed, this might not be possible.
.ie n .IP "$content\->addNS(@content)" 4
.el .IP "\f(CW$content\fR\->addNS(@content)" 4
.IX Item "$content->addNS(@content)"
Like \f(CW\*(C`add()\*(C'\fR, but does \fBnot\fR make sure there is a space between each element
and before and after the new content. It is up to \fIyou\fR to ensure that any
necessary spaces in the \s-1PDF\s0 stream are placed there explicitly!
.ie n .IP "$content\->\fBcompressFlate()\fR" 4
.el .IP "\f(CW$content\fR\->\fBcompressFlate()\fR" 4
.IX Item "$content->compressFlate()"
Marks content for compression on output.  This is done automatically
in nearly all cases, so you shouldn't need to call this yourself.
.Sp
The \f(CW\*(C`new()\*(C'\fR call can set the \fB\-compress\fR parameter to 'flate' (default) to
compress all object streams, or 'none' to suppress compression and allow you
to examine the output in an editor.
.ie n .IP "$content\->\fBtextstart()\fR" 4
.el .IP "\f(CW$content\fR\->\fBtextstart()\fR" 4
.IX Item "$content->textstart()"
Starts a text object (ignored if already in a text object). You will likely 
want to use the \f(CW\*(C`text()\*(C'\fR method (text \fIcontext\fR, not text output) instead.
.Sp
Note that calling this method, besides outputting a \fB\s-1BT\s0\fR marker, will reset
most text settings to their default values. In addition, \fB\s-1BT\s0\fR itself will
reset some transformation matrices.
.ie n .IP "$content\->\fBtextend()\fR" 4
.el .IP "\f(CW$content\fR\->\fBtextend()\fR" 4
.IX Item "$content->textend()"
Ends a text object (ignored if not in a text object).
.Sp
Note that calling this method, besides outputting an \fB\s-1ET\s0\fR marker, will output
any accumulated \fIpoststream\fR content.