Repository navigation
PDF Spec 09 Text State
Part of: PDF-Spec-09-Text
Navigation: PDF-Spec-09-Organization | PDF-Spec-Index | PDF-Spec-09-Text-Objects
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 shall move (by translating text space) when the glyph is painted.
NOTE 1 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 shall position the consecutive glyphs of a string according to their widths.
The width information for each glyph shall be stored both in the font dictionary and in the font program itself. The two sets of widths shall be identical.
- NOTE 2 Storing this information in the font dictionary, although redundant, enables a conforming reader to determine glyph positioning without having to look inside the font program.
- NOTE 3 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 positioning 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. However, in a Type 3 font, all metrics are specified explicitly (see 9.6.5, "Type 3 Fonts").
The glyph coordinate system is the space in which an individual character's glyph is defined. All path coordinates and metrics shall be 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 shall be defined by a font matrix specified in an explicit FontMatrix entry in the font. Figure 39 shows a typical glyph outline and its metrics.
Figure 39 - Glyph metrics
The glyph origin is the point (0, 0) in the glyph coordinate system. Tj and other text-showing operators shall position the origin of the first glyph to be painted at the origin of text space.
- EXAMPLE 1 This code adjusts the origin of text space to (40, 50) in the user coordinate system and then places the origin of the A glyph at that point:
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 displacement vector ) in the glyph coordinate system; it has horizontal and vertical components.
- NOTE 4 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-showing operators transform the displacement vector into text space and then translate text space by that amount.
The glyph bounding box shall be the smallest rectangle (oriented with the axes of the glyph coordinate system) that just encloses the entire glyph shape. The bounding box shall be 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.
NOTE 5 It is common to write Japanese and Chinese glyphs either horizontally or vertically.
To handle this, a font may contain a second set of metrics for each glyph. Which set of metrics to use shall be selected according to a writing mode , where 0 shall specify horizontal writing and 1 shall specify vertical writing. This feature is available only for composite fonts, discussed in 9.7, "Composite Fonts".
When a glyph has two sets of metrics, each set shall specify a glyph origin and a displacement vector for that writing mode. In vertical writing, the glyph position shall be described by a position vector from the origin used for horizontal writing (origin 0) to the origin used for vertical writing (origin 1). Figure 40 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 text position shall be changed after the glyph is painted in writing mode 0; its vertical component shall be 0.
- The center diagram illustrates writing mode 1, vertical writing. w1 shall be the displacement vector for writing mode 1; its horizontal component shall be 0.
- In the right diagram, v is a position vector defining the position of origin 1 relative to origin 0.
Figure 40 - Metrics for horizontal and vertical writing modes
The text state comprises those graphics state parameters that only affect text. There are nine parameters in the text state (see Table 104).
Table 104 - Text state parameters
| Parameter | Description |
|---|---|
| T c | Character spacing |
| T w | Word spacing |
| T h | Horizontal scaling |
| T l | Leading |
| T f | Text font |
| T fs | Text font size |
| T mode | Text rendering mode |
| T rise | Text rise |
| T k | Text knockout |
Except for the previously described T f and T fs , these parameters are discussed further in subsequent subclauses. (As described in 9.4, "Text Objects", three additional text-related parameters may occur 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 shall be consulted when text is positioned and shown (using the operators described in 9.4.2, "Text-Positioning Operators" and 9.4.3, "Text-Showing Operators"). In particular, the spacing and scaling parameters shall be used in a computation described in 9.4.4, "Text Space Details". The text state parameters may be set using the operators listed in Table 105.
The text knockout parameter, T k , shall be set through the TK entry in a graphics state parameter dictionary by using the gs operator (see 8.4.5, "Graphics State Parameter Dictionaries"). There is no specific operator for setting this parameter.
The text state operators may 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 shall be initialized to their default values at the beginning of each page.
Table 105 - Text state operators
| Operands | Operator | Description |
|---|---|---|
| charSpace | Tc | Set the character spacing, T c , to charSpace , which shall be a number expressed in unscaled text space units. Character spacing shall be used by the Tj , TJ , and ' operators. Initial value: 0. |
| wordSpace | Tw | Set the word spacing, T w , to wordSpace , which shall be a number expressed in unscaled text space units. Word spacing shall be used by the Tj , TJ , and ' operators. Initial value: 0. |
| scale | Tz | Set the horizontal scaling, T h , to ( scale ÷ 100). scale shall be a number specifying the percentage of the normal width. Initial value: 100 (normal width). |
Table 105 - Text state operators (continued)
| Operands | Operator | Description |
|---|---|---|
| leading | TL | Set the text leading, T l , to leading , which shall be a number expressed in unscaled text space units. Text leading shall be used only by the T* , ' , and " operators. Initial value: 0. |
| font size | Tf | Set the text font, T f , to font and the text font size, T fs , to size . font shall be the name of a font resource in the Font subdictionary of the current resource dictionary; size shall be a number representing a scale factor. There is no initial value for either font or size ; they shall be specified explicitly by using Tf before any text is shown. |
| render | Tr | Set the text rendering mode, T mode , to render , which shall be an integer. Initial value: 0. |
| rise | Ts | Set the text rise, T rise , to rise , which shall be a number expressed in unscaled text space units. Initial value: 0. |
Some of these parameters are expressed in unscaled text space units. This means that they shall be specified in a coordinate system that shall be defined by the text matrix, T m but shall not be scaled by the font size parameter, T fs .
The character-spacing parameter, T c , shall be a number specified in unscaled text space units (although it shall be 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 shall be added to the horizontal or vertical component of the glyph's displacement, depending on the writing mode. See 9.2.4, "Glyph Positioning and Metrics", for a discussion of glyph displacements. In the default coordinate system, 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 the effect of expanding the distance between glyphs (see Figure 41), whereas for vertical writing, a negative value of T c has this effect.
Figure 41 - Character spacing in horizontal writing
| T c = 0 (default) | Character |
|---|---|
| T c = 0.25 | Character |
Word spacing works the same way as character spacing but shall apply only to the ASCII SPACE character (20h). The word-spacing parameter, T w , shall be 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 increase from bottom to top. Figure 42 illustrates the effect of word spacing in horizontal writing.
The leading parameter, T l , shall be specified in unscaled text space units . It specifies the vertical distance between the baselines of adjacent lines of text, as shown in Figure 44.
Figure 44 - Leading
The leading parameter shall be used by the TD , T* , ' , and " operators; see Table 108 for a precise description of its effects. This parameter shall apply to the vertical coordinate in text space, independently of the writing mode.
T w = 0 (default)
T w = 2.5
PDF 32000-1:2008
Figure 42 - Word spacing in horizontal writing
Word spacing shall be 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 shall not apply to occurrences of the byte value 32 in multiple-byte codes.
The horizontal scaling parameter, T h , adjusts the width of glyphs by stretching or compressing them in the horizontal direction. Its value shall be specified as a percentage of the normal width of the glyphs, with 100 being the normal width. The scaling shall apply to the horizontal coordinate in text space, independently of the writing mode. It shall affect both the glyph's shape and its horizontal displacement (that is, its displacement vector). If the writing mode is horizontal, it shall also effect the spacing parameters T c and T w , as well as any positioning adjustments performed by the TJ operator. Figure 43 shows the effect of horizontal scaling.
Figure 43 - Horizontal scaling
| T h = 100 (default) | Word |
|---|---|
| T h = 50 | WordWord |
The text rendering mode, T mode , determines whether showing text shall cause glyph outlines to be stroked, filled, used as a clipping boundary, or some combination of the three. Stroking, filling, and clipping shall have the same effects for a text object as they do for a path object (see 8.5.3, "Path-Painting Operators" and 8.5.4, "Clipping Path Operators"), although they are specified in an entirely different way. The graphics state parameters affecting those operations, such as line width, shall be interpreted in user space rather than in text space.
NOTE The text rendering modes are shown in Table 106. In the examples, a stroke colour of black and a fill colour 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.
Only a value of 3 for text rendering mode shall have any effect on text displayed in a Type 3 font (see 9.6.5, "Type 3 Fonts").
If the text rendering mode calls for filling, the current nonstroking colour in the graphics state shall be used; if it calls for stroking, the current stroking colour shall be used. In modes that perform both filling and stroking, the effect shall be as if each glyph outline were filled and then stroked in separate operations. If any of the glyphs overlap, the result shall be 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. In the transparent imaging model, these combined filling and stroking modes shall be subject to further considerations; see 11.7.4.4, "Special Path-Painting Considerations".
The behaviour of the clipping modes requires further explanation. Glyph outlines shall 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 shall accumulate until the text object is ended by an ET operator; the text rendering mode shall not be changed back to a nonclipping mode before that point.
Table 106 - Text rendering modes
| Mode | Example | Description |
|---|---|---|
| 0 | R | Fill text. |
| 1 | Stroke text. | |
| 2 | R | Fill, then stroke text. |
| 3 | Neither fill nor stroke text (invisible). | |
| 4 | R | Fill text and add to path for clipping (see 9.3.6, "Text Rendering Mode,"). |
| 5 | Stroke text and add to path for clipping. |
The text knockout parameter, T k (PDF 1.4) , shall be a boolean value that determines what text elements shall be considered elementary objects for purposes of colour compositing in the transparent imaging model. Unlike other text state parameters, there is no specific operator for setting this parameter; it may be set only through the TK entry in a graphics state parameter dictionary by using the gs operator (see 8.4.5, "Graphics State Parameter Dictionaries"). The text knockout parameter shall apply only to entire text objects; it shall not be set between the BT and ET operators delimiting a text object. Its initial value shall be true .
Table 106 - Text rendering modes (continued)
| Mode | Example | Description |
|---|---|---|
| 6 | R | Fill, then stroke text and add to path for clipping. |
| 7 | Add text to path for clipping. |
At the end of the text object, the accumulated glyph outlines, if any, shall be combined into a single path, treating the individual outlines as subpaths of that path and applying the nonzero winding number rule (see 8.5.3.3.2, "Nonzero Winding Number Rule"). The current clipping path in the graphics state shall be set to the intersection of this path with the previous clipping path. As is the case for path objects, this clipping shall occur after all filling and stroking operations for the text object have occurred. It remains in effect until a previous clipping path is restored by an invocation of the Q operator.
If no glyphs are shown or if the only glyphs shown have no outlines (for example, if they are ASCII SPACE characters (20h)), no clipping shall occur.
Text rise, T rise , shall specify the distance, in unscaled text space units, to move the baseline up or down from its default location. Positive values of text rise shall move the baseline up. Figure 45 illustrates the effect of the text rise. Text rise shall apply to the vertical coordinate in text space, regardless of the writing mode.
NOTE 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 45 - Text rise
| (This text is ) Tj 5 Ts (superscripted) Tj | This text is superscripted |
|---|---|
| (This text is ) Tj -5 Ts (subscripted) Tj | This text is subscripted |
| (This ) Tj -5 Ts (text ) Tj 5 Ts (moves ) Tj 0 Ts (around) Tj | This text moves around |
If the parameter is false , each glyph in a text object shall be treated as a separate elementary object; when glyphs overlap, they shall composite with one another.
If the parameter is true , all glyphs in the text object shall be treated together as a single elementary object; when glyphs overlap, later glyphs shall overwrite ('knock out') earlier ones in the area of overlap. This behaviour is equivalent to treating the entire text object as if it were a non-isolated knockout transparency group; see 11.4.6, "Knockout Groups". Transparency parameters shall be applied to the glyphs individually rather than to the implicit transparency group as a whole:
- Graphics state parameters, including transparency parameters, shall be inherited from the context in which the text object appears. They shall not be saved and restored. The transparency parameters shall not be reset at the beginning of the transparency group (as they are when a transparency group XObject is explicitly invoked). Changes made to graphics state parameters within the text object shall persist beyond the end of the text object.
- After the implicit transparency group for the text object has been completely evaluated, the group results shall be composited with the backdrop, using the Normal blend mode and alpha and soft mask values of 1.0.
Navigation: PDF-Spec-09-Organization | PDF-Spec-Index | PDF-Spec-09-Text-Objects