Package icyllis.arc3d.core

# Class Pixmap

java.lang.Object
icyllis.arc3d.core.Pixmap

public class Pixmap extends Object
Immutable structure that pairs ImageInfo with pixels and row bytes.

This class does not try to manage the lifetime of pixels, unless it's backed by a heap array, use `Pixels` to manage the native pixel memory.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final long`
  `mAddress`
  `protected final Object`
  `mBase`
  `protected final ImageInfo`
  `mInfo`
  `protected final int`
  `mRowBytes`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Pixmap(ImageInfo newInfo, Pixmap oldPixmap)`
  Reinterprets an existing `Pixmap` with newInfo.
  `Pixmap(ImageInfo info, Object base, long address, int rowBytes)`
  Creates `Pixmap` from info width, height, AlphaType, ColorType and ColorSpace.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `clear(float[] color, Rect2ic subset)`
  Writes color to pixels bounded by subset; returns true on success.
  `long`
  `getAddress()`
  The address if native buffer, the base address corresponding to the pixel origin, or array base offset; may be NULL.
  `long`
  `getAddress(int x, int y)`
  Returns address/offset at (x, y).
  `int`
  `getAlphaType()`
  `Object`
  `getBase()`
  The array if heap buffer; may be null.
  `int`
  `getColor(int x, int y)`
  Gets the pixel value at (x, y), and converts it to `ColorInfo.CT_BGRA_8888_NATIVE`, `ColorInfo.AT_UNPREMUL`, and `ColorSpace.Named.SRGB`.
  `void`
  `getColor4f(int x, int y, float[] dst)`
  Gets the pixel at (x, y), and converts it to `ColorInfo.CT_RGBA_F32`.
  `ColorSpace`
  `getColorSpace()`
  Returns ColorSpace, the range of colors, associated with ImageInfo.
  `int`
  `getColorType()`
  `int`
  `getHeight()`
  Returns pixel row count.
  `ImageInfo`
  `getInfo()`
  Returns width, height, AlphaType, ColorType, and ColorSpace.
  `void`
  `getPixelOrigin(long pix, int[] origin)`
  Returns origin of pixels within Pixels pix.
  `int`
  `getRowBytes()`
  The size, in bytes, between the start of one pixel row/scanline and the next in buffer, including any unused padding between them.
  `int`
  `getWidth()`
  Returns pixel count in each pixel row.
  `Pixmap`
  `makeSubset(Rect2ic subset)`
  Make a pixmap width, height, pixel address to intersection of this with subset, if intersection is not empty; and return the new pixmap.
  `boolean`
  `readPixels(Pixmap dst, int srcX, int srcY)`
  Copies a Rect of pixels to dst.
  `void`
  `setColor4f(int x, int y, float[] src)`
  Sets the pixel at (x, y), from `ColorInfo.CT_RGBA_F32` to `getColorType()`.
  `String`
  `toString()`
  `boolean`
  `writePixels(Pixmap src, int dstX, int dstY)`
  Copies a Rect of pixels from src.

  ### Methods inherited from class java.lang.Object

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

- ## Field Details

  - ### mInfo

    @Nonnull protected final ImageInfo mInfo

  - ### mBase

    @Nullable protected final Object mBase

  - ### mAddress

    protected final long mAddress

  - ### mRowBytes

    protected final int mRowBytes

- ## Constructor Details

  - ### Pixmap

    public Pixmap(@Nonnull ImageInfo info, @Nullable Object base, long address, int rowBytes)
    Creates `Pixmap` from info width, height, AlphaType, ColorType and ColorSpace. rowBytes should be info.width() times info.bytesPerPixel(), or larger.

    No parameter checking is performed; it is up to the caller to ensure that address and rowBytes agree with info.

    The memory lifetime of pixels is managed by the caller.

    Parameters:
      `info` - width, height, AlphaType, ColorType and ColorSpace
      `base` - array if heap buffer; may be null
      `address` - address if native buffer, or array base offset; may be NULL
      `rowBytes` - size of one row of buffer; width times bpp, or larger

  - ### Pixmap

    public Pixmap(@Nonnull ImageInfo newInfo, @Nonnull Pixmap oldPixmap)
    Reinterprets an existing `Pixmap` with newInfo.

- ## Method Details

  - ### getInfo

    @Nonnull public ImageInfo getInfo()
    Returns width, height, AlphaType, ColorType, and ColorSpace.

  - ### getWidth

    public int getWidth()
    Returns pixel count in each pixel row. Should be equal or less than: rowBytes() / info().bytesPerPixel().
    Returns:
      pixel width in ImageInfo

  - ### getHeight

    public int getHeight()
    Returns pixel row count.
    Returns:
      pixel height in ImageInfo

  - ### getColorType

    public int getColorType()

  - ### getAlphaType

    public int getAlphaType()

  - ### getColorSpace

    @Nullable public ColorSpace getColorSpace()
    Returns ColorSpace, the range of colors, associated with ImageInfo.

  - ### getBase

    @Nullable public Object getBase()
    The array if heap buffer; may be null.

  - ### getAddress

    public long getAddress()
    The address if native buffer, the base address corresponding to the pixel origin, or array base offset; may be NULL. See `Unsafe`.

  - ### getRowBytes

    public int getRowBytes()
    The size, in bytes, between the start of one pixel row/scanline and the next in buffer, including any unused padding between them. This value must be at least the width multiplied by the bytes-per-pixel, where the bytes-per-pixel depends on the color type.

    Returns zero if colorType() is unknown. It is up to the caller to ensure that row bytes is a useful value.

  - ### getAddress

    public long getAddress(int x, int y)
    Returns address/offset at (x, y). Returns NULL if `getAddress()` is NULL.

    Input is not validated, and return value is undefined if ColorType is unknown.

    Parameters:
      `x` - column index, zero or greater, and less than width()
      `y` - row index, zero or greater, and less than height()
    Returns:
      readable generic pointer/offset to pixel

  - ### makeSubset

    @Nullable public Pixmap makeSubset(@Nonnull Rect2ic subset)
    Make a pixmap width, height, pixel address to intersection of this with subset, if intersection is not empty; and return the new pixmap. Otherwise, return null.
    Parameters:
      `subset` - bounds to intersect with SkPixmap
    Returns:
      a pixmap if intersection of this and subset is not empty

  - ### getPixelOrigin

    public void getPixelOrigin(long pix, @Nonnull @Size(2L) int[] origin)
    Returns origin of pixels within Pixels pix. Pixmap bounds is always contained by Pixels bounds, which may be the same size or larger. Multiple Pixmap can share the same Pixels instance, where each Pixmap has different bounds.

    The returned origin added to Pixmap dimensions equals or is smaller than the Pixels dimensions.

    Returns (0, 0) if pixels is NULL.

  - ### getColor

    @ColorInt public int getColor(int x, int y)
    Gets the pixel value at (x, y), and converts it to `ColorInfo.CT_BGRA_8888_NATIVE`, `ColorInfo.AT_UNPREMUL`, and `ColorSpace.Named.SRGB`.

    Input is not validated: out of bounds values of x or y trigger an assertion error; and returns undefined values or may crash. Fails if color type is unknown or pixel data is NULL.

    If the max bits per channel for the color type is greater than 8, or colors are premultiplied, then color precision may be lost in the conversion. Otherwise, precision will not be lost. If the color space is not sRGB, then this method will perform color space transformation, which can be slow.

    Parameters:
      `x` - column index, zero or greater, and less than width()
      `y` - row index, zero or greater, and less than height()
    Returns:
      pixel converted to unpremultiplied color
    See Also:
      - `getColor4f(int, int, float[])`

  - ### getColor4f

    public void getColor4f(int x, int y, @Nonnull @Size(4L) float[] dst)
    Gets the pixel at (x, y), and converts it to `ColorInfo.CT_RGBA_F32`. This method will not perform alpha type or color space transformation, the resulting color has `getAlphaType()` and is in `getColorSpace()`.

    Input is not validated: out of bounds values of x or y trigger an assertion error; and returns undefined values or may crash. Fails if color type is unknown or pixel data is NULL.

    Parameters:
      `x` - column index, zero or greater, and less than width()
      `y` - row index, zero or greater, and less than height()
      `dst` - pixel converted to float color

  - ### setColor4f

    public void setColor4f(int x, int y, @Nonnull @Size(4L) float[] src)
    Sets the pixel at (x, y), from `ColorInfo.CT_RGBA_F32` to `getColorType()`. This method will not perform alpha type or color space transformation, the given color should have `getAlphaType()` and be in `getColorSpace()`.

    Input is not validated: out of bounds values of x or y trigger an assertion error; and returns undefined values or may crash. Fails if color type is unknown or pixel data is NULL.

    Parameters:
      `x` - column index, zero or greater, and less than width()
      `y` - row index, zero or greater, and less than height()
      `src` - float color to set

  - ### readPixels

    public boolean readPixels(@Nonnull Pixmap dst, int srcX, int srcY)
    Copies a Rect of pixels to dst. Copy starts at (srcX, srcY), and does not exceed Pixmap (width(), height()). dst specifies width, height, ColorType, AlphaType, and ColorSpace of destination. Returns true if pixels are copied. Returns false if dst address equals nullptr, or dst.rowBytes() is less than dst ImageInfo::minRowBytes.

    Pixels are copied only if pixel conversion is possible. Returns false if pixel conversion is not possible.

    srcX and srcY may be negative to copy only top or left of source. Returns false pixmap width() or height() is zero or negative. Returns false if: srcX >= pixmap width(), or if srcY >= pixmap height().

    Parameters:
      `dst` - ImageInfo and pixel address to write to
      `srcX` - column index whose absolute value is less than width()
      `srcY` - row index whose absolute value is less than height()
    Returns:
      true if pixels are copied to dst

  - ### writePixels

    public boolean writePixels(@Nonnull Pixmap src, int dstX, int dstY)
    Copies a Rect of pixels from src. Copy starts at (dstX, dstY), and does not exceed (src.width(), src.height()).

    src specifies width, height, ColorType, AlphaType, ColorSpace, pixel storage, and row bytes of source. src.rowBytes() specifics the gap from one source row to the next. Returns true if pixels are copied. Returns false if: - src pixel storage equals nullptr - src.rowBytes is less than ImageInfo::minRowBytes()

    Pixels are copied only if pixel conversion is possible. Returns false if pixel conversion is not possible.

    dstX and dstY may be negative to copy only top or left of source. Returns false if width() or height() is zero or negative. Returns false if dstX >= pixmap width(), or if dstY >= pixmap height().

    Parameters:
      `src` - source Pixmap: ImageInfo, pixels, row bytes
      `dstX` - column index whose absolute value is less than width()
      `dstY` - row index whose absolute value is less than height()
    Returns:
      true if src pixels are copied to pixmap

  - ### clear

    public boolean clear(@Nonnull @Size(4L) float[] color, @Nullable Rect2ic subset)
    Writes color to pixels bounded by subset; returns true on success. if subset is null, writes colors pixels inside bounds(). Returns false if `getColorType()` is unknown, if subset is not null and does not intersect bounds(), or if subset is null and bounds() is empty.

    This method will not perform alpha type or color space transformation, the given color should have `getAlphaType()` and be in `getColorSpace()`.

    Parameters:
      `color` - float color to write
      `subset` - bounding box of pixels to write; may be null
    Returns:
      true if pixels are changed

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`