Variables
const Status	SYM_NO_STACK_FRAMES_FOUND = -100400

const Status	SYM_UNRETRIEVABLE_STATIC = -100401

const Status	SYM_UNRETRIEVABLE = -100402

const Status	SYM_TYPE_INFO_UNAVAILABLE = -100403

const Status	SYM_INTERNAL_ERROR = -100404

const Status	SYM_UNSUPPORTED = -100405

const Status	SYM_CHILD_NOT_FOUND = -100406

const Status	SYM_NESTING_LIMIT = -100407

const Status	SYM_SINGLE_SYMBOL_LIMIT = -100408

const Status	STL_CNT_UNKNOWN = -100500

const Status	STL_CNT_UNSUPPORTED = -100501

const Status	STL_CNT_INVALID = -100502

const Status	ARCHIVE_UNKNOWN_FORMAT = -110400

const Status	ARCHIVE_UNKNOWN_METHOD = -110401

const Status	FILE_ACCESS = -110300

const Status	FILE_NOT_FOUND = -110301

const Status	IO = -110301

const Status	VFS_DIR_NOT_FOUND = -110100

const Status	VFS_FILE_NOT_FOUND = -110101

const Status	VFS_ALREADY_MOUNTED = -110102

const Status	PATH_CHARACTER_ILLEGAL = -100300

const Status	PATH_CHARACTER_UNSAFE = -100301

const Status	PATH_NOT_FOUND = -100302

const Status	PATH_MIXED_SEPARATORS = -100303

const Status	STRING_NOT_TERMINATED = -100600

const Status	FAIL = -1

const Status	LOGIC = -100010

const Status	EXCEPTION = -100011

const Status	TIMED_OUT = -100012

const Status	REENTERED = -100013

const Status	CORRUPTED = -100014

const Status	ABORTED = -100015

const Status	INVALID_ALIGNMENT = -100020

const Status	INVALID_OFFSET = -100021

const Status	INVALID_HANDLE = -100022

const Status	INVALID_POINTER = -100023

const Status	INVALID_SIZE = -100024

const Status	INVALID_FLAG = -100025

const Status	INVALID_PARAM = -100026

const Status	INVALID_VERSION = -100027

const Status	AGAIN = -100030

const Status	LIMIT = -100031

const Status	NOT_SUPPORTED = -100032

const Status	NO_MEM = -100033

const Status	_1 = -100101

const Status	_2 = -100102

const Status	_3 = -100103

const Status	_4 = -100104

const Status	_5 = -100105

const Status	_6 = -100106

const Status	_7 = -100107

const Status	_8 = -100108

const Status	_9 = -100109

const Status	_11 = -100111

const Status	_12 = -100112

const Status	_13 = -100113

const Status	_14 = -100114

const Status	_15 = -100115

const Status	_16 = -100116

const Status	_17 = -100117

const Status	_18 = -100118

const Status	_19 = -100119

const Status	_21 = -100121

const Status	_22 = -100122

const Status	_23 = -100123

const Status	_24 = -100124

const Status	_25 = -100125

const Status	_26 = -100126

const Status	_27 = -100127

const Status	_28 = -100128

const Status	_29 = -100129

const Status	CPU_FEATURE_MISSING = -130000

const Status	CPU_UNKNOWN_OPCODE = -130001

const Status	CPU_UNKNOWN_VENDOR = -130002

const Status	OS_CPU_RESTRICTED_AFFINITY = -130100

const Status	TEX_UNKNOWN_FORMAT = -120100

const Status	TEX_INCOMPLETE_HEADER = -120101

const Status	TEX_FMT_INVALID = -120102

const Status	TEX_INVALID_COLOR_TYPE = -120103

const Status	TEX_NOT_8BIT_PRECISION = -120104

const Status	TEX_INVALID_LAYOUT = -120105

const Status	TEX_COMPRESSED = -120106

const Status	TEX_INVALID_SIZE = -120107

const Status	UTF8_SURROGATE = -100700

const Status	UTF8_OUTSIDE_BMP = -100701

const Status	UTF8_NONCHARACTER = -100702

const Status	UTF8_INVALID_UTF8 = -100703

Detailed Description

Introduction

This module allows reading/writing 2d images in various file formats and encapsulates them in Tex objects. It supports converting between pixel formats; this is to an extent done automatically when reading/writing. Provision is also made for flipping all images to a default orientation.

Format Conversion

Image file formats have major differences in their native pixel format: some store in BGR order, or have rows arranged bottom-up. We must balance runtime cost/complexity and convenience for the application (not dumping the entire problem on its lap). That means rejecting really obscure formats (e.g. right-to-left pixels), but converting everything else to uncompressed RGB "plain" format except where noted in enum TexFlags (1).

Note: conversion is implemented as a pipeline: e.g. "DDS decompress + vertical flip" would be done by decompressing to RGB (DDS codec) and then flipping (generic transform). This is in contrast to all<->all conversion paths: that would be much more complex, if more efficient.

Since any kind of preprocessing at runtime is undesirable (the absolute priority is minimizing load time), prefer file formats that are close to the final pixel format.

1) one of the exceptions is S3TC compressed textures. glCompressedTexImage2D requires these be passed in their original format; decompressing would be counterproductive. In this and similar cases, TexFlags indicates such deviations from the plain format.

Default Orientation

After loading, all images (except DDS, because its orientation is indeterminate) are automatically converted to the global row orientation: top-down or bottom-up, as specified by tex_set_global_orientation. If that isn't called, the default is top-down to match Photoshop's DDS output (since this is meant to be the no-preprocessing-required optimized format). Reasons to change it might be to speed up loading bottom-up BMP or TGA images, or to match OpenGL's convention for convenience; however, be aware of the abovementioned issues with DDS.

Rationale: it is not expected that this will happen at the renderer layer (a 'flip all texcoords' flag is too much trouble), so the application would have to do the same anyway. By taking care of it here, we unburden the app and save time, since some codecs (e.g. PNG) can flip for free when loading.

Codecs / IO Implementation

To ease adding support for new formats, they are organized as codecs. The interface aims to minimize code duplication, so it's organized following the principle of "Template Method" - this module both calls into codecs, and provides helper functions that they use.

IO is done via VFS, but the codecs are decoupled from this and work with memory buffers. Access to them is endian-safe.

When "writing", the image is put into an expandable memory region. This supports external libraries like libpng that do not know the output size beforehand, but avoids the need for a buffer between library and IO layer. Read and write are zero-copy.

Variable Documentation

◆ _1

const Status ERR::_1 = -100101

◆ _11

const Status ERR::_11 = -100111

◆ _12

const Status ERR::_12 = -100112

◆ _13

const Status ERR::_13 = -100113

◆ _14

const Status ERR::_14 = -100114

◆ _15

const Status ERR::_15 = -100115

◆ _16

const Status ERR::_16 = -100116

◆ _17

const Status ERR::_17 = -100117

◆ _18

const Status ERR::_18 = -100118

◆ _19

const Status ERR::_19 = -100119

◆ _2

const Status ERR::_2 = -100102

◆ _21

const Status ERR::_21 = -100121

◆ _22

const Status ERR::_22 = -100122

◆ _23

const Status ERR::_23 = -100123

◆ _24

const Status ERR::_24 = -100124

◆ _25

const Status ERR::_25 = -100125

◆ _26

const Status ERR::_26 = -100126

◆ _27

const Status ERR::_27 = -100127

◆ _28

const Status ERR::_28 = -100128

◆ _29

const Status ERR::_29 = -100129

◆ _3

const Status ERR::_3 = -100103

◆ _4

const Status ERR::_4 = -100104

◆ _5

const Status ERR::_5 = -100105

◆ _6

const Status ERR::_6 = -100106

◆ _7

const Status ERR::_7 = -100107

◆ _8

const Status ERR::_8 = -100108

◆ _9

const Status ERR::_9 = -100109

◆ ABORTED

const Status ERR::ABORTED = -100015

◆ AGAIN

const Status ERR::AGAIN = -100030

◆ ARCHIVE_UNKNOWN_FORMAT

const Status ERR::ARCHIVE_UNKNOWN_FORMAT = -110400

◆ ARCHIVE_UNKNOWN_METHOD

const Status ERR::ARCHIVE_UNKNOWN_METHOD = -110401

◆ CORRUPTED

const Status ERR::CORRUPTED = -100014

◆ CPU_FEATURE_MISSING

const Status ERR::CPU_FEATURE_MISSING = -130000

◆ CPU_UNKNOWN_OPCODE

const Status ERR::CPU_UNKNOWN_OPCODE = -130001

◆ CPU_UNKNOWN_VENDOR

const Status ERR::CPU_UNKNOWN_VENDOR = -130002

◆ EXCEPTION

const Status ERR::EXCEPTION = -100011

◆ FAIL

const Status ERR::FAIL = -1

◆ FILE_ACCESS

const Status ERR::FILE_ACCESS = -110300

◆ FILE_NOT_FOUND

const Status ERR::FILE_NOT_FOUND = -110301

◆ INVALID_ALIGNMENT

const Status ERR::INVALID_ALIGNMENT = -100020

◆ INVALID_FLAG

const Status ERR::INVALID_FLAG = -100025

◆ INVALID_HANDLE

const Status ERR::INVALID_HANDLE = -100022

◆ INVALID_OFFSET

const Status ERR::INVALID_OFFSET = -100021

◆ INVALID_PARAM

const Status ERR::INVALID_PARAM = -100026

◆ INVALID_POINTER

const Status ERR::INVALID_POINTER = -100023

◆ INVALID_SIZE

const Status ERR::INVALID_SIZE = -100024

◆ INVALID_VERSION

const Status ERR::INVALID_VERSION = -100027

◆ IO

const Status ERR::IO = -110301

◆ LIMIT

const Status ERR::LIMIT = -100031

◆ LOGIC

const Status ERR::LOGIC = -100010

◆ NO_MEM

const Status ERR::NO_MEM = -100033

◆ NOT_SUPPORTED

const Status ERR::NOT_SUPPORTED = -100032

◆ OS_CPU_RESTRICTED_AFFINITY

const Status ERR::OS_CPU_RESTRICTED_AFFINITY = -130100

◆ PATH_CHARACTER_ILLEGAL

const Status ERR::PATH_CHARACTER_ILLEGAL = -100300

◆ PATH_CHARACTER_UNSAFE

const Status ERR::PATH_CHARACTER_UNSAFE = -100301

◆ PATH_MIXED_SEPARATORS

const Status ERR::PATH_MIXED_SEPARATORS = -100303

◆ PATH_NOT_FOUND

const Status ERR::PATH_NOT_FOUND = -100302

◆ REENTERED

const Status ERR::REENTERED = -100013

◆ STL_CNT_INVALID

const Status ERR::STL_CNT_INVALID = -100502

◆ STL_CNT_UNKNOWN

const Status ERR::STL_CNT_UNKNOWN = -100500

◆ STL_CNT_UNSUPPORTED

const Status ERR::STL_CNT_UNSUPPORTED = -100501

◆ STRING_NOT_TERMINATED

const Status ERR::STRING_NOT_TERMINATED = -100600

◆ SYM_CHILD_NOT_FOUND

const Status ERR::SYM_CHILD_NOT_FOUND = -100406

◆ SYM_INTERNAL_ERROR

const Status ERR::SYM_INTERNAL_ERROR = -100404

◆ SYM_NESTING_LIMIT

const Status ERR::SYM_NESTING_LIMIT = -100407

◆ SYM_NO_STACK_FRAMES_FOUND

const Status ERR::SYM_NO_STACK_FRAMES_FOUND = -100400

◆ SYM_SINGLE_SYMBOL_LIMIT

const Status ERR::SYM_SINGLE_SYMBOL_LIMIT = -100408

◆ SYM_TYPE_INFO_UNAVAILABLE

const Status ERR::SYM_TYPE_INFO_UNAVAILABLE = -100403

◆ SYM_UNRETRIEVABLE

const Status ERR::SYM_UNRETRIEVABLE = -100402

◆ SYM_UNRETRIEVABLE_STATIC

const Status ERR::SYM_UNRETRIEVABLE_STATIC = -100401

◆ SYM_UNSUPPORTED

const Status ERR::SYM_UNSUPPORTED = -100405

◆ TEX_COMPRESSED

const Status ERR::TEX_COMPRESSED = -120106

◆ TEX_FMT_INVALID

const Status ERR::TEX_FMT_INVALID = -120102

◆ TEX_INCOMPLETE_HEADER

const Status ERR::TEX_INCOMPLETE_HEADER = -120101

◆ TEX_INVALID_COLOR_TYPE

const Status ERR::TEX_INVALID_COLOR_TYPE = -120103

◆ TEX_INVALID_LAYOUT

const Status ERR::TEX_INVALID_LAYOUT = -120105

◆ TEX_INVALID_SIZE

const Status ERR::TEX_INVALID_SIZE = -120107

◆ TEX_NOT_8BIT_PRECISION

const Status ERR::TEX_NOT_8BIT_PRECISION = -120104

◆ TEX_UNKNOWN_FORMAT

const Status ERR::TEX_UNKNOWN_FORMAT = -120100

◆ TIMED_OUT

const Status ERR::TIMED_OUT = -100012

◆ UTF8_INVALID_UTF8

const Status ERR::UTF8_INVALID_UTF8 = -100703

◆ UTF8_NONCHARACTER

const Status ERR::UTF8_NONCHARACTER = -100702

◆ UTF8_OUTSIDE_BMP

const Status ERR::UTF8_OUTSIDE_BMP = -100701

◆ UTF8_SURROGATE

const Status ERR::UTF8_SURROGATE = -100700

◆ VFS_ALREADY_MOUNTED

const Status ERR::VFS_ALREADY_MOUNTED = -110102

◆ VFS_DIR_NOT_FOUND

const Status ERR::VFS_DIR_NOT_FOUND = -110100

◆ VFS_FILE_NOT_FOUND

const Status ERR::VFS_FILE_NOT_FOUND = -110101

Variables