<refentry id="GnomeCanvasPixbuf">
<refmeta>
<refentrytitle>GnomeCanvasPixbuf</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK-PIXBUF Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>GnomeCanvasPixbuf</refname><refpurpose>Canvas item to display <link linkend="GdkPixbuf">GdkPixbuf</link> images.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gdk-pixbuf/gdk-pixbuf.h&gt;


#define     <link linkend="GNOME-CANVAS-PIXBUF-CAPS">GNOME_CANVAS_PIXBUF</link>             (obj)


</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
  <para>
    This canvas item displays <link linkend="GdkPixbuf">GdkPixbuf</link> images.  It handles full
    affine transformations in both GDK and antialiased modes, and also
    supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
    url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
    translation semantics for absolute pixel values.
  </para>

  <para>
    <link linkend="GdkPixbuf">GdkPixbuf</link> structures may be shared among different pixbuf canvas
    items; the pixbuf item uses <link linkend="GdkPixbuf">GdkPixbuf</link>'s reference counting
    functions for this.
  </para>

  <refsect2>
    <title>Custom Scaling and Translation</title>

    <para>
      In addition to the normal affine transformations supported by
      canvas items, the <link linkend="GnomeCanvasPixbuf">GnomeCanvasPixbuf</link> 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.
    </para>

    <para>
      By default, the pixbuf canvas item will attain the size in units
      of the <link linkend="GdkPixbuf">GdkPixbuf</link> it contains.  If a <link linkend="GnomeCanvasPixbuf">GnomeCanvasPixbuf</link> is
      configured to use a <link linkend="GdkPixbuf">GdkPixbuf</link> 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.
    </para>

    <para>
      To set custom width and height values, you must set the <link
      linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
      linkend="GnomeCanvasPixbuf--height-set">height_set</link>
      arguments to <literal>TRUE</literal>, and then set the <link
      linkend="GnomeCanvasPixbuf--width">width</link> or <link
      linkend="GnomeCanvasPixbuf--height">height</link> 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 <literal>FALSE</literal> by default so that the pixbuf item will
      attain a size in units equal to the size in pixels of the
      <link linkend="GdkPixbuf">GdkPixbuf</link> that the item contains.
    </para>

    <para>
      The custom translation offsets are controlled by the <link
      linkend="GnomeCanvasPixbuf--x">x</link> and <link
      linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
      upper-left vertex of the image will be translated by the
      specified distance, aligned with the item's local coordinate
      system.
    </para>
  </refsect2>

  <refsect2>
    <title>Absolute Pixel Scaling and Translation</title>

    <para>
      The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
      Graphics</ulink> specification (SVG) of the <ulink
      url="http://www.w3.org">World Wide Web Consortium</ulink> also
      allows images to be translated and scaled by absolute pixel
      values that are independent of an item's normal affine
      transformation.
    </para>

    <para>
      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 <link
      linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
      <link
      linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
      <link
      linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
      <link
      linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
      object arguments can be used to modify this behavior.  If one of
      these arguments is <literal>TRUE</literal>, then the corresponding scaling or
      translation value will not be affected lengthwise by the pixbuf
      item's affine transformation.
    </para>

    <para>
      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 <link
      linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
      is set to <literal>TRUE</literal>, 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.
    </para>

    <para>
      Likewise, consider a pixbuf item whose (<link
      linkend="GnomeCanvasPixbuf--x">x</link>, <link
      linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
      (30, 40).  If the item is then modified by the same scaling
      transformation of (0.5, 2.0) but the <link
      linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
      argument is set to <literal>TRUE</literal>, 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.
    </para>

    <para>
      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.
    </para>
  </refsect2>

  <refsect2>
    <title>Resource Management</title>

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

    <para>
      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 &lsquo;forget&rsquo; about the pixbuf structure:

      <programlisting>
	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),
				      <link linkend="gnome-canvas-pixbuf-get-type">gnome_canvas_pixbuf_get_type</link>(),
				      "pixbuf", pixbuf,
				      NULL);
	gdk_pixbuf_unref (pixbuf);
      </programlisting>
    </para>

    <para>
      After this happens, the reference count of the pixbuf structure
      will be 1:  the <link linkend="gdk-pixbuf-new-from-file">gdk_pixbuf_new_from_file</link>() function creates it
      with a reference count of 1, then setting the <link
      linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
      the <link linkend="GnomeCanvasPixbuf">GnomeCanvasPixbuf</link> item increases it to 2, and then it is
      decremented to 1 by the call to <link linkend="gdk-pixbuf-unref">gdk_pixbuf_unref</link>().  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.
    </para>
  </refsect2>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="GNOME-CANVAS-PIXBUF-CAPS">GNOME_CANVAS_PIXBUF()</title>
<programlisting>#define     GNOME_CANVAS_PIXBUF(obj)</programlisting>
  <para>
    Casts a <link linkend="GtkOjbect">GtkOjbect</link> to a <link linkend="GnomeCanvasPixbuf">GnomeCanvasPixbuf</link>.
  </para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>obj</parameter>&nbsp;:</entry>
<entry>A GTK+ object.


</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>



<refsect1>
<title>See Also</title>
  <para>
    <link linkend="GnomeCanvas">GnomeCanvas</link>, <link linkend="GdkPixbuf">GdkPixbuf</link>
  </para>
</refsect1>

</refentry>
