.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (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
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "PDF::Builder::Resource::Font::SynFont 3"
.TH PDF::Builder::Resource::Font::SynFont 3 2026-02-08 "perl v5.42.0" "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
.PP
Inherits from PDF::Builder::Resource::Font
.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) a.k.a. B<stretch>
\&    * 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\*(Aqs 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"
Character width condense/expand factor (0.1\-0.9 = condense, 1 = normal/default, 
1.1+ = expand). It is the multiplier to apply to the width of each character.
.Sp
In some font systems, this aspect or axis is known as \fIstretch\fR.
.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 or slanted text angle (+/\-) in degrees, where the character box is 
skewed (sheared), top to the right. While it\*(Aqs 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
Note that a font management system may have separate axes for normal/italic
fonts, and the degree of \fIslant\fR. Italic is a different (but related) face
to the regular (e.g., Roman) face, sometimes made to resemble handwritten
characters, and is usually a binary selection (it\*(Aqs either italic or it\*(Aqs not). 
Slant, on the other hand, can be in arbitrary amounts, and may be applied to either
normal (originally Roman posture) or italics (which are often themselves 
slightly slanted). Finally, what many fonts call "italic" others may call
"slanted" or "oblique", and in these cases the coordinate system is merely
sheared to slant the character box.
.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\*(Aqs 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
.Sp
Note that only lower case letters which appear in the "standard" font (plane 0
for core fonts and PS fonts) will be small\-capped. This may include eszett
(German sharp s), which becomes SS, and dotless i and j which become I and J
respectively. There are many other accented Latin alphabet letters which \fImay\fR 
show up in planes 1 and higher. Ligatures (e.g., ij and ffl) do not have
uppercase equivalents, nor does a long s. If you have text which includes such
characters, you may want to consider preprocessing it to replace them with
Latin character expansions (e.g., i+j and f+f+l) before small\-capping.
.RE
.RS 4
.RE