Content Stream <> Layers

Content streams are just a way to break up a large single content stream into blocks though it is not really necessary.  When the PDF is rendered it effectively combines all of the streams during rendering, stream 1 is rendered first then stream 2 and so on.

There are some special cases but this is for advanced usage and requires special attention to make sure the streams are valid.

1. Shared Content Stream - A background template may be created for page 1 of a PDF and that content stream can be shared for all subsequent pages.

2. Sometimes Debenu PDF Library customers create a new stream, add a watermark type logo to the stream and then move / insert the content stream as stream 1.  This has the effect of drawing the watermark image first so that all other content is drawn on top.

3. Some people use a contentstream for each Optional Content Group which is the closest thing to layers in the PDF format.  Again this needs to be managed carefully.

If content streams are used for layering then they should be self contained and begin with a SaveState and finish with a RestoreState command in order to restore the grapihcs state, scaling, rotation etc..

Content streams can be used for various reasons.  When you want to use CapturePage / DrawCapturedPage in the library then you should call QP.RemoveSharedContentStreams which creates copies of contents streams so that none are shared, making the PDF larger, but allowing the pages of the PDF to be extracted without errors.  ie.  If you delete page 1 that contains the shared content stream them all other pages would become invalid because of the missing shared content stream.  Also a call to QP.CombineContentStreams is required so that all streams are merged into one single stream that makes copying quicker and easier.

Andrew.