#include <CUImage.h>

Inheritance diagram for cugl::graphics::Image:

Public Member Functions
	Image ()

	~Image ()

void	dispose ()

bool	init (Uint32 width, Uint32 height, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE)

bool	initWithData (const std::byte *data, Uint32 width, Uint32 height, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

bool	initWithFile (const std::string filename, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

ImageData *	getImplementation ()

const Image &	operator= (const std::byte *data)

const Image &	set (const std::byte *data)

const Image &	set (const std::vector< std::byte > &data)

const size_t	get (std::vector< std::byte > &data)

bool	save (const std::string file)

void	setName (std::string name)

const std::string	getName () const

size_t	id () const

ImageAccess	getAccess () const

Uint32	getWidth () const

Uint32	getHeight () const

Size	getSize ()

size_t	getByteSize () const

TexelFormat	getFormat () const

bool	isPremultiplied () const

void	setPremultiplied (bool value)

bool	hasMipMaps () const

std::string	toString (bool verbose=false) const

	operator std::string () const

const std::shared_ptr< Image > &	getParent () const

std::shared_ptr< Image >	getParent ()

std::shared_ptr< Image >	getSubImage (Uint32 x, Uint32 y, Uint32 w, Uint32 h)

bool	isSubImage () const

Uint32	getX () const

Uint32	getY () const

Vec2	getOrigin () const

float	getMinS () const

float	getMinT () const

float	getMaxS () const

float	getMaxT () const

Static Public Member Functions
static std::shared_ptr< Image >	alloc (Uint32 width, Uint32 height, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE)

static std::shared_ptr< Image >	allocWithData (const std::byte *data, Uint32 width, Uint32 height, TexelFormat format=TexelFormat::COLOR_RGBA, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

static std::shared_ptr< Image >	allocWithFile (const std::string filename, ImageAccess access=ImageAccess::READ_WRITE, bool mipmaps=false)

static Uint32	getMaximumSize ()

Protected Attributes
std::string	_name

Uint32	_originx

Uint32	_originy

Uint32	_width

Uint32	_height

bool	_premult

ImageData *	_data

ImageAccess	_access

TexelFormat	_format

bool	_mipmaps

std::shared_ptr< Image >	_parent
	Image atlas support.

float	_minS

float	_maxS

float	_minT

float	_maxT

Detailed Description

This is a class representing an image.

This class represents a single 2d image, which is a rectangular collection of texels. The color format for these texels is determined by the value TexelFormat.

Historically, many game engines treat images and textures as the same thing. However, this is not the case in Vulkan and modern graphics APIs, where a texture is actually an image plus a sampler. To maximize compatibility with Vulkan, we have split textures into this class and the class Sampler.

An image stores the pixel information for a texture, but does not specify how to resize it or how to handle texture coordinates that are out-of-bounds. Note that in Vulkan, a texture must explicitly specify the number of mipmap levels, while this value is implicit in OpenGL. Our interface assumes that all OpenGL textures with mipmap level > 0 are the same.

Because this class stores the image information for a Texture, this class is also where we provide support for atlases. An atlas allows us to carve an image up into smaller subimages. A subimage wraps the same image data (and so does not require a context switch in the rendering pipeline), but has different start and end boundaries, as defined by getMinS, getMaxS, getMinT, and getMaxT. See getSubImage for more information.

Note that we talk about texture coordinates in terms of S (horizontal) and T (vertical). This is different from other implementations that use UV instead.

Images can only be constructed on the main thread when using OpenGL. However, in Vulkan, images can be safely constructed on any thread.

Constructor & Destructor Documentation

◆ Image()

cugl::graphics::Image::Image ( )

Creates a new empty image with no size.

This method performs no allocations. You must call init to generate a proper image.

◆ ~Image()

cugl::graphics::Image::~Image ( )

inline

Deletes this image, disposing all resources

Member Function Documentation

◆ alloc()

static std::shared_ptr< Image > cugl::graphics::Image::alloc	(	Uint32	width,
		Uint32	height,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`
	)

inlinestatic

Returns a new empty image with the given dimensions.

The image will have all of its texels set to 0. It will not support mipmaps. You should use allocWithData for mipmap support.

Parameters

width	The image width in texels
height	The image height in texels
format	The image data format
access	The image access

Returns: a new empty image with the given dimensions.

◆ allocWithData()

static std::shared_ptr< Image > cugl::graphics::Image::allocWithData	(	const std::byte *	data,
		Uint32	width,
		Uint32	height,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

inlinestatic

Returns a new image with the given data.

The data format must match the one specified by the format parameter. If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

This initializer assumes that alpha is not premultiplied. You should call setPremultiplied if this is not the case.

Parameters

data	The image data (size widthheightformat)
width	The image width in pixels
height	The image height in pixels
format	The image data format
access	The image access
mipmaps	A flag to generate mipmaps

Returns: a new image with the given data.

◆ allocWithFile()

static std::shared_ptr< Image > cugl::graphics::Image::allocWithFile	(	const std::string	filename,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

inlinestatic

Returns a new image with the data from the given file.

This method can load any file format supported by SDL_Image. This includes (but is not limited to) PNG, JPEG, GIF, TIFF, BMP and PCX. The image will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG). Because of how SDL3 processes image files, any image loaded this way will have premultiplied alpha.

If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

If the file path is relative, it is assumed to be with respect to Application#getAssetDirectory. If you wish to load an image from somewhere else, you must use an absolute path.

Parameters

filename	The file supporting the texture file.
access	The image access
mipmaps	A flag to generate mipmaps

Returns: a new image with the given data

◆ dispose()

void cugl::graphics::Image::dispose ( )

Deletes the image and resets all attributes.

You must reinitialize the image to use it.

◆ get()

const size_t cugl::graphics::Image::get ( std::vector< std::byte > & data )

Fills the given buffer with data from this texture.

This method will append the data to the given vector. This method will fail if the access does not support CPU-side reads.

Parameters

data	The buffer to store the texture data

Returns: the number of bytes read into the buffer

◆ getAccess()

ImageAccess cugl::graphics::Image::getAccess ( ) const

inline

Returns the access policy of this image

Returns: the access policy of this image

◆ getByteSize()

size_t cugl::graphics::Image::getByteSize ( ) const

Returns the number of bytes in a single texel of this image.

Returns: the number of bytes in a single texel of this image.

◆ getFormat()

TexelFormat cugl::graphics::Image::getFormat ( ) const

inline

Returns the data format of this image.

The data format determines what type of data can be assigned to this image.

Returns: the data format of this image.

◆ getHeight()

Uint32 cugl::graphics::Image::getHeight ( ) const

inline

Returns the height of this image in texels.

Returns: the height of this image in texels.

◆ getImplementation()

ImageData * cugl::graphics::Image::getImplementation ( )

inline

Returns the platform-specific implementation for this image

The value returned is an opaque type encapsulating the information for either OpenGL or Vulkan.

Returns: the platform-specific implementation for this image

◆ getMaximumSize()

static Uint32 cugl::graphics::Image::getMaximumSize ( )

static

Returns the maximum image size (per dimension) for this platform

This value is useful for when we want to allocate an image buffer and want to make sure we do not exceed the platform limitations

Returns: the maximum image size (per dimension) for this platform

◆ getMaxS()

float cugl::graphics::Image::getMaxS ( ) const

inline

Returns the maximum horizontal texture coordinate for this image.

When rescaling texture coordinates for a subimage, this value is used in place of 1.

Returns: the maximum horizontal texture coordinate for this image.

◆ getMaxT()

float cugl::graphics::Image::getMaxT ( ) const

inline

Returns the maximum vertical texture coordinate for this image.

When rescaling texture coordinates for a subimage, this value is used in place of 1.

Returns: the maximum vertical texture coordinate for this image.

◆ getMinS()

float cugl::graphics::Image::getMinS ( ) const

inline

Returns the minimum horizontal texture coordinate for this image.

When rescaling texture coordinates for a subimage, this value is used in place of 0.

Returns: the minimum horizontal texture coordinate for this image.

◆ getMinT()

float cugl::graphics::Image::getMinT ( ) const

inline

Returns the minimum vertical texture coordinate for this image.

When rescaling texture coordinates for a subimage, this value is used in place of 0.

Returns: the minimum vertical texture coordinate for this image.

◆ getName()

const std::string cugl::graphics::Image::getName ( ) const

inline

Returns the name of this image.

A name is a user-defined way of identifying a image.

Returns: the name of this image.

◆ getOrigin()

Vec2 cugl::graphics::Image::getOrigin ( ) const

inline

Returns the origin texel.

If this is not a subimage, this method returns the origin (0,0). Otherwise, this method returns the bottom left corner of the subimage region.

Returns: the y-coordinate of the origin texel.

◆ getParent() [1/2]

std::shared_ptr< Image > cugl::graphics::Image::getParent ( )

inline

Returns the parent image of this subimage.

This method will return nullptr is this is not a subimage.

Returns the parent image of this subtexture.

◆ getParent() [2/2]

const std::shared_ptr< Image > & cugl::graphics::Image::getParent ( ) const

inline

Returns the parent image of this subimage.

This method will return nullptr is this is not a subimage.

Returns the parent image of this subtexture.

◆ getSize()

Size cugl::graphics::Image::getSize ( )

inline

Returns the size of this image in texels.

Returns: the size of this image in texels.

◆ getSubImage()

std::shared_ptr< Image > cugl::graphics::Image::getSubImage	(	Uint32	x,
		Uint32	y,
		Uint32	w,
		Uint32	h
	)

Returns a subimage with the given dimensions.

The values x,y,w, and h must specify a subrectangle inside of the image. All values are in texels. In defining this rectangle, we put the origin in the bottom left corner. Positive y values go up the image from the bottom.

It is the responsibility of the user to rescale the texture coordinates of a mesh when using a subimage. Otherwise, the graphics pipeline will just use the original image instead. See the method internal method SpriteBatch#prepare for an example of how to scale texture coordinates.

It is possible to make a subimage of a subimage. However, in that case, the parent of the new subimage will be the original root image. So no tree of subtextures is more than one level deep.

Parameters

x	The x-coordinate of the bottom left in texels
y	The y-coordinate of the bottom left in texels
w	The region width in texels
h	The region height in texels

Returns: a subimage with the given dimensions.

◆ getWidth()

Uint32 cugl::graphics::Image::getWidth ( ) const

inline

Returns the width of this image in texels.

Returns: the width of this image in texels.

◆ getX()

Uint32 cugl::graphics::Image::getX ( ) const

inline

Returns the x-coordinate of the origin texel.

If this is not a subimage, this method returns 0. Otherwise, this method is defined by the origin of the subimage region.

Returns: the x-coordinate of the origin texel.

◆ getY()

Uint32 cugl::graphics::Image::getY ( ) const

inline

Returns the y-coordinate of the origin texel.

If this is not a subimage, this method returns 0. Otherwise, this method is defined by the origin of the subimage region.

Returns: the y-coordinate of the origin texel.

◆ hasMipMaps()

bool cugl::graphics::Image::hasMipMaps ( ) const

inline

Returns whether this image has generated mipmaps.

This method will not indicate the number of mipmap levels in Vulkan. Instead, it treats mipmaps as all-or-nothing (like OpenGL).

Returns: whether this image has generated mipmaps.

◆ id()

size_t cugl::graphics::Image::id ( ) const

Returns a unique identifier for this image

This value can be used in memory-based hashes.

Returns: a unique identifier for this image

◆ init()

bool cugl::graphics::Image::init	(	Uint32	width,
		Uint32	height,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`
	)

inline

Initializes an empty image with the given dimensions.

The image will have all of its texels set to 0. It will not support mipmaps. You should use initWithData for mipmap support.

Parameters

width	The image width in texels
height	The image height in texels
format	The image data format
access	The image access

Returns: true if initialization was successful.

◆ initWithData()

bool cugl::graphics::Image::initWithData	(	const std::byte *	data,
		Uint32	width,
		Uint32	height,
		TexelFormat	format = `TexelFormat::COLOR_RGBA`,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

Initializes an image with the given data and access.

The data format must match the one specified by the format parameter. If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

This initializer assumes that alpha is not premultiplied. You should call setPremultiplied if this is not the case.

Parameters

data	The image data (size widthheightformat)
width	The image width in pixels
height	The image height in pixels
format	The image data format
access	The image access
mipmaps	A flag to generate mipmaps

Returns: true if initialization was successful.

◆ initWithFile()

bool cugl::graphics::Image::initWithFile	(	const std::string	filename,
		ImageAccess	access = `ImageAccess::READ_WRITE`,
		bool	mipmaps = `false`
	)

Initializes an image with the data from the given file.

This method can load any file format supported by SDL_Image. This includes (but is not limited to) PNG, JPEG, GIF, TIFF, BMP and PCX. The image will be stored in RGBA format, even if it is a file format that does not support transparency (e.g. JPEG). Because of how SDL3 processes image files, any image loaded this way will have premultiplied alpha.

If the parameter mipmaps is true, the image will generate an appropriate number of mipmaps determined by its size.

If the file path is relative, it is assumed to be with respect to Application#getAssetDirectory. If you wish to load an image from somewhere else, you must use an absolute path.

Parameters

filename	The file supporting the texture file.
access	The image access
mipmaps	A flag to generate mipmaps

Returns: true if initialization was successful.

◆ isPremultiplied()

bool cugl::graphics::Image::isPremultiplied ( ) const

inline

Returns true if this image uses premultiplied alpha.

Changing this value does not actually change the image data. It only changes how the image is interpretted by the graphics backend.

By default, this value is true if the image was read from a file (because of how SDL3 processes image files) and false otherwise.

Returns: true if this image uses premultiplied alpha.

◆ isSubImage()

bool cugl::graphics::Image::isSubImage ( ) const

inline

Returns true if this image is a subimage.

This method is the same as checking if the parent is not nullptr.

Returns: true if this image is a subimage.

◆ operator std::string()

cugl::graphics::Image::operator std::string ( ) const

inline

Casts from Image to a string.

◆ operator=()

const Image & cugl::graphics::Image::operator= ( const std::byte * data )

inline

Sets this image to have the contents of the given buffer.

The buffer must have the correct data format. In addition, the buffer must be size width*height*bytesize. See getByteSize for a description of the latter.

Note that some images created by CUGL are read-only. For any such images, this method will fail.

Parameters

data	The buffer to read into the image

Returns: a reference to this (modified) image for chaining.

◆ save()

bool cugl::graphics::Image::save ( const std::string file )

Returns true if able to save the image to the given file.

The image will be saved as a PNG file. If the suffix of file is not a .png, then this suffix will be added.

This method will fail if the access does not support CPU-side reads.

IMPORTANT: In CUGL, relative path names always refer to the asset directory, which is a read-only directory. Therefore, the file must must be specified with an absolute path. Using a relative path for this method will cause this method to fail.

Parameters

file	The name of the file to write to

Returns: true if able to save the image to the given file.

◆ set() [1/2]

const Image & cugl::graphics::Image::set ( const std::byte * data )

Sets this image to have the contents of the given buffer.

The buffer must have the correct data format. In addition, the buffer must be size width*height*bytesize. See getByteSize for a description of the latter.

This method will fail if the access does not support CPU-side writes.

Parameters

data	The buffer to read into the image

Returns: a reference to this (modified) image for chaining.

◆ set() [2/2]

const Image & cugl::graphics::Image::set ( const std::vector< std::byte > & data )

inline

Sets this image to have the contents of the given buffer.

The buffer must have the correct data format. In addition, the buffer must be size width*height*bytesize. See getByteSize for a description of the latter.

This method will fail if the access does not support CPU-side writes.

Parameters

data	The buffer to read into the image

Returns: a reference to this (modified) image for chaining.

◆ setName()

void cugl::graphics::Image::setName ( std::string name )

inline

Sets the name of this image.

A name is a user-defined way of identifying a image.

Parameters

name	The name of this image.

◆ setPremultiplied()

void cugl::graphics::Image::setPremultiplied ( bool value )

inline

Sets whether this image uses premultiplied alpha.

Changing this value does not actually change the image data. It only changes how the image is interpretted by the graphics backend.

By default, this value is true if the image was read from a file (because of how SDL3 processes image files) and false otherwise.

Parameters

value Whether this image uses premultiplied alpha.

◆ toString()

std::string cugl::graphics::Image::toString ( bool verbose = false ) const

Returns a string representation of this image for debugging purposes.

If verbose is true, the string will include class information. This allows us to unambiguously identify the class.

Parameters

verbose Whether to include class information

Returns: a string representation of this image for debugging purposes.

Member Data Documentation

◆ _access

ImageAccess cugl::graphics::Image::_access

protected

The access for this image

◆ _data

ImageData* cugl::graphics::Image::_data

protected

The graphics API image data

◆ _format

TexelFormat cugl::graphics::Image::_format

protected

The pixel format of the image

◆ _height

Uint32 cugl::graphics::Image::_height

protected

The height in texels

◆ _maxS

float cugl::graphics::Image::_maxS

protected

The image max S (used for image atlases)

◆ _maxT

float cugl::graphics::Image::_maxT

protected

The image max T (used for image atlases)

◆ _minS

float cugl::graphics::Image::_minS

protected

The image min S (used for image atlases)

◆ _minT

float cugl::graphics::Image::_minT

protected

The image min T (used for image atlases)

◆ _mipmaps

bool cugl::graphics::Image::_mipmaps

protected

Whether this image has associated mipmaps

◆ _name

std::string cugl::graphics::Image::_name

protected

The decriptive name of this image

◆ _originx

Uint32 cugl::graphics::Image::_originx

protected

The horizontal origin of the texture region

◆ _originy

Uint32 cugl::graphics::Image::_originy

protected

The vertical origin of the texture region

◆ _parent

std::shared_ptr<Image> cugl::graphics::Image::_parent

protected

Image atlas support.

Our parent, who owns the image (or nullptr if we own it)

◆ _premult

bool cugl::graphics::Image::_premult

protected

Whether the image uses premultiplied alpha

◆ _width

Uint32 cugl::graphics::Image::_width

protected

The width in texels

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

/Users/wmwhite/Developer/CUGL/include/cugl/graphics/CUImage.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Image()

◆ ~Image()

Member Function Documentation

◆ alloc()

◆ allocWithData()

◆ allocWithFile()

◆ dispose()

◆ get()

◆ getAccess()

◆ getByteSize()

◆ getFormat()

◆ getHeight()

◆ getImplementation()

◆ getMaximumSize()

◆ getMaxS()

◆ getMaxT()

◆ getMinS()

◆ getMinT()

◆ getName()

◆ getOrigin()

◆ getParent() [1/2]

◆ getParent() [2/2]

◆ getSize()

◆ getSubImage()

◆ getWidth()

◆ getX()

◆ getY()

◆ hasMipMaps()

◆ id()

◆ init()

◆ initWithData()

◆ initWithFile()

◆ isPremultiplied()

◆ isSubImage()

◆ operator std::string()

◆ operator=()

◆ save()

◆ set() [1/2]

◆ set() [2/2]

◆ setName()

◆ setPremultiplied()

◆ toString()

Member Data Documentation

◆ _access

◆ _data

◆ _format

◆ _height

◆ _maxS

◆ _maxT

◆ _minS

◆ _minT

◆ _mipmaps

◆ _name

◆ _originx

◆ _originy

◆ _parent

◆ _premult

◆ _width