Class TextureCache

A texture cache used to keep textures resident for use over a user defined lifetime.

Inheritance
object
TextureCache
Implements
Inherited Members
Namespace: Gorgon.Editor.Rendering
Assembly: Gorgon.Editor.API.dll
Syntax
public class TextureCache : ITextureCache, IDisposable
Remarks

In some cases, textures are shared amongst several components because it is inefficient to load the same texture multiple times. However, the problem of ownership arises when one or more of the components needs to be destroyed, what to do about the texture it uses? Simply disposing of the texture would not work since the other components need this texture to work properly.

This is where the texture cache can be used to solve the problem. A texture cache will keep the textures resident in memory as long as they're being used. When a texture is requested by passing in its IContentFile it will load the texture if it is not previously cached, or if the actual texture object was disposed. If the texture was previously cached, then the cached texture will be returned, incrementing an internal count, which is used to determine how many items are using the texture.

When a texture is no longer required, the texture should not be disposed. Instead, use the texture cache to return the texture which will automatically dispose of it when no more objects are using it. If the texture is required again, then retrieving it from the texture cache will load the texture again.

Constructors

| Edit this page View Source

TextureCache(GorgonGraphics, IContentFileManager, IGorgonFileSystemWriter<Stream>, IGorgonImageCodec, IGorgonLog)

Initializes a new instance of the TextureCache class.

Declaration
public TextureCache(GorgonGraphics graphics, IContentFileManager fileManager, IGorgonFileSystemWriter<Stream> tempWriter, IGorgonImageCodec codec, IGorgonLog log)
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface used to create textures.
IContentFileManager fileManager

The file manager for the project file system.
IGorgonFileSystemWriter<Stream> tempWriter

The temporary writer used to write temporary data.
IGorgonImageCodec codec

The image codec.
IGorgonLog log

The logging interface for capturing debug messages.
Exceptions
Type Condition
ArgumentNullException

Thrown when any of the parameters are null.
See Also

Methods

| Edit this page View Source

AddTextureAsync(GorgonTexture2DView)

Function to add a texture to the cache.

Declaration
public Task<int> AddTextureAsync(GorgonTexture2DView texture)
Parameters
Type Name Description
GorgonTexture2DView texture

The texture to add.
Returns
Type Description
Task<int>

The number of users for the texture.
Remarks

Use this method to assign a pre-loaded texture to the cache. If the texture is already in the cache, then its user count is incremented.

important

Once a texture is added, the cache will assume ownership of the texture. Thus, the texture must not be disposed.

Exceptions
Type Condition
ArgumentNullException

Thrown when the texture parameter is null.
FileNotFoundException

Thrown when the name of the texture cannot be correlated to a file in the file system.
See Also
| Edit this page View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public void Dispose()
See Also
| Edit this page View Source

GetTextureAsync(IContentFile)

Function to retrieve a cached texture (or load one if it's not available).

Declaration
public Task<GorgonTexture2DView> GetTextureAsync(IContentFile file)
Parameters
Type Name Description
IContentFile file

The file containing the texture data.
Returns
Type Description
Task<GorgonTexture2DView>

The cached texture.
Remarks

This method will load the texture associated with the file passed in if it does not exist in the cache. If the texture is in the cache, then the cached version is returned to the user.

Every call to this method will increment an internal reference count for a cached texture. The texture will not be disposed of until this reference count hits zero. This can only be done with a call to ReturnTexture(GorgonTexture2DView). However, since the texture is stored as a weak reference internally, the garbage collector can still free the texture, so calling ReturnTexture(GorgonTexture2DView) is not mandatory. However, it is still recommended you call the method.

important

Do not dispose of the returned texture manually. Doing so will leave the reference count incorrect, and the cached value returned will be invalid.

See Also
| Edit this page View Source

GetUserCount(GorgonTexture2DView)

Function to retrieve the user count for a texture in the cache.

Declaration
public int GetUserCount(GorgonTexture2DView texture)
Parameters
Type Name Description
GorgonTexture2DView texture

The texture to look up.
Returns
Type Description
int

The number of users for the texture.
See Also
| Edit this page View Source

ReturnTexture(GorgonTexture2DView)

Function to return the texture to cache.

Declaration
public bool ReturnTexture(GorgonTexture2DView texture)
Parameters
Type Name Description
GorgonTexture2DView texture

The texture to return.
Returns
Type Description
bool

true if the texture was freed, false if not.
Remarks

This method should be called when the texture is no longer required.

important

Do not dispose of the returned texture manually. Doing so will leave the reference count incorrect, and the cached value returned will be invalid.

See Also

Implements

Extension Methods

See Also