1PDF::Builder::Content(3U)ser Contributed Perl DocumentatiPoDnF::Builder::Content(3)
2
6 PDF::Builder::Content - Methods for adding graphics and text to a PDF
7
9 # Start with a PDF page (new or opened)
10 my $pdf = PDF::Builder->new();
11 my $page = $pdf->page();
12 # Add new content object(s)
14 my $content = $page->gfx();
15 # and/or (as separate object name)
16 my $content = $page->text();
17 # Then call the methods below to add graphics and text to the page.
19 # Note that negative coordinates can have unpredictable effects, so
20 # keep your coordinates non-negative!
21 These methods add content to streams output for text or graphics
23 objects. Unless otherwise restricted by a check that we are in or out
24 of text mode, many methods listed here apply equally to text and
25 graphics streams. It is possible that there are some which have no
26 effect in one stream type or the other, but are currently lacking a
27 check to prevent them from being inserted into an inapplicable stream.
28
30 All public methods listed, except as otherwise noted, return $self.
31 Coordinate Transformations
33 The methods in this section change the coordinate system for the
34 current content object relative to the rest of the document. Note: the
35 changes are relative to the original page coordinates (and thus,
36 absolute), not to the previous position! Thus, "translate(10, 10);
37 translate(10, 10);" ends up only moving the origin to "[10, 10]",
38 rather than to "[20, 20]". There is one call, "transform_rel()", which
39 makes your changes relative to the previous position.
40 If you call more than one of these methods, the PDF specification
42 recommends calling them in the following order: translate, rotate,
43 scale, skew. Each change builds on the last, and you can get
44 unexpected results when calling them in a different order.
45 CAUTION: a text object ($content) behaves a bit differently. Individual
47 translate, rotate, scale, and skew calls cancel out any previous
48 settings. If you want to combine multiple transformations for text,
49 use the "transform" call.
50 $content->translate($dx,$dy)
52 Moves the origin along the x and y axes by $dx and $dy
53 respectively.
54 $content->rotate($degrees)
56 Rotates the coordinate system counter-clockwise (anti-clockwise)
57 around the current origin. Use a negative argument to rotate
58 clockwise. Note that 360 degrees will be treated as 0 degrees.
59 Note: Unless you have already moved (translated) the origin, it is,
61 and will remain, at the lower left corner of the visible sheet. It
62 will not automatically shift to another corner. For example, a
63 rotation of +90 degrees (counter-clockwise) will leave the entire
64 visible sheet in negative Y territory (0 at the left edge,
65 -original_width at the right edge), while X remains in positive
66 territory (0 at bottom, +original_height at the top edge).
67 This "rotate()" call permits any angle. Do not confuse it with the
69 page rotation "rotate" call, which only permits increments of 90
70 degrees (with opposite sign!), but does shift the origin to another
71 corner of the sheet.
72 $content->scale($sx,$sy)
74 Scales (stretches) the coordinate systems along the x and y axes.
75 Separate multipliers are provided for x and y.
76 $content->skew($skx,$sky)
78 Skews the coordinate system by $skx degrees
79 (counter-clockwise/anti-clockwise) from the x axis and $sky degrees
80 (clockwise) from the y axis. Note that 360 degrees will be treated
81 the same as 0 degrees.
82 $content->transform(%opts)
84 Use one or more of the given %opts:
85 $content->transform(
87 -translate => [$dx,$dy],
88 -rotate => $degrees,
89 -scale => [$sx,$sy],
90 -skew => [$skx,$sky],
91 -matrix => [$a, $b, $c, $d, $e, $f],
92 -point => [$x,$y]
93 )
94 A six element list may be given ("-matrix") for a further
96 transformation matrix:
97 $a = cos(rot) * scale factor for X
99 $b = sin(rot) * tan(skew for X)
100 $c = -sin(rot) * tan(skew for Y)
101 $d = cos(rot) * scale factor for Y
102 $e = translation for X
103 $f = translation for Y
104 Performs multiple coordinate transformations at once, in the order
106 recommended by the PDF specification (translate, rotate, scale,
107 skew). This is equivalent to making each transformation
108 separately, in the indicated order. A matrix of 6 values may also
109 be given ("-matrix"). The transformation matrix is updated. A
110 "-point" may be given (a point to be multiplied [transformed] by
111 the completed matrix).
112 $content->transform_rel(%opts)
114 Makes transformations similarly to "transform", except that it adds
115 to the previously set values, rather than replacing them (except
116 for scale, which multiplies the new values with the old).
117 Unlike "transform", "-matrix" and "-point" are not supported.
119 $content->matrix($a, $b, $c, $d, $e, $f)
121 (Advanced) Sets the current transformation matrix manually. Unless
122 you have a particular need to enter transformations manually, you
123 should use the "transform" method instead.
124 $a = cos(rot) * scale factor for X
126 $b = sin(rot) * tan(skew for X)
127 $c = -sin(rot) * tan(skew for Y)
128 $d = cos(rot) * scale factor for Y
129 $e = translation for X
130 $f = translation for Y
131 In text mode, the text matrix is returned. In graphics mode, $self
133 is returned.
134 Graphics State Parameters
136 The following calls also affect the text state.
137 $content->linewidth($width)
139 Sets the width of the stroke. This is the line drawn in graphics
140 mode, or the outline of a character in text mode (with appropriate
141 "render" mode). If no $width is given, the current setting is
142 returned. If the width is being set, $self is returned so that
143 calls may be chained.
144 $content->linecap($style)
146 Sets the style to be used at the end of a stroke. This applies to
147 lines which come to a free-floating end, not to "joins" ("corners")
148 in polylines (see "linejoin").
149 0 = Butt Cap
151 The stroke ends at the end of the path, with no projection.
152 1 = Round Cap
154 A semicircular arc is drawn around the end of the path with a
155 diameter equal to the line width, and is filled in.
156 2 = Projecting Square Cap
158 The stroke continues past the end of the path for half the line
159 width.
160 If no $style is given, the current setting is returned. If the
162 style is being set, $self is returned so that calls may be chained.
163 $content->linejoin($style)
165 Sets the style of join to be used at corners of a path (within a
166 multisegment polyline).
167 0 = Miter Join
169 The outer edges of the strokes extend until they meet, up to
170 the limit specified by miterlimit. If the limit would be
171 surpassed, a bevel join is used instead. For a given linewidth,
172 the more acute the angle is (closer to 0 degrees), the higher
173 the ratio of miter length to linewidth will be, and that's what
174 miterlimit controls.
175 1 = Round Join
177 A filled circle with a diameter equal to the linewidth is drawn
178 around the corner point, producing a rounded corner. The arc
179 will meet up with the sides of the line in a smooth tangent.
180 2 = Bevel Join
182 A filled triangle is drawn to fill in the notch between the two
183 strokes.
184 If no $style is given, the current setting is returned. If the
186 style is being set, $self is returned so that calls may be chained.
187 $content->miterlimit($ratio)
189 Sets the miter limit when the line join style is a miter join.
190 The ratio is the maximum length of the miter (inner to outer
192 corner) divided by the line width. Any miter above this ratio will
193 be converted to a bevel join. The practical effect is that lines
194 meeting at shallow angles are chopped off instead of producing long
195 pointed corners.
196 The default miter limit is 10.0 (approximately 11.5 degree cutoff
198 angle). The smaller the limit, the larger the cutoff angle.
199 If no $ratio is given, the current setting is returned. If the
201 ratio is being set, $self is returned so that calls may be chained.
202 $content->linedash()
204 $content->linedash($length)
205 $content->linedash($dash_length, $gap_length, ...)
206 $content->linedash(-pattern => [$dash_length, $gap_length, ...], -shift
207 => $offset)
208 Sets the line dash pattern.
209 If called without any arguments, a solid line will be drawn.
211 If called with one argument, the dashes and gaps (strokes and
213 spaces) will have equal lengths.
214 If called with two or more arguments, the arguments represent
216 alternating dash and gap lengths.
217 If called with a hash of arguments, the -pattern array may have one
219 or more elements, specifying the dash and gap lengths. A dash
220 phase may be set (-shift), which is a positive integer specifying
221 the distance into the pattern at which to start the dashed line.
222 Note that if you wish to give a shift amount, using "-shift", you
223 need to use "-pattern" instead of one or two elements.
224 If an odd number of dash array elements are given, the list is
226 repeated by the reader software to form an even number of elements
227 (pairs).
228 If a single argument of -1 is given, the current setting is
230 returned. This is an array consisting of two elements: an
231 anonymous array containing the dash pattern (default: empty), and
232 the shift (offset) amount (default: 0). If the dash pattern is
233 being set, $self is returned so that calls may be chained.
234 $content->flatness($tolerance)
236 (Advanced) Sets the maximum variation in output pixels when drawing
237 curves. The defined range of $tolerance is 0 to 100, with 0 meaning
238 use the device default flatness. According to the PDF
239 specification, you should not try to force visible line segments
240 (the curve's approximation); results will be unpredictable.
241 Usually, results for different flatness settings will be
242 indistinguishable to the eye.
243 The $tolerance value is silently clamped to be between 0 and 100.
245 If no $tolerance is given, the current setting is returned. If the
247 tolerance is being set, $self is returned so that calls may be
248 chained.
249 $content->egstate($object)
251 (Advanced) Adds an Extended Graphic State object containing
252 additional state parameters.
253 Path Construction (Drawing)
255 $content->move($x,$y)
256 Starts a new path at the specified coordinates. Note that multiple
257 x,y pairs can be given, although this isn't that useful (only the
258 last pair would have an effect).
259 $content->close()
261 Closes and ends the current path by extending a line from the
262 current position to the starting position.
263 $content->endpath()
265 Ends the current path without explicitly enclosing it. That is,
266 unlike "close", there is no line segment drawn back to the starting
267 position.
268 Straight line constructs
270 Note: None of these will actually be visible until you call "stroke" or
272 "fill". They are merely setting up the path to draw.
273 $content->line($x,$y)
275 $content->line($x,$y, $x2,$y2,...)
276 Extends the path in a line from the current coordinates to the
277 specified coordinates, and updates the current position to be the
278 new coordinates.
279 Multiple additional "[$x,$y]" pairs are permitted, to draw joined
281 multiple line segments. Note that this is not equivalent to a
282 polyline (see "poly"), because the first "[$x,$y]" pair in a
283 polyline is a move operation. Also, the "linecap" setting will be
284 used rather than the "linejoin" setting for treating the ends of
285 segments.
286 $content->hline($x)
288 $content->vline($y)
289 Shortcuts for drawing horizontal and vertical lines from the
290 current position. They are like "line()", but to the new x and
291 current y ("hline"), or to the the current x and new y ("vline").
292 $content->poly($x1,$y1, ..., $xn,$yn)
294 This is a shortcut for creating a polyline path. It moves to
295 "[$x1,$y1]", and then extends the path in line segments along the
296 specified coordinates. The current position is changed to the last
297 "[$x,$y]" pair given.
298 The difference between a polyline and a "line" with multiple
300 "[$x,$y]" pairs is that the first pair in a polyline are a move,
301 while in a line they are a draw. Also, "linejoin" instead of
302 "linecap" is used to control the appearance of the ends of line
303 segments.
304 $content->rect($x,$y, $w,$h)
306 $content->rect($x1,$y1, $w1,$h1, ..., $xn,$yn, $wn,$hn)
307 This creates paths for one or more rectangles, with their lower
308 left points at "[$x,$y]" and specified widths (+x direction) and
309 heights (+y direction). Negative widths and heights are permitted,
310 which draw to the left (-x) and below (-y) the given corner point,
311 respectively. The current position is changed to the "[$x,$y]" of
312 the last rectangle given. Note that this is the starting point of
313 the rectangle, not the end point.
314 $content->rectxy($x1,$y1, $x2,$y2)
316 This creates a rectangular path, with "[$x1,$y1]" and "[$x2,$y2]"
317 specifying opposite corners. They can be Lower Left and Upper
318 Right, or Upper Left and Lower Right, in either order, so long as
319 they are diagonally opposite each other. The current position is
320 changed to the "[$x1,$y1]" (first) pair.
321 Curved line constructs
323 Note: None of these will actually be visible until you call "stroke" or
325 "fill". They are merely setting up the path to draw.
326 $content->circle($xc,$yc, $radius)
328 This creates a circular path centered on "[$xc,$yc]" with the
329 specified radius. It does not change the current position.
330 $content->ellipse($xc,$yc, $rx,$ry)
332 This creates a closed elliptical path centered on "[$xc,$yc]", with
333 axis radii (semidiameters) specified by $rx (x axis) and $ry (y
334 axis), respectively. It does not change the current position.
335 $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move, $dir)
337 $content->arc($xc,$yc, $rx,$ry, $alpha,$beta, $move)
338 This extends the path along an arc of an ellipse centered at
339 "[$xc,$yc]". The semidiameters of the elliptical curve are $rx (x
340 axis) and $ry (y axis), respectively, and the arc sweeps from
341 $alpha degrees to $beta degrees. The current position is then set
342 to the endpoint of the arc.
343 Set $move to a true value if this arc is the beginning of a new
345 path instead of the continuation of an existing path. Either way,
346 the current position will be updated to the end of the arc. Use
347 "$rx == $ry" for a circular arc.
348 The optional $dir arc sweep direction defaults to 0 (false), for a
350 counter-clockwise/anti-clockwise sweep. Set to 1 (true) for a
351 clockwise sweep.
352 $content->pie($xc,$yc, $rx,$ry, $alpha,$beta, $dir)
354 $content->pie($xc,$yc, $rx,$ry, $alpha,$beta)
355 Creates a pie-shaped path from an ellipse centered on "[$xc,$yc]".
356 The x-axis and y-axis semidiameters of the ellipse are $rx and $ry,
357 respectively, and the arc sweeps from $alpha degrees to $beta
358 degrees. It does not change the current position. Depending on
359 the sweep angles and direction, this can draw either the pie
360 "slice" or the remaining pie (with slice removed). Use "$rx ==
361 $ry" for a circular pie. Use a different "[$xc,$yc]" for the
362 slice, to offset it from the remaining pie.
363 The optional $dir arc sweep direction defaults to 0 (false), for a
365 counter-clockwise/anti-clockwise sweep. Set to 1 (true) for a
366 clockwise sweep.
367 This is a shortcut to draw a section of elliptical (or circular)
369 arc and connect it to the center of the ellipse or circle, to form
370 a pie shape.
371 $content->curve($cx1,$cy1, $cx2,$cy2, $x,$y)
373 This extends the path in a curve from the current point to
374 "[$x,$y]", using the two specified control points to create a cubic
375 Bezier curve, and updates the current position to be the new point
376 ("[$x,$y]").
377 Within a text object, the text's baseline follows the Bezier curve.
379 Note that while multiple sets of three "[x,y]" pairs are permitted,
381 these are treated as independent cubic Bezier curves. There is no
382 attempt made to smoothly blend one curve into the next!
383 $content->qbspline($cx1,$cy1, $x,$y)
385 This extends the path in a curve from the current point to
386 "[$x,$y]", using the two specified points to create a quadratic
387 Bezier curve, and updates the current position to be the new point.
388 Internally, these splines are one or more cubic Bezier curves (see
390 "curve") with the two control points synthesized from the two given
391 points (a control point and the end point of a quadratic Bezier
392 curve).
393 Note that while multiple sets of two "[x,y]" pairs are permitted,
395 these are treated as independent quadratic Bezier curves. There is
396 no attempt made to smoothly blend one curve into the next!
397 Further note that this "spline" does not match the common
399 definition of a spline being a continuous curve passing through all
400 the given points! It is a piecewise non-continuous cubic Bezier
401 curve. Use with care, and do not make assumptions about splines for
402 you or your readers. You may wish to use the "bspline" call to have
403 a continuously smooth spline to pass through all given points.
404 Pairs of points (control point and end point) are consumed in a
406 loop. If one point or coordinate is left over at the end, it is
407 discarded (as usual practice for excess data to a routine). There
408 is no check for duplicate points or other degeneracies.
409 $content->bspline($ptsRef, %opts)
411 $content->bspline($ptsRef)
412 This extends the path in a curve from the current point to the end
413 of a list of coordinate pairs in the array referenced by $ptsRef.
414 Smoothly continuous cubic Bezier splines are used to create a curve
415 that passes through all the given points. Multiple control points
416 are synthesized; they are not supplied in the call. The current
417 position is updated to the last point.
418 Internally, these splines are one cubic Bezier curve (see "curve")
420 per pair of input points, with the two control points synthesized
421 from the tangent through each point as set by the polyline that
422 would connect each point to its neighbors. The intent is that the
423 resulting curve should follow reasonably closely a polyline that
424 would connect the points, and should avoid any major excursions.
425 See the discussions below for the handling of the control points at
426 the endpoints (current point and last input point). The point at
427 the end of the last line or curve drawn becomes the new current
428 point.
429 %opts
431 -firstseg => 'mode'
433 where mode is
434 curve
436 This is the default behavior. This forces the first
437 segment (from the current point to the first given point)
438 to be drawn as a cubic Bezier curve. This means that the
439 direction of the curve coming off the current point is
440 unconstrained (it will end up being a reflection of the
441 tangent at the first given point).
442 line1
444 This forces the first segment (from the current point to
445 the first given point) to be drawn as a curve, with the
446 tangent at the current point to be constrained as parallel
447 to the polyline segment.
448 line2
450 This forces the first segment (from the current point to
451 the first given point) to be drawn as a line segment. This
452 also sets the tangent through the first given point as a
453 continuation of the line, as well as constraining the
454 direction of the line at the current point.
455 constraint1
457 This forces the first segment (from the current point to
458 the first given point) to not be drawn, but to be an
459 invisible curve (like mode=line1) to leave the tangent at
460 the first given point unconstrained. A move will be made to
461 the first given point, and the current point is otherwise
462 ignored.
463 constraint2
465 This forces the first segment (from the current point to
466 the first given point) to not be drawn, but to be an
467 invisible line (like mode=line2) to constrain the tangent
468 at the first given point. A move will be made to the first
469 given point, and the current point is otherwise ignored.
470 -lastseg => 'mode'
472 where mode is
473 curve
475 This is the default behavior. This forces the last segment
476 (to the last given input point) to be drawn as a cubic
477 Bezier curve. This means that the direction of the curve
478 goin to the last point is unconstrained (it will end up
479 being a reflection of the tangent at the next-to-last given
480 point).
481 line1
483 This forces the last segment (to the last given input
484 point) to be drawn as a curve with the the tangent through
485 the last given point parallel to the polyline segment, thus
486 constraining the direction of the line at the last point.
487 line2
489 This forces the last segment (to the last given input
490 point) to be drawn as a line segment. This also sets the
491 tangent through the next-to-last given point as a back
492 continuation of the line, as well as constraining the
493 direction of the line at the last point.
494 constraint1
496 This forces the last segment (to the last given input
497 point) to not be drawn, but to be an invisible curve (like
498 mode=line1) to leave the tangent at the next-to-last given
499 point unconstrained. The last given input point is ignored,
500 and next-to-last point becomes the new current point.
501 constraint2
503 This forces the last segment (to the last given input
504 point) to not be drawn, but to be an invisible line (like
505 mode=line2) to constrain the tangent at the next-to-last
506 given point. The last given input point is ignored, and
507 next-to-last point becomes the new current point.
508 -ratio => n
510 n is the ratio of the length from a point to a control point to
511 the length of the polyline segment on that side of the given
512 point. It must be greater than 0.1, and the default is 0.3333
513 (1/3).
514 -colinear => 'mode'
516 This describes how to handle the middle segment when there are
517 four or more colinear points in the input set. A mode of 'line'
518 specifies that a line segment will be drawn between each of the
519 interior colinear points. A mode of 'curve' (this is the
520 default) will draw a Bezier curve between each of those points.
521 "-colinear" applies only to interior runs of colinear points,
523 between curves. It does not apply to runs at the beginning or
524 end of the point list, which are drawn as line segments or
525 linear constraints regardless of -firstseg and -lastseg
526 settings.
527 -debug => N
529 If N is 0 (the default), only the spline is returned. If it is
530 greater than 0, a number of additional items will be drawn:
531 (N>0) the points, (N>1) a green solid polyline connecting them,
532 (N>2) blue original tangent lines at each interior point, and
533 (N>3) red dashed lines and hollow points representing the
534 Bezier control points.
535 Special cases
537 Adjacent points which are duplicates are consolidated. An extra
539 coordinate at the end of the input point list (not a full "[x,y]" pair)
540 will, as usual, be ignored.
541 0 given points (after duplicate consolidation)
543 This leaves only the current point (unchanged), so it is a no-op.
544 1 given point (after duplicate consolidation)
546 This leaves the current point and one point, so it is rendered as a
547 line, regardless of %opt flags.
548 2 given points (after duplicate consolidation)
550 This leaves the current point, an intermediate point, and the end
551 point. If the three points are colinear, two line segments will be
552 drawn. Otherwise, both segments are curves (through the tangent at
553 the intermediate point). If either end segment mode is requested to
554 be a line or constraint, it is treated as a line1 mode request
555 instead.
556 N colinear points at beginning or end
558 N colinear points at beginning or end of the point set causes N-1
559 line segments ("line2" or "constraint2", regardless of the settings
560 of "-firstseg", "-lastseg", and "-colinear".
561 $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger, $reverse)
563 $content->bogen($x1,$y1, $x2,$y2, $radius, $move, $larger)
564 $content->bogen($x1,$y1, $x2,$y2, $radius, $move)
565 $content->bogen($x1,$y1, $x2,$y2, $radius)
566 (German for bow, as in a segment (arc) of a circle. This is a
567 segment of a circle defined by the intersection of two circles of a
568 given radius, with the two intersection points as inputs. There are
569 four possible resulting arcs, which can be selected with $larger
570 and $reverse.)
571 This extends the path along an arc of a circle of the specified
573 radius between "[$x1,$y1]" to "[$x2,$y2]". The current position is
574 then set to the endpoint of the arc ("[$x2,$y2]").
575 Set $move to a true value if this arc is the beginning of a new
577 path instead of the continuation of an existing path. Note that the
578 default ($move = false) is not a straight line to P1 and then the
579 arc, but a blending into the curve from the current point. It will
580 often not pass through P1!
581 Set $larger to a true value to draw the larger ("outer") arc
583 between the two points, instead of the smaller one. Both arcs are
584 drawn clockwise from P1 to P2. The default value of false draws the
585 smaller arc.
586 Set $reverse to a true value to draw the mirror image of the
588 specified arc (flip it over, so that its center point is on the
589 other side of the line connecting the two points). Both arcs are
590 drawn counter-clockwise from P1 to P2. The default (false) draws
591 clockwise arcs.
592 The $radius value cannot be smaller than half the distance from
594 "[$x1,$y1]" to "[$x2,$y2]". If it is too small, the radius will be
595 set to half the distance between the points (resulting in an arc
596 that is a semicircle). This is a silent error.
597 Path Painting (Drawing)
599 $content->stroke()
600 Strokes the current path.
601 $content->fill($use_even_odd_fill)
603 Fill the current path's enclosed area. It does not stroke the
604 enclosing path around the area.
605 If the path intersects with itself, the nonzero winding rule will
607 be used to determine which part of the path is filled in. This
608 basically fills in everything inside the path. If you would prefer
609 to use the even-odd rule, pass a true argument. This basically will
610 fill alternating closed sub-areas.
611 See the PDF Specification, section 8.5.3.3, for more details on
613 filling.
614 $content->fillstroke($use_even_odd_fill)
616 Fill the enclosed area and then stroke the current path.
617 $content->clip($use_even_odd_fill)
619 $content->clip()
620 Modifies the current clipping path by intersecting it with the
621 current path. Initially (a fresh page), the clipping path is the
622 entire media. Each definition of a path, and a "clip()" call,
623 intersects the new path with the existing clip path, so the
624 resulting clip path is no larger than the new path, and may even be
625 empty if the intersection is null.
626 If any $use_even_odd_fill parameter is given, use even-odd fill
628 (W*) instead of winding-rule fill (W). It is common usage to make
629 the "endpath()" call (n) after the "clip()" call, to clear the path
630 (unless you want to reuse that path, such as to fill and/or stroke
631 it to show the clip path). If you want to clip text glyphs, it gets
632 rather complicated, as a clip port cannot be created within a text
633 object (that will have an effect on text). See the object
634 discussion in "Rendering Order" in PDF::Builder::Docs.
635 my $grfxC1 = $page->gfx();
637 my $textC = $page->text();
638 my $grfxC2 = $page->gfx();
639 ...
640 $grfxC1->save();
641 $grfxC1->endpath();
642 $grfxC1->rect(...);
643 $grfxC1->clip();
644 $grfxC1->endpath();
645 ...
646 $textC-> output text to be clipped
647 ...
648 $grfxC2->restore();
649 Colors
651 $content->fillcolor($color)
652 $content->strokecolor($color)
653 Sets the fill (enclosed area) or stroke (path) color. The interior
654 of text characters are filled, and (if ordered by "render") the
655 outline is stroked.
656 # Use a named color
658 # -> RGB color model
659 # there are many hundreds of named colors defined in
660 # PDF::Builder::Resource::Colors
661 $content->fillcolor('blue');
662 # Use an RGB color (# followed by 3, 6, 9, or 12 hex digits)
664 # -> RGB color model
665 # This maps to 0-1.0 values for red, green, and blue
666 $content->fillcolor('#FF0000'); # red
667 # Use a CMYK color (% followed by 4, 8, 12, or 16 hex digits)
669 # -> CMYK color model
670 # This maps to 0-1.0 values for cyan, magenta, yellow, and black
671 $content->fillcolor('%FF000000'); # cyan
672 # Use an HSV color (! followed by 3, 6, 9, or 12 hex digits)
674 # -> RGB color model
675 # This maps to 0-360 degrees for the hue, and 0-1.0 values for
676 # saturation and value
677 $content->fillcolor('!FF0000');
678 # Use an HSL color (& followed by 3, 6, 9, or 12 hex digits)
680 # -> L*a*b color model
681 # This maps to 0-360 degrees for the hue, and 0-1.0 values for
682 # saturation and lightness. Note that 360 degrees = 0 degrees (wraps)
683 $content->fillcolor('&FF0000');
684 # Use an L*a*b color ($ followed by 3, 6, 9, or 12 hex digits)
686 # -> L*a*b color model
687 # This maps to 0-100 for L, -100 to 100 for a and b
688 $content->fillcolor('$FF0000');
689 In all cases, if too few digits are given, the given digits are
691 silently right-padded with 0's (zeros). If an incorrect number of
692 digits are given, the next lowest number of expected digits are
693 used, and the remaining digits are silently ignored.
694 # A single number between 0.0 (black) and 1.0 (white) is an alternate way
696 # of specifying a gray scale.
697 $content->fillcolor(0.5);
698 # Three array elements between 0.0 and 1.0 is an alternate way of specifying
700 # an RGB color.
701 $content->fillcolor(0.3, 0.59, 0.11);
702 # Four array elements between 0.0 and 1.0 is an alternate way of specifying
704 # a CMYK color.
705 $content->fillcolor(0.1, 0.9, 0.3, 1.0);
706 In all cases, if a number is less than 0, it is silently turned
708 into a 0. If a number is greater than 1, it is silently turned into
709 a 1. This "clamps" all values to the range 0.0-1.0.
710 # A single reference is treated as a pattern or shading space.
712 # Two or more entries with the first element a Perl reference, is treated
714 # as either an indexed colorspace reference plus color-index(es), or
715 # as a custom colorspace reference plus parameter(s).
716 If no value was passed in, the current fill color (or stroke color)
718 array is returned, otherwise $self is returned.
719 $content->shade($shade, @coord)
721 Sets the shading matrix.
722 $shade
724 A hash reference that includes a "name()" method for the shade
725 name.
726 @coord
728 An array of 4 items: X-translation, Y-translation, X-scaled and
729 translated, Y-scaled and translated.
730 External Objects
732 $content->image($image_object, $x,$y, $width,$height)
733 $content->image($image_object, $x,$y, $scale)
734 $content->image($image_object, $x,$y)
735 $content->image($image_object)
736 # Example
737 my $image_object = $pdf->image_jpeg($my_image_file);
738 $content->image($image_object, 100, 200);
739 Places an image on the page in the specified location (specifies
741 the lower left corner of the image). The default location is
742 "[0,0]".
743 If coordinate transformations have been made (see Coordinate
745 Transformations above), the position and scale will be relative to
746 the updated coordinates. Otherwise, "[0,0]" will represent the
747 bottom left corner of the page, and $width and $height will be
748 measured at 72dpi.
749 For example, if you have a 600x600 image that you would like to be
751 shown at 600dpi (i.e., one inch square), set the width and height
752 to 72. (72 Big Points is one inch)
753 $content->formimage($form_object, $x,$y, $scaleX, $scaleY)
755 $content->formimage($form_object, $x,$y, $scale)
756 $content->formimage($form_object, $x,$y)
757 $content->formimage($form_object)
758 Places an XObject on the page in the specified location (giving the
759 lower left corner of the image) and scale (applied to the image's
760 native height and width). If no scale is given, use 1 for both X
761 and Y. If one scale is given, use for both X and Y. If two scales
762 given, they are for (separately) X and Y. In general, you should
763 not greatly distort an image by using greatly different scaling
764 factors in X and Y, although it is now possible for when that
765 effect is desirable. The "$x,$y" default is "[0,0]".
766 Note that while this method is named form image, it is also used
768 for the pseudoimages created by the barcode routines. Images are
769 naturally dimensionless (1 point square) and need at some point to
770 be scaled up to the desired point size. Barcodes are naturally
771 sized in points, and should be scaled at approximately 1.
772 Therefore, it would greatly overscale barcodes to multiply by image
773 width and height within "formimage", and require scaling of 1/width
774 and 1/height in the call. So, we leave scaling alone within
775 "formimage" and have the user manually scale images by the image
776 width and height (in pixels) in the call to "formimage".
777 Text
779 Text State Parameters
780 All of the following parameters that take a size are applied before any
782 scaling takes place, so you don't need to adjust values to counteract
783 scaling.
784 $spacing = $content->charspace($spacing)
786 Sets additional spacing between characters in a line. This is in
787 points, and is initially zero. It may be positive to give an
788 expanded effect to words, or it may be negative to give a condensed
789 effect to words. If $spacing is given, the current setting is
790 replaced by that value and $self is returned (to permit chaining).
791 If $spacing is not given, the current setting is returned.
792 CAUTION: be careful about using "charspace" if you are using a
794 connected font. This might include Arabic, Devanagari, Latin
795 cursive handwriting, and so on. You don't want to leave gaps
796 between characters, or cause overlaps. For such fonts and
797 typefaces, set the "charspace" spacing to 0.
798 $spacing = $content->wordspace($spacing)
800 Sets additional spacing between words in a line. This is in points
801 and is initially zero (i.e., just the width of the space, without
802 anything extra). It may be negative to close up sentences a bit.
803 If $spacing is given, the current setting is replaced by that value
804 and $self is returned (to permit chaining). If $spacing is not
805 given, the current setting is returned.
806 Note that it is a limitation of the PDF specification (as of
808 version 1.7, section 9.3.3) that only spacing with an ASCII space
809 (x20) is adjusted. Neither required blanks (xA0) nor any multiple-
810 byte spaces (including thin and wide spaces) are currently
811 adjusted.
812 $scale = $content->hscale($scale)
814 Sets the percentage of horizontal text scaling (relative sizing,
815 not spacing). This is initally 100 (percent, i.e., no scaling). A
816 scale of greater than 100 will stretch the text, while less than
817 100 will compress it. If $scale is given, the current setting is
818 replaced by that value and $self is returned (to permit chaining).
819 If $scale is not given, the current setting is returned.
820 Note that scaling affects all of the character widths, interletter
822 spacing, and interword spacing. It is inadvisable to stretch or
823 compress text by a large amount, as it will quickly make the text
824 unreadable. If your objective is to justify text, you will usually
825 be better off using "charspace" and "wordspace" to expand (or
826 slightly condense) a line to fill a desired width. Also see the
827 "text_justify()" calls for this purpose.
828 $leading = $content->leading($leading)
830 $leading = $content->leading()
831 Sets the text leading, which is the distance between baselines.
832 This is initially zero (i.e., the lines will be printed on top of
833 each other). The unit of leading is points. If $leading is given,
834 the current setting is replaced by that value and $self is returned
835 (to permit chaining). If $leading is not given, the current
836 setting is returned.
837 Note that "leading" here is defined as used in electronic
839 typesetting and the PDF specification, which is the full interline
840 spacing (text baseline to text baseline distance, in points). In
841 cold metal typesetting, leading was usually the extra spacing
842 between lines beyond the font height itself, created by inserting
843 lead (type alloy) shims.
844 $leading = $content->lead($leading)
846 $leading = $content->lead()
847 Deprecated, to be removed after March 2023. Use "leading()" now.
848 Note that the "$self-"{' lead'}> internal variable is no longer
850 available, having been replaced by "$self-"{' leading'}>.
851 $mode = $content->render($mode)
853 Sets the text rendering mode.
854 0 = Fill text
856 1 = Stroke text (outline)
857 2 = Fill, then stroke text
858 3 = Neither fill nor stroke text (invisible)
859 4 = Fill text and add to path for clipping
860 5 = Stroke text and add to path for clipping
861 6 = Fill, then stroke text and add to path for clipping
862 7 = Add text to path for clipping
863 If $mode is given, the current setting is replaced by that value
865 and $self is returned (to permit chaining). If $mode is not given,
866 the current setting is returned.
867 $dist = $content->rise($dist)
869 Adjusts the baseline up or down from its current location. This is
870 initially zero. A $dist greater than 0 moves the baseline up the
871 page (y increases).
872 Use this for creating superscripts or subscripts (usually along
874 with an adjustment to the font size). If $dist is given, the
875 current setting is replaced by that value and $self is returned (to
876 permit chaining). If $dist is not given, the current setting is
877 returned.
878 %state = $content->textstate(charspace => $value, wordspace => $value,
880 ...)
881 This is a shortcut for setting multiple text state parameters at
882 once. If any parameters are set, an empty hash is returned. This
883 can also be used without arguments to retrieve the current text
884 state settings (a hash of the state is returned).
885 Note: This does not work with the "save" and "restore" commands.
887 $content->font($font_object, $size)
889 Sets the font and font size.
890 # Example (12 point Helvetica)
892 my $pdf = PDF::Builder->new();
893 my $fontname = $pdf->corefont('Helvetica');
894 $content->font($fontname, 12);
895 Positioning Text
897 $content->distance($dx,$dy)
899 This moves to the start of the previously-written line, plus an
900 offset by the given amounts, which are both required. "[0,0]" would
901 overwrite the previous line, while "[0,36]" would place the new
902 line 36pt above the old line (higher y). The $dx moves to the
903 right, if positive.
904 "distance" is analogous to graphic's "move", except that it is
906 relative to the beginning of the previous text write, not to the
907 coordinate origin. Note that subsequent text writes will be
908 relative to this new starting (left) point and Y position! E.g., if
909 you give a non-zero $dx, subsequent lines will be indented by that
910 amount.
911 $content->cr()
913 $content->cr($vertical_offset)
914 $content->cr(0)
915 If passed without an argument, moves (down) to the start of the
916 next line (distance set by "leading"). This is similar to "nl()".
917 If passed with an argument, the "leading" distance is ignored and
919 the next line starts that far up the page (positive value) or down
920 the page (negative value) from the current line. "Y" increases
921 upward, so a negative value would normally be used to get to the
922 next line down.
923 An argument of 0 would simply return to the start of the present
925 line, overprinting it with new text. That is, it acts as a simple
926 carriage return, without a linefeed.
927 $content->nl()
929 $content->nl($indent)
930 $content->nl(0)
931 Moves to the start of the next line (see "leading"). If $indent is
932 not given, or is 0, there is no indentation. Otherwise, indent by
933 that amount (outdent if a negative value). The unit of measure is
934 hundredths of a "unit of text space", or roughly 88 per em.
935 ($tx,$ty) = $content->textpos()
937 Returns the current text position on the page (where next write
938 will happen) as an array.
939 Note: This does not affect the PDF in any way. It only tells you
941 where the the next write will occur.
942 $width = $content->advancewidth($string, %opts)
944 $width = $content->advancewidth($string)
945 Options %opts:
946 font => $f3_TimesRoman
948 Change the font used, overriding $self->{' font'}. The font
949 must have been previously created (i.e., is not the name).
950 Example: use Times-Roman.
951 fontsize => 12
953 Change the font size, overriding $self->{' fontsize'}. Example:
954 12 pt font.
955 wordspace => 0.8
957 Change the additional word spacing, overriding
958 $self->wordspace(). Example: add 0.8 pt between words.
959 charspace => -2.1
961 Change the additional character spacing, overriding
962 $self->charspace(). Example: subtract 2.1 pt between letters,
963 to condense the text.
964 hscale => 125
966 Change the horizontal scaling factor, overriding
967 $self->hscale(). Example: stretch text to 125% of its natural
968 width.
969 Returns the width of the $string based on all currently set text-
971 state attributes. These can optionally be overridden with %opts.
972 Note that these values temporarily replace the existing values, not
973 scaling them up or down. For example, if the existing charspace is
974 2, and you give in options a value of 3, the value used is 3, not
975 5.
976 Note: This does not affect the PDF in any way. It only tells you
978 how much horizontal space a text string will take up.
979 Rendering Text
981 Single Lines
983 $width = $content->text($text, %opts)
985 $width = $content->text($text)
986 Adds text to the page (left justified). The width used (in points)
987 is returned.
988 Options:
990 -indent => $distance
992 Indents the text by the number of points (A value less than 0
993 gives an outdent).
994 -underline => 'none'
996 -underline => 'auto'
997 -underline => $distance
998 -underline => [$distance, $thickness, ...]
999 Underlines the text. $distance is the number of units beneath
1000 the baseline, and $thickness is the width of the line.
1001 Multiple underlines can be made by passing several distances
1002 and thicknesses. A value of 'none' means no underlining (is
1003 the default).
1004 Example:
1006 # 3 underlines:
1008 # distance 4, thickness 1, color red
1009 # distance 7, thickness 1.5, color yellow
1010 # distance 11, thickness 2, color (strokecolor default)
1011 -underline=>[4,[1,'red'],7,[1.5,'yellow'],11,2],
1012 -strikethru => 'none'
1014 -strikethru => 'auto'
1015 -strikethru => $distance
1016 -strikethru => [$distance, $thickness, ...]
1017 Strikes through the text (like HTML s tag). A value of 'auto'
1018 places the line about 30% of the font size above the baseline,
1019 or a specified $distance (above the baseline) and $thickness
1020 (in points). Multiple strikethroughs can be made by passing
1021 several distances and thicknesses. A value of 'none' means no
1022 strikethrough. It is the default.
1023 Example:
1025 # 2 strikethroughs:
1027 # distance 4, thickness 1, color red
1028 # distance 7, thickness 1.5, color yellow
1029 -strikethru=>[4,[1,'red'],7,[1.5,'yellow']],
1030 $width = $content->textHS($HSarray, $settings, %opts)
1032 $width = $content->textHS($HSarray, $settings)
1033 Takes an array of hashes produced by HarfBuzz::Shaper and outputs
1034 them to the PDF output file. HarfBuzz outputs glyph CIDs and
1035 positioning information. It may rearrange and swap characters
1036 (glyphs), and the result may bear no resemblance to the original
1037 Unicode point list. You should see examples/HarfBuzz.pl, which
1038 shows a number of examples with Latin and non-Latin text, as well
1039 as vertical writing. examples/resources/HarfBuzz_example.pdf is
1040 available in case you want to see some examples and don't yet have
1041 HarfBuzz::Shaper installed.
1042 $HSarray
1044 This is the reference to array of hashes produced by
1045 HarfBuzz::Shaper, normally unchanged after being created (but
1046 can be modified). See "Using Shaper" in PDF::Builder::Docs for
1047 some things that can be done.
1048 $settings
1050 This a reference to a hash of various pieces of information
1051 that "textHS()" needs in order to function. They include:
1052 script => 'script_name'
1054 This is the standard 4 letter code (e.g., 'Latn') for the
1055 script (alphabet and writing system) you're using.
1056 Currently, only Latn (Western writing systems) do kerning,
1057 and 'Latn' is the default. HarfBuzz::Shaper will usually be
1058 able to figure out from the Unicode points used what the
1059 script is, and you might be able to use the "set_script()"
1060 call to override its guess. However, PDF::Builder and
1061 HarfBuzz::Shaper do not talk to each other about the script
1062 being used.
1063 features => array_of_features
1065 This item is required, but may be empty, e.g.,
1066 "$settings->{'features'} = ();". It can include switches
1067 using the standard HarfBuzz naming, and a + or - switch,
1068 such as '-liga' to turn off ligatures. '-liga' and '-kern',
1069 to turn off ligatures and kerning, are the only features
1070 supported currently. Note that this is separate from any
1071 switches for features that you send to HarfBuzz::Shaper
1072 (with "$hb->add_features()", etc.) when you run it (before
1073 "textHS()").
1074 language => 'language_code'
1076 This item is optional and currently does not appear to have
1077 any substantial effect with HarfBuzz::Shaper. It is the
1078 standard code for the language to be used, such as 'en' or
1079 'en_US'. You might need to define this for
1080 HarfBuzz::Shaper, in case that system can't surmise the
1081 language rules to be used.
1082 dir => 'flag'
1084 Tell "textHS()" whether this text is to be written in a
1085 Left-To-Right manner (L, the default), Right-To-Left (R),
1086 Top-To-Bottom (T), or Bottom-To-Top (B). From the script
1087 used (Unicode points), HarfBuzz::Shaper can usually figure
1088 out what direction to write text in. Also, HarfBuzz::Shaper
1089 does not share its information with PDF::Builder -- you
1090 need to separately specify the direction, unless you want
1091 to accept the default LTR direction. You can use
1092 HarfBuzz::Shaper's "get_direction()" call (in addition to
1093 "get_language()" and "get_script()") to see what HarfBuzz
1094 thinks is the correct text direction. "set_direction()" may
1095 be used to override Shaper's guess as to the direction.
1096 By the way, if the direction is RTL, HarfBuzz will reverse
1098 the text and return an array with the last character first
1099 (to be written LTR). Likewise, for BTT, HarfBuzz will
1100 reverse the text and return a string to be written from the
1101 top down. Languages which are normally written horizontally
1102 are usually set vertically with direction TTB. If setting
1103 text vertically, ligatures and kerning, as well as
1104 character connectivity for cursive scripts, are
1105 automatically turned off, so don't let the direction
1106 default to LTR or RTL in the Shaper call, and then try to
1107 fix it up in "textHS()".
1108 align => 'flag'
1110 Given the current output location, align the text at the
1111 Beginning of the line (left for LTR, right for RTL),
1112 Centered at the location, or at the End of the line (right
1113 for LTR, left for RTL). The default is B. Centered is
1114 analogous to using "text_center()", and End is analogous to
1115 using "text_right()". Similar alignments are done for TTB
1116 and BTT.
1117 dump => flag
1119 Set to 1, it prints out positioning and glyph CID
1120 information (to STDOUT) for each glyph in the chunk. The
1121 default is 0 (no information dump).
1122 -minKern => amount (default 1)
1124 If the amount of kerning (font character width differs from
1125 glyph ax value) is larger than this many character grid
1126 units, use the unaltered ax for the width ("textHS()" will
1127 output a kern amount in the TJ operation). Otherwise,
1128 ignore kerning and use ax of the actual character width.
1129 The intent is to avoid bloating the PDF code with
1130 unnecessary tiny kerning adjustments in the TJ operation.
1131 %opts
1133 This a hash of options.
1134 -underline => underlining_instructions
1136 See "text()" for available instructions.
1137 -strikethru => strikethrough_instructions
1139 See "text()" for available instructions.
1140 -strokecolor => line_color
1142 Color specification (e.g., 'green', '#FF3377') for
1143 underline or strikethrough, if not given in an array with
1144 their instructions.
1145 Text is sent separately to HarfBuzz::Shaper in 'chunks'
1147 ('segments') of a single script (alphabet), a single direction
1148 (LTR, RTL, TTB, or BTT), a single font file, and a single font
1149 size. A chunk may consist of a large amount of text, but at
1150 present, "textHS()" can only output a single line. For long lines
1151 that need to be split into column-width lines, the best way may be
1152 to take the array of hashes returned by HarfBuzz::Shaper and split
1153 it into smaller chunks at spaces and other whitespace. You may have
1154 to query the font to see what the glyph CIDs are for space and
1155 anything else used.
1156 It is expected that when "textHS()" is called, that the font and
1158 font size have already been set in PDF::Builder code, as this
1159 information is needed to interpret what HarfBuzz::Shaper is
1160 returning, and to write it to the PDF file. Needless to say, the
1161 font should be opened from the same file as was given to
1162 HarfBuzz::Shaper ("ttfont()" only, with .ttf or .otf files), and
1163 the font size must be the same. The appropriate location on the
1164 page must also already have been specified.
1165 NOTE: as HarfBuzz::Shaper is still in its early days, it is
1167 possible that there will be major changes in its API. We hope that
1168 all changes will be upwardly compatible, but do not control this
1169 package and cannot guarantee that there will not be any
1170 incompatible changes that in turn require changes to PDF::Builder
1171 ("textHS()").
1172 $width = $content->advancewidthHS($HSarray, $settings, %opts)
1174 $width = $content->advancewidthHS($HSarray, $settings)
1175 Returns text chunk width (in points) for Shaper-defined glyph
1176 array. This is the horizontal width for LTR and RTL direction, and
1177 the vertical height for TTB and BTT direction. Note: You must
1178 define the font and font size before calling "advancewidthHS()".
1179 $HSarray
1181 The array reference of glyphs created by the HarfBuzz::Shaper
1182 call. See "textHS()" for details.
1183 $settings
1185 the hash reference of settings. See "textHS()" for details.
1186 dir => 'L' etc.
1188 the direction of the text, to know which "advance" value to
1189 sum up.
1190 %opts
1192 Options. Unlike "advancewidth()", you cannot override the font,
1193 font size, etc. used by HarfBuzz::Shaper to calculate the glyph
1194 list.
1195 -doKern => flag (default 1)
1197 If 1, cancel minor kerns per "-minKern" setting. This flag
1198 should be 0 (false) if -kern was passed to HarfBuzz::Shaper
1199 (do not kern text). This is treated as 0 if an ax override
1200 setting is given.
1201 -minKern => amount (default 1)
1203 If the amount of kerning (font character width differs from
1204 glyph ax value) is larger than this many character grid
1205 units, use the unaltered ax for the width ("textHS()" will
1206 output a kern amount in the TJ operation). Otherwise,
1207 ignore kerning and use ax of the actual character width.
1208 The intent is to avoid bloating the PDF code with
1209 unnecessary tiny kerning adjustments in the TJ operation.
1210 Returns total width in points.
1212 Advanced Methods
1214 $content->save()
1215 Saves the current graphics state on a PDF stack. See PDF definition
1216 8.4.2 through 8.4.4 for details. This includes the line width, the
1217 line cap style, line join style, miter limit, line dash pattern,
1218 stroke color, fill color, current transformation matrix, current
1219 clipping port, flatness, and dictname. This method applies to both
1220 text and gfx objects.
1221 $content->restore()
1223 Restores the most recently saved graphics state (see "save"),
1224 removing it from the stack. You cannot restore the graphics state
1225 (pop it off the stack) unless you have done at least one save
1226 (pushed it on the stack). This method applies to both text and gfx
1227 objects.
1228 $content->add(@content)
1230 Add raw content (arbitrary string(s)) to the PDF stream. You will
1231 generally want to use the other methods in this class instead,
1232 unless this is in order to implement some PDF operation that
1233 PDF::Builder does not natively support. An array of multiple
1234 strings may be given; they will be concatenated with spaces between
1235 them.
1236 Be careful when doing this, as you are dabbling in the black arts,
1238 directly setting PDF operations!
1239 One interesting use is to split up an overly long object stream
1241 that is giving your editor problems when exploring a PDF file. Add
1242 a newline add("\n") every few hundred bytes of output or so, to do
1243 this. Note that you must use double quotes (quotation marks),
1244 rather than single quotes (apostrophes).
1245 Use extreme care if inserting BT and ET markers into the PDF
1247 stream. You may want to use "textstart()" and "textend()" calls
1248 instead, and even then, there are many side effects either way. It
1249 is generally not useful to suspend text mode with ET/textend and
1250 BT/textstart, but it is possible, if you really need to do it.
1251 Another, useful, case is when your input PDF is from the Chrome
1253 browser printing a page to PDF with headers and/or footers. In some
1254 versions, this leaves the PDF page with a strange scaling (such as
1255 the page height in points divided by 3300) and the Y-axis flipped
1256 so 0 is at the top. This causes problems when trying to add
1257 additional text or graphics in a new text or graphics record, where
1258 text is flipped (mirrored) upsidedown and at the wrong end of the
1259 page. If this happens, you might be able to cure it by adding
1260 $scale = .23999999; # example, 792/3300, examine PDF or experiment!
1262 ...
1263 if ($scale != 1) {
1264 my @pageDim = $page->mediabox(); # e.g., 0 0 612 792
1265 my $size_page = $pageDim[3]/$scale; # 3300 = 792/.23999999
1266 my $invScale = 1.0/$scale; # 4.16666684
1267 $text->add("$invScale 0 0 -$invScale 0 $size_page cm");
1268 }
1269 as the first output to the $text stream. Unfortunately, it is
1271 difficult to predict exactly what $scale should be, as it may be
1272 3300 units per page, or a fixed amount. You may need to examine an
1273 uncompressed PDF file stream to see what is being used. It might be
1274 possible to get the input (original) PDF into a string and look for
1275 a certain pattern of "cm" output
1276 .2399999 0 0 -.23999999 0 792 cm
1278 or similar, which is not within a save/restore (q/Q). If the stream
1280 is already compressed, this might not be possible.
1281 $content->addNS(@content)
1283 Like "add()", but does not make sure there is a space between each
1284 element and before and after the new content. It is up to you to
1285 ensure that any necessary spaces in the PDF stream are placed there
1286 explicitly!
1287 $content->compressFlate()
1289 Marks content for compression on output. This is done
1290 automatically in nearly all cases, so you shouldn't need to call
1291 this yourself.
1292 The "new()" call can set the -compress parameter to 'flate'
1294 (default) to compress all object streams, or 'none' to suppress
1295 compression and allow you to examine the output in an editor.
1296 $content->textstart()
1298 Starts a text object (ignored if already in a text object). You
1299 will likely want to use the "text()" method (text context, not text
1300 output) instead.
1301 Note that calling this method, besides outputting a BT marker, will
1303 reset most text settings to their default values. In addition, BT
1304 itself will reset some transformation matrices.
1305 $content->textend()
1307 Ends a text object (ignored if not in a text object).
1308 Note that calling this method, besides outputting an ET marker,
1310 will output any accumulated poststream content.
1311perl v5.34.0 2021-07-22 PDF::Builder::Content(3)