#include <Sprite.hpp>

Public Types
enum	FlipFlags { NORMAL = 0x00 , FLIP_X = 0x01 , FLIP_Y = 0x02 , FLIP_XY = 0x04 , FLIP_BOTH = FLIP_X \| FLIP_Y }

enum	SourceRectIndex { SRC_START_X = 0 , SRC_START_Y = 1 , SRC_LENGTH_X = 2 , SRC_LENGTH_Y = 3 }

enum class	AttachMode : int8_t { DEFAULT = 0x00 , KEEP_DIMS = 0x01 , KEEP_UVS = 0x02 , KEEP_TINT = 0x04 , KEEP_ROTATION = 0x08 , GENERATE_MIPS = 0x10 }

Public Member Functions
virtual	~Sprite ()=default

virtual bool	loadTexture (const std::string &, AttachMode mode)=0

bool	loadTexture (const std::string &)

virtual Texture2D *	getTexture () const =0

float	xPos () const noexcept

void	xPos (float x) noexcept

float	yPos () const noexcept

void	yPos (float y) noexcept

float	width () const noexcept

void	width (float width) noexcept

float	height () const noexcept

void	height (float height) noexcept

void	dimensions (float &width, float &height) const noexcept

std::tuple< int, int >	dimensions () const noexcept

float	rotationInRadians () const noexcept

void	rotationInRadians (float rotation_radians)

float	scale () const noexcept

void	scale (float scale_value) noexcept

Colour	colour () const noexcept

void	colour (ASGE::Colour sprite_colour) noexcept

bool	isFlippedOnX () const noexcept

bool	isFlippedOnY () const noexcept

bool	isFlippedOnXY () const noexcept

void	setFlipFlags (FlipFlags flags) noexcept

FlipFlags	flipFlags () const noexcept

void	opacity (float alpha) noexcept

float	opacity () const noexcept

float *	srcRect () noexcept

const float *	srcRect () const noexcept

SpriteBounds	getLocalBounds () const noexcept

SpriteBounds	getWorldBounds () const noexcept

virtual bool	attach (ASGE::Texture2D *texture2D, AttachMode mode) noexcept=0

virtual bool	attach (ASGE::Texture2D *texture2D) noexcept

ASGE::Point2D	midpoint () const

int16_t	getGlobalZOrder () const noexcept

void	setGlobalZOrder (int16_t new_z_order) noexcept

const SHADER_LIB::Shader *	getPixelShader () const noexcept

SHADER_LIB::Shader *	getPixelShader () noexcept

void	setPixelShader (SHADER_LIB::Shader *shader) noexcept

bool	hasPixelShader () const noexcept

void	setMagFilter (Texture2D::MagFilter requested_filter) const noexcept

Protected Member Functions
std::array< float, 2 > &	dimensions ()

Friends
AttachMode	operator\| (AttachMode lhs, AttachMode rhs)

AttachMode	operator& (AttachMode lhs, AttachMode rhs)

Detailed Description

An ASGE supported sprite.

Used to render and load textures. Includes the ability to resize, scale, flip, recolour etc. 2D games are made up of these. This is the interface that defines the platform specific implementation's API. The management and loading of GPU data is handled within the inherited specialisations.

Definition at line 45 of file Sprite.hpp.

Member Enumeration Documentation

◆ AttachMode

enum ASGE::Sprite::AttachMode : int8_t

strong

Flags to control attachments of textures. When attaching a texture to the sprite, by default the sprite's settings will be reset to match the newly attached texture. These flags allow the user to prevent certain resets from occurs.

Enumerator
DEFAULT	By default, clobber the existing sprite's settings.
KEEP_DIMS	Retain the sprite's dimensions.
KEEP_UVS	Retain the sprite's UV settings.
KEEP_TINT	Retain the sprite's tint.
KEEP_ROTATION	Retain the sprite's rotation.
GENERATE_MIPS	Generate a new set of MipMaps for the texture.

Definition at line 85 of file Sprite.hpp.

◆ FlipFlags

enum ASGE::Sprite::FlipFlags

Flags to control the flipping of the sprite.

Used to flip the texture's UV coordinates. The flip is performed on the CPU when calculating the UVs.

Enumerator
NORMAL	texture is not flipped.
FLIP_X	texture is flipped on the x axis.
FLIP_Y	texture is flipped on the y axis.
FLIP_XY	texture is flipped diagonally.
FLIP_BOTH	texture is flipped on both axis.

Definition at line 54 of file Sprite.hpp.

◆ SourceRectIndex

enum ASGE::Sprite::SourceRectIndex

a simple enum to help with src rectangles These enums provide the index numbers that are used for manipulating the UV coordinates when mapping textures to sprites. They form a rectangle that contents delimit the range to use when calculating the source UV coordinates.

Enumerator
SRC_START_X	The starting position on the texture's X axis.
SRC_START_Y	The starting position on the texture's Y axis.
SRC_LENGTH_X	The length of the source rectangle.
SRC_LENGTH_Y	The width of the source rectangle.

Definition at line 71 of file Sprite.hpp.

Constructor & Destructor Documentation

◆ ~Sprite()

virtual ASGE::Sprite::~Sprite ( )

virtualdefault

Default destructor.

The destructor does not free the memory used on the GPU. This is handled inside the platform's specific implementation.

Member Function Documentation

◆ attach()

virtual bool ASGE::Sprite::attach	(	ASGE::Texture2D *	texture2D,
		AttachMode	mode
	)

pure virtualnoexcept

Attaches a texture to the sprite.

Sprites are simply textures which have transform and rendering properties applied to them. They are mostly for convenience of rendering. It is possible to swap out the texture attached to the sprite. Doing so will result the UV coordinates and width and height of the sprite to match the texture, so any changes will need to be reapplied.

Parameters

texture2D The texture to attach.

Returns: True if successful.

◆ colour() [1/2]

Colour ASGE::Sprite::colour ( ) const

noexcept

Gets the colour of the sprite.

The colour of the sprite can be influenced by providing a tint. The pixel shader will then apply the tint on the resultant pixel when sampling the texture.

Returns: The sprite's colour.

See also: ASGE::Colour

◆ colour() [2/2]

void ASGE::Sprite::colour ( ASGE::Colour sprite_colour )

noexcept

Sets the colour of the sprite.

The colour of the sprite can be influenced by providing a tint. The pixel shader will then apply the tint on the resultant pixel when sampling the texture.

Parameters

[in] sprite_colour The sprite's colour.

See also: ASGE::Colour; ASGE::COLOURS

◆ dimensions() [1/3]

std::array<float, 2>& ASGE::Sprite::dimensions ( )

protected

Retrieves the dimensions.

Returns: The array describing the width and height of the sprite.

◆ dimensions() [2/3]

std::tuple<int,int> ASGE::Sprite::dimensions ( ) const

noexcept

Gets the non-transformed height and the width of the sprite.

Returns: A tuple representing width and height.

◆ dimensions() [3/3]

void ASGE::Sprite::dimensions	(	float &	width,
		float &	height
	)		const

noexcept

Gets the non-transformed height and the width of the sprite.

Updates the width and the height of two parameters passed in to the function. It does not return a value. The width and height is found in the resultant parameters.

Parameters

[in]	width	The sprites width.
[in]	height	The sprites height.

◆ flipFlags()

FlipFlags ASGE::Sprite::flipFlags ( ) const

noexcept

Returns the current flip flags for the sprite.

Flip flags can be used to change the orientation of the texture's render. It does this by altering UV mappings. Use this function to retrieve the current flip flags used for rendering the attached texture.

Returns: flags The flip flags that apply to the texture.

See also: ASGE::Sprite::FlipFlags

◆ getGlobalZOrder()

int16_t ASGE::Sprite::getGlobalZOrder ( ) const

noexcept

Retrieves the rendering order (layer) of the sprite.

Returns: The sprite's current z-order.

◆ getLocalBounds()

SpriteBounds ASGE::Sprite::getLocalBounds ( ) const

noexcept

Retrieves the sprite's 4 points in local space.

Simply returns the sprite's original and unmodified dimensions. No transforms will be applied, meaning rotation and scaling are absent and the points can be considered as local or model space. These points can be used as the starting basis of an AABB or for additional collision detection.

Returns: The four vertex bounds of the sprite.

◆ getPixelShader() [1/2]

const SHADER_LIB::Shader* ASGE::Sprite::getPixelShader ( ) const

noexcept

Retrieves any attached shader.

Returns: A pointer to the shader attached to the sprite. May be null.

See also: ASGE::SHADER_LIB::Shader

◆ getPixelShader() [2/2]

SHADER_LIB::Shader* ASGE::Sprite::getPixelShader ( )

noexcept

Retrieves any attached shader.

Returns: A pointer to the shader attached to the sprite. May be null.

See also: ASGE::SHADER_LIB::Shader

◆ getTexture()

virtual Texture2D* ASGE::Sprite::getTexture ( ) const

pure virtual

Pure virtual function for retrieving the loaded texture.

This is handled inside the platform's specific implementation.

Returns: The currently attached texture.

◆ getWorldBounds()

SpriteBounds ASGE::Sprite::getWorldBounds ( ) const

noexcept

Retrieves the sprite's 4 points in world space.

Returns the 4 vertices that delimit the sprite's position in world space. Any transforms (scaling and rotation) have already been applied. This is useful for when you need to know the projected location i.e. calculating a bounding volume.

Returns: The four vertex bounds of the sprite in world space.

◆ hasPixelShader()

bool ASGE::Sprite::hasPixelShader ( ) const

noexcept

Checks to see if this sprite has a pixel shader attached.

Returns: True if pixel shader is attached.

◆ height() [1/2]

float ASGE::Sprite::height ( ) const

noexcept

Gets the height of the sprite.

Height is used (along with scale, rotation etc) to determine how tall a sprite will be when it's rendered to the screen. This is the non-transformed height of the sprite.

Returns: The sprites height.

◆ height() [2/2]

void ASGE::Sprite::height ( float height )

noexcept

Sets the height of the sprite.

Height is used (along with scale, rotation etc) to determine how tall a sprite will be when it's rendered to the screen. This is the non-transformed height of the sprite.

Parameters

[in] height The sprites height.

◆ isFlippedOnX()

bool ASGE::Sprite::isFlippedOnX ( ) const

noexcept

Checks to see if the texture is flipped on the X axis.

It is possible to flip the UV coordinates used on the sprite's texture. This will check to see if the X axis is flipped.

Returns: If the texture is flipped on the X axis.

◆ isFlippedOnXY()

bool ASGE::Sprite::isFlippedOnXY ( ) const

noexcept

Checks to see if the texture is flipped diagonally.

Returns: If the texture is flipped on the Y axis.

◆ isFlippedOnY()

bool ASGE::Sprite::isFlippedOnY ( ) const

noexcept

Checks to see if the texture is flipped on the Y axis.

It is possible to flip the UV coordinates used on the sprite's texture. This will check to see if the Y axis is flipped.

Returns: If the texture is flipped on the Y axis.

◆ loadTexture() [1/2]

bool ASGE::Sprite::loadTexture ( const std::string & )

Returns: The result of the load operation.

◆ loadTexture() [2/2]

virtual bool ASGE::Sprite::loadTexture	(	const std::string &	,
		AttachMode	mode
	)

pure virtual

Pure virtual function for loading texture on to the GPU.

This is handled inside the platform's specific implementation.

Returns
The result of the load operation.

◆ midpoint()

ASGE::Point2D ASGE::Sprite::midpoint ( ) const

Calculates the mid-point of the sprite.

Sprites origins are normally 0,0, which maps to the top left. This function returns the mid-point of the sprite based on its with and height and its current position in the world.

Note: This midpoint is scaled using the sprites scale factor.

Returns: The midpoint as an ASGE::Point2D

See also: ASGE::Point2D

◆ opacity() [1/2]

float ASGE::Sprite::opacity ( ) const

noexcept

Retrieves the opacity of the sprite.

This function let's you obtain the opacity of the sprite. The opacity is controlled by using the alpha channel. 1.0f is opaque and 0.0f is completely transparent.

Returns: The value for the alpha channel.

◆ opacity() [2/2]

void ASGE::Sprite::opacity ( float alpha )

noexcept

Sets the opacity of the sprite.

This function let's you control the opacity of the sprite by modifying the alpha channel during the render cycle. 1.0f is opaque and 0.0f is completely transparent.

Parameters

[in] alpha The new value for the alpha channel.

◆ rotationInRadians() [1/2]

float ASGE::Sprite::rotationInRadians ( ) const

noexcept

Gets the rotation of the sprite in radians.

The angle of rotation is used to rotate the sprite around it's origin. The origin defaults to the mid-point of the sprite. The angle of rotation is expressed in radians.

Returns: The sprites angle of rotation in radians.

Note: \((degrees = radians * 180^\theta\ / pi)\)

◆ rotationInRadians() [2/2]

void ASGE::Sprite::rotationInRadians ( float rotation_radians )

Sets the rotation of the sprite in radians.

The angle of rotation is used to rotate the sprite around it's origin. The origin defaults to the mid-point of the sprite. The angle of rotation is expressed in radians.

Parameters

[in] rotation_radians The angle of rotation in radians.

Note: \((degrees = radians * 180^\theta\ / pi)\)

◆ scale() [1/2]

float ASGE::Sprite::scale ( ) const

noexcept

Gets the scale of the sprite.

The scale can be adjusted to automatically make the sprite bigger or smaller than it's original size, allowing for on the fly alterations without having to edit the sprite's true size. The scaling operation is performed in both axis.

Returns: The scale factor.

◆ scale() [2/2]

void ASGE::Sprite::scale ( float scale_value )

noexcept

Sets the scale of the sprite.

The scale can be adjusted to automatically make the sprite bigger or smaller than it's original size, allowing for on the fly alterations without having to edit the sprite's true size. The scaling operation is performed in both axis.

Parameters

[in] scale_value The scaling factor to apply to the sprite.

◆ setFlipFlags()

void ASGE::Sprite::setFlipFlags ( FlipFlags flags )

noexcept

Sets the flip state of the texture.

It is possible to flip the UV coordinates used on the sprite's texture. This function allows setting of the flip flags. These are then used to control shader's UV mappings.

Parameters

flags The flip flags to apply to the texture.

◆ setGlobalZOrder()

void ASGE::Sprite::setGlobalZOrder ( int16_t new_z_order )

noexcept

Sets the rendering order (layer) of the sprite.

When rendering it is often necessary to control the order in which sprites, text or even UI elements are rendered. For example, if parts of the UI were rendered before the background they would end up hidden. Z-ordering is a common approach to controlling this behaviour and is essential when using batch rendering.

Parameters

[in] new_z_order The z-order to apply to sprite.

Note: Typically, an object with a lower z-order will be rendered before one with a higher z-order. In ASGE you can use the z_order property to control the render ordering.

Example

In this image you can see an example of when the z-order for a sprite is not set correctly. The blocks below the player should have a lower z-order than the player's sprite to ensure they are rendered first.

GameDev @ StackExchange

◆ setMagFilter()

void ASGE::Sprite::setMagFilter ( Texture2D::MagFilter requested_filter ) const

noexcept

Sets the magnification filter on the attached texture.

Use this function to alter the texture sampling behaviour when the attached texture is being read.

See also: ASGE::Texture2D::MagFilter

Parameters

requested_filter

◆ setPixelShader()

void ASGE::Sprite::setPixelShader ( SHADER_LIB::Shader * shader )

noexcept

Attaches a shader to the sprite.

When rendering in ASGE, it is possible to create custom pixel shaders that can have additional uniforms which can be updated by the developer. You can either flag the renderer to switch shaders, or if you only need a small subset of sprites to use the custom shader, attach them directly. The renderer will take care of switching shaders out when rendering to the GPU.

Parameters

[in] shader The shader to attach.

◆ srcRect() [1/2]

const float* ASGE::Sprite::srcRect ( ) const

noexcept

Gets a read-only source rectangle used for rendering.

It is possible to render a subset of a sprite using a rectangle. The rectangle will use [0] and [1] for the beginning x and y position in the texture and [2] and [3] for the width and height. This is useful when the texture is a sprite sheet.

Returns: The rectangle (as a constant) used for the UV source.

Warning: Make sure not to access the pointer out of bounds as this will lead to undefined behaviour.

◆ srcRect() [2/2]

float* ASGE::Sprite::srcRect ( )

noexcept

Gets the source rectangle used for rendering.

It is possible to render a subset of a sprite using a rectangle. The rectangle will use [0] and [1] for the beginning x and y position in the texture and [2] and [3] for the width and height. This is useful when the texture is a sprite sheet.

Returns: A pointer to the rectangle array used for the UV source.

Warning: Make sure not to access the pointer out of bounds as this will lead to undefined behaviour.

◆ width() [1/2]

float ASGE::Sprite::width ( ) const

noexcept

Gets the width of the sprite.

Width is used (along with scale, rotation etc) to determine how wide/long a sprite will be when it's rendered to the screen. This is the non-transformed width of the sprite.

Returns: The sprites width.

◆ width() [2/2]

void ASGE::Sprite::width ( float width )

noexcept

Sets the width of the sprite.

Width is used (along with scale, rotation etc) to determine how wide/long a sprite will be when it's rendered to the screen. This is the non-transformed width of the sprite.

Parameters

[in] width The sprites width.

◆ xPos() [1/2]

float ASGE::Sprite::xPos ( ) const

noexcept

Returns the sprite's position on the X axis.

Sprite positions are described using Cartesian Coordinates. The horizontal position in this engine is labelled X and runs from left to right. If an ASGE::Camera is not used it is mapped directly to the screen via the viewport.

Returns: The position current position the x axis.

◆ xPos() [2/2]

void ASGE::Sprite::xPos ( float x )

noexcept

Updates the sprite's position on the X axis.

Sprite positions are described using Cartesian Coordinates. The horizontal position in this engine is labelled X and runs from left to right. If an ASGE::Camera is not used it is mapped directly to the screen via the viewport.

Parameters

[in] x The sprites new position on the x axis.

◆ yPos() [1/2]

float ASGE::Sprite::yPos ( ) const

noexcept

Returns the sprite's position on the Y axis.

Sprite positions are described using Cartesian Coordinates. The vertical position in this engine is labelled y and runs from top to bottom. If an ASGE::Camera is not used it is mapped directly to the screen via the viewport.

Returns: The sprites new position on the y axis

◆ yPos() [2/2]

void ASGE::Sprite::yPos ( float y )

noexcept

Returns the sprite's position on the Y axis.

Sprite positions are described using Cartesian Coordinates. The vertical position in this engine is labelled y and runs from top to bottom.If an ASGE::Camera is not used it is mapped directly to the screen via the viewport.

Parameters

[in] y The new position on the y axis

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

Sprite.hpp

Public Types

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Member Enumeration Documentation

◆ AttachMode

◆ FlipFlags

◆ SourceRectIndex

Constructor & Destructor Documentation

◆ ~Sprite()

Member Function Documentation

◆ attach()

◆ colour() [1/2]

◆ colour() [2/2]

◆ dimensions() [1/3]

◆ dimensions() [2/3]

◆ dimensions() [3/3]

◆ flipFlags()

◆ getGlobalZOrder()

◆ getLocalBounds()

◆ getPixelShader() [1/2]

◆ getPixelShader() [2/2]

◆ getTexture()

◆ getWorldBounds()

◆ hasPixelShader()

◆ height() [1/2]

◆ height() [2/2]

◆ isFlippedOnX()

◆ isFlippedOnXY()

◆ isFlippedOnY()

◆ loadTexture() [1/2]

◆ loadTexture() [2/2]

◆ midpoint()

◆ opacity() [1/2]

◆ opacity() [2/2]

◆ rotationInRadians() [1/2]

◆ rotationInRadians() [2/2]

◆ scale() [1/2]

◆ scale() [2/2]

◆ setFlipFlags()

◆ setGlobalZOrder()

◆ setMagFilter()

◆ setPixelShader()

◆ srcRect() [1/2]

◆ srcRect() [2/2]

◆ width() [1/2]

◆ width() [2/2]

◆ xPos() [1/2]

◆ xPos() [2/2]

◆ yPos() [1/2]

◆ yPos() [2/2]