1PDF::Builder(3) User Contributed Perl Documentation PDF::Builder(3)
2
6 PDF::Builder - Facilitates the creation and modification of PDF files
7
9 use PDF::Builder;
10 # Create a blank PDF file
12 $pdf = PDF::Builder->new();
13 # Open an existing PDF file
15 $pdf = PDF::Builder->open('some.pdf');
16 # Add a blank page
18 $page = $pdf->page();
19 # Retrieve an existing page
21 $page = $pdf->open_page($page_number);
22 # Set the page size
24 $page->mediabox('Letter');
25 # Add a built-in font to the PDF
27 $font = $pdf->corefont('Helvetica-Bold');
28 # Add an external TTF font to the PDF
30 $font = $pdf->ttfont('/path/to/font.ttf');
31 # Add some text to the page
33 $text = $page->text();
34 $text->font($font, 20);
35 $text->translate(200, 700);
36 $text->text('Hello World!');
37 # Save the PDF
39 $pdf->saveas('/path/to/new.pdf');
40
42 See the file README (in downloadable package and on CPAN) for a summary
43 of prerequisites and tools needed to install PDF::Builder, both
44 mandatory and optional.
45 SOFTWARE DEVELOPMENT KIT
47 There are four levels of involvement with PDF::Builder. Depending on
48 what you want to do, different kinds of installs are recommended. See
49 "Software Development Kit" in PDF::Builder::Docs for suggestions.
50 OPTIONAL LIBRARIES
52 PDF::Builder can make use of some optional libraries, which are not
53 required for a successful installation, but improve speed and
54 capabilities. See "Optional Libraries" in PDF::Builder::Docs for more
55 information.
56 STRINGS (CHARACTER TEXT)
58 There are some things you should know about character encoding (for
59 text), before you dive in to coding. Please go to "Strings (Character
60 Text)" in PDF::Builder::Docs and have a read.
61 RENDERING ORDER
63 Invoking "text" and "graphics" methods can lead to unexpected results
64 (a different ordering of output than intended). See "Rendering Order"
65 in PDF::Builder::Docs for more information.
66 PDF VERSIONS SUPPORTED
68 PDF::Builder is mostly PDF 1.4-compliant, but there are complications
69 you should be aware of. Please read "PDF Versions Supported" in
70 PDF::Builder::Docs for details.
71 SUPPORTED PERL VERSIONS
73 PDF::Builder intends to support all major Perl versions that were
74 released in the past six years, plus one, in order to continue working
75 for the life of most long-term-stable (LTS) server distributions. See
76 the <https://www.cpan.org/src/> table First release in each branch of
77 Perl x.xxxx0 "Major" release dates.
78 For example, a version of PDF::Builder released on 2018-06-05 would
80 support the last major version of Perl released on or after 2012-06-05
81 (5.18), and then one before that, which would be 5.16. Alternatively,
82 the last major version of Perl released before 2012-06-05 is 5.16.
83 The intent is to avoid expending unnecessary effort in supporting very
85 old (obsolete) versions of Perl. If you need to use this module on a
86 server with an extremely out-of-date version of Perl, consider using
87 either plenv or Perlbrew to run a newer version of Perl without needing
88 admin privileges.
89 KNOWN ISSUES
91 This module does not work with perl's -l command-line switch.
92 There is a file INFO/KNOWN_INCOMP which lists known incompatibilities
94 with PDF::API2, in case you're thinking of porting over something from
95 that world, or have experience there and want to try PDF::Builder.
96 There is also a file INFO/DEPRECATED, which lists things which are
97 planned to be removed at some point.
98 HISTORY
100 The history of PDF::Builder is a complex and exciting saga... OK, it
101 may be mildly interesting. Have a look at "History" in
102 PDF::Builder::Docs section.
103
105 PDF::API2 was originally written by Alfred Reibenschuh. See the HISTORY
106 section for more information.
107 It was maintained by Steve Simms.
109 PDF::Builder is currently being maintained by Phil M. Perry.
111 SUPPORT
113 The full source is on https://github.com/PhilterPaper/Perl-PDF-Builder.
114 The release distribution is on CPAN:
116 https://metacpan.org/pod/PDF::Builder.
117 Bug reports are on
119 https://github.com/PhilterPaper/Perl-PDF-Builder/issues?q=is%3Aissue+sort%3Aupdated-desc
120 (with "bug" label), feature requests have an "enhancement" label, and
121 general discussions (architecture, roadmap, etc.) have a "general
122 discussion" label.
123 Do not under any circumstances open a PR (Pull Request) to report a
125 bug. It is a waste of both your and our time and effort. Open a regular
126 ticket (issue), and attach a Perl (.pl) program illustrating the
127 problem, if possible. If you believe that you have a program patch, and
128 offer to share it as a PR, we may give the go-ahead. Unsolicited PRs
129 may be closed without further action.
130
132 This software is Copyright (c) 2017-2021 by Phil M. Perry.
133 This is free software, licensed under:
135 The GNU Lesser General Public License (LGPL) Version 2.1, February 1999
137 (The master copy of this license lives on the GNU website.)
139 (A copy is provided in the INFO/LICENSE file for your convenience.)
140 This section of Builder.pm is intended only as a very brief summary of
142 the license; please consider INFO/LICENSE to be the controlling
143 version, if there is any conflict or ambiguity between the two.
144 This program is free software; you can redistribute it and/or modify it
146 under the terms of the GNU Lesser General Public License, as published
147 by the Free Software Foundation, either version 2.1 of the License, or
148 (at your option) any later version of this license.
149 NOTE: there are several files in this distribution which were
151 incorporated from outside sources and carry different licenses. If a
152 file states that it is under a license different than LGPL 2.1, that
153 license and its terms will apply to that file, and not LGPL 2.1.
154 This library is distributed in the hope that it will be useful, but
156 WITHOUT ANY WARRANTY; without even the implied warranty of
157 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
158 General Public License for more details.
159
161 $pdf = PDF::Builder->new(%options)
162 $pdf = PDF::Builder->new()
163 Creates a new PDF object.
164 Options
166 -file
168 If you will be saving it as a file and already know the
169 filename, you can give the '-file' option to minimize possible
170 memory requirements later on.
171 -compress
173 The '-compress' option can be given to specify stream
174 compression: default is 'flate', 'none' is no compression. No
175 other compression methods are currently supported.
176 -outver
178 The '-outver' option defaults to 1.4 as the output PDF version
179 and the highest allowed feature version (attempts to use
180 anything higher will give a warning). If an existing PDF with
181 a higher version is read in, -outver will be increased to that
182 version, with a warning.
183 -msgver
185 The '-msgver' option value of 1 (default) gives a warning
186 message if the '-outver' PDF level has to be bumped up due to
187 either a higher PDF level file being read in, or a higher level
188 feature was requested. A value of 0 suppresses the warning
189 message.
190 -diaglevel
192 The '-diaglevel' option can be given to specify the level of
193 diagnostics given by IntegrityCheck(). The default is level 2
194 (errors and warnings). See "IntegrityCheck" in
195 PDF::Builder::Docs for more information.
196 Example:
198 $pdf = PDF::Builder->new();
200 ...
201 print $pdf->stringify();
202 $pdf = PDF::Builder->new(-compress => 'none');
204 # equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)
205 $pdf = PDF::Builder->new();
207 ...
208 $pdf->saveas('our/new.pdf');
209 $pdf = PDF::Builder->new(-file => 'our/new.pdf');
211 ...
212 $pdf->save();
213 $pdf = PDF::Builder->open($pdf_file, %options)
215 $pdf = PDF::Builder->open($pdf_file)
216 Opens an existing PDF file. See "new()" for options.
217 Example:
219 $pdf = PDF::Builder->open('our/old.pdf');
221 ...
222 $pdf->saveas('our/new.pdf');
223 $pdf = PDF::Builder->open('our/to/be/updated.pdf');
225 ...
226 $pdf->update();
227 $pdf = PDF::Builder->open_scalar($pdf_string, %options)
229 $pdf = PDF::Builder->open_scalar($pdf_string)
230 Opens a PDF contained in a string. See "new()" for other options.
231 -diags => 1
233 Display warnings when non-conforming PDF structure is found,
234 and fix up where possible. See PDF::Builder::Basic::PDF::File
235 for more information.
236 Example:
238 # Read a PDF into a string, for the purpose of demonstration
240 open $fh, 'our/old.pdf' or die $@;
241 undef $/; # Read the whole file at once
242 $pdf_string = <$fh>;
243 $pdf = PDF::Builder->open_scalar($pdf_string);
245 ...
246 $pdf->saveas('our/new.pdf');
247 $pdf->preferences(%options)
249 Controls viewing preferences for the PDF, including the Page Mode,
250 Page Layout, Viewer, and Initial Page Options. See "Preferences -
251 set user display preferences" in PDF::Builder::Docs for details on
252 all these option groups.
253 $val = $pdf->default($parameter)
255 $pdf->default($parameter, $value)
256 Gets/sets the default value for a behavior of PDF::Builder.
257 Supported Parameters:
259 nounrotate
261 prohibits Builder from rotating imported/opened page to re-
262 create a default pdf-context.
263 pageencaps
265 enables Builder's adding save/restore commands upon
266 importing/opening pages to preserve graphics-state for
267 modification.
268 copyannots
270 enables importing of annotations (*EXPERIMENTAL*).
271 CAUTION: Perl::Critic (tools/1_pc.pl) has started flagging the name
273 "default" as a reserved keyword in higher Perl versions. Use with
274 caution, and be aware that this name may have to be changed in the
275 future.
276 $version = $pdf->version($new_version)
278 $version = $pdf->version()
279 Get/set the PDF version (e.g. 1.4).
280 For compatibility with earlier releases, if no decimal point is
282 given, assume "1." precedes the number given.
283 A warning message is given if you attempt to decrease the PDF
285 version, as you might have already read in a higher level file, or
286 used a higher level feature.
287 $bool = $pdf->isEncrypted()
289 Checks if the previously opened PDF is encrypted.
290 %infohash = $pdf->info(%infohash)
292 Gets/sets the info structure of the document.
293 See "info Example" in PDF::Builder::Docs section for an example of
295 the use of this method.
296 @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
298 Gets/sets the supported info-structure tags.
299 Example:
301 @attributes = $pdf->infoMetaAttributes;
303 print "Supported Attributes: @attr\n";
304 @attributes = $pdf->infoMetaAttributes('CustomField1');
306 print "Supported Attributes: @attributes\n";
307 $xml = $pdf->xmpMetadata($xml)
309 Gets/sets the XMP XML data stream.
310 See "XMP XML example" in PDF::Builder::Docs section for an example
312 of the use of this method.
313 $pdf->pageLabel($index, $options)
315 Sets page label options.
316 Supported Options:
318 -style
320 Roman, roman, decimal, Alpha or alpha.
321 -start
323 Restart numbering at given number.
324 -prefix
326 Text prefix for numbering.
327 Example:
329 # Start with Roman Numerals
331 $pdf->pageLabel(0, {
332 -style => 'roman',
333 });
334 # Switch to Arabic
336 $pdf->pageLabel(4, {
337 -style => 'decimal',
338 });
339 # Numbering for Appendix A
341 $pdf->pageLabel(32, {
342 -start => 1,
343 -prefix => 'A-'
344 });
345 # Numbering for Appendix B
347 $pdf->pageLabel( 36, {
348 -start => 1,
349 -prefix => 'B-'
350 });
351 # Numbering for the Index
353 $pdf->pageLabel(40, {
354 -style => 'Roman'
355 -start => 1,
356 -prefix => 'Index '
357 });
358 $pdf->finishobjects(@objects)
360 Force objects to be written to file if possible.
361 Example:
363 $pdf = PDF::Builder->new(-file => 'our/new.pdf');
365 ...
366 $pdf->finishobjects($page, $gfx, $txt);
367 ...
368 $pdf->save();
369 $pdf->update()
371 Saves a previously opened document.
372 Example:
374 $pdf = PDF::Builder->open('our/to/be/updated.pdf');
376 ...
377 $pdf->update();
378 $pdf->saveas($file)
380 Save the document to $file and remove the object structure from
381 memory.
382 Caution: Although the object $pdf will still exist, it is no longer
384 usable for any purpose after invoking this method! You will receive
385 error messages about "can't call method new_obj on an undefined
386 value".
387 Example:
389 $pdf = PDF::Builder->new();
391 ...
392 $pdf->saveas('our/new.pdf');
393 $pdf->save()
395 Save the document to an already-defined file (or filename) and
396 remove the object structure from memory.
397 Caution: Although the object $pdf will still exist, it is no longer
399 usable for any purpose after invoking this method! You will receive
400 error messages about "can't call method new_obj on an undefined
401 value".
402 Example:
404 $pdf = PDF::Builder->new(-file => 'file_to_output');
406 ...
407 $pdf->save();
408 $string = $pdf->stringify()
410 Return the document as a string and remove the object structure
411 from memory.
412 Caution: Although the object $pdf will still exist, it is no longer
414 usable for any purpose after invoking this method! You will receive
415 error messages about "can't call method new_obj on an undefined
416 value".
417 Example:
419 $pdf = PDF::Builder->new();
421 ...
422 print $pdf->stringify();
423 $pdf->end()
425 Remove the object structure from memory. PDF::Builder contains
426 circular references, so this call is necessary in long-running
427 processes to keep from running out of memory.
428 This will be called automatically when you save or stringify a PDF.
430 You should only need to call it explicitly if you are reading PDF
431 files and not writing them.
432
434 $page = $pdf->page()
435 $page = $pdf->page($page_number)
436 Returns a new page object. By default, the page is added to the
437 end of the document. If you give an existing page number, the new
438 page will be inserted in that position, pushing existing pages back
439 by 1 (e.g., page(5) would insert an empty page 5, with the old page
440 5 now page 6, etc.
441 If $page_number is -1, the new page is inserted as the second-last
443 page; if $page_number is 0, the new page is inserted as the last
444 page.
445 Example:
447 $pdf = PDF::Builder->new();
449 # Add a page. This becomes page 1.
451 $page = $pdf->page();
452 # Add a new first page. $page becomes page 2.
454 $another_page = $pdf->page(1);
455 $page = $pdf->open_page($page_number)
457 Returns the PDF::Builder::Page object of page $page_number. This
458 is similar to "$page = $pdf->page()", except that $page is not a
459 new, empty page; but contains the contents of that existing page.
460 If $page_number is 0 or -1, it will return the last page in the
462 document.
463 Example:
465 $pdf = PDF::Builder->open('our/99page.pdf');
467 $page = $pdf->open_page(1); # returns the first page
468 $page = $pdf->open_page(99); # returns the last page
469 $page = $pdf->open_page(-1); # returns the last page
470 $page = $pdf->open_page(999); # returns undef
471 $page = $pdf->openpage($page_number)
473 Deprecated. Will be removed on or after June, 2023. Use "open_page"
474 call instead.
475 $xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)
477 Returns a Form XObject created by extracting the specified page
478 from $source_pdf.
479 This is useful if you want to transpose the imported page somewhat
481 differently onto a page (e.g. two-up, four-up, etc.).
482 If $source_page_number is 0 or -1, it will return the last page in
484 the document.
485 Example:
487 $pdf = PDF::Builder->new();
489 $old = PDF::Builder->open('our/old.pdf');
490 $page = $pdf->page();
491 $gfx = $page->gfx();
492 # Import Page 2 from the old PDF
494 $xo = $pdf->importPageIntoForm($old, 2);
495 # Add it to the new PDF's first page at 1/2 scale
497 $gfx->formimage($xo, 0, 0, 0.5);
498 $pdf->saveas('our/new.pdf');
500 Note: You can only import a page from an existing PDF file.
502 $page = $pdf->import_page($source_pdf)
504 $page = $pdf->import_page($source_pdf, $source_page_number)
505 $page = $pdf->import_page($source_pdf, $source_page_number,
506 $target_page_number)
507 $page = $pdf->import_page($source_pdf, $source_page_number,
508 $target_page_object)
509 Imports a page from $source_pdf and adds it to the specified
510 position in $pdf.
511 If the $source_page_number is omitted, 0, or -1; the last page of
513 the source is imported. If the $target_page_number is omitted, 0,
514 or -1; the imported page will be placed as the new last page of the
515 target ($pdf). Otherwise, as with the "page()" method, the page
516 will be inserted before an existing page of that number.
517 Note: If you pass a page object instead of a page number for
519 $target_page_number, the contents of the page will be merged into
520 the existing page.
521 Example:
523 $pdf = PDF::Builder->new();
525 $old = PDF::Builder->open('our/old.pdf');
526 # Add page 2 from the old PDF as page 1 of the new PDF
528 $page = $pdf->import_page($old, 2);
529 $pdf->saveas('our/new.pdf');
531 Note: You can only import a page from an existing PDF file.
533 $count = $pdf->pages()
535 Returns the number of pages in the document.
536 $pdf->userunit($value)
538 Sets the global UserUnit, defining the scale factor to multiply any
539 size or coordinate by. For example, "userunit(72)" results in a
540 User Unit of 72 points, or 1 inch.
541 See "User Units" in PDF::Builder::Docs for more information.
543 $pdf->mediabox($name)
545 $pdf->mediabox($name, -orient => 'orientation')
546 $pdf->mediabox($w,$h)
547 $pdf->mediabox($llx,$lly, $urx,$ury)
548 ($llx,$lly, $urx,$ury) = $pdf->mediabox()
549 Sets (or gets) the global MediaBox, defining the width and height
550 (or by corner coordinates, or by standard name) of the output page
551 itself, such as the physical paper size.
552 See "Media Box" in PDF::Builder::Docs for more information. The
554 method always returns the current bounds (after any set operation).
555 $pdf->cropbox($name)
557 $pdf->cropbox($name, -orient => 'orientation')
558 $pdf->cropbox($w,$h)
559 $pdf->cropbox($llx,$lly, $urx,$ury)
560 ($llx,$lly, $urx,$ury) = $pdf->cropbox()
561 Sets (or gets) the global CropBox. This will define the media size
562 to which the output will later be clipped.
563 See "Crop Box" in PDF::Builder::Docs for more information. The
565 method always returns the current bounds (after any set operation).
566 $pdf->bleedbox($name)
568 $pdf->bleedbox($name, -orient => 'orientation')
569 $pdf->bleedbox($w,$h)
570 $pdf->bleedbox($llx,$lly, $urx,$ury)
571 ($llx,$lly, $urx,$ury) = $pdf->bleedbox()
572 Sets (or gets) the global BleedBox. This is typically used for hard
573 copy printing where you want ink to go to the edge of the cut
574 paper.
575 See "Bleed Box" in PDF::Builder::Docs for more information. The
577 method always returns the current bounds (after any set operation).
578 $pdf->trimbox($name)
580 $pdf->trimbox($name, -orient => 'orientation')
581 $pdf->trimbox($w,$h)
582 $pdf->trimbox($llx,$lly, $urx,$ury)
583 ($llx,$lly, $urx,$ury) = $pdf->trimbox()
584 Sets (or gets) the global TrimBox. This is supposed to be the
585 actual dimensions of the finished page (after trimming of the
586 paper).
587 See "Trim Box" in PDF::Builder::Docs for more information. The
589 method always returns the current bounds (after any set operation).
590 $pdf->artbox($name)
592 $pdf->artbox($name, -orient => 'orientation')
593 $pdf->artbox($w,$h)
594 $pdf->artbox($llx,$lly, $urx,$ury)
595 ($llx,$lly, $urx,$ury) = $pdf->artbox()
596 Sets (or gets) the global ArtBox. This is supposed to define "the
597 extent of the page's meaningful content".
598 See "Art Box" in PDF::Builder::Docs for more information. The
600 method always returns the current bounds (after any set operation).
601
603 @directories = PDF::Builder::addFontDirs($dir1, $dir2, ...)
604 Adds one or more directories to the search path for finding font
605 files.
606 Returns the list of searched directories.
608 $font = $pdf->corefont($fontname, %options)
610 $font = $pdf->corefont($fontname)
611 Returns a new Adobe core font object. For details, see "Core Fonts"
612 in PDF::Builder::Docs.
613 See also PDF::Builder::Resource::Font::CoreFont.
615 $font = $pdf->psfont($ps_file, %options)
617 $font = $pdf->psfont($ps_file)
618 Returns a new Adobe Type1 ("PostScript") font object. For details,
619 see "PS Fonts" in PDF::Builder::Docs.
620 See also PDF::Builder::Resource::Font::Postscript.
622 $font = $pdf->ttfont($ttf_file, %options)
624 $font = $pdf->ttfont($ttf_file)
625 Returns a new TrueType (or OpenType) font object. For details, see
626 "TrueType Fonts" in PDF::Builder::Docs.
627 $font = $pdf->cjkfont($cjkname, %options)
629 $font = $pdf->cjkfont($cjkname)
630 Returns a new CJK font object. These are TrueType-like fonts for
631 East Asian languages (Chinese, Japanese, Korean). For details, see
632 "CJK Fonts" in PDF::Builder::Docs.
633 See also PDF::Builder::Resource::CIDFont::CJKFont
635 $font = $pdf->synfont($basefont, %options)
637 $font = $pdf->synfont($basefont)
638 Returns a new synthetic font object. These are modifications to a
639 core (or PS/T1 or TTF/OTF) font, where the font may be replaced by
640 a Type1 or Type3 PostScript font. This does not appear to work
641 with CJK fonts (created with "cjkfont" method). For details, see
642 "Synthetic Fonts" in PDF::Builder::Docs.
643 See also PDF::Builder::Resource::Font::SynFont
645 $font = $pdf->bdfont($bdf_file, @options)
647 $font = $pdf->bdfont($bdf_file)
648 Returns a new BDF (bitmapped distribution format) font object,
649 based on the specified Adobe BDF file.
650 See also PDF::Builder::Resource::Font::BdFont
652 $font = $pdf->unifont(@fontspecs, %options)
654 $font = $pdf->unifont(@fontspecs)
655 Returns a new uni-font object, based on the specified fonts and
656 options.
657 BEWARE: This is not a true PDF-object, but a virtual/abstract font
659 definition!
660 See also PDF::Builder::Resource::UniFont.
662 Valid %options are:
664 -encode
666 Changes the encoding of the font from its default.
667
669 $jpeg = $pdf->image_jpeg($file)
670 Imports and returns a new JPEG image object. $file may be either a
671 filename or a filehandle.
672 See PDF::Builder::Resource::XObject::Image::JPEG for additional
674 information and "examples/Content.pl" for some examples of placing
675 an image on a page.
676 $tiff = $pdf->image_tiff($file, %opts)
678 $tiff = $pdf->image_tiff($file)
679 Imports and returns a new TIFF image object. $file may be either a
680 filename or a filehandle. For details, see "TIFF Images" in
681 PDF::Builder::Docs.
682 See PDF::Builder::Resource::XObject::Image::TIFF and
684 PDF::Builder::Resource::XObject::Image::TIFF_GT for additional
685 information and "examples/Content.pl" for some examples of placing
686 an image on a page (JPEG, but the principle is the same). There is
687 an optional TIFF library described, that gives more capability than
688 the default one.
689 $rc = $pdf->LA_GT()
691 Returns 1 if the library name (package) Graphics::TIFF is
692 installed, and 0 otherwise. For this optional library, this call
693 can be used to know if it is safe to use certain functions. For
694 example:
695 if ($pdf->LA_GT() {
697 # is installed and usable
698 } else {
699 # not available. you will be running the old, pure PERL code
700 }
701 $pnm = $pdf->image_pnm($file)
703 Imports and returns a new PNM image object. $file may be either a
704 filename or a filehandle.
705 See "examples/Content.pl" for some examples of placing an image on
707 a page (JPEG, but the principle is the same).
708 $png = $pdf->image_png($file, %options)
710 $png = $pdf->image_png($file)
711 Imports and returns a new PNG image object. $file may be either a
712 filename or a filehandle. For details, see "PNG Images" in
713 PDF::Builder::Docs.
714 See PDF::Builder::Resource::XObject::Image::PNG and
716 PDF::Builder::Resource::XObject::Image::PNG_IPL for additional
717 information and "examples/Content.pl" for some examples of placing
718 an image on a page (JPEG, but the principle is the same). There is
719 an optional PNG library (PNG_IPL) described, that gives more
720 capability than the default one.
721 $rc = $pdf->LA_IPL()
723 Returns 1 if the library name (package) Image::PNG::Libpng is
724 installed, and 0 otherwise. For this optional library, this call
725 can be used to know if it is safe to use certain functions. For
726 example:
727 if ($pdf->LA_IPL() {
729 # is installed and usable
730 } else {
731 # not available. don't use 16bps or interlaced PNG image files
732 }
733 $gif = $pdf->image_gif($file)
735 Imports and returns a new GIF image object. $file may be either a
736 filename or a filehandle.
737 See PDF::Builder::Resource::XObject::Image::GIF for additional
739 information and "examples/Content.pl" for some examples of placing
740 an image on a page (JPEG, but the principle is the same).
741 $gdf = $pdf->image_gd($gd_object, %options)
743 $gdf = $pdf->image_gd($gd_object)
744 Imports and returns a new image object from Image::GD.
745 Valid %options are:
747 -lossless => 1
749 Use lossless compression.
750 See PDF::Builder::Resource::XObject::Image::GD for additional
752 information and "examples/Content.pl" for some examples of placing
753 an image on a page (JPEG, but the principle is the same).
754
756 $cs = $pdf->colorspace_act($file)
757 Returns a new colorspace object based on an Adobe Color Table file.
758 See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a
760 reference to the file format's specification.
761 $cs = $pdf->colorspace_web()
763 Returns a new colorspace-object based on the "web-safe" color
764 palette.
765 $cs = $pdf->colorspace_hue()
767 Returns a new colorspace-object based on the hue color palette.
768 See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an
770 explanation.
771 $cs = $pdf->colorspace_separation($tint, $color)
773 Returns a new separation colorspace object based on the parameters.
774 $tint can be any valid ink identifier, including but not limited
776 to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
777 'Orange'.
778 $color must be a valid color specification limited to: '#rrggbb',
780 '!hhssvv', '%ccmmyykk' or a "named color" (rgb).
781 The colorspace model will automatically be chosen based on the
783 specified color.
784 $cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
786 $cs = $pdf->colorspace_devicen(\@tintCSx)
787 Returns a new DeviceN colorspace object based on the parameters.
788 Example:
790 $cy = $pdf->colorspace_separation('Cyan', '%f000');
792 $ma = $pdf->colorspace_separation('Magenta', '%0f00');
793 $ye = $pdf->colorspace_separation('Yellow', '%00f0');
794 $bk = $pdf->colorspace_separation('Black', '%000f');
795 $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
797 $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
799 The colorspace model will automatically be chosen based on the
801 first colorspace specified.
802
804 These are glue routines to the actual barcode rendering routines found
805 elsewhere.
806 $bc = $pdf->xo_codabar(%options)
808 $bc = $pdf->xo_code128(%options)
809 $bc = $pdf->xo_2of5int(%options)
810 $bc = $pdf->xo_3of9(%options)
811 $bc = $pdf->xo_ean13(%options)
812 Creates the specified barcode object as a form XObject.
813
815 $xo = $pdf->xo_form()
816 Returns a new form XObject.
817 $egs = $pdf->egstate()
819 Returns a new extended graphics state object.
820 $obj = $pdf->pattern(%options)
822 $obj = $pdf->pattern()
823 Returns a new pattern object.
824 $obj = $pdf->shading(%options)
826 $obj = $pdf->shading()
827 Returns a new shading object.
828 $otls = $pdf->outlines()
830 Returns a new or existing outlines object.
831 $ndest = $pdf->named_destination()
833 Returns a new or existing named destination object.
834perl v5.34.0 2022-01-21 PDF::Builder(3)