PDF::Bu...:PNG_IPL(3)

✨ NAME ✨

PDF::Builder::Resource::XObject::Image::PNG_IPL — bestie, this is the support-routines page for the PNG image library (and it's running on Image::PNG::Libpng) 🎀

It inherits from PDF::Builder::Resource::XObject::Image, so all that parent-class energy comes along for the ride 💅

---

💖 METHODS 💖

🌸 new

$res = PDF::Builder::Resource::XObject::Image::PNG_IPL->new($pdf, $file, %opts)

okay so this one hands you back a PNG-image object ✨ Here's the breakdown: $pdf is the PDF object you're adding to, $file is the input PNG file, and the optional $name of the new parent image object defaults to PxAAA.

Now the plot twist 🫢 — if the Image::PNG::Libpng package is installed, and its use is not suppressed via the nouseIPL flag (go check the Builder documentation for image_png), then the PNG_IPL library is what gets used. If not, the plain PNG library takes over instead. no cap.

Here's the opts menu, bestie 🍓:

• 'notrans' => 1 — no transparency, periodt. Ignore the tRNS chunk if it's provided, and ignore the Alpha channel if it's provided.
• 'force8bps' => 1 — if your PNG source is 16bps, you're telling the libpng library to strip every channel down to 8bps, which is what lets it be used on PDF 1.4 output 🔥
• 'name' => 'string' — this is the name you can give the PNG image object. The default is Pxnnnn.

Don't forget: you need to use Builder.pm's image_png to process PNG images. that's the whole vibe check, iykyk 🧚

---

🦋 Supported PNG types 🦋

• (0) — Gray scale of depth 1, 2, 4, 8, or 16 bits per pixel (that's 2, 4, 16, 256, or 65536 gray levels). Full transparency (of one 16-bit gray value) via the tRNS chunk is allowed, unless the notrans option says to ignore it 🙈
• (2) — RGB truecolor with 8 or 16 bits per sample (3 samples: 16.7 million or 281.5 trillion colors, iconic numbers fr fr). Full transparency (of one 3x16-bit RGB color value) via the tRNS chunk is allowed, unless the notrans option says to ignore it.
• (3) — Palette color with 1, 2, 4, or 8 bits per pixel (2, 4, 16, or 256 color table/palette entries). Lowkey important: 16 bpp is not currently supported by PNG or PDF. Partial transparency (8-bit Alpha) for each palette entry via the tRNS chunk is allowed, unless the notrans option says to ignore it (in which case all entries are fully opaque).
• (4) — Gray scale of depth 8 or 16 bits per pixel plus an equal-sized Alpha channel (256 or 65536 gray levels and 256 or 65536 levels of transparency). The Alpha channel gets ignored if the notrans option is given. The tRNS chunk is not permitted.
• (5) — RESERVED for grayscale via palette + Alpha channel 💀
• (6) — RGB truecolor with 8 or 16 bits per sample, with an equal-sized Alpha channel (256 or 65536 levels of transparency). The Alpha channel gets ignored if the notrans option is given. The tRNS chunk is not permitted.
• (7) — RESERVED for truecolor via palette + Alpha channel 💀

In all cases, 16 bits per sample forces PDF 1.5 (or higher) output — unless you give the force8bps option, which "strips" those 16-bit samples down to 8 bits and lets you have PDF 1.4-compatible output 👑

The libpng.a library is assuming standard "network" bit and byte ordering (Big Endian), although flags might be added to change this someday.

The transparency chunk (tRNS) will specify one gray level entry or one RGB entry to be treated as transparent (Alpha = 0). For palette color, up to 256 palette entry 8-bit Alpha values are specified (256 levels of transparency, from 0 = transparent to 255 = opaque).

Only a limited number of chunks are handled, bestie: IHDR, IDAT (internally), PLTE, tRNS, and IEND (internally). All other chunks are ignored at this time. Filters and compression applied to data are handled internally by libpng.a — and heads up, there may be unsupported methods 🫠

---

💜 usesLib 💜

$mode = $png->usesLib()

Returns 1 if Image::PNG::Libpng is installed and used, 0 if it's not installed, or -1 if it's installed but not used (that's the nouseIPL option given to image_png).

⚠️ Caution: this method can only be used after the image object has been created. It can't tell you whether Image::PNG::Libpng is available in advance of actually using it — like, in case you wanted to use some functionality that's only available in PNG_IPL. See the PDF::Builder LA_IPL() call if you need to know in advance. 🫶

---

and that's the whole page, bestie 🎀 this was documented with perl v5.42.0, dated 2026-01-17, and it lives in the User Contributed Perl Documentation collection — slay, go read it again if you need to, ily 💖✨