Class PngEncoder

java.lang.Object

cloud.opencode.base.image.codec.png.PngEncoder

public final class PngEncoder
extends Object

Pure-Java PNG encoder for image embedding / general use. 用于图像嵌入与通用场景的纯 Java PNG 编码器。

Encodes row-major 8-bit RGB or RGBA pixel data into a standards-compliant non-interlaced PNG byte stream without any dependency on java.desktop (no AWT, no ImageIO). Designed to be GraalVM native-image friendly and suitable for headless environments. Output is losslessly round-trippable through PngDecoder.

将行优先的 8 位 RGB 或 RGBA 像素数据编码为符合标准的非隔行 PNG 字节流， 不依赖 java.desktop（不使用 AWT 与 ImageIO）。设计上对 GraalVM native-image 友好，适用于无头（headless）环境。输出可通过 PngDecoder 完成无损往返解码。

Supported PNG variants | 支持的 PNG 变体:

• Bit depth 8 only - 仅 8 位深度
• colorType 2 (RGB) via encodeRgb(byte[], int, int) - RGB 经 encodeRgb(byte[], int, int)
• colorType 6 (RGBA) via encodeRgba(byte[], int, int) - RGBA 经 encodeRgba(byte[], int, int)
• Filter type 0 (None) for every row - 所有行使用 None 滤波器
• Non-interlaced (interlace=0) only - 仅非隔行

Not supported | 不支持: grayscale, indexed/palette, 16-bit depth, Adam7 interlacing. Callers needing those layouts should convert to RGB or RGBA first and then call this encoder.

不支持：灰度、调色板索引、16 位深度、Adam7 隔行。需要这些布局的调用方 应先转换为 RGB 或 RGBA，再调用本编码器。

Compression note | 压缩说明: filter type 0 (None) is chosen for implementation simplicity. Compression ratios will be lower than encoders that adaptively select per-row sub/up/average/paeth filters; if higher ratios become necessary later, an adaptive filter strategy can be added without changing the public API.

选用 filter 0（None）以简化实现。压缩率不及自适应选择 sub/up/average/paeth 的编码器；若日后需要更高压缩，可在不改变公共 API 的情况下扩展为自适应滤波策略。

Security | 安全性:

• Thread-safe: Yes - all methods are stateless static. - 线程安全: 是 - 所有方法均为无状态静态方法。
• Null-safe: throws on null input. - 空值安全: 输入为 null 时抛异常。
• Validates pixel array length matches dimensions. - 校验像素数组长度与尺寸一致。

Since:

JDK 25, opencode-base-image-codec V1.0.4

Author:

Leon Soo www.LeonSoo.com

See Also:

• OpenCode.cloud

Method Summary

Modifier and Type	Method	Description
static byte[]	encodeRgb(byte[] rgb, int width, int height)	Encodes RGB pixel data (3 bytes per pixel, row-major) as PNG bytes.
static byte[]	encodeRgba(byte[] rgba, int width, int height)	Encodes RGBA pixel data (4 bytes per pixel, row-major) as PNG bytes.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

encodeRgb

public static byte[] encodeRgb(byte[] rgb,
 int width,
 int height)

Encodes RGB pixel data (3 bytes per pixel, row-major) as PNG bytes. 将 RGB 像素数据（每像素 3 字节，行优先）编码为 PNG 字节。

Parameters:

rgb - interleaved RGB bytes, length must equal width*height*3 | 交错的 RGB 字节，长度必须等于 width*height*3

width - image width in pixels (must be > 0) | 图像宽度（像素，必须 > 0）

height - image height in pixels (must be > 0) | 图像高度（像素，必须 > 0）

Returns:

non-interlaced 8-bit PNG byte stream (colorType 2) | 非隔行 8 位 PNG 字节流（colorType 2）

Throws:

IllegalArgumentException - if rgb is null, dimensions are non-positive, or rgb.length != width*height*3 | 当 rgb 为 null、尺寸非正或长度与宽高不匹配时抛出

encodeRgba

public static byte[] encodeRgba(byte[] rgba,
 int width,
 int height)

Encodes RGBA pixel data (4 bytes per pixel, row-major) as PNG bytes. 将 RGBA 像素数据（每像素 4 字节，行优先）编码为 PNG 字节。

Parameters:

rgba - interleaved RGBA bytes, length must equal width*height*4 | 交错的 RGBA 字节，长度必须等于 width*height*4

width - image width in pixels (must be > 0) | 图像宽度（像素，必须 > 0）

height - image height in pixels (must be > 0) | 图像高度（像素，必须 > 0）

Returns:

non-interlaced 8-bit PNG byte stream (colorType 6) | 非隔行 8 位 PNG 字节流（colorType 6）

Throws:

IllegalArgumentException - if rgba is null, dimensions are non-positive, or rgba.length != width*height*4 | 当 rgba 为 null、尺寸非正或长度与宽高不匹配时抛出