THotPDF.AddImageWithSMask Method

Adds a color image XObject together with a PDF 1.4 soft-mask image XObject (ISO 32000-1 8.9.5.4) so the resulting picture carries full per-pixel transparency instead of the binary on/off limit of the legacy /ImageMask path.

加入 color image XObject 與 PDF 1.4 soft-mask image XObject (ISO 32000-1 8.9.5.4)，使產生的圖片帶有完整 per-pixel transparency，而不是舊式 /ImageMask path 的二元開關限制

function AddImageWithSMask(Width, Height: Integer; const RGB: TBytes; const Alpha: TBytes): Integer;

__property int AddImageWithSMask(int Width, int Height, const TBytes& RGB, const TBytes& Alpha);

傳回值：與 AddImage 傳回值相同的 XImages index；請將它傳給 THPDFPage.ShowImage 以將圖片放置在頁面上。當 StrictVersionLock 啟用且目前 Version 低於 PDF 1.4 時傳回 -1；否則 version 會自動提升到 1.4

- RGB: Width * Height * 3 bytes, row-major top-down, R G B interleaved per pixel (no row padding).

- Alpha: Width * Height bytes, row-major top-down, 8-bit luminosity per pixel.

這是常見「我有一張帶 alpha 的 PNG」workflow 的便利 overload。TBitmap 必須具有 PixelFormat = pf32bit；HotPDF 會直接讀取 BGRA ScanLine rows，將其重排為 color plane 的 R G B，並在委派給 raw AddImageWithSMask entry point 前，將 A byte 複製到 alpha planePixels must contain Width * Height * 4 bytes in R, G, B, A order. HotPDF splits the buffer into the RGB color plane and the 8-bit alpha plane before delegating to AddImageWithSMask

傳回值：XImages 中的 index，與 AddImage 傳回的值相同；請將它傳給 THPDFPage.ShowImage 以在頁面放置圖片。當 StrictVersionLock 開啟且 active Version 低於 PDF 1.4 時傳回 -1；否則 version 會自動提升到 1.4XImages identical to the one AddImage returns; pass it to THPDFPage.ShowImage to place the picture on a page. Returns -1 when StrictVersionLock is on and the active Version is below PDF 1.4 (otherwise the version is auto-bumped to 1.4).

Code Example

// Raw-bytes path: build a 64x64 magenta-on-white plane + horizontal
// alpha gradient and place the result on the page
var
  RGB, Alpha: TBytes;
  W, H, X, Y, Idx, ImIdx: Integer;
begin
  W := 64;
  H := 64;
  SetLength(RGB,   W * H * 3);
  SetLength(Alpha, W * H);
  for Y := 0 to H - 1 do
    for X := 0 to W - 1 do
    begin
      Idx := Y * W + X;
      RGB[Idx * 3 + 0] := 255;    // R
      RGB[Idx * 3 + 1] := 0;      // G
      RGB[Idx * 3 + 2] := 255;    // B
      Alpha[Idx]       := Byte((X * 255) div (W - 1));
    end;

  HPDF.Version    := pdf14;       // SMask requires PDF 1.4
  HPDF.Compression := cmFlateDecode;
  HPDF.BeginDoc;
  ImIdx := HPDF.AddImageWithSMask(W, H, RGB, Alpha);
  HPDF.CurrentPage.ShowImage(ImIdx, 80, 80, 256, 256, 0);
  HPDF.EndDoc;
end;