EdenSurfaces

Introduction

Texture loading, selection, and drawing.

Discussion

EdenSurfaces forms one part of the Eden library.

Functions

EdenGLCapabilityCheck: Checks for the presence of an OpenGL capability by version or extension.
EdenGluCheckExtension: Check for the availability of an OpenGL extension.
EdenSurfacesDraw: Draw a texture on a quad using OpenGL.
EdenSurfacesFinal: Finalise the EdenSurfaces library.
EdenSurfacesInit: Initialise the EdenSurfaces library.
EdenSurfacesTextureLoad: Loads textures into OpenGL texture objects.
EdenSurfacesTextureSet: Binds the OpenGL texture.
EdenSurfacesTextureUnload: Unloads textures and frees OpenGL texture objects.

EdenGLCapabilityCheck

Checks for the presence of an OpenGL capability by version or extension.

int EdenGLCapabilityCheck(
    const unsigned short minVersion,
    const unsigned char *extension);

Parameters

minVersion: A binary-coded decimal (i.e. version 1.0 is represented as 0x0100) version number. If minVersion is zero, (i.e. there is no version of OpenGL with this extension in core) the version test will always fail, and the result will only be true if the extension string test passes.
extension: A string with an extension name to search the drivers extensions string for. E.g. "GL_EXT_texture". If NULL, the extension name test will always fail, and the result will only be true if the version number test passes.

Return Value

TRUE If either of the tests passes, or FALSE if both fail.

Discussion

Checks for the presence of an OpenGL capability by version or extension. The test returns true if EITHER the OpenGL driver's OpenGL implementation version meets or exceeds a minimum value (passed in in minVersion) OR if an OpenGL extension identifier passed in as a character string is non-NULL, and is found in the current driver's list of supported extensions.

EdenGluCheckExtension

Check for the availability of an OpenGL extension.

GLboolean EdenGluCheckExtension(
    const GLubyte *extName,
    const GLubyte *extString);

Parameters

extName: Name of the extension, e.g. "GL_EXT_texture".
extString: The OpenGL extensions string, as returned by glGetString(GL_EXTENSIONS);

Return Value

TRUE, if the extension is found, FALSE otherwise.

Discussion

Provides the same functionality as the gluCheckExtension() function, since some platforms don't have GLU version 1.3 or later.

EdenSurfacesDraw

Draw a texture on a quad using OpenGL.

EDEN_BOOL EdenSurfacesDraw(
    const int contextIndex,
    const TEXTURE_INDEX_t textureIndex,
    const int width,
    const int height,
    const EDEN_TEXTURE_SCALING_MODE scaleMode,
    const EDEN_TEXTURE_ALIGNMENT_MODE alignMode);

Parameters

width: Width, in OpenGL units, of the quad on which to draw.
height: Height, in OpenGL units, of the quad on which to draw.
scaleMode: determines how the scale factor between pixels in the source image and OpenGL units on the surface.
alignMode: determines the placement of the image inside the surface.

Return Value

TRUE if the function succeeded, FALSE otherwise.

Discussion

Draws the texture pointed to by index on a surface of size (width, height) OpenGL units, with the lower-left corner of the surface at the origin, and the surface lying in the X-Y plane.

To draw at a different position and/or orientation precede with glTranslate/glRotate calls.

EdenSurfacesFinal

Finalise the EdenSurfaces library.

EDEN_BOOL EdenSurfacesFinal(
    void);

Return Value

TRUE if the function succeeded, FALSE otherwise.

Discussion

This function should be called once no more calls to any other EdenSurfaces*() functions are required, to free up allocated memory. Does NOT require that a valid OpenGL context be available.

EdenSurfacesInit

Initialise the EdenSurfaces library.

EDEN_BOOL EdenSurfacesInit(
    const int contextsActiveCount,
    const int textureIndicesMax);

Parameters

contextsActiveCount: Maximum number of OpenGL contexts that will be in use. Typically 1.
textureIndicesMax: Maximum number of textures that can be loaded via calls to EdenSurfacesTextureLoad.

Return Value

TRUE if the function succeeded, FALSE otherwise.

Discussion

This function must be called prior to any other EdenSurfaces*() functions being called.

Does NOT require that a valid OpenGL context be available.

EdenSurfacesTextureLoad

Loads textures into OpenGL texture objects.

EDEN_BOOL EdenSurfacesTextureLoad(
    const int contextIndex,
    const int numTextures,
    const TEXTURE_INFO_t *textureInfo,
    TEXTURE_INDEX_t *textureIndices,
    char *hasAlpha_out);

Parameters

contextIndex

The index of the OpenGL context into which this texture is being loaded. (The context must already be active.) Normally 0 if using only one context. May not be more than contextsActiveCount-1 (as passed to EdenSurfacesInit).

numTextures

The number of textures being loaded.

textureInfo

An array (of length numTextures) holding details of each texture being loaded.

On OpenGL ES devices with limited non-power-of-two (NPOT) texture support, the NPOT support will only be available if {mipmaps = FALSE, min_filter/mag_filter = GL_NEAREST/GL_LINEAR, wrap_s/wrap_t = GL_CLAMP_TO_EDGE}.

textureIndices

After loading, the array textureIndices[] holds the index numbers assigned to each texture. These index numbers may then be used in calls to EdenSurfacesTextureSet() and EdenSurfacesTextureUnload(). (These indices are of type TEXTURE_INDEX_t, an unsigned int, greater than or equal to 1, and are only valid per-OpenGL context.) In the event of a loading error, the index value of any textures not loaded will be equal to 0.

hasAlpha_out

If the calling routine wishes to know if the returned texture contains an alpha channel it should supply a pointer to a char in parameter hasAlpha_out, and on return, this char will equal 0 if no alpha channel is present, or 1 otherwise. If this information is not needed, set hasAlpha_out to NULL

Return Value

TRUE if all textures were loaded correctly, FALSE if one or more were not.

Discussion

Loads numTextures textures into OpenGL texture objects, for the specified OpenGL context (the first context has a contextIndex of 0).

EdenSurfacesTextureSet

Binds the OpenGL texture.

void EdenSurfacesTextureSet(
    const int contextIndex,
    TEXTURE_INDEX_t textureIndex);

Parameters

textureIndex: The texture bound is specified by parameter textureIndex. This index is only valid if the current OpenGL context is contextIndex, and the index was returned by EdenSurfacesTextureLoad() with the same OpenGL context.
contextIndex: The index of the OpenGL context with which this texture is being bound. (The context must already be active.) Normally 0 if using only one context. May not be more than contextsActiveCount-1 (as passed to EdenSurfacesInit).

EdenSurfacesTextureUnload

Unloads textures and frees OpenGL texture objects.

EDEN_BOOL EdenSurfacesTextureUnload(
    const int contextIndex,
    const int numTextures,
    TEXTURE_INDEX_t *textureIndices);

Parameters

numTextures: The number of textures being unloaded.
textureIndices: After unloading, the corresponding index in textureIndices for each record in textureInfo[] is set to 0.
contextIndex: The index of the OpenGL context from this texture is being unloaded. (The context must already be active.) Normally 0 if using only one context. May not be more than contextsActiveCount-1 (as passed to EdenSurfacesInit).

Return Value

TRUE if the function succeeded, FALSE otherwise.

Discussion

Unloads numTextures textures from OpenGL texture objects, for the specified OpenGL context.

Typedefs

EDEN_TEXTURE_ALIGNMENT_MODE: How to align the texture content when drawing a texture on a quad.
EDEN_TEXTURE_SCALING_MODE: Scaling mode to use when drawing a texture on a quad.
TEXTURE_INFO_t

EDEN_TEXTURE_ALIGNMENT_MODE

How to align the texture content when drawing a texture on a quad.

typedef enum { 
    CENTRE, 
    TOP_LEFT, 
    TOP_RIGHT, 
    BOTTOM_LEFT, 
    BOTTOM_RIGHT, 
    LEFT, 
    TOP, 
    RIGHT, 
    BOTTOM 
} EDEN_TEXTURE_ALIGNMENT_MODE;

EDEN_TEXTURE_SCALING_MODE

Scaling mode to use when drawing a texture on a quad.

typedef enum { 
    STRETCH, 
    FILL, 
    FIT, 
    UNITY 
} EDEN_TEXTURE_SCALING_MODE;

Constants

STRETCH: Match texture size to quad, stretching as necessary.
FILL: Scale the texture so that its smallest side exactly fills the largest side of the quad. If the texture and the quad are not the same ratio, the texture will be cropped.
FIT: Scale the texture so that it's largest side exactly fits in the smallest side of the quad. If the texture and the quad are not the same ratio, the texture will be surrounded by background texture (letterbox/pillarbox).
UNITY: Draw the texture with one pixel per one OpenGL unit, without stretching. If the texture is larger than the quad, it will be cropped. If it is smaller, it will be surrounded by background texture.

TEXTURE_INFO_t

typedef struct { 
    const char *pathname; 
    GLboolean mipmaps; 
    GLint internalformat; 
    GLint min_filter; 
    GLint mag_filter; 
    GLint wrap_s; 
    GLint wrap_t; 
    GLclampf priority; 
    GLint env_mode; 
    //GLfloat        env_color[4]; 
} TEXTURE_INFO_t;

Fields

pathname: Pathname of the texture file to load.
mipmaps: TRUE if mipmaps should be generated (e.g. if the texture will be drawn scaled to sizes smaller than unity), FALSE otherwise.
internalformat: OpenGL internal texture format to use. E.g. this allows a single-channel texture to be loaded as GL_ALPHA rather than GL_LUMINANCE. Typically GL_RGB or GL_RGBA.
min_filter
mag_filter
wrap_s
wrap_t
priority
env_mode

Last Updated: Wednesday, March 23, 2016