1. ------------------------------------------------------------------------------ 
  2. --                  GtkAda - Ada95 binding for Gtk+/Gnome                   -- 
  3. --                                                                          -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  This object provides image manipulation routines. 
  26. -- 
  27. --  The following image formats are known, but some depend on external 
  28. --  libraries for the proper loading of files (indicated with * in the list): 
  29. --     PNG*, JPEG*, TIFF*, GIF, XPM, PNM, Sun raster file (ras), ico, 
  30. --     bmp. 
  31. -- 
  32. --  With this package, you can load images from file, display them on the 
  33. --  screen, re-scale them and compose them with other images. 
  34. --  All the functions fully support alpha channels (opacity). 
  35. -- 
  36. --  Different filters are provided, depending on the quality of output you 
  37. --  expect and the speed you need. 
  38. --  </description> 
  39. --  <c_version>1.3.11</c_version> 
  40. --  <group>Gdk, the low-level API</group> 
  41. --  <testgtk>create_pixbuf.adb</testgtk> 
  42.  
  43. with Interfaces.C.Strings; 
  44. with System; 
  45. with Cairo; 
  46. with Glib; use Glib; 
  47. with Glib.Error; use Glib.Error; 
  48. with Glib.Object; 
  49. with Gdk.Display; 
  50.  
  51. package Gdk.Pixbuf is 
  52.  
  53.    type Gdk_Pixbuf_Record is new Glib.Object.GObject_Record with private; 
  54.  
  55.    type Gdk_Pixbuf is access all Gdk_Pixbuf_Record'Class; 
  56.    --  A very efficient client-side pixmap. 
  57.    --  This type can be adapted to all the possible screen depths (number of 
  58.    --  bits per pixel), and the algorithms are extremely efficient. 
  59.    --  You can also load a pixbuf directly from an external file in one of 
  60.    --  the standard image formats. 
  61.  
  62.    Null_Pixbuf : constant Gdk_Pixbuf := null; 
  63.  
  64.    type Gdk_Pixbuf_Animation is new Glib.C_Proxy; 
  65.    --  Type used for animations. 
  66.  
  67.    type Gdk_Pixbuf_Animation_Iter is new Glib.C_Proxy; 
  68.    --  Type used to iterate through an animation. 
  69.  
  70.    type Alpha_Mode is (Alpha_Bilevel, Alpha_Full); 
  71.    --  Alpha compositing mode. 
  72.    --  This indicates how the alpha channel (for opacity) is handled when 
  73.    --  rendering. 
  74.    pragma Convention (C, Alpha_Mode); 
  75.  
  76.    type Gdk_Colorspace is (Colorspace_RGB); 
  77.    --  Type of the image. 
  78.    --  The only possible value is currently RGB, but extensions will 
  79.    --  exist with CMYK, Gray, Lab, ... 
  80.    pragma Convention (C, Gdk_Colorspace); 
  81.  
  82.    type Gdk_Interp_Type is 
  83.      (Interp_Nearest, 
  84.       --  Nearest neighbor. It is the fastest and lowest quality. 
  85.  
  86.       Interp_Tiles, 
  87.       --  Accurate simulation of the Postscript image operator 
  88.       --  without any interpolation enabled; each pixel is rendered as a tiny 
  89.       --  parallelogram of solid color, the edges of which are implemented 
  90.       --  with anti-aliasing. It resembles nearest neighbor for enlargement, 
  91.       --  and bilinear for reduction. 
  92.  
  93.       Interp_Bilinear, 
  94.       --  Bilinear interpolation. For enlargement, it is equivalent to 
  95.       --  point-sampling the ideal bilinear-interpolated image. For reduction, 
  96.       --  it is equivalent to laying down small tiles and integrating over the 
  97.       --  coverage area. 
  98.  
  99.       Interp_Hyper 
  100.       --  Filter_Hyper is the highest quality reconstruction function. It is 
  101.       --  derived from the hyperbolic filters in Wolberg's "Digital Image 
  102.       --  Warping," and is formally defined as the hyperbolic-filter sampling 
  103.       --  the ideal hyperbolic-filter interpolated image (the filter is 
  104.       --  designed to be idempotent for 1:1 pixel mapping). It is the slowest 
  105.       --  and highest quality. 
  106.      ); 
  107.    --  Interpolation methods. 
  108.    pragma Convention (C, Gdk_Interp_Type); 
  109.  
  110.    ------------ 
  111.    -- Errors -- 
  112.    ------------ 
  113.  
  114.    --  Errors defined in the Pixbuf_Error domain: 
  115.  
  116.    Corrupt_Image         : constant := 0; 
  117.    --  image data hosed 
  118.  
  119.    Insufficient_Memory   : constant := 1; 
  120.    --  no mem to load image 
  121.  
  122.    Bad_Option            : constant := 2; 
  123.    --  bad option passed to save routine 
  124.  
  125.    Unknown_Type          : constant := 3; 
  126.    --  unsupported image type 
  127.  
  128.    Unsupported_Operation : constant := 4; 
  129.    --  unsupported operation (load, save) for image type 
  130.  
  131.    Failed                : constant := 5; 
  132.    --  Operation failed. 
  133.  
  134.    type File_Format is (JPEG, PNG, ICO, BMP); 
  135.    --  Possible formats when saving a file. 
  136.  
  137.    type Image_Quality is range 0 .. 100; 
  138.    --  For a JPEG image only, quality of the image in percentage. 
  139.  
  140.    type Alpha_Range is range 0 .. 255; 
  141.    --  Valid values for alpha parameters. 
  142.  
  143.    pragma Convention (C, Alpha_Range); 
  144.    type Gdk_Rgb_Dither is (Dither_None, Dither_Normal, Dither_Max); 
  145.    --  The three kinds of dithering that are implemented in this package: 
  146.    --  - Dither_None: No dithering will be done 
  147.    --  - Dither_Normal: Specifies dithering on 8 bit displays, but not 16-bit. 
  148.    --                   Usually the best choice. 
  149.    --  - Dither_Max: Specifies dithering on every kind of display 
  150.    for Gdk_Rgb_Dither'Size use Glib.Gint'Size; 
  151.  
  152.    type Rgb_Record is record 
  153.       Red, Green, Blue : Glib.Guchar; 
  154.    end record; 
  155.    pragma Convention (C, Rgb_Record); 
  156.  
  157.    --  This is the buffer that will contain the image. You can manipulate each 
  158.    --  byte in it independantly, although there is no high level routine 
  159.    --  to draw lines, circles, ... 
  160.    --  Once you are done drawing into this buffer, you can copy it to any 
  161.    --  drawable on the screen, *if* the widget was created with the correct 
  162.    --  visual and colormap (see above). 
  163.  
  164.    type Unchecked_Rgb_Buffer is array (Glib.Guint) of Rgb_Record; 
  165.    pragma Convention (C, Unchecked_Rgb_Buffer); 
  166.    type Rgb_Buffer_Access is access all Unchecked_Rgb_Buffer; 
  167.    pragma Convention (C, Rgb_Buffer_Access); 
  168.    --  Type used By Get_Pixels to return an array with no 
  169.    --  bound checks that is compatible with C (also known as a flat array). 
  170.  
  171.    -------------- 
  172.    -- Get_Type -- 
  173.    -------------- 
  174.  
  175.    function Get_Type return Glib.GType; 
  176.    --  Return the internal value associated with a Gdk_Pixbuf. 
  177.  
  178.    -------------------------- 
  179.    -- Accessing the fields -- 
  180.    -------------------------- 
  181.  
  182.    function Get_Colorspace (Pixbuf : Gdk_Pixbuf) return Gdk_Colorspace; 
  183.    --  Query the color space of a pixbuf. 
  184.  
  185.    function Get_N_Channels (Pixbuf : Gdk_Pixbuf) return Gint; 
  186.    --  Number of channels in the image. 
  187.  
  188.    function Get_Has_Alpha (Pixbuf : Gdk_Pixbuf) return Boolean; 
  189.    --  Return True if the image has an alpha channel (opacity information). 
  190.  
  191.    function Get_Bits_Per_Sample (Pixbuf : Gdk_Pixbuf) return Gint; 
  192.    --  Number of bits per color sample. 
  193.  
  194.    function Get_Pixels (Pixbuf : Gdk_Pixbuf) return Rgb_Buffer_Access; 
  195.    --  Return a pointer to the pixel data of the image. 
  196.  
  197.    function Get_Width (Pixbuf : Gdk_Pixbuf) return Gint; 
  198.    --  Return the width of the image in pixels. 
  199.  
  200.    function Get_Height (Pixbuf : Gdk_Pixbuf) return Gint; 
  201.    --  Return the height of the image in pixels. 
  202.  
  203.    function Get_Rowstride (Pixbuf : Gdk_Pixbuf) return Gint; 
  204.    --  Return the number of bytes between rows in the image data. 
  205.  
  206.    -------------- 
  207.    -- Creating -- 
  208.    -------------- 
  209.  
  210.    function Gdk_New 
  211.      (Colorspace      : Gdk_Colorspace := Colorspace_RGB; 
  212.       Has_Alpha       : Boolean := False; 
  213.       Bits_Per_Sample : Gint := 8; 
  214.       Width           : Gint; 
  215.       Height          : Gint) return Gdk_Pixbuf; 
  216.    --  Create a blank pixbuf with an optimal row stride and a new buffer. 
  217.    --  The buffer is allocated, but not cleared. 
  218.    --  The reference counting is initialized to 1. 
  219.  
  220.    function Copy (Pixbuf : Gdk_Pixbuf) return Gdk_Pixbuf; 
  221.    --  Copy a pixbuf. 
  222.  
  223.    function Gdk_New_Subpixbuf 
  224.      (Src_Pixbuf : Gdk_Pixbuf; 
  225.       Src_X      : Gint; 
  226.       Src_Y      : Gint; 
  227.       Width      : Gint; 
  228.       Height     : Gint) return Gdk_Pixbuf; 
  229.    --  Create a pixbuf which points to the pixels of another pixbuf 
  230.  
  231.    procedure Gdk_New_From_File 
  232.      (Pixbuf   : out Gdk_Pixbuf; 
  233.       Filename : String; 
  234.       Error    : out GError); 
  235.    --  Load an image from file. 
  236.  
  237.    function Gdk_New_From_Data 
  238.      (Data              : Guchar_Array_Access; 
  239.       Colorspace        : Gdk_Colorspace := Colorspace_RGB; 
  240.       Has_Alpha         : Boolean := False; 
  241.       Bits_Per_Sample   : Gint := 8; 
  242.       Width             : Gint; 
  243.       Height            : Gint; 
  244.       Rowstride         : Gint; 
  245.       Auto_Destroy_Data : Boolean := True) return Gdk_Pixbuf; 
  246.    --  Create a pixbuf out of in-memory image data. 
  247.    --  Currently only RGB images with 8 bits per sample are supported. 
  248.    --  Width and Height must be > 0. 
  249.    --  Rowstride is the distance in bytes between row starts. 
  250.    --  A typical value is 4*Width when there is an Alpha channel. 
  251.    --  If Auto_Destroy_Data is true, passed data will be automatically 
  252.    --  freed when the reference count of the pixbuf reaches 1. 
  253.    --  Otherwise, data is never freed. 
  254.  
  255.    function Gdk_New_From_Xpm_Data 
  256.      (Data : Interfaces.C.Strings.chars_ptr_array) return Gdk_Pixbuf; 
  257.    --  Create an image from a XPM data. 
  258.  
  259.    procedure Fill (Pixbuf : Gdk_Pixbuf; Pixel : Guint32); 
  260.    --  Fill pixbuf with a given pixel value. 
  261.  
  262.    procedure Save 
  263.      (Pixbuf   : Gdk_Pixbuf; 
  264.       Filename : String; 
  265.       Format   : File_Format; 
  266.       Error    : out GError; 
  267.       Quality  : Image_Quality := Image_Quality'Last; 
  268.       Depth    : Integer := 32); 
  269.    --  Save pixbuf to a file. 
  270.    --  Quality is only taken into account for JPEG images. 
  271.    --  Depth is only taken into account for ICO images and can take the values 
  272.    --  16, 24 or 32. 
  273.    --  Error is set to null on success, and set to a GError otherwise. 
  274.  
  275.    function Add_Alpha 
  276.      (Pixbuf           : Gdk_Pixbuf; 
  277.       Substitute_Color : Boolean := False; 
  278.       Red              : Guchar := 0; 
  279.       Green            : Guchar := 0; 
  280.       Blue             : Guchar := 0) return Gdk_Pixbuf; 
  281.    --  Add an alpha channel. 
  282.    --  Return a newly allocated image copied from Pixbuf, but with an 
  283.    --  extra alpha channel. 
  284.    --  If Pixbuf already had an alpha channel, the two images have exactly 
  285.    --  the same contents. 
  286.    --  If Substitute_Color is True, the color (Red, Green, Blue) is 
  287.    --  substituted for zero opacity. 
  288.    --  If Substitute_Color is False, Red, Green and Blue are ignored, and a 
  289.    --  new color is created with zero opacity. 
  290.  
  291.    procedure Copy_Area 
  292.      (Src_Pixbuf  : Gdk_Pixbuf; 
  293.       Src_X       : Gint; 
  294.       Src_Y       : Gint; 
  295.       Width       : Gint; 
  296.       Height      : Gint; 
  297.       Dest_Pixbuf : Gdk_Pixbuf; 
  298.       Dest_X      : Gint; 
  299.       Dest_Y      : Gint); 
  300.    --  Copy a rectangular area from Src_pixbuf to Dest_pixbuf. 
  301.    --  Conversion of pixbuf formats is done automatically. 
  302.  
  303.    procedure Saturate_And_Pixelate 
  304.      (Src        : Gdk_Pixbuf; 
  305.       Dest       : Gdk_Pixbuf; 
  306.       Saturation : Gfloat; 
  307.       Pixelate   : Boolean := True); 
  308.    --  Brighten/darken and optionally make it pixelated-looking. 
  309.  
  310.    --------------- 
  311.    -- Rendering -- 
  312.    --------------- 
  313.  
  314.    function Get_From_Window 
  315.      (Window : Gdk_Window; 
  316.       Src_X  : Gint; 
  317.       Src_Y  : Gint; 
  318.       Width  : Gint; 
  319.       Height : Gint) return Gdk_Pixbuf; 
  320.    function Get_From_Surface 
  321.      (Surface : Cairo.Cairo_Surface; 
  322.       Src_X   : Gint; 
  323.       Src_Y   : Gint; 
  324.       Width   : Gint; 
  325.       Height  : Gint) return Gdk_Pixbuf; 
  326.    --  Transfers image data from a Gdk_Window and converts it to an RGB(A) 
  327.    --  representation inside a Gdk_Pixbuf. In other words, copies 
  328.    --  image data from a server-side drawable to a client-side RGB(A) buffer. 
  329.    --  This allows you to efficiently read individual pixels on the client 
  330.    --  side. 
  331.    -- 
  332.    --  This function will create an RGB pixbuf with 8 bits per channel with 
  333.    --  the same size specified by the Width and Height arguments. The pixbuf 
  334.    --  will contain an alpha channel if the window contains one. 
  335.    -- 
  336.    --  If the window is off the screen, then there is no image data in the 
  337.    --  obscured/offscreen regions to be placed in the pixbuf. The contents 
  338.    --  of portions of the pixbuf corresponding to the offscreen region are 
  339.    --  undefined. 
  340.    -- 
  341.    --  If the window you're obtaining data from is partially obscured by other 
  342.    --  windows, then the contents of the pixbuf areas corresponding to the 
  343.    --  obscured regions are undefined. 
  344.    -- 
  345.    --  If the window is not mapped (typically because it's iconified/minimized 
  346.    --  or not on the current workspace), then Null_Pixbuf will be returned. 
  347.    -- 
  348.    --  If memory can't be allocated for the return value, Null_Pixbuf 
  349.    --  will be returned instead. 
  350.    -- 
  351.    --  (In short, there are several ways this function can fail, and if it 
  352.    --   fails it returns Null_Pixbuf; so check the return value.) 
  353.    -- 
  354.    --  Return value: (transfer full): A newly-created pixbuf with a reference 
  355.    --      count of 1, or Null_Pixbuf on error 
  356.  
  357.    ------------- 
  358.    -- Scaling -- 
  359.    ------------- 
  360.  
  361.    procedure Scale 
  362.      (Src          : Gdk_Pixbuf; 
  363.       Dest         : Gdk_Pixbuf; 
  364.       Dest_X       : Gint; 
  365.       Dest_Y       : Gint; 
  366.       Dest_Width   : Gint; 
  367.       Dest_Height  : Gint; 
  368.       Offset_X     : Gdouble := 0.0; 
  369.       Offset_Y     : Gdouble := 0.0; 
  370.       Scale_X      : Gdouble := 1.0; 
  371.       Scale_Y      : Gdouble := 1.0; 
  372.       Inter_Type   : Gdk_Interp_Type := Interp_Bilinear); 
  373.    --  Transform the source image by scaling by Scale_x and Scale_y then 
  374.    --  translating by Offset_x and Offset_y. 
  375.    --  The image is then rendered in the rectangle (Dest_x, Dest_y, 
  376.    --  Dest_width, Dest_height) of the resulting image onto the destination 
  377.    --  drawable replacing the previous contents. 
  378.  
  379.    procedure Composite 
  380.      (Src           : Gdk_Pixbuf; 
  381.       Dest          : Gdk_Pixbuf; 
  382.       Dest_X        : Gint; 
  383.       Dest_Y        : Gint; 
  384.       Dest_Width    : Gint; 
  385.       Dest_Height   : Gint; 
  386.       Offset_X      : Gdouble := 0.0; 
  387.       Offset_Y      : Gdouble := 0.0; 
  388.       Scale_X       : Gdouble := 1.0; 
  389.       Scale_Y       : Gdouble := 1.0; 
  390.       Inter_Type    : Gdk_Interp_Type := Interp_Bilinear; 
  391.       Overall_Alpha : Alpha_Range := 128); 
  392.    --  Transform the source image by scaling by Scale_X and Scale_Y then 
  393.    --  translating by Offset_X and Offset_Y, then composite the rectangle 
  394.    --  (Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image onto 
  395.    --  the destination drawable. 
  396.  
  397.    procedure Composite_Color 
  398.      (Src           : Gdk_Pixbuf; 
  399.       Dest          : Gdk_Pixbuf; 
  400.       Dest_X        : Gint; 
  401.       Dest_Y        : Gint; 
  402.       Dest_Width    : Gint; 
  403.       Dest_Height   : Gint; 
  404.       Offset_X      : Gdouble := 0.0; 
  405.       Offset_Y      : Gdouble := 0.0; 
  406.       Scale_X       : Gdouble := 1.0; 
  407.       Scale_Y       : Gdouble := 1.0; 
  408.       Inter_Type    : Gdk_Interp_Type := Interp_Bilinear; 
  409.       Overall_Alpha : Alpha_Range := 128; 
  410.       Check_X       : Gint := 0; 
  411.       Check_Y       : Gint := 0; 
  412.       Check_Size    : Gint := 0; 
  413.       Color1        : Guint32 := 0; 
  414.       Color2        : Guint32 := 0); 
  415.    --  Transform the source image by scaling by Scale_x and Scale_y then 
  416.    --  translating by Offset_x and Offset_y, then composites the rectangle 
  417.    --  (Dest_X, Dest_Y, Dest_Width, Dest_Height) of the resulting image with 
  418.    --  a checkboard of the colors Color1 and Color2 and renders it onto the 
  419.    --  destination drawable. 
  420.    --  The origin of checkboard is at (Check_x, Check_y) 
  421.    --  Color1 is the color at the upper left of the check. 
  422.  
  423.    function Scale_Simple 
  424.      (Src           : Gdk_Pixbuf; 
  425.       Dest_Width    : Gint; 
  426.       Dest_Height   : Gint; 
  427.       Inter_Type    : Gdk_Interp_Type := Interp_Bilinear) return Gdk_Pixbuf; 
  428.    --  Scale the Src image to Dest_width x Dest_height and render the result 
  429.    --  into a new pixbuf. 
  430.  
  431.    function Composite_Color_Simple 
  432.      (Src           : Gdk_Pixbuf; 
  433.       Dest_Width    : Gint; 
  434.       Dest_Height   : Gint; 
  435.       Inter_Type    : Gdk_Interp_Type := Interp_Bilinear; 
  436.       Overall_Alpha : Alpha_Range := 128; 
  437.       Color1        : Guint32 := 0; 
  438.       Color2        : Guint32 := 0) return Gdk_Pixbuf; 
  439.    --  Scale Src to Dest_width x Dest_height and composite the result with 
  440.    --  a checkboard of colors Color1 and Color2 and render the result into 
  441.    --  a new pixbuf. 
  442.  
  443.    ----------------------- 
  444.    -- Animation support -- 
  445.    ----------------------- 
  446.  
  447.    function Get_Type_Animation return Glib.GType; 
  448.    --  Return the internal value associated with a Gdk_Pixbuf_Animation. 
  449.  
  450.    procedure Gdk_New_From_File 
  451.      (Animation : out Gdk_Pixbuf_Animation; 
  452.       Filename  : String; 
  453.       Error     : out GError); 
  454.    --  Create a new animation by loading it from a file. 
  455.    --  The file format is detected automatically. If the file's format does not 
  456.    --  support multi-frame images, then an animation with a single frame will 
  457.    --  be created. Possible errors are in the Pixbuf_Error and GFile_Error 
  458.    --  domains. 
  459.    --  On return, Animation is a newly created animation with a reference count 
  460.    --  of 1, or null if any of several error conditions ocurred: the file could 
  461.    --  not be opened, there was no loader for the file's format, there was not 
  462.    --  enough memory to allocate the image buffer, or the image file contained 
  463.    --  invalid data. 
  464.  
  465.    procedure Ref (Animation : Gdk_Pixbuf_Animation); 
  466.    --  Increment the reference counting on the animation. 
  467.  
  468.    procedure Unref (Animation : Gdk_Pixbuf_Animation); 
  469.    --  Decrement the reference counting on the animation. 
  470.  
  471.    function Get_Width (Animation : Gdk_Pixbuf_Animation) return Gint; 
  472.    --  Return the width of the bounding box of a pixbuf animation. 
  473.  
  474.    function Get_Height (Animation : Gdk_Pixbuf_Animation) return Gint; 
  475.    --  Return the height of the bounding box of a pixbuf animation. 
  476.  
  477.    function Is_Static_Image (Animation : Gdk_Pixbuf_Animation) return Boolean; 
  478.    --  If you load a file with Gdk_New_From_File and it turns out to be a 
  479.    --  plain, unanimated image, then this function will return True. 
  480.    --  Use Get_Static_Image to retrieve the image. 
  481.  
  482.    function Get_Static_Image 
  483.      (Animation : Gdk_Pixbuf_Animation) return Gdk_Pixbuf; 
  484.    --  If an animation is really just a plain image (has only one frame), 
  485.    --  this function returns that image. If the animation is an animation, 
  486.    --  this function returns a reasonable thing to display as a static 
  487.    --  unanimated image, which might be the first frame, or something more 
  488.    --  sophisticated. If an animation hasn't loaded any frames yet, this 
  489.    --  function will return null. 
  490.  
  491.    function Get_Iter 
  492.      (Animation  : Gdk_Pixbuf_Animation; 
  493.       Start_Time : GTime_Val_Access := null) 
  494.       return Gdk_Pixbuf_Animation_Iter; 
  495.    --  Get an iterator for displaying an animation. The iterator provides 
  496.    --  the frames that should be displayed at a given time. 
  497.    --  It should be freed after use with Unref. 
  498.    -- 
  499.    --  Start_Time would normally come from G_Get_Current_Time, and marks the 
  500.    --  beginning of animation playback. After creating an iterator, you should 
  501.    --  immediately display the pixbuf returned by Get_Pixbuf. Then, you should 
  502.    --  install a timeout (with Timeout_Add) or by some other mechanism to 
  503.    --  ensure that you'll update the image after Get_Delay_Time milliseconds. 
  504.    --  Each time the image is updated, you should reinstall the timeout with 
  505.    --  the new, possibly-changed delay time. 
  506.    -- 
  507.    --  As a shortcut, if Start_Time is equal to null, the result of 
  508.    --  G_Get_Current_Time will be used automatically. 
  509.    -- 
  510.    --  To update the image (i.e. possibly change the result of Get_Pixbuf to a 
  511.    --  new frame of the animation), call Advance. 
  512.    -- 
  513.    --  If you're using Gdk_Pixbuf_Loader, in addition to updating the image 
  514.    --  after the delay time, you should also update it whenever you 
  515.    --  receive the area_updated signal and On_Currently_Loading_Frame returns 
  516.    --  True. In this case, the frame currently being fed into the loader 
  517.    --  has received new data, so needs to be refreshed. The delay time for 
  518.    --  a frame may also be modified after an area_updated signal, for 
  519.    --  example if the delay time for a frame is encoded in the data after 
  520.    --  the frame itself. So your timeout should be reinstalled after any 
  521.    --  area_updated signal. 
  522.    -- 
  523.    --  A delay time of -1 is possible, indicating "infinite." 
  524.  
  525.    --------------- 
  526.    -- Iterators -- 
  527.    --------------- 
  528.  
  529.    function Get_Type_Animation_Iter return Glib.GType; 
  530.    --  Return the internal value associated with a Gdk_Pixbuf_Animation_Iter. 
  531.  
  532.    procedure Ref (Iter : Gdk_Pixbuf_Animation_Iter); 
  533.    --  Increment the reference counting on the iterator. 
  534.  
  535.    procedure Unref (Iter : Gdk_Pixbuf_Animation_Iter); 
  536.    --  Decrement the reference counting on the iterator. 
  537.  
  538.    function Get_Delay_Time (Iter : Gdk_Pixbuf_Animation_Iter) return Gint; 
  539.    --  Return the number of milliseconds the current pixbuf should be displayed 
  540.    --  or -1 if the current pixbuf should be displayed forever. Timeout_Add 
  541.    --  conveniently takes a timeout in milliseconds, so you can use a timeout 
  542.    --  to schedule the next update. 
  543.  
  544.    function Get_Pixbuf (Iter : Gdk_Pixbuf_Animation_Iter) return Gdk_Pixbuf; 
  545.    --  Return the current pixbuf which should be displayed. 
  546.    --  The pixbuf will be the same size as the animation itself (Get_Width, 
  547.    --  Get_Height). This pixbuf should be displayed for Get_Delay_Time 
  548.    --  milliseconds. The caller of this function does not own a reference to 
  549.    --  the returned pixbuf; the returned pixbuf will become invalid when the 
  550.    --  iterator advances to the next frame, which may happen anytime you call 
  551.    --  Advance. Copy the pixbuf to keep it (don't just add a reference), as it 
  552.    --  may get recycled as you advance the iterator. 
  553.  
  554.    function On_Currently_Loading_Frame 
  555.      (Iter : Gdk_Pixbuf_Animation_Iter) return Boolean; 
  556.    --  Used to determine how to respond to the area_updated signal on 
  557.    --  Gdk_Pixbuf_Loader when loading an animation. area_updated is emitted 
  558.    --  for an area of the frame currently streaming in to the loader. So if 
  559.    --  you're on the currently loading frame, you need to redraw the screen for 
  560.    --  the updated area. 
  561.  
  562.    function Advance 
  563.      (Iter          : Gdk_Pixbuf_Animation_Iter; 
  564.       Current_Timer : GTime_Val_Access := null) return Boolean; 
  565.    --  Possibly advance an animation to a new frame. 
  566.    --  Chooses the frame based on the start time passed to Get_Iter. 
  567.    -- 
  568.    --  Current_Time would normally come from G_Get_Current_Time, and 
  569.    --  must be greater than or equal to the time passed to Get_Iter, 
  570.    --  and must increase or remain unchanged each time Get_Pixbuf is 
  571.    --  called. That is, you can't go backward in time; animations only 
  572.    --  play forward. 
  573.    -- 
  574.    --  As a shortcut, pass null for the current time and G_Get_Current_Time 
  575.    --  will be invoked on your behalf. So you only need to explicitly pass 
  576.    --  Current_Time if you're doing something odd like playing the animation 
  577.    --  at double speed. 
  578.    -- 
  579.    --  If this function returns False, there's no need to update the animation 
  580.    --  display, assuming the display had been rendered prior to advancing; 
  581.    --  if True, you need to call Get_Pixbuf and update the display with the new 
  582.    --  pixbuf. 
  583.  
  584.    ------------- 
  585.    -- Cursors -- 
  586.    ------------- 
  587.  
  588.    procedure Gdk_New_From_Pixbuf 
  589.      (Cursor  : out Gdk.Gdk_Cursor; 
  590.       Display : Gdk.Display.Gdk_Display := Gdk.Display.Get_Default; 
  591.       Pixbuf  : Gdk_Pixbuf; 
  592.       X       : Glib.Gint; 
  593.       Y       : Glib.Gint); 
  594.    --  Create a cursor from a pixbuf. 
  595.    --  Not all GDK backends support RGBA cursors. If they are not supported, 
  596.    --  a monochrome approximation will be displayed. 
  597.    --  The functions gdk.display.supports_cursor_alpha and 
  598.    --  gdk.display.supports_cursor_color can be used to determine whether RGBA 
  599.    --  cursors are supported; 
  600.    --  gdk.display.get_default_cursor_size and 
  601.    --  gdk.display.get_maximal_cursor_size give information about cursor sizes. 
  602.    --  On the X backend, support for RGBA cursors requires a sufficently new 
  603.    --  version of the X Render extension. 
  604.  
  605.    function Get_Image (Cursor : Gdk.Gdk_Cursor) return Gdk_Pixbuf; 
  606.    --  Return the image stored in the cursor 
  607.  
  608.    --  <doc_ignore> 
  609.    function Convert (P : System.Address) return Gdk_Pixbuf; 
  610.    --  </doc_ignore> 
  611.  
  612. private 
  613.  
  614.    type Gdk_Pixbuf_Record is new Glib.Object.GObject_Record with null record; 
  615.  
  616.    pragma Import (C, Get_Type, "gdk_pixbuf_get_type"); 
  617.    pragma Import (C, Get_Type_Animation, "gdk_pixbuf_animation_get_type"); 
  618.    pragma Import 
  619.      (C, Get_Type_Animation_Iter, "gdk_pixbuf_animation_iter_get_type"); 
  620.    pragma Import (C, Get_Iter, "gdk_pixbuf_animation_get_iter"); 
  621.    pragma Import 
  622.      (C, Get_Delay_Time, "gdk_pixbuf_animation_iter_get_delay_time"); 
  623.  
  624. end Gdk.Pixbuf;