.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Resource::CIDFont::TrueType 3"
.TH PDF::Builder::Resource::CIDFont::TrueType 3 2025-06-29 "perl v5.40.2" "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::Resource::CIDFont::TrueType \- TrueType (ttfont) font support
.PP
Inherits from PDF::Builder::Resource::CIDFont
.PP
Generally also usable for OTF (Open Type) fonts
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    $font = PDF::Builder::Resource::CIDFont::TrueType\->new($pdf, $file, %opts)
.Ve
.Sp
.RS 4
Returns a font object for TrueType and OpenType fonts (from \f(CWttfont()\fR call).
.RE
.PP
Valid Options (%opts) are:
.IP encode 4
.IX Item "encode"
Changes the encoding of the font from its default (WinAnsiEncoding).
.Sp
Note that for a single byte encoding (e.g., 'latin1'), you are limited to 256
characters defined for that encoding. 'automap' does not work with TrueType.
If you want more characters than that, use 'utf8' encoding with a UTF\-8
encoded text string.
.IP isocmap 4
.IX Item "isocmap"
Use the ISO Unicode Map instead of the default MS Unicode Map.
.IP unicodemap 4
.IX Item "unicodemap"
If 1 (default), output ToUnicode CMap to permit text searches and screen
readers. Set to 0 to save space by \fInot\fR including the ToUnicode CMap, but
text searching and screen reading will not be possible.
.IP dokern 4
.IX Item "dokern"
Enables kerning if data is available.
.Sp
\&\f(CW\*(C`kerning\*(C'\fR is still accepted as an (older) \fBalternative\fR to \f(CW\*(C`dokern\*(C'\fR.
.IP noembed 4
.IX Item "noembed"
Disables embedding of the font file. \fBNote that this is potentially hazardous,
as the glyphs provided on the PDF reader machine may not match what was used on
the PDF writer machine (the one running PDF::Builder)!\fR If you know \fIfor sure\fR 
that all PDF readers will be using the same TTF or OTF file you're using with
PDF::Builder; not embedding the font may be acceptable, in return for a smaller
PDF file size. Note that the Reader needs to know where to find the font file
\&\-\- it can't be in any random place, but typically needs to be listed in a path 
that the Reader follows. Otherwise, it will be unable to render the text!
.Sp
The only value for the \f(CW\*(C`noembed\*(C'\fR flag currently checked for is \fB1\fR, which
means to \fInot\fR embed the font file in the PDF. Any other value currently
results in the font file being embedded (by \fBdefault\fR), although in the future,
other values might be given significance (such as checking permission bits).
.Sp
Some additional comments on embedding font file(s) into the PDF: besides 
substantially increasing the size of the PDF (even if the font is subsetted,
by default), PDF::Builder does not check the font file for any flags indicating 
font licensing issues and limitations on use. A font foundry may not permit 
embedding at all, may permit a subset of the font to be embedded, may permit a 
full font to be embedded, and may specify what can be done with an embedded 
font (e.g., may or may not be extracted for further use beyond displaying this 
one PDF). When you choose to use (and embed) a font, you should be aware of any
such licensing issues.
.IP nosubset 4
.IX Item "nosubset"
Disables subsetting of a TTF/OTF font, when embedded. By default, only the
glyphs used by a document are included in the file, and \fInot\fR the entire font.
This can result in a tremendous savings in PDF file size. If you intend to 
allow the PDF to be edited by users, not having the entire font glyph set
available may cause problems, so be aware of that (and consider using 
\&\f(CW\*(C`nosubset => 1\*(C'\fR. Setting this flag to any value results in the entire
font glyph set being embedded in the file. It might be a good idea to use only
the value \fB1\fR, in case other values are assigned roles in the future.
.IP debug 4
.IX Item "debug"
If set to 1 (default is 0), diagnostic information is output about the CMap
processing.
.IP usecmf 4
.IX Item "usecmf"
If set to 1 (default is 0), the first priority is to make use of one of the
four \f(CW\*(C`.cmap\*(C'\fR files for CJK fonts. This is the \fIold\fR way of processing TTF
files. If, after all is said and done, a working \fIinternal\fR CMap hasn't been
found (for usecmf=>0), \f(CWttfont()\fR will fall back to using a \f(CW\*(C`.cmap\*(C'\fR file
if possible.
.IP cmaps 4
.IX Item "cmaps"
This flag may be set to a string listing the Platform/Encoding pairs to look 
for of any internal CMaps in the font file, in the desired order (highest 
priority first). If one list (comma and/or space-separated pairs) is given, it 
is used for both Windows and non-Windows platforms (on which PDF::Builder is 
running, \fInot\fR the PDF reader's). Two lists, separated by a semicolon ; may be 
given, with the first being used for a Windows platform and the second for 
non-Windows. The default list is \f(CW\*(C`0/6 3/10 0/4 3/1 0/3; 0/6 0/4 3/10 0/3 3/1\*(C'\fR. 
Finally, instead of a P/E list, a string \f(CW\*(C`find_ms\*(C'\fR may be given to tell it to 
simply call the Font::TTF \f(CWfind_ms()\fR method to find a (preferably Windows) 
internal CMap. \f(CW\*(C`cmaps\*(C'\fR set to 'find_ms' would emulate the \fIold\fR way of 
looking for CMaps. Symbol fonts (3/0) always use \fBfind_ms()\fR, and the new default 
lookup is (if \f(CW\*(C`.cmap\*(C'\fR isn't used, see \f(CW\*(C`usecmf\*(C'\fR) to try to get a match with 
the default list for the appropriate OS. If none can be found, \fBfind_ms()\fR is 
tried, and as last resort use the \f(CW\*(C`.cmap\*(C'\fR (if available), even if \f(CW\*(C`usecmf\*(C'\fR 
is not 1.
.SS fontfile
.IX Subsection "fontfile"
.Vb 1
\&    $font\->fontfile()
.Ve
.Sp
.RS 4
Returns font file object (' ff' element), so its methods may be invoked.
.RE
.SS fontobj
.IX Subsection "fontobj"
.Vb 1
\&    $font\->fontobj()
.Ve
.Sp
.RS 4
Returns font object, so its methods and properties may be used.
.RE
.SS wxByCId
.IX Subsection "wxByCId"
.Vb 1
\&    $font\->wxByCId($gID)
.Ve
.Sp
.RS 4
Returns unscaled glyph width, given the glyph ID (CID).
.RE
.SS haveKernPairs
.IX Subsection "haveKernPairs"
.Vb 1
\&    $flag = $font\->haveKernPairs()
.Ve
.Sp
.RS 4
Does the font include kerning data? Invokes fontfile's \fBhaveKernPairs()\fR.
Not clear what additional optional arguments are.
.RE
.SS kernPairCid
.IX Subsection "kernPairCid"
.Vb 1
\&    $flag = $font\->kernPairCid($gID, $n)
.Ve
.Sp
.RS 4
Returns kerning information for? Not clear what additional arguments are.
Invokes fontfile's \fBkernPairCid()\fR method.
.RE
.SS subsetByCid
.IX Subsection "subsetByCid"
.Vb 1
\&    $font\->subsetByCid($gID)
.Ve
.Sp
.RS 4
Invokes \fBsubsetByCId()\fR method from \fBfontfile()\fR to put the glyph into the embedded
font cache in the PDF.
.RE
.SS subvec
.IX Subsection "subvec"
.Vb 1
\&    $font\->subvec($gID)
.Ve
.Sp
.RS 4
(No Information) invokes fontfile's \fBsubvec()\fR method.
.RE
.SS glyphNum
.IX Subsection "glyphNum"
.Vb 1
\&    $count = $font\->glyphNum()
.Ve
.Sp
.RS 4
Number of glyphs in the font.
.RE
.SS outobjdeep
.IX Subsection "outobjdeep"
.Vb 1
\&    $font\->outobjdeep()
.Ve
.Sp
.RS 4
(No Information) output to PDF
.RE