SpriteSheet

Generated from engine/render/sprite_sheet.h at 862e08b. The text under each declaration is the header's own comment, word for word. About the reference says how these pages are made.

Browse the render module

#include "engine/render/sprite_sheet.h" · namespace labrador

class SpriteSheet

class SpriteSheet

One texture, and the names of the rectangles inside it.

The texture is a handle, not a pointer. A raw device resource here would need re-seating by hand after a device restore - a set_texture(), and a sprite-sheet asset kind whose reload function differs from its load function. A handle names a registry slot and the reload refills that slot, so the sheet survives a device loss without being touched, and this class names no backend type at all.

frame_handle · strip_handle

using frame_handle = Handle<SpriteFrame>;
using strip_handle = Handle<AnimationStrip>;

What a frame name and a strip name become once resolved. They are distinct types on purpose: both are an index into this sheet, and the two tables are not the same table.

SpriteSheet

SpriteSheet(TextureHandle texture,
  NameTable<SpriteFrame> sprite_frames,
  NameTable<AnimationStrip> animation_strips);

Built by read_sprite_sheet (engine/assets/) from an already-parsed definition: the sheet indexes and draws, it does not read files.

resolve_sprite_frame · resolve_animation_strip

frame_handle resolve_sprite_frame(const std::string& name) const;
strip_handle resolve_animation_strip(const std::string& name) const;

Load-time. Turn a name from a definition file into something the draw path can carry. Both throw std::out_of_range naming the element if this sheet does not contain it.

A handle is an index into *this* sheet and means nothing against another, so whatever holds one holds the sheet it came from too.

sprite_frame · animation_strip

const SpriteFrame& sprite_frame(frame_handle frame) const;
const AnimationStrip& animation_strip(strip_handle strip) const;

Per-frame. No name, no map: an index into a contiguous table.

texture

TextureHandle texture() const;

draw

void draw(DrawList& draw_list,
  frame_handle frame,
  const mattmath::RectangleF& destination,
  const Colour& colour = Colour::white,
  float rotation = 0.0f,
  const mattmath::Vector2F& origin = mattmath::Vector2F::ZERO,
  SpriteFlip flip = SpriteFlip::none,
  float layer_depth = 0.0f) const;

Every draw is const: a single SpriteSheet is shared by every drawable in the level and is entered concurrently by the render workers, so nothing here may mutate the frame or strip tables.

The destination is in world space and the list's current camera maps it; the position overloads are the same draw with the size taken from the source rectangle, which is arithmetic no backend performs.

origin IS ADDED TO THE FRAME'S OWN, NOT SUBSTITUTED FOR IT. A sheet may author a pivot per frame (sprite_frame.h), and these two overloads are where it reaches a quad. Both quantities are in unscaled source texels - the same units, so they compose with no conversion, exactly as build_glyph_quad composes a pen with a string's origin (sprite_geometry.h).

Addition rather than "the caller's if it gave one" because the second needs a sentinel this signature does not have: a default argument cannot tell a caller that said nothing from one that asked for the top-left corner, so the rule would be a silent policy hanging off whether a Vector2F happened to be zero. A frame with no authored pivot adds zero, so the caller's origin is the whole of it.

draw

void draw(DrawList& draw_list,
  frame_handle frame,
  const mattmath::Vector2F& position,
  const Colour& colour = Colour::white,
  float rotation = 0.0f,
  const mattmath::Vector2F& origin = mattmath::Vector2F::ZERO,
  float scale = 1.0f,
  SpriteFlip flip = SpriteFlip::none,
  float layer_depth = 0.0f) const;

draw

void draw(DrawList& draw_list,
  const mattmath::RectangleI& source,
  const mattmath::RectangleF& destination,
  const Colour& colour = Colour::white,
  float rotation = 0.0f,
  const mattmath::Vector2F& origin = mattmath::Vector2F::ZERO,
  SpriteFlip flip = SpriteFlip::none,
  float layer_depth = 0.0f) const;

The same two, for a caller holding a source rectangle rather than a frame handle - an animation strip's current frame is computed, not named.

SO origin IS THE CALLER'S ALONE HERE, and the asymmetry with the pair above is not an oversight: there is no frame, so there is no authored pivot to add. A strip's definition has no origin key either, which is why the one caller that reaches these - AnimationObject - loses nothing by it. A sheet that wants a per-frame pivot on an animation is asking for a schema this loader does not have.

draw

void draw(DrawList& draw_list,
  const mattmath::RectangleI& source,
  const mattmath::Vector2F& position,
  const Colour& colour = Colour::white,
  float rotation = 0.0f,
  const mattmath::Vector2F& origin = mattmath::Vector2F::ZERO,
  float scale = 1.0f,
  SpriteFlip flip = SpriteFlip::none,
  float layer_depth = 0.0f) const;

Related types

Named in the public declarations above: AnimationStrip, Colour, DrawList, Handle, NameTable, RectangleF, RectangleI, SpriteFlip, SpriteFrame, Vector2F.

In the samples and tests

The files that include this header directly. A file can also reach it through another header.

• tests/assets/ sprite_sheet_loader_tests.cpp
• tests/render/ animation_object_tests.cpp, null_tests.cpp, sprite_sheet_object_tests.cpp, visual_tests.cpp
• tests/scene/ cull_tests.cpp