Interface ITextureCache
A texture cache used to keep textures resident for use over a user defined lifetime.
Inherited Members
Namespace: Gorgon.Editor.Rendering
Assembly: Gorgon.Editor.API.dll
Syntax
public interface ITextureCache : IDisposableRemarks
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.
Methods
| Edit this page View SourceAddTextureAsync(GorgonTexture2DView)
Function to add a texture to the cache.
Declaration
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.
See Also
| Edit this page View SourceGetTextureAsync(IContentFile)
Function to retrieve a cached texture (or load one if it's not available).
Declaration
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 SourceGetUserCount(GorgonTexture2DView)
Function to retrieve the user count for a texture in the cache.
Declaration
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 SourceReturnTexture(GorgonTexture2DView)
Function to return the texture to cache.
Declaration
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.