cloud.opencode.base.image.codec.gif.GifCodec

public final class GifCodec extends Object

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

Decodes the first frame of a GIF87a / GIF89a byte stream into row-major RGBA bytes and encodes single-frame GIF89a files (LZW-compressed) without any dependency on java.desktop (no AWT, no ImageIO). The encoder supports inputs with up to 256 unique colours, which is the GIF format limit; callers must externally quantise wider gamut data first.

将 GIF87a / GIF89a 字节流的首帧解码为行优先的 RGBA 字节，并将单帧 GIF89a 文件（LZW 压缩）编码出来，不依赖 java.desktop （不使用 AWT 与 ImageIO）。编码器支持至多 256 种唯一颜色（GIF 格式上限）；调用方需先对超出范围的输入进行外部量化。

Supported decoding | 支持的解码:

GIF87a and GIF89a signatures - 两种签名
Logical Screen Descriptor + global color table - 逻辑屏幕描述符 + 全局色表
Image Descriptor + optional local color table - 图像描述符 + 可选局部色表
LZW compression with sub-block packing - LZW 压缩 + sub-block 拼接
Graphic Control Extension transparency index - 图形控制扩展透明索引
Plain Text and Comment / Application Extensions are skipped. 纯文本与注释/应用扩展会被跳过。

Decoder limitations | 解码器限制:

Only the first frame is returned; multi-frame disposal logic is TODO. 仅返回第一帧；多帧 disposal 逻辑暂未实现。
Interlaced frames are rejected. - 拒绝隔行 (interlaced) 帧。

Supported encoding | 支持的编码:

Single-frame GIF89a, global color table, LZW compressed. 单帧 GIF89a，全局色表，LZW 压缩。
Up to 256 unique colours in the input (GIF hard limit). 输入颜色数 ≤ 256（GIF 硬上限）。
RGBA inputs: alpha == 0 maps to a reserved transparent index. RGBA 输入：alpha == 0 的像素映射到预留的透明索引。

Any unsupported variant raises OpenImageCodecException with a message starting with "unsupported GIF variant: ...".

所有不支持的变体均抛出 OpenImageCodecException，消息以 "unsupported GIF variant: ..." 开头。

Security | 安全性:

Thread-safe: Yes - all methods are stateless static. - 线程安全: 是。
Null-safe: throws on null input. - 空值安全。
Bounded by CodecLimits.MAX_DECODED_BYTES to reject pathological dimensions. 通过 CodecLimits.MAX_DECODED_BYTES 限制以拒绝病态尺寸。

Since:

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

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static DecodedGif

decodeFirstFrame(byte[] gifBytes)

Decodes the first frame of the supplied GIF byte stream.

static byte[]

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

Convenience: encode an RGB byte array (no transparency) as GIF89a.

static byte[]

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

Encodes RGBA pixel data as a single-frame GIF89a.

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- decodeFirstFrame
  
  public static DecodedGif decodeFirstFrame(byte[] gifBytes)
  
  Decodes the first frame of the supplied GIF byte stream. 解码 GIF 字节流的第一帧。
  
  Parameters:
  
  gifBytes - raw GIF byte stream including the 6-byte signature | 含 6 字节签名的原始 GIF 字节流
  
  Returns:
  
  decoded first frame | 解码后的首帧
  
  Throws:
  
  OpenImageCodecException - when the input is not a supported GIF | 当输入不是受支持的 GIF 时抛出
- encodeRgba
  
  public static byte[] encodeRgba(byte[] rgba, int width, int height)
  
  Encodes RGBA pixel data as a single-frame GIF89a. 将 RGBA 像素数据编码为单帧 GIF89a。
  Pixels with alpha == 0 are mapped to a reserved transparent palette index; opaque pixels (any non-zero alpha) are quantised into a single global color table. The input must contain no more than 256 unique opaque colours; otherwise OpenImageCodecException is raised so that callers can decide how to quantise.
  
  alpha == 0 的像素映射到预留的透明调色板索引；不透明像素（任意非零 alpha）合并到单个全局色表。输入不透明像素的唯一颜色数不得超过 256，否则抛出 OpenImageCodecException，以便调用方自行决定量化策略。
  
  Parameters:
  
  rgba - RGBA pixel data, length must equal width*height*4 | RGBA 像素数据，长度必须等于 width*height*4
  
  width - pixel width (must be > 0) | 像素宽度（必须 > 0）
  
  height - pixel height (must be > 0) | 像素高度（必须 > 0）
  
  Returns:
  
  encoded GIF89a byte stream | 编码后的 GIF89a 字节流
  
  Throws:
  
  IllegalArgumentException - on null/invalid arguments | 参数为 null 或非法时抛出
  
  OpenImageCodecException - when the input has more than 256 unique colours | 当输入颜色数 > 256 时抛出
- encodeRgb
  
  public static byte[] encodeRgb(byte[] rgb, int width, int height)
  
  Convenience: encode an RGB byte array (no transparency) as GIF89a. 便捷方法：将 RGB 字节数组（无透明）编码为 GIF89a。
  
  Parameters:
  
  rgb - RGB pixel data, length must equal width*height*3 | RGB 像素数据，长度必须等于 width*height*3
  
  width - pixel width | 像素宽度
  
  height - pixel height | 像素高度
  
  Returns:
  
  encoded GIF89a byte stream | 编码后的 GIF89a 字节流
  
  Throws:
  
  IllegalArgumentException - on null/invalid arguments | 参数非法时抛出
  
  OpenImageCodecException - when the input has more than 256 unique colours | 当输入颜色数 > 256 时抛出

Class GifCodec

Method Summary

Methods inherited from class Object

Method Details

decodeFirstFrame

encodeRgba

encodeRgb