Class GorgonTextureCache<T>

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

Inheritance

object

GorgonTextureCache<T>

Implements

IEnumerable<T>

IEnumerable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

Namespace: Gorgon.Graphics.Core

Assembly: Gorgon.Graphics.Core.dll

Syntax

public class GorgonTextureCache<T> : IEnumerable<T>, IEnumerable where T : class, IGorgonTextureResource

Type Parameters

Name	Description
T	The type of texture view to store. Must be a reference type, and implement IGorgonTextureResource.

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 Name 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

GorgonTextureCache(GorgonGraphics)

Initializes a new instance of the GorgonTextureCache<T> class.

Declaration

public GorgonTextureCache(GorgonGraphics graphics)

Parameters

Type	Name	Description
GorgonGraphics	graphics	The graphics interface used to create textures.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the graphics parameter is null.

See Also

IGorgonTextureResource

Properties

Count

Property to return the number of cached textures.

Declaration

public int Count { get; }

Property Value

Type	Description
int

See Also

IGorgonTextureResource

Methods

AddTexture(T)

Function to add a texture to the cache.

Declaration

public int AddTexture(T texture)

Parameters

Type	Name	Description
T	texture	The texture to add.

Returns

Type	Description
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.

This method is thread safe.

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

IGorgonTextureResource

Clear()

Function to clear the cached textures.

Declaration

public void Clear()

Remarks

This will dispose of all textures in the cache. Please take care to update any objects dependent upon the textures stored in the cache after calling this method.

See Also

IGorgonTextureResource

Dispose()

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

Declaration

public void Dispose()

Remarks

This method is NOT thread safe.

See Also

IGorgonTextureResource

FindTexture(string)

Function to retrieve a previously cached texture.

Declaration

public T FindTexture(string textureName)

Parameters

Type	Name	Description
string	textureName	The name of the texture to look up.

Returns

Type	Description
T	The cached texture, or null if it was not cached.

Remarks

This method will retrieve the texture associated with the textureName from the cache if it has been loaded into the cache. If it was not loaded, then the method will return null.

If a texture was reclaimed by the garbage collector, then this method will return null.

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(T). However, since the texture is stored as a weak reference internally, the garbage collector can still free the texture, so calling ReturnTexture(T) is not mandatory. However, it is best practice to call the method when it is no longer in use.

This method is thread safe.

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 until the garbage collector picks it up.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the textureName parameter is null.
ArgumentEmptyException	Thrown when the textureName parameter is empty.

See Also

IGorgonTextureResource

GetEnumerator()

Returns an enumerator that iterates through the collection.

Declaration

public IEnumerator<T> GetEnumerator()

Returns

Type	Description
IEnumerator<T>	A IEnumerator<T> that can be used to iterate through the collection.

See Also

IGorgonTextureResource

GetTextureAsync(string, Func<string, Task<T>>)

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

Declaration

public Task<T> GetTextureAsync(string textureName, Func<string, Task<T>> missingTextureAction = null)

Parameters

Type	Name	Description
string	textureName	The name of the texture to look up.
Func<string, Task<T>>	missingTextureAction	[Optional] The method to call if a texture is missing, or not loaded.

Returns

Type	Description
Task<T>	The cached texture.

Remarks

This method will load the texture associated with the textureName 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.

If a texture was reclaimed by the garbage collector, or was never added to the cache, then the missingTextureAction method is called to retrieve the texture from an external source (e.g. loaded from the file system) and returned to be added to the cache (or updated with a fresh copy). If the parameter is not specified, then Gorgon's internal resource list will be examined for the specified texture (using the LocateResourcesByName<T>(GorgonGraphics, string, LocateFilterType, StringComparison) extension method).

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(T). However, since the texture is stored as a weak reference internally, the garbage collector can still free the texture, so calling ReturnTexture(T) is not mandatory. However, it is best practice to call the method when it is no longer in use.

This method is thread safe.

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 until the garbage collector picks it up.

Exceptions

Type	Condition
ArgumentNullException	Thrown when the textureName parameter is null.
ArgumentEmptyException	Thrown when the textureName parameter is empty.

See Also

IGorgonTextureResource

GetUserCount(T)

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

Declaration

public int GetUserCount(T texture)

Parameters

Type	Name	Description
T	texture	The texture to look up.

Returns

Type	Description
int	The number of users for the texture.

See Also

IGorgonTextureResource

ReturnTexture(T)

Function to return the texture to cache.

Declaration

public bool ReturnTexture(T texture)

Parameters

Type	Name	Description
T	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.

This method is thread safe.

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

IGorgonTextureResource

Implements

IEnumerable<T>

IEnumerable

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonTreeLinqExtensions.TraverseDepthFirst<T>(IEnumerable<T>, Func<T, IEnumerable<T>>)

GorgonTreeLinqExtensions.Traverse<T>(IEnumerable<T>, Func<T, IEnumerable<T>>)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)

See Also

IGorgonTextureResource