Class ColorTransform

java.lang.Object
cloud.opencode.base.image.codec.color.ColorTransform
All Implemented Interfaces:
AutoCloseable
public final class ColorTransform extends Object implements AutoCloseable
Color transform between two ColorProfiles, backed by an lcms2 cmsHTRANSFORM. 基于 ColorProfile 的色彩变换，底层为 lcms2 的 cmsHTRANSFORM。

Created via create(ColorProfile, PixelFormat, ColorProfile, PixelFormat, RenderingIntent); supports apply(byte[]) for one-shot transforms and apply(byte[], int, byte[], int, int) for in-place batch transforms.

通过 create(ColorProfile, PixelFormat, ColorProfile, PixelFormat, RenderingIntent) 创建；支持 apply(byte[]) 一次性变换和 apply(byte[], int, byte[], int, int) 原地批量变换。

Must be closed via close() (try-with-resources recommended) — the underlying handle is freed by cmsDeleteTransform.

必须通过 close() 释放（建议使用 try-with-resources）— 底层 handle 由 cmsDeleteTransform 释放。

Security | 安全性:

  • Thread-safe: No - external synchronization required for shared instances. - 线程安全: 否 — 共享实例需外部同步。
  • Bounds-checked: input/output offsets and lengths validated before crossing the FFM boundary. - 边界检查：跨 FFM 边界前严格校验 offset/length。
  • Resource-safe: temporary buffers held in confined Arena; no leaks on success or failure. - 资源安全：临时缓冲驻留受限 Arena， 成功/失败均不泄漏。
Since:
JDK 25, opencode-base-image-codec V1.0.4
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • create

      public static ColorTransform create(ColorProfile inProfile, PixelFormat inFormat, ColorProfile outProfile, PixelFormat outFormat, RenderingIntent intent)
      Creates a transform from (inProfile, inFormat) to (outProfile, outFormat) using the given rendering intent. 使用指定渲染意图创建从 (inProfile, inFormat) 到 (outProfile, outFormat) 的变换。
      Parameters:
      inProfile - source profile (must be open) | 源配置文件（必须未关闭）
      inFormat - source pixel format | 源像素格式
      outProfile - destination profile (must be open) | 目标配置文件（必须未关闭）
      outFormat - destination pixel format | 目标像素格式
      intent - rendering intent | 渲染意图
      Returns:
      open transform, caller must close() | 打开的变换，调用方需 close()
      Throws:
      IllegalArgumentException - if any argument is null | 任意参数为 null 时
      IllegalStateException - if either profile is closed | 任一配置文件已关闭时
      OpenImageCodecException - if lcms2 fails to build the transform | lcms2 构建失败时

    • apply

      public byte[] apply(byte[] input)
      Allocates a fresh output array and applies this transform to all pixels in input. 分配新输出数组并对 input 中所有像素应用本变换。
      Parameters:
      input - non-null buffer with length divisible by inputFormat().bytesPerPixel() | 长度可被 inputFormat().bytesPerPixel() 整除的非空缓冲
      Returns:
      new output buffer of length pixelCount * outputFormat.bytesPerPixel() | 长度为 pixelCount * outputFormat.bytesPerPixel() 的新缓冲
      Throws:
      IllegalArgumentException - if input is null or unaligned | 入参为 null 或未对齐时
      IllegalStateException - if this transform is closed | 已关闭时
      OpenImageCodecException - on native failure | native 失败时

    • apply

      public void apply(byte[] input, int inputOffset, byte[] output, int outputOffset, int pixelCount)
      Applies this transform to pixelCount pixels starting at the given offsets. 对从指定 offset 起的 pixelCount 个像素应用本变换。
      Parameters:
      input - non-null source buffer | 非空源缓冲
      inputOffset - byte offset into input (must be a multiple of input bytesPerPixel) | input 字节偏移（须为 输入 bytesPerPixel 的整数倍）
      output - non-null destination buffer | 非空目标缓冲
      outputOffset - byte offset into output (must be a multiple of output bytesPerPixel) | output 字节偏移
      pixelCount - number of pixels to transform; must be >= 0 | 待变换像素数；须 >= 0
      Throws:
      IllegalArgumentException - for any boundary violation | 任意边界违规时
      IllegalStateException - if this transform is closed | 已关闭时
      OpenImageCodecException - on native failure | native 失败时

    • inputFormat

      public PixelFormat inputFormat()
      Source pixel format. 源像素格式。
      Returns:
      non-null format | 非空格式

    • outputFormat

      public PixelFormat outputFormat()
      Destination pixel format. 目标像素格式。
      Returns:
      non-null format | 非空格式

    • close

      public void close()
      Closes this transform via cmsDeleteTransform. Idempotent. 通过 cmsDeleteTransform 关闭。幂等。
      Specified by:
      close in interface AutoCloseable