PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 1) — page 10

372

CHAPTER 4

Graphics

% In the resources dictionary

/Properties << /oc1 5 0 R >>

% This dictionary maps the name oc1 to an

% optional content group (object 5)

5 0 obj

% The OCG controlling the visibility

% of the text.

/Type /OCG

/Name (Show Greeting)

endobj

The example above shows one piece of content associated with one optional con-

tent group. There are other possibilities:

• More than one section of content can refer to the same group or membership

dictionary, in which case the visibility of both sections is always the same.

• Equivalently, although less space-efficient, different sections can have separate

membership dictionaries with the same OCGs and P entries. The sections will

have identical visibility behavior.

• Two sections of content can belong to membership dictionaries that refer to the

same group(s) but with different P settings. For example, if one section has no P

entry, and the other has a P entry of AllOff, the visibility of the two sections of

content are opposite. That is, the first section is visible when the second is hid-

den, and vice versa.

The following example demonstrates both the direct use of optional content

groups and the indirect use of groups through a membership dictionary. The

content (a black rectangle frame) is drawn if either of the images controlled by

the groups named Image A or Image B is shown. If both groups are hidden, the

rectangle frame is hidden.

Example 4.36

% Within a content stream

/OC /OC2 BDC

% Draws a black rectangle frame

0 g

4 w

100 100 412 592 re s

EMC

373

SECTION 4.10

Optional Content

/OC /OC3 BDC

% Draws an image XObject

412 0 0 592 100 100 cm

/Im3 Do

EMC

/OC /OC4 BDC

% Draws an image XObject

412 0 0 592 100 100 cm

/Im4 Do

EMC

% The resource dictionary

/Properties << /OC2 20 0 R /OC3 30 0 R /OC4 40 0 R >>

/XObject << /lm3 50 0 R /lm4 /60 0 R >>

20 0 obj

% Optional content membership dictionary

/Type /OCMD

/OCGs [30 0 R 40 0 R]

/P /AnyOn

endobj

30 0 obj

% Optional content group “Image A”

/Type /OCG

/Name (Image A)

endobj

40 0 obj

% Optional content group “Image B”

/Type /OCG

/Name (Image B)

endobj

374

CHAPTER 4

Graphics

Optional Content in XObjects and Annotations

In addition to marked content within content streams, form XObjects and image

XObjects (see Section 4.7, “External Objects”) and annotations (see Section 8.4,

“Annotations”) may contain an OC entry, which is an optional content group or

an optional content membership dictionary.

A form or image XObject's visibility is determined by the state of the group or

those of the groups referenced by the membership dictionary in conjunction with

its P (or VE) entry, along with the current visibility state in the context in which

the XObject is invoked (that is, whether objects are visible in the contents stream

at the place where the Do operation occurred).

Annotations have various flags controlling on-screen and print visibility (see Sec-

tion 8.4.2, “Annotation Flags”). If an annotation contains an OC entry, it is visible

for screen or print only if the flags have the appropriate settings and the group or

membership dictionary indicates it is visible.

4.10.3

Configuring Optional Content

A PDF document containing optional content can specify the default states for

the optional content groups in the document and indicate which external factors

should be used to alter the states. The following sections describe the PDF struc-

tures that are used to specify this information.

• “Optional Content Properties Dictionary” on page 375 describes the structure

that lists all the optional content groups in the document and their possible

configurations.

• “Optional Content Configuration Dictionaries” on page 375 describes the

structures that specify initial state settings and other information about the

groups in the document.

• “Usage and Usage Application Dictionaries” on page 380 and “Determining the

State of Optional Content Groups” on page 385 describe how the states of

groups can be affected based on external factors.

375

SECTION 4.10

Optional Content

Optional Content Properties Dictionary

The optional OCProperties entry in the document catalog (see Section 3.6.1,

“Document Catalog”) holds the optional content properties dictionary, which con-

tains a list of all the optional content groups in the document, as well as informa-

tion about the default and alternate configurations for optional content. This

dictionary is required if the file contains any optional content; if it is missing, a

PDF consumer should ignore any optional content structures in the document.

This dictionary contains the following entries:

TABLE 4.50 Entries in the optional content properties dictionary

KEY

TYPE

VALUE

OCGs

array

(Required) An array of indirect references to all the optional content groups in

the document (see Section 4.10.1, “Optional Content Groups”), in any order.

Every optional content group must be included in this array.

dictionary

(Required) The default viewing optional content configuration dictionary (see

“Optional Content Configuration Dictionaries,” below).

Configs

array

(Optional) An array of alternate optional content configuration dictionaries (see

“Optional Content Configuration Dictionaries,” below) for PDF processing ap-

plications or features.

Optional Content Configuration Dictionaries

The D and Configs entries in Table 4.50 are configuration dictionaries, which rep-

resent different presentations of a document’s optional content groups for use by

PDF processing applications or features. The D configuration dictionary specifies

the initial state of the optional content groups when a document is first opened.

Configs lists other configurations that may be used under particular circumstanc-

es. The entries in a configuration dictionary are shown in Table 4.51.

376

CHAPTER 4

Graphics

TABLE 4.51 Entries in an optional content configuration dictionary

KEY

TYPE

VALUE

Name

text string

(Optional) A name for the configuration, suitable for presentation in a user

interface.

Creator

text string

(Optional) Name of the application or feature that created this configuration

dictionary.

BaseState

name

(Optional) Used to initialize the states of all the optional content groups in a

document when this configuration is applied. The value of this entry must

be one of the following names:

• ON: The states of all groups are turned ON.

• OFF: The states of all groups are turned OFF.

• Unchanged: The states of all groups are left unchanged.

After this initialization, the contents of the ON and OFF arrays are processed,

overriding the state of the groups included in the arrays.

Default value: ON.

Note: If BaseState is present in the document’s default configuration dictio-

nary, its value must be ON.

array

(Optional) An array of optional content groups whose state should be set to

ON when this configuration is applied.

Note: If the BaseState entry is ON, this entry is redundant.

OFF

array

(Optional) An array of optional content groups whose state should be set to

OFF when this configuration is applied.

Note: If the BaseState entry is OFF, this entry is redundant.

Intent

name or array

(Optional) A single intent name or an array containing any combination of

names. It is used to determine which optional content groups’ states to con-

sider and ignore in calculating the visibility of content (see “Intent” on page

368).

PDF 1.5 defines two intent names, View and Design. Future versions may de-

fine others. In addition, the name All indicates the set of all intents, including

those not yet defined. Default value: View. The value must be View for the

document’s default configuration.

377

SECTION 4.10

Optional Content

KEY

TYPE

VALUE

array

(Optional) An array of usage application dictionaries (see Table 4.53) speci-

fying which usage dictionary categories (see Table 4.52) should be consulted

by viewer applications to automatically set the states of optional content

groups based on external factors, such as the current system language or

viewing magnification, and when they should be applied.

Order

array

(Optional) An array specifying the recommended order for presentation of

optional content groups in a user interface. The array elements may include

the following objects:

• Optional content group dictionaries, whose Name entry is to be displayed

in the user interface.

• Arrays of optional content groups to allow nesting as in a tree or outline

structure. Each nested array may optionally have as its first element a text

string to be used as a non-selectable label in the user interface.

Note: Text labels in nested arrays should be used to present collections of relat-

ed optional content groups, and not to communicate actual nesting of content

inside multiple layers of groups (see Example 4.37). To reflect actual nesting of

groups in the content, such as for layers with sublayers, nested arrays of groups

without a text label should be used (see Example 4.38).

An empty array [] explicitly specifies that no groups should be presented.

In the default configuration dictionary, the default value is an empty array;

in other configuration dictionaries, the default is the Order value from the

default configuration dictionary.

Note: Any groups not listed in this array should not be presented in any user

interface that uses the configuration.

ListMode

name

(Optional) A name specifying which optional content groups in the Order

array should be displayed to the user. Valid values are:

• AllPages: Display all groups in the Order array.

• VisiblePages: Display only those groups in the Order array that are refer-

enced by one or more visible pages.

Default value: AllPages.

378

CHAPTER 4

Graphics

KEY

TYPE

VALUE

RBGroups

array

(Optional) An array consisting of one or more arrays, each of which repre-

sents a collection of optional content groups whose states are intended to fol-

low a radio button paradigm. That is, the state of at most one optional

content group in each array should be ON at a time. If one group is turned

ON, all others must be turned OFF. However, turning a group from ON to

OFF does not force any other group to be turned ON.

An empty array [] explicitly indicates that no such collections exist.

In the default configuration dictionary, the default value is an empty array;

in other configuration dictionaries, the default is the RBGroups value from

the default configuration dictionary.

Locked

array

(Optional; PDF 1.6) An array of optional content groups that should be

locked when this configuration is applied. The state of a locked group cannot

be changed through the user interface of a viewer application. Producers can

use this entry to prevent the visibility of content that depends on these

groups from being changed by users.

Default value: an empty array.

Note: This entry does not prevent the states of optional content groups from be-

ing changed by means other than the user interface, such as JavaScript or items

in the AS entry of a configuration dictionary.

Examples 4.37 and 4.38 illustrates the use of the Order entry to control the display

of groups in a user interface.

Example 4.37

Given the following PDF objects:

1 0 obj <</Type /OCG /Name (Skin)>> endobj

% Optional content groups

2 0 obj <</Type /OCG /Name (Bones)>> endobj

3 0 obj <</Type /OCG /Name (Bark)>> endobj

4 0 obj <</Type /OCG /Name (Wood)>> endobj

5 0 obj

% Configuration dictionary

<< /Order [[(Frog Anatomy) 1 0 R 2 0 R] [(Tree Anatomy) 3 0 R 4 0 R] ] >>

379

SECTION 4.10

Optional Content

A PDF viewer should display the optional content groups as follows:

Frog Anatomy

Skin

Bones

Tree Anatomy

Bark

Wood

Example 4.38

Given the following PDF objects:

% Page contents

/OC /L1 BDC

% Layer 1

/OC /L1a BDC

% Sublayer A of layer 1

0 0 100 100 re f

EMC

/OC /L1b BDC

% Sublayer B of layer 1

0 100 100 100 re f

EMC

<< /L1 1 0 R

% Resource names

/L1a 2 0 R

/L1b 3 0 R

%Optional content groups

1 0 obj <</Type /OCG /Name (Layer 1)>> endobj

2 0 obj <</Type /OCG /Name (Sublayer A)>> endobj

3 0 obj <</Type /OCG /Name (Sublayer B)>> endobj

4 0 obj

% Configuration dictionary

<< /Order [1 0 R [2 0 R 3 0 R]] >>

A PDF viewer should display the OCGs as follows:

Layer 1

Sublayer A

Sublayer B

The AS entry is an auto state array consisting of one or more usage application

dictionaries that specify how viewer applications should automatically set the

state of optional content groups based on external factors, as discussed in the fol-

lowing section.

380

CHAPTER 4

Graphics

Usage and Usage Application Dictionaries

Optional content groups are typically constructed to control the visibility of

graphic objects that are related in some way. Objects can be related in several

ways; for example, a group may contain content in a particular language or con-

tent suitable for viewing at a particular magnification.

An optional content group’s usage dictionary (the value of the Usage entry in an

optional content group dictionary; see Table 4.48) contains information describ-

ing the nature of the content controlled by the group. This dictionary can contain

any combination of the entries shown in Table 4.52.

TABLE 4.52 Entries in an optional content usage dictionary

KEY

TYPE

VALUE

CreatorInfo

dictionary

(Optional) A dictionary used by the creating application to store application-spe-

cific data associated with this optional content group. It contains two required en-

tries:

• Creator: A text string specifying the application that created the group.

• Subtype: A name defining the type of content controlled by the group. Suggest-

ed values include but are not limited to Artwork, for graphic-design or publish-

ing applications, and Technical, for technical designs such as building plans or

schematics.

Additional entries may be included to present information relevant to the creat-

ing application or related applications.

Note: Groups whose Intent entry contains Design typically include a CreatorInfo en-

try.

Language

dictionary

(Optional) A dictionary specifying the language of the content controlled by this

optional content group. It has two entries:

• Lang (required): A text string that specifies a language and possibly a locale (see

Section 10.8.1, “Natural Language Specification”). For example, es-MX repre-

sents Mexican Spanish.

• Preferred (optional): A name whose values may be ON or OFF. Default value:

OFF. It is used by viewer applications when there is a partial match but no exact

match between the system language and the language strings in all usage dic-

tionaries. See “Usage and Usage Application Dictionaries” on page 380 for

more information.

381

SECTION 4.10

Optional Content

KEY

TYPE

VALUE

Export

dictionary

(Optional) A dictionary containing one entry, ExportState, a name whose value

may be ON or OFF. This value indicates the recommended state for content in this

group when the document (or part of it) is saved by a viewer application to a for-

mat that does not support optional content (for example, an earlier version of

PDF or a raster image format).

Zoom

dictionary

(Optional) A dictionary specifying a range of magnifications at which the content

in this optional content group is best viewed. It may contain one or both of the

following entries:

• min: The minimum recommended magnification factor at which the group

should be ON. Default value: 0.

• max: The magnification factor below which the group should be ON. Default

value: infinity.

Print

dictionary

(Optional) A dictionary specifying that the content in this group is intended for

use in printing. It contains the following optional entries:

• Subtype: A name object specifying the kind of content controlled by the group;

for example, Trapping, PrintersMarks and Watermark.

• PrintState: A name that may be ON or OFF, indicating that the group should be

set to that state when the document is printed from a viewer application.

View

dictionary

(Optional) A dictionary that has a single entry, ViewState, a name that may have a

value of ON or OFF, indicating that the group should be set to that state when the

document is opened in a viewer application.

User

dictionary

(Optional) A dictionary specifying one or more users for whom this optional con-

tent group is primarily intended. Each dictionary has two required entries:

• Type: A name object that can be Ind (individual), Ttl (title), or Org (organiza-

tion).

• Name: A text string or array of text strings representing the name(s) of the in-

dividual, position or organization.

PageElement

dictionary

(Optional) A dictionary declaring that the group contains a pagination artifact. It

contains one entry, Subtype, whose value is a name that can be HF (header/foot-

er), FG (foreground image or graphic), BG (background image or graphic), or L

(logo).

While the data in the usage dictionary can be viewed as information for a docu-

ment user to examine, it can also be used by viewer applications to automatically

382

CHAPTER 4

Graphics

manipulate the state of optional content groups based on external factors such as

current system language settings or zoom level. Document authors can use usage

application dictionaries to specify which entries in the usage dictionary should be

consulted to automatically set the state of optional content groups based on such

factors. Usage application dictionaries are listed in the AS entry in an optional

content configuration dictionary (see Table 4.51). If no AS entry is present, states

are not automatically adjusted based on usage information.

A usage application dictionary specifies the rules for which usage entries should

be used by viewer applications to automatically manipulate the state of optional

content groups, which groups should be affected, and under which circumstanc-

es. Table 4.53 shows the entries in a usage application dictionary.

Note: Usage application dictionaries are only intended for use by interactive viewer

applications, not for applications that use PDF as final form output (see “Determin-

ing the State of Optional Content Groups” on page 385 for more information).

TABLE 4.53 Entries in a usage application dictionary

KEY

TYPE

VALUE

Event

name

(Required) A name defining the situation in which this usage application dictio-

nary should be used. May be View, Print, or Export.

OCGs

array

(Optional) An array listing the optional content groups that should have their

states automatically managed based on information in their usage dictionary

(see “Usage and Usage Application Dictionaries” on page 380). Default value: an

empty array, indicating that no groups are affected.

Category

array

(Required) An array of names, each of which corresponds to a usage dictionary

entry (see Table 4.52). When managing the states of the optional content groups

in the OCGs array, each of the corresponding categories in the group’s usage dic-

tionary should be considered.

The Event entry specifies whether the usage settings should be applied during

viewing, printing, or exporting the document. The OCGs entry specifies the set of

optional content groups to which usage settings should be applied. For each of

the groups in OCGs, the entries in its usage dictionary (see Table 4.52) specified

by Category are examined to yield a recommended state for the group. If all the

entries yield a recommended state of ON, the group’s state is set to ON; otherwise,

its state is set to OFF.

383

SECTION 4.10

Optional Content

The entries in the usage dictionary are used as follows:

• View: The recommended state is the value of the ViewState entry. This entry al-

lows a document to contain content that is relevant only when the document is

viewed interactively, such as instructions for how to interact with the docu-

ment.

• Print: The recommended state is the value of the PrintState entry. If PrintState

is not present, the state of the optional content group is left unchanged.

• Export: The recommended state is the value of the ExportState entry.

• Zoom: If the current magnification level of the document is greater than or

equal to min and less than max, an ON state is recommended; otherwise, OFF is

recommended.

• User: The Name entry specifies a name or names to match with the user’s iden-

tification. The Type entry determines how the Name entry is interpreted

(name, title, or organization). If there is an exact match, an ON state is recom-

mended; otherwise OFF is recommended.

• Language: This category allows the selection of content based on the language

and locale of the application. If an exact match to the language and locale is

found among the Lang entries of the optional content groups in the usage ap-

plication dictionary’s OCGs list, all groups that have exact matches receive an

ON recommendation. If no exact match is found, but a partial match is found

(that is, the language matches but not the locale), all partially matching groups

that have Preferred entries with a value of ON receive an ON recommendation.

All other groups receive an OFF recommendation.

Example 4.39 shows the use of an auto state array with usage application dictio-

naries. The AS entry in the default configuration dictionary is an array of three

usage application dictionaries, one for each of the Event values View, Print, and

Export.

Note: While this case is typical, there is no restriction on multiple entries with the

same value of Event, which allows documents with incompatible usage application

dictionaries to be combined into larger documents and have their behavior pre-

served. If a given optional content group appears in more than one OCGs array, its

state is ON only if all categories in all the usage application dictionaries it appears in

recommend a state of ON.

384

CHAPTER 4

Graphics

Example 4.39

/OCProperties

% OCProperties dictionary in document catalog

<< /OCGs [1 0 R 2 0 R 3 0 R 4 0 R]

/D << /BaseState /OFF

% The default configuration

/ON [1 0 R]

/AS [

% Auto state array of usage application dictionaries

<< /Event /View /Category [/Zoom] /OCGs [1 0 R 2 0 R 3 0 R 4 0 R] >>

<< /Event /Print /Category [/Print] /OCGs [4 0 R] >>

<< /Event /Export /Category [/Export] /OCGs [3 0 R 4 0 R] >>

]

1 0 obj

<< /Type /OCG

/Name (20000 foot view)

/Usage << /Zoom << /max 1.0 >> >>

endobj

2 0 obj

<< /Type /OCG

/Name (10000 foot view)

/Usage << /Zoom << /min 1.0 /max 2.0 >> >>

endobj

3 0 obj

<< /Type /OCG

/Name (1000 foot view)

/Usage << /Zoom << /min 2.0 /max 20.0 >>

/Export << /ExportState /OFF >> >>

endobj

4 0 obj

<< /Type /OCG

/Name (Copyright notice)

/Usage << /Print << /PrintState /ON >>

/Export << /ExportState /ON>> >>

endobj

In the example, the usage application dictionary with event type View specifies

that all optional content groups are to have their states managed based on zoom

385

SECTION 4.10

Optional Content

level when viewing. Three groups (objects 1, 2, and 3) contain Zoom usage infor-

mation. Object 4 has none; therefore, it is not affected by zoom level changes. Ob-

ject

3 receives an OFF recommendation when exporting. When printing or

exporting, object 4 receives an ON recommendation.

Determining the State of Optional Content Groups

This section summarizes the rules by which applications make use of the config-

uration and usage application dictionaries to set the state of optional content

groups. For purposes of this discussion, it is useful to distinguish the following

types of applications:

• Viewer applications, such as Acrobat, which allow users to interact with the

document in various ways.

• Design applications, which offer layering features for collecting groups of

graphics together and selectively hiding or viewing them.

Note: The following rules are not meant to apply to design applications; they may

manage their states in an entirely different manner if they choose.

• Aggregating applications, which import PDF files as graphics.

• Printing applications, which print PDF files.

When a document is first opened, its optional content groups are assigned a state

based on the D (default) configuration dictionary in the OCProperties dictionary:

1. The value of BaseState is applied to all the groups.

2. The groups listed in either the ON or OFF array (depending on which one is

opposite to BaseState) have their states adjusted.

This state is the recommended state for printing and aggregating applications,

which should not apply the changes based on usage application dictionaries de-

scribed below. However, for more advanced functionality, they may provide user

control for manipulating the individual states of optional content groups.

Note: Viewer applications should also provide users with an option to view docu-

ments in this state (that is, to disable the automatic adjustments discussed below).

This option permits an accurate preview of the content as it will appear when placed

into an aggregating application or sent to a stand-alone printing system.

386

CHAPTER 4

Graphics

The remaining discussion in this section applies only to viewer applications. Such

applications should examine the AS array for usage application dictionaries that

have an Event of type View. For each one found, the groups listed in its OCGs ar-

ray should be adjusted as described in “Usage and Usage Application Dictionar-

ies” on page 380.

Subsequently, the document is ready for interactive viewing by a user. Whenever

there is a change to a factor that the usage application dictionaries with event type

View depend on (such as zoom level), the corresponding dictionaries should be

reapplied.

The user may manipulate optional content group states manually or by triggering

SetOCGState actions (see “Set-OCG-State Actions” on page 667) by, for example,

clicking links or bookmarks. Manual changes override the states that were set au-

tomatically. The states of these groups remain overridden and are not readjusted

based on usage application dictionaries with event type View as long as the docu-

ment is open (or until the user reverts the document to its original state).

When a document is printed by a viewer application, usage application dictionar-

ies with an event type Print are applied over the current states of optional content

groups. These changes persist only for the duration of the print operation; then

all groups revert to their prior states.

Similarly, when a document is exported to an earlier version of PDF or other for-

mat that does not support optional content, usage application dictionaries with

an event type Export are applied over the current states of optional content

groups. Changes persist only for the duration of the export operation; then all

groups revert to their prior states.

Note: Although the event types Print and Export have identically named counter-

parts that are usage categories, the corresponding usage application dictionaries are

permitted to specify that other categories may be applied.

CHAPTER 5

Text

This chapter describes the special facilities in PDF for dealing with text— specifi-

cally, for representing characters with glyphs from fonts. A glyph is a graphical

shape and is subject to all graphical manipulations, such as coordinate transfor-

mation. Because of the importance of text in most page descriptions, PDF pro-

vides higher-level facilities that permit an application to describe, select, and

render glyphs conveniently and efficiently.

The first section is a general description of how glyphs from fonts are painted on

the page. Subsequent sections cover the following topics in detail:

• Text state. A subset of the graphics state parameters pertain to text, including

parameters that select the font, scale the glyphs to an appropriate size, and

accomplish other graphical effects.

• Text objects and operators. The text operators specify the glyphs to be painted,

represented by string objects whose values are interpreted as sequences of char-

acter codes. A text object encloses a sequence of text operators and associated

parameters.

• Font data structures. Font dictionaries and associated data structures provide

information that a consumer application needs to interpret the text and posi-

tion the glyphs properly. The definitions of the glyphs themselves are contained

in font programs, which may be embedded in the PDF file, built into the appli-

cation, or obtained from an external font file.

387

388

CHAPTER 5

Text

5.1

Organization and Use of Fonts

A character is an abstract symbol, whereas a glyph is a specific graphical render-

ing of a character. For example, the glyphs A, A, and A are renderings of the ab-

stract

“A” character. Historically these two terms have often been used

interchangeably in computer typography (as evidenced by the names chosen for

some PDF dictionary keys and PostScript operators), but advances in this area

have made the distinction more meaningful. Consequently, this book distin-

guishes between characters and glyphs, though with some residual names that are

inconsistent.

Glyphs are organized into fonts. A font defines glyphs for a particular character

set; for example, the Helvetica and Times fonts define glyphs for a set of standard

Latin characters. A font for use with a PDF consumer application is prepared in

the form of a program. Such a font program is written in a special-purpose lan-

guage, such as the Type 1 or TrueType font format, that is understood by a special-

ized font interpreter.

In PDF, the term font refers to a font dictionary, a PDF object that identifies the

font program and contains additional information about it. There are several dif-

ferent font types, identified by the Subtype entry of the font dictionary.

For most font types, the font program is defined in a separate font file, which may

be either embedded in a PDF stream object or obtained from an external source.

The font program contains glyph descriptions that generate glyphs.

A content stream paints glyphs on the page by specifying a font dictionary and a

string object that is interpreted as a sequence of one or more character codes

identifying glyphs in the font. This operation is called showing the text string; the

text strings drawn in this way are called show strings. The glyph description con-

sists of a sequence of graphics operators that produce the specific shape for that

character in this font. To render a glyph, the application executes the glyph de-

scription.

Programmers who have experience with scan conversion of general shapes may

be concerned about the amount of computation that this description seems to

imply. However, this is only the abstract behavior of glyph descriptions and font

programs, not how they are implemented. In fact, an efficient implementation

can be achieved through careful caching and reuse of previously rendered glyphs.

389

SECTION 5.1

Organization and Use of Fonts

5.1.1

Basics of Showing Text

Example 5.1 illustrates the most straightforward use of a font. The text ABC is

placed 10 inches from the bottom of the page and 4 inches from the left edge, us-

ing 12-point Helvetica.

Example 5.1

/F13 12 Tf

288 720 Td

( ABC ) Tj

The five lines of this example perform the following steps:

1. Begin a text object.

2. Set the font and font size to use, installing them as parameters in the text state.

(The font resource identified by the name F13 specifies the font externally

known as Helvetica.)

3. Specify a starting position on the page, setting parameters in the text object.

4. Paint the glyphs for a string of characters at that position.

5. End the text object.

The following paragraphs explain these operations in more detail.

To paint glyphs, a content stream must first identify the font to be used. The Tf

operator specifies the name of a font resource—that is, an entry in the Font

subdictionary of the current resource dictionary. The value of that entry is a font

dictionary. The font dictionary identifies the font’s externally known name, such

as Helvetica, and supplies some additional information that the application needs

to paint glyphs from that font. The font dictionary optionally provides the defini-

tion of the font program itself.

Note: The font resource name presented to the Tf operator is arbitrary, as are the

names for all kinds of resources. It bears no relationship to an actual font name,

such as Helvetica.

Example 5.2 illustrates an excerpt from the current page’s resource dictionary,

which defines the font dictionary that is referenced as F13 in Example 5.1.

390

CHAPTER 5

Text

Example 5.2

/Resources

<< /Font << /F13 23 0 R >>

23 0 obj

<< /Type /Font

/Subtype /Type1

/BaseFont /Helvetica

endobj

A font defines the glyphs for one standard size. This standard is arranged so that

the nominal height of tightly spaced lines of text is 1 unit. In the default user

coordinate system, this means the standard glyph size is 1 unit in user space, or

1 ⁄ 72 inch. (In PDF 1.6, the size of this unit may be specified as greater than 1 ⁄ 72

inch by means of the UserUnit entry of the page dictionary; see Table 3.27.) The

standard-size font must then be scaled to be usable. The scale factor is specified

as the second operand of the Tf operator, thereby setting the text font size param-

eter in the graphics state. Example 5.1 establishes the Helvetica font with a 12-

unit size in the graphics state.

Once the font has been selected and scaled, it can be used to paint glyphs. The Td

operator adjusts the current text position (actually, the translation components of

the text matrix, as described in Section 5.3.1, “Text-Positioning Operators”).

When executed for the first time after BT, Td establishes the text position in the

current user coordinate system. This determines the position on the page at

which to begin painting glyphs.

The Tj operator takes a string operand and paints the corresponding glyphs, us-

ing the current font and other text-related parameters in the graphics state. In Ex-

ample 5.1, the Tj operator treats each element of the string (an integer in the

range 0 to 255) as a character code. Each code selects a glyph description in the

font, and the glyph description is executed to paint that glyph on the page. This is

the behavior of Tj for simple fonts, such as ordinary Latin text fonts. Interpreta-

tion of the string as a sequence of character codes is more complex for composite

fonts, described in Section 5.6, “Composite Fonts.”

Note: What these steps produce on the page is not a 12-point glyph, but rather a

12-unit glyph, where the unit size is that of the text space at the time the glyphs are

rendered on the page. The actual size of the glyph is determined by the text matrix

391

SECTION 5.1

Organization and Use of Fonts

(T_m ) in the text object, several text state parameters, and the current transforma-

tion matrix (CTM) in the graphics state; see Section 5.3.3, “Text Space Details.” If

the text space is later scaled to make the unit size 1 centimeter, painting glyphs from

the same 12-unit font generates results that are 12 centimeters high.

5.1.2

Achieving Special Graphical Effects

Normal uses of Tj and other glyph-painting operators cause black-filled glyphs to

be painted. Other effects can be obtained by combining font operators with gen-

eral graphics operators.

The color used for painting glyphs is the current color in the graphics state: either

the nonstroking color or the stroking color (or both), depending on the text ren-

dering mode (see Section 5.2.5, “Text Rendering Mode”). The default color is

black, but other colors can be obtained by executing an appropriate color-setting

operator or operators (see Section 4.5.7, “Color Operators”) before painting the

glyphs. Example 5.3 uses text rendering mode 0 and the g operator to fill glyphs

in 50 percent gray, as shown in Figure 5.1.

Example 5.3

/F13 48 Tf

20 40 Td

0 Tr

0.5 g

( ABC ) Tj

ABC

FIGURE 5.1 Glyphs painted in 50% gray

392

CHAPTER 5

Text

Other graphical effects can be achieved by treating the glyph outline as a path in-

stead of filling it. The text rendering mode parameter in the graphics state speci-

fies whether glyph outlines are to be filled, stroked, used as a clipping boundary,

or some combination of these effects. (This parameter does not apply to Type 3

fonts.)

Example 5.4 treats glyph outlines as a path to be stroked. The Tr operator sets the

text rendering mode to 1 (stroke). The w operator sets the line width to 2 units in

user space. Given those graphics state parameters, the Tj operator strokes the

glyph outlines with a line 2 points thick (see Figure 5.2).

Example 5.4

/F13 48 Tf

20 38 Td

1 Tr

2 w

( ABC ) Tj

ABC

FIGURE 5.2 Glyph outlines treated as a stroked path

Example 5.5 treats the glyphs’ outlines as a clipping boundary. The Tr operator

sets the text rendering mode to 7 (clip), causing the subsequent Tj operator to

impose the glyph outlines as the current clipping path. All subsequent painting

operations mark the page only within this path, as illustrated in Figure 5.3. This

state persists until some earlier clipping path is reinstated by the Q operator.

393

SECTION 5.1

Organization and Use of Fonts

Example 5.5

/F13 48 Tf

20 38 Td

7 Tr

( ABC ) Tj

… Graphics operators to draw a starburst…

ABC

FIGURE 5.3 Graphics clipped by a glyph path

5.1.3

Glyph Positioning and Metrics

A glyph’s width—formally, its horizontal displacement—is the amount of space it

occupies along the baseline of a line of text that is written horizontally. In other

words, it is the distance the current text position moves (by translating text space)

when the glyph is painted. Note that the width is distinct from the dimensions of

the glyph outline.

In some fonts, the width is constant; it does not vary from glyph to glyph. Such

fonts are called fixed-pitch or monospaced. They are used mainly for typewriter-

style printing. However, most fonts used for high-quality typography associate a

different width with each glyph. Such fonts are called proportional or variable-

pitch fonts. In either case, the Tj operator positions the consecutive glyphs of a

string according to their widths.

The width information for each glyph is stored both in the font dictionary and in

the font program itself. (The two sets of widths must be identical; storing this in-

formation in the font dictionary, although redundant, enables a consumer appli-

394

CHAPTER 5

Text

cation to determine glyph positioning without having to look inside the font

program.) The operators for showing text are designed on the assumption that

glyphs are ordinarily positioned according to their standard widths. However,

means are provided to vary the positioning in certain limited ways. For example,

the TJ operator enables the text position to be adjusted between any consecutive

pair of glyphs corresponding to characters in a text string. There are graphics

state parameters to adjust character and word spacing systematically.

In addition to width, a glyph has several other metrics that influence glyph posi-

tioning and painting. For most font types, this information is largely internal to

the font program and is not specified explicitly in the PDF font dictionary. How-

ever, in a Type 3 font, all metrics are specified explicitly (see Section 5.5.4, “Type

3 Fonts”).

The glyph coordinate system is the space in which an individual character’s glyph

is defined. All path coordinates and metrics are interpreted in glyph space. For all

font types except Type 3, the units of glyph space are one-thousandth of a unit of

text space; for a Type 3 font, the transformation from glyph space to text space is

defined by a font matrix specified in an explicit FontMatrix entry in the font.

Figure 5.4 shows a typical glyph outline and its metrics.

Glyph

bounding

box

Next

Glyph

glyph

origin

Glyph width

FIGURE 5.4 Glyph metrics

The glyph origin is the point (0, 0) in the glyph coordinate system. Tj and other

text-showing operators position the origin of the first glyph to be painted at the

origin of text space. For example, the following code adjusts the origin of text

395

SECTION 5.1

Organization and Use of Fonts

space to (40, 50) in the user coordinate system and then places the origin of the A

glyph at that point:

40 50 Td

( ABC ) Tj

The glyph displacement is the distance from the glyph’s origin to the point at

which the origin of the next glyph should normally be placed when painting the

consecutive glyphs of a line of text. This distance is a vector (called the displace-

ment vector) in the glyph coordinate system; it has horizontal and vertical com-

ponents. (A displacement that is horizontal is usually called a width.) Most

Western writing systems, including those based on the Latin alphabet, have a

positive horizontal displacement and a zero vertical displacement. Some Asian

writing systems have a nonzero vertical displacement. In all cases, the text-show-

ing operators transform the displacement vector into text space and then trans-

late text space by that amount.

The glyph bounding box is the smallest rectangle (oriented with the axes of the

glyph coordinate system) that just encloses the entire glyph shape. The bounding

box is expressed in terms of its left, bottom, right, and top coordinates relative to

the glyph origin in the glyph coordinate system.

In some writing systems, text is frequently aligned in two different directions. For

example, it is common to write Japanese and Chinese glyphs either horizontally

or vertically. To handle this, a font can optionally contain a second set of metrics

for each glyph. Which set of metrics to use is selected according to a writing

mode, where 0 specifies horizontal writing and 1 specifies vertical writing. This

feature is available only for composite fonts, discussed in Section 5.6, “Composite

Fonts.”

When a glyph has two sets of metrics, each set specifies a glyph origin and a dis-

placement vector for that writing mode. In vertical writing, the glyph position is

described by a position vector from the origin used for horizontal writing

(origin 0) to the origin used for vertical writing (origin 1). Figure 5.5 illustrates

the metrics for the two writing modes:

• The left diagram illustrates the glyph metrics associated with writing mode 0,

horizontal writing. The coordinates ll and ur specify the bounding box of the

glyph relative to origin 0. w0 is the displacement vector that specifies how the

396

CHAPTER 5

Text

text position is changed after the glyph is painted in writing mode 0; its vertical

component is always 0.

• The center diagram illustrates writing mode 1, vertical writing. w1 is the dis-

placement vector for writing mode 1; its horizontal component is always 0.

• In the right diagram, v is a position vector defining the position of origin 1 rel-

ative to origin 0.

Origin 1

Origin

New text

position

New text position

Writing mode 0

Writing mode 1

Mode 1 relative to mode 0

(horizontal)

(vertical)

FIGURE 5.5 Metrics for horizontal and vertical writing modes

Glyph metric information is also available separately in the form of Adobe font

metrics (AFM) and Adobe composite font metrics (ACFM) files. These files are

for use by application programs that generate PDF page descriptions and must

make formatting decisions based on the widths and other metrics of glyphs. Also

available in the AFM and ACFM files is kerning information, which allows an

application generating a PDF file to determine spacing adjustments between

glyphs depending on context. Specifications for the AFM and ACFM file formats

are available in Adobe Technical Note #5004, Adobe Font Metrics File Format

Specification; the files can be obtained from the Adobe Solutions Network Web

site (see the Bibliography).

5.2

Text State Parameters and Operators

The text state comprises those graphics state parameters that only affect text.

There are nine parameters in the text state (see Table 5.1).

397

SECTION 5.2

Text State Parameters and Operators

TABLE 5.1 Text state parameters

PARAMETER

DESCRIPTION

Character spacing

Word spacing

T_h

Horizontal scaling

T_l

Leading

T_f

Text font

T_fs

Text font size

Text rendering mode

Tmode

Text rise

Trise

T_k

Text knockout

Except for the self-explanatory T_f and T_fs , these parameters are discussed further

in the following sections. (As described in Section 5.3, “Text Objects,” three addi-

tional text-related parameters are defined only within a text object: T_m , the text

matrix; T_lm , the text line matrix; and T_rm , the text rendering matrix.) The values

of the text state parameters are consulted when text is positioned and shown

(using the operators described in Sections 5.3.1, “Text-Positioning Operators,”

and 5.3.2, “Text-Showing Operators”). In particular, the spacing and scaling

parameters participate in a computation described in Section 5.3.3, “Text Space

Details.” The text state parameters can be set using the operators listed in Table

5.2.

Note: The text knockout parameter, T_k , is set through the TK entry in a graphics

state parameter dictionary by using the gs operator (see Section 4.3.4, “Graphics

State Parameter Dictionaries”). There is no specific operator for setting this parame-

ter.

The text state operators can appear outside text objects, and the values they set

are retained across text objects in a single content stream. Like other graphics

state parameters, these parameters are initialized to their default values at the

beginning of each page.

398

CHAPTER 5

Text

TABLE 5.2 Text state operators

OPERANDS

OPERATOR

DESCRIPTION

charSpace

Set the character spacing, T_c , to charSpace, which is a number expressed in un-

scaled text space units. Character spacing is used by the Tj, TJ, and ' operators.

Initial value: 0.

wordSpace

Set the word spacing, T_w, to wordSpace, which is a number expressed in unscaled

text space units. Word spacing is used by the Tj, TJ, and ' operators. Initial

value: 0.

scale

Set the horizontal scaling, T_h , to (scale ÷ 100). scale is a number specifying the

percentage of the normal width. Initial value: 100 (normal width).

leading

Set the text leading, T_l , to leading, which is a number expressed in unscaled text

space units. Text leading is used only by the T*, ', and " operators. Initial value: 0.

font size

Set the text font, T_f , to font and the text font size, T_fs , to size. font is the name of a

font resource in the Font subdictionary of the current resource dictionary; size is

a number representing a scale factor. There is no initial value for either font or

size; they must be specified explicitly by using Tf before any text is shown.

render

Set the text rendering mode, T_mode , to render, which is an integer. Initial value: 0.

rise

Set the text rise, T_rise , to rise, which is a number expressed in unscaled text space

units. Initial value: 0.

Note that some of these parameters are expressed in unscaled text space units.

This means that they are specified in a coordinate system that is defined by the

text matrix, T_m but is not scaled by the font size parameter, T_fs .

5.2.1

Character Spacing

The character-spacing parameter, T_c , is a number specified in unscaled text space

units (although it is subject to scaling by the T_h parameter if the writing mode is

horizontal). When the glyph for each character in the string is rendered, T_c is

added to the horizontal or vertical component of the glyph’s displacement,

depending on the writing mode. (See Section 5.1.3, “Glyph Positioning and

Metrics,” for a discussion of glyph displacements.) In the default coordinate sys-

tem, horizontal coordinates increase from left to right and vertical coordinates

from bottom to top. Therefore, for horizontal writing, a positive value of T_c has

399

SECTION 5.2

Text State Parameters and Operators

the effect of expanding the distance between glyphs (see Figure 5.6), whereas for

vertical writing, a negative value of T_c has this effect.

T_c = 0 (default)

Character

T_c = 0.25

Character

FIGURE 5.6 Character spacing in horizontal writing

5.2.2

Word Spacing

Word spacing works the same way as character spacing but applies only to the

space character, code 32. The word-spacing parameter, T_w, is added to the

glyph’s horizontal or vertical displacement (depending on the writing mode). For

horizontal writing, a positive value for T_w has the effect of increasing the spacing

between words. For vertical writing, a positive value for T_w decreases the spacing

between words (and a negative value increases it), since vertical coordinates in-

crease from bottom to top. Figure 5.7 illustrates the effect of word spacing in

horizontal writing.

T_w = 0 (default)

Word Space

T_w = 2.5

Word Space

FIGURE 5.7 Word spacing in horizontal writing

Note: Word spacing is applied to every occurrence of the single-byte character code

32 in a string when using a simple font or a composite font that defines code 32 as a

single-byte code. It does not apply to occurrences of the byte value 32 in multiple-

byte codes.

400

CHAPTER 5

Text

5.2.3

Horizontal Scaling

The horizontal scaling parameter, T_h , adjusts the width of glyphs by stretching or

compressing them in the horizontal direction. Its value is specified as a percent-

age of the normal width of the glyphs, with 100 being the normal width. The scal-

ing always applies to the horizontal coordinate in text space, independently of the

writing mode. It affects both the glyph’s shape and its horizontal displacement

(that is, its displacement vector). If the writing mode is horizontal, it also affects

the spacing parameters T_c and T_w, as well as any positioning adjustments per-

formed by the TJ operator. Figure 5.8 shows the effect of horizontal scaling.

T_h = 100 (default)

Word

T_h = 50

WordWord

FIGURE 5.8 Horizontal scaling

5.2.4

Leading

The leading parameter, T_l , is measured in unscaled text space units . It specifies

the vertical distance between the baselines of adjacent lines of text, as shown in

Figure 5.9.

This is 12-point text with

14.5-point leading

Leading

FIGURE 5.9 Leading

The leading parameter is used by the TD, T*, ', and " operators; see Table 5.5 on

page 406 for a precise description of its effects. This parameter always applies to

the vertical coordinate in text space, independently of the writing mode.

401

SECTION 5.2

Text State Parameters and Operators

5.2.5

Text Rendering Mode

The text rendering mode, T_mode , determines whether showing text causes glyph

outlines to be stroked, filled, used as a clipping boundary, or some combination

of the three. Stroking, filling, and clipping have the same effects for a text object

as they do for a path object (see Sections 4.4.2, “Path-Painting Operators,” and

4.4.3, “Clipping Path Operators”), although they are specified in an entirely dif-

ferent way. The graphics state parameters affecting those operations, such as line

width, are interpreted in user space rather than in text space.

Note: The text rendering mode has no effect on text displayed in a Type 3 font (see

Section 5.5.4, “Type 3 Fonts”).

The text rendering modes are shown in Table 5.3. In the examples, a stroke color

of black and a fill color of light gray are used. For the clipping modes (4 to 7), a

series of lines has been drawn through the glyphs to show where the clipping

occurs.

If the text rendering mode calls for filling, the current nonstroking color in the

graphics state is used; if it calls for stroking, the current stroking color is used. In

modes that perform both filling and stroking, the effect is as if each glyph outline

were filled and then stroked in separate operations. If any of the glyphs overlap,

the result is equivalent to filling and stroking them one at a time, producing the

appearance of stacked opaque glyphs, rather than first filling and then stroking

them all at once (see implementation note 57 in Appendix H). In the transparent

imaging model, these combined filling and stroking modes are subject to further

considerations; see “Special Path-Painting Considerations” on page 569.

The behavior of the clipping modes requires further explanation. Glyph outlines

begin accumulating if a BT operator is executed while the text rendering mode is

set to a clipping mode or if it is set to a clipping mode within a text object. Glyphs

accumulate until the text object is ended by an ET operator; the text rendering

mode must not be changed back to a nonclipping mode before that point.

402

CHAPTER 5

Text

TABLE 5.3 Text rendering modes

MODE

EXAMPLE

DESCRIPTION

Fill text.

Stroke text.

Fill, then stroke text.

Neither fill nor stroke text (invisible).

Fill text and add to path for clipping (see above).

Stroke text and add to path for clipping.

Fill, then stroke text and add to path for clipping.

Add text to path for clipping.

At the end of the text object, the accumulated glyph outlines, if any, are combined

into a single path, treating the individual outlines as subpaths of that path and ap-

plying the nonzero winding number rule (see “Nonzero Winding Number Rule”

on page 232). The current clipping path in the graphics state is set to the intersec-

tion of this path with the previous clipping path. As is the case for path objects,

this clipping occurs after all filling and stroking operations for the text object

have occurred. It remains in effect until some previous clipping path is restored

by an invocation of the Q operator.

Note: If no glyphs are shown or if the only glyphs shown have no outlines (for exam-

ple, if they are space characters), no clipping occurs.

403

SECTION 5.2

Text State Parameters and Operators

5.2.6

Text Rise

Text rise, T_rise , specifies the distance, in unscaled text space units, to move the

baseline up or down from its default location. Positive values of text rise move the

baseline up. Adjustments to the baseline are useful for drawing superscripts or

subscripts. The default location of the baseline can be restored by setting the text

rise to 0. Figure 5.10 illustrates the effect of the text rise. Text rise always applies

to the vertical coordinate in text space, regardless of the writing mode.

(This text is ) Tj

5 Ts

This text is superscripted

(superscripted) Tj

(This text is ) Tj

This text is

-5 Ts

subscripted

(subscripted) Tj

(This ) Tj

-5 Ts

(text ) Tj

moves

5 Ts

This

around

text

(moves ) Tj

0 Ts

(around) Tj

FIGURE 5.10 Text rise

5.2.7

Text Knockout

The text knockout parameter, T_k (PDF 1.4), is a boolean flag that determines

what text elements are considered elementary objects for purposes of color com-

positing in the transparent imaging model. Unlike other text state parameters,

there is no specific operator for setting this parameter; it can be set only through

the TK entry in a graphics state parameter dictionary by using the gs operator (see

Section 4.3.4, “Graphics State Parameter Dictionaries”).

The text knockout parameter applies only to entire text objects; it may not be set

between the BT and ET operators delimiting a text object. Its initial value is true. If

its value is false, each glyph in a text object is treated as a separate elementary ob-

ject; when glyphs overlap, they composite with one another.

404

CHAPTER 5

Text

If the parameter is true, all glyphs in the text object are treated together as a single

elementary object; when glyphs overlap, later glyphs overwrite (“knock out”) ear-

lier ones in the area of overlap. This behavior is equivalent to treating the entire

text object as if it were a non-isolated knockout transparency group; see Section

7.3.5, “Knockout Groups.” Transparency parameters are applied to the glyphs in-

dividually rather than to the implicit transparency group as a whole:

• Graphics state parameters, including transparency parameters, are inherited

from the context in which the text object appears. They are not saved and re-

stored, nor are the transparency parameters reset at the beginning of the trans-

parency group (as they are when a transparency group XObject is explicitly

invoked). Changes made to graphics state parameters within the text object

persist beyond the end of the text object.

• After the implicit transparency group for the text object has been completely

evaluated, the group results are composited with the backdrop, using the

Normal blend mode and alpha and soft mask values of 1.0.

5.3

Text Objects

A PDF text object consists of operators that can show text strings, move the text

position, and set text state and certain other parameters. In addition, three pa-

rameters are defined only within a text object and do not persist from one text

object to the next:

• T_m , the text matrix

• T_lm , the text line matrix

• T_rm , the text rendering matrix, which is actually just an intermediate result that

combines the effects of text state parameters, the text matrix (T_m ), and the cur-

rent transformation matrix

A text object begins with the BT operator and ends with the ET operator, as shown

below and described in Table 5.4.

… Zero or more text operators or other allowed operators…

405

SECTION 5.3

Text Objects

TABLE 5.4 Text object operators

OPERANDS OPERATOR DESCRIPTION

—

Begin a text object, initializing the text matrix, T_m , and the text line matrix, T_lm , to

the identity matrix. Text objects cannot be nested; a second BT cannot appear before

an ET.

—

End a text object, discarding the text matrix.

These specific categories of text-related operators can appear in a text object:

• Text state operators, described in Section 5.2, “Text State Parameters and Oper-

ators”

• Text-positioning operators, described in Section 5.3.1, “Text-Positioning Opera-

tors”

• Text-showing operators, described in Section 5.3.2, “Text-Showing Operators”

The latter two sections also provide further details about the text object parame-

ters described above. The other operators that can appear in a text object are

those related to the general graphics state, color, and marked content, as shown in

Figure 4.1 on page 197.

Note: If a content stream does not contain any text, the Text procedure set may be

omitted (see Section 10.1, “Procedure Sets”). In those circumstances, no text opera-

tors (including operators that merely set the text state) may be present in the content

stream, since those operators are defined in the same procedure set.

Note: Although text objects cannot be statically nested, text might be shown using a

Type 3 font whose glyph descriptions include any graphics objects, including another

text object. Likewise, the current color might be a tiling pattern whose pattern cell

includes a text object.

406

CHAPTER 5

Text

5.3.1

Text-Positioning Operators

Text space is the coordinate system in which text is shown. It is defined by the

text matrix, T_m , and the text state parameters T_fs , T_h , and T_rise , which together

determine the transformation from text space to user space. Specifically, the ori-

gin of the first glyph shown by a text-showing operator is placed at the origin of

text space. If text space has been translated, scaled, or rotated, then the position,

size, or orientation of the glyph in user space is correspondingly altered.

TABLE 5.5 Text-positioning operators

OPERANDS

OPERATOR

DESCRIPTION

t_x t_y

Move to the start of the next line, offset from the start of the current line by

(t_x , t_y ). t_x and t_y are numbers expressed in unscaled text space units. More pre-

cisely, this operator performs the following assignments:

0 0

T_m = Tlm

1 0

T_lm

t_x t_y 1

t_x t_y

Move to the start of the next line, offset from the start of the current line by

(t_x , t_y ). As a side effect, this operator sets the leading parameter in the text state.

This operator has the same effect as the following code:

−t_y TL

t_x t_y Td

a b c

d e

Set the text matrix, T_m , and the text line matrix, T_lm :

a b 0

T_m = Tlm

c d 0

e f

The operands are all numbers, and the initial value for T_m and T_lm is the identity

matrix, [ 1 0 0 1 0 0 ]. Although the operands specify a matrix, they are passed

to Tm as six separate numbers, not as an array.

The matrix specified by the operands is not concatenated onto the current text

matrix, but replaces it.

—

Move to the start of the next line. This operator has the same effect as the code

0 T_l Td

where T_l is the current leading parameter in the text state.

407

SECTION 5.3

Text Objects

At the beginning of a text object, T_m is the identity matrix; therefore, the origin of

text space is initially the same as that of user space. The text-positioning operators,

described in Table 5.5, alter T_m and thereby control the placement of glyphs that

are subsequently painted. Also, the text-showing operators, described in Table 5.6

in the next section, update T_m (by altering its e and f translation components) to

take into account the horizontal or vertical displacement of each glyph painted as

well as any character or word-spacing parameters in the text state.

Additionally, a text object keeps track of a text line matrix, T_lm , which captures

the value of T_m at the beginning of a line of text. This is convenient for aligning

evenly spaced lines of text. The text-positioning and text-showing operators read

and set T_lm on specific occasions mentioned in Tables 5.5 and 5.6.

Note: The text-positioning operators can appear only within text objects.

5.3.2

Text-Showing Operators

The text-showing operators (Table 5.6) show text on the page, repositioning text

space as they do so. All of the operators interpret the text string and apply the text

state parameters as described below.

TABLE 5.6 Text-showing operators

OPERANDS

OPERATOR

DESCRIPTION

string

Show a text string.

string

Move to the next line and show a text string. This operator has the same effect as

the code

string Tj

a_w a_c string

Move to the next line and show a text string, using a_w as the word spacing and a_c

as the character spacing (setting the corresponding parameters in the text state).

a_w and a_c are numbers expressed in unscaled text space units. This operator has

the same effect as the following code:

aw Tw

a_c Tc

string '

408

CHAPTER 5

Text

OPERANDS

OPERATOR

DESCRIPTION

array

Show one or more text strings, allowing individual glyph positioning (see imple-

mentation note 58 in Appendix H). Each element of array can be a string or a

number. If the element is a string, this operator shows the string. If it is a num-

ber, the operator adjusts the text position by that amount; that is, it translates the

text matrix, T_m . The number is expressed in thousandths of a unit of text space

(see Section 5.3.3, “Text Space Details,” and implementation note 59 in Appen-

dix H). This amount is subtracted from the current horizontal or vertical coordi-

nate, depending on the writing mode. In the default coordinate system, a

positive adjustment has the effect of moving the next glyph painted either to the

left or down by the given amount. Figure 5.11 shows an example of the effect of

passing offsets to TJ.

[ (AWAY again) ] TJ

AWAY again

[ (A) 120 (W) 120 (A) 95 (Y again) ] TJ

AWAY again

FIGURE 5.11 Operation of the TJ operator in horizontal writing

Note: The text-showing operators can appear only within text objects.

A string operand of a text-showing operator is interpreted as a sequence of char-

acter codes identifying the glyphs to be painted. With most font types, each byte

of the string is treated as a separate character code. The character code is then

looked up in the font’s encoding to select the glyph, as described in Section 5.5.5,

“Character Encoding.”

Beginning with PDF 1.2, a string may be shown in a composite font that uses

multiple-byte codes to select some of its glyphs. In that case, one or more consec-

utive bytes of the string are treated as a single character code. The code lengths

and the mappings from codes to glyphs are defined in a data structure called a

CMap, described in Section 5.6, “Composite Fonts.”

The strings must conform to the syntax for string objects. When a string is writ-

ten by enclosing the data in parentheses, bytes whose values are the same as those

409

SECTION 5.3

Text Objects

of the ASCII characters left parenthesis (40), right parenthesis (41), and backslash

(92) must be preceded by a backslash character. All other byte values between 0

and 255 may be used in a string object. These rules apply to each individual byte

in a string object, whether the string is interpreted by the text-showing operators

as single-byte or multiple-byte character codes.

Strings presented to the text-showing operators may be of any length—even a

single character code per string—and may be placed on the page in any order.

The grouping of glyphs into strings has no significance for the display of text.

Showing multiple glyphs with one invocation of a text-showing operator such as

Tj produces the same results as showing them with a separate invocation for each

glyph. However, the performance of text searching (and other text extraction op-

erations) is significantly better if the text strings are as long as possible and are

shown in natural reading order.

Note: In some cases, the text that is extracted can vary depending on the grouping of

glyphs into strings. See, for example, “Reverse-Order Show Strings” on page 890.

5.3.3

Text Space Details

As stated in Section 5.3.1, “Text-Positioning Operators,” text is shown in text

space, which is defined by the combination of the text matrix, T_m , and the text

state parameters T_fs , T_h , and T_rise . This determines how text coordinates are

transformed into user space. Both the glyph’s shape and its displacement (hori-

zontal or vertical) are interpreted in text space.

Note: Glyphs are actually defined in glyph space, whose definition varies according

to the font type as discussed in Section 5.1.3, “Glyph Positioning and Metrics.” Glyph

coordinates are first transformed from glyph space to text space before being subject-

ed to the transformations described below.

The entire transformation from text space to device space can be represented by a

text rendering matrix, T_rm :

T_fs × T_h

T_rm

T_fs

T_m

× CTM

T_rise

410

CHAPTER 5

Text

Trm is a temporary matrix; conceptually, it is recomputed before each glyph is

painted during a text-showing operation.

After the glyph is painted, the text matrix is updated according to the glyph dis-

placement and any spacing parameters that apply. First, a combined displacement

is computed, denoted by t_x in horizontal writing mode or t_y in vertical writing

mode (the variable corresponding to the other writing mode is set to 0):

T_j

⎛

⎞

t_x

- -----------

T_fs

T_c + T_w

T_h

⎝

1000⎠

⎠

T_j

⎛

⎞

t_y

- -----------

T_fs

T_c +Tw

⎝

1000⎠

where

w0 and w1 are the glyph’s horizontal and vertical displacements

Tj is a position adjustment specified by a number in a TJ array, if any

T_fs and T_h are the current text font size and horizontal scaling parameters in the

graphics state

and T_w are the current character- and word-spacing parameters in the

graphics state, if applicable

The text matrix is then updated as follows:

T_m

t_x t_y 1

5.4

Introduction to Font Data Structures

A font is represented in PDF as a dictionary specifying the type of font, its Post-

Script name, its encoding, and information that can be used to provide a substi-

tute when the font program is not available. Optionally, the font program can be

embedded as a stream object in the PDF file.

The font types are distinguished by the Subtype entry in the font dictionary.

Table 5.7 lists the font types defined in PDF. Type 0 fonts are called composite

fonts; other types of fonts are called simple fonts. In addition to fonts, PDF sup-

411

SECTION 5.4

Introduction to Font Data Structures

ports two classes of font-related objects, called CIDFonts and CMaps, described in

Section 5.6.1, “CID-Keyed Fonts Overview.” CIDFonts are listed in Table 5.7 be-

cause, like fonts, they are collections of glyphs; however, a CIDFont is never used

directly but only as a component of a Type 0 font.

TABLE 5.7 Font types

TYPE

SUBTYPE VALUE

DESCRIPTION

Type 0

Type0

(PDF 1.2) A composite font—a font composed of glyphs from a descendant

CIDFont (see Section 5.6, “Composite Fonts”)

Type 1

Type1

A font that defines glyph shapes using Type 1 font technology (see Section

5.5.1, “Type 1 Fonts”).

MMType1

A multiple master font—an extension of the Type 1 font that allows the gen-

eration of a wide variety of typeface styles from a single font (see “Multiple

Master Fonts” on page 416)

Type 3

Type3

A font that defines glyphs with streams of PDF graphics operators (see Sec-

tion 5.5.4, “Type 3 Fonts”)

TrueType

A font based on the TrueType font format (see Section 5.5.2, “TrueType

Fonts”)

CIDFont

CIDFontType0

(PDF 1.2) A CIDFont whose glyph descriptions are based on Type 1 font

technology (see Section 5.6.3, “CIDFonts”)

CIDFontType2

(PDF 1.2) A CIDFont whose glyph descriptions are based on TrueType font

technology (see Section 5.6.3, “CIDFonts”)

For all font types, the term font dictionary refers to a PDF dictionary containing

information about the font; likewise, a CIDFont dictionary contains information

about a CIDFont. Except for Type 3, this dictionary is distinct from the font pro-

gram that defines the font’s glyphs. That font program may be embedded in the

PDF file as a stream object or be obtained from some external source.

Note: This terminology differs from that used in the PostScript language. In Post-

Script, a font dictionary is a PostScript data structure that is created as a direct re-

sult of interpreting a font program. In PDF, a font program is always treated as if it

were a separate file, even if its contents are embedded in the PDF file. The font pro-

gram is interpreted by a specialized font interpreter when necessary; its contents

never materialize as PDF objects.

412

CHAPTER 5

Text

Most font programs (and related programs, such as CIDFonts and CMaps) con-

form to external specifications, such as the Adobe Type 1 Font Format. This book

does not include those specifications. See the Bibliography for more information

about the specifications mentioned in this chapter.

The most predictable and dependable results are produced when all font

programs used to show text are embedded in the PDF file. The following sections

describe precisely how to do so. If a PDF file refers to font programs that are not

embedded, the results depend on the availability of fonts in the consumer appli-

cation’s environment. The following sections specify some conventions for refer-

ring to external font programs. However, some details of font naming, font

substitution, and glyph selection are implementation-dependent and may vary

among different applications and operating system environments.

5.5

Simple Fonts

There are several types of simple fonts, all of which have the following properties:

• Glyphs in the font are selected by single-byte character codes obtained from a

string that is shown by the text-showing operators. Logically, these codes index

into a table of 256 glyphs; the mapping from codes to glyphs is called the font’s

encoding. Each font program has a built-in encoding. Under some circum-

stances, the encoding can be altered by means described in Section 5.5.5,

“Character Encoding.”

• Each glyph has a single set of metrics, including a horizontal displacement or

width, as described in Section 5.1.3, “Glyph Positioning and Metrics;” that is,

simple fonts support only horizontal writing mode.

• Except for Type 0 fonts, Type 3 fonts in non-Tagged PDF documents, and cer-

tain standard Type 1 fonts, every font dictionary contains a subsidiary dictio-

nary, the font descriptor, containing font-wide metrics and other attributes of

the font; see Section 5.7, “Font Descriptors.” Among those attributes is an op-

tional font file stream containing the font program.

5.5.1

Type 1 Fonts

A Type 1 font program is a stylized PostScript program that describes glyph

shapes. It uses a compact encoding for the glyph descriptions, and it includes hint

information that enables high-quality rendering even at small sizes and low reso-

Была ли эта страница вам полезна?

Да!Нет

6 посетителей считают эту страницу полезной.

PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 1) — page 10

Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.