Pileus Git - ~andy/gtk/blob - docs/reference/gdk-pixbuf/tmpl/gdk-pixbuf-unused.sgml

   1 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Long_Description ##### -->
   2   <para>
   3     The functions in this section allow you to take the image data
   4     from a GDK drawable and dump it into a #GdkPixbuf.  This can be
   5     used for screenshots and other special effects.  Note that these
   6     operations can be expensive, since the image data has to be
   7     transferred from the X server to the client program and converted.
   8   </para>
   9
  10
  11 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Short_Description ##### -->
  12 Getting parts of a drawable's image data into a pixbuf.
  13
  14
  15 <!-- ##### SECTION ./tmpl/from-drawables.sgml:Title ##### -->
  16 Drawables to Pixbufs
  17
  18
  19 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Long_Description ##### -->
  20   <para>
  21     This canvas item displays #GdkPixbuf images.  It handles full
  22     affine transformations in both GDK and antialiased modes, and also
  23     supports the <ulink url="http://www.w3.org">W3C</ulink>'s <ulink
  24     url="http://www.w3.org/Graphics/SVG/">SVG</ulink>-like scaling and
  25     translation semantics for absolute pixel values.
  26   </para>
  27
  28   <para>
  29     #GdkPixbuf structures may be shared among different pixbuf canvas
  30     items; the pixbuf item uses #GdkPixbuf's reference counting
  31     functions for this.
  32   </para>
  33
  34   <refsect2>
  35     <title>Custom Scaling and Translation</title>
  36
  37     <para>
  38       In addition to the normal affine transformations supported by
  39       canvas items, the #GnomeCanvasPixbuf item supports independent
  40       object arguments for scaling and translation.  This is useful
  41       for explicitly setting a size to which the pixbuf's image will
  42       be scaled, and for specifying translation offsets that take
  43       place in the item's local coordinate system.
  44     </para>
  45
  46     <para>
  47       By default, the pixbuf canvas item will attain the size in units
  48       of the #GdkPixbuf it contains.  If a #GnomeCanvasPixbuf is
  49       configured to use a #GdkPixbuf that has a size of 300 by 200
  50       pixels, then the pixbuf item will automatically obtain a size of
  51       300 by 200 units in the item's local coordinate system.  If the
  52       item is transformed with a scaling transformation of (0.5, 2.0),
  53       then the final image size will be of 150 by 400 pixels.
  54     </para>
  55
  56     <para>
  57       To set custom width and height values, you must set the <link
  58       linkend="GnomeCanvasPixbuf--width-set">width_set</link> or <link
  59       linkend="GnomeCanvasPixbuf--height-set">height_set</link>
  60       arguments to %TRUE, and then set the <link
  61       linkend="GnomeCanvasPixbuf--width">width</link> or <link
  62       linkend="GnomeCanvasPixbuf--height">height</link> arguments to
  63       the desired values.  The former two arguments control whether
  64       the latter two are used when computing the final image's size;
  65       they are both %FALSE by default so that the pixbuf item will
  66       attain a size in units equal to the size in pixels of the
  67       #GdkPixbuf that the item contains.
  68     </para>
  69
  70     <para>
  71       The custom translation offsets are controlled by the <link
  72       linkend="GnomeCanvasPixbuf--x">x</link> and <link
  73       linkend="GnomeCanvasPixbuf--y">y</link> arguments.  The logical
  74       upper-left vertex of the image will be translated by the
  75       specified distance, aligned with the item's local coordinate
  76       system.
  77     </para>
  78   </refsect2>
  79
  80   <refsect2>
  81     <title>Absolute Pixel Scaling and Translation</title>
  82
  83     <para>
  84       The <ulink url="http://www.w3.org/Graphics/SVG/">Scalable Vector
  85       Graphics</ulink> specification (SVG) of the <ulink
  86       url="http://www.w3.org">World Wide Web Consortium</ulink> also
  87       allows images to be translated and scaled by absolute pixel
  88       values that are independent of an item's normal affine
  89       transformation.
  90     </para>
  91
  92     <para>
  93       Normally, the pixbuf item's translation and scaling arguments
  94       are interpreted in units, so they will be modified by the item's
  95       affine transformation.  The <link
  96       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>,
  97       <link
  98       linkend="GnomeCanvasPixbuf--height-in-pixels">height_in_pixels</link>,
  99       <link
 100       linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>, and
 101       <link
 102       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 103       object arguments can be used to modify this behavior.  If one of
 104       these arguments is %TRUE, then the corresponding scaling or
 105       translation value will not be affected lengthwise by the pixbuf
 106       item's affine transformation.
 107     </para>
 108
 109     <para>
 110       For example, consider a pixbuf item whose size is (300, 200).
 111       If the item is modified with a scaling transformation of (0.5,
 112       2.0) but the <link
 113       linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 114       is set to %TRUE, then the item will appear to be (300, 400)
 115       pixels in size.  This means that in this case the item's affine
 116       transformation only applies to the height value, while the width
 117       value is kept in absolute pixels.
 118     </para>
 119
 120     <para>
 121       Likewise, consider a pixbuf item whose (<link
 122       linkend="GnomeCanvasPixbuf--x">x</link>, <link
 123       linkend="GnomeCanvasPixbuf--y">y</link>) arguments are set to
 124       (30, 40).  If the item is then modified by the same scaling
 125       transformation of (0.5, 2.0) but the <link
 126       linkend="GnomeCanvasPixbuf--y-in-pixels">y_in_pixels</link>
 127       argument is set to %TRUE, then the image's upper-left corner
 128       will appear to be at position (15, 40).  In this case, the
 129       affine transformation is applied only to the x offset, while the
 130       y offset is kept in absolute pixels.
 131     </para>
 132
 133     <para>
 134       In short, these arguments control whether a particular dimension
 135       of a pixbuf item is scaled or not in the normal way by the
 136       item's affine transformation.
 137     </para>
 138   </refsect2>
 139
 140   <refsect2>
 141     <title>Resource Management</title>
 142
 143     <para>
 144       When you set the #GdkPixbuf structure that a #GnomeCanvasPixbuf
 145       item will use by setting the <link
 146       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument, a
 147       reference count will be added to that #GdkPixbuf structure.
 148       When the pixbuf item no longer needs the #GdkPixbuf structure,
 149       such as when the item is destroyed or when a new pixbuf
 150       structure is passed to it, then the old #GdkPixbuf structure
 151       will be automatically unreferenced.
 152     </para>
 153
 154     <para>
 155       This means that if an application just needs to load a pixbuf
 156       image and set it into a pixbuf canvas item, it can do the
 157       following to &lsquo;forget&rsquo; about the pixbuf structure:
 158
 159       <programlisting>
 160         GdkPixbuf *pixbuf;
 161         GnomeCanvasItem *item;
 162
 163         pixbuf = gdk_pixbuf_new_from_file ("foo.png");
 164         g_assert (pixbuf != NULL);
 165
 166         item = gnome_canvas_item_new (gnome_canvas_root (my_canvas),
 167                                       gnome_canvas_pixbuf_get_type (),
 168                                       "pixbuf", pixbuf,
 169                                       NULL);
 170         gdk_pixbuf_unref (pixbuf);
 171       </programlisting>
 172     </para>
 173
 174     <para>
 175       After this happens, the reference count of the pixbuf structure
 176       will be 1:  the gdk_pixbuf_new_from_file() function creates it
 177       with a reference count of 1, then setting the <link
 178       linkend="GnomeCanvasPixbuf--pixbuf">pixbuf</link> argument of
 179       the #GnomeCanvasPixbuf item increases it to 2, and then it is
 180       decremented to 1 by the call to gdk_pixbuf_unref().  When the
 181       canvas item is destroyed, it will automatically unreference the
 182       pixbuf structure again, causing its reference count to drop to
 183       zero and thus be freed.
 184     </para>
 185   </refsect2>
 186
 187
 188 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:See_Also ##### -->
 189   <para>
 190     #GnomeCanvas, #GdkPixbuf
 191   </para>
 192
 193
 194 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Short_Description ##### -->
 195 Canvas item to display #GdkPixbuf images.
 196
 197
 198 <!-- ##### SECTION ./tmpl/gnome-canvas-pixbuf.sgml:Title ##### -->
 199 GnomeCanvasPixbuf
 200
 201
 202 <!-- ##### SECTION ./tmpl/rendering.sgml:Long_Description ##### -->
 203   <para>
 204     The &gdk-pixbuf; library provides several convenience functions to
 205     render pixbufs to GDK drawables.  It uses the GdkRGB to render the
 206     image data.
 207   </para>
 208
 209   <para>
 210     At this point there is not a standard alpha channel extension for
 211     the X Window System, so it is not possible to use full opacity
 212     information when painting images to arbitrary drawables.  The
 213     &gdk-pixbuf; convenience functions will threshold the opacity
 214     information to create a bi-level clipping mask (black and white),
 215     and use that to draw the image onto a drawable.
 216   </para>
 217
 218   <important>
 219     <para>
 220       Since these functions use GdkRGB for rendering, you must
 221       initialize GdkRGB before using any of them.  You can do this by
 222       calling gdk_rgb_init() near the beginning of your program.
 223     </para>
 224   </important>
 225
 226
 227 <!-- ##### SECTION ./tmpl/rendering.sgml:See_Also ##### -->
 228   <para>
 229     GdkRGB
 230   </para>
 231
 232
 233 <!-- ##### SECTION ./tmpl/rendering.sgml:Short_Description ##### -->
 234 Rendering a pixbuf to a GDK drawable.
 235
 236
 237 <!-- ##### SECTION ./tmpl/rendering.sgml:Title ##### -->
 238 Rendering
 239
 240
 241 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Long_Description ##### -->
 242   <para>
 243     The functions in this section allow you to take the image data
 244     from an X drawable and dump it into a #GdkPixbuf.  This can be
 245     used for screenshots and other special effects.  Note that these
 246     operations can be expensive, since the image data has to be
 247     transferred from the X server to the client program and converted.
 248   </para>
 249
 250   <para>
 251     These functions are analogous to those for the Gdk version of
 252     &gdk-pixbuf;.
 253   </para>
 254
 255
 256 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:See_Also ##### -->
 257 <para>
 258
 259 </para>
 260
 261
 262 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Short_Description ##### -->
 263 Getting parts of an X drawable's image data into a pixbuf.
 264
 265
 266 <!-- ##### SECTION ./tmpl/xlib-from-drawables.sgml:Title ##### -->
 267 X Drawables to Pixbufs
 268
 269
 270 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Long_Description ##### -->
 271   <para>
 272     In addition to the normal Gdk-specific functions, the &gdk-pixbuf;
 273     package provides a small library that lets Xlib-only applications
 274     use #GdkPixbuf structures and render them to X drawables.  The
 275     functions in this section are used to initialize the &gdk-pixbuf;
 276     Xlib library.  This library must be initialized near the beginning
 277     or the program or before calling any of the other &gdk-pixbuf;
 278     Xlib functions; it cannot be initialized automatically since
 279     Xlib-only applications do not call gdk_rgb_init() like GNOME
 280     applications do.
 281   </para>
 282
 283
 284 <!-- ##### SECTION ./tmpl/xlib-init.sgml:See_Also ##### -->
 285   <para>
 286     XlibRGB
 287   </para>
 288
 289
 290 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Short_Description ##### -->
 291 Initializing the &gdk-pixbuf; Xlib library.
 292
 293
 294 <!-- ##### SECTION ./tmpl/xlib-init.sgml:Title ##### -->
 295 &gdk-pixbuf; Xlib initialization
 296
 297
 298 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Long_Description ##### -->
 299   <para>
 300     The &gdk-pixbuf; Xlib library provides several convenience
 301     functions to render pixbufs to X drawables.  It uses XlibRGB to
 302     render the image data.
 303   </para>
 304
 305   <para>
 306     These functions are analogous to those for the Gdk version of
 307     &gdk-pixbuf;.
 308   </para>
 309
 310
 311 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:See_Also ##### -->
 312 <para>
 313
 314 </para>
 315
 316
 317 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Short_Description ##### -->
 318 Rendering a pixbuf to an X drawable.
 319
 320
 321 <!-- ##### SECTION ./tmpl/xlib-rendering.sgml:Title ##### -->
 322 Xlib Rendering
 323
 324
 325 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Long_Description ##### -->
 326   <para>
 327     The XlibRGB set of functions is a port of the GdkRGB library to
 328     use plain Xlib and X drawables.  You can use these functions to
 329     render RGB buffers into drawables very quickly with high-quality
 330     dithering.
 331   </para>
 332
 333
 334 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:See_Also ##### -->
 335   <para>
 336     GdkRGB
 337   </para>
 338
 339
 340 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Short_Description ##### -->
 341 Functions for rendering RGB buffers to X drawables.
 342
 343
 344 <!-- ##### SECTION ./tmpl/xlib-rgb.sgml:Title ##### -->
 345 XlibRGB
 346
 347
 348 <!-- ##### MACRO GDK_PIXBUF_LOADER ##### -->
 349   <para>
 350     Casts a #GtkObject to a #GdkPixbufLoader.
 351   </para>
 352
 353 @obj: A GTK+ object.
 354
 355 <!-- ##### MACRO GNOME_CANVAS_PIXBUF ##### -->
 356   <para>
 357     Casts a #GtkOjbect to a #GnomeCanvasPixbuf.
 358   </para>
 359
 360 @obj: A GTK+ object.
 361
 362 <!-- ##### STRUCT GdkPixbufFrame ##### -->
 363 <para>
 364  This object describes an individual frame of an animation.
 365 </para>
 366
 367
 368 <!-- ##### ENUM GdkPixbufFrameAction ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @GDK_PIXBUF_FRAME_RETAIN:
 374 @GDK_PIXBUF_FRAME_DISPOSE:
 375 @GDK_PIXBUF_FRAME_REVERT:
 376
 377 <!-- ##### USER_FUNCTION GdkPixbufLastUnref ##### -->
 378   <para>
 379     A function of this type can be used to override the default
 380     operation when a pixbuf loses its last reference, i.e. when
 381     gdk_pixbuf_unref() is called on a #GdkPixbuf structure that has a
 382     reference count of 1.  This function should determine whether to
 383     finalize the pixbuf by calling gdk_pixbuf_finalize(), or whether
 384     to just resume normal execution.  The last unref handler for a
 385     #GdkPixbuf can be set using the
 386     gdk_pixbuf_set_last_unref_handler() function.  By default, pixbufs
 387     will be finalized automatically if no last unref handler has been
 388     defined.
 389   </para>
 390
 391 @pixbuf: The pixbuf that is losing its last reference.
 392 @data: User closure data.
 393
 394 <!-- ##### ARG GnomeCanvasPixbuf:height ##### -->
 395   <para>
 396     Indicates the height the pixbuf will be scaled to.  This argument
 397     will only be used if the <link
 398     linkend="GnomeCanvasPixbuf--height-set">height_set</link> argument
 399     is %TRUE.  Works in the same way as the <link
 400     linkend="GnomeCanvasPixbuf--width">width</link> argument.
 401   </para>
 402
 403
 404 <!-- ##### ARG GnomeCanvasPixbuf:height-in-pixels ##### -->
 405   <para>
 406     Works in the same way as the <link
 407     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 408     argument.  The default is %FALSE.
 409   </para>
 410
 411
 412 <!-- ##### ARG GnomeCanvasPixbuf:height-pixels ##### -->
 413 <para>
 414
 415 </para>
 416
 417
 418 <!-- ##### ARG GnomeCanvasPixbuf:height-set ##### -->
 419   <para>
 420     Determines whether the <link
 421     linkend="GnomeCanvasPixbuf--height">height</link> argument is
 422     taken into account when scaling the pixbuf item.  Works in the
 423     same way as the <link
 424     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument.
 425     The default is %FALSE.
 426   </para>
 427
 428
 429 <!-- ##### ARG GnomeCanvasPixbuf:pixbuf ##### -->
 430   <para>
 431     Contains a pointer to a #GdkPixbuf structure that will be used by
 432     the pixbuf canvas item as an image source.  When a pixbuf is set
 433     its reference count is incremented; if the pixbuf item kept a
 434     pointer to another #GdkPixbuf structure, the reference count of
 435     this structure will be decremented.  Also, the GdkPixbuf's
 436     reference count will automatically be decremented when the
 437     #GnomeCanvasPixbuf item is destroyed.  When a pixbuf is queried, a
 438     reference count will not be added to the return value; you must do
 439     this yourself if you intend to keep the pixbuf structure around.
 440   </para>
 441
 442
 443 <!-- ##### ARG GnomeCanvasPixbuf:width ##### -->
 444   <para>
 445     Indicates the width the pixbuf will be scaled to.  This argument
 446     will only be used if the <link
 447     linkend="GnomeCanvasPixbuf--width-set">width_set</link> argument
 448     is %TRUE.  If the <link
 449     linkend="GnomeCanvasPixbuf--width-in-pixels">width_in_pixels</link>
 450     argument is %FALSE, the width will be taken to be in canvas units,
 451     and thus will be scaled along with the canvas item's affine
 452     transformation.  If width_in_pixels is %TRUE, the width will be
 453     taken to be in pixels, and will visually remain a constant size
 454     even if the item's affine transformation changes.
 455   </para>
 456
 457
 458 <!-- ##### ARG GnomeCanvasPixbuf:width-in-pixels ##### -->
 459   <para>
 460     If this argument is %TRUE, then the width of the pixbuf will be
 461     considered to be in pixels, that is, it will not be visually
 462     scaled even if the item's affine transformation changes.  If this
 463     is %FALSE, then the width of the pixbuf will be considered to be
 464     in canvas units, and so will be scaled normally by affine
 465     transformations.  The default is %FALSE.
 466   </para>
 467
 468
 469 <!-- ##### ARG GnomeCanvasPixbuf:width-pixels ##### -->
 470 <para>
 471
 472 </para>
 473
 474
 475 <!-- ##### ARG GnomeCanvasPixbuf:width-set ##### -->
 476   <para>
 477     Determines whether the <link
 478     linkend="GnomeCanvasPixbuf--width">width</link> argument is taken
 479     into account when scaling the pixbuf item.  If this argument is
 480     %FALSE, then the width value of the pixbuf will be used instead.
 481     This argument is %FALSE by default.
 482   </para>
 483
 484
 485 <!-- ##### ARG GnomeCanvasPixbuf:x ##### -->
 486   <para>
 487     Indicates the horizontal translation offset of the pixbuf item's
 488     image.  This offset may not actually appear horizontal, since it
 489     will be affected by the item's affine transformation.  The default
 490     is 0.0.
 491   </para>
 492
 493
 494 <!-- ##### ARG GnomeCanvasPixbuf:x-in-pixels ##### -->
 495   <para>
 496     If this argument is %TRUE, the pixbuf's translation with respect
 497     to its logical origin in item-relative coordinates will be in
 498     pixels, that is, the visible offset will not change even if the
 499     item's affine transformation changes.  If it is %FALSE, the
 500     pixbuf's translation will be taken to be in canvas units, and thus
 501     will change along with the item's affine transformation.  The
 502     default is %FALSE.
 503   </para>
 504
 505
 506 <!-- ##### ARG GnomeCanvasPixbuf:x-pixels ##### -->
 507 <para>
 508
 509 </para>
 510
 511
 512 <!-- ##### ARG GnomeCanvasPixbuf:x-set ##### -->
 513   <para>
 514     Determines whether the <link
 515     linkend="GnomeCanvasPixbuf--x">x</link> argument is used to
 516     translate the pixbuf from its logical origin in item-relative
 517     coordinates.
 518   </para>
 519
 520
 521 <!-- ##### ARG GnomeCanvasPixbuf:y ##### -->
 522   <para>
 523     Indicates the vertical translation offset of the pixbuf item's
 524     image.  Works in the same way as the <link
 525     linkend="GnomeCanvasPixbuf--x">x</link> argument.  The default is
 526     0.0.
 527   </para>
 528
 529
 530 <!-- ##### ARG GnomeCanvasPixbuf:y-in-pixels ##### -->
 531   <para>
 532     Works in the same way as the <link
 533     linkend="GnomeCanvasPixbuf--x-in-pixels">x_in_pixels</link>
 534     argument, but controls whether the <link
 535     linkend="GnomeCanvasPixbuf--y">y</link> translation offset is
 536     scaled or not.  The default is %FALSE.
 537   </para>
 538
 539 <!--
 540 Local variables:
 541 mode: sgml
 542 sgml-parent-document: ("../gdk-pixbuf.sgml" "book" "refsect2" "")
 543 End:
 544 -->
 545
 546
 547 <!-- ##### ARG GnomeCanvasPixbuf:y-pixels ##### -->
 548 <para>
 549
 550 </para>
 551
 552
 553 <!-- ##### ARG GnomeCanvasPixbuf:y-set ##### -->
 554   <para>
 555     Determines whether the <link
 556     linkend="GnomeCanvasPixbuf--y">y</link> argument is used to
 557     translate the pixbuf from its logical origin in item-relative
 558     coordinates.  Works in the same way as the <link
 559     linkend="GnomeCanvasPixbuf--x-set">x_set</link> argument.  The
 560     default is %FALSE.
 561   </para>
 562
 563