gdkpixbufdrawcache

## gdkpixbufdrawcache gdkpixbufdrawcache — Cache for drawing scaled pixbufs |

## Synopsis

                        GdkPixbufDrawOpts;
                        GdkPixbufDrawCache;
    enum                GdkPixbufDrawMethod;
    GdkPixbufDrawCache * gdk_pixbuf_draw_cache_new          (void);
    void                gdk_pixbuf_draw_cache_free          (GdkPixbufDrawCache *cache);
    void                gdk_pixbuf_draw_cache_invalidate    (GdkPixbufDrawCache *cache);
    void                gdk_pixbuf_draw_cache_draw          (GdkPixbufDrawCache *cache,
                                                             GdkPixbufDrawOpts *opts,
                                                             GdkDrawable *drawable);
    GdkPixbufDrawMethod  gdk_pixbuf_draw_cache_get_method   (GdkPixbufDrawOpts *old,
                                                             GdkPixbufDrawOpts *new_);

## Description

The main object in this file is GdkPixbufDrawCache which provies a cache that should be used by GtkIImageTool's when redrawing the GtkImageView.

## Details

### GdkPixbufDrawOpts

    typedef struct {
        gdouble        zoom;

        /* Rectangle in zoom-space coordinates of the area to draw. */
        GdkRectangle   zoom_rect;

        /* Position in widget-space coordinates where to draw. */
        int            widget_x;
        int            widget_y;

        GdkInterpType  interp;
        GdkPixbuf     *pixbuf;

        /* The two colors to use to draw the checker board. */
        int            check_color1;
        int            check_color2;
    } GdkPixbufDrawOpts;

Struct which holds options for how the pixbuf should be drawn. Options include such things like the source rectangle in the pixbuf to draw, where to draw it, which zoom to use and so on.

### GdkPixbufDrawCache

    typedef struct {
        GdkPixbuf         *last_pixbuf;
        GdkPixbufDrawOpts  old;
        int                check_size;
    } GdkPixbufDrawCache;

Cache that ensures fast redraws by storing the last draw operation. For example, when resizing a GtkImageView, the view receives an expose event and must redraw the damaged region. Unless fitting is `TRUE`, most of the pixels it should draw are indentical to the ones drawn the previous time. Redrawing them is wasteful because scaling and especially bilinear scaling is very slow. Therefore, PixbufDrawCache objectifies the drawing process and adds a cache with the last draw from which pixels can be fetched.

This object is present purely to ensure optimal speed. A GtkIImageTool that is asked to redraw a part of the image view widget could either do it by itself using `gdk_pixbuf_scale()` and `gdk_draw_pixbuf()`.

### enum GdkPixbufDrawMethod

    typedef enum
    {
        GDK_PIXBUF_DRAW_METHOD_SCALE = 0,
        GDK_PIXBUF_DRAW_METHOD_CONTAINS = 1,
        GDK_PIXBUF_DRAW_METHOD_SCROLL = 2
    } GdkPixbufDrawMethod;

Enumeration constants that determine the proper way to draw the next time.

- GD_PIXBUF_DRAW_METHOD_SCALE : Scale the area of the pixbuf to draw and put the result in cache. This is the slowest draw method as the whole area to be drawn must be rescaled. It is mostly used when no part of "s" cache is valid.
- GDK_PIXBUF_DRAW_METHOD_CONTAINS : Get the area of the pixbuf to draw from the cache without updating the cache afterwards. Only blitting is needed.
- GDK_PIXBUF_DRAW_METHOD_SCROLL : Partially use the cache and scale the region not cached. The cache is updated with the result.

### gdk_pixbuf_draw_cache_new ()

    GdkPixbufDrawCache * gdk_pixbuf_draw_cache_new          (void);

Creates a new pixbuf draw cache.

Returns : | a new GdkPixbufDrawCache

### gdk_pixbuf_draw_cache_free ()

    void                gdk_pixbuf_draw_cache_free          (GdkPixbufDrawCache *cache);

Deallocates a pixbuf draw cache and all its data.

`cache` : | a GdkPixbufDrawCache

### gdk_pixbuf_draw_cache_invalidate ()

    void                gdk_pixbuf_draw_cache_invalidate    (GdkPixbufDrawCache *cache);

Force the pixbuf draw cache to scale the pixbuf at the next draw.

GdkPixbufDrawCache tries to minimize the number of scale operations needed by caching the last drawn pixbuf. It would be inefficient to check the individual pixels inside the pixbuf so it assumes that if the memory address of the pixbuf has not changed, then the cache is good to use.

However, when the image data is modified, this assumtion breaks, which is why this method must be used to tell draw cache about it.

`cache` : | a GdkPixbufDrawCache

### gdk_pixbuf_draw_cache_draw ()

    void                gdk_pixbuf_draw_cache_draw          (GdkPixbufDrawCache *cache,
                                                             GdkPixbufDrawOpts *opts,
                                                             GdkDrawable *drawable);

Redraws the area specified in the pixbuf draw options in an efficient way by using caching.

`cache` : | a GdkPixbufDrawCache
`opts` : | the GdkPixbufDrawOpts to use in this draw
`drawable` : | a GdkDrawable to draw on

### gdk_pixbuf_draw_cache_get_method ()

    GdkPixbufDrawMethod  gdk_pixbuf_draw_cache_get_method   (GdkPixbufDrawOpts *old,
                                                             GdkPixbufDrawOpts *new_);

Gets the fastest method to draw the specified draw options. `last_opts` is assumed to be the last PixbufDrawOpts used and `new_opts` is the one to use this time.

`old` : | the last draw options used
`new_` : | the current draw options
Returns : | the best draw method to use to draw