Interface IGorgonRenderTargetFactory

A factory for creating/retrieving render targets for temporary use.

Namespace: Gorgon.Graphics.Core

Assembly: Gorgon.Graphics.Core.dll

Syntax

public interface IGorgonRenderTargetFactory

Remarks

During the lifecycle of an application, many render targets may be required. In most instances, creating a render target for a scene and disposing of it when done is all that is required. But, when dealing with effects, shaders, etc... render targets may need to be created and released during a frame and doing this several times in a frame can be costly.

This factory allows applications to "rent" a render target and return it when done with only an initial cost when creating a target for the first time. This way, temporary render targets can be reused when needed.

When the factory retrieves a target, it will check its internal pool and see if a render target already exists. If it exists, and is not in use, it will return the existing target. If the target does not exist, or is being used elsewhere, then a new target is created and added to the pool.

Targets retrieved by this factory must be returned when they are no longer needed, otherwise the purpose of the factory is defeated. As such, best practice is to rent and return a render target during the lifetime of a single frame. If the IsDebugEnabled property is set to true, then after a swap chain presentation, a warning will be sent to the application log complaining about render targets still rented out at the end of the frame.

Properties

AvailableCount

Property to return the number of free render targets available for rent.

Declaration

int AvailableCount { get; }

Property Value

Type	Description
int

ExpiryTime

Property to set or return the maximum lifetime for an unrented render target, in minutes.

Declaration

double ExpiryTime { get; set; }

Property Value

Type	Description
double

RentedCount

Property to return the number of render targets that are currently in flight.

Declaration

int RentedCount { get; }

Property Value

Type	Description
int

TotalCount

Property to return the total number of render targets available in the factory.

Declaration

int TotalCount { get; }

Property Value

Type	Description
int

Methods

ExpireTargets(bool)

Function to expire any previously allocated targets after a certain amount of time.

Declaration

void ExpireTargets(bool force = false)

Parameters

Type	Name	Description
bool	force	true to clear all unrented targets immediately, false to only remove targets that have expired past the ExpiryTime.

Remarks

Applications should call this method to free up memory associated with the cached render targets. This only affects targets that are not currently rented out.

See Also

ExpiryTime

Rent(IGorgonTexture2DInfo, string, bool)

Function to rent a render target from the factory.

Declaration

GorgonRenderTarget2DView Rent(IGorgonTexture2DInfo targetInfo, string name, bool clearOnRetrieve = true)

Parameters

Type	Name	Description
IGorgonTexture2DInfo	targetInfo	The information about the render target to retrieve.
string	name	A unique user defined name for a new render target.
bool	clearOnRetrieve	[Optional] true to clear the render target when retrieved, or false to leave the contents as-is.

Returns

Type	Description
GorgonRenderTarget2DView	The requested render target.

Remarks

All calls to this method should be paired with a call to the Return(GorgonRenderTarget2DView) method. Failure to do so may result in a leak.

The optional clearOnRetrieve parameter, if set to true,, will clear the contents of a render target that is being reused prior to returning it. In some cases this is not ideal, so setting it to false will preserve the contents. New render targets will always be cleared.

caution

For performance reasons, any exceptions thrown from this method will only be thrown when Gorgon is compiled as DEBUG.

Return(GorgonRenderTarget2DView)

Function to return the render target to the factory.

Declaration

bool Return(GorgonRenderTarget2DView rtv)

Parameters

Type	Name	Description
GorgonRenderTarget2DView	rtv	The render target to return.

Returns

Type	Description
bool	true if the target was returned successfully, false if not.

Extension Methods

GorgonDebugExtensions.ValidateObject<T>(T, string)

GorgonNullExtensions.AsNullable<T>(object)

GorgonNullExtensions.IfNull<T>(object, T)

GorgonNullExtensions.IsNull(object)