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
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