Package icyllis.arc3d.sketch

Class Surface

java.lang.Object
icyllis.arc3d.core.RefCnt
icyllis.arc3d.sketch.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 Details

    • kPreserve_ContentChangeMode

      protected static final int kPreserve_ContentChangeMode
      See Also:

    • kDiscard_ContentChangeMode

      protected static final int kDiscard_ContentChangeMode
      See Also:

  • Constructor Details

    • Surface

      protected Surface(int width, int height)

  • Method Details

    • makeFromBackendTexture

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

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

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

    • getGenerationID

      public final Object 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.

    • getCommandContext

      @RawPtr public final @RawPtr Context getCommandContext()
      Returns the GPU context being used by the Surface.
      Returns:
      the GPU 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

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

      @SharedPtr public final @Nullable @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()

    • onGetCommandContext

      @Internal @RawPtr protected @RawPtr Context onGetCommandContext()

    • 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 @SharedPtr protected abstract @Nullable @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.