PDF generation — How to merge multiple stream objects?

Question

I'm currently into generating PDF documents without the use of an external library and it has been going well so far. I've written the document exposed below with a text editor (vim) and it renders the expected results using at least two PDF distinct viewers (evince & gsview, running Linux).

This document produces three squares at top of the page, coming in different sizes, widths and colors.

My question is : is there a way to merge two stream objects into a new single one or, in other words, is there a way to compose sophisticated objects starting from simple ones, so we can easily refer to these composite objects, multiple times if needed ?

In the given example, object 5 0 obj is drawing a square, and following ones are just applying colors and coordinates transformations (through a matrix).

The PDF reference manual states that multiple stream contents passed as an array to page object's /Contents parameter are concatenated and processed as a single continuous stream, which totally does the trick… as long as the document remains small and simple!

In this same example, the /Contents array is indirectly passed through object 4 0 obj, which refers three times to 5 0 R, to draw the squares.

The ideal here would be to define three differents objects, each refering to 5 0 R by themselves, then invoke only these objects, a single time each, from the Contents array.

I tried adding subarrays inside it, which could in turn be embedded into dedicated objects and referenced indirectly, but it unfortunately doesn't work. :-(

A lot of thanks to any people that could/try-to help !

PS: I'm doing it because I'm interested in the format itself and would like to produce some autogenerated documents from small scripts. Also, I'll probably embed them into a weakly powered appliance and I cannot afford relying on dozens of megabytes in dependencies.

But before this, I still tried to do that too, using PHP with TCPDF. If there's already some facilities dedicated to this that I would have missed, this is relevant to my interests too. :-)

---

Small.pdf (hand made PDF file)

%PDF-1.7

1 0 obj
<<
    /Type       /Catalog
    /Pages      2 0 R
>>
endobj

2 0 obj
<<
    /Type       /Pages
    /Count      1
    /Kids       [ 3 0 R ]
>>
endobj

3 0 obj
<<
    /Type       /Page
    /MediaBox   [ 0.000000 0.000000 1000.000000 1414.213562 ]
    /Contents   4 0 R
>>
endobj

4 0 obj
% A simple array, just to avoid embedding it directly in /Page object (3 0 R here)
[
    6 0 R   5 0 R   % Red   square
    7 0 R   5 0 R   % Green square
    8 0 R   5 0 R   % Blue  square (tilted)
]
endobj

5 0 obj
% Draws a square, centered by default on lower left corner
<<
    /Length     43
>>
stream
+20 +20 m
+20 -20 l
-20 -20 l
-20 +20 l s Q
endstream
endobj

6 0 obj
<<
    /Length     63
>>
stream
/DeviceRGB CS
q
1.0 0.0 0.0 SC
2.0 w
1 0 0 -1 60 1354.213562 cm
endstream
endobj

7 0 obj
<<
    /Length     49
>>
stream
q
0.0 1.0 0.0 SC
1.0 w
2 0 0 -2 190 1334.213562 cm
endstream
endobj

8 0 obj
<<
    /Length     83
>>
stream
q
0.0 0.0 1.0 SC
5.0 w
0.707106781 0.707106781 -0.707106781 0.707106781 110 1250 cm
endstream
endobj

xref
0 9
0000000000 65535 f
0000000010 00000 n
0000000079 00000 n
0000000168 00000 n
0000000296 00000 n
0000000513 00000 n
0000000674 00000 n
0000000796 00000 n
0000000905 00000 n
trailer
<<
    /Size       9
    /Root       1 0 R
    /ID         [ <0000000000> <0000000001> ]
>>
startxref
01047
%%EOF

Answer 1

What you are looking for are form XObjects.

The pdf specification ISO 32000-1 characterizes them like this:

A form XObject is a PDF content stream that is a self-contained description of any sequence of graphics objects. A form XObject may be painted multiple times - either on several pages or at several locations on the same page - and produces the same results each time, subject only to the graphics state at the time it is invoked.

For details please read section 8.10 of the specification.