Package icyllis.arc3d.engine

# Class ResourceProvider

java.lang.Object
icyllis.arc3d.engine.ResourceProvider

Direct Known Subclasses:
  `GLResourceProvider`, `VulkanResourceProvider`

public abstract class ResourceProvider extends Object
Factory class used to obtain GPU resources with cache. A subclass can provide backend-specific resources.

This can only be used on render thread. To create Surface-like resources in other threads, use `SurfaceProxy`. To obtain Pipeline resources, use `SharedResourceCache`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Context`
  `mContext`
  `protected final Device`
  `mDevice`
  `protected final ResourceCache`
  `mResourceCache`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ResourceProvider(Device device, Context context, long maxResourceBudget)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `assignUniqueKeyToResource(IUniqueKey key, Resource resource)`
  `protected @SharedPtr GraphicsPipeline`
  `createGraphicsPipeline(PipelineDesc pipelineDesc, RenderPassDesc renderPassDesc)`
  `final @SharedPtr Image`
  `createImage(int width, int height, BackendFormat format, int sampleCount, int surfaceFlags, String label)`
  Deprecated.
  `final @SharedPtr Buffer`
  `createNewBuffer(long size, int usage)`
  `final @SharedPtr Image`
  `createNewImage(ImageDesc desc, boolean budgeted, String label)`
  Creates a new GPU image object and allocates its GPU memory.
  `final @SharedPtr GpuRenderTarget`
  `createRenderTarget(int width, int height, int sampleCount)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `createRenderTarget(int width, int height, BackendFormat colorFormat, int colorFlags, BackendFormat resolveFormat, int resolveFlags, BackendFormat depthStencilFormat, int depthStencilFlags, int sampleCount, int surfaceFlags, String label)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `createRenderTarget(int numColorTargets, Image[] colorTargets, Image[] resolveTargets, int[] mipLevels, Image depthStencilTarget, int surfaceFlags)`
  Deprecated.
  `protected abstract @SharedPtr Sampler`
  `createSampler(SamplerDesc desc)`
  `final @SharedPtr Image`
  `createTexture(int width, int height, BackendFormat format, int sampleCount, int surfaceFlags, String label)`
  Deprecated.
  `protected void`
  `destroy()`
  `final @SharedPtr Image`
  `findAndRefScratchImage(ImageDesc desc, boolean budgeted, String label)`
  Search the cache for a scratch texture matching the provided arguments.
  `final @SharedPtr Image`
  `findAndRefScratchImage(IResourceKey key, boolean budgeted, String label)`
  Search the cache for a scratch texture matching the provided arguments.
  `final @SharedPtr GpuRenderTarget`
  `findAndRefScratchRenderTarget(int width, int height, BackendFormat colorFormat, int colorFlags, BackendFormat resolveFormat, int resolveFlags, BackendFormat depthStencilFormat, int depthStencilFlags, int sampleCount, int surfaceFlags, String label)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `findAndRefScratchRenderTarget(IResourceKey key, String label)`
  Deprecated.
  `final @SharedPtr Buffer`
  `findOrCreateBuffer(long size, int usage, String label)`
  Returns a buffer.
  `final @SharedPtr Sampler`
  `findOrCreateCompatibleSampler(SamplerDesc desc)`
  Finds or creates a compatible `Sampler` based on the SamplerState.
  `@SharedPtr GraphicsPipeline`
  `findOrCreateGraphicsPipeline(PipelineDesc pipelineDesc, RenderPassDesc renderPassDesc)`
  `final @SharedPtr Image`
  `findOrCreateImage(ImageDesc desc, boolean budgeted, String label)`
  `void`
  `freeGpuResources()`
  Deallocates unlocked resources as much as possible.
  `ResourceCache`
  `getResourceCache()`
  `long`
  `getResourceCacheBudgetedBytes()`
  Returns the number of bytes consumed by budgeted resources.
  `long`
  `getResourceCacheLimit()`
  Returns the number of bytes that cached resources should count against.
  `long`
  `getResourceCachePurgeableBytes()`
  Returns the number of bytes held by unlocked resources which are available for cleanup.
  `protected abstract @SharedPtr Buffer`
  `onCreateNewBuffer(long size, int usage)`
  `protected abstract @SharedPtr Image`
  `onCreateNewImage(ImageDesc desc, boolean budgeted)`
  Overridden by backend-specific derived class to create objects.
  `void`
  `purgeResourcesNotUsedSince(long timeMillis)`
  Deallocates unlocked resources not used since the passed point in time.
  `final @SharedPtr GpuRenderTarget`
  `wrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `wrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)`
  Deprecated.
  `final @SharedPtr GpuRenderTarget`
  `wrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)`
  Deprecated.

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

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

- ## Field Details

  - ### mDevice

    protected final Device mDevice

  - ### mContext

    protected final Context mContext

  - ### mResourceCache

    protected final ResourceCache mResourceCache

- ## Constructor Details

  - ### ResourceProvider

    protected ResourceProvider(Device device, Context context, long maxResourceBudget)

- ## Method Details

  - ### destroy

    protected void destroy()

  - ### findOrCreateGraphicsPipeline

    @Nullable @SharedPtr public @SharedPtr GraphicsPipeline findOrCreateGraphicsPipeline(PipelineDesc pipelineDesc, RenderPassDesc renderPassDesc)

  - ### createGraphicsPipeline

    @SharedPtr protected @SharedPtr GraphicsPipeline createGraphicsPipeline(PipelineDesc pipelineDesc, RenderPassDesc renderPassDesc)

  - ### createImage

    @Deprecated @Nullable @SharedPtr public final @SharedPtr Image createImage(int width, int height, BackendFormat format, int sampleCount, int surfaceFlags, @Nullable String label)
    Deprecated.
    Finds or creates a texture that matches the descriptor. The texture's format will always match the request. The contents of the texture are undefined.

    When `ISurface.FLAG_BUDGETED` is set, the texture will count against the resource cache budget. If `ISurface.FLAG_APPROX_FIT` is also set, it's always budgeted.

    When `ISurface.FLAG_APPROX_FIT` is set, the method returns a potentially approx fit texture that approximately matches the descriptor. Will be at least as large in width and height as desc specifies. In this case, `ISurface.FLAG_MIPMAPPED` and `ISurface.FLAG_BUDGETED` are ignored. Otherwise, the method returns an exact fit texture.

    When `ISurface.FLAG_MIPMAPPED` is set, the texture will be allocated with mipmaps. If `ISurface.FLAG_APPROX_FIT` is also set, it always has no mipmaps.

    When `ISurface.FLAG_RENDERABLE` is set, the texture can be rendered to and can be used as attachments of a framebuffer. The `sampleCount` specifies the number of samples to use for rendering.

    When `ISurface.FLAG_PROTECTED` is set, the texture will be created as protected.

    Parameters:
      `width` - the desired width of the texture to be created
      `height` - the desired height of the texture to be created
      `format` - the backend format for the texture
      `sampleCount` - the number of samples to use for rendering if renderable is set, otherwise this must be 1
      `surfaceFlags` - the combination of the above flags
      `label` - the label for debugging purposes, can be empty to clear the label, or null to leave the label unchanged
    See Also:
      - `ISurface.FLAG_BUDGETED`
      - `ISurface.FLAG_APPROX_FIT`
      - `ISurface.FLAG_MIPMAPPED`
      - `ISurface.FLAG_SAMPLED_IMAGE`
      - `ISurface.FLAG_RENDERABLE`
      - `ISurface.FLAG_MEMORYLESS`
      - `ISurface.FLAG_PROTECTED`

  - ### findOrCreateImage

    @Nullable @SharedPtr public final @SharedPtr Image findOrCreateImage(ImageDesc desc, boolean budgeted, @Nullable String label)

  - ### createNewImage

    @Nullable @SharedPtr public final @SharedPtr Image createNewImage(ImageDesc desc, boolean budgeted, @Nullable String label)
    Creates a new GPU image object and allocates its GPU memory. In other words, the image data is dirty and needs to be uploaded later. If mipmapped, also allocates `(31 - CLZ(max(width,height)))` mipmaps in addition to the base level. NPoT (non-power-of-two) dimensions are always supported. Compressed format are supported.
    Returns:
      the image object if successful, otherwise nullptr
    See Also:
      - `ISurface.FLAG_BUDGETED`
      - `ISurface.FLAG_MIPMAPPED`
      - `ISurface.FLAG_RENDERABLE`
      - `ISurface.FLAG_PROTECTED`

  - ### onCreateNewImage

    @OverrideOnly @Nullable @SharedPtr protected abstract @SharedPtr Image onCreateNewImage(ImageDesc desc, boolean budgeted)
    Overridden by backend-specific derived class to create objects.

    Image size and format support will have already been validated in base class before onCreateImage is called.

  - ### findAndRefScratchImage

    @Nullable @SharedPtr public final @SharedPtr Image findAndRefScratchImage(IResourceKey key, boolean budgeted, @Nullable String label)
    Search the cache for a scratch texture matching the provided arguments. Failing that it returns null. If non-null, the resulting texture is always budgeted.
    Parameters:
      `label` - the label for debugging purposes, can be empty to clear the label, or null to leave the label unchanged

  - ### findAndRefScratchImage

    @Nullable @SharedPtr public final @SharedPtr Image findAndRefScratchImage(ImageDesc desc, boolean budgeted, @Nullable String label)
    Search the cache for a scratch texture matching the provided arguments. Failing that it returns null. If non-null, the resulting texture is always budgeted.
    Parameters:
      `label` - the label for debugging purposes, can be empty to clear the label, or null to leave the label unchanged
    See Also:
      - `ISurface.FLAG_MIPMAPPED`
      - `ISurface.FLAG_RENDERABLE`
      - `ISurface.FLAG_PROTECTED`

  - ### createTexture

    @Deprecated @Nullable @SharedPtr public final @SharedPtr Image createTexture(int width, int height, BackendFormat format, int sampleCount, int surfaceFlags, String label)
    Deprecated.
    Finds or creates a texture that matches the descriptor. The texture's format will always match the request. The contents of the texture are undefined.

    When `ISurface.FLAG_BUDGETED` is set, the texture will count against the resource cache budget. If `ISurface.FLAG_APPROX_FIT` is also set, it's always budgeted.

    When `ISurface.FLAG_APPROX_FIT` is set, the method returns a potentially approx fit texture that approximately matches the descriptor. Will be at least as large in width and height as desc specifies. In this case, `ISurface.FLAG_MIPMAPPED` and `ISurface.FLAG_BUDGETED` are ignored. Otherwise, the method returns an exact fit texture.

    When `ISurface.FLAG_MIPMAPPED` is set, the texture will be allocated with mipmaps. If `ISurface.FLAG_APPROX_FIT` is also set, it always has no mipmaps.

    When `ISurface.FLAG_RENDERABLE` is set, the texture can be rendered to and can be used as attachments of a framebuffer. The `sampleCount` specifies the number of samples to use for rendering.

    When `ISurface.FLAG_PROTECTED` is set, the texture will be created as protected.

    Parameters:
      `width` - the desired width of the texture to be created
      `height` - the desired height of the texture to be created
      `format` - the backend format for the texture
      `sampleCount` - the number of samples to use for rendering if renderable is set, otherwise this must be 1
      `surfaceFlags` - the combination of the above flags
      `label` - the label for debugging purposes, can be empty to clear the label, or null to leave the label unchanged
    See Also:
      - `ISurface.FLAG_BUDGETED`
      - `ISurface.FLAG_APPROX_FIT`
      - `ISurface.FLAG_MIPMAPPED`
      - `ISurface.FLAG_SAMPLED_IMAGE`
      - `ISurface.FLAG_RENDERABLE`
      - `ISurface.FLAG_MEMORYLESS`
      - `ISurface.FLAG_PROTECTED`

  - ### findOrCreateCompatibleSampler

    @Nullable @SharedPtr public final @SharedPtr Sampler findOrCreateCompatibleSampler(@Nonnull SamplerDesc desc)
    Finds or creates a compatible `Sampler` based on the SamplerState.
    Parameters:
      `desc` - see `SamplerDesc`
    Returns:
      the sampler object, or null if failed

  - ### createSampler

    @Nullable @SharedPtr protected abstract @SharedPtr Sampler createSampler(SamplerDesc desc)

  - ### createRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget createRenderTarget(int width, int height, @Nullable BackendFormat colorFormat, int colorFlags, @Nullable BackendFormat resolveFormat, int resolveFlags, @Nullable BackendFormat depthStencilFormat, int depthStencilFlags, int sampleCount, int surfaceFlags, @Nullable String label)
    Deprecated.
    Create a single color target, resolve target and optional depth/stencil target, then create the framebuffer for these targets.

    Search the cache for a combination of attachments and its `GpuRenderTarget` matching the provided arguments. If none, find or create one color target, resolve target, and optional depth/stencil target. Then creates a new `GpuRenderTarget` object for the combination of attachments.

    This method is responsible for canonicalization of surface flags.

    Parameters:
      `width` -
      `height` -
      `colorFormat` -
      `depthStencilFormat` -
      `surfaceFlags` -
      `label` -
    Returns:

  - ### createRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget createRenderTarget(int numColorTargets, @Nullable Image[] colorTargets, @Nullable Image[] resolveTargets, @Nullable int[] mipLevels, @Nullable Image depthStencilTarget, int surfaceFlags)
    Deprecated.
    Create a new `GpuRenderTarget` object for the given attachments (RTs and resolve targets). If and only if successful, this method transfers the ownership of all the given attachments.

    The colorTargets array may contain nullptr elements, meaning that draw buffer index is unused.

    Parameters:
      `numColorTargets` - the number of color targets
      `colorTargets` - array of color attachments
      `resolveTargets` - array of color resolve attachments
      `mipLevels` - array of which mip level will be used for color invalid input: '&' resolve attachments
      `depthStencilTarget` - optional depth/stencil attachment
      `surfaceFlags` - framebuffer flags
    Returns:
      a new RenderTarget

  - ### createRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget createRenderTarget(int width, int height, int sampleCount)
    Deprecated.

  - ### findAndRefScratchRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget findAndRefScratchRenderTarget(IResourceKey key, String label)
    Deprecated.

  - ### findAndRefScratchRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget findAndRefScratchRenderTarget(int width, int height, BackendFormat colorFormat, int colorFlags, BackendFormat resolveFormat, int resolveFlags, BackendFormat depthStencilFormat, int depthStencilFlags, int sampleCount, int surfaceFlags, String label)
    Deprecated.

  - ### wrapRenderableBackendTexture

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget wrapRenderableBackendTexture(BackendImage texture, int sampleCount, boolean ownership)
    Deprecated.
    This makes the backend texture be renderable. If `sampleCount` is > 1 and the underlying API uses separate MSAA render buffers then a MSAA render buffer is created that resolves to the texture.

    Ownership specifies rules for external GPU resources imported into Engine. If false, Engine will assume the client will keep the resource alive and Engine will not free it. If true, Engine will assume ownership of the resource and free it. If this method failed, then ownership doesn't work.

    Parameters:
      `texture` - the backend texture must be single sample
      `sampleCount` - the desired sample count
    Returns:
      a managed, non-recycled render target, or null if failed

  - ### wrapGLDefaultFramebuffer

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget wrapGLDefaultFramebuffer(int width, int height, int sampleCount, int depthBits, int stencilBits, BackendFormat format)
    Deprecated.
    Wraps OpenGL default framebuffer (FBO 0). Currently wrapped render targets always are not cacheable and not owned by returned object (you must free it manually, releasing RenderSurface doesn't release the backend framebuffer).
    Returns:
      RenderSurface object or null on failure.

  - ### wrapBackendRenderTarget

    @Deprecated @Nullable @SharedPtr public final @SharedPtr GpuRenderTarget wrapBackendRenderTarget(BackendRenderTarget backendRenderTarget)
    Deprecated.
    Wraps an existing render target with a RenderSurface object. It is similar to wrapBackendTexture but can be used to draw into surfaces that are not also textures (e.g. FBO 0 in OpenGL, or an MSAA buffer that the client will resolve to a texture). Currently wrapped render targets always are not cacheable and not owned by returned object (you must free it manually, releasing RenderSurface doesn't release the backend framebuffer).
    Returns:
      RenderSurface object or null on failure.

  - ### findOrCreateBuffer

    @Nullable @SharedPtr public final @SharedPtr Buffer findOrCreateBuffer(long size, int usage, String label)
    Returns a buffer.
    Parameters:
      `size` - minimum size of buffer to return.
      `usage` - hint to the graphics subsystem about what the buffer will be used for.
    Returns:
      the buffer if successful, otherwise nullptr.
    See Also:
      - `Engine.BufferUsageFlags`

  - ### createNewBuffer

    @Nullable @SharedPtr public final @SharedPtr Buffer createNewBuffer(long size, int usage)

  - ### onCreateNewBuffer

    @Nullable @SharedPtr protected abstract @SharedPtr Buffer onCreateNewBuffer(long size, int usage)

  - ### assignUniqueKeyToResource

    public final void assignUniqueKeyToResource(IUniqueKey key, Resource resource)

  - ### getResourceCacheLimit

    public long getResourceCacheLimit()
    Returns the number of bytes that cached resources should count against.

  - ### getResourceCacheBudgetedBytes

    public long getResourceCacheBudgetedBytes()
    Returns the number of bytes consumed by budgeted resources.

  - ### getResourceCachePurgeableBytes

    public long getResourceCachePurgeableBytes()
    Returns the number of bytes held by unlocked resources which are available for cleanup.

  - ### freeGpuResources

    public void freeGpuResources()
    Deallocates unlocked resources as much as possible. All purgeable resources will be deleted.

  - ### purgeResourcesNotUsedSince

    public void purgeResourcesNotUsedSince(long timeMillis)
    Deallocates unlocked resources not used since the passed point in time. The time-base is `System.currentTimeMillis()`. Otherwise, all purgeable resources older than `timeMillis` will be deleted.
    Parameters:
      `timeMillis` - the resources older than this time will be deleted

  - ### getResourceCache

    @VisibleForTesting public ResourceCache getResourceCache()