Communicating ideas in digital documents can often be made much clearer through the use of layers. Layers have been supported in PDF documents since version 1.5 through optional content groups (OCGs), also known as PDF layers.

“Optional” is key here. OCGs allow us to group images or annotations together, then control their visibility based on conditions such as whether the document is being viewed on screen or being printed, or through a user interacting with the document to enable or disable a layer.

For example, you might want to add a watermark that’s invisible on screen but visible when the PDF is printed, or display a message on screen, but not on the printed version. Or perhaps you want the user to be able to change the language.

In this article, we’ll demonstrate how to create and configure OCGs — layers in a PDF — using C# and GdPicture.NET.


The examples below have been written and tested in C# on .NET Core 3.1 using Visual Studio 16.4.5, but GdPicture.NET is also available for .NET Framework 4.5. Other IDEs should also work so long as you’re able to reference assemblies.

To work along, you can download the following and include them in your project:

If your project is targeting .NET Core, you should also install the NuGet package System.Drawing.Common.

Then just download and install a copy of the GdPicture.NET SDK, following the instructions here.

Creating an OCG Watermark

For the first example, let’s look at how you can use GdPicture.NET to add watermarks to your PDF files in code.

To use all the features of the toolkit, you need to unlock it with a license key (which is supplied with the 60-day trial) in code:

var licenseManager = new LicenseManager();

GdPicture.NET can create PDF content dynamically in code, load it from a PDF, or import a text file. In this example, we’ll load our existing PDF file.