GnomeCanvasPixbuf

Custom Scaling and Translation

In addition to the normal affine transformations supported by canvas items, the GnomeCanvasPixbuf item supports independent object arguments for scaling and translation. This is useful for explicitly setting a size to which the pixbuf's image will be scaled, and for specifying translation offsets that take place in the item's local coordinate system.

By default, the pixbuf canvas item will attain the size in units of the GdkPixbuf it contains. If a GnomeCanvasPixbuf is configured to use a GdkPixbuf that has a size of 300 by 200 pixels, then the pixbuf item will automatically obtain a size of 300 by 200 units in the item's local coordinate system. If the item is transformed with a scaling transformation of (0.5, 2.0), then the final image size will be of 150 by 400 pixels.

To set custom width and height values, you must set the width_set or height_set arguments to TRUE, and then set the width or height arguments to the desired values. The former two arguments control whether the latter two are used when computing the final image's size; they are both FALSE by default so that the pixbuf item will attain a size in units equal to the size in pixels of the GdkPixbuf that the item contains.

The custom translation offsets are controlled by the x and y arguments. The logical upper-left vertex of the image will be translated by the specified distance, aligned with the item's local coordinate system.

Absolute Pixel Scaling and Translation

The Scalable Vector Graphics specification (SVG) of the World Wide Web Consortium also allows images to be translated and scaled by absolute pixel values that are independent of an item's normal affine transformation.

Normally, the pixbuf item's translation and scaling arguments are interpreted in units, so they will be modified by the item's affine transformation. The width_in_pixels, height_in_pixels, x_in_pixels, and y_in_pixels object arguments can be used to modify this behavior. If one of these arguments is TRUE, then the corresponding scaling or translation value will not be affected lengthwise by the pixbuf item's affine transformation.

For example, consider a pixbuf item whose size is (300, 200). If the item is modified with a scaling transformation of (0.5, 2.0) but the width_in_pixels is set to TRUE, then the item will appear to be (300, 400) pixels in size. This means that in this case the item's affine transformation only applies to the height value, while the width value is kept in absolute pixels.

Likewise, consider a pixbuf item whose (x, y) arguments are set to (30, 40). If the item is then modified by the same scaling transformation of (0.5, 2.0) but the y_in_pixels argument is set to TRUE, then the image's upper-left corner will appear to be at position (15, 40). In this case, the affine transformation is applied only to the x offset, while the y offset is kept in absolute pixels.

In short, these arguments control whether a particular dimension of a pixbuf item is scaled or not in the normal way by the item's affine transformation.

Resource Management

When you set the GdkPixbuf structure that a GnomeCanvasPixbuf item will use by setting the pixbuf argument, a reference count will be added to that GdkPixbuf structure. When the pixbuf item no longer needs the GdkPixbuf structure, such as when the item is destroyed or when a new pixbuf structure is passed to it, then the old GdkPixbuf structure will be automatically unreferenced.

This means that if an application just needs to load a pixbuf image and set it into a pixbuf canvas item, it can do the following to ‘forget’ about the pixbuf structure:

GdkPixbuf *pixbuf; GnomeCanvasItem *item; pixbuf = gdk_pixbuf_new_from_file ("foo.png"); g_assert (pixbuf != NULL); item = gnome_canvas_item_new (gnome_canvas_root (my_canvas), gnome_canvas_pixbuf_get_type(), "pixbuf", pixbuf, NULL); gdk_pixbuf_unref (pixbuf);

After this happens, the reference count of the pixbuf structure will be 1: the gdk_pixbuf_new_from_file() function creates it with a reference count of 1, then setting the pixbuf argument of the GnomeCanvasPixbuf item increases it to 2, and then it is decremented to 1 by the call to gdk_pixbuf_unref(). When the canvas item is destroyed, it will automatically unreference the pixbuf structure again, causing its reference count to drop to zero and thus be freed.

GNOME_CANVAS_PIXBUF()

#define     GNOME_CANVAS_PIXBUF(obj)

Casts a GtkOjbect to a GnomeCanvasPixbuf.