Package icyllis.arc3d.core

# Class Surface

java.lang.Object
icyllis.arc3d.core.RefCnt
icyllis.arc3d.core.Surface

All Implemented Interfaces:
  `RefCounted`

Direct Known Subclasses:
  `GraniteSurface`

public abstract class Surface extends RefCnt
Surface is responsible for managing the pixels that a canvas draws into. The pixels will be allocated on the GPU (a RenderTarget surface). Surface takes care of allocating a `Canvas` that will draw into the surface. Call `getCanvas()` to use that canvas (it is owned by the surface). Surface always has non-zero dimensions. If there is a request for a new surface, and either of the requested dimensions are zero, then null will be returned.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final int`
  `kDiscard_ContentChangeMode`
  `protected static final int`
  `kPreserve_ContentChangeMode`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Surface(int width, int height)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `deallocate()`
  Override this method to invoke de-allocation of the underlying resource.
  `final @RawPtr Canvas`
  `getCachedCanvas()`
  `final @RawPtr Image`
  `getCachedImage()`
  `final @RawPtr Canvas`
  `getCanvas()`
  Returns Canvas that draws into Surface.
  `final GenerationID`
  `getGenerationID()`
  Returns unique value identifying the content of Surface.
  `final int`
  `getHeight()`
  Returns pixel row count; may be zero or greater.
  `abstract ImageInfo`
  `getImageInfo()`
  Returns an ImageInfo describing the Surface.
  `final @RawPtr RecordingContext`
  `getRecordingContext()`
  Returns the recording context being used by the Surface.
  `final int`
  `getWidth()`
  Returns pixel count in each row; may be zero or greater.
  `final boolean`
  `hasCachedImage()`
  `static Surface`
  `makeFromBackendTexture(RecordingContext context, BackendImage backendImage, int origin, int sampleCount, int colorType, Runnable releaseCallback)`
  Wraps a GPU-backed texture into Surface.
  `final @SharedPtr Image`
  `makeImageSnapshot()`
  Returns Image capturing Surface contents.
  `final @SharedPtr Image`
  `makeImageSnapshot(Rect2ic subset)`
  Like the no-parameter version, this returns an image of the current surface contents.
  `static Surface`
  `makeRenderTarget(RecordingContext context, ImageInfo imageInfo, int origin, int sampleCount, boolean mipmapped, boolean budgeted)`
  Returns Surface on GPU indicated by context.
  `final void`
  `notifyWillChange()`
  Notifies that Surface contents will be changed externally.
  `protected abstract boolean`
  `onCopyOnWrite(int changeMode)`
  If the surface is about to change, we call this so that our subclass can optionally fork their backend (copy-on-write) in case it was being shared with the cachedImage.
  `protected void`
  `onDiscard()`
  Called as a performance hint when the Surface is allowed to make its contents undefined.
  `protected @RawPtr RecordingContext`
  `onGetRecordingContext()`
  `protected abstract @RawPtr Canvas`
  `onNewCanvas()`
  Allocate a canvas that will draw into this surface.
  `protected abstract @SharedPtr Image`
  `onNewImageSnapshot(Rect2ic subset)`
  Allocate an Image that represents the current contents of the surface.
  `protected void`
  `onRestoreBackingMutability()`
  Signal the surface to remind its backing store that it's mutable again.

  ### 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, toString, wait, wait, wait`

- ## Field Details

  - ### kPreserve_ContentChangeMode

    protected static final int kPreserve_ContentChangeMode
    See Also:
      - Constant Field Values

  - ### kDiscard_ContentChangeMode

    protected static final int kDiscard_ContentChangeMode
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### Surface

    protected Surface(int width, int height)

- ## Method Details

  - ### makeFromBackendTexture

    @Nullable public static Surface makeFromBackendTexture(RecordingContext context, BackendImage backendImage, int origin, int sampleCount, int colorType, Runnable releaseCallback)
    Wraps a GPU-backed texture into Surface. Caller must ensure the texture is valid for the lifetime of returned Surface. If `sampleCount` greater than one, creates an intermediate MSAA Surface which is used for drawing `backendTexture`.

    Surface is returned if all parameters are valid. `backendTexture` is valid if its pixel configuration agrees with `context`; for instance, if `backendTexture` has an sRGB configuration, then `context` must support sRGB. Further, `backendTexture` width and height must not exceed `context` capabilities, and the `context` must be able to support back-end textures.

    Upon success `releaseCallback` is called when it is safe to delete the texture in the backend API (accounting only for use of the texture by this surface). If Surface creation fails `releaseCallback` is called before this method returns.

    Parameters:
      `context` - GPU context
      `backendImage` - texture residing on GPU
      `sampleCount` - samples per pixel, or 1 to disable full scene anti-aliasing
      `releaseCallback` - function called when texture can be released, may be null
    Returns:
      Surface if all parameters are valid; otherwise, null

  - ### makeRenderTarget

    @Nullable public static Surface makeRenderTarget(RecordingContext context, ImageInfo imageInfo, int origin, int sampleCount, boolean mipmapped, boolean budgeted)
    Returns Surface on GPU indicated by context. Allocates memory for pixels, based on the width, height, and ColorType in ColorInfo. `budgeted` selects whether allocation for pixels is tracked by context. `imageInfo` describes the pixel format in ColorType, and transparency in AlphaType.

    `sampleCount` requests the number of samples per pixel. Pass one to disable multi-sample anti-aliasing. The request is rounded up to the next supported count, or rounded down if it is larger than the maximum supported count.

    `origin` pins either the top-left or the bottom-left corner to the origin.

    `mipmapped` hints that Image returned by makeImageSnapshot() has mipmaps.

    Parameters:
      `context` - GPU context
      `imageInfo` - width, height, ColorType, AlphaType; width, or height, or both, may be zero
      `sampleCount` - samples per pixel, or 1 to disable full scene anti-aliasing
      `mipmapped` - hint that Surface will host mipmap images
    Returns:
      Surface if all parameters are valid; otherwise, null

  - ### 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`

  - ### getWidth

    public final int getWidth()
    Returns pixel count in each row; may be zero or greater.
    Returns:
      number of pixel columns

  - ### getHeight

    public final int getHeight()
    Returns pixel row count; may be zero or greater.
    Returns:
      number of pixel rows

  - ### getImageInfo

    @Nonnull public abstract ImageInfo getImageInfo()
    Returns an ImageInfo describing the Surface.

  - ### getGenerationID

    public final GenerationID getGenerationID()
    Returns unique value identifying the content of Surface. Returned value changes each time the content changes. Content is changed by drawing, or by calling `notifyWillChange()`.
    Returns:
      unique content identifier

  - ### notifyWillChange

    public final void notifyWillChange()
    Notifies that Surface contents will be changed externally. Subsequent calls to `getGenerationID()` return a different value.

  - ### getRecordingContext

    @RawPtr public final @RawPtr RecordingContext getRecordingContext()
    Returns the recording context being used by the Surface.
    Returns:
      the recording context, if available; null otherwise

  - ### getCanvas

    @RawPtr public final @RawPtr Canvas getCanvas()
    Returns Canvas that draws into Surface. Subsequent calls return the same Canvas. Canvas returned is managed and owned by Surface, and is deleted when Surface is deleted.
    Returns:
      drawing Canvas for Surface

  - ### makeImageSnapshot

    @Nullable @SharedPtr public final @SharedPtr Image makeImageSnapshot()
    Returns Image capturing Surface contents. Subsequent drawing to Surface contents are not captured. Image allocation is accounted for if Surface was created with Budgeted flag.
    Returns:
      Image initialized with Surface contents

  - ### makeImageSnapshot

    @Nullable @SharedPtr public final @SharedPtr Image makeImageSnapshot(@Nonnull Rect2ic subset)
    Like the no-parameter version, this returns an image of the current surface contents. This variant takes a rectangle specifying the subset of the surface that is of interest. These bounds will be sanitized before being used.

    - If bounds extends beyond the surface, it will be trimmed to just the intersection of it and the surface.
    - If bounds does not intersect the surface, then this returns nullptr.
    - If bounds == the surface, then this is the same as calling the no-parameter variant.

  - ### getCachedCanvas

    @Internal @RawPtr public final @RawPtr Canvas getCachedCanvas()

  - ### getCachedImage

    @Internal @RawPtr public final @RawPtr Image getCachedImage()

  - ### hasCachedImage

    @Internal public final boolean hasCachedImage()

  - ### onGetRecordingContext

    @Internal @RawPtr protected @RawPtr RecordingContext onGetRecordingContext()

  - ### onNewCanvas

    @Internal @RawPtr protected abstract @RawPtr Canvas onNewCanvas()
    Allocate a canvas that will draw into this surface. We will cache this canvas, to return the same object to the caller multiple times. We take ownership, and will call unref() on the canvas when we go out of scope.

  - ### onNewImageSnapshot

    @Internal @Nullable @SharedPtr protected abstract @SharedPtr Image onNewImageSnapshot(@Nullable Rect2ic subset)
    Allocate an Image that represents the current contents of the surface. This needs to be able to outlive the surface itself (if need be), and must faithfully represent the current contents, even if the surface is changed after this called (e.g. it is drawn to via its canvas).

    If a subset is specified, the impl must make a copy, rather than try to wait on copy-on-write.

  - ### onDiscard

    @Internal protected void onDiscard()
    Called as a performance hint when the Surface is allowed to make its contents undefined.

  - ### onCopyOnWrite

    @Internal protected abstract boolean onCopyOnWrite(int changeMode)
    If the surface is about to change, we call this so that our subclass can optionally fork their backend (copy-on-write) in case it was being shared with the cachedImage.

    Returns false if the backing cannot be un-shared.

  - ### onRestoreBackingMutability

    @Internal protected void onRestoreBackingMutability()
    Signal the surface to remind its backing store that it's mutable again. Called only when we _didn't_ copy-on-write; we assume the copies start mutable.