IResourceCache

Description

interface Tinman.Engine.Rendering.IResourceCache

Derived from

IDisposable

Extended by

ResourceCache sealed

A cache for GPU resources.

GPU resources are referenced via IResourceHandle objects, from which GPU resource objects (see IResource) can be created using the following methods:

  • GetNull
    Optional GPU resources; these resources are created on-demand and are fed into the graphics API by the calling code. Usually, the calling code does not keep references to these resources. Ownership is held by the resource cache.

  • OwnNull
    Mandatory GPU resources that will be shared between all callers for a graphics context; these resources are created once and then kept by the calling code. Ownership is held by the calling code.

These method may be called repeatedly in arbitrary order for the same resource handle.

Public / Methods

Dispose​All

public method DisposeAll → ()

Disposes all resource objects that are owned by this resource cache and removes their resource handle mappings from the cache.

When this method is called, all cached resources that have been obtained via GetNull will be disposed.

Cached resources that have been obtained via OwnNull will remain in the cache.

Error

public method Error → (1)

handle in : IResourceHandle

The resource handle that has been passed to GetNull resp. OwnNull.

returns → TinmanError

The exception that has happened or null if handle in is still being loaded in the background, if handle in has been loaded successfully or if handle in is not present in the resource cache.

Returns the exception that has happened while loading the given resource object.

Evict

public method Evict → (1)

handle in : IResourceHandle

The resource handle or null.

Evicts a cached resource object.

After this method has been called, the next call to GetNull or OwnNull passing handle in will create a new resource object. The evicted resource is not necessarily disposed immediately, because this depends on the actual disposal strategy of the implementing class.

Find​Null

public method FindNull → (1)

handle in : IResourceHandle

The resource handle or null.

returns → IResource

The cached resource object or null if handle in is null or if there is no existing object in the cache.

Returns an existing object in the resource cache.

The IResourceHandle.CreateResource will never be called when this method is used, only existing resource objects will be returned.

Get​Null

public method GetNull → (2)

handle in : IResourceHandle

The resource handle or null. If handle in is not null and does not implement the IPreloadingResourceHandle interface or IPreloadingResourceHandle.CanPreloadResource returns false, the preload opt parameter is ignored and this method behaves as if it were null.

preload opt : IResourceHandle = null

If null, the calling thread will be blocked until the handle in resource has been loaded. Otherwise, the handle in resource is preloaded in the background (if not null) and the cached resource object of preload opt is returned instead.

returns → IResource

The cached resource object or null if both handle in and preload opt are null or if IResourceHandle.CreateResource has thrown an exception (see Error).

Returns a cached resource object.

The returned resource object will be disposed automatically. Implementing classes may choose any kind of disposal strategy, as long as it adheres to the following requirements:

  • The resource object will be disposed at the latest when the resource cache is disposed.

  • The resource object will be disposed at the earliest when one of the following occurs:

Immediately passing a resource obtained via GetNull to the graphics API is always valid, as the resource disposal rules (see IResource) ensure that resource disposal will not produce undefined results while the resource is bound or being used by in-flight GPU commands.

The calling code should not keep references to resource objects returned by GetNull, unless it is aware of the fact that resource disposal may happen at any time while holding the reference. If this is not feasible, consider using OwnNull instead.

Own​Null

[OwnerReturn]
public method OwnNull → (1)

handle in : IResourceHandle

The resource handle or null.

returns → IResource

The cached resource object or null if handle in is null or if IResourceHandle.CreateResource has thrown an exception (see Error).

Returns a cached resource object.

The returned resource object will remain in the resource cache until it is destroyed as soon as all ownership references have been disposed. Subsequent calls to OwnNull passing the same handle in will return the same IResource object, unless Evict is called for handle in.

Public / Attributes

Cache​Memory

public attribute CacheMemory → (get)

value : int32

[>=0]
The maximum video memory amount, in MB.

The maximum amount of video memory to use for caching resource objects.

Cache​Memory​Utilization

public attribute CacheMemoryUtilization → (get)

value : int32

[>=0]
The cached video memory amount, in MB.

The memory amount of cached resource objects.

Extensions

Find

public static method Find → (1)

handle in : IResourceHandle

The resource handle or null.

returns → IResource

The cached resource object.

Returns an existing object in the resource cache.

This method delegates to IResourceCache.FindNull.

RenderException

If the resulting resource object would be null.

See also

IResourceCache.FindNull

Get

public static method Get → (2)

handle in : IResourceHandle

The resource handle.

preload opt : IResourceHandle = null

The preloading handle.

returns → IResource

The cached resource object.

Returns a cached resource object.

This method delegates to IResourceCache.GetNull.

RenderException

If the resulting resource object would be null.

See also

IResourceCache.GetNull

Own

[OwnerReturn]
public static method Own → (1)

handle in : IResourceHandle

The resource handle.

returns → IResource

The cached resource object.

Returns a cached resource object.

This method delegates to IResourceCache.OwnNull.

RenderException

If the resulting resource object would be null.

See also

IResourceCache.OwnNull

Own​Pixel​Font

[OwnerReturn]
public static method OwnPixelFont → (1)

pixelFont in : IResourceHandle

[not-null]
The pixel font handle.

returns → PixelFont

The pixel font.

Helper that delegates to IResourceCache.OwnNull and returns a default font (see PixelFont.HandleDefault) if it returns null.