tex.h File Reference

#include "lib/os_path.h"
#include "lib/file/vfs/vfs_path.h"
#include "lib/allocators/dynarray.h"
#include <vector>

Include dependency graph for tex.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	Tex
	Stores all data describing an image. More...
struct	Tex::MIPLevel

Namespaces
namespace	ERR
namespace	WARN
namespace	INFO

Typedefs
typedef void(*	MipmapCB) (size_t level, size_t level_w, size_t level_h, const u8 *RESTRICT level_data, size_t level_data_size, void *RESTRICT cbData)
	callback function for each mipmap level. More...

Enumerations
enum	TexFlags {   TEX_DXT = 0x7 , DXT1A = 7 , TEX_BGR = 0x08 , TEX_ALPHA = 0x10 ,   TEX_GREY = 0x20 , TEX_BOTTOM_UP = 0x40 , TEX_TOP_DOWN = 0x80 , TEX_ORIENTATION = TEX_BOTTOM_UP|TEX_TOP_DOWN ,   TEX_MIPMAPS = 0x100 , TEX_UNDEFINED_FLAGS = ~0x1FF }
	flags describing the pixel format. More...

Functions
void	tex_set_global_orientation (int orientation)
	Set the orientation to which all loaded images will automatically be converted (excepting file formats that don't specify their orientation, i.e. More...
void	tex_util_foreach_mipmap (size_t w, size_t h, size_t bpp, const u8 *data, int levels_to_skip, size_t data_padding, MipmapCB cb, void *RESTRICT cbData)
	for a series of mipmaps stored from base to highest, call back for each level. More...
bool	tex_is_known_extension (const VfsPath &pathname)
	Is the file's extension that of a texture format supported by tex_load? More...
size_t	tex_hdr_size (const VfsPath &filename)
	return the minimum header size (i.e. More...

Variables
const Status	ERR::TEX_UNKNOWN_FORMAT = -120100
const Status	ERR::TEX_INCOMPLETE_HEADER = -120101
const Status	ERR::TEX_FMT_INVALID = -120102
const Status	ERR::TEX_INVALID_COLOR_TYPE = -120103
const Status	ERR::TEX_NOT_8BIT_PRECISION = -120104
const Status	ERR::TEX_INVALID_LAYOUT = -120105
const Status	ERR::TEX_COMPRESSED = -120106
const Status	ERR::TEX_INVALID_SIZE = -120107
const Status	WARN::TEX_INVALID_DATA = +120108
const Status	INFO::TEX_CODEC_CANNOT_HANDLE = +120109
const int	TEX_BASE_LEVEL_ONLY = -1
	special value for levels_to_skip: the callback will only be called for the base mipmap level (i.e. More...

Typedef Documentation

MipmapCB

typedef void(* MipmapCB) (size_t level, size_t level_w, size_t level_h, const u8 *RESTRICT level_data, size_t level_data_size, void *RESTRICT cbData)

callback function for each mipmap level.

Parameters

level	number; 0 for base level (i.e. 100%), or the first one in case some were skipped.
level_w,level_h	pixel dimensions (powers of 2, never 0)
level_data	the level's texels
level_data_size	[bytes]
cbData	passed through from tex_util_foreach_mipmap.

Enumeration Type Documentation

TexFlags

enum TexFlags

flags describing the pixel format.

these are to be interpreted as deviations from "plain" format, i.e. uncompressed RGB.

Enumerator
TEX_DXT	flags & TEX_DXT is a field indicating compression. if 0, the texture is uncompressed; otherwise, it holds the S3TC type: 1,3,5 or DXT1A. not converted by default - glCompressedTexImage2D receives the compressed data.
DXT1A	we need a special value for DXT1a to avoid having to consider flags & TEX_ALPHA to determine S3TC type. the value is arbitrary; do not rely on it!
TEX_BGR	indicates B and R pixel components are exchanged. depending on flags & TEX_ALPHA or bpp, this means either BGR or BGRA. not converted by default - it's an acceptable format for OpenGL.
TEX_ALPHA	indicates the image contains an alpha channel. this is set for your convenience - there are many formats containing alpha and divining this information from them is hard. (conversion is not applicable here)
TEX_GREY	indicates the image is 8bpp greyscale. this is required to differentiate between alpha-only and intensity formats. not converted by default - it's an acceptable format for OpenGL.
TEX_BOTTOM_UP	flags & TEX_ORIENTATION is a field indicating orientation, i.e. in what order the pixel rows are stored. tex_load always sets this to the global orientation (and flips the image accordingly to match). texture codecs may in intermediate steps during loading set this to 0 if they don't know which way around they are (e.g. DDS), or to whatever their file contains.
TEX_TOP_DOWN
TEX_ORIENTATION
TEX_MIPMAPS	mask indicates the image data includes mipmaps. they are stored from lowest to highest (1x1), one after the other. (conversion is not applicable here)
TEX_UNDEFINED_FLAGS

Function Documentation

tex_hdr_size()

size_t tex_hdr_size

(

const VfsPath &

filename

)

return the minimum header size (i.e.

offset to pixel data) of the file format corresponding to the filename.

rationale: this can be used to optimize calls to tex_write: when allocating the buffer that will hold the image, allocate this much extra and pass the pointer as base+hdr_size. this allows writing the header directly into the output buffer and makes for zero-copy IO.

Parameters

filename

Filename; only the extension (that after '.') is used. case-insensitive.

Returns

size [bytes] or 0 on error (i.e. no codec found).

tex_is_known_extension()

bool tex_is_known_extension

(

const VfsPath &

pathname

)

Is the file's extension that of a texture format supported by tex_load?

Rationale: tex_load complains if the given file is of an unsupported type. this API allows users to preempt that warning (by checking the filename themselves), and also provides for e.g. enumerating only images in a file picker. an alternative might be a flag to suppress warning about invalid files, but this is open to misuse.

Parameters

pathname

Only the extension (starting with '.') is used. case-insensitive.

Returns

bool

tex_set_global_orientation()

void tex_set_global_orientation

(

int

orientation

)

Set the orientation to which all loaded images will automatically be converted (excepting file formats that don't specify their orientation, i.e.

DDS). See "Default Orientation" in docs.

Parameters

orientation

Either TEX_BOTTOM_UP or TEX_TOP_DOWN.

tex_util_foreach_mipmap()

void tex_util_foreach_mipmap	(	size_t	w,
		size_t	h,
		size_t	bpp,
		const u8 *	data,
		int	levels_to_skip,
		size_t	data_padding,
		MipmapCB	cb,
		void *RESTRICT	cbData
	)

for a series of mipmaps stored from base to highest, call back for each level.

Parameters

w,h	Pixel dimensions.
bpp	Bits per pixel.
data	Series of mipmaps.
levels_to_skip	Number of levels (counting from base) to skip, or TEX_BASE_LEVEL_ONLY to only call back for the base image. Rationale: this avoids needing to special case for images with or without mipmaps.
data_padding	Minimum pixel dimensions of mipmap levels. This is used in S3TC images, where each level is actually stored in 4x4 blocks. usually 1 to indicate levels are consecutive.
cb	MipmapCB to call.
cbData	Extra data to pass to cb.

Variable Documentation

TEX_BASE_LEVEL_ONLY

const int TEX_BASE_LEVEL_ONLY = -1

special value for levels_to_skip: the callback will only be called for the base mipmap level (i.e.

100%)