SpriteCache
Description
- Derived from
-
Disposable abstract
ICapacity
A sprite cache uses a set of 2D textures to cache rectangular sprite images for subsequent rendering in batches.
Sprites are (usually small) 2D images that are drawn onto the screen, either pixel-perfectly or with bilinear filtering when an affine transformation is used. Using a separate texture resource for each sprite may have negative impact on performance, especially for numerous sprites of small sizes. By packing sprite images into a sprite cache, near-optimal performance can be achieved when rendering many sprites. Using a SpriteCache involves the following steps:
-
Choose the sprite cache parameters and create a new SpriteCache object.
-
Use Allocate to add new sprites to the cache. Each sprite will get a unique sprite ID.
-
Use Data to obtain a SpriteData object, which will be used to upload sprite image content.
-
Call Prepare to prepare the sprite image content. This step includes transformations and texture encoding.
-
Call Image to upload the prepared sprite image content to the GPU.
-
Use Render to obtain render batch values for allocated sprites, in order to render their image content.
-
Use Release to remove sprites from the cache.
The texels of each slice of each cache texture are arranged sequentially, using a 2D space-filling curve. An index range in the resulting texel sequence may then represent rectangular texel blocks of the following sizes: 1x1, 1x2, 1x3, 1x4, 2x3, 2x5, 3x4, 2x2, 2x4, 2x6, etc. Each sprite is represented by a single textured quadrilateral, where each quadrilateral has its own texel block.
Public / Constructors
SpriteCache
Creates a new instance of SpriteCache.
The capacity in parameter depicts the maximum number of sprites that may be present in the cache, regardless of their size (this determines the vertex buffer size, see Vertices). The effective number of sprites that fit into the cache depends on the size opt and count opt parameters, as well on the actual sizes that are passed to Allocate.
- RenderException
-
If a graphics subsystem error has occurred.
Public / Methods
Allocate
Allocates a new sprite, without specifying its image content.
For aspect ratios (i.e. width in / height in) less than 0.25 or greater than 4.00, consider splitting the sprite image, in order to achieve better packing into the sprite texture atlas. This method does not update the GPU resources.
- See also
Image
Specifies the image content of the given sprite.
This method updates the GPU resources using GpuUpdateFlag.Discard.
- See also
Prepare
Prepares the image content of the given sprite.
This method does not update the GPU resources.
ReadPixels
Reads the contents of the sprite cache texture from the GPU.
This method assumes that IBeginEnd.Begin has been called on context in and that no render effect is active.
- RenderException
-
If a graphics subsystem error has occurred.
Release
Releases the given sprite.
The sprite identifier becomes invalid when a sprite is released and may be reused later, when another sprite is allocated. This method does not update the GPU resources.
Render
Returns the vertex index of the textured quadrilateral to use for rendering the given sprite.
The textured quadrilateral may be used to submit GPU work until Release is called again (passing spriteId in). To render the sprite, the following triangles must be drawn:
triangle-0 = (X+0, X+1, X+2) triangle-1 = (X+3, X+2, X+1)
The Z-coordinate of the vertex positions in Vertices depict the texture slice that contains the sprite image content.
Public / Attributes
Vertices
Returns the vertex buffer that holds the textured quadrilaterals to use for rendering the image content of the allocated sprites.
Each sprite has a textured quadrilateral with a contiguous range of four vertices in the buffer, which form a triangle strip primitive that represents the sprite image:
Sprite quadrilateral: Position TexCoord 0-----1 0 : top-left = (x+0, y+0) (u0, v0) | | 1 : top-right = (x+w, y+0) (u1, v0) | | 2 : bottom-left = (x+0, y+h) (u0, v1) 2-----3 3 : bottom-right = (x+w, y+h) (u1, v1)
where w, h, x and y are the values that have been specified to Allocate. This is the vertex layout (see VertexElements):
@0 : Float x 3 (Position) @12 : UInt8_Norm_Srgb x 4 (Color) @16 : Float x 3 (TextureCoords) @28 : - pad - @32 : - end -
The VertexElementUsage.Position X- and Y-coordinates refer to sprite image pixels, where (x,y) is the top-left corner of the top-left pixel of the sprite image and (x+w,y+h) is the bottom-right corner of the bottom-right pixel. The Z-coordinate depicts the texture slice. The VertexElementUsage.TextureCoords coordinates are the normalized texture coordinates of the corresponding outer pixel corner.
- See also