gdl::Texture Class Reference

Texture handling class. More...

#include <mgdl-wii-texture.h>

Public Member Functions
	Texture ()
	Constructor.
virtual	~Texture ()
	Deconstructor.
bool	Create (short xSize, short ySize, u_int filterMode, u_int format)
	Creates a texture image.
bool	CreateMipmapped (short xSize, short ySize, u_int minFilt, u_int magFilt, short maxMipmaps, u_int format)
	Creates a mipmapped texture image.
bool	LoadTexture (const char *fileName)
	Loads a TPL texture file generated by gxtexconv.
bool	ConvertRawImage (short rawXres, short rawYres, void *rawBuff, short srcFormat)
	Converts raw image data into a texture.
void	CopyFromScreen (short x, short y, short width, short height, u_char clearScreen)
	Copies pixel data from the active framebuffer.
void	Delete ()
	Deletes the texture (but not the object itself).
void	Flush ()
	Flushes the texture's data block.
void	SetFilterMode (u_int minFilt, u_int magFilt)
	Sets filter modes to a texture.
void	SetWrapMode (u_int wrap_s, u_int wrap_t)
	Sets the wrapping strategy of the texture.
void	PokePixel (short x, short y, u_int col)
	Pokes a pixel into the texture.
u_int	PeekPixel (short x, short y)
	Peeks a pixel from the texture.
void *	TexAddr ()
	Returns the pointer to the texture data block.
u_int	TexSize ()
	Returns the size of the texture data in bytes.
short	TexFmt ()
	Returns the texture format index of the texture.
GXTexObj *	TexObj ()
	Returns a pointer to the GXTexObj object of the texture.
short	TXsize ()
	Returns the X size of the texture in pixels.
short	TYsize ()
	Returns the Y size of the texture in pixels.

Detailed Description

Texture handling class.

This class is used for conveniently handling textures for storing 2D graphics data such as images, sprites and textures. These are used by the library in image and sprite set classes and can be used by itself to ease loading and converting of textures when developing custom graphics engines.

Member Function Documentation

ConvertRawImage()

bool Texture::ConvertRawImage	(	short	rawXres,
		short	rawYres,
		void *	rawBuff,
		short	srcFormat
	)

Converts raw image data into a texture.

Converts raw image data into an appropriate texture format specified by gdl::Texture::Create() or gdl::Texture::CreateMipmapped(). If the texture is created with gdl::Texture::CreateMipmapped(), the function will generate mipmaps internally.

Note

If rawXres and rawYres are lower than the created size of the texture, it is automatically padded out with black (or transparent if the texture format has an alpha channel except gdl::RGB5A3).

The texture must already be created with gdl::Texture::Create() or gdl::Texture::CreateMipmapped() first.

If the texture is mipmapped, the function would take a bit more time to finish conversion as it had to generate mipmaps.

Parameters

[in]	rawXres	X size of raw image data in pixels.
[in]	rawYres	Y size of raw image data in pixels.
[in]	*rawBuff	Pointer to raw image data.
[in]	srcFormat	Format of raw image data (see gdl::ColorFormats).

CopyFromScreen()

void Texture::CopyFromScreen	(	short	x,
		short	y,
		short	width,
		short	height,
		u_char	clearScreen
	)

Copies pixel data from the active framebuffer.

This function copies pixels from the active framebuffer to be used as a texture which is useful for doing render-to-texture based effects. Take note that the range at which you can capture depends on the current video mode that the system is running on and is best to take into account of the actual framebuffer resolution using the variables gdl::wii::rmode->fbWidth and gdl::wii::rmode->efbHeight.

Note

The texture must already be created with gdl::Texture::Create().

This function is GPU intensive which means calling this function too many times will cause a big performance drop.

The copy region offset and size is specified in framebuffer pixels which means that the specified resolution is always relative to the actual resolution from gdl::wii::rmode and is never affected by the current projection matrix.

Parameters

[in]	x	X offset of screen to copy from in framebuffer pixels.
[in]	y	Y offset of screen to copy from in framebuffer pixels.
[in]	width	Width of copy region in framebuffer pixels.
[in]	height	Height of copy region in framebuffer pixels.
[in]	clearScreen	If true, the framebuffer is cleared after copying.

Create()

bool Texture::Create	(	short	xSize,
		short	ySize,
		u_int	filterMode,
		u_int	format
	)

Creates a texture image.

Creates a memory buffer for storing texture data.

Note

The size of the texture must be a multiple of 4 in both dimensions and must not be greater than 1024 pixels as that is the maximum texture resolution the GX can handle.

If the texture is already created, it is simply reallocated but it is not recommended to keep recreating the texture to prevent too much memory fragmentation.

Parameters

[in]	xSize	X size of texture in pixels.
[in]	ySize	Y size of texture in pixels.
[in]	filterMode	Filtering mode (see gdl::TextureFilterModes).
[in]	format	Texture format (see gdl::TextureFormatModes).

Returns

Non-zero if the texture had been created successfully otherwise there is not enough free memory to create the texture buffer.

CreateMipmapped()

bool Texture::CreateMipmapped	(	short	xSize,
		short	ySize,
		u_int	minFilt,
		u_int	magFilt,
		short	maxMipmaps,
		u_int	format
	)

Creates a mipmapped texture image.

Unlike gdl::Texture::Create(), this function creates a mipmapped texture buffer which improves rendering quality (and in some cases performance) when the texture is drawn smaller than its original resolution. It is recommended to use mipmapped textures for large 3D geometry or images that get scaled up or down immensely and you don't want it to look all jagged and pixelated when it gets small enough.

Note

Unlike non-mipmapped textures which can be of any size as long as its a multiple of 4x4 pixels, mipmapped textures however must be a power of two to work correctly.

Mipmapped textures take up roughly 33% more memory (with 9 mipmap levels) than that of a non mipmapped texture so you must determine the number of mipmaps necessary to generate such as if the image doesn't get downscaled so much, a single mipmap level is good enough for it. Using texture formats that are of a lower color depth such as gdl::RGB565 or gdl::RGB5A3 will help as well with a slight loss of color definition.

The smallest mipmap resolution the library will allow is 4x4 pixels (same size as a texture block) so a maximum of 9 mipmaps can be generated from a 1024x1024 texture image. If the texture is too small to reach the specified number of maximum mipmaps, it will simply generate less mipmaps than that specified.

By default, mipmaped textures are set to have an anisotropy level of 4 and edge LOD computation enabled for the best (but most intensive) mipmapping quality. You can change these using GX commands and the gdl::Texture::TexObj() function to retrieve the GXTexObj struct of the texture.

Parameters

[in]	xSize	X size of texture in pixels.
[in]	ySize	Y size of texture in pixels.
[in]	minFilt	Filtering mode when texture is drawn less than the original resolution (see gdl::TextureFilterModes).
[in]	magFilt	Filtering mode when texture is drawn higher than the original resolution (see gdl::TextureFilterModes).
[in]	maxMipmaps	Number of mipmaps to generate.
[in]	format	Texture format (see gdl::TextureFormatModes).

Returns

Non-zero if the texture had been allocated successfully otherwise there is not enough free memory to create the texture.

Delete()

void Texture::Delete

(

)

Deletes the texture (but not the object itself).

This function deallocates the texture data block associated to it and resets various parameters of the texture to 0.

Note

It is unnecessary to call this function before deconstructing the object as the texture is automatically freed upon deconstruction... It is implemented for certain purposes.

Flush()

void Texture::Flush

(

)

Flushes the texture's data block.

If gdl::SetAutoFlush() is set to false, you must call this function whenever you modify the contents of the texture data block otherwise, the changes will not take effect or it will initially appear as corrupted blocks.

LoadTexture()

bool Texture::LoadTexture

(

const char *

fileName

)

Loads a TPL texture file generated by gxtexconv.

This function loads a texture from a TPL texture file. TPL actually stands for Texture PaLette as the file format can contain multiple textures at once. However, this function only supports single texture TPL files currently. If the texture has mipmaps, trilinear mipmap filtering is set.

Note

The texture does not need to be created first when loading a TPL file.

TPL files are best used for handling textures in special formats which are not supported by the library such as DXT1 compressed textures. However, Color Index textures are not supported.

Parameters

[in]

fileName

File name of TPL texture file to load.

Returns

Non-zero if the texture was successfully loaded otherwise an error occured.

PeekPixel()

u_int Texture::PeekPixel	(	short	x,
		short	y
	)

Peeks a pixel from the texture.

Peeks a pixel from the texture for generating things from images

Note

This function is only effective on non-mipmapped and non-specialty format textures.

If you peek a pixel from an I4/I8 format texture, the color value will be only be in a range from 0 to 255. If the texture is an IA4/IA8, use the IA() color macro.

Parameters

[in]	x	X offset of pixel to read.
[in]	y	Y offset of pixel to read.

Returns

Color of pixel (use the RGBA() or IA() macros for this).

PokePixel()

void Texture::PokePixel	(	short	x,
		short	y,
		u_int	col
	)

Pokes a pixel into the texture.

Pokes a pixel into a texture useful for procedurally generating textures easily.

Note

This function is only effective on non-mipmapped and non-specialty format textures. Also, pixels drawn outside the texture are simply clipped.

If gdl::SetAutoFlush() is set to true (false by default), this function will perform a lot slower when doing a lot of texture changes. For best performance, set gdl::SetAutoFlush() to false and call gdl::Texture::Flush() after doing such changes.

If you poke a pixel to an I4/I8 format texture, the color value must only be a range from 0 to 255. If the texture is an IA4/IA8, use the IA() color macro.

Parameters

[in]	x	X offset of pixel to draw to.
[in]	y	Y offset of pixel to draw to.
[in]	col	Color of pixel (use the RGBA() or IA() macros for this).

SetFilterMode()

void Texture::SetFilterMode	(	u_int	minFilt,
		u_int	magFilt
	)

Sets filter modes to a texture.

Note

magFilt can only be either gdl::Nearest or gdl::Linear.

Parameters

[in]	minFilt	Filter mode when texture is < 1.0 of original size (see gdl::TextureFilterModes for more filter modes).
[in]	magFilt	Filter mode when texture is >= 1.0 of original size.

SetWrapMode()

void Texture::SetWrapMode	(	u_int	wrap_s,
		u_int	wrap_t
	)

Sets the wrapping strategy of the texture.

Parameters

[in]	wrap_s	Texture wrapping strategy in the S (or U) direction (see gdl::TextureWrapModes).
[in]	wrap_t	Texture wrapping strategy in the T (or V) direction (see gdl::TextureWrapModes).

TexAddr()

void * Texture::TexAddr

(

)

Returns the pointer to the texture data block.

Note

If you modify the contents of the memory block, you must flush it either with gdl::Texture::Flush() or DCFlushRange().

The pointer is always aligned in 32 byte increments.

Returns

Pointer to texture data (NULL if texture has not yet been created).

TexFmt()

short Texture::TexFmt

(

)

Returns the texture format index of the texture.

Returns

Texture format (see gdl::TextureFormatModes).

TexObj()

GXTexObj * Texture::TexObj

(

)

Returns a pointer to the GXTexObj object of the texture.

Useful if you want to set the texture with GX_LoadTexObj() to be used as your current texture object.

Returns

Pointer to a GXTexObj object, NULL if texture is not yet created.

TexSize()

u_int Texture::TexSize

(

)

Returns the size of the texture data in bytes.

Returns

Size of texture data in bytes (0 if texture is not yet created).

TXsize()

short Texture::TXsize

(

)

Returns the X size of the texture in pixels.

Returns

X size of texture in pixels, 0 if texture is not yet created.

TYsize()

short Texture::TYsize

(

)

Returns the Y size of the texture in pixels.

Returns

Y size of texture in pixels, 0 if texture is not yet created.

---

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

• include/mgdl/wii/mgdl-wii-texture.h
• source/wii/wii-texture.cpp