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