Tex Class Reference

Stores all data describing an image. More...

#include <tex.h>

Classes
struct	MIPLevel

Public Member Functions
	~Tex ()
Status	validate () const
	Is the texture object valid and self-consistent? More...
void	free ()
	free all resources associated with the image and make further use of it impossible. More...
Status	decode (const std::shared_ptr< u8 > &data, size_t data_size)
	decode an in-memory texture file into texture object. More...
Status	encode (const OsPath &extension, DynArray *da)
	encode a texture into a memory buffer in the desired file format. More...
Status	wrap (size_t w, size_t h, size_t bpp, size_t flags, const std::shared_ptr< u8 > &data, size_t ofs)
	store the given image data into a Tex object; this will be as if it had been loaded via tex_load. More...
Status	transform (size_t transforms)
	Change the pixel format. More...
Status	transform_to (size_t new_flags)
	Change the pixel format (2nd version) (note: this is equivalent to Tex::transform(t, t->flags^new_flags). More...
u8 *	get_data ()
	return a pointer to the image data (pixels), taking into account any header(s) that may come before it. More...
const std::vector< MIPLevel > &	GetMIPLevels () const
u32	get_average_color () const
	return the ARGB value of the 1x1 mipmap level of the texture. More...
size_t	img_size () const
	return total byte size of the image pixels. More...

Public Attributes
std::shared_ptr< u8 >	m_Data
	file buffer or image data. More...
size_t	m_DataSize
size_t	m_Ofs
	offset to image data in file. More...
size_t	m_Width
size_t	m_Height
size_t	m_Bpp
size_t	m_Flags
	see TexFlags and "Format Conversion" in docs. More...

Private Member Functions
void	UpdateMIPLevels ()

Private Attributes
std::vector< MIPLevel >	m_MIPLevels

Detailed Description

Stores all data describing an image.

TODO: rename to TextureData.

Constructor & Destructor Documentation

~Tex()

Tex::~Tex ( )

inline

Member Function Documentation

decode()

Status Tex::decode	(	const std::shared_ptr< u8 > &	data,
		size_t	data_size
	)

decode an in-memory texture file into texture object.

FYI, currently BMP, TGA, JPG, JP2, PNG, DDS are supported - but don't rely on this (not all codecs may be included).

Parameters

data	Input data.
data_size	Its size [bytes].

Returns

Status.

encode()

Status Tex::encode	(	const OsPath &	extension,
		DynArray *	da
	)

encode a texture into a memory buffer in the desired file format.

Parameters

extension	(including '.').
da	Output memory array. Allocated here; caller must free it when no longer needed. Invalid unless function succeeds.

Returns

Status

free()

void Tex::free

(

)

free all resources associated with the image and make further use of it impossible.

Returns

Status

get_average_color()

u32 Tex::get_average_color

(

)

const

return the ARGB value of the 1x1 mipmap level of the texture.

Returns

ARGB value (or 0 if texture does not have mipmaps)

get_data()

u8 * Tex::get_data

(

)

return a pointer to the image data (pixels), taking into account any header(s) that may come before it.

Returns

pointer to the data.

GetMIPLevels()

const std::vector< MIPLevel > & Tex::GetMIPLevels ( ) const

inline

img_size()

size_t Tex::img_size

(

)

const

return total byte size of the image pixels.

(including mipmaps!) rationale: this is preferable to calculating manually because it's less error-prone (e.g. confusing bits_per_pixel with bytes).

Returns

size [bytes]

transform()

Status Tex::transform

(

size_t

transforms

)

Change the pixel format.

Parameters

transforms

TexFlags that are to be flipped.

Returns

Status

transform_to()

Status Tex::transform_to

(

size_t

new_flags

)

Change the pixel format (2nd version) (note: this is equivalent to Tex::transform(t, t->flags^new_flags).

Parameters

new_flags

desired new value of TexFlags.

Returns

Status

UpdateMIPLevels()

void Tex::UpdateMIPLevels ( )

private

validate()

Status Tex::validate

(

)

const

Is the texture object valid and self-consistent?

Returns

Status

wrap()

Status Tex::wrap	(	size_t	w,
		size_t	h,
		size_t	bpp,
		size_t	flags,
		const std::shared_ptr< u8 > &	data,
		size_t	ofs
	)

store the given image data into a Tex object; this will be as if it had been loaded via tex_load.

rationale: support for in-memory images is necessary for emulation of glCompressedTexImage2D and useful overall. however, we don't want to provide an alternate interface for each API; these would have to be changed whenever fields are added to Tex. instead, provide one entry point for specifying images. note: since we do not know how <img> was allocated, the caller must free it themselves (after calling tex_free, which is required regardless of alloc type).

we need only add bookkeeping information and "wrap" it in our Tex struct, hence the name.

Parameters

w,h	Pixel dimensions.
bpp	Bits per pixel.
flags	TexFlags.
data	Img texture data. note: size is calculated from other params.
ofs

Returns

Status

Member Data Documentation

m_Bpp

size_t Tex::m_Bpp

m_Data

std::shared_ptr<u8> Tex::m_Data

file buffer or image data.

note: during the course of transforms (which may occur when being loaded), this may be replaced with a new buffer (e.g. if decompressing file contents).

m_DataSize

size_t Tex::m_DataSize

m_Flags

size_t Tex::m_Flags

see TexFlags and "Format Conversion" in docs.

m_Height

size_t Tex::m_Height

m_MIPLevels

std::vector<MIPLevel> Tex::m_MIPLevels

private

m_Ofs

size_t Tex::m_Ofs

offset to image data in file.

this is required since tex_get_data needs to return the pixels, but data returns the actual file buffer. zero-copy load and write-back to file is also made possible.

m_Width

size_t Tex::m_Width

---

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

• /home/docker/jenkins/workspace/technical-docs/source/lib/tex/tex.h
• /home/docker/jenkins/workspace/technical-docs/source/lib/tex/tex.cpp