Method embedPng

src/api/pdf.ts:2170–2213

* Embed a PNG image into the document. * * PNG images are decoded and re-encoded with FlateDecode filter. * Alpha channels are separated into a soft mask (SMask) for * proper transparency support. * * @param bytes - PNG file bytes * @returns PDFImage that can be drawn with page.

(bytes: Uint8Array)

   * ```
   */
  embedPng(bytes: Uint8Array): PDFImage {
    const data = parsePng(bytes);
    const { info, pixels, alpha } = data;

    // Compress pixel data with FlateDecode
    const compressedPixels = deflate(pixels);

    // Build XObject dictionary
    const dictEntries: Record<string, PdfObject> = {
      Type: PdfName.of("XObject"),
      Subtype: PdfName.of("Image"),
      Width: PdfNumber.of(info.width),
      Height: PdfNumber.of(info.height),
      ColorSpace: PdfName.of(info.colorSpace),
      BitsPerComponent: PdfNumber.of(info.bitDepth > 8 ? 8 : info.bitDepth),
      Filter: PdfName.of("FlateDecode"),
    };

    // If there's alpha, create a soft mask
    if (alpha) {
      const compressedAlpha = deflate(alpha);

      const smaskStream = PdfStream.fromDict(
        {
          Type: PdfName.of("XObject"),
          Subtype: PdfName.of("Image"),
          Width: PdfNumber.of(info.width),
          Height: PdfNumber.of(info.height),
          ColorSpace: PdfName.of("DeviceGray"),
          BitsPerComponent: PdfNumber.of(8),
          Filter: PdfName.of("FlateDecode"),
        },
        compressedAlpha,
      );

      const smaskRef = this.register(smaskStream);
      dictEntries.SMask = smaskRef;
    }

    const stream = PdfStream.fromDict(dictEntries, compressedPixels);
    const ref = this.register(stream);

    return new PDFImage(ref, info.width, info.height);
  }

  // ─────────────────────────────────────────────────────────────────────────────
  // Low-Level Drawing API - Shadings