1PDF::Builder(3)       User Contributed Perl Documentation      PDF::Builder(3)
2
3
4

NAME

6       PDF::Builder - Facilitates the creation and modification of PDF files
7

SYNOPSIS

9           use PDF::Builder;
10
11           # Create a blank PDF file
12           $pdf = PDF::Builder->new();
13
14           # Open an existing PDF file
15           $pdf = PDF::Builder->open('some.pdf');
16
17           # Add a blank page
18           $page = $pdf->page();
19
20           # Retrieve an existing page
21           $page = $pdf->open_page($page_number);
22
23           # Set the page size
24           $page->mediabox('Letter');
25
26           # Add a built-in font to the PDF
27           $font = $pdf->corefont('Helvetica-Bold');
28
29           # Add an external TTF font to the PDF
30           $font = $pdf->ttfont('/path/to/font.ttf');
31
32           # 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
38           # Save the PDF
39           $pdf->saveas('/path/to/new.pdf');
40

SOME SPECIAL NOTES

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
46   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
51   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
57   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
62   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
67   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
72   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
79       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
84       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
90   KNOWN ISSUES
91       This module does not work with perl's -l command-line switch.
92
93       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
99   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

AUTHOR

105       PDF::API2 was originally written by Alfred Reibenschuh. See the HISTORY
106       section for more information.
107
108       It was maintained by Steve Simms.
109
110       PDF::Builder is currently being maintained by Phil M. Perry.
111
112   SUPPORT
113       The full source is on https://github.com/PhilterPaper/Perl-PDF-Builder.
114
115       The release distribution is on CPAN:
116       https://metacpan.org/pod/PDF::Builder.
117
118       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
124       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

LICENSE

132       This software is Copyright (c) 2017-2021 by Phil M. Perry.
133
134       This is free software, licensed under:
135
136       The GNU Lesser General Public License (LGPL) Version 2.1, February 1999
137
138         (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
141       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
145       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
150       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
155       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

GENERIC METHODS

161       $pdf = PDF::Builder->new(%options)
162       $pdf = PDF::Builder->new()
163           Creates a new PDF object.
164
165           Options
166
167           -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
172           -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
177           -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
184           -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
191           -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
197           Example:
198
199               $pdf = PDF::Builder->new();
200               ...
201               print $pdf->stringify();
202
203               $pdf = PDF::Builder->new(-compress => 'none');
204               # equivalent to $pdf->{'forcecompress'} = 'none'; (or older, 0)
205
206               $pdf = PDF::Builder->new();
207               ...
208               $pdf->saveas('our/new.pdf');
209
210               $pdf = PDF::Builder->new(-file => 'our/new.pdf');
211               ...
212               $pdf->save();
213
214       $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
218           Example:
219
220               $pdf = PDF::Builder->open('our/old.pdf');
221               ...
222               $pdf->saveas('our/new.pdf');
223
224               $pdf = PDF::Builder->open('our/to/be/updated.pdf');
225               ...
226               $pdf->update();
227
228       $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
232           -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
237           Example:
238
239               # 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
244               $pdf = PDF::Builder->open_scalar($pdf_string);
245               ...
246               $pdf->saveas('our/new.pdf');
247
248       $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
254       $val = $pdf->default($parameter)
255       $pdf->default($parameter, $value)
256           Gets/sets the default value for a behavior of PDF::Builder.
257
258           Supported Parameters:
259
260           nounrotate
261               prohibits Builder from rotating imported/opened page to re-
262               create a default pdf-context.
263
264           pageencaps
265               enables Builder's adding save/restore commands upon
266               importing/opening pages to preserve graphics-state for
267               modification.
268
269           copyannots
270               enables importing of annotations (*EXPERIMENTAL*).
271
272           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
277       $version = $pdf->version($new_version)
278       $version = $pdf->version()
279           Get/set the PDF version (e.g. 1.4).
280
281           For compatibility with earlier releases, if no decimal point is
282           given, assume "1." precedes the number given.
283
284           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
288       $bool = $pdf->isEncrypted()
289           Checks if the previously opened PDF is encrypted.
290
291       %infohash = $pdf->info(%infohash)
292           Gets/sets the info structure of the document.
293
294           See "info Example" in PDF::Builder::Docs section for an example of
295           the use of this method.
296
297       @metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)
298           Gets/sets the supported info-structure tags.
299
300           Example:
301
302               @attributes = $pdf->infoMetaAttributes;
303               print "Supported Attributes: @attr\n";
304
305               @attributes = $pdf->infoMetaAttributes('CustomField1');
306               print "Supported Attributes: @attributes\n";
307
308       $xml = $pdf->xmpMetadata($xml)
309           Gets/sets the XMP XML data stream.
310
311           See "XMP XML example" in PDF::Builder::Docs section for an example
312           of the use of this method.
313
314       $pdf->pageLabel($index, $options)
315           Sets page label options.
316
317           Supported Options:
318
319           -style
320               Roman, roman, decimal, Alpha or alpha.
321
322           -start
323               Restart numbering at given number.
324
325           -prefix
326               Text prefix for numbering.
327
328           Example:
329
330               # Start with Roman Numerals
331               $pdf->pageLabel(0, {
332                   -style => 'roman',
333               });
334
335               # Switch to Arabic
336               $pdf->pageLabel(4, {
337                   -style => 'decimal',
338               });
339
340               # Numbering for Appendix A
341               $pdf->pageLabel(32, {
342                   -start => 1,
343                   -prefix => 'A-'
344               });
345
346               # Numbering for Appendix B
347               $pdf->pageLabel( 36, {
348                   -start => 1,
349                   -prefix => 'B-'
350               });
351
352               # Numbering for the Index
353               $pdf->pageLabel(40, {
354                   -style => 'Roman'
355                   -start => 1,
356                   -prefix => 'Index '
357               });
358
359       $pdf->finishobjects(@objects)
360           Force objects to be written to file if possible.
361
362           Example:
363
364               $pdf = PDF::Builder->new(-file => 'our/new.pdf');
365               ...
366               $pdf->finishobjects($page, $gfx, $txt);
367               ...
368               $pdf->save();
369
370       $pdf->update()
371           Saves a previously opened document.
372
373           Example:
374
375               $pdf = PDF::Builder->open('our/to/be/updated.pdf');
376               ...
377               $pdf->update();
378
379       $pdf->saveas($file)
380           Save the document to $file and remove the object structure from
381           memory.
382
383           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
388           Example:
389
390               $pdf = PDF::Builder->new();
391               ...
392               $pdf->saveas('our/new.pdf');
393
394       $pdf->save()
395           Save the document to an already-defined file (or filename) and
396           remove the object structure from memory.
397
398           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
403           Example:
404
405               $pdf = PDF::Builder->new(-file => 'file_to_output');
406               ...
407               $pdf->save();
408
409       $string = $pdf->stringify()
410           Return the document as a string and remove the object structure
411           from memory.
412
413           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
418           Example:
419
420               $pdf = PDF::Builder->new();
421               ...
422               print $pdf->stringify();
423
424       $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
429           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

PAGE METHODS

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
442           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
446           Example:
447
448               $pdf = PDF::Builder->new();
449
450               # Add a page.  This becomes page 1.
451               $page = $pdf->page();
452
453               # Add a new first page.  $page becomes page 2.
454               $another_page = $pdf->page(1);
455
456       $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
461           If $page_number is 0 or -1, it will return the last page in the
462           document.
463
464           Example:
465
466               $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
472       $page = $pdf->openpage($page_number)
473           Deprecated. Will be removed on or after June, 2023. Use "open_page"
474           call instead.
475
476       $xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)
477           Returns a Form XObject created by extracting the specified page
478           from $source_pdf.
479
480           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
483           If $source_page_number is 0 or -1, it will return the last page in
484           the document.
485
486           Example:
487
488               $pdf = PDF::Builder->new();
489               $old = PDF::Builder->open('our/old.pdf');
490               $page = $pdf->page();
491               $gfx = $page->gfx();
492
493               # Import Page 2 from the old PDF
494               $xo = $pdf->importPageIntoForm($old, 2);
495
496               # Add it to the new PDF's first page at 1/2 scale
497               $gfx->formimage($xo, 0, 0, 0.5);
498
499               $pdf->saveas('our/new.pdf');
500
501           Note: You can only import a page from an existing PDF file.
502
503       $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
512           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
518           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
522           Example:
523
524               $pdf = PDF::Builder->new();
525               $old = PDF::Builder->open('our/old.pdf');
526
527               # Add page 2 from the old PDF as page 1 of the new PDF
528               $page = $pdf->import_page($old, 2);
529
530               $pdf->saveas('our/new.pdf');
531
532           Note: You can only import a page from an existing PDF file.
533
534       $count = $pdf->pages()
535           Returns the number of pages in the document.
536
537       $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
542           See "User Units" in PDF::Builder::Docs for more information.
543
544       $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
553           See "Media Box" in PDF::Builder::Docs for more information.  The
554           method always returns the current bounds (after any set operation).
555
556       $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
564           See "Crop Box" in PDF::Builder::Docs for more information.  The
565           method always returns the current bounds (after any set operation).
566
567       $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
576           See "Bleed Box" in PDF::Builder::Docs for more information.  The
577           method always returns the current bounds (after any set operation).
578
579       $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
588           See "Trim Box" in PDF::Builder::Docs for more information.  The
589           method always returns the current bounds (after any set operation).
590
591       $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
599           See "Art Box" in PDF::Builder::Docs for more information.  The
600           method always returns the current bounds (after any set operation).
601

FONT METHODS

603       @directories = PDF::Builder::addFontDirs($dir1, $dir2, ...)
604           Adds one or more directories to the search path for finding font
605           files.
606
607           Returns the list of searched directories.
608
609       $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
614           See also PDF::Builder::Resource::Font::CoreFont.
615
616       $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
621           See also PDF::Builder::Resource::Font::Postscript.
622
623       $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
628       $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
634           See also PDF::Builder::Resource::CIDFont::CJKFont
635
636       $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
644           See also PDF::Builder::Resource::Font::SynFont
645
646       $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
651           See also PDF::Builder::Resource::Font::BdFont
652
653       $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
658           BEWARE: This is not a true PDF-object, but a virtual/abstract font
659           definition!
660
661           See also PDF::Builder::Resource::UniFont.
662
663           Valid %options are:
664
665           -encode
666               Changes the encoding of the font from its default.
667

IMAGE METHODS

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
673           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
677       $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
683           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
690       $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
696               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
702       $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
706           See "examples/Content.pl" for some examples of placing an image on
707           a page (JPEG, but the principle is the same).
708
709       $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
715           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
722       $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
728               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
734       $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
738           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
742       $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
746           Valid %options are:
747
748           -lossless => 1
749               Use lossless compression.
750
751           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

COLORSPACE METHODS

756       $cs = $pdf->colorspace_act($file)
757           Returns a new colorspace object based on an Adobe Color Table file.
758
759           See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a
760           reference to the file format's specification.
761
762       $cs = $pdf->colorspace_web()
763           Returns a new colorspace-object based on the "web-safe" color
764           palette.
765
766       $cs = $pdf->colorspace_hue()
767           Returns a new colorspace-object based on the hue color palette.
768
769           See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an
770           explanation.
771
772       $cs = $pdf->colorspace_separation($tint, $color)
773           Returns a new separation colorspace object based on the parameters.
774
775           $tint can be any valid ink identifier, including but not limited
776           to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
777           'Orange'.
778
779           $color must be a valid color specification limited to: '#rrggbb',
780           '!hhssvv', '%ccmmyykk' or a "named color" (rgb).
781
782           The colorspace model will automatically be chosen based on the
783           specified color.
784
785       $cs = $pdf->colorspace_devicen(\@tintCSx, $samples)
786       $cs = $pdf->colorspace_devicen(\@tintCSx)
787           Returns a new DeviceN colorspace object based on the parameters.
788
789           Example:
790
791               $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
796               $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
797
798               $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
799
800           The colorspace model will automatically be chosen based on the
801           first colorspace specified.
802

BARCODE METHODS

804       These are glue routines to the actual barcode rendering routines found
805       elsewhere.
806
807       $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

OTHER METHODS

815       $xo = $pdf->xo_form()
816           Returns a new form XObject.
817
818       $egs = $pdf->egstate()
819           Returns a new extended graphics state object.
820
821       $obj = $pdf->pattern(%options)
822       $obj = $pdf->pattern()
823           Returns a new pattern object.
824
825       $obj = $pdf->shading(%options)
826       $obj = $pdf->shading()
827           Returns a new shading object.
828
829       $otls = $pdf->outlines()
830           Returns a new or existing outlines object.
831
832       $ndest = $pdf->named_destination()
833           Returns a new or existing named destination object.
834
835
836
837perl v5.34.0                      2021-07-22                   PDF::Builder(3)
Impressum