| # 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` © 2001-2013 Philip Lamb Last Updated: Monday, October 05, 2015