Class WebpCodec

java.lang.Object

cloud.opencode.base.image.codec.webp.WebpCodec

public final class WebpCodec
extends Object

WebP codec backed by libwebp via Foreign Function & Memory API. 基于 FFM API 调用 libwebp 的 WebP 编解码器。

Provides five operations:

• encode(byte[], int, int, WebpOptions) — RGB pixels to WebP bytes. - 将 RGB 像素编码为 WebP 字节流。
• encodeRgba(byte[], int, int, WebpOptions) — RGBA pixels to WebP bytes. - 将 RGBA 像素编码为 WebP 字节流。
• decode(byte[]) — WebP bytes to RGB pixels. - 将 WebP 字节流解码为 RGB 像素。
• decodeRgba(byte[]) — WebP bytes to RGBA pixels. - 将 WebP 字节流解码为 RGBA 像素。
• readHeader(byte[]) — WebP dimensions without pixel decode. - 仅读取 WebP 尺寸，不解码像素。

Pixel layout for both encode input and decode output is tightly packed 8-bit RGB / RGBA, row by row top-to-bottom. Buffer length is exactly width * height * format.bytesPerPixel().

编码输入与解码输出的像素布局均为紧密排列的 8 位 RGB / RGBA，自上而下逐行。 缓冲区长度恰好为 width * height * format.bytesPerPixel()。

Security | 安全性:

• Thread-safe: Yes - each call uses a confined Arena; no shared mutable state. - 线程安全: 是 — 每次调用使用受限 Arena，无共享可变状态。
• Bounds-checked: input arrays validated; native buffer sizes derived from width * height * bytesPerPixel. - 边界检查: 严格校验输入；native 缓冲区大小由 width * height * bytesPerPixel 决定。
• Resource-safe: native output buffers freed via WebPFree in success and failure paths. - 资源安全: 成功/失败路径均通过 WebPFree 释放 native 输出缓冲区。

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 DecodedWebp	decode(byte[] webpBytes)	Decodes a WebP byte stream to tightly packed RGB pixels.
static DecodedWebp	decodeRgba(byte[] webpBytes)	Decodes a WebP byte stream to tightly packed RGBA pixels.
static byte[]	encode(byte[] rgb, int width, int height, WebpOptions options)	Encodes tightly packed RGB pixels to a WebP byte stream.
static byte[]	encodeRgba(byte[] rgba, int width, int height, WebpOptions options)	Encodes tightly packed RGBA pixels to a WebP byte stream.
static WebpHeader	readHeader(byte[] webpBytes)	Reads dimensions from a WebP byte stream without decoding pixels.

Methods inherited from class Object

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

Method Details

encode

public static byte[] encode(byte[] rgb,
 int width,
 int height,
 WebpOptions options)

Encodes tightly packed RGB pixels to a WebP byte stream. 将紧密排列的 RGB 像素编码为 WebP 字节流。

Parameters:

rgb - RGB pixel buffer of length width*height*3 | 长度为 width*height*3 的 RGB 像素缓冲

width - image width in pixels (positive) | 图像宽度（像素，正整数）

height - image height in pixels (positive) | 图像高度（像素，正整数）

options - encoding options | 编码选项

Returns:

encoded WebP bytes | 编码后的 WebP 字节

Throws:

IllegalArgumentException - for invalid arguments | 入参非法时

OpenImageCodecException - on native failure | native 失败时

encodeRgba

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

Encodes tightly packed RGBA pixels to a WebP byte stream. 将紧密排列的 RGBA 像素编码为 WebP 字节流。

Parameters:

rgba - RGBA pixel buffer of length width*height*4 | 长度为 width*height*4 的 RGBA 像素缓冲

width - image width in pixels (positive) | 图像宽度（像素，正整数）

height - image height in pixels (positive) | 图像高度（像素，正整数）

options - encoding options | 编码选项

Returns:

encoded WebP bytes | 编码后的 WebP 字节

Throws:

IllegalArgumentException - for invalid arguments | 入参非法时

OpenImageCodecException - on native failure | native 失败时

decode

public static DecodedWebp decode(byte[] webpBytes)

Decodes a WebP byte stream to tightly packed RGB pixels. 将 WebP 字节流解码为紧密排列的 RGB 像素。

Parameters:

webpBytes - WebP byte stream | WebP 字节流

Returns:

decoded DecodedWebp with WebpFormat.RGB | 以 WebpFormat.RGB 表示的解码结果 DecodedWebp

Throws:

IllegalArgumentException - if webpBytes is null or empty | 入参非法时

OpenImageCodecException - on native failure | native 失败时

decodeRgba

public static DecodedWebp decodeRgba(byte[] webpBytes)

Decodes a WebP byte stream to tightly packed RGBA pixels. 将 WebP 字节流解码为紧密排列的 RGBA 像素。

Parameters:

webpBytes - WebP byte stream | WebP 字节流

Returns:

decoded DecodedWebp with WebpFormat.RGBA | 以 WebpFormat.RGBA 表示的解码结果 DecodedWebp

Throws:

IllegalArgumentException - if webpBytes is null or empty | 入参非法时

OpenImageCodecException - on native failure | native 失败时

readHeader

public static WebpHeader readHeader(byte[] webpBytes)

Reads dimensions from a WebP byte stream without decoding pixels. 读取 WebP 字节流的尺寸，不解码像素。

Parameters:

webpBytes - WebP byte stream | WebP 字节流

Returns:

parsed WebpHeader | 解析得到的 WebpHeader

Throws:

IllegalArgumentException - if webpBytes is null or empty | 入参非法时

OpenImageCodecException - on native failure | native 失败时