## texture

texture — Texture loading and manipulation

## Synopsis

    #include <g3d/texture.h>

    #define             G3D_FLAG_IMG_GREYSCALE
    enum                G3DTexEnv;
                        G3DImage;
    G3DImage*           g3d_texture_load_cached             (G3DContext *context,
                                                             G3DModel *model,
                                                             const gchar *filename);
    G3DImage*           g3d_texture_load_from_stream        (G3DContext *context,
                                                             G3DModel *model,
                                                             G3DStream *stream);
    G3DImage*           g3d_texture_load                    (G3DContext *context,
                                                             const gchar *filename);
    void                g3d_texture_free                    (G3DImage *texture);
    gboolean            g3d_texture_prepare                 (G3DImage *texture);
    gboolean            g3d_texture_flip_y                  (G3DImage *texture);
    G3DImage*           g3d_texture_merge_alpha             (G3DImage *image,
                                                             G3DImage *aimage);

## Description

A texture is an image used in materials. Here are some helper functions, mostly for cached loading of a G3DImage.

## Details

### G3D_FLAG_IMG_GREYSCALE

    #define G3D_FLAG_IMG_GREYSCALE       (1L << 1)

The image just uses the red channel for grey value

### enum G3DTexEnv

    typedef enum {
    	G3D_TEXENV_UNSPECIFIED = 0,
    	G3D_TEXENV_BLEND,
    	G3D_TEXENV_DECAL,
    	G3D_TEXENV_MODULATE,
    	G3D_TEXENV_REPLACE
    } G3DTexEnv;

Specify how the texture should interact with other material properties.

`G3D_TEXENV_UNSPECIFIED` | unspecified, application decides
`G3D_TEXENV_BLEND` | use blending
`G3D_TEXENV_DECAL` | use as decal
`G3D_TEXENV_MODULATE` | use modulate
`G3D_TEXENV_REPLACE` | replace color

### G3DImage

    typedef struct {
    	gchar *name;
    	guint32 width;
    	guint32 height;
    	guint8 depth;
    	guint32 flags;
    	guint8 *pixeldata;

    	guint32 tex_id;
    	G3DTexEnv tex_env;
    	G3DFloat tex_scale_u;
    	G3DFloat tex_scale_v;
    } G3DImage;

Object containing a two-dimensional pixel image.

gchar *`name`; | name of image
guint32 `width`; | width of image in pixels
guint32 `height`; | height of image in pixels
guint8 `depth`; | depth of image in bits
guint32 `flags`; | flags
guint8 *`pixeldata`; | the binary image data
guint32 `tex_id`; | the OpenGL texture id, should be unique model-wide
G3DTexEnv `tex_env`; | texture environment flags
G3DFloat `tex_scale_u`; | factor scaling texture width, should be 1.0 for most cases
G3DFloat `tex_scale_v`; | factor scaling texture height, should be 1.0 for most cases

### g3d_texture_load_cached ()

    G3DImage*           g3d_texture_load_cached             (G3DContext *context,
                                                             G3DModel *model,
                                                             const gchar *filename);

Loads a texture image from file and attaches it to a hash table in the model. On a second try to load this texture it is returned from cache.

`context` : | a valid context
`model` : | a valid model
`filename` : | the file name of the texture to load
Returns : | the texture image

### g3d_texture_load_from_stream ()

    G3DImage*           g3d_texture_load_from_stream        (G3DContext *context,
                                                             G3DModel *model,
                                                             G3DStream *stream);

Load a texture image from a stream. The file type is determined by the extension of the stream URI, so it should be valid. If `model` is not NULL the texture image is cached (or retrieved from cache if available).

`context` : | a valid context
`model` : | a valid model or NULL
`stream` : | an open stream
Returns : | the texture image or NULL in case of an error.

### g3d_texture_load ()

    G3DImage*           g3d_texture_load                    (G3DContext *context,
                                                             const gchar *filename);

Load a texture from a file. The type of file is determined by the file extension.

`context` : | a valid context
`filename` : | the file name of the texture
Returns : | the texture image or NULL in case of an error.

### g3d_texture_free ()

    void                g3d_texture_free                    (G3DImage *texture);

Frees all memory used by this texture image.

`texture` : | a texture image

### g3d_texture_prepare ()

    gboolean            g3d_texture_prepare                 (G3DImage *texture);

Resizes the image to dimensions which are a power of 2 to be usable as an OpenGL texture. (FIXME: unimplemented)

`texture` : | a texture image
Returns : | TRUE on success, FALSE else

### g3d_texture_flip_y ()

    gboolean            g3d_texture_flip_y                  (G3DImage *texture);

Mirror the image along the x axis - all y coordinates are inverted.

`texture` : | a texture image
Returns : | TRUE on success, FALSE on error.

### g3d_texture_merge_alpha ()

    G3DImage*           g3d_texture_merge_alpha             (G3DImage *image,
                                                             G3DImage *aimage);

Merges alpha information from `aimage` into output image. If `image` is NULL a new image is created, else `image` is returned with alpha from `aimage`.

`image` : | a texture image or NULL
`aimage` : | an image with alpha information
Returns : | a texture image or NULL in case of an error.