Adobe® PDF Library

Layers and Transparencies

Optional Content Groups (OCG) are referred to as layers within Adobe Acrobat and Reader, and can be used to separate and manage content or graphics on a single page.  Layers are a very useful way to present information when opening a PDF file.  For example, you could create a brochure with multiple layers offering the same content but in different languages.  The first layer would be the blank background page.  The resulting PDF file could be set up, with some extra program code, to select the appropriate layer with French or Spanish or English, depending on the language of the reader, and then display that language in the PDF file.


View Sample Code

This program changes the On/Off setting for the layers in the PDF file’s default configuration (OptionalContentConfig).  By changing the On/Off state, we can make the layers visible or invisible when opening the PDF file in Adobe Acrobat or another similar viewer.  In this example, the system changes the way layers are presented in the original PDF file, Layers.PDF, found in the Data directory, and then saves the file to a new PDF called ChangeLayerConfiguration-Out.PDF.

The Layers.PDF file has four layers, Layers 1, 2, and 3, and Guides and Grids.  Each can be either ON of OFF.  In the original Layer.PDF file, the layers are set this way:

Layer 1 ON
Layer 2 ON
Layer 3 ON
Guides and Grids OFF

The ChangeLayerConfiguration sample program changes the settings in Layer.PDF to these:

Layer 1 OFF
Layer 2 OFF
Layer 3 ON
Guides and Grids ON

These values are set in the OptionalContentConfig section of the program.  The OptionalContentConfig has three properties that can be applied to each layer, the BaseState, the ON array, and the OFF array.  The BaseState is the default state for all of the layers in the PDF file, so if you define the BaseState to OFF, you can then set one layer to ON and only that layer will appear in the PDF file.

So to reach the goal above we can use three methods:

  1. Set the BaseState to OFF and set Layer 3 and Grids to ON.
  2. Set the BaseState to ON and set Layer 1 and Layer 2 to OFF.
  3. Set the BaseState to Unchanged, and set Layer 1 and Layer 2 to OFF and Layer 3 and Grids to ON. Be careful in using the Unchanged state, however.  The Unchanged state can lead to an array being set to both ON and OFF at the same time.

The related Createlayer program adds a layer to a PDF file.


View Sample Code

Use this program to add a layer to a PDF file, and attach an image to that layer.  The program adds a layer called “Rubber Ducky” to the sample file Ducky.PDF and places the image of the rubber duck in the middle.

The related ChangeLayerConfiguration program makes layers invisible.

You can toggle back and forth to make the layer (the duck image) visible or invisible in the PDF file.  In Adobe Acrobat, click View and select Show/Hide.  Then select Navigation Panes and Layers to display the layers in the PDF file.  Click on the box next to the name of the layer.


View Sample Code

PDF files can have objects that are partially or fully transparent, and thus can blend in various ways with objects behind them.  Transparent graphics or images can be stacked in a PDF file, with each one contributing to the final result that appears on the page.  This is in contrast to opaque objects, where if you have a stack of graphics or images, only the graphic or image on top of the stack will appear.  One or more graphics images presented together in a stack is referred to as a transparency group. With a stack of transparent images, the final colors shown are the result of blending the colors of all of the overlapping objects.

The Flatten Transparency program simply merges a stack of transparent objects or graphics images into a single image on the page.  After this process the original set of transparent objects cannot be broken out again into their constituent parts.  Flattening images in a PDF file is generally necessary before you can send the document to a printer.  The flattening process simplifies the PDF file and may make it smaller as well.  Note that the flatten transparency process does not flatten layers within the PDF file (also known as Optional Content Groups).

The sample program checks each page of the PDF file for any transparencies.  If a page has transparency, this program will create a new, flattened version of the page and replace the original page with the new one.  The program demonstrates both how to flatten a single page document and a multi-page document, and generates a pair of PDF output files.