.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PDF::Builder 3pm"
.TH PDF::Builder 3pm "2021-03-28" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
PDF::Builder \- Facilitates the creation and modification of PDF files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use PDF::Builder;
\&
\&    # Create a blank PDF file
\&    $pdf = PDF::Builder\->new();
\&
\&    # Open an existing PDF file
\&    $pdf = PDF::Builder\->open(\*(Aqsome.pdf\*(Aq);
\&
\&    # Add a blank page
\&    $page = $pdf\->page();
\&
\&    # Retrieve an existing page
\&    $page = $pdf\->openpage($page_number);
\&
\&    # Set the page size
\&    $page\->mediabox(\*(AqLetter\*(Aq);
\&
\&    # Add a built\-in font to the PDF
\&    $font = $pdf\->corefont(\*(AqHelvetica\-Bold\*(Aq);
\&
\&    # Add an external TTF font to the PDF
\&    $font = $pdf\->ttfont(\*(Aq/path/to/font.ttf\*(Aq);
\&
\&    # Add some text to the page
\&    $text = $page\->text();
\&    $text\->font($font, 20);
\&    $text\->translate(200, 700);
\&    $text\->text(\*(AqHello World!\*(Aq);
\&
\&    # Save the PDF
\&    $pdf\->saveas(\*(Aq/path/to/new.pdf\*(Aq);
.Ve
.SH "SOME SPECIAL NOTES"
.IX Header "SOME SPECIAL NOTES"
See the file \s-1README\s0 (in downloadable package and on \s-1CPAN\s0) for a summary of 
prerequisites and tools needed to install PDF::Builder, both mandatory and 
optional.
.SS "\s-1SOFTWARE DEVELOPMENT KIT\s0"
.IX Subsection "SOFTWARE DEVELOPMENT KIT"
There are four levels of involvement with PDF::Builder. Depending on what you
want to do, different kinds of installs are recommended.
See \*(L"Software Development Kit\*(R" in PDF::Builder::Docs for suggestions.
.SS "\s-1OPTIONAL LIBRARIES\s0"
.IX Subsection "OPTIONAL LIBRARIES"
PDF::Builder can make use of some optional libraries, which are not \fIrequired\fR
for a successful installation, but improve speed and capabilities. See 
\&\*(L"Optional Libraries\*(R" in PDF::Builder::Docs for more information.
.SS "\s-1STRINGS\s0 (\s-1CHARACTER TEXT\s0)"
.IX Subsection "STRINGS (CHARACTER TEXT)"
There are some things you should know about character encoding (for text),
before you dive in to coding. Please go to \*(L"Strings (Character Text)\*(R" in PDF::Builder::Docs and have a read.
.SS "\s-1RENDERING ORDER\s0"
.IX Subsection "RENDERING ORDER"
Invoking \*(L"text\*(R" and \*(L"graphics\*(R" methods can lead to unexpected results (a 
different ordering of output than intended). See \*(L"Rendering Order\*(R" in PDF::Builder::Docs for more information.
.SS "\s-1PDF VERSIONS SUPPORTED\s0"
.IX Subsection "PDF VERSIONS SUPPORTED"
PDF::Builder is mostly \s-1PDF 1\s0.4\-compliant, but there \fIare\fR complications you
should be aware of. Please read \*(L"\s-1PDF\s0 Versions Supported\*(R" in PDF::Builder::Docs
for details.
.SS "\s-1SUPPORTED PERL VERSIONS\s0"
.IX Subsection "SUPPORTED PERL VERSIONS"
PDF::Builder intends to support all major Perl versions that were released in
the past six years, plus one, in order to continue working for the life of
most long-term-stable (\s-1LTS\s0) server distributions.
See the <https://www.cpan.org/src/> table 
\&\fBFirst release in each branch of Perl\fR x.xxxx0 \*(L"Major\*(R" release dates.
.PP
For example, a version of PDF::Builder released on 2018\-06\-05 would support 
the last major version of Perl released \fIon or after\fR 2012\-06\-05 (5.18), and 
then one before that, which would be 5.16. Alternatively, the last major 
version of Perl released \fIbefore\fR 2012\-06\-05 is 5.16.
.PP
The intent is to avoid expending unnecessary effort in supporting very old
(obsolete) versions of Perl.
If you need to use this module on a server with an extremely out-of-date version
of Perl, consider using either plenv or Perlbrew to run a newer version of Perl
without needing admin privileges.
.SS "\s-1KNOWN ISSUES\s0"
.IX Subsection "KNOWN ISSUES"
This module does not work with perl's \-l command-line switch.
.PP
There is a file \s-1INFO/KNOWN_INCOMP\s0 which lists known incompatibilities with 
\&\s-1PDF::API2,\s0 in case you're thinking of porting over something from that world, 
or have experience there and want to try PDF::Builder. There is also a file 
\&\s-1INFO/DEPRECATED,\s0 which lists things which are planned to be removed at some 
point.
.SS "\s-1HISTORY\s0"
.IX Subsection "HISTORY"
The history of PDF::Builder is a complex and exciting saga... \s-1OK,\s0 it may be
mildly interesting. Have a look at \*(L"History\*(R" in PDF::Builder::Docs section.
.SH "AUTHOR"
.IX Header "AUTHOR"
\&\s-1PDF::API2\s0 was originally written by Alfred Reibenschuh. See the \s-1HISTORY\s0 section
for more information.
.PP
It was maintained by Steve Simms.
.PP
PDF::Builder is currently being maintained by Phil M. Perry.
.SS "\s-1SUPPORT\s0"
.IX Subsection "SUPPORT"
The full source is on https://github.com/PhilterPaper/Perl\-PDF\-Builder.
.PP
The release distribution is on \s-1CPAN:\s0 https://metacpan.org/pod/PDF::Builder.
.PP
Bug reports are on https://github.com/PhilterPaper/Perl\-PDF\-Builder/issues?q=is%3Aissue+sort%3Aupdated\-desc (with \*(L"bug\*(R" label), feature requests have an \*(L"enhancement\*(R" label, and general discussions (architecture, roadmap, etc.) have a \*(L"general discussion\*(R" label.
.PP
Do \fBnot\fR under \fIany\fR circumstances open a \s-1PR\s0 (Pull Request) to report a bug. It is a waste of both your and our time and effort. Open a regular ticket (issue), and attach a Perl (.pl) program illustrating the problem, if possible. If you believe that you have a program patch, and offer to share it as a \s-1PR,\s0 we may give the go-ahead. Unsolicited PRs may be closed without further action.
.SH "LICENSE"
.IX Header "LICENSE"
This software is Copyright (c) 2017\-2020 by Phil M. Perry.
.PP
This is free software, licensed under:
.PP
The \s-1GNU\s0 Lesser General Public License (\s-1LGPL\s0) Version 2.1, February 1999
.PP
.Vb 2
\&  (The master copy of this license lives on the GNU website.)
\&  (A copy is provided in the INFO/LICENSE file for your convenience.)
.Ve
.PP
This section of Builder.pm is intended only as a very brief summary 
of the license; please consider \s-1INFO/LICENSE\s0 to be the controlling version, 
if there is any conflict or ambiguity between the two.
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 Lesser General Public License, as published by the Free
Software Foundation, either version 2.1 of the License, or (at your option) any
later version of this license.
.PP
\&\s-1NOTE:\s0 there are several files in this distribution which were incorporated from
outside sources and carry different licenses. If a file states that it is under 
a license different than \s-1LGPL 2.1,\s0 that license and its terms will apply to 
that file, and not \s-1LGPL 2.1.\s0
.PP
This library is distributed in the hope that it will be useful, but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0 See the \s-1GNU\s0 Lesser General Public License for more details.
.SH "GENERIC METHODS"
.IX Header "GENERIC METHODS"
.ie n .IP "$pdf = PDF::Builder\->new(%options)" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->new(%options)" 4
.IX Item "$pdf = PDF::Builder->new(%options)"
.PD 0
.ie n .IP "$pdf = PDF::Builder\->\fBnew()\fR" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->\fBnew()\fR" 4
.IX Item "$pdf = PDF::Builder->new()"
.PD
Creates a new \s-1PDF\s0 object.
.Sp
\&\fBOptions\fR
.RS 4
.IP "\-file" 4
.IX Item "-file"
If you will be saving it as a file and
already know the filename, you can give the '\-file' option to minimize
possible memory requirements later on.
.IP "\-compress" 4
.IX Item "-compress"
The '\-compress' option can be
given to specify stream compression: default is 'flate', 'none' is no
compression. No other compression methods are currently supported.
.IP "\-outver" 4
.IX Item "-outver"
The '\-outver' option defaults to 1.4 as the output \s-1PDF\s0 version and the highest 
allowed feature version (attempts to use anything higher will give a warning).
If an existing \s-1PDF\s0 with a higher version is read in, \-outver will be increased 
to that version, with a warning.
.IP "\-msgver" 4
.IX Item "-msgver"
The '\-msgver' option value of 1 (default) gives a warning message if the 
\&'\-outver' \s-1PDF\s0 level has to be bumped up due to either a higher \s-1PDF\s0 level file 
being read in, or a higher level feature was requested. A value of 0 
suppresses the warning message.
.IP "\-diaglevel" 4
.IX Item "-diaglevel"
The '\-diaglevel' option can be
given to specify the level of diagnostics given by \fBIntegrityCheck()\fR. The
default is level 2 (errors and warnings). 
See \*(L"IntegrityCheck\*(R" in PDF::Builder::Docs for more information.
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    print $pdf\->stringify();
\&
\&    $pdf = PDF::Builder\->new(\-compress => \*(Aqnone\*(Aq);
\&    # equivalent to $pdf\->{\*(Aqforcecompress\*(Aq} = \*(Aqnone\*(Aq; (or older, 0)
\&
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::Builder\->new(\-file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->save();
.Ve
.RE
.ie n .IP "$pdf = PDF::Builder\->open($pdf_file, %options)" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->open($pdf_file, \f(CW%options\fR)" 4
.IX Item "$pdf = PDF::Builder->open($pdf_file, %options)"
.PD 0
.ie n .IP "$pdf = PDF::Builder\->open($pdf_file)" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->open($pdf_file)" 4
.IX Item "$pdf = PDF::Builder->open($pdf_file)"
.PD
Opens an existing \s-1PDF\s0 file. See \f(CW\*(C`new()\*(C'\fR for options.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->open(\*(Aqour/old.pdf\*(Aq);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
\&
\&    $pdf = PDF::Builder\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.ie n .IP "$pdf = PDF::Builder\->open_scalar($pdf_string, %options)" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->open_scalar($pdf_string, \f(CW%options\fR)" 4
.IX Item "$pdf = PDF::Builder->open_scalar($pdf_string, %options)"
.PD 0
.ie n .IP "$pdf = PDF::Builder\->open_scalar($pdf_string)" 4
.el .IP "\f(CW$pdf\fR = PDF::Builder\->open_scalar($pdf_string)" 4
.IX Item "$pdf = PDF::Builder->open_scalar($pdf_string)"
.PD
Opens a \s-1PDF\s0 contained in a string. See \f(CW\*(C`new()\*(C'\fR for other options.
.RS 4
.IP "\-diags => 1" 4
.IX Item "-diags => 1"
Display warnings when non-conforming \s-1PDF\s0 structure is found, and fix up
where possible. See PDF::Builder::Basic::PDF::File for more information.
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    # Read a PDF into a string, for the purpose of demonstration
\&    open $fh, \*(Aqour/old.pdf\*(Aq or die $@;
\&    undef $/;  # Read the whole file at once
\&    $pdf_string = <$fh>;
\&
\&    $pdf = PDF::Builder\->open_scalar($pdf_string);
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.RE
.ie n .IP "$pdf\->preferences(%options)" 4
.el .IP "\f(CW$pdf\fR\->preferences(%options)" 4
.IX Item "$pdf->preferences(%options)"
Controls viewing preferences for the \s-1PDF,\s0 including the \fBPage Mode\fR, 
\&\fBPage Layout\fR, \fBViewer\fR, and \fBInitial Page\fR Options. See 
\&\*(L"Preferences \- set user display preferences\*(R" in PDF::Builder::Docs for details on all these 
option groups.
.ie n .IP "$val = $pdf\->default($parameter)" 4
.el .IP "\f(CW$val\fR = \f(CW$pdf\fR\->default($parameter)" 4
.IX Item "$val = $pdf->default($parameter)"
.PD 0
.ie n .IP "$pdf\->default($parameter, $value)" 4
.el .IP "\f(CW$pdf\fR\->default($parameter, \f(CW$value\fR)" 4
.IX Item "$pdf->default($parameter, $value)"
.PD
Gets/sets the default value for a behavior of PDF::Builder.
.Sp
\&\fBSupported Parameters:\fR
.RS 4
.IP "nounrotate" 4
.IX Item "nounrotate"
prohibits Builder from rotating imported/opened page to re-create a
default pdf-context.
.IP "pageencaps" 4
.IX Item "pageencaps"
enables Builder's adding save/restore commands upon importing/opening
pages to preserve graphics-state for modification.
.IP "copyannots" 4
.IX Item "copyannots"
enables importing of annotations (\fB*EXPERIMENTAL*\fR).
.RE
.RS 4
.RE
.ie n .IP "$version = $pdf\->version($new_version)" 4
.el .IP "\f(CW$version\fR = \f(CW$pdf\fR\->version($new_version)" 4
.IX Item "$version = $pdf->version($new_version)"
.PD 0
.ie n .IP "$version = $pdf\->\fBversion()\fR" 4
.el .IP "\f(CW$version\fR = \f(CW$pdf\fR\->\fBversion()\fR" 4
.IX Item "$version = $pdf->version()"
.PD
Get/set the \s-1PDF\s0 version (e.g. 1.4).
.Sp
For compatibility with earlier releases, if no decimal point is given, assume
\&\*(L"1.\*(R" precedes the number given.
.Sp
A warning message is given if you attempt to \fIdecrease\fR the \s-1PDF\s0 version, as you
might have already read in a higher level file, or used a higher level feature.
.ie n .IP "$bool = $pdf\->\fBisEncrypted()\fR" 4
.el .IP "\f(CW$bool\fR = \f(CW$pdf\fR\->\fBisEncrypted()\fR" 4
.IX Item "$bool = $pdf->isEncrypted()"
Checks if the previously opened \s-1PDF\s0 is encrypted.
.ie n .IP "%infohash = $pdf\->info(%infohash)" 4
.el .IP "\f(CW%infohash\fR = \f(CW$pdf\fR\->info(%infohash)" 4
.IX Item "%infohash = $pdf->info(%infohash)"
Gets/sets the info structure of the document.
.Sp
See \*(L"info Example\*(R" in PDF::Builder::Docs section for an example of the use
of this method.
.ie n .IP "@metadata_attributes = $pdf\->infoMetaAttributes(@metadata_attributes)" 4
.el .IP "\f(CW@metadata_attributes\fR = \f(CW$pdf\fR\->infoMetaAttributes(@metadata_attributes)" 4
.IX Item "@metadata_attributes = $pdf->infoMetaAttributes(@metadata_attributes)"
Gets/sets the supported info-structure tags.
.Sp
\&\fBExample:\fR
.Sp
.Vb 2
\&    @attributes = $pdf\->infoMetaAttributes;
\&    print "Supported Attributes: @attr\en";
\&
\&    @attributes = $pdf\->infoMetaAttributes(\*(AqCustomField1\*(Aq);
\&    print "Supported Attributes: @attributes\en";
.Ve
.ie n .IP "$xml = $pdf\->xmpMetadata($xml)" 4
.el .IP "\f(CW$xml\fR = \f(CW$pdf\fR\->xmpMetadata($xml)" 4
.IX Item "$xml = $pdf->xmpMetadata($xml)"
Gets/sets the \s-1XMP XML\s0 data stream.
.Sp
See \*(L"\s-1XMP XML\s0 example\*(R" in PDF::Builder::Docs section for an example of the use
of this method.
.ie n .IP "$pdf\->pageLabel($index, $options)" 4
.el .IP "\f(CW$pdf\fR\->pageLabel($index, \f(CW$options\fR)" 4
.IX Item "$pdf->pageLabel($index, $options)"
Sets page label options.
.Sp
\&\fBSupported Options:\fR
.RS 4
.IP "\-style" 4
.IX Item "-style"
Roman, roman, decimal, Alpha or alpha.
.IP "\-start" 4
.IX Item "-start"
Restart numbering at given number.
.IP "\-prefix" 4
.IX Item "-prefix"
Text prefix for numbering.
.RE
.RS 4
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    # Start with Roman Numerals
\&    $pdf\->pageLabel(0, {
\&        \-style => \*(Aqroman\*(Aq,
\&    });
\&
\&    # Switch to Arabic
\&    $pdf\->pageLabel(4, {
\&        \-style => \*(Aqdecimal\*(Aq,
\&    });
\&
\&    # Numbering for Appendix A
\&    $pdf\->pageLabel(32, {
\&        \-start => 1,
\&        \-prefix => \*(AqA\-\*(Aq
\&    });
\&
\&    # Numbering for Appendix B
\&    $pdf\->pageLabel( 36, {
\&        \-start => 1,
\&        \-prefix => \*(AqB\-\*(Aq
\&    });
\&
\&    # Numbering for the Index
\&    $pdf\->pageLabel(40, {
\&        \-style => \*(AqRoman\*(Aq
\&        \-start => 1,
\&        \-prefix => \*(AqIndex \*(Aq
\&    });
.Ve
.RE
.ie n .IP "$pdf\->finishobjects(@objects)" 4
.el .IP "\f(CW$pdf\fR\->finishobjects(@objects)" 4
.IX Item "$pdf->finishobjects(@objects)"
Force objects to be written to file if possible.
.Sp
\&\fBExample:\fR
.Sp
.Vb 5
\&    $pdf = PDF::Builder\->new(\-file => \*(Aqour/new.pdf\*(Aq);
\&    ...
\&    $pdf\->finishobjects($page, $gfx, $txt);
\&    ...
\&    $pdf\->save();
.Ve
.ie n .IP "$pdf\->\fBupdate()\fR" 4
.el .IP "\f(CW$pdf\fR\->\fBupdate()\fR" 4
.IX Item "$pdf->update()"
Saves a previously opened document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->open(\*(Aqour/to/be/updated.pdf\*(Aq);
\&    ...
\&    $pdf\->update();
.Ve
.ie n .IP "$pdf\->saveas($file)" 4
.el .IP "\f(CW$pdf\fR\->saveas($file)" 4
.IX Item "$pdf->saveas($file)"
Save the document to \f(CW$file\fR and remove the object structure from memory.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.ie n .IP "$pdf\->\fBsave()\fR" 4
.el .IP "\f(CW$pdf\fR\->\fBsave()\fR" 4
.IX Item "$pdf->save()"
Save the document to an already-defined file (or filename) and 
remove the object structure from memory.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->new(\-file => \*(Aqfile_to_output\*(Aq);
\&    ...
\&    $pdf\->save();
.Ve
.ie n .IP "$string = $pdf\->\fBstringify()\fR" 4
.el .IP "\f(CW$string\fR = \f(CW$pdf\fR\->\fBstringify()\fR" 4
.IX Item "$string = $pdf->stringify()"
Return the document as a string and remove the object structure from memory.
.Sp
\&\fBCaution:\fR Although the object \f(CW$pdf\fR will still exist, it is no longer
usable for any purpose after invoking this method! You will receive error
messages about \*(L"can't call method new_obj on an undefined value\*(R".
.Sp
\&\fBExample:\fR
.Sp
.Vb 3
\&    $pdf = PDF::Builder\->new();
\&    ...
\&    print $pdf\->stringify();
.Ve
.ie n .IP "$pdf\->\fBend()\fR" 4
.el .IP "\f(CW$pdf\fR\->\fBend()\fR" 4
.IX Item "$pdf->end()"
Remove the object structure from memory. PDF::Builder contains circular
references, so this call is necessary in long-running processes to
keep from running out of memory.
.Sp
This will be called automatically when you save or stringify a \s-1PDF.\s0
You should only need to call it explicitly if you are reading \s-1PDF\s0
files and not writing them.
.SH "PAGE METHODS"
.IX Header "PAGE METHODS"
.ie n .IP "$page = $pdf\->\fBpage()\fR" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->\fBpage()\fR" 4
.IX Item "$page = $pdf->page()"
.PD 0
.ie n .IP "$page = $pdf\->page($page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->page($page_number)" 4
.IX Item "$page = $pdf->page($page_number)"
.PD
Returns a \fInew\fR page object.  By default, the page is added to the end
of the document.  If you give an existing page number, the new page
will be inserted in that position, pushing existing pages back by 1 (e.g., 
\&\f(CWpage(5)\fR would insert an empty page 5, with the old page 5 now page 6,
etc.
.Sp
If \f(CW$page_number\fR is \-1, the new page is inserted as the second-last page;
if \f(CW$page_number\fR is 0, the new page is inserted as the last page.
.Sp
\&\fBExample:\fR
.Sp
.Vb 1
\&    $pdf = PDF::Builder\->new();
\&
\&    # Add a page.  This becomes page 1.
\&    $page = $pdf\->page();
\&
\&    # Add a new first page.  $page becomes page 2.
\&    $another_page = $pdf\->page(1);
.Ve
.ie n .IP "$page = $pdf\->openpage($page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->openpage($page_number)" 4
.IX Item "$page = $pdf->openpage($page_number)"
Returns the PDF::Builder::Page object of page \f(CW$page_number\fR.
This is similar to \f(CW\*(C`$page = $pdf\->page()\*(C'\fR, except that \f(CW$page\fR is 
\&\fInot\fR a new, empty page; but contains the contents of that existing page.
.Sp
If \f(CW$page_number\fR is 0 or \-1, it will return the last page in the
document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 5
\&    $pdf  = PDF::Builder\->open(\*(Aqour/99page.pdf\*(Aq);
\&    $page = $pdf\->openpage(1);   # returns the first page
\&    $page = $pdf\->openpage(99);  # returns the last page
\&    $page = $pdf\->openpage(\-1);  # returns the last page
\&    $page = $pdf\->openpage(999); # returns undef
.Ve
.ie n .IP "$xoform = $pdf\->importPageIntoForm($source_pdf, $source_page_number)" 4
.el .IP "\f(CW$xoform\fR = \f(CW$pdf\fR\->importPageIntoForm($source_pdf, \f(CW$source_page_number\fR)" 4
.IX Item "$xoform = $pdf->importPageIntoForm($source_pdf, $source_page_number)"
Returns a Form XObject created by extracting the specified page from 
\&\f(CW$source_pdf\fR.
.Sp
This is useful if you want to transpose the imported page somewhat
differently onto a page (e.g. two-up, four-up, etc.).
.Sp
If \f(CW$source_page_number\fR is 0 or \-1, it will return the last page in the
document.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $pdf = PDF::Builder\->new();
\&    $old = PDF::Builder\->open(\*(Aqour/old.pdf\*(Aq);
\&    $page = $pdf\->page();
\&    $gfx = $page\->gfx();
\&
\&    # Import Page 2 from the old PDF
\&    $xo = $pdf\->importPageIntoForm($old, 2);
\&
\&    # Add it to the new PDF\*(Aqs first page at 1/2 scale
\&    $gfx\->formimage($xo, 0, 0, 0.5);
\&
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.Sp
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.ie n .IP "$page = $pdf\->import_page($source_pdf)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->import_page($source_pdf)" 4
.IX Item "$page = $pdf->import_page($source_pdf)"
.PD 0
.ie n .IP "$page = $pdf\->import_page($source_pdf, $source_page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->import_page($source_pdf, \f(CW$source_page_number\fR)" 4
.IX Item "$page = $pdf->import_page($source_pdf, $source_page_number)"
.ie n .IP "$page = $pdf\->import_page($source_pdf, $source_page_number, $target_page_number)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->import_page($source_pdf, \f(CW$source_page_number\fR, \f(CW$target_page_number\fR)" 4
.IX Item "$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_number)"
.ie n .IP "$page = $pdf\->import_page($source_pdf, $source_page_number, $target_page_object)" 4
.el .IP "\f(CW$page\fR = \f(CW$pdf\fR\->import_page($source_pdf, \f(CW$source_page_number\fR, \f(CW$target_page_object\fR)" 4
.IX Item "$page = $pdf->import_page($source_pdf, $source_page_number, $target_page_object)"
.PD
Imports a page from \f(CW$source_pdf\fR and adds it to the specified position
in \f(CW$pdf\fR.
.Sp
If the \f(CW$source_page_number\fR is omitted, 0, or \-1; the last page of the 
source is imported.
If the \f(CW$target_page_number\fR is omitted, 0, or \-1; the imported page will be
placed as the new last page of the target (\f(CW$pdf\fR).
Otherwise, as with the \f(CW\*(C`page()\*(C'\fR method, the page will be inserted before an 
existing page of that number.
.Sp
\&\fBNote:\fR If you pass a page \fIobject\fR instead of a page \fInumber\fR for
\&\f(CW$target_page_number\fR, the contents of the page will be \fBmerged\fR into the
existing page.
.Sp
\&\fBExample:\fR
.Sp
.Vb 2
\&    $pdf = PDF::Builder\->new();
\&    $old = PDF::Builder\->open(\*(Aqour/old.pdf\*(Aq);
\&
\&    # Add page 2 from the old PDF as page 1 of the new PDF
\&    $page = $pdf\->import_page($old, 2);
\&
\&    $pdf\->saveas(\*(Aqour/new.pdf\*(Aq);
.Ve
.Sp
\&\fBNote:\fR You can only import a page from an existing \s-1PDF\s0 file.
.ie n .IP "$count = $pdf\->\fBpages()\fR" 4
.el .IP "\f(CW$count\fR = \f(CW$pdf\fR\->\fBpages()\fR" 4
.IX Item "$count = $pdf->pages()"
Returns the number of pages in the document.
.ie n .IP "$pdf\->userunit($value)" 4
.el .IP "\f(CW$pdf\fR\->userunit($value)" 4
.IX Item "$pdf->userunit($value)"
Sets the global UserUnit, defining the scale factor to multiply any size or
coordinate by. For example, \f(CW\*(C`userunit(72)\*(C'\fR results in a User Unit of 72 points,
or 1 inch.
.Sp
See \*(L"User Units\*(R" in PDF::Builder::Docs for more information.
.ie n .IP "$pdf\->mediabox($name)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($name)" 4
.IX Item "$pdf->mediabox($name)"
.PD 0
.ie n .IP "$pdf\->mediabox($name, \-orient => 'orientation')" 4
.el .IP "\f(CW$pdf\fR\->mediabox($name, \-orient => 'orientation')" 4
.IX Item "$pdf->mediabox($name, -orient => 'orientation')"
.ie n .IP "$pdf\->mediabox($w,$h)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($w,$h)" 4
.IX Item "$pdf->mediabox($w,$h)"
.ie n .IP "$pdf\->mediabox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$pdf\fR\->mediabox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$pdf->mediabox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $pdf\->\fBmediabox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$pdf\fR\->\fBmediabox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $pdf->mediabox()"
.PD
Sets (or gets) the global MediaBox, defining the width and height (or by 
corner coordinates, or by standard name) of the output page itself, such as 
the physical paper size.
.Sp
See \*(L"Media Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "$pdf\->cropbox($name)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($name)" 4
.IX Item "$pdf->cropbox($name)"
.PD 0
.ie n .IP "$pdf\->cropbox($name, \-orient => 'orientation')" 4
.el .IP "\f(CW$pdf\fR\->cropbox($name, \-orient => 'orientation')" 4
.IX Item "$pdf->cropbox($name, -orient => 'orientation')"
.ie n .IP "$pdf\->cropbox($w,$h)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($w,$h)" 4
.IX Item "$pdf->cropbox($w,$h)"
.ie n .IP "$pdf\->cropbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$pdf\fR\->cropbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$pdf->cropbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $pdf\->\fBcropbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$pdf\fR\->\fBcropbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $pdf->cropbox()"
.PD
Sets (or gets) the global CropBox. This will define the media size to which 
the output will later be clipped.
.Sp
See \*(L"Crop Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "$pdf\->bleedbox($name)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($name)" 4
.IX Item "$pdf->bleedbox($name)"
.PD 0
.ie n .IP "$pdf\->bleedbox($name, \-orient => 'orientation')" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($name, \-orient => 'orientation')" 4
.IX Item "$pdf->bleedbox($name, -orient => 'orientation')"
.ie n .IP "$pdf\->bleedbox($w,$h)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($w,$h)" 4
.IX Item "$pdf->bleedbox($w,$h)"
.ie n .IP "$pdf\->bleedbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$pdf\fR\->bleedbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$pdf->bleedbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $pdf\->\fBbleedbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$pdf\fR\->\fBbleedbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $pdf->bleedbox()"
.PD
Sets (or gets) the global BleedBox. This is typically used for hard copy 
printing where you want ink to go to the edge of the cut paper.
.Sp
See \*(L"Bleed Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "$pdf\->trimbox($name)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($name)" 4
.IX Item "$pdf->trimbox($name)"
.PD 0
.ie n .IP "$pdf\->trimbox($name, \-orient => 'orientation')" 4
.el .IP "\f(CW$pdf\fR\->trimbox($name, \-orient => 'orientation')" 4
.IX Item "$pdf->trimbox($name, -orient => 'orientation')"
.ie n .IP "$pdf\->trimbox($w,$h)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($w,$h)" 4
.IX Item "$pdf->trimbox($w,$h)"
.ie n .IP "$pdf\->trimbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$pdf\fR\->trimbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$pdf->trimbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $pdf\->\fBtrimbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$pdf\fR\->\fBtrimbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $pdf->trimbox()"
.PD
Sets (or gets) the global TrimBox. This is supposed to be the actual 
dimensions of the finished page (after trimming of the paper).
.Sp
See \*(L"Trim Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.ie n .IP "$pdf\->artbox($name)" 4
.el .IP "\f(CW$pdf\fR\->artbox($name)" 4
.IX Item "$pdf->artbox($name)"
.PD 0
.ie n .IP "$pdf\->artbox($name, \-orient => 'orientation')" 4
.el .IP "\f(CW$pdf\fR\->artbox($name, \-orient => 'orientation')" 4
.IX Item "$pdf->artbox($name, -orient => 'orientation')"
.ie n .IP "$pdf\->artbox($w,$h)" 4
.el .IP "\f(CW$pdf\fR\->artbox($w,$h)" 4
.IX Item "$pdf->artbox($w,$h)"
.ie n .IP "$pdf\->artbox($llx,$lly, $urx,$ury)" 4
.el .IP "\f(CW$pdf\fR\->artbox($llx,$lly, \f(CW$urx\fR,$ury)" 4
.IX Item "$pdf->artbox($llx,$lly, $urx,$ury)"
.ie n .IP "($llx,$lly, $urx,$ury) = $pdf\->\fBartbox()\fR" 4
.el .IP "($llx,$lly, \f(CW$urx\fR,$ury) = \f(CW$pdf\fR\->\fBartbox()\fR" 4
.IX Item "($llx,$lly, $urx,$ury) = $pdf->artbox()"
.PD
Sets (or gets) the global ArtBox. This is supposed to define "the extent of 
the page's \fImeaningful\fR content".
.Sp
See \*(L"Art Box\*(R" in PDF::Builder::Docs for more information.
The method always returns the current bounds (after any set operation).
.SH "FONT METHODS"
.IX Header "FONT METHODS"
.ie n .IP "@directories = PDF::Builder::addFontDirs($dir1, $dir2, ...)" 4
.el .IP "\f(CW@directories\fR = PDF::Builder::addFontDirs($dir1, \f(CW$dir2\fR, ...)" 4
.IX Item "@directories = PDF::Builder::addFontDirs($dir1, $dir2, ...)"
Adds one or more directories to the search path for finding font
files.
.Sp
Returns the list of searched directories.
.ie n .IP "$font = $pdf\->corefont($fontname, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->corefont($fontname, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->corefont($fontname, %options)"
.PD 0
.ie n .IP "$font = $pdf\->corefont($fontname)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->corefont($fontname)" 4
.IX Item "$font = $pdf->corefont($fontname)"
.PD
Returns a new Adobe core font object. For details, see \*(L"Core Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::Font::CoreFont.
.ie n .IP "$font = $pdf\->psfont($ps_file, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->psfont($ps_file, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->psfont($ps_file, %options)"
.PD 0
.ie n .IP "$font = $pdf\->psfont($ps_file)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->psfont($ps_file)" 4
.IX Item "$font = $pdf->psfont($ps_file)"
.PD
Returns a new Adobe Type1 (\*(L"PostScript\*(R") font object.
For details, see \*(L"\s-1PS\s0 Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::Font::Postscript.
.ie n .IP "$font = $pdf\->ttfont($ttf_file, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->ttfont($ttf_file, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->ttfont($ttf_file, %options)"
.PD 0
.ie n .IP "$font = $pdf\->ttfont($ttf_file)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->ttfont($ttf_file)" 4
.IX Item "$font = $pdf->ttfont($ttf_file)"
.PD
Returns a new TrueType (or OpenType) font object.
For details, see \*(L"TrueType Fonts\*(R" in PDF::Builder::Docs.
.ie n .IP "$font = $pdf\->cjkfont($cjkname, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->cjkfont($cjkname, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->cjkfont($cjkname, %options)"
.PD 0
.ie n .IP "$font = $pdf\->cjkfont($cjkname)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->cjkfont($cjkname)" 4
.IX Item "$font = $pdf->cjkfont($cjkname)"
.PD
Returns a new \s-1CJK\s0 font object. These are TrueType-like fonts for East Asian
languages (Chinese, Japanese, Korean).
For details, see \*(L"\s-1CJK\s0 Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::CIDFont::CJKFont
.ie n .IP "$font = $pdf\->synfont($basefont, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->synfont($basefont, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->synfont($basefont, %options)"
.PD 0
.ie n .IP "$font = $pdf\->synfont($basefont)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->synfont($basefont)" 4
.IX Item "$font = $pdf->synfont($basefont)"
.PD
Returns a new synthetic font object. These are modifications to a core (or 
\&\s-1PS/T1\s0 or \s-1TTF/OTF\s0) font, where the font may be replaced by a Type1 or Type3 
PostScript font.
This does not appear to work with \s-1CJK\s0 fonts (created with \f(CW\*(C`cjkfont\*(C'\fR method).
For details, see \*(L"Synthetic Fonts\*(R" in PDF::Builder::Docs.
.Sp
See also PDF::Builder::Resource::Font::SynFont
.ie n .IP "$font = $pdf\->bdfont($bdf_file, @options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->bdfont($bdf_file, \f(CW@options\fR)" 4
.IX Item "$font = $pdf->bdfont($bdf_file, @options)"
.PD 0
.ie n .IP "$font = $pdf\->bdfont($bdf_file)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->bdfont($bdf_file)" 4
.IX Item "$font = $pdf->bdfont($bdf_file)"
.PD
Returns a new \s-1BDF\s0 (bitmapped distribution format) font object, based on the 
specified Adobe \s-1BDF\s0 file.
.Sp
See also PDF::Builder::Resource::Font::BdFont
.ie n .IP "$font = $pdf\->unifont(@fontspecs, %options)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->unifont(@fontspecs, \f(CW%options\fR)" 4
.IX Item "$font = $pdf->unifont(@fontspecs, %options)"
.PD 0
.ie n .IP "$font = $pdf\->unifont(@fontspecs)" 4
.el .IP "\f(CW$font\fR = \f(CW$pdf\fR\->unifont(@fontspecs)" 4
.IX Item "$font = $pdf->unifont(@fontspecs)"
.PD
Returns a new uni-font object, based on the specified fonts and options.
.Sp
\&\fB\s-1BEWARE:\s0\fR This is not a true PDF-object, but a virtual/abstract font definition!
.Sp
See also PDF::Builder::Resource::UniFont.
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-encode" 4
.IX Item "-encode"
Changes the encoding of the font from its default.
.RE
.RS 4
.RE
.SH "IMAGE METHODS"
.IX Header "IMAGE METHODS"
.ie n .IP "$jpeg = $pdf\->image_jpeg($file)" 4
.el .IP "\f(CW$jpeg\fR = \f(CW$pdf\fR\->image_jpeg($file)" 4
.IX Item "$jpeg = $pdf->image_jpeg($file)"
Imports and returns a new \s-1JPEG\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See PDF::Builder::Resource::XObject::Image::JPEG for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page.
.ie n .IP "$tiff = $pdf\->image_tiff($file, %opts)" 4
.el .IP "\f(CW$tiff\fR = \f(CW$pdf\fR\->image_tiff($file, \f(CW%opts\fR)" 4
.IX Item "$tiff = $pdf->image_tiff($file, %opts)"
.PD 0
.ie n .IP "$tiff = $pdf\->image_tiff($file)" 4
.el .IP "\f(CW$tiff\fR = \f(CW$pdf\fR\->image_tiff($file)" 4
.IX Item "$tiff = $pdf->image_tiff($file)"
.PD
Imports and returns a new \s-1TIFF\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
For details, see \*(L"\s-1TIFF\s0 Images\*(R" in PDF::Builder::Docs.
.Sp
See PDF::Builder::Resource::XObject::Image::TIFF and
PDF::Builder::Resource::XObject::Image::TIFF_GT for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR
for some examples of placing an image on a page (\s-1JPEG,\s0 but the principle is
the same). There is an optional \s-1TIFF\s0 library described, that gives more
capability than the default one.
.ie n .IP "$rc = $pdf\->\s-1\fBLA_GT\s0()\fR" 4
.el .IP "\f(CW$rc\fR = \f(CW$pdf\fR\->\s-1\fBLA_GT\s0()\fR" 4
.IX Item "$rc = $pdf->LA_GT()"
Returns 1 if the library name (package) Graphics::TIFF is installed, and 
0 otherwise. For this optional library, this call can be used to know if it 
is safe to use certain functions. For example:
.Sp
.Vb 5
\&    if ($pdf\->LA_GT() {
\&        # is installed and usable
\&    } else {
\&        # not available. you will be running the old, pure PERL code
\&    }
.Ve
.ie n .IP "$pnm = $pdf\->image_pnm($file)" 4
.el .IP "\f(CW$pnm\fR = \f(CW$pdf\fR\->image_pnm($file)" 4
.IX Item "$pnm = $pdf->image_pnm($file)"
Imports and returns a new \s-1PNM\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See \f(CW\*(C`examples/Content.pl\*(C'\fR
for some examples of placing an image on a page (\s-1JPEG,\s0 but the principle is
the same).
.ie n .IP "$png = $pdf\->image_png($file, %options)" 4
.el .IP "\f(CW$png\fR = \f(CW$pdf\fR\->image_png($file, \f(CW%options\fR)" 4
.IX Item "$png = $pdf->image_png($file, %options)"
.PD 0
.ie n .IP "$png = $pdf\->image_png($file)" 4
.el .IP "\f(CW$png\fR = \f(CW$pdf\fR\->image_png($file)" 4
.IX Item "$png = $pdf->image_png($file)"
.PD
Imports and returns a new \s-1PNG\s0 image object. \f(CW$file\fR may be either 
a filename or a filehandle.
For details, see \*(L"\s-1PNG\s0 Images\*(R" in PDF::Builder::Docs.
.Sp
See PDF::Builder::Resource::XObject::Image::PNG and
PDF::Builder::Resource::XObject::Image::PNG_IPL for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR
for some examples of placing an image on a page (\s-1JPEG,\s0 but the principle is
the same). There is an optional \s-1PNG\s0 library (\s-1PNG_IPL\s0) described, that gives more
capability than the default one.
.ie n .IP "$rc = $pdf\->\s-1\fBLA_IPL\s0()\fR" 4
.el .IP "\f(CW$rc\fR = \f(CW$pdf\fR\->\s-1\fBLA_IPL\s0()\fR" 4
.IX Item "$rc = $pdf->LA_IPL()"
Returns 1 if the library name (package) Image::PNG::Libpng is installed, and 
0 otherwise. For this optional library, this call can be used to know if it 
is safe to use certain functions. For example:
.Sp
.Vb 5
\&    if ($pdf\->LA_IPL() {
\&        # is installed and usable
\&    } else {
\&        # not available. don\*(Aqt use 16bps or interlaced PNG image files
\&    }
.Ve
.ie n .IP "$gif = $pdf\->image_gif($file)" 4
.el .IP "\f(CW$gif\fR = \f(CW$pdf\fR\->image_gif($file)" 4
.IX Item "$gif = $pdf->image_gif($file)"
Imports and returns a new \s-1GIF\s0 image object. \f(CW$file\fR may be either a filename 
or a filehandle.
.Sp
See PDF::Builder::Resource::XObject::Image::GIF for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page 
(\s-1JPEG,\s0 but the principle is the same).
.ie n .IP "$gdf = $pdf\->image_gd($gd_object, %options)" 4
.el .IP "\f(CW$gdf\fR = \f(CW$pdf\fR\->image_gd($gd_object, \f(CW%options\fR)" 4
.IX Item "$gdf = $pdf->image_gd($gd_object, %options)"
.PD 0
.ie n .IP "$gdf = $pdf\->image_gd($gd_object)" 4
.el .IP "\f(CW$gdf\fR = \f(CW$pdf\fR\->image_gd($gd_object)" 4
.IX Item "$gdf = $pdf->image_gd($gd_object)"
.PD
Imports and returns a new image object from Image::GD.
.Sp
Valid \f(CW%options\fR are:
.RS 4
.IP "\-lossless => 1" 4
.IX Item "-lossless => 1"
Use lossless compression.
.RE
.RS 4
.Sp
See PDF::Builder::Resource::XObject::Image::GD for additional information
and \f(CW\*(C`examples/Content.pl\*(C'\fR for some examples of placing an image on a page 
(\s-1JPEG,\s0 but the principle is the same).
.RE
.SH "COLORSPACE METHODS"
.IX Header "COLORSPACE METHODS"
.ie n .IP "$cs = $pdf\->colorspace_act($file)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_act($file)" 4
.IX Item "$cs = $pdf->colorspace_act($file)"
Returns a new colorspace object based on an Adobe Color Table file.
.Sp
See PDF::Builder::Resource::ColorSpace::Indexed::ACTFile for a
reference to the file format's specification.
.ie n .IP "$cs = $pdf\->\fBcolorspace_web()\fR" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->\fBcolorspace_web()\fR" 4
.IX Item "$cs = $pdf->colorspace_web()"
Returns a new colorspace-object based on the \*(L"web-safe\*(R" color palette.
.ie n .IP "$cs = $pdf\->\fBcolorspace_hue()\fR" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->\fBcolorspace_hue()\fR" 4
.IX Item "$cs = $pdf->colorspace_hue()"
Returns a new colorspace-object based on the hue color palette.
.Sp
See PDF::Builder::Resource::ColorSpace::Indexed::Hue for an explanation.
.ie n .IP "$cs = $pdf\->colorspace_separation($tint, $color)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_separation($tint, \f(CW$color\fR)" 4
.IX Item "$cs = $pdf->colorspace_separation($tint, $color)"
Returns a new separation colorspace object based on the parameters.
.Sp
\&\fI\f(CI$tint\fI\fR can be any valid ink identifier, including but not limited
to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or
\&'Orange'.
.Sp
\&\fI\f(CI$color\fI\fR must be a valid color specification limited to: '#rrggbb',
\&'!hhssvv', '%ccmmyykk' or a \*(L"named color\*(R" (rgb).
.Sp
The colorspace model will automatically be chosen based on the
specified color.
.ie n .IP "$cs = $pdf\->colorspace_devicen(\e@tintCSx, $samples)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_devicen(\e@tintCSx, \f(CW$samples\fR)" 4
.IX Item "$cs = $pdf->colorspace_devicen(@tintCSx, $samples)"
.PD 0
.ie n .IP "$cs = $pdf\->colorspace_devicen(\e@tintCSx)" 4
.el .IP "\f(CW$cs\fR = \f(CW$pdf\fR\->colorspace_devicen(\e@tintCSx)" 4
.IX Item "$cs = $pdf->colorspace_devicen(@tintCSx)"
.PD
Returns a new DeviceN colorspace object based on the parameters.
.Sp
\&\fBExample:\fR
.Sp
.Vb 4
\&    $cy = $pdf\->colorspace_separation(\*(AqCyan\*(Aq,    \*(Aq%f000\*(Aq);
\&    $ma = $pdf\->colorspace_separation(\*(AqMagenta\*(Aq, \*(Aq%0f00\*(Aq);
\&    $ye = $pdf\->colorspace_separation(\*(AqYellow\*(Aq,  \*(Aq%00f0\*(Aq);
\&    $bk = $pdf\->colorspace_separation(\*(AqBlack\*(Aq,   \*(Aq%000f\*(Aq);
\&
\&    $pms023 = $pdf\->colorspace_separation(\*(AqPANTONE 032CV\*(Aq, \*(Aq%0ff0\*(Aq);
\&
\&    $dncs = $pdf\->colorspace_devicen( [ $cy,$ma,$ye,$bk, $pms023 ] );
.Ve
.Sp
The colorspace model will automatically be chosen based on the first
colorspace specified.
.SH "BARCODE METHODS"
.IX Header "BARCODE METHODS"
These are glue routines to the actual barcode rendering routines found
elsewhere.
.ie n .IP "$bc = $pdf\->xo_codabar(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_codabar(%options)" 4
.IX Item "$bc = $pdf->xo_codabar(%options)"
.PD 0
.ie n .IP "$bc = $pdf\->xo_code128(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_code128(%options)" 4
.IX Item "$bc = $pdf->xo_code128(%options)"
.ie n .IP "$bc = $pdf\->xo_2of5int(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_2of5int(%options)" 4
.IX Item "$bc = $pdf->xo_2of5int(%options)"
.ie n .IP "$bc = $pdf\->xo_3of9(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_3of9(%options)" 4
.IX Item "$bc = $pdf->xo_3of9(%options)"
.ie n .IP "$bc = $pdf\->xo_ean13(%options)" 4
.el .IP "\f(CW$bc\fR = \f(CW$pdf\fR\->xo_ean13(%options)" 4
.IX Item "$bc = $pdf->xo_ean13(%options)"
.PD
Creates the specified barcode object as a form XObject.
.SH "OTHER METHODS"
.IX Header "OTHER METHODS"
.ie n .IP "$xo = $pdf\->\fBxo_form()\fR" 4
.el .IP "\f(CW$xo\fR = \f(CW$pdf\fR\->\fBxo_form()\fR" 4
.IX Item "$xo = $pdf->xo_form()"
Returns a new form XObject.
.ie n .IP "$egs = $pdf\->\fBegstate()\fR" 4
.el .IP "\f(CW$egs\fR = \f(CW$pdf\fR\->\fBegstate()\fR" 4
.IX Item "$egs = $pdf->egstate()"
Returns a new extended graphics state object.
.ie n .IP "$obj = $pdf\->pattern(%options)" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->pattern(%options)" 4
.IX Item "$obj = $pdf->pattern(%options)"
.PD 0
.ie n .IP "$obj = $pdf\->\fBpattern()\fR" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->\fBpattern()\fR" 4
.IX Item "$obj = $pdf->pattern()"
.PD
Returns a new pattern object.
.ie n .IP "$obj = $pdf\->shading(%options)" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->shading(%options)" 4
.IX Item "$obj = $pdf->shading(%options)"
.PD 0
.ie n .IP "$obj = $pdf\->\fBshading()\fR" 4
.el .IP "\f(CW$obj\fR = \f(CW$pdf\fR\->\fBshading()\fR" 4
.IX Item "$obj = $pdf->shading()"
.PD
Returns a new shading object.
.ie n .IP "$otls = $pdf\->\fBoutlines()\fR" 4
.el .IP "\f(CW$otls\fR = \f(CW$pdf\fR\->\fBoutlines()\fR" 4
.IX Item "$otls = $pdf->outlines()"
Returns a new or existing outlines object.
.ie n .IP "$ndest = $pdf\->\fBnamed_destination()\fR" 4
.el .IP "\f(CW$ndest\fR = \f(CW$pdf\fR\->\fBnamed_destination()\fR" 4
.IX Item "$ndest = $pdf->named_destination()"
Returns a new or existing named destination object.