## StTextureCache

StTextureCache

## Synopsis

    struct              StTextureCache;
    struct              StTextureCacheClass;
    CoglHandle          (*StTextureCacheLoader)             (StTextureCache *cache,
                                                             const char *key,
                                                             void *data,
                                                             GError **error);
    enum                StTextureCachePolicy;
    ClutterActor *      st_texture_cache_bind_pixbuf_property
                                                            (StTextureCache *cache,
                                                             GObject *object,
                                                             const char *property_name);
    void                st_texture_cache_evict_recent_thumbnail
                                                            (StTextureCache *cache,
                                                             GtkRecentInfo *info);
    void                st_texture_cache_evict_thumbnail    (StTextureCache *cache,
                                                             const char *uri);
    StTextureCache *    st_texture_cache_get_default        (void);
    CoglHandle          st_texture_cache_load               (StTextureCache *cache,
                                                             const char *key,
                                                             StTextureCachePolicy policy,
                                                             StTextureCacheLoader load,
                                                             void *data,
                                                             GError **error);
    ClutterActor *      st_texture_cache_load_file_simple   (StTextureCache *cache,
                                                             const gchar *file_path);
    cairo_surface_t *   st_texture_cache_load_file_to_cairo_surface
                                                            (StTextureCache *cache,
                                                             const gchar *file_path);
    CoglHandle          st_texture_cache_load_file_to_cogl_texture
                                                            (StTextureCache *cache,
                                                             const gchar *file_path);
    ClutterActor *      st_texture_cache_load_from_data     (StTextureCache *cache,
                                                             const guchar *data,
                                                             gsize len,
                                                             int size,
                                                             GError **error);
    ClutterActor *      st_texture_cache_load_from_raw      (StTextureCache *cache,
                                                             const guchar *data,
                                                             gsize len,
                                                             gboolean has_alpha,
                                                             int width,
                                                             int height,
                                                             int rowstride,
                                                             int size,
                                                             GError **error);
    ClutterActor *      st_texture_cache_load_gicon         (StTextureCache *cache,
                                                             StThemeNode *theme_node,
                                                             GIcon *icon,
                                                             gint size);
    ClutterActor *      st_texture_cache_load_icon_name     (StTextureCache *cache,
                                                             StThemeNode *theme_node,
                                                             const char *name,
                                                             StIconType icon_type,
                                                             gint size);
    ClutterActor *      st_texture_cache_load_recent_thumbnail
                                                            (StTextureCache *cache,
                                                             int size,
                                                             GtkRecentInfo *info);
    ClutterGroup *      st_texture_cache_load_sliced_image  (StTextureCache *cache,
                                                             const gchar *path,
                                                             gint grid_width,
                                                             gint grid_height);
    ClutterActor *      st_texture_cache_load_thumbnail     (StTextureCache *cache,
                                                             int size,
                                                             const char *uri,
                                                             const char *mimetype);
    ClutterActor *      st_texture_cache_load_uri_async     (StTextureCache *cache,
                                                             const gchar *uri,
                                                             int available_width,
                                                             int available_height);
    ClutterActor *      st_texture_cache_load_uri_sync      (StTextureCache *cache,
                                                             StTextureCachePolicy policy,
                                                             const gchar *uri,
                                                             int available_width,
                                                             int available_height,
                                                             GError **error);
    gboolean            st_texture_cache_pixbuf_equal       (StTextureCache *cache,
                                                             GdkPixbuf *a,
                                                             GdkPixbuf *b);

## Object Hierarchy

      GObject
       +----StTextureCache

## Signals

      "icon-theme-changed"                             : Run Last

## Description

## Details

### struct StTextureCache

    struct StTextureCache;

### struct StTextureCacheClass

    struct StTextureCacheClass {
      GObjectClass parent_class;
    };

### StTextureCacheLoader ()

    CoglHandle          (*StTextureCacheLoader)             (StTextureCache *cache,
                                                             const char *key,
                                                             void *data,
                                                             GError **error);

See `st_texture_cache_load()`. Implementations should return a texture handle for the given key, or set `error`.

`cache` : | a StTextureCache
`key` : | Unique identifier for this texture
`data` : | Callback user data
`error` : | A GError

### enum StTextureCachePolicy

    typedef enum {
      ST_TEXTURE_CACHE_POLICY_NONE,
      ST_TEXTURE_CACHE_POLICY_FOREVER
    } StTextureCachePolicy;

### st_texture_cache_bind_pixbuf_property ()

    ClutterActor *      st_texture_cache_bind_pixbuf_property
                                                            (StTextureCache *cache,
                                                             GObject *object,
                                                             const char *property_name);

Create a ClutterTexture which tracks the GdkPixbuf value of a GObject property named by `property_name`. Unlike other methods in StTextureCache, the underlying CoglHandle is not shared by default with other invocations to this method.

If the source object is destroyed, the texture will continue to show the last value of the property.

`object` : | A GObject with a property `property_name` of type GdkPixbuf
`property_name` : | Name of a property
Returns : | A new ClutterActor. [transfer none]

### st_texture_cache_evict_recent_thumbnail ()

    void                st_texture_cache_evict_recent_thumbnail
                                                            (StTextureCache *cache,
                                                             GtkRecentInfo *info);

Removes all references added by `st_texture_cache_load_recent_thumbnail()` function for the URI associated with the given `info`.

`info` : | A recent info

### st_texture_cache_evict_thumbnail ()

    void                st_texture_cache_evict_thumbnail    (StTextureCache *cache,
                                                             const char *uri);

Removes all references added by `st_texture_cache_load_thumbnail()` function created for the given URI.

`uri` : | Source URI

### st_texture_cache_get_default ()

    StTextureCache *    st_texture_cache_get_default        (void);

Returns : | The global texture cache. [transfer none]

### st_texture_cache_load ()

    CoglHandle          st_texture_cache_load               (StTextureCache *cache,
                                                             const char *key,
                                                             StTextureCachePolicy policy,
                                                             StTextureCacheLoader load,
                                                             void *data,
                                                             GError **error);

Load an arbitrary texture, caching it. The string chosen for `key` should be of the form "type-prefix:type-uuid". For example, "url:file:///usr/share/icons/hicolor/48x48/apps/firefox.png", or "stock-icon:gtk-ok".

`cache` : | A StTextureCache
`key` : | Arbitrary string used to refer to item
`policy` : | Caching policy
`load` : | Function to create the texture, if not already cached
`data` : | User data passed to `load`
`error` : | A GError
Returns : | A newly-referenced handle to the texture. [transfer full]

### st_texture_cache_load_file_simple ()

    ClutterActor *      st_texture_cache_load_file_simple   (StTextureCache *cache,
                                                             const gchar *file_path);

Synchronously load an image into a texture. The texture will be cached indefinitely. On error, this function returns an empty texture and prints a warning.

`cache` : | A StTextureCache
`file_path` : | Filesystem path
Returns : | A new ClutterTexture. [transfer none]

### st_texture_cache_load_file_to_cairo_surface ()

    cairo_surface_t *   st_texture_cache_load_file_to_cairo_surface
                                                            (StTextureCache *cache,
                                                             const gchar *file_path);

This function synchronously loads the given file path into a cairo surface. On error, a warning is emitted and `NULL` is returned.

`cache` : | A StTextureCache
`file_path` : | Path to a file in supported image format
Returns : | a new cairo_surface_t. [transfer full]

### st_texture_cache_load_file_to_cogl_texture ()

    CoglHandle          st_texture_cache_load_file_to_cogl_texture
                                                            (StTextureCache *cache,
                                                             const gchar *file_path);

This function synchronously loads the given file path into a COGL texture. On error, a warning is emitted and `COGL_INVALID_HANDLE` is returned.

`cache` : | A StTextureCache
`file_path` : | Path to a file in supported image format
Returns : | a new CoglHandle. [transfer full]

### st_texture_cache_load_from_data ()

    ClutterActor *      st_texture_cache_load_from_data     (StTextureCache *cache,
                                                             const guchar *data,
                                                             gsize len,
                                                             int size,
                                                             GError **error);

Synchronously creates an image from `data`. The image is scaled down to fit the available width and height dimensions, but the image is never scaled up beyond its actual size. The pixbuf is rotated according to the associated orientation setting.

`cache` : | The texture cache instance
`data` : | Image data in PNG, GIF, etc format
`len` : | length of `data`
`size` : | Size in pixels to use for the resulting texture
`error` : | Return location for error
Returns : | A new ClutterActor with the image data loaded if it was generated succesfully, `NULL` otherwise. [transfer none]

### st_texture_cache_load_from_raw ()

    ClutterActor *      st_texture_cache_load_from_raw      (StTextureCache *cache,
                                                             const guchar *data,
                                                             gsize len,
                                                             gboolean has_alpha,
                                                             int width,
                                                             int height,
                                                             int rowstride,
                                                             int size,
                                                             GError **error);

Creates (or retrieves from cache) an icon based on raw pixel data.

`cache` : | a StTextureCache
`data` : | raw pixel data. [array length=len]
`len` : | the length of `data`
`has_alpha` : | whether `data` includes an alpha channel
`width` : | width in pixels of `data`
`height` : | width in pixels of `data`
`rowstride` : | rowstride of `data`
`size` : | size of icon to return
Returns : | a new ClutterActor displaying a pixbuf created from `data` and the other parameters. [transfer none]

### st_texture_cache_load_gicon ()

    ClutterActor *      st_texture_cache_load_gicon         (StTextureCache *cache,
                                                             StThemeNode *theme_node,
                                                             GIcon *icon,
                                                             gint size);

This method returns a new ClutterActor for a given GIcon. If the icon isn't loaded already, the texture will be filled asynchronously.

This will load `icon` as a full-color icon; if you want a symbolic icon, you must use `st_texture_cache_load_icon_name()`.

`cache` : | The texture cache instance
`theme_node` : | The StThemeNode to use for colors, or NULL if the icon must not be recolored. [allow-none]
`icon` : | the GIcon to load
`size` : | Size of themed
Returns : | A new ClutterActor for the icon, or `NULL` if not found. [transfer none]

### st_texture_cache_load_icon_name ()

    ClutterActor *      st_texture_cache_load_icon_name     (StTextureCache *cache,
                                                             StThemeNode *theme_node,
                                                             const char *name,
                                                             StIconType icon_type,
                                                             gint size);

Load a themed icon into a texture. See the StIconType documentation for an explanation of how `icon_type` affects the returned icon. The colors used for symbolic icons are derived from `theme_node`.

`cache` : | The texture cache instance
`theme_node` : | a StThemeNode. [allow-none]
`name` : | Name of a themed icon
`icon_type` : | the type of icon to load
`size` : | Size of themed icon
Returns : | A new ClutterTexture for the icon. [transfer none]

### st_texture_cache_load_recent_thumbnail ()

    ClutterActor *      st_texture_cache_load_recent_thumbnail
                                                            (StTextureCache *cache,
                                                             int size,
                                                             GtkRecentInfo *info);

Asynchronously load a thumbnail image of a GtkRecentInfo into a texture. The returned texture object will be a new instance; however, its texture data may be shared with other objects. This implies the texture data is cached.

The current caching policy is permanent; to uncache, you must explicitly call `st_texture_cache_unref_recent_thumbnail()`.

`size` : | Size in pixels to use for thumbnail
`info` : | Recent item info
Returns : | A new ClutterActor. [transfer none]

### st_texture_cache_load_sliced_image ()

    ClutterGroup *      st_texture_cache_load_sliced_image  (StTextureCache *cache,
                                                             const gchar *path,
                                                             gint grid_width,
                                                             gint grid_height);

This function reads a single image file which contains multiple images internally. The image file will be divided using `grid_width` and `grid_height`; note that the dimensions of the image loaded from `path` should be a multiple of the specified grid dimensions.

`cache` : | A StTextureCache
`path` : | Path to a filename
`grid_width` : | Width in pixels
`grid_height` : | Height in pixels
Returns : | A new ClutterGroup. [transfer none]

### st_texture_cache_load_thumbnail ()

    ClutterActor *      st_texture_cache_load_thumbnail     (StTextureCache *cache,
                                                             int size,
                                                             const char *uri,
                                                             const char *mimetype);

Asynchronously load a thumbnail image of a URI into a texture. The returned texture object will be a new instance; however, its texture data may be shared with other objects. This implies the texture data is cached.

The current caching policy is permanent; to uncache, you must explicitly call `st_texture_cache_unref_thumbnail()`.

`size` : | Size in pixels to use for thumbnail
`uri` : | Source URI
`mimetype` : | Source mime type
Returns : | A new ClutterActor. [transfer none]

### st_texture_cache_load_uri_async ()

    ClutterActor *      st_texture_cache_load_uri_async     (StTextureCache *cache,
                                                             const gchar *uri,
                                                             int available_width,
                                                             int available_height);

`cache`: The texture cache instance `uri`: uri of the image file from which to create a pixbuf `available_width`: available width for the image, can be -1 if not limited `available_height`: available height for the image, can be -1 if not limited

Asynchronously load an image. Initially, the returned texture will have a natural size of zero. At some later point, either the image will be loaded successfully and at that point size will be negotiated, or upon an error, no image will be set.

Returns : | A new ClutterActor with no image loaded initially. [transfer none]

### st_texture_cache_load_uri_sync ()

    ClutterActor *      st_texture_cache_load_uri_sync      (StTextureCache *cache,
                                                             StTextureCachePolicy policy,
                                                             const gchar *uri,
                                                             int available_width,
                                                             int available_height,
                                                             GError **error);

`cache`: The texture cache instance `policy`: Requested lifecycle of cached data `uri`: uri of the image file from which to create a pixbuf `available_width`: available width for the image, can be -1 if not limited `available_height`: available height for the image, can be -1 if not limited `error`: Return location for error

Synchronously load an image from a uri. The image is scaled down to fit the available width and height imensions, but the image is never scaled up beyond its actual size. The pixbuf is rotated according to the associated orientation setting.

Returns : | A new ClutterActor with the image file loaded if it was generated succesfully, `NULL` otherwise. [transfer none]

### st_texture_cache_pixbuf_equal ()

    gboolean            st_texture_cache_pixbuf_equal       (StTextureCache *cache,
                                                             GdkPixbuf *a,
                                                             GdkPixbuf *b);

Returns : | `TRUE` iff the given pixbufs are bytewise-equal

## Signal Details

### The `"icon-theme-changed"` signal

    void                user_function                      (StTextureCache *sttexturecache,
                                                            gpointer        user_data)           : Run Last