.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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::Font::SynFont 3"
.TH PDF::Builder::Resource::Font::SynFont 3 2023-12-21 "perl v5.38.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::Resource::Font::SynFont \- Module for creating temporary synthetic Fonts.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
This module permits you to create a "new" font (loaded temporarily, but not 
permanently stored) based on an existing font, where you can modify certain 
attributes in the original font, such as:
.PP
.Vb 7
\&    * slant/obliqueness 
\&    * extra weight/boldness (by drawing glyph outlines at various line 
\&      thicknesses, rather than just filling enclosed areas)
\&    * condense/expand (narrower or wider characters)
\&    * extra space between characters
\&    * small caps (synthesized, not using any provided with a font)
\&    * change the encoding
\&
\&    $pdf = PDF::Builder\->new();
\&    $cft = $pdf\->font(\*(AqTimes\-Roman\*(Aq);  # corefont, ttfont, etc. also works
\&    $sft = $pdf\->synfont($cft, \*(Aqcondense\*(Aq => .75);  # condense by 25%
.Ve
.PP
This works for \fIcorefonts\fR, \fIPS fonts\fR, and \fITTF/OTF fonts\fR; but does not
work for \fICJK fonts\fR or \fIbitmapped fonts\fR.
See also "Synthetic Fonts" in PDF::Builder::Docs.
.PP
\&\fBAlternate name:\fR \f(CW\*(C`synthetic_font\*(C'\fR
.PP
This is for compatibility with recent changes to PDF::API2.
.SH METHODS
.IX Header "METHODS"
.SS new
.IX Subsection "new"
.Vb 1
\&    $font = PDF::Builder::Resource::Font::SynFont\->new($pdf, $fontobj, %opts)
.Ve
.Sp
.RS 4
Returns a synfont object. \f(CW$fontobj\fR is a normal font object read in from
a file, and \f(CW$font\fR is the modified output.
.Sp
Valid options \f(CW%opts\fR are:
.IP \fIencode\fR 4
.IX Item "encode"
Changes the encoding of the font from its default.
See \fIPerl's Encode\fR for the supported values. \fBWarning:\fR only single byte
encodings are supported. Multibyte encodings such as UTF\-8 are invalid.
.IP \fIpdfname\fR 4
.IX Item "pdfname"
Changes the reference-name of the font from its default.
The reference-name is normally generated automatically and can be
retrieved via \f(CW$pdfname\fR=$font\->\fBname()\fR.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`name\*(C'\fR (for PDF::API2 compatibility)
.IP \fIcondense\fR 4
.IX Item "condense"
Condense/expand factor (0.1\-0.9 = condense, 1 = normal, 1.1+ = expand).
It's the multiplier for character widths vs. normal.
.Sp
\&\fBAlternate names:\fR \f(CW\*(C`hscale\*(C'\fR and \f(CW\*(C`slant\*(C'\fR (for PDF::API2 compatibility)
.Sp
The \fIslant\fR option is a deprecated name in both PDF::Builder and PDF::API2.
Its value is the same as \fIcondense\fR value (1 = normal, unchanged scale).
For the \fIhscale\fR option, the value is percentage (%), with 100 being normal,
and other values 100 times the \fIcondense\fR value. 
\&\fBUse only one (at most) of these three option names.\fR
.IP \fIoblique\fR 4
.IX Item "oblique"
Italic angle (+/\-) in degrees, where the character box is skewed. While 
it's unlikely that anyone will want to slant characters at +/\-360 degrees, they 
should be aware that these will be treated as an angle of 0 degrees (\fBdeg2rad()\fR 
wraps around). 0 degrees of italic slant (obliqueness) is the default.
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`angle\*(C'\fR (for PDF::API2 compatibility)
.Sp
\&\fBUse only one (at most) of these two option names.\fR
.IP \fIbold\fR 4
.IX Item "bold"
Embolding factor (0.1+, bold=1, heavy=2, ...). It is additional outline
\&\fBthickness\fR (\fBlinewidth\fR), which expands the character (glyph) outwards (as
well as shrinking unfilled enclosed areas such as bowls and counters). 
Normally, the glyph's outline is not drawn (it is only filled); this adds
a thick outline. The units are in 1/100ths of a text unit.
.Sp
If used with the \f(CW\*(C`synthetic_font\*(C'\fR alternate entry name, the unit is 1/1000th
of a text unit, so you will need a value 10 times larger than with the 
\&\f(CW\*(C`synfont\*(C'\fR entry to get the same effect
.IP \fIspace\fR 4
.IX Item "space"
Additional charspacing in thousandths of an em.
.IP \fIcaps\fR 4
.IX Item "caps"
Create synthetic small-caps. 0 = no, 1 = yes. These are capitals of 
lowercase letters, at 80% height and 88% width. Note that this is guaranteed
to cover ASCII lowercase letters only \-\- single byte encoded accented 
characters \fIusually\fR work, but we can make no promises on accented characters 
in general, as well as ligatures!
.Sp
\&\fBAlternate name:\fR \f(CW\*(C`smallcaps\*(C'\fR (for PDF::API2 compatibility)
.Sp
\&\fBUse only one (at most) of these two option names.\fR
.RE
.RS 4
.RE