Pyrogenesis  trunk
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Variables
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