Pyrogenesis HEAD
Pyrogenesis, a RTS Engine
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...
 
u8get_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< u8m_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< MIPLevelm_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
dataInput data.
data_sizeIts 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 '.').
daOutput 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
transformsTexFlags 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_flagsdesired 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,hPixel dimensions.
bppBits per pixel.
flagsTexFlags.
dataImg 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: