pdfBeginLayer

Purpose — Start a marked-content region scoped to a layer or layer group, on the currently open content stream.

Description — Accepts either an OCG handle (from pdfCreateOCG) or an OCMD handle (from pdfCreateOCMD) — the two handle spaces are disjoint (OCMD handles are >= 1,000,000), so a single parameter can address both. Writes /OC /<alias> BDC to the open content stream and increments an open-layer counter; every pdfBeginLayer must be matched by exactly one pdfEndLayer (nesting is tracked by a simple counter, not a stack of specific handles, so mismatched nesting between different layers is not detected).

Declarations

BOOL32 __stdcall pdfBeginLayer(PPDF IPDF, uint32_t OCG);

function pdfBeginLayer(const IPDF: PPDF; OCG: Cardinal): LongBool; stdcall; external 'LumasPdf.dll';

Parameters

Return value — TRUE on success; FALSE if the handle is invalid (in either space) or there is no open content stream to write to.

Remarks — Content drawn between pdfBeginLayer/pdfEndLayer is visible only when the referenced layer (or, for an OCMD, per its pdfCreateOCMD visibility policy) is ON in the viewer.

Example — Delphi (production)

var P: PPDF; ocg: Integer;
begin
  P := pdfNewPDF;
  try
    pdfCreateNewPDFW(P, 'layers.pdf');
    ocg := pdfCreateOCGA(P, 'Watermark', True, False, oiView);  // hidden by default
    pdfAppend(P);
    pdfBeginLayer(P, Cardinal(ocg));
    pdfWriteFText(P, 100, 700, 'DRAFT');
    pdfEndLayer(P);
    pdfEndPage(P);
    pdfCloseFile(P);
  finally
    pdfDeletePDF(P);
  end;
end;

See also — pdfEndLayer, pdfCreateOCMD

C# (P/Invoke)

[return: MarshalAs(UnmanagedType.Bool)]