donut::graphics::SpriteAtlas Class Reference

Expandable texture atlas for packing 2D images into a spritesheet to enable batch rendering. More...

#include <donut/graphics/SpriteAtlas.hpp>

Classes
struct	Sprite
	Information about a specific image in the spritesheet. More...
struct	SpriteId
	Identifier for a specific image in the spritesheet. More...

Public Types
enum	FlipAxis : Flip { NO_FLIP = 0 , FLIP_HORIZONTALLY = 1 << 0 , FLIP_VERTICALLY = 1 << 1 }
	Flag values for Flip that describe how a sprite is flipped when rendered. More...
using	Flip = std::uint8_t
	Flags that describe how a sprite is flipped when rendered. More...

Public Member Functions
	SpriteAtlas ()=default
	Construct an empty sprite atlas. More...
	SpriteAtlas (const SpriteAtlasOptions &options)
	Construct an empty sprite atlas. More...
SpriteId	insert (Renderer &renderer, const ImageView &image, Flip flip=NO_FLIP)
	Add a new image to the spritesheet, possibly expanding the texture atlas in order to make space for it. More...
SpriteId	createSubSprite (SpriteId baseSpriteId, std::size_t offsetX, std::size_t offsetY, std::size_t width, std::size_t height, Flip flip=NO_FLIP)
	Add a new sprite that is defined as a sub-region of an existing sprite. More...
const Sprite &	getSprite (SpriteId id) const
	Get information about a specific image in the spritesheet. More...
const Texture &	getAtlasTexture () const noexcept
	Get a reference to the internal texture atlas. More...

Detailed Description

Expandable texture atlas for packing 2D images into a spritesheet to enable batch rendering.

Examples

example_game.cpp.

Member Typedef Documentation

Flip

using donut::graphics::SpriteAtlas::Flip = std::uint8_t

Flags that describe how a sprite is flipped when rendered.

Member Enumeration Documentation

FlipAxis

enum donut::graphics::SpriteAtlas::FlipAxis : Flip

Flag values for Flip that describe how a sprite is flipped when rendered.

Enumerator
NO_FLIP	Do not flip the sprite.
FLIP_HORIZONTALLY	Flip the sprite along the X axis.
FLIP_VERTICALLY	Flip the sprite along the Y axis.

Constructor & Destructor Documentation

SpriteAtlas() [1/2]

donut::graphics::SpriteAtlas::SpriteAtlas ( )

default

Construct an empty sprite atlas.

SpriteAtlas() [2/2]

donut::graphics::SpriteAtlas::SpriteAtlas ( const SpriteAtlasOptions &  options )

inlineexplicit

Construct an empty sprite atlas.

Parameters

options

sprite atlas options, see SpriteAtlasOptions.

Member Function Documentation

insert()

SpriteId donut::graphics::SpriteAtlas::insert ( Renderer &  renderer, const ImageView &  image, Flip  flip = NO_FLIP  )

inline

Add a new image to the spritesheet, possibly expanding the texture atlas in order to make space for it.

Parameters

renderer	renderer to use for expanding the texture atlas, if needed.
image	non-owning view over the image to copy into the spritesheet.
flip	flags that describe how the sprite should be flipped when rendered.

Returns

an identifier for the inserted image.

Exceptions

graphics::Error	on failure to copy the image or expand the texture atlas.
std::bad_alloc	on allocation failure.

See also

createSubSprite()

createSubSprite()

SpriteId donut::graphics::SpriteAtlas::createSubSprite ( SpriteId  baseSpriteId, std::size_t  offsetX, std::size_t  offsetY, std::size_t  width, std::size_t  height, Flip  flip = NO_FLIP  )

inline

Add a new sprite that is defined as a sub-region of an existing sprite.

Parameters

baseSpriteId	identifier for the existing sprite to create a sub-region of. Must have been obtained from a previous call to insert() or createSubSprite() on the same SpriteAtlas object as the one that this function is called on.
offsetX	horizontal offset, in pixels, from the left edge of the original sprite, where the new sprite will begin. Must be less than or equal to the width of the original sprite image.
offsetY	vertical offset, in pixels, from the bottom edge of the original sprite, where the new sprite will begin. Must be less than or equal to the height of the original sprite image.
width	width, in pixels, of the new sprite region. Must be less than or equal to the width of the original sprite image minus offsetX.
height	height, in pixels, of the new sprite region. Must be less than or equal to the height of the original sprite image minus offsetY.
flip	flags that describe how the sprite should be flipped when rendered.

Returns

an identifier for the new sub-sprite.

Exceptions

std::bad_alloc

on allocation failure.

Note

This function does not grow the texture atlas.

See also

insert()

getSprite()

const Sprite& donut::graphics::SpriteAtlas::getSprite ( SpriteId  id ) const

inline

Get information about a specific image in the spritesheet.

Parameters

id	identifier for the image to get the information of. Must have been obtained from a previous call to insert() or createSubSprite() on the same SpriteAtlas object as the one that this function is called on.

Returns

a read-only reference to the sprite information that is valid until the next call to insert(), or until the SpriteAtlas is destroyed, whichever happens first.

getAtlasTexture()

const Texture& donut::graphics::SpriteAtlas::getAtlasTexture ( ) const

inlinenoexcept

Get a reference to the internal texture atlas.

Returns

a read-only reference to the texture atlas containing the sprite image data that is valid until the next call to insert(), or until the SpriteAtlas is destroyed, whichever happens first.

---

The documentation for this class was generated from the following file:

• include/donut/graphics/SpriteAtlas.hpp