Higher-level representation of an image. More...

#include <jngl/Sprite.hpp>

Classes
class	Batch
	While this object is alive, don't do any other draw calls. Should never outlive its Sprite. More...

class	Loader
	Use this class to load a Sprite asynchronously. More...

Public Types
enum class	LoadType : uint8_t { NORMAL , HALF , THREADED }

Public Member Functions
	Sprite (const ImageData &, double scale, std::optional< std::string_view > filename=std::nullopt, bool mipmap=false)
	Creates a Sprite from ImageData and scales it by scale.

	Sprite (const uint8_t *bytes, size_t width, size_t height, bool mipmap=false)
	The sprite data is stored as packed RGBA bytes in an array, where the size of the array needs to be calculated as `width * height * 4`.

	Sprite (const std::string &filename, LoadType loadType=LoadType::NORMAL, bool mipmap=false)

	Sprite (const std::string &filename, bool mipmap)

void	step ()
	Does nothing.

void	draw () const
	Draws the Sprite, centered by default.

void	draw (const Mat3 &modelview, const ShaderProgram *shaderProgram=nullptr) const
	Draws the image centered using modelview.

void	draw (Mat3 modelview, Alpha, const ShaderProgram *shaderProgram=nullptr) const

void	draw (Mat3 modelview, Rgba color) const
	Draws the sprite but multiplies each pixel's color with color.

void	drawLerped (Mat3 modelview, Rgb color, float red, float green, float blue, Alpha) const
	Draws the Sprite with each color channel linearly interpolated towards color.

void	draw (const ShaderProgram *shaderProgram) const
	Draws the sprite using the specified shader program.

Batch	batch (const ShaderProgram *shaderProgram=nullptr) const
	Allows to draw the Sprite multiple times at different locations in an efficient way.

void	drawScaled (float xfactor, float yfactor, const ShaderProgram *shaderProgram=nullptr) const
	Draws the image scaled by `xfactor` and `yfactor`

void	drawClipped (float xstart, float xend, float ystart, float yend) const

void	drawClipped (Vec2 start, Vec2 end) const
	Draw a cutout of the sprite. drawClipped({0, 0}, {1, 1}) would draw it normally.

void	drawMesh (const std::vector< Vertex > &vertexes, const ShaderProgram *=nullptr) const
	Draws a list of triangles with the sprite's texture on it using the global modelview from jngl::modelview()

void	drawMesh (const Mat3 &modelview, const std::vector< Vertex > &vertexes, const ShaderProgram *shaderProgram=nullptr) const
	Draws a list of triangles with the sprite's texture on it, ignores the Sprite's position.

void	drawMesh (const Mat3 &modelview, const std::vector< Vertex > &vertexes, jngl::Rgba color, const ShaderProgram *=nullptr) const

void	setBytes (const unsigned char *)

Vec2	getPos () const

void	setPos (double x, double y)

template<class Vect >
void	setPos (Vect p)

jngl::Vec2	getCenter () const

void	setCenter (double x, double y)

template<class Vect >
void	setCenter (Vect c)

double	getLeft () const

void	setLeft (double x)

double	getTop () const

void	setTop (double y)

double	getRight () const

void	setRight (double x)

double	getBottom () const

void	setBottom (double y)

double	getX () const

void	setX (double)

double	getY () const

void	setY (double)

Vec2	getSize () const

float	getWidth () const

float	getHeight () const

void	drawBoundingBox () const

bool	contains (jngl::Vec2 point) const

void	setTextureFilter (TextureFilter minification, TextureFilter magnification)
	Sets how the texture is sampled when the sprite is drawn smaller than its pixel size (minification) and bigger (magnification).

Static Public Member Functions
static const Shader &	vertexShader ()
	Returns a reference to JNGL's default vertex shader used to draw textures.

Public Attributes
std::shared_ptr< Finally >	loader
	Function which actually loads the sprite.

Detailed Description

Higher-level representation of an image.

Definition at line 27 of file Sprite.hpp.

Collaboration diagram for Sprite:

[legend]

Member Enumeration Documentation

◆ LoadType

enum class LoadType : uint8_t

strong

Definition at line 29 of file Sprite.hpp.

Constructor & Destructor Documentation

◆ Sprite() [1/4]

Sprite	(	const ImageData &	,
		double	scale,
		std::optional< std::string_view >	filename = std::nullopt,
		bool	mipmap = false )

explicit

Creates a Sprite from ImageData and scales it by scale.

When you want to draw an ImageData that hasn't been scaled, make sure to pass JNGL's scale factor so that it appears as the same size independent of the resolution of the user.

Example:

auto img = jngl::ImageData::load("foo.png");
auto sprite1 = std::make_unique<jngl::Sprite>(*img, jngl::getScaleFactor());
 
auto sprite2 = std::make_unique<jngl::Sprite>("foo.png");
 
assert(std::lround(sprite1.getWidth()) == std::lround(sprite2.getWidth()));

You may pass a filename, then JNGL will use that as a key for its internal texture cache, meaning that if there's already a file loaded with that name, it won't upload the passed ImageData to the GPU again. There is one texture per filename: once mipmap is true for that name, every later load shares the mipmapped texture.

Parameters

mipmap Generate mipmaps so the sprite filters cleanly when drawn smaller than its pixel size. Minification is trilinear. On OpenGL ES 2.0 the image's width and height must both be powers of two.

◆ Sprite() [2/4]

Sprite	(	const uint8_t *	bytes,
		size_t	width,
		size_t	height,
		bool	mipmap = false )

The sprite data is stored as packed RGBA bytes in an array, where the size of the array needs to be calculated as width * height * 4.

Parameters

mipmap Generate mipmaps for minification. See Sprite(const ImageData&, double, ...).

◆ Sprite() [3/4]

Sprite	(	const std::string &	filename,
		LoadType	loadType = LoadType::NORMAL,
		bool	mipmap = false )

explicit

Deprecated: Use Loader instead

Parameters

mipmap Generate mipmaps for minification. See Sprite(const ImageData&, double, ...).

◆ Sprite() [4/4]

Sprite	(	const std::string &	filename,
		bool	mipmap )

explicit

Deprecated: Use Loader instead

Parameters

mipmap Generate mipmaps for minification. See Sprite(const ImageData&, double, ...).

Member Function Documentation

◆ draw() [1/3]

void draw	(	const Mat3 &	modelview,
		const ShaderProgram *	shaderProgram = nullptr ) const

Draws the image centered using modelview.

Parameters

shaderProgram Passing nullptr uses the default.

◆ draw() [2/3]

void draw	(	Mat3	modelview,
		Rgba	color ) const

Draws the sprite but multiplies each pixel's color with color.

If the sprite is mostly white, this will make it appear in the specified color. If it's black, nothing will change.

◆ drawLerped()

void drawLerped	(	Mat3	modelview,
		Rgb	color,
		float	red,
		float	green,
		float	blue,
		Alpha	) const

Draws the Sprite with each color channel linearly interpolated towards color.

Parameters

red	0.0f (red channel unchanged) ... 1.0f (red channel of color)
green	0.0f (green channel unchanged) ... 1.0f (green channel of color)
blue	0.0f (blue channel unchanged) ... 1.0f (blue channel of color)

Unlike draw(Mat3, Rgba), which multiplies, this also works for black Sprites. The color set by jngl::setSpriteColor is ignored.

// completely white:
sprite.drawLerped(jngl::modelview(), 0xffffff_rgb, 1.f, 1.f, 1.f, jngl::Alpha(1.f));
// halfway between original colors and red, half transparent:
sprite.drawLerped(jngl::modelview(), 0xff0000_rgb, .5f, .5f, .5f, jngl::Alpha(.5f));
// only set the red channel to 1.0f:
sprite.drawLerped(jngl::modelview(), 0xffffff_rgb, 1.f, 0.f, 0.f, jngl::Alpha(1.f));

◆ draw() [3/3]

void draw ( const ShaderProgram * shaderProgram ) const

Draws the sprite using the specified shader program.

Parameters

shaderProgram A pointer to the ShaderProgram object to use for drawing.

◆ batch()

Batch batch ( const ShaderProgram * shaderProgram = nullptr ) const

Allows to draw the Sprite multiple times at different locations in an efficient way.

This is pureley a performance optimisation. If it's fast enough, use Sprite::draw instead.

Example:

void MyWork::draw() const {
    auto batch = mySprite.batch();
    for (jngl::Vec2 position : positions) {
        batch.draw(jngl::modelview().translate(position));
    }
}

Parameters

shaderProgram Passing nullptr uses the default.

◆ drawScaled()

void drawScaled	(	float	xfactor,
		float	yfactor,
		const ShaderProgram *	shaderProgram = nullptr ) const

Draws the image scaled by xfactor and yfactor

Parameters

xfactor	Scale width by this factor
yfactor	Scale height by this factor
shaderProgram	Passing `nullptr` uses the default.

drawScaled(1, 1) would draw it normally. You can pass negative values to flip the image. For example drawScaled(-1, 1) would draw the image horizontally flipped.

Deprecated: Scale the modelview matrix instead using jngl::Mat3::scale

◆ drawClipped()

void drawClipped	(	float	xstart,
		float	xend,
		float	ystart,
		float	yend ) const

Deprecated: Use new drawClipped(Vec2, Vec2) method instead

◆ drawMesh()

void drawMesh	(	const Mat3 &	modelview,
		const std::vector< Vertex > &	vertexes,
		const ShaderProgram *	shaderProgram = nullptr ) const

Draws a list of triangles with the sprite's texture on it, ignores the Sprite's position.

Example:

std::vector<jngl::Vertex> vertexes;
// mySprite is a Texture Atlas with two images next to each other.
// First image:
vertexes.emplace_back( 0,  0,   0, 0); // triangle 1
vertexes.emplace_back(10,  0, 0.5, 0);
vertexes.emplace_back(10, 10, 0.5, 1);
vertexes.emplace_back(10, 10, 0.5, 1); // triangle 2
vertexes.emplace_back( 0, 10, 0,   1);
vertexes.emplace_back( 0,  0, 0,   0);
// Second image:
vertexes.emplace_back(30,  0, 0.5, 0); // triangle 1
vertexes.emplace_back(40,  0,   1, 0);
vertexes.emplace_back(40, 10,   1, 1);
vertexes.emplace_back(40, 10,   1, 1); // triangle 2
vertexes.emplace_back(30, 10, 0.5, 1);
vertexes.emplace_back(30,  0, 0.5, 0);
mySprite.drawMesh(vertexes);

Parameters

shaderProgram Passing nullptr uses the default.

◆ setPos()

template<class Vect >

void setPos ( Vect p )

inline

Definition at line 279 of file Sprite.hpp.

◆ setCenter()

template<class Vect >

void setCenter ( Vect c )

inline

Definition at line 285 of file Sprite.hpp.

◆ setTextureFilter()

void setTextureFilter	(	TextureFilter	minification,
		TextureFilter	magnification )

Sets how the texture is sampled when the sprite is drawn smaller than its pixel size (minification) and bigger (magnification).

With mipmaps, minification also says how they're sampled. All sprites of the same texture, e.g. of the same file, share this.

Member Data Documentation

◆ loader

std::shared_ptr<Finally> loader

Function which actually loads the sprite.

Definition at line 274 of file Sprite.hpp.

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

jngl/Sprite.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Enumeration Documentation

◆ LoadType

Constructor & Destructor Documentation

◆ Sprite() [1/4]

◆ Sprite() [2/4]

◆ Sprite() [3/4]

◆ Sprite() [4/4]

Member Function Documentation

◆ draw() [1/3]

◆ draw() [2/3]

◆ drawLerped()

◆ draw() [3/3]

◆ batch()

◆ drawScaled()

◆ drawClipped()

◆ drawMesh()

◆ setPos()

◆ setCenter()

◆ setTextureFilter()

Member Data Documentation

◆ loader