Class JpegCodec

java.lang.Object

cloud.opencode.base.image.codec.jpeg.JpegCodec

public final class JpegCodec
extends Object

JPEG codec backed by libjpeg-turbo via Foreign Function & Memory API. 基于 FFM API 调用 libjpeg-turbo 的 JPEG 编解码器。

Provides three operations:

• encode(byte[], int, int, JpegOptions) — RGB pixels to JPEG bytes. - 将 RGB 像素编码为 JPEG 字节流。
• decode(byte[]) — JPEG bytes to RGB pixels. - 将 JPEG 字节流解码为 RGB 像素。
• readHeader(byte[]) — JPEG dimensions/subsampling without pixel decode. - 仅读取 JPEG 尺寸/下采样信息，不解码像素。

Pixel layout for both encode input and decode output is tightly packed 8-bit RGB, row by row top-to-bottom. rgb.length == width * height * 3.

编码输入与解码输出的像素布局均为紧密排列的 8 位 RGB，自上而下逐行。 rgb.length == width * height * 3。

Security | 安全性:

• Thread-safe: Yes - each call creates a fresh native compress/decompress handle inside a confined Arena; no shared mutable state. - 线程安全: 是 — 每次调用在受限 Arena 中创建独立的 native 压缩/解压 handle， 无共享可变状态。
• Bounds-checked: input arrays are validated; native buffer sizes derived from width * height * 3 (decode) or tjBufSize-managed (encode). - 边界检查: 严格校验输入；native 缓冲区大小由 width * height * 3（decode）或 tjBufSize（encode）决定。
• Resource-safe: native handles closed in finally blocks; native buffers freed via tjFree. - 资源安全: native handle 在 finally 中释放；native 缓冲区通过 tjFree 释放。

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 DecodedJpeg	decode(byte[] jpeg)	Decodes a JPEG byte stream to tightly packed RGB pixels.
static byte[]	encode(byte[] rgb, int width, int height, JpegOptions options)	Encodes tightly packed RGB pixels to a JPEG byte stream.
static JpegHeader	readHeader(byte[] jpeg)	Reads dimensions and subsampling mode from a JPEG 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,
 JpegOptions options)

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

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 JPEG bytes | 编码后的 JPEG 字节

Throws:

IllegalArgumentException - for invalid arguments | 入参非法时

OpenImageCodecException - on native failure | native 失败时

decode

public static DecodedJpeg decode(byte[] jpeg)

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

Parameters:

jpeg - JPEG byte stream | JPEG 字节流

Returns:

decoded DecodedJpeg | 解码结果 DecodedJpeg

Throws:

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

OpenImageCodecException - on native failure | native 失败时

readHeader

public static JpegHeader readHeader(byte[] jpeg)

Reads dimensions and subsampling mode from a JPEG byte stream without decoding pixels. 读取 JPEG 字节流的尺寸与下采样模式，不解码像素。

Parameters:

jpeg - JPEG byte stream | JPEG 字节流

Returns:

parsed JpegHeader | 解析得到的 JpegHeader

Throws:

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

OpenImageCodecException - on native failure | native 失败时