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

   1 <!-- ##### SECTION Title ##### -->
   2 Images
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 A client-side area for bit-mapped graphics
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GdkImage type represents an area for drawing graphics.
  10 It has now been superceded to a large extent by the much more flexible
  11 <link linkend="gdk-GdkRGB">GdkRGB</link> functions.
  12 </para>
  13 <para>
  14 To create an empty #GdkImage use gdk_image_new().
  15 To create an image from part of a #GdkWindow use gdk_drawable_get_image().
  16 </para>
  17 <para>
  18 The image can be manipulated with gdk_image_get_pixel() and
  19 gdk_image_put_pixel(), or alternatively by changing the actual pixel data.
  20 Though manipulating the pixel data requires complicated code to cope with
  21 the different formats that may be used.
  22 </para>
  23 <para>
  24 To draw a #GdkImage in a #GdkWindow or #GdkPixmap use gdk_draw_image().
  25 </para>
  26 <para>
  27 To destroy a #GdkImage use g_object_unref().
  28 </para>
  29
  30 <!-- ##### SECTION See_Also ##### -->
  31 <para>
  32 <variablelist>
  33
  34 <varlistentry>
  35 <term><link linkend="gdk-Bitmaps-and-Pixmaps">Bitmaps and Pixmaps</link></term>
  36 <listitem><para>
  37 Graphics which are stored on the X Windows server.
  38 Since these are stored on the server they can be drawn very quickly, and all
  39 of the <link linkend="gdk-Drawing-Primitives">Drawing Primitives</link> can be
  40 used to draw on them. Their main disadvantage is that manipulating individual
  41 pixels can be very slow.
  42 </para></listitem>
  43 </varlistentry>
  44
  45 <varlistentry>
  46 <term><link linkend="gdk-GdkRGB">GdkRGB</link></term>
  47 <listitem><para>
  48 Built on top of #GdkImage, this provides much more functionality,
  49 including the dithering of colors to produce better output on low-color
  50 displays.
  51 </para></listitem>
  52 </varlistentry>
  53
  54 </variablelist>
  55 </para>
  56
  57 <!-- ##### SECTION Stability_Level ##### -->
  58
  59
  60 <!-- ##### SECTION Image ##### -->
  61
  62
  63 <!-- ##### STRUCT GdkImage ##### -->
  64 <para>
  65 The #GdkImage struct contains information on the image and the pixel data.
  66 </para>
  67
  68 @parent_instance: the parent instance
  69 @type: the type of the image.
  70 @visual: the visual.
  71 @byte_order: the byte order.
  72 @width: the width of the image in pixels.
  73 @height: the height of the image in pixels.
  74 @depth: the depth of the image, i.e. the number of bits per pixel.
  75 @bpp: the number of bytes per pixel.
  76 @bpl: the number of bytes per line of the image.
  77 @bits_per_pixel: the number of bits per pixel.
  78 @mem: the pixel data.
  79 @colormap: the #GdkColormap associated with the image
  80
  81 <!-- ##### FUNCTION gdk_image_new ##### -->
  82 <para>
  83 Creates a new #GdkImage.
  84 </para>
  85
  86 @type: the type of the #GdkImage, one of %GDK_IMAGE_NORMAL, %GDK_IMAGE_SHARED
  87 and %GDK_IMAGE_FASTEST. %GDK_IMAGE_FASTEST is probably the best choice, since
  88 it will try creating a %GDK_IMAGE_SHARED image first and if that fails it will
  89 then use %GDK_IMAGE_NORMAL.
  90 @visual: the #GdkVisual to use for the image.
  91 @width: the width of the image in pixels.
  92 @height: the height of the image in pixels.
  93 @Returns: a new #GdkImage, or %NULL if the image could not be created.
  94
  95
  96 <!-- ##### ENUM GdkImageType ##### -->
  97 <para>
  98 Specifies the type of a #GdkImage.
  99 </para>
 100
 101 @GDK_IMAGE_NORMAL: The original X image type, which is quite slow since the
 102 image has to be transferred from the client to the server to display it.
 103 @GDK_IMAGE_SHARED: A faster image type, which uses shared memory to transfer
 104 the image data between client and server. However this will only be available
 105 if client and server are on the same machine and the shared memory extension
 106 is supported by the server.
 107 @GDK_IMAGE_FASTEST: Specifies that %GDK_IMAGE_SHARED should be tried first,
 108 and if that fails then %GDK_IMAGE_NORMAL will be used.
 109
 110 <!-- ##### FUNCTION gdk_image_get_colormap ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @image:
 116 @Returns:
 117
 118
 119 <!-- ##### FUNCTION gdk_image_set_colormap ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @image:
 125 @colormap:
 126
 127
 128 <!-- ##### FUNCTION gdk_image_put_pixel ##### -->
 129 <para>
 130 Sets a pixel in a #GdkImage to a given pixel value.
 131 </para>
 132
 133 @image: a #GdkImage.
 134 @x: the x coordinate of the pixel to set.
 135 @y: the y coordinate of the pixel to set.
 136 @pixel: the pixel value to set.
 137
 138
 139 <!-- ##### FUNCTION gdk_image_get_pixel ##### -->
 140 <para>
 141 Gets a pixel value at a specified position in a #GdkImage.
 142 </para>
 143
 144 @image: a #GdkImage.
 145 @x: the x coordinate of the pixel to get.
 146 @y: the y coordinate of the pixel to get.
 147 @Returns: the pixel value at the given position.
 148
 149