pdfPlaceTemplByMatrix

BOOL32 __stdcall pdfPlaceTemplByMatrix(PPDF IPDF, int32_t TmplHandle);

function pdfPlaceTemplByMatrix(const IPDF: PPDF; TmplHandle: Integer): LongBool; stdcall;

Purpose. Place a previously-created template (or pattern-scratch surface — same PlaceTemplate mechanism), sized at its natural BBox dimensions and positioned at the origin, so that the placement is entirely governed by whatever coordinate transform is already active in the current content stream — set up beforehand via pdfSetMatrix/ pdfRotateCoords/pdfScaleCoords/pdfSkewCoords.

Description. Despite taking no matrix parameter itself, "ByMatrix" is accurate: internally this calls the same PlaceTemplate used by the plain pdfPlaceTemplate (which instead takes explicit PosX/PosY/ ScaleWidth/ScaleHeight arguments), but always with PosX=PosY=ScaleW=ScaleH=0. A 0 scale falls back to the template's natural BBox size, and PosX=PosY=0 places its origin at the current content-stream origin — PlaceTemplate wraps its own q ... cm /Tpl Do Q bracket around the placement, so whatever CTM was already concatenated onto the content stream via prior pdfSetMatrix/pdfRotateCoords/ pdfScaleCoords/pdfSkewCoords calls (all of which write real cm operators — see the previous chapter) is captured by that q and determines the template's actual on-page position, scale, and rotation. This is the intended division of labor between the two placement entry points: use pdfPlaceTemplate for direct positional placement, or set up a transform first and use pdfPlaceTemplByMatrix for transform-driven placement (e.g. placing a template rotated/skewed, which pdfPlaceTemplate's plain position+scale arguments cannot express).

Parameters.

Return value. True on success; False if there is no open page or TmplHandle does not resolve to an existing template.

See also. pdfSetMatrix, pdfPlaceTemplate (the explicit-position sibling, not covered in this volume).

C# (P/Invoke)

[return: MarshalAs(UnmanagedType.Bool)]