Image Resuse

DynamicPDF Core Suite for .NET allows for highly efficient image reuse both within a document or across several documents. The ImageData class is included for this purpose. This class holds the pixel data for an image and is used in the constructors of the Image and BackgroundImage Page Elements. When the same ImageData object is used multiple times in a PDF document, its data is only included once in the resulting PDF document.

NOTE: If the same Image or BackgroundImage Page Element is used multiple times in the same document, image reuse is handled automatically because the same ImageData object is used each time it is displayed. This also applies to images that are used in a single section or document template.

Using The Same Image Multiple Times In A Document

When using an image multiple times in a document, care must be taken to ensure that the image data is not included multiple times in the PDF output. This is accomplished by creating an ImageData object and using that in the Image or BackgroundImage constructors. An image data object can be created using the ImageData classes static GetImage method. Using this technique, the same image can appear at different locations and scale in the document without increasing the overall size of the document:

// Create an ImageData object from the image.
ImageData imageData = ImageData.GetImage( @"C:\MyLogo.gif" );
// Add the image to the fist page twice.
page1.Elements.Add( new BackgroundImage( imageData ) );
page1.Elements.Add( new Image( imageData, 0, 0, 0.24f ) );
// Add the image to the second page at a differant location and scale.
page2.Elements.Add( new Image( imageData, 100, 100, 0.48f ) );        
' Create an ImageData object from the image.
Dim MyImageData As ImageData = ImageData.GetImage( "C:\MyLogo.gif" )
' Add the image to the fist page twice.
MyPage1.Elements.Add( New BackgroundImage( imageData ) )
MyPage1.Elements.Add( New Image( imageData, 0, 0, 0.24f ) )
' Add the image to the second page at a differant location and scale.
MyPage2.Elements.Add( New Image( imageData, 100, 100, 0.48f ) )  

Using The Same Image Across Documents

When an ImageData object is created, resources are required to parse information from the image. If the Image format does not allow for our highly efficient pass through process, additional resources are required to reformat the contents of the image so that it can be included in the PDF document. For images that appear in multiple documents (such as logos) it is best to create an ImageData object and set it to a static member variable of your class. You can then use that static member variable in all of your Image or BackgroundImage constructors.

If the image is being used in a single document or section template, the template object itself can be set to a static member field instead.

NOTE: For web applications that require the MapPath method, you will not be able to use the static constructor to initialize your ImageData static (Shared in VB) member variables. In this case, you can test if the static member variable is null in your Page_Load event and initialize it then. This is required because the MapPath method can not be used from a static constructor of a System.Web.UI.Page object.

In this topic