## texture

texture — Texture loading and manipulation

## Functions

G3DImage * | g3d_texture_load_cached ()
G3DImage * | g3d_texture_load_from_stream ()
G3DImage * | g3d_texture_load ()
void | g3d_texture_free ()
gboolean | g3d_texture_prepare ()
gboolean | g3d_texture_flip_y ()
G3DImage * | g3d_texture_merge_alpha ()

## Types and Values

#define | G3D_FLAG_IMG_GREYSCALE
enum | G3DTexEnv
| G3DImage

## Includes

    #include <g3d/texture.h>

## Description

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

## Functions

### 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.

#### Parameters

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).

#### Parameters

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.

#### Parameters

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.

#### Parameters

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)

#### Parameters

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.

#### Parameters

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` .

#### Parameters

image | a texture image or NULL |
aimage | an image with alpha information |

#### Returns

a texture image or NULL in case of an error.

## Types and Values

### G3D_FLAG_IMG_GREYSCALE

    #define G3D_FLAG_IMG_GREYSCALE       (1L << 1)

The image just uses the red channel for grey value

### enum G3DTexEnv

Specify how the texture should interact with other material properties.

#### Members

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.

#### Members

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 |