Package icyllis.arc3d.engine

# Class ImageViewProxy

java.lang.Object
icyllis.arc3d.core.RefCnt
icyllis.arc3d.engine.ImageViewProxy

All Implemented Interfaces:
  `RefCounted`

public final class ImageViewProxy extends RefCnt
The `ImageViewProxy` implements the proxy pattern for `Image`, it targets an `Image` with three instantiation methods: deferred, lazy-callback and wrapped.

Deferred version takes an `ImageDesc`, and will be instantiated as needed automatically.

Lazy-callback version takes an `ImageDesc`, but will be instantiated via a user-defined callback. There is a special case where the extent of the image is uncertain before the callback is invoked. This is known as lazy-most, and the extent of `ImageDesc` can be arbitrary (1x1x1 by convention).

Wrapped version takes an existing `Image` without further instantiation.

Target: The backing GPU `Image` that referenced by this proxy.

Instantiate: Find or create GPU `Image` via `ResourceProvider` when they are actually required on flush.

BackingFit: Indicates whether a backing store needs to be an exact match or can be larger than is strictly necessary. True: Exact; False: Approx. See `ISurface.FLAG_APPROX_FIT`, the default is exact.

UseAllocator:

- False: This surface will be instantiated outside the allocator (e.g. for surfaces that are instantiated in on-flush callbacks).
- True: `SurfaceAllocator` should instantiate this surface.

Threading: Proxies may be created on the owner thread of a `Context`, and change the reference count through `RefCnt.ref()` and `RefCnt.unref()`. The proxy may be disposed on either the owner thread of its creating context, or the owner thread of its immediate context.

See Also:
  - `ImageProxyCache`

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ImageViewProxy.LazyCallbackResult`
  `static interface`
  `ImageViewProxy.LazyInstantiateCallback`
  Lazy-callback function.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clear()`
  De-instantiate.
  `void`
  `concatSwizzle(short swizzle)`
  `protected void`
  `deallocate()`
  Override this method to invoke de-allocation of the underlying resource.
  `boolean`
  `doLazyInstantiation(ResourceProvider resourceProvider)`
  `ImageDesc`
  `getDesc()`
  `int`
  `getHeight()`
  Returns the logical height of this surface.
  `Image`
  `getImage()`
  `String`
  `getLabel()`
  `long`
  `getMemorySize()`
  Retrieves the amount of GPU memory that will be or currently is used by this resource in bytes.
  `int`
  `getOrigin()`
  `int`
  `getSampleCount()`
  Returns the number of samples per pixel in color buffers (one if non-MSAA).
  `short`
  `getSwizzle()`
  `int`
  `getWidth()`
  Returns the logical width of this surface.
  `boolean`
  `instantiate(ResourceProvider resourceProvider)`
  Instantiates the backing store, if necessary.
  `boolean`
  `instantiateIfNonLazy(ResourceProvider resourceProvider)`
  `boolean`
  `isBackingWrapped()`
  Returns whether the backing store references the wrapped object.
  `boolean`
  `isBudgeted()`
  Does the resource count against the resource budget?
  `boolean`
  `isInstantiated()`
  Returns true if the backing store is instantiated.
  `boolean`
  `isLazy()`
  Returns true if the image proxy has a lazy callback.
  `boolean`
  `isLazyMost()`
  Returns true if the image proxy has a lazy callback, loose fit and dimension is not known.
  `boolean`
  `isMipmapped()`
  If we are instantiated and have a target, return the mip state of that target.
  `boolean`
  `isProtected()`
  `boolean`
  `isVolatile()`
  For Promise Images - should the Promise Image be fulfilled every time a Recording that references it is inserted into the Context.
  `static @SharedPtr ImageViewProxy`
  `make(Context context, int imageType, int colorType, int width, int height, int depthOrArraySize, int imageFlags, int origin, short swizzle)`
  `static @SharedPtr ImageViewProxy`
  `make(Context context, ImageDesc desc, int origin, short swizzle, boolean budgeted, String label)`
  `static @SharedPtr ImageViewProxy`
  `makeLazy(ImageDesc desc, int origin, short swizzle, boolean budgeted, boolean isVolatile, boolean lazyDimensions, ImageViewProxy.LazyInstantiateCallback callback)`
  `@SharedPtr Image`
  `refImage()`
  `void`
  `setSwizzle(short swizzle)`
  Replace the view's swizzle.
  `String`
  `toString()`
  `static @SharedPtr ImageViewProxy`
  `wrap(@SharedPtr Image image, int origin, short swizzle)`

  ### Methods inherited from class icyllis.arc3d.core.RefCnt

  `create, create, getRefCnt, getRefCntAcquire, getRefCntVolatile, move, move, ref, unique, unref`

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

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

- ## Method Details

  - ### make

    @Nullable @SharedPtr public static @SharedPtr ImageViewProxy make(@Nonnull Context context, @Nullable ImageDesc desc, int origin, short swizzle, boolean budgeted, @Nullable String label)

  - ### make

    @Nullable @SharedPtr public static @SharedPtr ImageViewProxy make(@Nonnull Context context, int imageType, int colorType, int width, int height, int depthOrArraySize, int imageFlags, int origin, short swizzle)

  - ### makeLazy

    @SharedPtr public static @SharedPtr ImageViewProxy makeLazy(@Nonnull ImageDesc desc, int origin, short swizzle, boolean budgeted, boolean isVolatile, boolean lazyDimensions, @Nonnull ImageViewProxy.LazyInstantiateCallback callback)

  - ### wrap

    @SharedPtr public static @SharedPtr ImageViewProxy wrap(@SharedPtr @SharedPtr Image image, int origin, short swizzle)

  - ### deallocate

    protected void deallocate()
    Description copied from class: `RefCnt`
    Override this method to invoke de-allocation of the underlying resource.
    Specified by:
      `deallocate` in class `RefCnt`

  - ### isLazy

    public boolean isLazy()
    Returns true if the image proxy has a lazy callback.

  - ### isLazyMost

    public boolean isLazyMost()
    Returns true if the image proxy has a lazy callback, loose fit and dimension is not known.

  - ### getWidth

    public int getWidth()
    Returns the logical width of this surface. The result is undefined if `isLazyMost()` returns true.
    Returns:
      the desired width of the surface

  - ### getHeight

    public int getHeight()
    Returns the logical height of this surface. The result is undefined if `isLazyMost()` returns true.
    Returns:
      the desired height of the surface

  - ### getOrigin

    public int getOrigin()
    See Also:
      - `Engine.SurfaceOrigin`

  - ### getSwizzle

    public short getSwizzle()
    See Also:
      - `Swizzle`

  - ### concatSwizzle

    public void concatSwizzle(short swizzle)

  - ### setSwizzle

    public void setSwizzle(short swizzle)
    Replace the view's swizzle.

  - ### isVolatile

    public boolean isVolatile()
    For Promise Images - should the Promise Image be fulfilled every time a Recording that references it is inserted into the Context. True: fulfilled on every insertion call, otherwise only fulfilled once.

  - ### getSampleCount

    public int getSampleCount()
    Returns the number of samples per pixel in color buffers (one if non-MSAA). If this surface it non-renderable, this method always returns one.
    Returns:
      the number of samples, greater than (multisample) or equal to one

  - ### getDesc

    @Nonnull public ImageDesc getDesc()

  - ### isInstantiated

    public boolean isInstantiated()
    Returns true if the backing store is instantiated.

  - ### instantiate

    public boolean instantiate(ResourceProvider resourceProvider)
    Instantiates the backing store, if necessary.
    Parameters:
      `resourceProvider` - the resource provider to create textures
    Returns:
      success or not

  - ### instantiateIfNonLazy

    public boolean instantiateIfNonLazy(ResourceProvider resourceProvider)

  - ### doLazyInstantiation

    public boolean doLazyInstantiation(ResourceProvider resourceProvider)

  - ### clear

    public void clear()
    De-instantiate. Called after instantiated.

  - ### isBudgeted

    public boolean isBudgeted()
    Does the resource count against the resource budget?

    Always true for lazy-callback resources; set from the backing resource for wrapped resources; only meaningful if 'mLazyInstantiateCallback' is non-null.

  - ### isProtected

    public boolean isProtected()

  - ### getMemorySize

    public long getMemorySize()
    Retrieves the amount of GPU memory that will be or currently is used by this resource in bytes. It is approximate since we aren't aware of additional padding or copies made by the driver.
    Returns:
      the amount of GPU memory used in bytes

  - ### isBackingWrapped

    public boolean isBackingWrapped()
    Returns whether the backing store references the wrapped object. Always false if not instantiated.

  - ### getImage

    public Image getImage()

  - ### refImage

    @SharedPtr public @SharedPtr Image refImage()

  - ### isMipmapped

    public boolean isMipmapped()
    If we are instantiated and have a target, return the mip state of that target. Otherwise, returns the proxy's mip state from creation time. This is useful for lazy proxies which may claim to not need mips at creation time, but the instantiation happens to give us a mipmapped target. In that case we should use that for our benefit to avoid possible copies/mip generation later.

  - ### getLabel

    public String getLabel()

  - ### toString

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