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 PixelRef to manage the native pixel memory.

  • Field Details

    • mInfo

      protected final @NonNull ImageInfo mInfo

    • mBase

      protected final @Nullable 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

      public @NonNull 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

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

    • getBase

      public @Nullable 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

      public @Nullable 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, @Size(2L) int @NonNull [] 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

      public void getColor4f(int x, int y, @Size(4L) float @NonNull [] 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, @Size(4L) float @NonNull [] 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(@Size(4L) float @NonNull [] 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