MxTextureCache

## MxTextureCache MxTextureCache — A per-process store to cache textures |

## Synopsis

                        MxTextureCache;
                        MxTextureCacheClass;
    MxTextureCache *    mx_texture_cache_get_default        (void);
    ClutterTexture *    mx_texture_cache_get_texture        (MxTextureCache *self,
                                                             const gchar *uri);
    ClutterActor *      mx_texture_cache_get_actor          (MxTextureCache *self,
                                                             const gchar *uri);
    gboolean            mx_texture_cache_contains           (MxTextureCache *self,
                                                             const gchar *uri);
    void                mx_texture_cache_insert             (MxTextureCache *self,
                                                             const gchar *uri,
                                                             CoglHandle *texture);
    CoglHandle          mx_texture_cache_get_cogl_texture   (MxTextureCache *self,
                                                             const gchar *uri);
    gint                mx_texture_cache_get_size           (MxTextureCache *self);
    void                mx_texture_cache_load_cache         (MxTextureCache *self,
                                                             const char *filename);
    gboolean            mx_texture_cache_contains_meta      (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);
    CoglHandle          mx_texture_cache_get_meta_cogl_texture
                                                            (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);
    ClutterTexture *    mx_texture_cache_get_meta_texture   (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);
    void                mx_texture_cache_insert_meta        (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident,
                                                             CoglHandle *texture,
                                                             GDestroyNotify destroy_func);

## Object Hierarchy

      GObject
       +----MxTextureCache

## Description

MxTextureCache allows an application to re-use an previously loaded textures.

## Details

### MxTextureCache

    typedef struct _MxTextureCache MxTextureCache;

The contents of this structure are private and should only be accessed through the public API.

### MxTextureCacheClass

    typedef struct {
      GObjectClass parent_class;

      void (* loaded)        (MxTextureCache *self,
                              const gchar      *uri,
                              ClutterTexture   *texture);

      void (* error_loading) (MxTextureCache *self,
                              GError           *error);

      /* padding for future expansion */
      void (*_padding_0) (void);
      void (*_padding_1) (void);
      void (*_padding_2) (void);
      void (*_padding_3) (void);
      void (*_padding_4) (void);
    } MxTextureCacheClass;

### mx_texture_cache_get_default ()

    MxTextureCache *    mx_texture_cache_get_default        (void);

Returns the default texture cache. This is owned by Mx and should not be unreferenced or freed.

Returns : | a MxTextureCache. [transfer none]

### mx_texture_cache_get_texture ()

    ClutterTexture *    mx_texture_cache_get_texture        (MxTextureCache *self,
                                                             const gchar *uri);

Create a new ClutterTexture with the specified image. Adds the image to the cache if the image had not been previously loaded. Subsequent calls with the same image URI/path will return a new ClutterTexture with the previously loaded image.

`self` : | A MxTextureCache
`uri` : | A URI or path to a image file
Returns : | a newly created ClutterTexture. [transfer none]

### mx_texture_cache_get_actor ()

    ClutterActor *      mx_texture_cache_get_actor          (MxTextureCache *self,
                                                             const gchar *uri);

This is a wrapper around `mx_texture_cache_get_texture()` which returns a ClutterActor.

`self` : | A MxTextureCache
`uri` : | A URI or path to a image file
Returns : | a newly created ClutterTexture. [transfer none]

### mx_texture_cache_contains ()

    gboolean            mx_texture_cache_contains           (MxTextureCache *self,
                                                             const gchar *uri);

Checks whether the given URI/path is contained within the texture cache.

`self` : | A MxTextureCache
`uri` : | A URI or path to an image file
Returns : | `TRUE` if the image exists, `FALSE` otherwise

Since 1.2

### mx_texture_cache_insert ()

    void                mx_texture_cache_insert             (MxTextureCache *self,
                                                             const gchar *uri,
                                                             CoglHandle *texture);

Inserts a texture into the texture cache. This can be useful if you want to cache a texture from a custom or unhandled URI type, or you want to override a particular texture.

If the image is already in the cache, this texture will replace it. A reference will be taken on the given texture.

`self` : | A MxTextureCache
`uri` : | A URI or local file path
`texture` : | A CoglHandle to a texture

Since 1.2

### mx_texture_cache_get_cogl_texture ()

    CoglHandle          mx_texture_cache_get_cogl_texture   (MxTextureCache *self,
                                                             const gchar *uri);

Create a CoglHandle representing a texture of the specified image. Adds the image to the cache if the image had not been previously loaded. Subsequent calls with the same image URI/path will return the CoglHandle of the previously loaded image with an increased reference count.

`self` : | A MxTextureCache
`uri` : | A URI or path to an image file
Returns : | a CoglHandle to the cached texture. [transfer none]

### mx_texture_cache_get_size ()

    gint                mx_texture_cache_get_size           (MxTextureCache *self);

Returns the number of items in the texture cache

`self` : | A MxTextureCache
Returns : | the current size of the cache

### mx_texture_cache_load_cache ()

    void                mx_texture_cache_load_cache         (MxTextureCache *self,
                                                             const char *filename);

### mx_texture_cache_contains_meta ()

    gboolean            mx_texture_cache_contains_meta      (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);

Checks whether there are any textures associated with the given URI by the given identifier.

`self` : | A MxTextureCache
`uri` : | A URI or path to an image file
`ident` : | A unique identifier
Returns : | `TRUE` if the data exists, `FALSE` otherwise

Since 1.2

### mx_texture_cache_get_meta_cogl_texture ()

    CoglHandle          mx_texture_cache_get_meta_cogl_texture
                                                            (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);

Retrieves the CoglHandle of the previously added image associated with the given unique identifier.

See `mx_texture_cache_insert_meta()`

`self` : | A MxTextureCache
`uri` : | A URI or path to an image file
`ident` : | A unique identifier
Returns : | A CoglHandle to a texture, with an added reference. `NULL` if no image was found. [transfer full]

Since 1.2

### mx_texture_cache_get_meta_texture ()

    ClutterTexture *    mx_texture_cache_get_meta_texture   (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident);

Create a new ClutterTexture using the previously added image associated with the given unique identifier.

See `mx_texture_cache_insert_meta()`

`self` : | A MxTextureCache
`uri` : | A URI or path to an image file
`ident` : | A unique identifier
Returns : | A newly allocated ClutterTexture, or `NULL` if no image was found. [transfer full]

Since 1.2

### mx_texture_cache_insert_meta ()

    void                mx_texture_cache_insert_meta        (MxTextureCache *self,
                                                             const gchar *uri,
                                                             gpointer ident,
                                                             CoglHandle *texture,
                                                             GDestroyNotify destroy_func);

Inserts a texture that's associated with a URI into the cache. If the metadata already exists for this URI, it will be replaced.

This is useful if you have a widely used modification of an image, for example, an image with a border composited around it.

`self` : | A MxTextureCache
`uri` : | A URI or local file path
`ident` : | A unique identifier
`texture` : | A CoglHandle to a texture
`destroy_func` : | An optional destruction function for `ident`

Since 1.2