All 73 operators that can appear in a content stream, with their operands, grouped the way the specification groups them.
sh,
came in PDF 1.3. PDF 2.0 added none, deprecated F, and made inline images declare their length.
Operands come first, then the operator, as in a content stream: x y width height re. Names like /F1 are looked up in the page’s /Resources. A version badge marks an operator added after PDF 1.0. Each group links to the table that defines it in the PDF 1.4 reference and in ISO 32000-1.
Where operators live
Operators are written in content streams: stream objects whose data, once decoded, is a sequence of operands and operators. In this page from the sample file in Learning, the page dictionary points at object 4 with /Contents, and the operators are that stream’s data:
3 0 obj << /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 5 0 R >> >> /Contents 4 0 R >> endobj 4 0 obj << /Length 41 >> stream BT /F1 24 Tf 72 712 Td (Hello, PDF) Tj ET endstream endobj
To the file parser, the stream’s data is just bytes, and in real files it is usually Flate-compressed. A content interpreter then reads those bytes with the same token rules as the rest of the file. Operands are ordinary objects: numbers, names, strings, arrays and dictionaries. Operators are bare keywords like Tf that aren’t objects of any type: a name starts with a slash (/F1), an operator doesn’t.
- Operands must be direct objects. A content stream can’t contain references like
5 0 R, or streams. So it uses names like/F1, and the interpreter looks them up in/Resources, where the references live. - There is no stack. An operator takes exactly the operands just before it, returns nothing, and leaves nothing behind.
Content streams appear in four places:
| Where | What it draws |
|---|---|
A page’s /Contents | The page. The value is one stream, or an array of streams read as if joined end to end. A split can only fall between tokens and means nothing. |
| A form XObject | A reusable graphic, painted with Do. Annotation appearance streams (/AP) are form XObjects too. |
A tiling pattern (/PatternType 1) | One tile of a repeating pattern. |
A Type 3 font’s /CharProcs | One glyph, starting with d0 or d1. |
Where operators may appear
A content stream is a sequence of graphics objects. Between them is the page description level, where every stream starts. Each kind of object begins and ends with particular operators and allows only some operators inside it.
| Context | Begins with | Ends with | Allowed inside |
|---|---|---|---|
| Page description level | start of the stream, or the end of any object | the start of any object | General and special graphics state, color, text state, marked content |
| Path object | m or re | a path-painting operator | Path construction |
| Clipping path object | W or W*, inside a path object | a path-painting operator | Nothing |
| Text object | BT | ET | General graphics state, color, text state, text positioning, text showing, marked content |
| Shading object | sh | immediately | Nothing |
| Inline image object | BI | EI | ID |
| External object | Do | immediately | Nothing |
Some consequences:
q,Qandcmcan’t appear betweenBTandET. To rotate or scale text, useTm, orcmbeforeBT.- Nothing can change between
mand the painting operator, not even the color: set the state first, then build and paint the path. Do,shand inline images can’t appear inside a text object.
General graphics state
Set one parameter of the graphics state each. They stay in effect until changed or until a Q restores an earlier state. The Graphics state page in Learning lists every parameter and its initial value.
| Syntax | What it does | Added |
|---|---|---|
lineWidth w | Set the line width. 0 means the thinnest line the device can draw. | |
lineCap J | Set the line cap: 0 butt, 1 round, 2 projecting square. | |
lineJoin j | Set the line join: 0 miter, 1 round, 2 bevel. | |
miterLimit M | Set the miter limit: how long a miter join may get, relative to the line width, before it is drawn as a bevel instead. | |
dashArray dashPhase d | Set the dash pattern, for example [3 2] 0 d. [] 0 d gives solid lines again. | |
intent ri | Set the color rendering intent: /AbsoluteColorimetric, /RelativeColorimetric, /Saturation or /Perceptual. | |
flatness i | Set the flatness tolerance, 0 to 100, used to turn curves into straight segments. 0 means the device default. | |
dictName gs | Apply a graphics state parameter dictionary from the /ExtGState resources. The only way to set transparency, soft masks, overprint and some other parameters. |
Special graphics state
| Syntax | What it does | Added |
|---|---|---|
q | Save a copy of the whole graphics state on the graphics state stack. | |
Q | Restore the graphics state saved by the matching q. | |
a b c d e f cm | Concatenate a matrix onto the current transformation matrix (CTM). Six numbers, not an array. |
q and Q must balance within a content stream, or within the streams of a page's /Contents array taken together. Wrapping changes in q … Q is the usual way to undo a cm, and the only way to remove a clip.
Path construction
Build up the current path. Nothing is drawn until a path-painting operator ends the path.
| Syntax | What it does | Added |
|---|---|---|
x y m | Begin a new subpath at (x, y). | |
x y l | Append a straight line to (x, y). | |
x1 y1 x2 y2 x3 y3 c | Append a cubic Bézier curve to (x3, y3), with control points (x1, y1) and (x2, y2). | |
x2 y2 x3 y3 v | Append a Bézier curve whose first control point is the current point. | |
x1 y1 x3 y3 y | Append a Bézier curve whose second control point is its end point (x3, y3). | |
h | Close the subpath with a straight line back to its start. | |
x y width height re | Append a rectangle with its lower-left corner at (x, y), as a complete closed subpath: the same as an m, three l and an h. |
Path painting
End the path object: paint the current path, then discard it.
| Syntax | What it does | Added |
|---|---|---|
S | Stroke the path. | |
s | Close and stroke the path, the same as h S. | |
f | Fill the path using the nonzero winding number rule. Open subpaths are closed first. | |
F | The same as f. Readers must accept it, but writers should use f. | |
f* | Fill the path using the even-odd rule. | |
B | Fill using the nonzero rule, then stroke. | |
B* | Fill using the even-odd rule, then stroke. | |
b | Close, fill using the nonzero rule, and stroke: the same as h B. | |
b* | Close, fill using the even-odd rule, and stroke: the same as h B*. | |
n | End the path without painting it. Used after W or W* to set a clip. |
Clipping paths
| Syntax | What it does | Added |
|---|---|---|
W | Intersect the clipping path with the current path, using the nonzero rule. | |
W* | Intersect the clipping path with the current path, using the even-odd rule. |
W goes between the last path-construction operator and the painting operator, and the new clip takes effect after the path is painted. Use n to clip without drawing anything. A clip can only get smaller: to remove it, restore an earlier state with Q.
q 72 72 200 100 re W n % clip to a rectangle, draw nothing /Im0 Do % only the part inside the rectangle shows Q % back to the old clip
Text objects
| Syntax | What it does | Added |
|---|---|---|
BT | Begin a text object, setting the text matrix and the text line matrix to the identity. Text objects can’t nest. | |
ET | End the text object. The text matrix is discarded. |
Text state
Text state is part of the graphics state: it outlasts ET, carries over to the next BT, and is saved and restored by q and Q. Spacing values are in unscaled text space units, so they don’t grow with the font size.
| Syntax | What it does | Added |
|---|---|---|
charSpace Tc | Set the character spacing, added after every glyph. Initially 0. | |
wordSpace Tw | Set the word spacing, added after every single-byte character code 32 (a space). Initially 0. | |
scale Tz | Set the horizontal scaling, as a percentage of normal width. Initially 100. | |
leading TL | Set the leading, the distance from one baseline to the next, used by T*, ' and ". Initially 0. | |
font size Tf | Set the font (a name in the /Font resources) and the font size. There is no default, so Tf must come before any text is shown. | |
render Tr | Set the text rendering mode, 0 to 7: fill, stroke, invisible, clip, or a mix. Initially 0 (fill). | |
rise Ts | Set the text rise, which moves the baseline up (positive) or down, for superscripts and subscripts. Initially 0. |
Text positioning
| Syntax | What it does | Added |
|---|---|---|
tx ty Td | Move to the start of the next line, offset by (tx, ty) from the start of the current line. | |
tx ty TD | Like Td, and also set the leading to −ty. The same as −ty TL tx ty Td. | |
a b c d e f Tm | Set the text matrix and the text line matrix. This replaces them rather than concatenating like cm. | |
T* | Move to the start of the next line, using the leading: the same as 0 −leading Td. |
Inside a text object a reader tracks two matrices. The text matrix is where the next glyph goes; every glyph shown moves it along. The text line matrix is where the current line started. Td, TD and T* move from the start of the current line, not from where the last glyph ended.
BT /F1 12 Tf 72 700 Td (Name:) Tj % line starts at (72, 700) 60 0 Td (Ada) Tj % 60 units right of the line start, not of "Name:" -60 -14 Td (Next line) Tj % back to x = 72, 14 units down ET
Text extraction has to rebuild lines and spaces from these moves. A Td with ty = 0 might be a word gap or a column jump, and many generators position every word or glyph separately, so extraction tools guess from the distances.
Text showing
The bytes in a string are character codes for the current font, not Unicode.
| Syntax | What it does | Added |
|---|---|---|
string Tj | Show a string. | |
array TJ | Show strings with adjustments between them. Numbers are in thousandths of a text space unit and are subtracted from the position, so in horizontal writing a positive number moves the next glyph left. [(W) 80 (orld)] TJ kerns the “o” closer to the “W”. | |
string ' | Move to the next line and show a string: the same as T* string Tj. | |
aw ac string " | Set the word spacing to aw and the character spacing to ac, then do string '. |
Type 3 fonts
A Type 3 font draws each glyph with a small content stream in its /CharProcs dictionary. That stream must start with one of these two operators, and they are allowed nowhere else.
| Syntax | What it does | Added |
|---|---|---|
wx wy d0 | Set the glyph’s width (wy must be 0). The glyph sets its own colors, so it can be multicolored. | |
wx wy llx lly urx ury d1 | Set the glyph’s width and bounding box. The glyph is a shape only, painted in whatever color is current when the text is shown. Color operators inside it are ignored, and it can’t contain images (image masks are fine). |
The width must match the font’s /Widths entry for that character. With d1 the bounding box must enclose every mark the glyph makes; marks outside it give unpredictable results.
% /CharProcs << /square 9 0 R >>, stream 9 is: 1000 0 0 0 750 750 d1 % width 1000, bounding box (0,0)–(750,750) 0 0 750 750 re f % a filled square, in the current fill color
Color
Upper case sets the stroking color, lower case the nonstroking (fill) color. Both start as black in DeviceGray.
| Syntax | What it does | Added |
|---|---|---|
name CS | Set the stroking color space: /DeviceGray, /DeviceRGB, /DeviceCMYK, /Pattern, or a name in the /ColorSpace resources. Also resets the stroking color to that space’s initial value. | |
name cs | Set the nonstroking color space. | |
c1 … cn SC | Set the stroking color in the current space: one, three or four numbers for device, CIE-based (other than ICCBased) and Indexed spaces. | |
c1 … cn [name] SCN | Like SC, but also for ICCBased, Separation, DeviceN and Pattern spaces. In a Pattern space, name is a /Pattern resource. | |
c1 … cn sc | Set the nonstroking color, like SC. | |
c1 … cn [name] scn | Set the nonstroking color, like SCN. | |
gray G | Set the stroking space to DeviceGray and the gray level, from 0 (black) to 1 (white). | |
gray g | Set the nonstroking space to DeviceGray and the gray level. | |
r g b RG | Set the stroking space to DeviceRGB and the color, each component 0 to 1. | |
r g b rg | Set the nonstroking space to DeviceRGB and the color. | |
c m y k K | Set the stroking space to DeviceCMYK and the color, each component 0 to 1. | |
c m y k k | Set the nonstroking space to DeviceCMYK and the color. |
Shading patterns
| Syntax | What it does | Added |
|---|---|---|
name sh | Paint a shading (a smooth color gradient) from the /Shading resources. It is limited only by the current clip and the shading’s own extent. The current color is neither used nor changed. |
There are two ways to paint a shading. sh paints it directly, in the current user space, limited only by the clip, so it is usually wrapped in q, a clip and Q. A shading pattern is used as a color instead, then any fill, stroke or text is painted with it. A pattern’s coordinates are fixed to the page: its /Matrix maps pattern space to the default space of the page (or of the form XObject using it), so a cm before the fill doesn’t move the gradient.
% 1. sh: clip first, because only the clip limits sh q 72 600 200 100 re W n /Sh0 sh Q % 2. Pattern color: /P0 is a type 2 pattern whose /Shading is the gradient /Pattern cs /P0 scn 72 450 200 100 re f
Inline images
| Syntax | What it does | Added |
|---|---|---|
BI | Begin an inline image. Key–value pairs describing the image follow. | |
ID | Begin the image data. One white-space byte follows, then the data. | |
EI | End the inline image. |
An inline image puts a small image straight into the content stream instead of in a separate image XObject. The specs limit it to small images, 4 KB or less, and it can’t use JBIG2Decode or JPXDecode. Between BI and ID, keys can be abbreviated:
| Keys | Color spaces | Filters |
|---|---|---|
/W Width, /H Height, /BPC BitsPerComponent, /CS ColorSpace, /F Filter, /DP DecodeParms, /D Decode, /IM ImageMask, /I Interpolate |
/G DeviceGray, /RGB DeviceRGB, /CMYK DeviceCMYK, /I Indexed |
/AHx ASCIIHex, /A85 ASCII85, /LZW, /Fl Flate, /RL RunLength, /CCF CCITTFax, /DCT |
q 100 0 0 100 72 600 cm % images paint into the unit square BI /W 2 /H 2 /CS /G /BPC 8 /F /AHx % 2×2 gray, hex-encoded ID 00FFFF00> EI % black, white / white, black Q
EI between white space, and those bytes can turn up inside the data by chance. PDF 2.0 requires a /Length (or /L) key so readers can skip the data safely.
XObjects
| Syntax | What it does | Added |
|---|---|---|
name Do | Paint an XObject from the /XObject resources. An image fills the unit square of the current user space; a form runs its own content stream with its own resources; a PostScript XObject is obsolete and should not be written. |
Marked content
Label parts of the content stream for tagged PDF, optional content (layers) and other uses. Readers that don’t care about a tag paint the content as usual.
| Syntax | What it does | Added |
|---|---|---|
tag MP | Mark a point in the content stream. | |
tag properties DP | Mark a point, with a property list: an inline dictionary or a name in the /Properties resources. | |
tag BMC | Begin a marked-content sequence, ended by EMC. | |
tag properties BDC | Begin a marked-content sequence with a property list, for example /P <</MCID 0>> BDC in tagged PDF or /OC /oc1 BDC for a layer. | |
EMC | End the sequence begun by the matching BMC or BDC. |
Sequences can nest, but they must nest properly with each other and with BT … ET: BDC BT … ET EMC and BT BDC … EMC ET are fine, BDC BT … EMC ET is not.
Compatibility
| Syntax | What it does | Added |
|---|---|---|
BX | Begin a compatibility section: until the matching EX, unknown operators and their operands are ignored instead of being errors. | |
EX | End the compatibility section. |
Checked against Appendix A of the Adobe PDF Reference, third edition (PDF 1.4), Annex A of ISO 32000-1:2008 (PDF 1.7), Annex A of ISO 32000-2:2020 (PDF 2.0), and the operator tables they point to.