cloud.opencode.base.image.core.Raster

public final class Raster extends Object

Mutable rectangular pixel container, zero-AWT replacement for BufferedImage. 可变矩形像素容器，零 AWT 的 BufferedImage 替代。

Backed by a contiguous byte[] buffer with an optional non-tight stride (row pitch in bytes). Sub-views share the parent buffer and may have a different stride than width * bytesPerPixel to span sub-rectangles cheaply without copying.

底层为连续的 byte[] 缓冲区，可选非紧凑 stride（每行字节跨距）。子视图共享父缓冲区，且 stride 可与 width * bytesPerPixel 不同，从而以零拷贝代价跨越子矩形。

Thread safety | 线程安全: Not thread-safe. Synchronize externally if accessing from multiple threads. 非线程安全。如需多线程访问，请在外部同步。

Since:

JDK 25, opencode-base-image V1.0.4

Author:

Leon Soo www.LeonSoo.com

See Also:

Field Summary

Fields

Modifier and Type

Field

Description

static final long

MAX_PIXELS

Maximum total pixels allowed in a single Raster (256 megapixels).
Method Summary

Modifier and Type

Method

Description

int

byteOffsetOf(int x, int y)

Byte offset of pixel (x, y) inside data().

Raster

copy()

Returns a deep copy with tight stride, fresh buffer, only the visible sub-region.

static Raster

create(int width, int height, PixelFormat format)

Allocates a fresh Raster of the given dimensions with tight stride (zero-filled).

byte[]

data()

Returns the underlying byte buffer.

boolean

equals(Object o)

void

fill(int argb)

Fills every pixel in this raster with the given ARGB color.

PixelFormat

format()

static Raster

fromBmp(DecodedBmp bmp)

Builds an RGB_8 Raster sharing the BMP's RGB buffer.

static Raster

fromGif(DecodedGif gif)

Builds an RGBA_8 Raster sharing the GIF frame's RGBA buffer.

static Raster

fromJpeg(DecodedJpeg jpeg)

Builds an RGB_8 Raster sharing the JPEG's RGB buffer.

static Raster

fromPng(DecodedPng png)

Builds a Raster from a decoded PNG, choosing RGBA_8 when the source has alpha and RGB_8 otherwise.

static Raster

fromWebp(DecodedWebp webp)

Builds a Raster sharing the WebP's pixel buffer; RGBA_8 when the WebP carries alpha, otherwise RGB_8.

int

getPixelArgb(int x, int y)

Reads a single pixel and packs it as 0xAARRGGBB int.

int

hashCode()

int

height()

boolean

isTight()

Whether this raster spans the entire underlying buffer with tight stride.

void

setPixelArgb(int x, int y, int argb)

Sets a pixel from 0xAARRGGBB int (alpha ignored for non-alpha formats).

int

stride()

Raster

subView(int x, int y, int w, int h)

Returns a sub-view sharing this raster's underlying buffer.

String

toString()

byte[]

toTightBytes()

Returns a tight-packed byte[] of the visible sub-region.

int

width()

static Raster

wrap(byte[] data, int width, int height, PixelFormat format)

Wraps existing pixel data (no copy) with tight stride.

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

Field Details
- MAX_PIXELS
  public static final long MAX_PIXELS
  
  Maximum total pixels allowed in a single Raster (256 megapixels). 单个 Raster 允许的最大总像素数（256 兆像素）。
  Aligned with the opencode-base-image-codec decode-bomb cap to keep the three-layer image stack consistent. Guards against integer overflow in stride/buffer computations and accidental multi-GB allocations from malformed inputs.
  
  与 opencode-base-image-codec 的 decode-bomb 上限对齐，保持三层图像栈一致。防止 stride/缓冲计算的整数溢出，以及畸形输入触发的数 GB 级别意外分配。
  
  See Also:
  
  Constant Field Values
Method Details
- create
  
  public static Raster create(int width, int height, PixelFormat format)
  
  Allocates a fresh Raster of the given dimensions with tight stride (zero-filled). 以紧凑 stride 分配指定尺寸的新 Raster（零填充）。
  
  Parameters:
  
  width - image width in pixels (positive) | 图像宽度（像素，正整数）
  
  height - image height in pixels (positive) | 图像高度（像素，正整数）
  
  format - pixel format | 像素格式
  
  Returns:
  
  a freshly allocated zero-filled Raster | 新分配的零填充 Raster
  
  Throws:
  
  IllegalArgumentException - if width/height is not positive (basic dimension precondition) | width/height 非正时抛出（基础维度前置条件）
  
  OpenImageCoreException - if width * height exceeds MAX_PIXELS, or if the resulting buffer length would exceed Integer.MAX_VALUE | width * height 超过 MAX_PIXELS，或缓冲长度超出 Integer.MAX_VALUE 时抛出
- wrap
  
  public static Raster wrap(byte[] data, int width, int height, PixelFormat format)
  
  Wraps existing pixel data (no copy) with tight stride. 包装已有像素数据（不拷贝），使用紧凑 stride。
  
  Parameters:
  
  data - tightly packed pixel buffer | 紧密排列的像素缓冲
  
  width - image width in pixels (positive) | 图像宽度（像素，正整数）
  
  height - image height in pixels (positive) | 图像高度（像素，正整数）
  
  format - pixel format | 像素格式
  
  Returns:
  
  a Raster sharing the supplied buffer | 共享给定缓冲的 Raster
  
  Throws:
  
  IllegalArgumentException - if width/height is not positive | width/height 非正时抛出
  
  OpenImageCoreException - if width * height exceeds MAX_PIXELS, the buffer length exceeds Integer.MAX_VALUE, or data.length does not match the declared dimensions | width * height 超过 MAX_PIXELS、缓冲长度超出 Integer.MAX_VALUE，或 data.length 与声明维度不符时抛出
- fromPng
  
  public static Raster fromPng(DecodedPng png)
  
  Builds a Raster from a decoded PNG, choosing RGBA_8 when the source has alpha and RGB_8 otherwise. When alpha is present the RGB and alpha channels are interleaved into a fresh RGBA buffer. 由解码后的 PNG 构造 Raster：源含 alpha 时使用 RGBA_8，否则使用 RGB_8。含 alpha 时将 RGB 与 alpha 交错合成新缓冲。
  
  Parameters:
  
  png - decoded PNG | 解码后的 PNG
  
  Returns:
  
  a Raster containing the PNG's pixels | 包含 PNG 像素的 Raster
  
  Throws:
  
  IllegalArgumentException - if dimensions are non-positive (basic dimension precondition) | 维度非正时抛出（基础维度前置条件）
  
  OpenImageCoreException - if dimensions exceed MAX_PIXELS, or if rgb/alpha buffer lengths don't match the declared dimensions | 维度超过 MAX_PIXELS，或 rgb/alpha 缓冲长度与声明维度不符时抛出
- fromJpeg
  
  public static Raster fromJpeg(DecodedJpeg jpeg)
  
  Builds an RGB_8 Raster sharing the JPEG's RGB buffer. 构造与 JPEG 共享 RGB 缓冲的 RGB_8 Raster。
  
  Parameters:
  
  jpeg - decoded JPEG | 解码后的 JPEG
  
  Returns:
  
  Raster sharing the JPEG buffer | 共享 JPEG 缓冲的 Raster
- fromWebp
  
  public static Raster fromWebp(DecodedWebp webp)
  
  Builds a Raster sharing the WebP's pixel buffer; RGBA_8 when the WebP carries alpha, otherwise RGB_8. 构造与 WebP 共享像素缓冲的 Raster：含 alpha 时为 RGBA_8，否则为 RGB_8。
  
  Parameters:
  
  webp - decoded WebP | 解码后的 WebP
  
  Returns:
  
  Raster sharing the WebP buffer | 共享 WebP 缓冲的 Raster
- fromBmp
  
  public static Raster fromBmp(DecodedBmp bmp)
  
  Builds an RGB_8 Raster sharing the BMP's RGB buffer. 构造与 BMP 共享 RGB 缓冲的 RGB_8 Raster。
  
  Parameters:
  
  bmp - decoded BMP | 解码后的 BMP
  
  Returns:
  
  Raster sharing the BMP buffer | 共享 BMP 缓冲的 Raster
- fromGif
  
  public static Raster fromGif(DecodedGif gif)
  
  Builds an RGBA_8 Raster sharing the GIF frame's RGBA buffer. 构造与 GIF 帧共享 RGBA 缓冲的 RGBA_8 Raster。
  
  Parameters:
  
  gif - decoded GIF first frame | 解码后的 GIF 首帧
  
  Returns:
  
  Raster sharing the GIF buffer | 共享 GIF 缓冲的 Raster
- width
  
  public int width()
  
  Returns:
  
  width in pixels | 像素宽度
- height
  
  public int height()
  
  Returns:
  
  height in pixels | 像素高度
- stride
  
  public int stride()
  
  Returns:
  
  row pitch (bytes per row in data()) | 每行字节跨距（data() 中）
- format
  
  public PixelFormat format()
  
  Returns:
  
  pixel format | 像素格式
- data
  
  public byte[] data()
  
  Returns the underlying byte buffer. 返回底层字节缓冲。
  Caller MUST NOT mutate when this Raster is a sub-view or shared. 当此 Raster 为子视图或共享时，调用方禁止修改。
  
  Returns:
  
  underlying buffer (live reference) | 底层缓冲（活引用）
- isTight
  
  public boolean isTight()
  
  Whether this raster spans the entire underlying buffer with tight stride. 此 raster 是否以紧凑 stride 覆盖整个底层缓冲。
  
  Returns:
  
  true if tight and full | 既紧凑又完整时返回 true
- byteOffsetOf
  
  public int byteOffsetOf(int x, int y)
  
  Byte offset of pixel (x, y) inside data(). 像素 (x, y) 在 data() 中的字节偏移。
  
  Parameters:
  
  x - x coordinate (0-based) | x 坐标（从 0 开始）
  
  y - y coordinate (0-based) | y 坐标（从 0 开始）
  
  Returns:
  
  absolute byte offset | 绝对字节偏移
- getPixelArgb
  
  public int getPixelArgb(int x, int y)
  
  Reads a single pixel and packs it as 0xAARRGGBB int. 读取单个像素并打包为 0xAARRGGBB 整数。
  For RGB_8 / BGR_8 / GRAY_8 the alpha bits are 0xFF (fully opaque). 对 RGB_8 / BGR_8 / GRAY_8， alpha 位为 0xFF（完全不透明）。
  
  Parameters:
  
  x - x coordinate | x 坐标
  
  y - y coordinate | y 坐标
  
  Returns:
  
  packed ARGB int | 打包后的 ARGB 整数
- setPixelArgb
  
  public void setPixelArgb(int x, int y, int argb)
  
  Sets a pixel from 0xAARRGGBB int (alpha ignored for non-alpha formats). 由 0xAARRGGBB 整数设置像素（无 alpha 格式忽略 alpha）。
  For grayscale formats, the input RGB is converted using the BT.601 luminance formula Y = 0.299R + 0.587G + 0.114B (integer approximation, half-up rounding). 对于灰度格式，使用 BT.601 亮度公式 Y = 0.299R + 0.587G + 0.114B（整数近似，四舍五入）将输入 RGB 转换。
  
  Parameters:
  
  x - x coordinate | x 坐标
  
  y - y coordinate | y 坐标
  
  argb - packed ARGB int | 打包的 ARGB 整数
- subView
  
  public Raster subView(int x, int y, int w, int h)
  
  Returns a sub-view sharing this raster's underlying buffer. 返回与此 raster 共享底层缓冲的子视图。
  The returned Raster has the same format and stride, but width/height limited to the requested rectangle. Mutations to either side propagate. 返回的 Raster 具有相同的格式和 stride，但宽/高被限制到所请求的矩形。任一侧的修改都会传播。
  
  Parameters:
  
  x - sub-region origin x | 子区域起点 x
  
  y - sub-region origin y | 子区域起点 y
  
  w - sub-region width | 子区域宽度
  
  h - sub-region height | 子区域高度
  
  Returns:
  
  sub-view sharing the buffer | 共享缓冲的子视图
- copy
  
  public Raster copy()
  
  Returns a deep copy with tight stride, fresh buffer, only the visible sub-region. 返回深拷贝：紧凑 stride、新缓冲、仅可见子区域。
  
  Returns:
  
  deep copy | 深拷贝
- toTightBytes
  
  public byte[] toTightBytes()
  
  Returns a tight-packed byte[] of the visible sub-region. 返回可见子区域的紧密打包 byte[]。
  Length is width * height * bytesPerPixel. 长度为 width * height * bytesPerPixel。
  
  Returns:
  
  fresh tight-packed buffer | 新的紧密打包缓冲
- fill
  
  public void fill(int argb)
  
  Fills every pixel in this raster with the given ARGB color. 用给定的 ARGB 颜色填充此 raster 中的每个像素。
  Implementation strategy: for GRAY_8 the whole row is a uniform byte and is cleared via Arrays.fill(long[], long); for multi-byte formats one pixel is encoded into a small template, the first row is built once via byte-doubling System.arraycopy, and subsequent rows are produced by row-level arraycopy. This is typically 5–20× faster than per-pixel encoding for large rasters.
  
  实现策略：GRAY_8 整行字节相同，使用 Arrays.fill(long[], long)；多字节格式则把一个像素编码到小模板缓冲，首行通过字节倍增 System.arraycopy 构建，后续行使用行级 arraycopy 复制。对大尺寸 raster 通常比逐像素编码快 5–20 倍。
  
  Parameters:
  
  argb - packed ARGB int | 打包的 ARGB 整数
- equals
  
  public boolean equals(Object o)
  
  Overrides:
  
  equals in class Object
- hashCode
  
  public int hashCode()
  
  Overrides:
  
  hashCode in class Object
- toString
  
  public String toString()
  
  Overrides:
  
  toString in class Object

Class Raster

Field Summary

Method Summary

Methods inherited from class Object

Field Details

MAX_PIXELS

Method Details

create

wrap

fromPng

fromJpeg

fromWebp

fromBmp

fromGif

width

height

stride

format

data

isTight

byteOffsetOf

getPixelArgb

setPixelArgb

subView

copy

toTightBytes

fill

equals

hashCode

toString