ERR Namespace Reference

Introduction

More...

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
static const Status	H_IDX_INVALID = -120000
static const Status	H_IDX_UNUSED = -120001
static const Status	H_TAG_MISMATCH = -120003
static const Status	H_TYPE_MISMATCH = -120004
static const Status	H_ALREADY_FREED = -120005
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	WHRT_COUNTER_UNSAFE = 140000
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

const Status ERR::_1 = -100101

const Status ERR::_11 = -100111

const Status ERR::_12 = -100112

const Status ERR::_13 = -100113

const Status ERR::_14 = -100114

const Status ERR::_15 = -100115

const Status ERR::_16 = -100116

const Status ERR::_17 = -100117

const Status ERR::_18 = -100118

const Status ERR::_19 = -100119

const Status ERR::_2 = -100102

const Status ERR::_21 = -100121

const Status ERR::_22 = -100122

const Status ERR::_23 = -100123

const Status ERR::_24 = -100124

const Status ERR::_25 = -100125

const Status ERR::_26 = -100126

const Status ERR::_27 = -100127

const Status ERR::_28 = -100128

const Status ERR::_29 = -100129

const Status ERR::_3 = -100103

const Status ERR::_4 = -100104

const Status ERR::_5 = -100105

const Status ERR::_6 = -100106

const Status ERR::_7 = -100107

const Status ERR::_8 = -100108

const Status ERR::_9 = -100109

const Status ERR::ABORTED = -100015

const Status ERR::AGAIN = -100030

const Status ERR::ARCHIVE_UNKNOWN_FORMAT = -110400

const Status ERR::ARCHIVE_UNKNOWN_METHOD = -110401

const Status ERR::CORRUPTED = -100014

const Status ERR::CPU_FEATURE_MISSING = -130000

const Status ERR::CPU_UNKNOWN_OPCODE = -130001

const Status ERR::CPU_UNKNOWN_VENDOR = -130002

const Status ERR::EXCEPTION = -100011

const Status ERR::FAIL = -1

const Status ERR::FILE_ACCESS = -110300

const Status ERR::FILE_NOT_FOUND = -110301

const Status ERR::H_ALREADY_FREED = -120005

static

const Status ERR::H_IDX_INVALID = -120000

static

const Status ERR::H_IDX_UNUSED = -120001

static

const Status ERR::H_TAG_MISMATCH = -120003

static

const Status ERR::H_TYPE_MISMATCH = -120004

static

const Status ERR::INVALID_ALIGNMENT = -100020

const Status ERR::INVALID_FLAG = -100025

const Status ERR::INVALID_HANDLE = -100022

const Status ERR::INVALID_OFFSET = -100021

const Status ERR::INVALID_PARAM = -100026

const Status ERR::INVALID_POINTER = -100023

const Status ERR::INVALID_SIZE = -100024

const Status ERR::INVALID_VERSION = -100027

const Status ERR::IO = -110301

const Status ERR::LIMIT = -100031

const Status ERR::LOGIC = -100010

const Status ERR::NO_MEM = -100033

const Status ERR::NOT_SUPPORTED = -100032

const Status ERR::OS_CPU_RESTRICTED_AFFINITY = -130100

const Status ERR::PATH_CHARACTER_ILLEGAL = -100300

const Status ERR::PATH_CHARACTER_UNSAFE = -100301

const Status ERR::PATH_MIXED_SEPARATORS = -100303

const Status ERR::PATH_NOT_FOUND = -100302

const Status ERR::REENTERED = -100013

const Status ERR::STL_CNT_INVALID = -100502

const Status ERR::STL_CNT_UNKNOWN = -100500

const Status ERR::STL_CNT_UNSUPPORTED = -100501

const Status ERR::STRING_NOT_TERMINATED = -100600

const Status ERR::SYM_CHILD_NOT_FOUND = -100406

const Status ERR::SYM_INTERNAL_ERROR = -100404

const Status ERR::SYM_NESTING_LIMIT = -100407

const Status ERR::SYM_NO_STACK_FRAMES_FOUND = -100400

const Status ERR::SYM_SINGLE_SYMBOL_LIMIT = -100408

const Status ERR::SYM_TYPE_INFO_UNAVAILABLE = -100403

const Status ERR::SYM_UNRETRIEVABLE = -100402

const Status ERR::SYM_UNRETRIEVABLE_STATIC = -100401

const Status ERR::SYM_UNSUPPORTED = -100405

const Status ERR::TEX_COMPRESSED = -120106

const Status ERR::TEX_FMT_INVALID = -120102

const Status ERR::TEX_INCOMPLETE_HEADER = -120101

const Status ERR::TEX_INVALID_COLOR_TYPE = -120103

const Status ERR::TEX_INVALID_LAYOUT = -120105

const Status ERR::TEX_INVALID_SIZE = -120107

const Status ERR::TEX_NOT_8BIT_PRECISION = -120104

const Status ERR::TEX_UNKNOWN_FORMAT = -120100

const Status ERR::TIMED_OUT = -100012

const Status ERR::UTF8_INVALID_UTF8 = -100703

const Status ERR::UTF8_NONCHARACTER = -100702

const Status ERR::UTF8_OUTSIDE_BMP = -100701

const Status ERR::UTF8_SURROGATE = -100700

const Status ERR::VFS_ALREADY_MOUNTED = -110102

const Status ERR::VFS_DIR_NOT_FOUND = -110100

const Status ERR::VFS_FILE_NOT_FOUND = -110101

const Status ERR::WHRT_COUNTER_UNSAFE = 140000