Decodes compressed image data (PNG) into a platform-native texture created from it. More...

#include <GuiImageData.h>

Classes
struct	DecodedImage
	CPU-only decode result from decodeToRgba(): raw RGBA8 pixel data that has NOT been uploaded to a platform texture yet. More...

Public Member Functions
	GuiImageData ()
	Constructor.

	GuiImageData (const uint8_t *i, int w=0, int h=0)
	Constructor Converts the PNG format image data to a platform-native texture, allocated and owned by this object.

	GuiImageData (const uint8_t i, uint8_t dst, int maxw=0, int maxh=0)
	Constructor Converts the PNG format image data to a platform-native texture, decoded directly into a caller-supplied buffer.

	GuiImageData (void *t, int w, int h, bool takeOwnership=true)
	Constructor Populates an image directly with an already-created platform-native texture.

	~GuiImageData ()
	Destructor.

bool	reload (const uint8_t *pngData, int maxw=0, int maxh=0)
	Decodes new PNG data into this object's own texture, reusing the existing allocation whenever the platform's ImageRenderer says it can hold the new image instead of freeing and reallocating.

void *	getTexture ()
	Gets the attached platform-native texture.

int	getWidth ()
	Gets the image width.

int	getHeight ()
	Gets the image height.

bool	uploadDecoded (DecodedImage &&decoded)
	Uploads a DecodedImage produced by decodeToRgba() into this object's own texture, reusing the existing allocation whenever ImageRenderer::canReuseTexture() allows (same policy as reload()).

bool	loadClipped (const uint8_t *pngData, int boxW, int boxH, float radius, float inset=0.0f, float offsetX=0.0f, float offsetY=0.0f)
	Decodes PNG data and fits it into a box of a given size, then masks it with a rounded rectangle: the image is centred in the box (never scaled), anything that falls outside the box or the rounded corners is cropped, and the mask edge is anti-aliased.

void	clear ()
	Releases any owned texture and resets this object to the same (empty) state as a default-constructed GuiImageData.

Static Public Member Functions
static void	setDecodeScratch (void *buffer, unsigned int size)
	Sets the scratch buffer that every decode (the PNG-decoding constructors, reload(), decodeToRgba() and loadClipped()) will stage its raw, uncompressed pixel rows into while it runs.

static Mutex &	scratchLock ()

static DecodedImage	decodeToRgba (const uint8_t *pngData, int maxw=0, int maxh=0)
	Decodes a PNG buffer into plain RGBA8 pixels, resizing to fit maxw/maxh the same way the decoding constructors/reload() do.

Protected Attributes
void *	texture
	Attached platform-native texture.

int	height
	Height of image.

int	width
	Width of image.

Detailed Description

Decodes compressed image data (PNG) into a platform-native texture created from it.

Currently designed for use only with PNG files.

Definition at line 16 of file GuiImageData.h.

Constructor & Destructor Documentation

◆ GuiImageData() [1/4]

GuiImageData::GuiImageData ( )

Constructor.

Definition at line 41 of file GuiImageData.cpp.

◆ GuiImageData() [2/4]

GuiImageData::GuiImageData	(	const uint8_t *	i,
		int	w = 0,
		int	h = 0 )

Constructor Converts the PNG format image data to a platform-native texture, allocated and owned by this object.

Parameters

i	Source image data (PNG)
w	Max image width (0 = not set)
h	Max image height (0 = not set)

Definition at line 51 of file GuiImageData.cpp.

◆ GuiImageData() [3/4]

GuiImageData::GuiImageData	(	const uint8_t *	i,
		uint8_t *	dst,
		int	maxw = 0,
		int	maxh = 0 )

Constructor Converts the PNG format image data to a platform-native texture, decoded directly into a caller-supplied buffer.

Parameters

i	Source image data (PNG)
dst	Destination texture buffer, owned by the caller
maxw	Max image width (0 = not set)
maxh	Max image height (0 = not set)

Definition at line 64 of file GuiImageData.cpp.

◆ GuiImageData() [4/4]

GuiImageData::GuiImageData	(	void *	t,
		int	w,
		int	h,
		bool	takeOwnership = true )

Constructor Populates an image directly with an already-created platform-native texture.

Parameters

t	Platform-native texture
w	Image width
h	Image height
takeOwnership	If true (default), this object will destroy `t` when it is destroyed or replaced.

Definition at line 78 of file GuiImageData.cpp.

◆ ~GuiImageData()

GuiImageData::~GuiImageData ( )

Destructor.

Definition at line 88 of file GuiImageData.cpp.

Member Function Documentation

◆ clear()

void GuiImageData::clear ( )

Releases any owned texture and resets this object to the same (empty) state as a default-constructed GuiImageData.

Useful for explicitly freeing GPU memory before the object itself is destroyed.

Definition at line 93 of file GuiImageData.cpp.

◆ decodeToRgba()

GuiImageData::DecodedImage GuiImageData::decodeToRgba	(	const uint8_t *	pngData,
		int	maxw = 0,
		int	maxh = 0 )

static

Decodes a PNG buffer into plain RGBA8 pixels, resizing to fit maxw/maxh the same way the decoding constructors/reload() do.

Parameters

pngData	Source image data (PNG)
maxw	Max image width (0 = not set)
maxh	Max image height (0 = not set)

Returns: a DecodedImage; check valid() before use

Definition at line 132 of file GuiImageData.cpp.

◆ getHeight()

int GuiImageData::getHeight ( )

inline

Gets the image height.

Returns: image height

Definition at line 63 of file GuiImageData.h.

◆ getTexture()

void * GuiImageData::getTexture ( )

inline

Gets the attached platform-native texture.

Returns: opaque texture handle

Definition at line 57 of file GuiImageData.h.

◆ getWidth()

int GuiImageData::getWidth ( )

inline

Gets the image width.

Returns: image width

Definition at line 60 of file GuiImageData.h.

◆ loadClipped()

bool GuiImageData::loadClipped	(	const uint8_t *	pngData,
		int	boxW,
		int	boxH,
		float	radius,
		float	inset = 0.0f,
		float	offsetX = 0.0f,
		float	offsetY = 0.0f )

Decodes PNG data and fits it into a box of a given size, then masks it with a rounded rectangle: the image is centred in the box (never scaled), anything that falls outside the box or the rounded corners is cropped, and the mask edge is anti-aliased.

Replaces this object's texture; its size becomes the box size. Use it for a picture that sits on a code-drawn button, so it can't spill over the button's border or corners.

Parameters

pngData	Source image data (PNG)
boxW	Box width, in design-canvas pixels
boxH	Box height, in design-canvas pixels
radius	Corner radius of the box (clamped to half the shorter side)
inset	Shrinks the mask on every side, eg. to stay inside a stroke
offsetX	Moves the image horizontally from centre (negative = left)
offsetY	Moves the image vertically from centre (negative = up)

Returns: true on success

Definition at line 316 of file GuiImageData.cpp.

◆ reload()

bool GuiImageData::reload	(	const uint8_t *	pngData,
		int	maxw = 0,
		int	maxh = 0 )

Decodes new PNG data into this object's own texture, reusing the existing allocation whenever the platform's ImageRenderer says it can hold the new image instead of freeing and reallocating.

Parameters

pngData	Source image data (PNG)
maxw	Max image width (0 = not set)
maxh	Max image height (0 = not set)

Returns: true on success

Definition at line 123 of file GuiImageData.cpp.

◆ scratchLock()

Mutex & GuiImageData::scratchLock ( )

static

Returns: the mutex guarding the shared decode scratch buffer set by setDecodeScratch() - callers decoding from more than one thread must hold this for the duration of a decode.

Definition at line 36 of file GuiImageData.cpp.

◆ setDecodeScratch()

void GuiImageData::setDecodeScratch	(	void *	buffer,
		unsigned int	size )

static

Sets the scratch buffer that every decode (the PNG-decoding constructors, reload(), decodeToRgba() and loadClipped()) will stage its raw, uncompressed pixel rows into while it runs.

Parameters

buffer	Scratch buffer, owned and sized by the caller
size	Size of buffer, in bytes

Examples: demo.cpp.

Definition at line 30 of file GuiImageData.cpp.

◆ uploadDecoded()

bool GuiImageData::uploadDecoded ( DecodedImage && decoded )

Uploads a DecodedImage produced by decodeToRgba() into this object's own texture, reusing the existing allocation whenever ImageRenderer::canReuseTexture() allows (same policy as reload()).

Must be called on the main/GPU thread.

Parameters

decoded Result of a prior decodeToRgba() call

Returns: true on success

Definition at line 265 of file GuiImageData.cpp.

Member Data Documentation

◆ height

int GuiImageData::height

protected

Height of image.

Definition at line 121 of file GuiImageData.h.

◆ texture

void* GuiImageData::texture

protected

Attached platform-native texture.

Definition at line 120 of file GuiImageData.h.

◆ width

int GuiImageData::width

protected

Width of image.

Definition at line 122 of file GuiImageData.h.

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

source/libgui/GuiImageData.h
source/libgui/GuiImageData.cpp

libgui 3.00 libgui is a GUI library for the GameCube, Wii, and Wii U

Classes

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GuiImageData() [1/4]

◆ GuiImageData() [2/4]

◆ GuiImageData() [3/4]

◆ GuiImageData() [4/4]

◆ ~GuiImageData()

Member Function Documentation

◆ clear()

◆ decodeToRgba()

◆ getHeight()

◆ getTexture()

◆ getWidth()

◆ loadClipped()

◆ reload()

◆ scratchLock()

◆ setDecodeScratch()

◆ uploadDecoded()

Member Data Documentation

◆ height

◆ texture

◆ width