Package icyllis.modernui.graphics

# Class Image

java.lang.Object
icyllis.modernui.graphics.Image

All Implemented Interfaces:
  `AutoCloseable`

public class Image extends Object implements AutoCloseable
`Image` describes a two-dimensional array of pixels to sample from. The pixels may be located in CPU memory, in GPU memory as a GPU texture, or be lazily-generated.

- `Image` cannot be modified by CPU or GPU after it is created.
- `Image` width and height are greater than zero.
- `Image` may be created from `Bitmap`, Surface, Picture and GPU texture.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DENSITY_NONE`
  Indicates that the image was created for an unknown pixel density and will not be scaled.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Perform a deferred cleanup if the underlying resource is not released.
  `static Image`
  `create(String namespace, String entry)`
  Creates a new image object representing the target resource image.
  `static Image`
  `createTextureFromBitmap(RecordingContext recordingContext, Bitmap bitmap)`
  Create an image that backed by a GPU texture with the given bitmap.
  `static Image`
  `createTextureFromBitmap(Bitmap bitmap)`
  Create an image that backed by a GPU texture with the given bitmap.
  `ColorSpace`
  `getColorSpace()`
  Returns the color space associated with this image.
  `int`
  `getDensity()`
  Returns the density for this image.
  `int`
  `getHeight()`
  Returns the intrinsic height of this image.
  `ImageInfo`
  `getInfo()`
  Returns the `ImageInfo` describing the width, height, color type, alpha type and color space of this image.
  `int`
  `getScaledHeight(int targetDensity)`
  Convenience method that returns the height of this image divided by the density scale factor.
  `int`
  `getScaledWidth(int targetDensity)`
  Convenience method that returns the width of this image divided by the density scale factor.
  `int`
  `getWidth()`
  Returns the intrinsic width of this image.
  `boolean`
  `isClosed()`
  Returns true if this image has been closed.
  `void`
  `setDensity(int density)`
  Specifies the density for this image.

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

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

- ## Field Details

  - ### DENSITY_NONE

    public static final int DENSITY_NONE
    Indicates that the image was created for an unknown pixel density and will not be scaled.
    See Also:
      - `getDensity()`
      - `setDensity(int)`
      - Constant Field Values

- ## Method Details

  - ### createTextureFromBitmap

    @Nullable public static Image createTextureFromBitmap(Bitmap bitmap)
    Create an image that backed by a GPU texture with the given bitmap. Whether the bitmap is immutable or not, the bitmap can be safely closed after the call.

    Must be called after render system and UI system are initialized successfully, must be called from UI thread.

    This method may fail if:

    - Bitmap is null or closed
    - GPU device is lost (disconnected)
    - The width or height of the bitmap exceeds the maximum dimension supported by the GPU
    - The format of bitmap is not directly or indirectly supported by the GPU
    - Unable to allocate sufficient GPU-only memory for the GPU texture
    - Unable to allocate sufficient host memory for the staging buffer
    Parameters:
      `bitmap` - the source bitmap
    Returns:
      image, or null if failed
    Throws:
      `NullPointerException` - no GPU context
      `IllegalStateException` - not call from UI thread

  - ### createTextureFromBitmap

    @Experimental @Nullable public static Image createTextureFromBitmap(@NonNull RecordingContext recordingContext, @NonNull Bitmap bitmap)
    Create an image that backed by a GPU texture with the given bitmap. Whether the bitmap is immutable or not, the bitmap can be safely closed after the call.
    Parameters:
      `recordingContext` - the recording graphics context on the current thread
      `bitmap` - the source bitmap
    Returns:
      image, or null if failed
    Throws:
      `NullPointerException` - bitmap is null or released
      `IllegalStateException` - not call from context thread, or no context

  - ### create

    @Nullable public static Image create(@NonNull String namespace, @NonNull String entry)
    Creates a new image object representing the target resource image. You should use a single image as the UI texture to avoid each icon creating its own image. Underlying resources are automatically released.
    Parameters:
      `namespace` - the application namespace
      `entry` - the sub path to the resource
    Returns:
      the image

  - ### getInfo

    @Experimental @NonNull public ImageInfo getInfo()
    Returns the `ImageInfo` describing the width, height, color type, alpha type and color space of this image.
    Returns:
      image info

  - ### getWidth

    public int getWidth()
    Returns the intrinsic width of this image.
    Returns:
      image width in pixels

  - ### getHeight

    public int getHeight()
    Returns the intrinsic height of this image.
    Returns:
      image height in pixels

  - ### getScaledWidth

    public int getScaledWidth(int targetDensity)
    Convenience method that returns the width of this image divided by the density scale factor.

    Returns the image's width multiplied by the ratio of the target density to the image's source density

    Parameters:
      `targetDensity` - The density of the target canvas of the image.
    Returns:
      The scaled width of this image, according to the density scale factor.

  - ### getScaledHeight

    public int getScaledHeight(int targetDensity)
    Convenience method that returns the height of this image divided by the density scale factor.

    Returns the image's height multiplied by the ratio of the target density to the image's source density

    Parameters:
      `targetDensity` - The density of the target canvas of the image.
    Returns:
      The scaled height of this image, according to the density scale factor.

  - ### getDensity

    public int getDensity()

    Returns the density for this image.

    The default density is `DisplayMetrics.DENSITY_DEFAULT`..

    Returns:
      A scaling factor of the default density or `DENSITY_NONE` if the scaling factor is unknown.
    See Also:
      - `setDensity(int)`
      - `DisplayMetrics.DENSITY_DEFAULT`
      - `DisplayMetrics.densityDpi`
      - `DENSITY_NONE`

  - ### setDensity

    public void setDensity(int density)

    Specifies the density for this image. When the image is drawn to a `Canvas` or with a `ImageDrawable` that also has a density, it will be scaled appropriately.

    Parameters:
      `density` - The density scaling factor to use with this image or `DENSITY_NONE` if the density is unknown.
    See Also:
      - `getDensity()`
      - `DisplayMetrics.DENSITY_DEFAULT`
      - `DisplayMetrics.densityDpi`
      - `DENSITY_NONE`

  - ### getColorSpace

    @Nullable public ColorSpace getColorSpace()
    Returns the color space associated with this image. If the color space is unknown, this method returns null.

  - ### close

    public void close()
    Perform a deferred cleanup if the underlying resource is not released. Manually mark the underlying resources closed, if needed. After this, you will not be able to operate this object, and its GPU resource will be reclaimed as soon as possible after use.

    When this object becomes phantom-reachable, the system will automatically do this cleanup operation.

    Specified by:
      `close` in interface `AutoCloseable`

  - ### isClosed

    public boolean isClosed()
    Returns true if this image has been closed. If so, then it is an error to try to access it.
    Returns:
      true if the image has been closed