What Is a PDF Overlay? Content Streams and Layer Logic

What happens inside the file when you overlay one PDF onto another? Two pages don't get glued together, because in PDF a page isn't an image but a stream of drawing commands. This article explains how the overlay operation intervenes in that stream, what XObject form objects are for, and why drawing order determines everything.

Page content: an ordered drawing stream

Every PDF page has a content stream. That stream is an ordered list of commands describing how the page is drawn:

q                          % save the graphics state
1 0 0 RG                   % set the stroke color to red
50 700 200 100 re          % define a rectangle
f                          % fill
Q                          % restore the graphics state
BT                         % begin a text block
/F1 12 Tf                  % select font F1 at 12 points
72 650 Td                  % move to position
(Hello) Tj                 % draw the text
ET                         % end the text block

The critical property: commands are applied in order and later drawing lands on top of earlier drawing. It's like applying paint on a canvas — what you laid down first gets covered.

That single fact explains all of the overlay's logic.

How an overlay is added to the stream

The overlay operation appends the overlay file's page content into the main document's page stream. One of two positions is chosen:

Foreground (overlay): the overlay commands are appended to the end of the stream. Because they're drawn later, they land on top of the main content.

Background (underlay): the overlay commands are added to the beginning of the stream. Because they're drawn first, the main content lands on top of them.

That's all there is to it. "Layer" is metaphorical here — no toggleable layer is created in the file, only the order of the commands changes.

There is one technical detail to watch, though: graphics state leakage. If the overlay stream changes a color or a transformation matrix and ends without restoring it, the main content that follows gets drawn with those settings and the document breaks. That's why proper implementations wrap the overlay stream in q (save) and Q (restore) commands. If you see unexpected color changes or shifts in your document after an overlay, this is usually the reason.

XObject form: the structure that solves repetition

Imagine overlaying a letterhead onto an 80-page document. It would be possible to copy the letterhead commands separately into each of the 80 pages' streams, but that's wasteful — especially if the letterhead contains a complex vector logo or an embedded image.

The solution is the XObject form object. A form XObject is like a "reusable drawing block": an independent object with its own content stream and its own resources. A page invokes it with a single command:

q
1 0 0 1 0 0 cm             % transformation matrix (position/scale)
/Letterhead Do             % draw the Letterhead form
Q

The overlay tool turns the overlay file's page into a form XObject and puts it in the file once. Then it adds just those two lines to each page.

The practical consequence: the increase in file size is independent of the page count. Whether you overlay onto 10 pages or 500, the letterhead's data is stored once. The growth comes from the overlay file's own resources — an embedded font, a logo image.

The transformation matrix: how positioning works

The cm command in the form invocation sets a transformation matrix. That matrix consists of six numbers and defines scaling, translation and rotation together:

a b c d e f cm

In the simple case 1 0 0 1 0 0 is used — no transformation, the form is drawn in its own coordinates. To shift the overlay 20 units right and 30 units up you'd write 1 0 0 1 20 30. To draw at half scale, 0.5 0 0 0.5 0 0.

In PDF's coordinate system the origin is the page's bottom left corner and the y axis increases upward. That's the reverse of screen coordinates (top left origin, y increasing downward) and a common source of confusion in overlay alignment.

The problem shows up when page sizes differ. If the main document is A4 (595 × 842 points), the overlay is Letter (612 × 792 points), and the transformation matrix is the identity, the overlay aligns from the bottom left corner. The result: the overlay's top sits 50 points low and its right side overflows by 17 points. That's why preparing the overlay file at the target size is far more reliable than trying to align it afterward.

Resource collisions and how they're resolved

The overlay file and the main document may have different resources using the same internal names. Both may have a font named /F1 and an image named /Im1 — but they're different fonts and different images.

The tool has to resolve this during the merge. The standard approach: when copying the overlay file's resources into the main document, rename colliding names (/F1 → /Ov_F1) and update the references inside the form XObject accordingly.

That has a side effect: the same font can end up in the file twice. If Arial is embedded in the main document and Arial is also embedded in the overlay file, the two sit as separate objects. File size grows somewhat. Running the result through a compression tool after the overlay usually clears up that kind of duplication.

Transparency: why it can't be added afterward

When you put the overlay in the foreground and the overlay content is opaque, it covers everything beneath it. If you want a watermark-like effect, you need transparency.

In PDF, transparency is defined by the ExtGState (extended graphics state) dictionary. Before a drawing command you set:

/GS1 gs                    % apply the GS1 graphics state

and the GS1 dictionary contains values like /ca 0.3 (fill transparency) or /CA 0.3 (stroke transparency).

Overlay tools generally carry the overlay file's content across as it is and don't interfere with these settings. That's why transparency has to be set while producing the overlay PDF — lower the element's opacity in your design program and export it that way.

Content using transparency is also usually placed inside a transparency group. That ensures blending calculations are done correctly, but it can be processed differently in some older viewers and some printer drivers. For critical print jobs you need to test the post-overlay output on the real printer.

Does it stay as text?

Yes. The overlay operation doesn't turn text into an image; if the text in the overlay file is real text, it stays selectable and searchable in the combined file.

That has two sides:

The benefit: the organization name in the letterhead shows up in search results, the date on a stamp can be copied, and document processing systems can read this information.

The thing to watch: an overlay is not a concealment tool. If you cover information in the main document with an overlay, that information stays in the file and surfaces through text selection or extraction. Removing confidential information requires redaction — that operation physically deletes the content from the file.

Real layers: optional content groups

PDF does have real, toggleable layers: optional content groups (OCG). They're used in technical drawings and maps; in the viewer you can turn layers on and off from a panel.

Overlay tools generally don't use this — they just arrange the drawing order. So you can't turn off an overlaid letterhead later in the viewer; it has become a permanent part of the content stream.

If you want a separable layer, you need specialized tools that add the overlay as an OCG. That can be useful for temporary markings like a draft stamp, but it's rarely needed in everyday use.

In summary

An overlay is nothing more than adding new drawing commands to a PDF page's content stream — appended to the end it appears on top, added to the beginning it appears underneath. Repeated overlays are stored once as an XObject form object that every page references, which is why file size grows independently of the page count. Positioning is done with a transformation matrix referenced to the page's bottom left corner; that's why size mismatches create misalignment. Transparency is defined in the graphics state dictionary and can't be added during the overlay, so it has to be ready in the overlay file. And overlaid text stays as real text — a behavior that's both useful and worth being aware of from a privacy standpoint.