Package icyllis.arc3d.engine

# Class Image

java.lang.Object
icyllis.arc3d.engine.Resource
icyllis.arc3d.engine.Image

All Implemented Interfaces:
  `RefCounted`

Direct Known Subclasses:
  `GLImage`, `VulkanImage`

public abstract class Image extends Resource
Represents GPU image resources, which may be 2D or 3D. This class also represents a default image view, see `Engine.ImageType`.

`Image` can be used for various purposes. It may be used as textures (sampled in fragment shaders), may be used as storage images (load and store in compute shaders), may be used as color and depth/stencil attachments of framebuffers (render targets). See `ISurface.FLAG_SAMPLED_IMAGE`, `ISurface.FLAG_STORAGE_IMAGE` and `ISurface.FLAG_RENDERABLE`.

An `Image` is created with device-local memory, its contents may be updated via a staging buffer.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static final class`
  `Image.ResourceKey`
  Storage key of `Image`, may be compared with `ImageViewProxy`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected int`
  `mFlags`
  Note: budgeted is a dynamic state, it can be returned by `getSurfaceFlags()`.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Image(Context context, boolean budgeted, boolean wrapped, ImageDesc desc, ImageMutableState mutableState)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final int`
  `getArraySize()`
  `final int`
  `getDepth()`
  `int`
  `getDepthBits()`
  `final ImageDesc`
  `getDesc()`
  `final int`
  `getHeight()`
  `final int`
  `getImageType()`
  Returns the default image view type.
  `final int`
  `getMipLevelCount()`
  `final ImageMutableState`
  `getMutableState()`
  `final int`
  `getSampleCount()`
  Returns the number of samples per pixel.
  `int`
  `getStencilBits()`
  `final int`
  `getWidth()`
  `final boolean`
  `isMipmapped()`
  `final boolean`
  `isMipmapsDirty()`
  Return `true` if mipmaps are dirty and need to regenerate before sampling.
  `final boolean`
  `isProtected()`
  `final boolean`
  `isReadOnly()`
  The pixel values of this surface cannot be modified (e.g.
  `final boolean`
  `isRenderable()`
  `final boolean`
  `isSampledImage()`
  `final boolean`
  `isStorageImage()`
  `protected void`
  `onRelease()`
  Subclass should override this method to free GPU resources in the backend API.
  `final void`
  `setMipmapsDirty(boolean mipmapsDirty)`
  Set whether mipmaps are dirty or not.
  `void`
  `setReleaseCallback(@SharedPtr ReleaseCallback callback)`
  Unmanaged backends (e.g.

  ### Methods inherited from class icyllis.arc3d.engine.Resource

  `getContext, getDevice, getKey, getLabel, getMemorySize, getUniqueID, hasAnyRefs, hasCacheRef, hasCommandBufferRef, hasUsageRef, isBudgeted, isDestroyed, isPurgeable, isWrapped, onSetLabel, ref, refCommandBuffer, setKey, setLabel, setNonCacheable, unref, unrefCommandBuffer`

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

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

- ## Field Details

  - ### mFlags

    protected int mFlags
    Note: budgeted is a dynamic state, it can be returned by `getSurfaceFlags()`. This field is OR-ed only and immutable when created.

- ## Constructor Details

  - ### Image

    protected Image(Context context, boolean budgeted, boolean wrapped, ImageDesc desc, ImageMutableState mutableState)

- ## Method Details

  - ### getDesc

    @Nonnull public final ImageDesc getDesc()

  - ### getMutableState

    public final ImageMutableState getMutableState()

  - ### getImageType

    public final int getImageType()
    Returns the default image view type.
    Returns:
      see `Engine.ImageType`

  - ### getWidth

    public final int getWidth()
    Returns:
      the width of the image in texels, greater than zero

  - ### getHeight

    public final int getHeight()
    Returns:
      the height of the image in texels, greater than zero

  - ### getDepth

    public final int getDepth()
    Returns:
      the depth of the image in texels, greater than zero

  - ### getArraySize

    public final int getArraySize()

  - ### getDepthBits

    public int getDepthBits()

  - ### getStencilBits

    public int getStencilBits()

  - ### isMipmapped

    public final boolean isMipmapped()
    Returns:
      true if this image has mipmaps and have been allocated

  - ### isSampledImage

    public final boolean isSampledImage()
    Returns:
      true if this image can be used as textures

  - ### isStorageImage

    public final boolean isStorageImage()
    Returns:
      true if this image can be used as storage images.

  - ### isRenderable

    public final boolean isRenderable()
    Returns:
      true if this image can be used as color and depth/stencil attachments

  - ### getMipLevelCount

    public final int getMipLevelCount()
    Returns:
      number of mipmap levels, greater than 1 if mipmapped

  - ### getSampleCount

    public final int getSampleCount()
    Returns the number of samples per pixel.
    Returns:
      the number of samples, greater than (multi-sampled) or equal to one

  - ### isReadOnly

    public final boolean isReadOnly()
    The pixel values of this surface cannot be modified (e.g. doesn't support write pixels or mipmap regeneration). To be exact, only wrapped textures, external textures, stencil attachments and MSAA color attachments can be read only.
    Returns:
      true if pixels in this surface are read-only

  - ### isProtected

    public final boolean isProtected()
    Returns:
      true if we are working with protected content

  - ### isMipmapsDirty

    public final boolean isMipmapsDirty()
    Return `true` if mipmaps are dirty and need to regenerate before sampling. The value is valid only when `isMipmapped()` returns `true`.
    Returns:
      whether mipmaps are dirty

  - ### setMipmapsDirty

    public final void setMipmapsDirty(boolean mipmapsDirty)
    Set whether mipmaps are dirty or not. Call only when `isMipmapped()` returns `true`.
    Parameters:
      `mipmapsDirty` - whether mipmaps are dirty

  - ### setReleaseCallback

    public void setReleaseCallback(@SharedPtr @SharedPtr ReleaseCallback callback)
    Unmanaged backends (e.g. Vulkan) may want to specially handle the release proc in order to ensure it isn't called until GPU work related to the resource is completed.

  - ### onRelease

    protected void onRelease()
    Description copied from class: `Resource`
    Subclass should override this method to free GPU resources in the backend API.
    Specified by:
      `onRelease` in class `Resource`