THotPDF.AddImageWithSMask Method

添加一个彩色图像 XObject，同时添加一个 PDF 1.4 soft-mask 图像 XObject（ISO 32000-1 8.9.5.4），使最终图片携带完整的逐像素透明度，而不是旧式 /ImageMask 路径那种二值开/关限制。

function AddImageWithSMask(Width, Height: Integer; const RGB: array of Byte; const Alpha: array of Byte): Integer;

function AddImageWithTransparency(Width, Height: Integer; const RGB: array of Byte; const Alpha: array of Byte): Integer;

function AddImageWithSMask32(Width, Height: Integer; const Pixels: array of Byte): Integer;

function AddImageWithTransparency32(Width, Height: Integer; const Pixels: array of Byte): Integer;

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

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

SMask 图像携带独立的 8 位 DeviceGray 通道，其亮度在绘制时驱动彩色图像的 alpha（0 = 全透明，255 = 不透明）。HotPDF 把两个平面都输出为 Flate 压缩的 image XObject，把彩色图像字典的 /SMask 条目接到软蒙版 XObject，并返回XImages 索引，THPDFPage.ShowImage 可直接接受——下游放置代码无需改动。

AddImageWithTransparency 与 AddImageWithTransparency32 是同一 PDF 1.4 软蒙版工作流的命名别名，供以“透明图像”而非 PDF 字典术语思考的调用点使用

- RGB：Width * Height * 3 字节，行优先自顶向下，每像素 R G B 交错（无行填充）。

- Alpha：Width * Height 字节，行优先自顶向下，每像素 8 位亮度。

面向打包 32 位 RGBA 输入的便捷重载。Pixels 必须含 Width * Height * 4 字节，按 R、G、B、A 顺序。HotPDF 先把缓冲拆成 RGB 彩色平面和 8 位 alpha 平面，再委托给 AddImageWithSMask

返回值：指向XImages 的索引，与 AddImage 返回的一致；把它传给THPDFPage.ShowImage 即可把图像放到页面上。返回-1 ——当 StrictVersionLock 开启且当前 Version 低于 PDF 1.4 时（否则版本自动升到 1.4）。

代码示例

// 原始字节路径：构建 64x64 白底品红平面 + 水平 alpha 渐变并放到页面上
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 需要 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;