THotPDF.AddImageWithSMask Method

Добавляет цветной image XObject вместе с soft-mask image XObject из PDF 1.4 (ISO 32000-1 8.9.5.4), так что итоговая картинка получает полную попиксельную прозрачность вместо бинарного предела вкл/выкл у legacy /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, чья яркость управляет альфой цветного изображения в момент отрисовки (0 = полностью прозрачно, 255 = полностью непрозрачно). HotPDF выводит обе плоскости как Flate-сжатые image XObject и привязывает /SMask запись словаря цветного изображения к soft-mask XObject, а возвращает XImages индекс, который THPDFPage.ShowImage принимает напрямую — весь последующий код размещения работает без изменений.

AddImageWithTransparency и AddImageWithTransparency32 — именные псевдонимы того же soft-mask-сценария PDF 1.4. Они нужны точкам вызова, которые думают в терминах прозрачных картинок, а не словарной терминологии PDF

- Width / Height: пиксельные размеры, одинаковые для обеих плоскостей.

- RGB: Width * Height * 3 байтов, по строкам сверху вниз, R G B вперемешку на пиксель (без выравнивания строк).

- Alpha: Width * Height байтов, по строкам сверху вниз, 8-битная яркость на пиксель.

Удобная перегрузка для упакованного 32-битного RGBA-входа. Pixels должен содержать Width * Height * 4 байтов в порядке R, G, B, A. HotPDF разделяет буфер на цветную плоскость RGB и 8-битную альфа-плоскость, затем делегирует в AddImageWithSMask

Возвращаемое значение: индекс в XImages идентичный тому, что возвращает AddImage; передайте его в THPDFPage.ShowImage, чтобы разместить картинку на странице. Возвращает -1, когда StrictVersionLock включён, а активная Версия ниже PDF 1.4 (иначе версия автоматически поднимается до 1.4).

Пример кода

// 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;