Pyrogenesis  trunk
Enumerations | Functions
ogl_tex.h File Reference
#include "lib/res/handle.h"
#include "lib/file/vfs/vfs.h"
#include "lib/ogl.h"
#include "lib/tex/tex.h"
Include dependency graph for ogl_tex.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  OglTexQualityFlags { OGL_TEX_FULL_QUALITY = 0x20, OGL_TEX_HALF_BPP = 0x10, OGL_TEX_HALF_RES = 0x01 }
 Quality flags for texture uploads. More...
 
enum  OglTexOverrides { OGL_TEX_S3TC, OGL_TEX_AUTO_MIPMAP_GEN, OGL_TEX_ANISOTROPY }
 
enum  OglTexAllow { OGL_TEX_DISABLE, OGL_TEX_ENABLE }
 

Functions

void ogl_tex_set_defaults (int q_flags, GLint filter)
 Change default settings - these affect performance vs. More...
 
Handle ogl_tex_load (const PIVFS &vfs, const VfsPath &pathname, size_t flags=0)
 Load and return a handle to the texture. More...
 
Handle ogl_tex_find (const VfsPath &pathname)
 Find and return an existing texture object, if it has already been loaded and is still in memory. More...
 
Handle ogl_tex_wrap (Tex *t, const PIVFS &vfs, const VfsPath &pathname, size_t flags=0)
 Make the Tex object ready for use as an OpenGL texture and return a handle to it. More...
 
Status ogl_tex_free (Handle &ht)
 Release this texture reference. More...
 
Status ogl_tex_set_filter (Handle ht, GLint filter)
 Override default filter (see ogl_tex_set_defaults) for this texture. More...
 
Status ogl_tex_set_wrap (Handle ht, GLint wrap_s, GLint wrap_t)
 Override default wrap mode (GL_REPEAT) for this texture. More...
 
Status ogl_tex_set_anisotropy (Handle ht, GLfloat anisotropy)
 Override default maximum anisotropic filtering for this texture. More...
 
void ogl_tex_override (OglTexOverrides what, OglTexAllow allow)
 Override the default decision and force/disallow use of the given feature. More...
 
Status ogl_tex_upload (const Handle ht, GLenum fmt_ovr=0, int q_flags_ovr=0, GLint int_fmt_ovr=0)
 Upload texture to OpenGL. More...
 
Status ogl_tex_get_size (Handle ht, size_t *w, size_t *h, size_t *bpp)
 Retrieve dimensions and bit depth of the texture. More...
 
Status ogl_tex_get_format (Handle ht, size_t *flags, GLenum *fmt)
 Retrieve pixel format of the texture. More...
 
Status ogl_tex_get_data (Handle ht, u8 **p)
 Retrieve pixel data of the texture. More...
 
Status ogl_tex_get_uploaded_size (Handle ht, size_t *size)
 Retrieve number of bytes uploaded for the texture, including mipmaps. More...
 
Status ogl_tex_get_average_color (Handle ht, u32 *p)
 Retrieve ARGB value of 1x1 mipmap level of the texture, i.e. More...
 
Status ogl_tex_bind (Handle ht, size_t unit=0)
 Bind texture to the specified unit in preparation for using it in rendering. More...
 
Status ogl_tex_get_texture_id (Handle ht, GLuint *id)
 Return the GL handle of the loaded texture in *id, or 0 on failure. More...
 
Status ogl_tex_transform (Handle ht, size_t flags)
 (partially) Transform pixel format of the texture. More...
 
Status ogl_tex_transform_to (Handle ht, size_t new_flags)
 Transform pixel format of the texture. More...
 
bool ogl_tex_has_s3tc ()
 Return whether native S3TC texture compression support is available. More...
 
bool ogl_tex_has_anisotropy ()
 Return whether anisotropic filtering support is available. More...
 

Enumeration Type Documentation

Enumerator
OGL_TEX_DISABLE 
OGL_TEX_ENABLE 
Enumerator
OGL_TEX_S3TC 
OGL_TEX_AUTO_MIPMAP_GEN 
OGL_TEX_ANISOTROPY 

Quality flags for texture uploads.

Specify any of them to override certain aspects of the default.

Enumerator
OGL_TEX_FULL_QUALITY 

emphatically require full quality for this texture.

(q_flags are invalid if this is set together with any other bit) rationale: the value 0 is used to indicate "use default flags" in ogl_tex_upload and ogl_tex_set_defaults, so this is the only way we can say "disregard default and do not reduce anything".

OGL_TEX_HALF_BPP 

store the texture at half the normal bit depth (4 bits per pixel component, as opposed to 8).

this increases performance on older graphics cards due to decreased size in vmem. it has no effect on compressed textures because they have a fixed internal format.

OGL_TEX_HALF_RES 

store the texture at half its original resolution.

this increases performance on older graphics cards due to decreased size in vmem. this is useful for also reducing quality of compressed textures, which are not affected by OGL_TEX_HALF_BPP. currently only implemented for images that contain mipmaps (otherwise, we'd have to resample, which is slow). note: scaling down to 1/4, 1/8, .. is easily possible without extra work, so we leave some bits free for that.

Function Documentation

Status ogl_tex_bind ( Handle  ht,
size_t  unit = 0 
)

Bind texture to the specified unit in preparation for using it in rendering.

Parameters
htTexture handle. If 0, texturing is disabled on this unit.
unitTexture Mapping Unit number, typically 0 for the first.
Returns
Status

Side Effects:

  • changes the active texture unit;
  • (if successful) texturing was enabled/disabled on that unit.

Notes:

  • assumes multitexturing is available.
  • not necessary before calling ogl_tex_upload!
  • on error, the unit's texture state is unchanged; see implementation.
Handle ogl_tex_find ( const VfsPath pathname)

Find and return an existing texture object, if it has already been loaded and is still in memory.

Parameters
pathnamefn VFS filename of texture.
Returns
Handle to texture or negative Status
Status ogl_tex_free ( Handle ht)

Release this texture reference.

When the count reaches zero, all of its associated resources are freed and further use made impossible.

Parameters
htTexture handle.
Returns
Status
Status ogl_tex_get_average_color ( Handle  ht,
u32 p 
)

Retrieve ARGB value of 1x1 mipmap level of the texture, i.e.

the average color of the whole texture.

Parameters
htTexture handle
pwill be filled with ARGB value (or 0 if texture does not have mipmaps)
Returns
Status

Must be called before uploading (raises a warning if called afterwards).

Status ogl_tex_get_data ( Handle  ht,
u8 **  p 
)

Retrieve pixel data of the texture.

Parameters
htTexture handle
pwill be filled with pointer to texels.
Returns
Status

Note: this memory is freed after a successful ogl_tex_upload for this texture. After that, the pointer we retrieve is NULL but the function doesn't fail (negative return value) by design. If you still need to get at the data, add a reference before uploading it or read directly from OpenGL (discouraged).

Status ogl_tex_get_format ( Handle  ht,
size_t *  flags,
GLenum *  fmt 
)

Retrieve pixel format of the texture.

Parameters
htTexture handle
flagsoptional; will be filled with TexFlags
fmtoptional; will be filled with GL format (it is determined during ogl_tex_upload and 0 before then)
Returns
Status
Status ogl_tex_get_size ( Handle  ht,
size_t *  w,
size_t *  h,
size_t *  bpp 
)

Retrieve dimensions and bit depth of the texture.

Parameters
htTexture handle
woptional; will be filled with width
hoptional; will be filled with height
bppoptional; will be filled with bits per pixel
Returns
Status
Status ogl_tex_get_texture_id ( Handle  ht,
GLuint *  id 
)

Return the GL handle of the loaded texture in *id, or 0 on failure.

Status ogl_tex_get_uploaded_size ( Handle  ht,
size_t *  size 
)

Retrieve number of bytes uploaded for the texture, including mipmaps.

size will be 0 if the texture has not been uploaded yet.

Parameters
htTexture handle
sizeWill be filled with size in bytes
Returns
Status
bool ogl_tex_has_anisotropy ( )

Return whether anisotropic filtering support is available.

(The anisotropy might still be disabled or overridden by the driver configuration.)

Returns
true if anisotropic filtering supported.

ogl_tex_upload must be called at least once before this.

bool ogl_tex_has_s3tc ( )

Return whether native S3TC texture compression support is available.

If not, textures will be decompressed automatically, hurting performance.

Returns
true if native S3TC supported.

ogl_tex_upload must be called at least once before this.

Handle ogl_tex_load ( const PIVFS vfs,
const VfsPath pathname,
size_t  flags = 0 
)

Load and return a handle to the texture.

Parameters
vfs
pathname
flagsh_alloc flags.
Returns
Handle to texture or negative Status for a list of supported formats, see tex.h's tex_load.
void ogl_tex_override ( OglTexOverrides  what,
OglTexAllow  allow 
)

Override the default decision and force/disallow use of the given feature.

Typically called from ah_override_gl_upload_caps.

Parameters
whatFeature to influence.
allowDisable/enable flag.
Status ogl_tex_set_anisotropy ( Handle  ht,
GLfloat  anisotropy 
)

Override default maximum anisotropic filtering for this texture.

Parameters
htTexture handle
anisotropyAnisotropy value (must not be less than 1.0; should usually be a power of two)
Returns
Status

Must be called before uploading (raises a warning if called afterwards).

void ogl_tex_set_defaults ( int  q_flags,
GLint  filter 
)

Change default settings - these affect performance vs.

quality. May be overridden for individual textures via parameter to ogl_tex_upload or ogl_tex_set_filter, respectively.

Parameters
q_flagsquality flags. Pass 0 to keep the current setting (initially OGL_TEX_FULL_QUALITY), or any combination of OglTexQualityFlags.
filtermag/minification filter. Pass 0 to keep the current setting (initially GL_LINEAR), or any valid OpenGL minification filter.
Status ogl_tex_set_filter ( Handle  ht,
GLint  filter 
)

Override default filter (see ogl_tex_set_defaults) for this texture.

Parameters
htTexture handle
filterOpenGL minification and magnification filter (rationale: see OglTexState)
Returns
Status

Must be called before uploading (raises a warning if called afterwards).

Status ogl_tex_set_wrap ( Handle  ht,
GLint  wrap_s,
GLint  wrap_t 
)

Override default wrap mode (GL_REPEAT) for this texture.

Parameters
htTexture handle
wrap_sOpenGL wrap mode for S coordinates
wrap_tOpenGL wrap mode for T coordinates
Returns
Status

Must be called before uploading (raises a warning if called afterwards).

Status ogl_tex_transform ( Handle  ht,
size_t  flags 
)

(partially) Transform pixel format of the texture.

Parameters
htTexture handle.
flagsthe TexFlags that are to be changed.
Returns
Status
See also
tex_transform

Must be called before uploading (raises a warning if called afterwards).

Status ogl_tex_transform_to ( Handle  ht,
size_t  new_flags 
)

Transform pixel format of the texture.

Parameters
htTexture handle.
new_flagsFlags desired new TexFlags indicating pixel format.
Returns
Status
See also
tex_transform

Must be called before uploading (raises a warning if called afterwards).

Note: this is equivalent to ogl_tex_transform(ht, ht_flags^new_flags).

Status ogl_tex_upload ( const Handle  ht,
GLenum  fmt_ovr = 0,
int  q_flags_ovr = 0,
GLint  int_fmt_ovr = 0 
)

Upload texture to OpenGL.

Parameters
htTexture handle
fmt_ovroptional override for OpenGL format (e.g. GL_RGB), which is decided from bpp / Tex flags
q_flags_ovroptional override for global default OglTexQualityFlags
int_fmt_ovroptional override for OpenGL internal format (e.g. GL_RGB8), which is decided from fmt / q_flags.
Returns
Status.

Side Effects:

  • enables texturing on TMU 0 and binds the texture to it;
  • frees the texel data! see ogl_tex_get_data.
Handle ogl_tex_wrap ( Tex t,
const PIVFS vfs,
const VfsPath pathname,
size_t  flags = 0 
)

Make the Tex object ready for use as an OpenGL texture and return a handle to it.

This will be as if its contents had been loaded by ogl_tex_load.

Parameters
tTexture object.
vfs
pathnamefilename or description of texture. not strictly needed, but would allow h_filename to return meaningful info for purposes of debugging.
flags
Returns
Handle to texture or negative Status

note: because we cannot guarantee that callers will pass distinct "filenames", caching is disabled for the created object. this avoids mistakenly reusing previous objects that share the same comment.

we need only add bookkeeping information and "wrap" it in a resource object (accessed via Handle), hence the name.