AddAlternateImage

Image handling, optional content

Description

Adds or updates one alternate representation of a base image XObject as defined by ISO 32000-1 §8.9.5.4

Alternate images can provide a high-resolution printing representation or an optional-content-controlled display representation without duplicating page content

Syntax

Function TPDFlib.AddAlternateImage(BaseImageID, AlternateImageID: Integer; DefaultForPrinting: Boolean; OptionalContentID: Integer= 0): Integer;

Parameters

BaseImageID	The image used by page resources and content-stream `Do` operators
AlternateImageID	The image XObject to attach as a variant
DefaultForPrinting	Marks this variant as the preferred printing image and clears that flag from other variants of the same base image
OptionalContentID	An optional OCG or OCMD handle controlling selection of this variant, or 0 for no optional-content condition

Return value

Returns the one-based alternate index, including the existing index when the same image is updated, or 0 when validation fails

Remarks

The base and alternate must be different image objects in the selected document

An image already used as an alternate cannot own its own /Alternates array, and an image that owns alternates cannot be attached as another alternate

Passing an OCG or OCMD raises the minimum PDF version to 1.5; otherwise the minimum version is PDF 1.3

All PDF/A modes reject the operation because ISO 19005 forbids /Alternates in image dictionaries

When the base image has an /OC entry, the built-in renderer displays the base while it is visible and otherwise selects the first visible alternate whose entry has /OC

Example

BaseImageID := PDF.AddImageFromFile('preview.png', 0);
PrintImageID := PDF.AddImageFromFile('print-600dpi.tif', 0);
AlternateIndex := PDF.AddAlternateImage(BaseImageID, PrintImageID, True);