Cache Repeated Images

When you render an image in DsPdf multiple times (e.g. rendering the same image as part of a page header on all pages), it will automatically be added to a dictionary and reused throughout the document, provided you use the same image object on all pages.

So rather than loading the same image from file (or stream) each time it is needed, it is always preferable to load the image once and cache it in an image object. This applies to all image types available in DsPdf (Image, RawImage, ImageWrapper).

Refer to the following code sample to see a demonstration of caching an image in an image object:

public int CreatePDF(Stream stream)
        {
            var doc = new GcPdfDocument();
 
            // Text format used to draw captions:
            var tf = new TextFormat() { Font = StandardFonts.Times, FontSize = 12 };
 
            // Action to draw the image with various alignment options:
            Action<GCDRAW.Image, Page, ImageAlign, bool> drawImage = (image_, page_, ia_, clip_) =>
            {
                var rect = new RectangleF(72, 72, 72 * 4, 72 * 4);
                var clipped = clip_ ? "clipped to a 4\"x4\" rectangle" : "without clipping";
                var align = ia_ == ImageAlign.Default ? "ImageAlign.Default" :
                    ia_ == ImageAlign.CenterImage ? "ImageAlign.CenterImage" :
                    ia_ == ImageAlign.StretchImage ? "ImageAlign.StretchImage" : "custom ImageAlign";
                // Draw image caption:
                page_.Graphics.DrawString($"Page {doc.Pages.IndexOf(page_) + 1}: Image drawn at (1\",1\"), {clipped}, using {align}:", tf, new PointF(72, 36));
                var clip = clip_ ? new Nullable<RectangleF>(rect) : new Nullable<RectangleF>();
                // Draw the image:
                page_.Graphics.DrawImage(image_, rect, clip, ia_, out RectangleF[] imageRects);
                // Show the image outline:
                page_.Graphics.DrawRectangle(imageRects[0], Color.Red, 1, null);
                // Show image/clip area:
                page_.Graphics.DrawRectangle(rect, Color.Blue, 1, null);
            };
 
            // Create images from JPEG files (using the same Image class instance to draw an image
            // in a PDF ensures that the image data will be reused and not duplicated in the PDF):
            using var image = GCDRAW.Image.FromFile(Path.Combine("Resources", "Images", "puffins.jpg"));
            using var imageSmall = GCDRAW.Image.FromFile(Path.Combine("Resources", "ImagesBis", "puffins-small.jpg"));
 
            // The ImageAlign class provides various image alignment options.
            // It also defines a few static instances with some commonly used
            // combinations of options demonstrated below.
 
            // Page 1: draw image without clipping, with default alignment:
            drawImage(image, doc.NewPage(), ImageAlign.Default, false);
 
            // Page 2: draw image with clipping, with default alignment:
            drawImage(image, doc.NewPage(), ImageAlign.Default, true);
 
            // Page 3: draw image with clipping, with CenterImage alignment:
            drawImage(image, doc.NewPage(), ImageAlign.CenterImage, true);
 
            // Done:
            doc.Save(stream);
            return doc.Pages.Count;
        }