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 GlobalResourceCache.

  • 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

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

    • createGraphicsPipeline

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

    • createImage

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

    • findOrCreateImage

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

    • createNewImage

      @SharedPtr public final @Nullable @SharedPtr Image createNewImage(ImageDesc desc, @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:

    • onCreateNewImage

      @OverrideOnly @SharedPtr protected abstract @Nullable @SharedPtr Image onCreateNewImage(ImageDesc desc)
      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

      @SharedPtr public final @Nullable @SharedPtr Image findAndRefScratchImage(IResourceKey key, boolean budgeted, boolean shareable, @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

      @SharedPtr public final @Nullable @SharedPtr Image findAndRefScratchImage(ImageDesc desc, boolean budgeted, boolean shareable, @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:

    • createTexture

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

    • findOrCreateCompatibleSampler

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

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

    • createRenderTarget

      @Deprecated @SharedPtr public final @Nullable @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 @SharedPtr public final @Nullable @SharedPtr GpuRenderTarget createRenderTarget(int numColorTargets, Image @Nullable [] colorTargets, Image @Nullable [] resolveTargets, int @Nullable [] 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 @SharedPtr public final @Nullable @SharedPtr GpuRenderTarget createRenderTarget(int width, int height, int sampleCount)
      Deprecated.

    • findAndRefScratchRenderTarget

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

    • findAndRefScratchRenderTarget

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

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

    • createNewBuffer

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

    • onCreateNewBuffer

      @SharedPtr protected abstract @Nullable @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()