VisualCache

Description

sealed class Tinman.Engine.Drawing.VisualCache

Derived from

Disposable abstract
IBeginEnd

The visual cache is a high-level utility for rendering 2D visuals, by rasterizing them into textured quadrilaterals.

To perform rendering of 2D visuals, the following steps are necessary:

  1. Create a IVisualRasterizer instance, which will perform rasterization of 2D visuals.

  2. Create a Sprites object, which will hold the textured quadrilaterals which represent the rasterized 2D visuals.

  3. Create a VisualCache object and specify a IGraphicsContext that is compatible with the IBufferFactory and ITextureFactory of the Sprites.

  4. Call IBeginEnd.Begin to begin a new render cycle. Render cycles may be nested and should wrap actual render code only, so that they will end as soon as possible.

  5. Call Get to obtain the render batch for a visual instance.

  6. Use the RangeI value obtained from the previous step, Geometry and Texture to render the visual instance, for example by calling IPrimitiveRenderer.DrawIndexed. Use instancing and/or indirect draw buffers to reduce the number of draw calls, if necessary.

  7. Call IBeginEnd.End to end the current render cycle.

  8. Use Clear and Evict to remove visuals from the cache that will no longer be used. This allows the cache to operate more efficiently.

Public / Constructors

Visual​Cache

public constructor VisualCache → (5)

rasterizer in : IVisualRasterizer

[not-null]
The visual rasterizer to use.

context in : IGraphicsContext

[not-null]
The graphics context to use.

sprites in : SpriteCache own

[not-null]
The sprite cache to use.

sizeMinimum opt : int32 = 16

[>0]
Fragments of rasterized 2D visuals will not be split when their width and height is less than this minimum.

sizeMaximum opt : int32 = 256

[>=sizeMinimum]
Fragments of rasterized 2D visuals will be split if their width or height is greater than this maximum.

Creates a new instance of VisualCache.

RenderException

If a graphics subsystem error has occurred.

Public / Methods

Clear

[BeginEnd]
public method Clear → ()

Clears the visual cache.

Evict

[BeginEnd]
public method Evict → (1)

instance in : VisualInstance

The visual instance to remove from the cache.

Evicts the given visual instance from the cache.

This method should be used whenever an application has determined that it will no longer need a visual instance for some time. Evicting unused visual instances up-front will allow better use of the available cache texture space, compared to least-recently-used eviction.

Get

[BeginEnd]
public method Get → (2)

instance in : VisualInstance

The visual instance for which to return the render batch.

flags opt : VisualFlags = VisualFlags.Rasterize

The flags to use.

returns → int32

A bitwise combination of the following flags:
0x01 : the cache contains a usable version of instance in,
0x02 : the version of instance in in the cache is outdated,
0x04 : instance in is being rasterized in the background,
0x08 : the cache capacity is exhausted, no more visuals can be rasterized.
If there is a usable version, the RenderSize and RenderTriangles properties hold additional information about instance in, which will remain valid until Get is called for the next time.

Returns the cached render batch of the given visual instance, building it if necessary.

The returned render batch may be used to submit GPU work during the current IBeginEnd.Begin / IBeginEnd.End cycle. After the cycle has ended, the render batch may become invalid, because of the least-recently used eviction scheme of the visual cache. The results from background rasterization (see VisualFlags.Background) will be consumed when the next outermost call to IBeginEnd.Begin is made.

Public / Attributes

Geometry

[Constant]
public attribute Geometry → (get)

value : IGeometryBuffer

[not-null]
The geometry buffer.

The geometry buffer to use for rendering rasterized 2D visuals.

Rasterizer

[Constant]
public attribute Rasterizer → (get)

value : IVisualRasterizer

[not-null]
The rasterizer.

Returns the visual rasterizer.

Render​Size

public attribute RenderSize → (get)

value : Vec2F

The size of the visual, in visual units.

Returns the size of the rasterized visual.

When the triangles of a rasterized visual are rendered without transformation, the top-left corner of the visual bounds (see IVisual.Bounds) appears at the screen coordinates (0,0), which is the top-left corner of the top-left pixel. The bottom-right corner of the visual bounds maps to the screen coordinates (RenderSize.X,RenderSize.Y). The render size is not necessarily the same as the pixel size of the underlying sprite, see Visual.ComputeAlignedBounds.

See also

VisualCache.Get

Render​Triangles

public attribute RenderTriangles → (get)

value : RangeI

The index range of the triangle list primitive.

Returns the range of elements in Geometry that represent the rasterized visual, as an indexed triangle list. Will be RangeI.Zero if the cache does not (yet) contain a usable version of the visual instance or if the 2D visual is empty.

See also

VisualCache.Get

Sprites

[Constant]
public attribute Sprites → (get)

value : SpriteCache

[not-null]
The SpriteCache object.

Returns the sprite cache that holds the rasterization fragments of the 2D visuals.

Texture

[Constant]
public attribute Texture → (get)

value : ITexture2D

[not-null]
The cache texture.

The texture that contains the rasterized quadrilaterals of the 2D visuals.

Logging

Logger

public static readonly attribute Logger → (ILogger)

The logger object of this class.