A content stream draws a page, a form XObject, a pattern cell, a Type 3 glyph or an annotation’s appearance. It is a stream of operands and operators in postfix order: the operands first, then the operator that uses them, as in PostScript but with no procedures, loops or variables. There are 73 operators. PDF 1.0 had most of them; 1.1, 1.2 and 1.3 added the rest, and PDF 1.4, which brought transparency, added none, because transparency is set through graphics state dictionaries.
Syntax
Operands are ordinary objects: numbers, strings, names, arrays and dictionaries.
They may not be indirect references, and there are no streams. An operator is a
keyword of regular characters, such as re or T*; it is
not an object. Every operator takes a fixed set of operands, except the colour
operators whose number depends on the colour space. White space and comments are
as in the rest of the file.
q % save the graphics state
1 0 0 RG 2 w % red stroke, 2 units wide
0 0 1 rg % blue fill
72 600 200 100 re B % a rectangle, filled and stroked
Q % restore
BT % begin text
/F1 24 Tf % font F1 at 24 units
72 700 Td % move to (72, 700)
(Hello, world) Tj % show the string
ET % end text
/Im1 Do % draw the XObject named Im1F1 and Im1 are names in the page’s resourcesNames such as /F1 and /Im1 are looked up in the
resource dictionary
of the page or XObject the stream belongs to. A page’s Contents may be
an array of streams; they are read as one, and a token may not be split between
two of them.
All operators
The tables below give every operator, grouped as the specification groups them. Since is the first version that had it; operators with no later version were in PDF 1.0.
General graphics state
| Operands | Operator | Since | What it does |
|---|---|---|---|
| lineWidth | w | 1.0 | Set the line width, in user units; 0 means the thinnest line the device can draw |
| lineCap | J | 1.0 | Set the line cap: 0 butt, 1 round, 2 projecting square |
| lineJoin | j | 1.0 | Set the line join: 0 mitre, 1 round, 2 bevel |
| miterLimit | M | 1.0 | Set the mitre limit, above which a mitre join becomes a bevel; default 10 |
| dashArray dashPhase | d | 1.0 | Set the dash pattern: [3 2] 0 d is 3 on, 2 off; [] 0 d is solid |
| intent | ri | 1.1 | Set the colour rendering intent: AbsoluteColorimetric, RelativeColorimetric, Saturation or Perceptual |
| flatness | i | 1.0 | Set the flatness tolerance, 0 to 100 device pixels; 0 means the device’s default |
| dictName | gs | 1.2 | Set parameters from the named graphics state parameter dictionary in the ExtGState resources |
Special graphics state
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | q | 1.0 | Save the graphics state on a stack |
| none | Q | 1.0 | Restore the graphics state last saved; q and Q must pair within a stream |
| a b c d e f | cm | 1.0 | Multiply the current transformation matrix by [a b c d e f]: 1 0 0 1 tx ty cm moves, sx 0 0 sy 0 0 cm scales |
Path construction
| Operands | Operator | Since | What it does |
|---|---|---|---|
| x y | m | 1.0 | Begin a new subpath at (x, y) |
| x y | l | 1.0 | Add a straight line to (x, y) |
| x1 y1 x2 y2 x3 y3 | c | 1.0 | Add a cubic Bézier curve to (x3, y3), with control points (x1, y1) and (x2, y2) |
| x2 y2 x3 y3 | v | 1.0 | A curve whose first control point is the current point |
| x1 y1 x3 y3 | y | 1.0 | A curve whose second control point is the end point |
| none | h | 1.0 | Close the subpath with a straight line to its start |
| x y width height | re | 1.0 | Add a rectangle as a closed subpath: the same as x y m, three lines and h |
Path painting
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | S | 1.0 | Stroke the path |
| none | s | 1.0 | Close and stroke: h S |
| none | f | 1.0 | Fill, by the non-zero winding rule; open subpaths are closed |
| none | F | 1.0 | The same as f, kept for old files |
| none | f* | 1.0 | Fill by the even-odd rule |
| none | B | 1.0 | Fill by non-zero winding, then stroke |
| none | B* | 1.0 | Fill by even-odd, then stroke |
| none | b | 1.0 | Close, fill by non-zero winding and stroke |
| none | b* | 1.0 | Close, fill by even-odd and stroke |
| none | n | 1.0 | End the path without painting; used after a clip |
Each painting operator ends the path: the next path starts empty.
Clipping paths
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | W | 1.0 | Intersect the clipping path with the current path, by non-zero winding |
| none | W* | 1.0 | The same by the even-odd rule |
The clip takes effect when the path is ended by the painting operator that follows,
usually n: 0 0 100 100 re W n. Only Q makes
the clipping path larger again.
Text objects
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | BT | 1.0 | Begin a text object: set the text matrix and text line matrix to the identity |
| none | ET | 1.0 | End the text object |
Text objects cannot nest. Inside one, only text, colour, general graphics state,
marked content and the text operators may appear, not path construction or
q and Q.
Text state
| Operands | Operator | Since | What it does |
|---|---|---|---|
| charSpace | Tc | 1.0 | Set the character spacing, added after each glyph, in unscaled text space units; default 0 |
| wordSpace | Tw | 1.0 | Set the word spacing, added after each single-byte code 32; default 0 |
| scale | Tz | 1.0 | Set the horizontal scaling, in per cent; default 100 |
| leading | TL | 1.0 | Set the leading, the distance between baselines, used by T*, ' and "; default 0 |
| font size | Tf | 1.0 | Set the font, a name in the Font resources, and its size; there is no default, so it must come before text is shown |
| render | Tr | 1.0 | Set the text rendering mode; default 0 |
| rise | Ts | 1.0 | Set the text rise, a baseline shift up, for superscripts; default 0 |
Text state is part of the graphics state, so q and Q
save and restore it, and it lasts from one text object to the next.
| Tr | Rendering |
|---|---|
| 0 | Fill the glyphs |
| 1 | Stroke the glyphs |
| 2 | Fill, then stroke |
| 3 | Neither: invisible, as in the text layer of a scanned page |
| 4 | Fill and add to the clipping path |
| 5 | Stroke and add to the clipping path |
| 6 | Fill, stroke and add to the clipping path |
| 7 | Add to the clipping path only |
Text positioning
| Operands | Operator | Since | What it does |
|---|---|---|---|
| tx ty | Td | 1.0 | Move to the start of the next line, offset (tx, ty) from the start of the current one |
| tx ty | TD | 1.0 | The same, and set the leading to −ty |
| a b c d e f | Tm | 1.0 | Set the text matrix and the text line matrix; it replaces them, it does not multiply |
| none | T* | 1.0 | Move to the start of the next line: 0 -leading Td |
Text showing
| Operands | Operator | Since | What it does |
|---|---|---|---|
| string | Tj | 1.0 | Show the glyphs for the string’s character codes |
| array | TJ | 1.0 | Show strings, with numbers between them that move the next glyph left by that many thousandths of a text space unit (negative numbers move right): [(W) 120 (orld)] TJ |
| string | ' | 1.0 | Move to the next line and show: T* string Tj |
| aw ac string | " | 1.0 | Set word spacing aw and character spacing ac, move to the next line and show |
After each glyph the text matrix moves on by the glyph’s width:
tx = ((w0 − Tj ÷ 1000) × Tfs + Tc + Tw) × Th, where w0
is the glyph’s width from the font in thousandths, Tj a number from a
TJ array, Tfs the font size, Tc and
Tw the spacings (Tw only after code 32) and
Th the horizontal scaling as a fraction. A string’s bytes are
character codes in the font’s encoding, one or more bytes a code: see
Fonts.
Type 3 fonts
| Operands | Operator | Since | What it does |
|---|---|---|---|
| wx wy | d0 | 1.0 | In a Type 3 glyph procedure: set the glyph’s width; the glyph may set its own colours |
| wx wy llx lly urx ury | d1 | 1.0 | Set the width and bounding box; the glyph is a shape only, painted in the current colour, so it may not set colours |
One of the two must be the first operator of every glyph’s content stream.
Colour
| Operands | Operator | Since | What it does |
|---|---|---|---|
| name | CS | 1.1 | Set the stroking colour space: DeviceGray, DeviceRGB, DeviceCMYK, Pattern, or a name in the ColorSpace resources; the colour becomes the space’s initial one |
| name | cs | 1.1 | The same for the non-stroking (fill) colour space |
| c1 … cn | SC | 1.1 | Set the stroking colour in the current space, one number a component; not for Pattern, Separation, DeviceN or ICCBased spaces |
| c1 … cn [name] | SCN | 1.2 | Set the stroking colour in any space; for a Pattern space, the last operand is the pattern’s name |
| c1 … cn | sc | 1.1 | The non-stroking form of SC |
| c1 … cn [name] | scn | 1.2 | The non-stroking form of SCN |
| gray | G | 1.0 | Set the stroking space to DeviceGray and the colour to gray, 0 black to 1 white |
| gray | g | 1.0 | The same for non-stroking |
| r g b | RG | 1.0 | Set the stroking space to DeviceRGB and the colour |
| r g b | rg | 1.0 | The same for non-stroking |
| c m y k | K | 1.0 | Set the stroking space to DeviceCMYK and the colour |
| c m y k | k | 1.0 | The same for non-stroking |
Upper case is for stroking, lower case for everything else: fills, text in mode 0 and stencil image masks. The initial colour space is DeviceGray and the colour black.
Shading
| Operands | Operator | Since | What it does |
|---|---|---|---|
| name | sh | 1.3 | Paint the named shading from the Shading resources over the current clipping region |
Inline images
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | BI | 1.0 | Begin an inline image; key and value pairs follow |
| none | ID | 1.0 | Begin the image data: one white-space byte, then the bytes |
| none | EI | 1.0 | End the inline image |
BI /W 4 /H 4 /CS /G /BPC 8 /F /AHx
ID 00 40 80 C0 40 80 C0 FF 80 C0 FF 40 C0 FF 40 80 >
EIThe keys are short forms of an image XObject’s; see
Images.
There is no length, so a reader finds the end by decoding the data, or by
searching for EI after white space, which binary data can also
contain.
XObjects
| Operands | Operator | Since | What it does |
|---|---|---|---|
| name | Do | 1.0 | Draw the named XObject from the XObject resources: an image in the unit square of user space, or a form XObject’s content stream |
Marked content
| Operands | Operator | Since | What it does |
|---|---|---|---|
| tag | MP | 1.2 | Mark a point in the stream with a tag name |
| tag properties | DP | 1.2 | Mark a point with a tag and a property list: a dictionary, or a name in the Properties resources |
| tag | BMC | 1.2 | Begin a marked-content sequence |
| tag properties | BDC | 1.2 | Begin a marked-content sequence with a property list |
| none | EMC | 1.2 | End the sequence begun by the matching BMC or BDC |
Marked content does not change what is drawn. It labels parts of a stream for other
uses. From PDF 1.3 logical
structure uses it: /Span << /MCID 0 >> BDC … EMC ties
the content to a structure element. Sequences nest, and must pair within one
stream.
Compatibility
| Operands | Operator | Since | What it does |
|---|---|---|---|
| none | BX | 1.1 | Begin a compatibility section: until the matching EX, a reader ignores operators it does not know |
| none | EX | 1.1 | End the compatibility section |
Outside such a section an unknown operator is an error, though most readers skip it anyway.
Operators by version
| Version | Operators added | Count |
|---|---|---|
| 1.0 | b B b* B* BI BT c cm d d0 d1 Do EI ET f F f* G g h i ID j J K k l m M n q Q re RG rg s S T* Tc Td TD Tf Tj TJ TL Tm Tr Ts Tw Tz v w W W* y ' " | 57 |
| 1.1 | BX EX CS cs SC sc ri | 7 |
| 1.2 | BDC BMC EMC MP DP gs SCN scn | 8 |
| 1.3 | sh | 1 |
| 1.4 | none | 0 |
A reader of a PDF 1.0 file can expect only the first row. The colour operators
CS, cs, SC and sc came with the
device-independent colour spaces of PDF 1.1, and SCN and
scn with patterns and Separation spaces in PDF 1.2.
What the operators change
The operators work on the graphics state, which starts fresh at the beginning of each page:
| Parameter | Initial value | Set by |
|---|---|---|
| Current transformation matrix | Default user space: 1/72 inch units, origin at the lower left of the page | cm |
| Clipping path | The whole page | W, W* |
| Colour space and colour, stroking and non-stroking | DeviceGray, black | colour operators |
| Text state | see above | text state operators |
| Line width, cap, join, mitre limit, dash | 1, 0, 0, 10, solid | w J j M d |
| Rendering intent | RelativeColorimetric | ri |
| Flatness | 1 | i |
| Others: stroke adjustment, overprint, halftone, transfer, blend mode, soft mask, alpha | see Graphics | gs |