Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
ime::SpriteSheet Class Reference

An ImageSprite which contains images of the same size arranged in a grid. More...

#include <SpriteSheet.h>

Inheritance diagram for ime::SpriteSheet:
ime::SpriteImage ime::Object

Public Types

using Ptr = std::shared_ptr< SpriteSheet >
 shared spritesheet pointer More...
 
using Frame = UIntRect
 A frame in the spritesheet. More...
 

Public Member Functions

 SpriteSheet ()
 Default constructor. More...
 
 SpriteSheet (const std::string &sourceTexture, Vector2u frameSize, Vector2u spacing={0, 0}, UIntRect area={})
 Constructor. More...
 
void create (const std::string &sourceTexture, Vector2u frameSize, Vector2u spacing={0, 0}, UIntRect area={})
 Create the spritesheet. More...
 
 SpriteSheet (const SpriteSheet &)=default
 Copy constructor. More...
 
SpriteSheetoperator= (const SpriteSheet &)=default
 Copy assignment operator. More...
 
 SpriteSheet (SpriteSheet &&) noexcept=default
 Move constructor. More...
 
SpriteSheetoperator= (SpriteSheet &&) noexcept=default
 Move assignment operator. More...
 
std::string getClassName () const override
 Get the name of this class. More...
 
Vector2u getFrameSize () const
 Get the size of each frame in the spritesheet. More...
 
Vector2u getSpaceBetweenFrames () const
 Get the space between frames in the spritesheet. More...
 
std::size_t getFramesCount () const
 Get the number of frames in the spritesheet. More...
 
std::optional< FramegetFrame (Index index) const
 Get the frame at a given index. More...
 
std::optional< FramegetFrame (const std::string &alias) const
 Get the frame by its assigned alias. More...
 
std::vector< FramegetFramesOnRow (unsigned int row) const
 Get all the frames in a given row. More...
 
std::vector< FramegetFramesOnColumn (unsigned int column) const
 Get all the frames in a given column. More...
 
std::vector< FramegetFramesInRange (Index start, Index end) const
 Get all the frames in a range. More...
 
std::vector< FramegetAllFrames () const
 Get all the frames in the spritesheet. More...
 
Vector2u getSizeInFrames () const
 Get the size of the spritesheet in frames. More...
 
unsigned int getRowCount () const
 Get the number of rows in the spritesheet. More...
 
unsigned int getColumnCount () const
 Get the number of columns in the spritesheet. More...
 
Sprite getSprite (Index index) const
 Get a sprite from an index. More...
 
Sprite getSprite (const std::string &alias) const
 Get a sprite from the index with a given alias. More...
 
std::vector< SpritegetSpritesOnRow (unsigned int row) const
 Get all the sprites in a row. More...
 
std::vector< SpritegetSpritesOnColumn (unsigned int column) const
 Get all the sprites in a column. More...
 
std::vector< SpritegetSpritesInRange (Index start, Index end) const
 Get all the sprites in a range. More...
 
std::vector< SpritegetAllSprites () const
 Get all the sprites in the spritesheet. More...
 
bool hasFrame (Index index) const
 Check if an index has a frame or not. More...
 
bool hasFrame (const std::string &alias) const
 Check if there is a frame with a specified alias. More...
 
bool assignAlias (Index index, const std::string &alias)
 Assign an alias to a frame. More...
 
 ~SpriteSheet () override
 Destructor. More...
 
void create (const std::string &sourceTexture, UIntRect area={})
 Create the sprite image. More...
 
Vector2u getSize () const
 Get the size of the sprite image in pixels. More...
 
unsigned int getWidth () const
 Get the width of the sprite image in pixels. More...
 
unsigned int getHeight () const
 Get the height of the sprite image in pixels. More...
 
std::string getClassType () const override
 Get the name of this class. More...
 
const TexturegetTexture () const
 Get the source texture of the sprite image. More...
 
Vector2u getRelativePosition () const
 Get the top-left position of the sprite image relative to the sprite image source texture. More...
 
void setTag (const std::string &tag)
 Assign the object an alias. More...
 
const std::string & getTag () const
 Get the tag assigned to the object. More...
 
unsigned int getObjectId () const
 Get the unique id of the object. More...
 
int onPropertyChange (const std::string &property, const Callback< Property > &callback, bool oneTime=false)
 Add an event listener to a specific property change event. More...
 
int onPropertyChange (const Callback< Property > &callback, bool oneTime=false)
 Add an event listener to any property change event. More...
 
void suspendedEventListener (int id, bool suspend)
 Pause or resume execution of an event listener. More...
 
bool isEventListenerSuspended (int id) const
 Check if an event listener is suspended or not. More...
 
bool removeEventListener (const std::string &event, int id)
 Remove an event listener from an event. More...
 
bool removeEventListener (int id)
 Remove an event listener. More...
 
int onDestruction (const Callback<> &callback)
 Add a destruction listener. More...
 
bool isSameObjectAs (const Object &other) const
 Check if another object is the same instance as this object. More...
 

Protected Member Functions

bool contains (Vector2u point) const
 Check if the sprite image contains a point or not. More...
 
void emitChange (const Property &property)
 Dispatch a property change event. More...
 
void emitDestruction ()
 Emit a destruction event. More...
 

Protected Attributes

EventEmitter eventEmitter_
 Event dispatcher. More...
 

Detailed Description

An ImageSprite which contains images of the same size arranged in a grid.

This class only works with a SpriteImage that has contiguous textures (perfectly aligned vertically or horizontally) that are the same size. Use the TextureAtlas for textures that are different sizes and have no specific arrangement in the source texture. Usually a spritesheet holds animation frames of a single entity such as (but not limited to) a characters animation in an idle, walking, running or jumping state

Definition at line 52 of file SpriteSheet.h.

Member Typedef Documentation

◆ Frame

A frame in the spritesheet.

Definition at line 55 of file SpriteSheet.h.

◆ Ptr

using ime::SpriteSheet::Ptr = std::shared_ptr<SpriteSheet>

shared spritesheet pointer

Definition at line 54 of file SpriteSheet.h.

Constructor & Destructor Documentation

◆ SpriteSheet() [1/4]

ime::SpriteSheet::SpriteSheet ( )

Default constructor.

Warning
This constructor creates an empty spritesheet, you must call the create() function before using the class, not doing so leads to undefined behavior
See also
create

◆ SpriteSheet() [2/4]

ime::SpriteSheet::SpriteSheet ( const std::string &  sourceTexture,
Vector2u  frameSize,
Vector2u  spacing = {0, 0},
UIntRect  area = {} 
)

Constructor.

Parameters
sourceTextureFilename of the image used by the spritesheet
frameSizeThe size of each frame in the source texture
spacingThe space between frames in the source texture
areaSub-rectangle to construct spritesheet from
Exceptions
FileNotFountif the the source image cannot be found on the disk

The area can be used to construct the spritesheet from a sub-rectangle of the whole spritesheet image. To construct the spritesheet from the whole image (default), leave the area argument unspecified. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size

Note
This class assumes that if the spacing between frames in non- zero then the frame has spacing on both sides. For example if the spacing is {1, 0}, it is assumed that each individual frame has a space of 1 pixel to its left and a space of 1 pixel to its right (The assumption applies for first frames)

◆ SpriteSheet() [3/4]

ime::SpriteSheet::SpriteSheet ( const SpriteSheet )
default

Copy constructor.

◆ SpriteSheet() [4/4]

ime::SpriteSheet::SpriteSheet ( SpriteSheet &&  )
defaultnoexcept

Move constructor.

◆ ~SpriteSheet()

ime::SpriteSheet::~SpriteSheet ( )
override

Destructor.

Member Function Documentation

◆ assignAlias()

bool ime::SpriteSheet::assignAlias ( Index  index,
const std::string &  alias 
)

Assign an alias to a frame.

Parameters
indexIndex of the frame to assign an alias
aliasThe alias to be assigned to the frame
Returns
True if the frame was assigned an alias

This function allows a frame or a sprite to be accessed by its name instead of its index

sprite image.assignAlias("blank_frame", Index{4, 0});
sprite image.getFrame("blank_frame"); //Returns frame at index 4, 0
//Returns a sprite displaying the image at index 4, 0
sprite image.getSprite("blank_frame");
See also
getFrame(const std::string&)

◆ contains()

bool ime::SpriteImage::contains ( Vector2u  point) const
protectedinherited

Check if the sprite image contains a point or not.

Parameters
pointThe point to be checked
Returns
True if the sprite image contains the point otherwise false

◆ create() [1/2]

void ime::SpriteImage::create ( const std::string &  sourceTexture,
UIntRect  area = {} 
)
inherited

Create the sprite image.

Parameters
sourceTextureThe filename of the sprite image on the disk
areaSub-rectangle to construct sprite image from
Exceptions
FileNotFoundExceptionIf the image could not be found on the disk

The area can be used to construct the sprite image from a sub-rectangle of the sourceTexture. To construct the sprite image from the whole sourceTexture (default), leave the area argument unspecified. If the area rectangle crosses the bounds of the sourceTexture, it is adjusted to fit the sourceTexture size

Note
Only use this function if you've previously created an empty sprite image
See also
SpriteImage()

◆ create() [2/2]

void ime::SpriteSheet::create ( const std::string &  sourceTexture,
Vector2u  frameSize,
Vector2u  spacing = {0, 0},
UIntRect  area = {} 
)

Create the spritesheet.

Parameters
sourceTextureFilename of the image used by the spritesheet
frameSizeThe size of each frame in the source texture
spacingThe space between frames in the source texture
areaSub-rectangle to construct spritesheet from
Exceptions
FileNotFountif the the source image cannot be found on the disk

The area can be used to construct the spritesheet from a sub-rectangle of the whole spritesheet image. To construct the spritesheet from the whole image (default), leave the area argument unspecified. If the area rectangle crosses the bounds of the image, it is adjusted to fit the image size

Note
This class assumes that if the spacing between frames in non- zero then the frame has spacing on both sides. For example if the spacing is {1, 0}, it is assumed that each individual frame has a space of 1 pixel to its left and a space of 1 pixel to its right (The assumption applies for first frames)
Only use this function if you've previously created an empty spritesheet
See also
SpriteSheet()

◆ emitChange()

void ime::Object::emitChange ( const Property property)
protectedinherited

Dispatch a property change event.

Parameters
propertyThe property that changed

This function will invoke all the event listeners of the specified property

See also
emit

◆ emitDestruction()

void ime::Object::emitDestruction ( )
protectedinherited

Emit a destruction event.

Note
This function must be the first statement in the definition of a destructor to avoid undefined behavior. In addition, note that destruction listeners are invoked once. Therefore, multiple classes in a hierarchy may call this function but the class that makes the call first will be the one that invokes the destruction listeners

◆ getAllFrames()

std::vector< Frame > ime::SpriteSheet::getAllFrames ( ) const

Get all the frames in the spritesheet.

Returns
All the frames in the spritesheet

◆ getAllSprites()

std::vector< Sprite > ime::SpriteSheet::getAllSprites ( ) const

Get all the sprites in the spritesheet.

Returns
All the sprites in the spritesheet

◆ getClassName()

std::string ime::SpriteSheet::getClassName ( ) const
overridevirtual

Get the name of this class.

Returns
The name of this class

Implements ime::Object.

◆ getClassType()

std::string ime::SpriteImage::getClassType ( ) const
overridevirtualinherited

Get the name of this class.

Returns
The name of this class

Note that this function is only overridden by child classes of Object which also serve as a base class for other classes

See also
Object::getClassType and Object::getClassName

Reimplemented from ime::Object.

◆ getColumnCount()

unsigned int ime::SpriteSheet::getColumnCount ( ) const

Get the number of columns in the spritesheet.

Returns
The number of columns in the spritesheet

◆ getFrame() [1/2]

std::optional< Frame > ime::SpriteSheet::getFrame ( const std::string &  alias) const

Get the frame by its assigned alias.

Parameters
aliasThe alias assigned to a frame
Returns
The frame at the specified index if it is within bounds otherwise returns no value

◆ getFrame() [2/2]

std::optional< Frame > ime::SpriteSheet::getFrame ( Index  index) const

Get the frame at a given index.

Parameters
indexThe index to get the frame of
Returns
The frame at the specified index if it is within bounds otherwise returns no value

Note that index starts at {0, 0}

◆ getFramesCount()

std::size_t ime::SpriteSheet::getFramesCount ( ) const

Get the number of frames in the spritesheet.

Returns
The total number of frames in the spritesheet

Note that the number of sprites in the spritesheet is the same as the number of frames

◆ getFramesInRange()

std::vector< Frame > ime::SpriteSheet::getFramesInRange ( Index  start,
Index  end 
) const

Get all the frames in a range.

Parameters
startThe start of the range (inclusive)
endThe end of the range (inclusive)
Returns
All the frames in the specified range or an empty vector if the range is invalid

The range must either be on a row or column. For rows the x components of the start and end arguments must be the same. Similarly, for columns, the y components of the start and end must be the same otherwise an empty vector will be returned. In addition for components that varies (row or column), the start component must be less than the end component. An empty vector will also be returned if the either the start or end index is out of bounds

Note that start and end start at {0, 0}

//Returns all the frames in row 1 from column 2 to column 5
spritesheet.getFramesInRange(Index{1, 2}, Index{1, 5});
//Returns all the frames in column 4 from row 0 to row 5
spritesheet.getFramesInRange(Index{0, 4}, Index{5, 4});

◆ getFrameSize()

Vector2u ime::SpriteSheet::getFrameSize ( ) const

Get the size of each frame in the spritesheet.

Returns
The size of each frame in the spritesheet

◆ getFramesOnColumn()

std::vector< Frame > ime::SpriteSheet::getFramesOnColumn ( unsigned int  column) const

Get all the frames in a given column.

Parameters
columnThe column to get the frames from
Returns
All the frames in the specified column or an empty vector if the column is out of bounds

Note that column starts at 0

◆ getFramesOnRow()

std::vector< Frame > ime::SpriteSheet::getFramesOnRow ( unsigned int  row) const

Get all the frames in a given row.

Parameters
rowThe row to get the frames from
Returns
All the frames in the specified row or an empty vector if the row is out of bounds

Note that row starts at 0

◆ getHeight()

unsigned int ime::SpriteImage::getHeight ( ) const
inherited

Get the height of the sprite image in pixels.

Returns
The height of the sprite image in pixels

◆ getObjectId()

unsigned int ime::Object::getObjectId ( ) const
inherited

Get the unique id of the object.

Returns
The unique id of the object

Note that each instance of ime::Object has a unique id

See also
setTag

◆ getRelativePosition()

Vector2u ime::SpriteImage::getRelativePosition ( ) const
inherited

Get the top-left position of the sprite image relative to the sprite image source texture.

Returns
The relative top-left position

If the sprite image was created from the whole source texture, this function returns {0, 0}

See also
SpriteImage

◆ getRowCount()

unsigned int ime::SpriteSheet::getRowCount ( ) const

Get the number of rows in the spritesheet.

Returns
The number of rows in the spritesheet

◆ getSize()

Vector2u ime::SpriteImage::getSize ( ) const
inherited

Get the size of the sprite image in pixels.

Returns
The size of the sprite image in pixels

The x component is width whilst the y component is the height of the sprite image

◆ getSizeInFrames()

Vector2u ime::SpriteSheet::getSizeInFrames ( ) const

Get the size of the spritesheet in frames.

Returns
The size of the spritesheet in frames
Warning
The x component is the number of columns and the y component is the number of rows

◆ getSpaceBetweenFrames()

Vector2u ime::SpriteSheet::getSpaceBetweenFrames ( ) const

Get the space between frames in the spritesheet.

Returns
The space between frames in the spritesheet

◆ getSprite() [1/2]

Sprite ime::SpriteSheet::getSprite ( const std::string &  alias) const

Get a sprite from the index with a given alias.

Parameters
aliasThe name given to a frame in the spritesheet
Returns
The sprite at the aliased index or an empty sprite if there is no frame with the specified alias
See also
assignAlias

◆ getSprite() [2/2]

Sprite ime::SpriteSheet::getSprite ( Index  index) const

Get a sprite from an index.

Parameters
indexIndex to get the sprite from
Returns
The sprite at the given index, or an empty sprite if the index is out of bounds

Note than index starts at {0, 0}

◆ getSpritesInRange()

std::vector< Sprite > ime::SpriteSheet::getSpritesInRange ( Index  start,
Index  end 
) const

Get all the sprites in a range.

Parameters
startThe start of the range (inclusive)
endThe end of the range (inclusive)
Returns
All the sprites in the specified range or an empty vector if the range is invalid

The range must either be on a row or column. For rows the x components of the start and end arguments must be the same. Similarly, for columns, the y components of the start and end must be the same otherwise an empty vector will be returned. In addition for components that varies (row or column), the start component must be less than the end component. An empty vector will also be returned if the either the start or end index is out of bounds

Note that start and end start at {0, 0}

//Returns all the sprites in row 1 from column 2 to column 5
spritesheet.getSpritesInRange(Index{1, 2}, Index{1, 5});
//Returns all the sprites in column 4 from row 0 to row 5
spritesheet.getSpritesInRange(Index{0, 4}, Index{5, 4});

◆ getSpritesOnColumn()

std::vector< Sprite > ime::SpriteSheet::getSpritesOnColumn ( unsigned int  column) const

Get all the sprites in a column.

Parameters
columnThe column to get the sprites from
Returns
All the sprites in the specified column or an empty vector if the column is out of bounds

Note that column starts at 0

See also
getSpritesOnRows

◆ getSpritesOnRow()

std::vector< Sprite > ime::SpriteSheet::getSpritesOnRow ( unsigned int  row) const

Get all the sprites in a row.

Parameters
rowThe row to get the sprites from
Returns
All the sprites in the specified row or an empty vector if the row is out of bounds

Note that row starts at 0

See also
getSpritesOnColumn

◆ getTag()

const std::string & ime::Object::getTag ( ) const
inherited

Get the tag assigned to the object.

Returns
The tag of the object
See also
setTag

◆ getTexture()

const Texture & ime::SpriteImage::getTexture ( ) const
inherited

Get the source texture of the sprite image.

Returns
The source texture of the sprite image
Warning
Don't call this function when the sprite image is not yet created. Also, the texture is destroyed when the sprite image is destroyed, exercise caution when there are Sprite objects referencing the sprite image texture
See also
create

◆ getWidth()

unsigned int ime::SpriteImage::getWidth ( ) const
inherited

Get the width of the sprite image in pixels.

Returns
The width of the sprite image in pixels

◆ hasFrame() [1/2]

bool ime::SpriteSheet::hasFrame ( const std::string &  alias) const

Check if there is a frame with a specified alias.

Parameters
aliasName of the alias given to a frame
Returns
True if a frame with the specified alias exist or false if there is no frame with the given alias
See also
assignAlias

◆ hasFrame() [2/2]

bool ime::SpriteSheet::hasFrame ( Index  index) const

Check if an index has a frame or not.

Parameters
indexIndex to be checked
Returns
True if there is a frame at the specified index of false if the index is invalid

Note that index starts at {0, 0}

◆ isEventListenerSuspended()

bool ime::Object::isEventListenerSuspended ( int  id) const
inherited

Check if an event listener is suspended or not.

Parameters
idThe identification number of the listener to be checked
Returns
True if suspended, otherwise false

This function also returns false if the specified event listener does not exist

See also
suspendedEventListener

◆ isSameObjectAs()

bool ime::Object::isSameObjectAs ( const Object other) const
inherited

Check if another object is the same instance as this object.

Parameters
otherThe object to compare against this object
Returns
True if other is the same instance as this object, otherwise false

◆ onDestruction()

int ime::Object::onDestruction ( const Callback<> &  callback)
inherited

Add a destruction listener.

Parameters
callbackFunction to be executed when the object is destroyed
Returns
The unique id of the destruction listener

The destruction listener is called when the object reaches the end of its lifetime. Note that an object may have multiple destruction listeners registered to it

Warning
It's not advised to call virtual functions in the destruction callback as some parts of the object may have already been destroyed by the time the callback is invoked. In such an event, the behavior is undefined
See also
removeEventListener

◆ onPropertyChange() [1/2]

int ime::Object::onPropertyChange ( const Callback< Property > &  callback,
bool  oneTime = false 
)
inherited

Add an event listener to any property change event.

Parameters
callbackThe function to be executed when any property changes
oneTimeTrue to execute the callback one-time or false to execute it every time the event is triggered
Returns
The unique id of the event listener

When unsubscribing the any property change event handler, you must pass "propertyChange" as the name of the event

See also
onPropertyChange(const std::string&, const ime::Callback<ime::Property>&)

◆ onPropertyChange() [2/2]

int ime::Object::onPropertyChange ( const std::string &  property,
const Callback< Property > &  callback,
bool  oneTime = false 
)
inherited

Add an event listener to a specific property change event.

Parameters
propertyThe name of the property to add an event listener to
oneTimeTrue to execute the callback one-time or false to execute it every time the event is triggered
callbackThe function to be executed when the property changes
Returns
The unique id of the event listener

A property change event is triggered by any function that begins with set, where the the text after set is the name of the property. For example, the setTag() function, modifies the tag property of the object, thus will generate a "tag" change event each time it is called

Note that multiple event listeners may be registered to the same property change event. In addition, when adding a property change event listener, the name of the property must be in lowercase.

// Prints the tag of the player object to the console everytime it changes
player.onPropertyChange("tag", [](const Property& property) {
cout << "New tag: " << property.getValue<std::string>() << endl;
});
...
//Sets tag = "player1" and invokes event listener(s)
player.setTag("player1");
See also
unsubscribe and onPropertyChange(const ime::Callback<ime::Property>&)

◆ operator=() [1/2]

SpriteSheet & ime::SpriteSheet::operator= ( const SpriteSheet )
default

Copy assignment operator.

◆ operator=() [2/2]

SpriteSheet & ime::SpriteSheet::operator= ( SpriteSheet &&  )
defaultnoexcept

Move assignment operator.

◆ removeEventListener() [1/2]

bool ime::Object::removeEventListener ( const std::string &  event,
int  id 
)
inherited

Remove an event listener from an event.

Parameters
eventThe name of the event to remove an event listener from
idThe unique id of the event listener to be removed
Returns
True if the event listener was removed or false if the event or the event listener is does not exist
// Display the tag of the object to console every time it changes
auto tagChangeId = object.onPropertyChange("tag", [](ime::Property tag) {
std::cout << name.getValue<std::string>() << std::endl;
});
// Stop displaying the tag of the object when it changes
object.removeEventListener("tag", tagChangeId);
Class that can store a value of any type.
Definition: Property.h:38

◆ removeEventListener() [2/2]

bool ime::Object::removeEventListener ( int  id)
inherited

Remove an event listener.

Parameters
idThe id of the event listener to be removed
Returns
True if the event listener was removed or false if no such handler exists

◆ setTag()

void ime::Object::setTag ( const std::string &  tag)
inherited

Assign the object an alias.

Parameters
tagThe alias of the object

This function is useful if you want to refer to the object by a tag instead of its object id. Unlike an object id, multiple objects may have the same tag

By default, the tag is an empty string

See also
getObjectId

◆ suspendedEventListener()

void ime::Object::suspendedEventListener ( int  id,
bool  suspend 
)
inherited

Pause or resume execution of an event listener.

Parameters
idThe event listeners unique identification number
suspendTrue to suspend/pause or false to unsuspend/resume
See also
isEventListenerSuspended

Member Data Documentation

◆ eventEmitter_

EventEmitter ime::Object::eventEmitter_
protectedinherited

Event dispatcher.

Definition at line 289 of file Object.h.


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