AddImageDirectFromString

Image handling

Description

Creates an image XObject directly from already-encoded image sample bytes instead of detecting a container format such as PNG, TIFF, or JPEG.

PDF version behavior: the JBIG2Decode image filter requires PDF 1.4, while JPXDecode, Crypt, and image samples with BitsPerComponent = 16 require PDF 1.5. When a document is set below the required version and the save version is not locked, AddImageDirectFromString automatically raises the document version and records JBIG2Decode filter, JPXDecode filter, Crypt filter, or 16-bit image samples in AutoBumpedFeatures. If the caller locks a lower save version, the compatibility gate rejects the save with LastErrorCode 602.

Syntax

Delphi

function TPDFlib.AddImageDirectFromString(const Source: AnsiString; Width, Height, BitsPerComponent: Integer; const ColorSpace, Filter, Decode: WideString; Interpolate: Integer): Integer;

Parameters

Source	Raw or encoded image data to store in the image stream.
Width	Image width in pixels.
Height	Image height in pixels.
BitsPerComponent	Number of bits per sample component. PDF image dictionaries allow 1, 2, 4, and 8 in earlier versions; 16-bit samples are PDF 1.5.
ColorSpace	PDF color-space name or array text for the image dictionary, for example `/DeviceGray`, `/DeviceRGB`, or an indexed color-space array.
Filter	PDF stream filter name, such as `FlateDecode`, `DCTDecode`, or `JPXDecode`. Use an empty string for unfiltered data.
Decode	Optional PDF Decode array text. Pass an empty string when no Decode entry is needed.
Interpolate	Nonzero writes the `/Interpolate true` flag.

Return values

0	The image could not be created, or the current PDF/A mode forbids the requested filter.
Non-zero	The new ImageID. The created image is selected for subsequent image operations.

Remarks

PDF/A mode rejects LZWDecode in every part and rejects JBIG2Decode / JPXDecode in PDF/A-1. The caller is responsible for matching Source bytes to the declared ColorSpace, Filter, Decode, dimensions, and sample depth.