1. ----------------------------------------------------------------------- 
  2. --               GtkAda - Ada95 binding for Gtk+/Gnome               -- 
  3. --                                                                   -- 
  4. --                    Copyright (C) 2010-2013, AdaCore               -- 
  5. --                                                                   -- 
  6. -- This library is free software; you can redistribute it and/or     -- 
  7. -- modify it under the terms of the GNU General Public               -- 
  8. -- License as published by the Free Software Foundation; either      -- 
  9. -- version 2 of the License, or (at your option) any later version.  -- 
  10. --                                                                   -- 
  11. -- This library is distributed in the hope that it will be useful,   -- 
  12. -- but WITHOUT ANY WARRANTY; without even the implied warranty of    -- 
  13. -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU -- 
  14. -- General Public License for more details.                          -- 
  15. --                                                                   -- 
  16. -- You should have received a copy of the GNU General Public         -- 
  17. -- License along with this library; if not, write to the             -- 
  18. -- Free Software Foundation, Inc., 59 Temple Place - Suite 330,      -- 
  19. -- Boston, MA 02111-1307, USA.                                       -- 
  20. --                                                                   -- 
  21. -- As a special exception, if other files instantiate generics from  -- 
  22. -- this unit, or you link this unit with other files to produce an   -- 
  23. -- executable, this  unit  does not  by itself cause  the resulting  -- 
  24. -- executable to be covered by the GNU General Public License. This  -- 
  25. -- exception does not however invalidate any other reasons why the   -- 
  26. -- executable file  might be covered by the  GNU Public License.     -- 
  27. ----------------------------------------------------------------------- 
  28.  
  29. --  <description> 
  30. --  Bindings to the Cairo 2D graphics library. 
  31. --  The Cairo_Context is the main object used when drawing with cairo. To draw 
  32. --  with Cairo, you create a Context, set the target surface, and drawing 
  33. --  options for the Cairo_Context, create shapes with functions like Move_To 
  34. --  and Line_To, and then draw shapes with Stroke or Fill. 
  35. -- 
  36. --  All drawing in Cairo is done on a Cairo_Context. 
  37. -- 
  38. --  Drawing on on-screen Gtk widgets should be done in a callback to the 
  39. --  "expose" event: 
  40. -- 
  41. --  When the widget has been created, connect a drawing function: 
  42. -- 
  43. --  <code> 
  44. --     declare 
  45. --        Area : Gtk_Drawing_Area; 
  46. -- 
  47. --        package Event_Cb is new Gtk.Handlers.Return_Callback 
  48. --            (Gtk_Drawing_Area_Record, Boolean); 
  49. --     begin 
  50. --        Gtk_New (Area); 
  51. --        Event_Cb.Connect (Area, "expose_event", 
  52. --                          Event_Cb.To_Marshaller (Expose_Cb'Access)); 
  53. --     end; 
  54. --  </code> 
  55. -- 
  56. --  In the callback, first get the context of the drawable on which you 
  57. --  need to draw, using Gdk.Cairo.Create. Then do the drawing operations, and 
  58. --  release the memory allocated to Cr using Cairo.Destroy. 
  59. -- 
  60. --  In addition to drawing on on-screen widgets, drawing can also be done using 
  61. --  the same Cairo calls to pixbufs (see Gdk.Cairo) to memory 
  62. --  (see Cairo.Image_Surface), and to PNG files (see Cairo.Png). 
  63. -- 
  64. --  Code samples demonstrating how to use various functionalities of Cairo 
  65. --  can be found in the testcairo example, shipped with GtkAda. 
  66. --  </description> 
  67. -- 
  68. --  <c_version>1.8.8</c_version> 
  69. --  <group>Cairo</group> 
  70.  
  71. with Ada.Unchecked_Deallocation; 
  72.  
  73. with System; 
  74. with Interfaces.C.Strings; 
  75.  
  76. with Glib; use Glib; 
  77.  
  78. package Cairo is 
  79.  
  80.    type Cairo_Context is private; 
  81.    --  A Cairo_Context contains the current state of the rendering device, 
  82.    --  including coordinates of yet to be drawn shapes. 
  83.    -- 
  84.    --  Cairo contexts, as Cairo_Context objects are named, are central to 
  85.    --  cairo and all drawing with cairo is always done to a Cairo_Context 
  86.    --  object. 
  87.    -- 
  88.    --  Memory management of Cairo_Context is done with subprograms 
  89.    --  Reference and Destroy, see below. 
  90.  
  91.    type Cairo_Surface is private; 
  92.    --  A Cairo_Surface represents an image, either as the destination 
  93.    --  of a drawing operation or as source when drawing onto another 
  94.    --  surface.  To draw to a Cairo_Surface, create a cairo context 
  95.    --  with the surface as the target, using Create. 
  96.    -- 
  97.    --  There are different subtypes of Cairo_Surface for 
  98.    --  different drawing backends; for example, Cairo.Image_Surface.Create 
  99.    --  creates a bitmap image in memory. 
  100.    --  The type of a surface can be queried with Cairo.Surface.Get_Type. 
  101.    -- 
  102.    --  Memory management of Cairo_Surface is done with 
  103.    --  Cairo.Surface.Reference and Cairo.Surface.Destroy. 
  104.  
  105.    type Cairo_Matrix is record 
  106.       Xx : aliased Gdouble; 
  107.       Yx : aliased Gdouble; 
  108.       Xy : aliased Gdouble; 
  109.       Yy : aliased Gdouble; 
  110.       X0 : aliased Gdouble; 
  111.       Y0 : aliased Gdouble; 
  112.    end record; 
  113.    --  Xx: Xx component of the affine transformation 
  114.    --  Yx: Yx component of the affine transformation 
  115.    --  Xy: Xy component of the affine transformation 
  116.    --  Yy: Yy component of the affine transformation 
  117.    --  X0: X translation component of the affine transformation 
  118.    --  Y0: Y translation component of the affine transformation 
  119.    -- 
  120.    --  A Cairo_Matrix holds an affine transformation, such as a scale, 
  121.    --  rotation, shear, or a combination of those. The transformation of 
  122.    --  a point (X, Y) is given by: 
  123.    -- 
  124.    --      X_New = Xx * X + Xy * Y + X0; 
  125.    --      Y_New = Yx * X + Yy * Y + Y0; 
  126.    pragma Convention (C_Pass_By_Copy, Cairo_Matrix); 
  127.  
  128.    type Cairo_Matrix_Access is access Cairo_Matrix; 
  129.    procedure Unchecked_Free is new Ada.Unchecked_Deallocation 
  130.      (Cairo_Matrix, Cairo_Matrix_Access); 
  131.  
  132.    type Cairo_Pattern is private; 
  133.    --  A Cairo_Pattern represents a source when drawing onto a 
  134.    --  surface. There are different subtypes of Cairo_Pattern, 
  135.    --  for different types of sources; for example, 
  136.    --  Cairo.Pattern.Create_Rgb creates a pattern for a solid 
  137.    --  opaque color. 
  138.    -- 
  139.    --  Other than various Cairo.Pattern.Create_<type> 
  140.    --  functions, some of the pattern types can be implicitly created 
  141.    --  using various Set_Source_<type> functions; for example Set_Source_Rgb. 
  142.    -- 
  143.    --  The type of a pattern can be queried with Cairo.Pattern.Get_Type. 
  144.    -- 
  145.    --  Memory management of Cairo_Pattern is done with 
  146.    --  Cairo.Pattern.Reference and Cairo.Pattern.Destroy. 
  147.  
  148.    type Cairo_Destroy_Func is access procedure (Arg1 : System.Address); 
  149.    --  Data: The Data element being destroyed. 
  150.    -- 
  151.    --  Cairo_destroy_func the type of function which is called when a 
  152.    --  data element is destroyed. It is passed the pointer to the data 
  153.    --  element and should free any memory and resources allocated for it. 
  154.  
  155.    type Cairo_User_Data_Key is record 
  156.       Unused : aliased Gint; 
  157.    end record; 
  158.    --  Unused: not used; ignore. 
  159.    -- 
  160.    --  Cairo_User_Data_Key is used for attaching user data to cairo 
  161.    --  data structures.  The actual contents of the struct is never used, 
  162.    --  and there is no need to initialize the object; only the unique 
  163.    --  address of a Cairo_User_Data_Key object is used.  Typically, you 
  164.    --  would just use the address of a static Cairo_User_Data_Key object. 
  165.  
  166.    pragma Convention (C_Pass_By_Copy, Cairo_User_Data_Key); 
  167.  
  168.    --  Cairo_Status is used to indicate errors that can occur when 
  169.    --  using Cairo. In some cases it is returned directly by functions. 
  170.    --  but when using Cairo_T, the last error, if any, is stored in 
  171.    --  the context and can be retrieved with Cairo_Status. 
  172.    -- 
  173.    --  New entries may be added in future versions.  Use 
  174.    --  Cairo_Status_To_String 
  175.    --  to get a human-readable representation of an error message. 
  176.    type Cairo_Status is 
  177.      ( 
  178.       Cairo_Status_Success, 
  179.       --  no error has occurred 
  180.  
  181.       Cairo_Status_No_Memory, 
  182.       --  out of memory 
  183.  
  184.       Cairo_Status_Invalid_Restore, 
  185.       --  Cairo_Restore called without matching Cairo_Save 
  186.  
  187.       Cairo_Status_Invalid_Pop_Group, 
  188.       --  no saved group to pop 
  189.  
  190.       Cairo_Status_No_Current_Point, 
  191.       --  no current point defined 
  192.  
  193.       Cairo_Status_Invalid_Matrix, 
  194.       --  invalid matrix (not invertible) 
  195.  
  196.       Cairo_Status_Invalid_Status, 
  197.       --  invalid value for an input Cairo_status 
  198.  
  199.       Cairo_Status_Null_Pointer, 
  200.       --  NULL pointer 
  201.  
  202.       Cairo_Status_Invalid_String, 
  203.       --  input string not valid UTF-8 
  204.  
  205.       Cairo_Status_Invalid_Path_Data, 
  206.       --  input path data not valid 
  207.  
  208.       Cairo_Status_Read_Error, 
  209.       --  error while reading from input stream 
  210.  
  211.       Cairo_Status_Write_Error, 
  212.       --  error while writing to output stream 
  213.  
  214.       Cairo_Status_Surface_Finished, 
  215.       --  target surface has been finished 
  216.  
  217.       Cairo_Status_Surface_Type_Mismatch, 
  218.       --  the surface type is not appropriate for the operation 
  219.  
  220.       Cairo_Status_Pattern_Type_Mismatch, 
  221.       --  the pattern type is not appropriate for the operation 
  222.  
  223.       Cairo_Status_Invalid_Content, 
  224.       --  invalid value for an input Cairo_content 
  225.  
  226.       Cairo_Status_Invalid_Format, 
  227.       --  invalid value for an input Cairo_format 
  228.  
  229.       Cairo_Status_Invalid_Visual, 
  230.       --  invalid value for an input Visual* 
  231.  
  232.       Cairo_Status_File_Not_Found, 
  233.       --  file not found 
  234.  
  235.       Cairo_Status_Invalid_Dash, 
  236.       --  invalid value for a dash setting 
  237.  
  238.       Cairo_Status_Invalid_Dsc_Comment, 
  239.       --  invalid value for a DSC comment (Since 1.2) 
  240.  
  241.       Cairo_Status_Invalid_Index, 
  242.       --  invalid index passed to getter (Since 1.4) 
  243.  
  244.       Cairo_Status_Clip_Not_Representable, 
  245.       --  clip region not representable in desired format (Since 1.4) 
  246.  
  247.       Cairo_Status_Temp_File_Error, 
  248.       --  error creating or writing to a temporary file (Since 1.6) 
  249.  
  250.       Cairo_Status_Invalid_Stride, 
  251.       --  invalid value for stride (Since 1.6) 
  252.  
  253.       Cairo_Status_Font_Type_Mismatch, 
  254.       --  the font type is not appropriate for the operation (Since 1.8) 
  255.  
  256.       Cairo_Status_User_Font_Immutable, 
  257.       --  the user-font is immutable (Since 1.8) 
  258.  
  259.       Cairo_Status_User_Font_Error, 
  260.       --  error occurred in a user-font callback function (Since 1.8) 
  261.  
  262.       Cairo_Status_Negative_Count, 
  263.       --  negative number used where it is not allowed (Since 1.8) 
  264.  
  265.       Cairo_Status_Invalid_Clusters, 
  266.       --  input clusters do not represent the accompanying text and glyph 
  267.       --  array (Since 1.8) 
  268.  
  269.       Cairo_Status_Invalid_Slant, 
  270.       --  invalid value for an input Cairo_Font_Slant (Since 1.8) 
  271.  
  272.       Cairo_Status_Invalid_Weight 
  273.       --  invalid value for an input Cairo_Font_Weight (Since 1.8) 
  274.      ); 
  275.  
  276.    subtype Cairo_Content is Guint; 
  277.    --  Cairo_content is used to describe the content that a surface will 
  278.    --  contain, whether color information, alpha information (translucence 
  279.    --  vs. opacity), or both. 
  280.    -- 
  281.    --  Note: The large values here are designed to keep Cairo_Content 
  282.    --  values distinct from Cairo_Format values so that the 
  283.    --  implementation can detect the error if users confuse the two types. 
  284.  
  285.    Cairo_Content_Color       : constant Cairo_Content := 4096; 
  286.    --  The surface will hold color content only. 
  287.  
  288.    Cairo_Content_Alpha       : constant Cairo_Content := 8192; 
  289.    --  CAIRO_CONTENT_ALPHA: The surface will hold alpha content only. 
  290.  
  291.    Cairo_Content_Color_Alpha : constant Cairo_Content := 12288; 
  292.    --  CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha 
  293.    --  content. 
  294.  
  295.    function Create (Target : Cairo_Surface) return Cairo_Context; 
  296.    --  Target: Target surface for the context 
  297.    -- 
  298.    --  Creates a new Cairo_Context with all graphics state parameters set to 
  299.    --  default values and with target as a target surface. The target 
  300.    --  surface should be constructed with a backend-specific function such 
  301.    --  as Cairo.Image_Surface.Create. 
  302.    -- 
  303.    --  This function references target, so you can immediately 
  304.    --  call Cairo.Surface.Destroy on it if you don't need to 
  305.    --  maintain a separate reference to it. 
  306.    -- 
  307.    --  Return value: a newly allocated Cairo_Context with a reference 
  308.    --  count of 1. The initial reference count should be released 
  309.    --  with Destroy when you are done using the Cairo_Context. 
  310.    --  This function never returns NULL. If memory cannot be 
  311.    --  allocated, a special Cairo_Context object will be returned on 
  312.    --  which Status returns Cairo_Status_No_Memory. 
  313.    --  You can use this object normally, but no drawing will 
  314.    --  be done. 
  315.  
  316.    function Reference (Cr : Cairo_Context) return Cairo_Context; 
  317.    --  Cr: a Cairo_Context 
  318.    -- 
  319.    --  Increases the reference count on cr by one. This prevents 
  320.    --  cr from being destroyed until a matching call to Destroy 
  321.    --  is made. 
  322.    -- 
  323.    --  The number of references to a Cairo_Context can be retrieved using 
  324.    --  Get_Reference_Count. 
  325.    -- 
  326.    --  Return value: the referenced Cairo_Context. 
  327.  
  328.    procedure Destroy (Cr : Cairo_Context); 
  329.    --  Cr: a Cairo_Context 
  330.    -- 
  331.    --  Decreases the reference count on cr by one. If the result 
  332.    --  is zero, then cr and all associated resources are freed. 
  333.    --  See Reference. 
  334.  
  335.    function Get_Reference_Count (Cr : Cairo_Context) return Guint; 
  336.    --  Cr: a Cairo_Context 
  337.    -- 
  338.    --  Returns the current reference count of cr. 
  339.    -- 
  340.    --  Return value: the current reference count of cr.  If the 
  341.    --  object is a nil object, 0 will be returned. 
  342.    -- 
  343.    --  Since: 1.4 
  344.  
  345.    function Get_User_Data 
  346.      (Cr   : Cairo_Context; 
  347.       Key  : access Cairo_User_Data_Key) 
  348.       return System.Address; 
  349.    --  Cr: a Cairo_Context 
  350.    --  Key: the address of the Cairo_User_Data_Key the user data was 
  351.    --  attached to 
  352.    -- 
  353.    --  Return user data previously attached to cr using the specified 
  354.    --  key.  If no user data has been attached with the given key this 
  355.    --  function returns NULL. 
  356.    -- 
  357.    --  Return value: the user data previously attached or NULL. 
  358.    -- 
  359.    --  Since: 1.4 
  360.  
  361.    function Set_User_Data 
  362.      (Cr        : Cairo_Context; 
  363.       Key       : access Cairo_User_Data_Key; 
  364.       User_Data : System.Address; 
  365.       Destroy   : Cairo_Destroy_Func) 
  366.       return      Cairo_Status; 
  367.    --  Cr: a Cairo_Context 
  368.    --  Key: the address of a Cairo_User_Data_Key to attach the user data to 
  369.    --  User_Data: the user data to attach to the Cairo_Context 
  370.    --  Destroy: a Cairo_Destroy_Func which will be called when the 
  371.    --  Cairo_Context is destroyed or when new user data is attached using the 
  372.    --  same key. 
  373.    -- 
  374.    --  Attach user data to cr.  To remove user data from a surface, 
  375.    --  call this function with the key that was used to set it and NULL 
  376.    --  for data. 
  377.    -- 
  378.    --  Return value: CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a 
  379.    --  slot could not be allocated for the user data. 
  380.    -- 
  381.    --  Since: 1.4 
  382.  
  383.    procedure Save (Cr : Cairo_Context); 
  384.    --  Cr: a Cairo_Context 
  385.    -- 
  386.    --  Makes a copy of the current state of cr and saves it 
  387.    --  on an internal stack of saved states for cr. When 
  388.    --  Cairo_Restore is called, cr will be restored to 
  389.    --  the saved state. Multiple calls to Cairo_Save and 
  390.    --  Cairo_Restore can be nested; each call to Cairo_Restore 
  391.    --  restores the state from the matching paired Cairo_Save. 
  392.    -- 
  393.    --  It isn't necessary to clear all saved states before 
  394.    --  a Cairo_Context is freed. If the reference count of a Cairo_Context 
  395.    --  drops to zero in response to a call to Cairo_Destroy, 
  396.    --  any saved states will be freed along with the Cairo_Context. 
  397.  
  398.    procedure Restore (Cr : Cairo_Context); 
  399.    --  Cr: a Cairo_Context 
  400.    -- 
  401.    --  Restores cr to the state saved by a preceding call to 
  402.    --  Cairo_Save and removes that state from the stack of 
  403.    --  saved states. 
  404.  
  405.    procedure Push_Group (Cr : Cairo_Context); 
  406.    --  Cr: a cairo context 
  407.    -- 
  408.    --  Temporarily redirects drawing to an intermediate surface known as a 
  409.    --  group. The redirection lasts until the group is completed by a call 
  410.    --  to Pop_Group or Pop_Group_To_Source. 
  411.    -- 
  412.    --  These calls provide the result of any drawing to the group as a pattern, 
  413.    --  (either as an explicit object, or set as the source pattern). 
  414.    -- 
  415.    --  This group functionality can be convenient for performing 
  416.    --  intermediate compositing. One common use of a group is to render 
  417.    --  objects as opaque within the group, (so that they occlude each 
  418.    --  other), and then blend the result with translucence onto the 
  419.    --  destination. 
  420.    -- 
  421.    --  Groups can be nested arbitrarily deep by making balanced calls to 
  422.    --  Push_Group/Pop_Group. Each call pushes/pops the new target group 
  423.    --  onto/from a stack. 
  424.    -- 
  425.    --  The Push_Group function calls Save so that any changes to the graphics 
  426.    --  state will not be visible outside the group, (the pop_group functions 
  427.    --  call Restore). 
  428.    -- 
  429.    --  By default the intermediate group will have a content type of 
  430.    --  Cairo_Content_Color_Alphe. Other content types can be chosen for 
  431.    --  the group by using Push_Group_With_Content instead. 
  432.    -- 
  433.    --  As an example, here is how one might fill and stroke a path with 
  434.    --  translucence, but without any portion of the fill being visible 
  435.    --  under the stroke: 
  436.    -- 
  437.    --      Push_Group (Cr); 
  438.    --      Set_Source (Cr, Fill_Pattern); 
  439.    --      Fill_Preserve (Cr); 
  440.    --      Set_Source (Cr, Stroke_Pattern); 
  441.    --      Stroke (Cr); 
  442.    --      Pop_Group_To_Source (Cr); 
  443.    --      Paint_With_Alpha (Cr, Alpha); 
  444.    -- 
  445.    --  Since: 1.2 
  446.  
  447.    procedure Push_Group_With_Content 
  448.      (Cr      : Cairo_Context; 
  449.       Content : Cairo_Content); 
  450.    --  Cr: a cairo context 
  451.    --  Content: a Cairo_Content indicating the type of group that 
  452.    --            will be created 
  453.    -- 
  454.    --  Temporarily redirects drawing to an intermediate surface known as a 
  455.    --  group. The redirection lasts until the group is completed by a call to 
  456.    --  Pop_Group or Pop_Group_To_Source. These calls provide the result of any 
  457.    --  drawing to the group as a pattern, (either as an explicit object, or set 
  458.    --  as the source pattern). 
  459.    -- 
  460.    --  The group will have a content type of content. The ability to control 
  461.    --  this content type is the only distinction between this function and 
  462.    --  Push_Group which you should see for a more detailed description of group 
  463.    --  rendering. 
  464.    -- 
  465.    --  Since: 1.2 
  466.  
  467.    function Pop_Group (Cr : Cairo_Context) return Cairo_Pattern; 
  468.    --  Cr: a cairo context 
  469.    -- 
  470.    --  Terminates the redirection begun by a call to Push_Group or 
  471.    --  Push_Group_With_Content and returns a new pattern containing the results 
  472.    --  of all drawing operations performed to the group. 
  473.    -- 
  474.    --  The Pop_Group function calls Restore, (balancing a call to Save by the 
  475.    --  Push_Group function), so that any changes to the graphics state will not 
  476.    --  be visible outside the group. 
  477.    -- 
  478.    --  Return value: a newly created (surface) pattern containing the 
  479.    --  results of all drawing operations performed to the group. The 
  480.    --  caller owns the returned object and should call 
  481.    --  Cairo.Pattern.Destroy when finished with it. 
  482.    -- 
  483.    --  Since: 1.2 
  484.  
  485.    procedure Pop_Group_To_Source (Cr : Cairo_Context); 
  486.    --  Cr: a cairo context 
  487.    -- 
  488.    --  Terminates the redirection begun by a call to Push_Group or 
  489.    --  Push_Group_With_Content and installs the resulting pattern as the source 
  490.    --  pattern in the given cairo context. 
  491.    -- 
  492.    --  The behavior of this function is equivalent to the sequence of 
  493.    --  operations: 
  494.    -- 
  495.    --  declare 
  496.    --     Group: Cairo_Pattern := Pop_Group (Cr); 
  497.    --  begin 
  498.    --     Set_Source (Cr, Group); 
  499.    --     Cairo.Pattern.Destroy (Group); 
  500.    --  end; 
  501.    -- 
  502.    --  but is more convenient as their is no need for a variable to store 
  503.    --  the short-lived pointer to the pattern. 
  504.    -- 
  505.    --  The Pop_Group function calls Restore, (balancing a call to Save by the 
  506.    --  push_group function), so that any changes to the graphics state will not 
  507.    --  be visible outside the group. 
  508.    -- 
  509.    --  Since: 1.2 
  510.  
  511.    --  Cairo_operator is used to set the compositing operator for all cairo 
  512.    --  drawing operations. 
  513.    -- 
  514.    --  The default operator is Cairo_Operator_Over. 
  515.    -- 
  516.    --  The operators marked as "unbounded" modify their destination even 
  517.    --  outside of the mask layer (that is, their effect is not bound by the 
  518.    --  mask layer). However, their effect can still be limited by way of 
  519.    --  clipping. 
  520.    -- 
  521.    --  To keep things simple, the operator descriptions here document the 
  522.    --  behavior for when both source and destination are either fully 
  523.    --  transparent or fully opaque. The actual implementation works for 
  524.    --  translucent layers too. 
  525.    -- 
  526.    --  For a more detailed explanation of the effects of each operator, 
  527.    --  including the mathematical definitions, see 
  528.    --  http://cairographics.org/operators/ 
  529.    type Cairo_Operator is 
  530.      (Cairo_Operator_Clear, 
  531.       --  clear destination layer (bounded) 
  532.  
  533.       Cairo_Operator_Source, 
  534.       --  replace destination layer (bounded) 
  535.  
  536.       Cairo_Operator_Over, 
  537.       --  draw source layer on top of destination layer (bounded) 
  538.  
  539.       Cairo_Operator_In, 
  540.       --  draw source where there was destination content (unbounded) 
  541.  
  542.       Cairo_Operator_Out, 
  543.       --  draw source where there was no destination content (unbounded) 
  544.  
  545.       Cairo_Operator_Atop, 
  546.       --  draw source on top of destination content and only there 
  547.  
  548.       Cairo_Operator_Dest, 
  549.       --  ignore the source 
  550.  
  551.       Cairo_Operator_Dest_Over, 
  552.       --  draw destination on top of source 
  553.  
  554.       Cairo_Operator_Dest_In, 
  555.       --  leave destination only where there was source content (unbounded) 
  556.  
  557.       Cairo_Operator_Dest_Out, 
  558.       --  leave destination only where there was no source content 
  559.  
  560.       Cairo_Operator_Dest_Atop, 
  561.       --  leave destination on top of source content and only there (unbounded) 
  562.  
  563.       Cairo_Operator_Xor, 
  564.       --  source and destination are shown where there is only one of them 
  565.  
  566.       Cairo_Operator_Add, 
  567.       --  source and destination layers are accumulated 
  568.  
  569.       Cairo_Operator_Saturate 
  570.       --  like over, but assuming source and dest are disjoint geometries 
  571.      ); 
  572.  
  573.    procedure Set_Operator (Cr : Cairo_Context; Op : Cairo_Operator); 
  574.    --  Cr: a Cairo_Context 
  575.    --  Op: a compositing Operator, specified as a Cairo_Operator 
  576.    -- 
  577.    --  Sets the compositing operator to be used for all drawing 
  578.    --  operations. See Cairo_Operator for details on the semantics of 
  579.    --  each available compositing operator. 
  580.    -- 
  581.    --  The default operator is Cairo_Operator_Over. 
  582.  
  583.    procedure Set_Source (Cr : Cairo_Context; Source : Cairo_Pattern); 
  584.    --  Cr: a cairo context 
  585.    --  Source: a Cairo_Pattern to be used as the Source for 
  586.    --  subsequent drawing operations. 
  587.    -- 
  588.    --  Sets the source pattern within Cr to source. This pattern 
  589.    --  will then be used for any subsequent drawing operation until a new 
  590.    --  source pattern is set. 
  591.    -- 
  592.    --  Note: The pattern's transformation matrix will be locked to the user 
  593.    --  space in effect at the time of Set_Source. This means that further 
  594.    --  modifications of the current transformation matrix will not affect the 
  595.    --  source pattern. See Cairo.Pattern.Set_Matrix. 
  596.    -- 
  597.    --  The default source pattern is a solid pattern that is opaque black, 
  598.    --  (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)). 
  599.  
  600.    procedure Set_Source_Rgb 
  601.      (Cr    : Cairo_Context; 
  602.       Red   : Gdouble; 
  603.       Green : Gdouble; 
  604.       Blue  : Gdouble); 
  605.    --  Cr    : a cairo context 
  606.    --  Red   : Red component of color 
  607.    --  Green : Green component of color 
  608.    --  Blue  : Blue component of color 
  609.    -- 
  610.    --  Sets the source pattern within Cr to an opaque color. This opaque 
  611.    --  color will then be used for any subsequent drawing operation until 
  612.    --  a new source pattern is set. 
  613.    -- 
  614.    --  The color components are floating point numbers in the range 0 to 
  615.    --  1. If the values passed in are outside that range, they will be 
  616.    --  clamped. 
  617.    -- 
  618.    --  The default source pattern is opaque black, (that is, it is 
  619.    --  equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)). 
  620.  
  621.    procedure Set_Source_Rgba 
  622.      (Cr    : Cairo_Context; 
  623.       Red   : Gdouble; 
  624.       Green : Gdouble; 
  625.       Blue  : Gdouble; 
  626.       Alpha : Gdouble); 
  627.    --  Cr    : a cairo context 
  628.    --  Red   : Red component of color 
  629.    --  Green : Green component of color 
  630.    --  Blue  : Blue component of color 
  631.    --  Alpha : Alpha component of color 
  632.    -- 
  633.    --  Sets the source pattern within Cr to a translucent color. This 
  634.    --  color will then be used for any subsequent drawing operation until 
  635.    --  a new source pattern is set. 
  636.    -- 
  637.    --  The color and alpha components are floating point numbers in the 
  638.    --  range 0 to 1. If the values passed in are outside that range, they 
  639.    --  will be clamped. 
  640.    -- 
  641.    --  The default source pattern is opaque black, (that is, it is 
  642.    --  equivalent to Set_Source_Rgba (Cr, 0.0, 0.0, 0.0, 1.0)). 
  643.  
  644.    procedure Set_Source_Surface 
  645.      (Cr      : Cairo_Context; 
  646.       Surface : Cairo_Surface; 
  647.       X       : Gdouble; 
  648.       Y       : Gdouble); 
  649.    --  Cr      : a cairo context 
  650.    --  Surface : a Surface to be used to set the source pattern 
  651.    --  X       : User-space X coordinate for surface origin 
  652.    --  Y       : User-space Y coordinate for surface origin 
  653.    -- 
  654.    --  This is a convenience function for creating a pattern from surface 
  655.    --  and setting it as the source in Cr with Set_Source. 
  656.    -- 
  657.    --  The X and Y parameters give the user-space coordinate at which 
  658.    --  the surface origin should appear. (The surface origin is its 
  659.    --  upper-left corner before any transformation has been applied.) The 
  660.    --  X and Y patterns are negated and then set as translation values 
  661.    --  in the pattern matrix. 
  662.    -- 
  663.    --  Other than the initial translation pattern matrix, as described 
  664.    --  above, all other pattern attributes, (such as its extend mode), are 
  665.    --  set to the default values as in Cairo.Pattern.Create_For_Surface. 
  666.    --  The resulting pattern can be queried with Get_Source so that these 
  667.    --  attributes can be modified if desired, (eg. to create a 
  668.    --  repeating pattern with Cairo.Pattern.Set_Extend). 
  669.  
  670.    procedure Set_Tolerance (Cr : Cairo_Context; Tolerance : Gdouble); 
  671.    --  Cr: a Cairo_Context 
  672.    --  Tolerance: the Tolerance, in device units (typically pixels) 
  673.    -- 
  674.    --  Sets the tolerance used when converting paths into trapezoids. 
  675.    --  Curved segments of the path will be subdivided until the maximum 
  676.    --  deviation between the original path and the polygonal approximation 
  677.    --  is less than tolerance. The default value is 0.1. A larger 
  678.    --  value will give better performance, a smaller value, better 
  679.    --  appearance. (Reducing the value from the default value of 0.1 
  680.    --  is unlikely to improve appearance significantly.)  The accuracy of paths 
  681.    --  within Cairo is limited by the precision of its internal arithmetic, and 
  682.    --  the prescribed tolerance is restricted to the smallest 
  683.    --  representable internal value. 
  684.  
  685.    --  Specifies the type of antialiasing to do when rendering text or shapes. 
  686.    type Cairo_Antialias is 
  687.      ( 
  688.       Cairo_Antialias_Default, 
  689.       --  Use the default antialiasing for the subsystem and target device 
  690.  
  691.       Cairo_Antialias_None, 
  692.       --  Use a bilevel alpha mask 
  693.  
  694.       Cairo_Antialias_Gray, 
  695.       --  Perform single-color antialiasing (using shades of gray for black 
  696.       --  text on a white background, for example). 
  697.  
  698.       Cairo_Antialias_Subpixel 
  699.       --  Perform antialiasing by taking advantage of the order of subpixel 
  700.       --  elements on devices such as LCD panels 
  701.      ); 
  702.  
  703.    procedure Set_Antialias 
  704.      (Cr        : Cairo_Context; 
  705.       Antialias : Cairo_Antialias); 
  706.    --  Cr: a Cairo_Context 
  707.    --  Antialias: the new Antialiasing mode 
  708.    -- 
  709.    --  Set the antialiasing mode of the rasterizer used for drawing shapes. 
  710.    --  This value is a hint, and a particular backend may or may not support 
  711.    --  a particular value.  At the current time, no backend supports 
  712.    --  Cairo_Antialias_Subpixel when drawing shapes. 
  713.    -- 
  714.    --  Note that this option does not affect text rendering, instead see 
  715.    --  Cairo.Font_Options.Set_Antialias. 
  716.  
  717.    --  Cairo_Fill_Rule is used to select how paths are filled. For both 
  718.    --  fill rules, whether or not a point is included in the fill is 
  719.    --  determined by taking a ray from that point to infinity and looking 
  720.    --  at intersections with the path. The ray can be in any direction, 
  721.    --  as long as it doesn't pass through the end point of a segment 
  722.    --  or have a tricky intersection such as intersecting tangent to the path. 
  723.    --  (Note that filling is not actually implemented in this way. This 
  724.    --  is just a description of the rule that is applied.) 
  725.    -- 
  726.    --  The default fill rule is Cairo_Fill_Rule_Winding. 
  727.    -- 
  728.    --  New entries may be added in future versions. 
  729.    type Cairo_Fill_Rule is 
  730.      (Cairo_Fill_Rule_Winding, 
  731.       --  If the path crosses the ray from left-to-right, counts +1. If the 
  732.       --  path crosses the ray from right to left, counts -1. (Left and right 
  733.       --  are determined from the perspective of looking along the ray from 
  734.       --  the starting point). If the total count is non-zero, the point will 
  735.       --  be filled. 
  736.  
  737.       Cairo_Fill_Rule_Even_Odd 
  738.       --  Counts the total number of 
  739.       --  intersections, without regard to the orientation of the contour. If 
  740.       --  the total number of intersections is odd, the point will be filled. 
  741.      ); 
  742.  
  743.    procedure Set_Fill_Rule 
  744.      (Cr        : Cairo_Context; 
  745.       Fill_Rule : Cairo_Fill_Rule); 
  746.    --  Cr: a Cairo_Context 
  747.    --  Fill_Rule: a fill rule 
  748.    -- 
  749.    --  Set the current fill rule within the cairo context. The fill rule is 
  750.    --  used to determine which regions are inside or outside a complex 
  751.    --  (potentially self-intersecting) path. The current fill rule affects both 
  752.    --  Fill and Clip. See Cairo_Fill_Rule for details on the semantics of each 
  753.    --  available fill rule. 
  754.    -- 
  755.    --  The default fill rule is Cairo_Fill_Rule_Winding. 
  756.  
  757.    procedure Set_Line_Width (Cr : Cairo_Context; Width : Gdouble); 
  758.    --  Cr: a Cairo_Context 
  759.    --  Width: a line Width 
  760.    -- 
  761.    --  Sets the current line width within the cairo context. The line 
  762.    --  width value specifies the diameter of a pen that is circular in 
  763.    --  user space, (though device-space pen may be an ellipse in general 
  764.    --  due to scaling/shear/rotation of the CTM). 
  765.    -- 
  766.    --  Note: When the description above refers to user space and CTM it 
  767.    --  refers to the user space and CTM in effect at the time of the 
  768.    --  stroking operation, not the user space and CTM in effect at the 
  769.    --  time of the call to Set_Line_Width. The simplest usage 
  770.    --  makes both of these spaces identical. That is, if there is no 
  771.    --  change to the CTM between a call to Set_Line_Width and the 
  772.    --  stroking operation, then one can just pass user-space values to 
  773.    --  Set_Line_Width and ignore this note. 
  774.    -- 
  775.    --  As with the other stroke parameters, the current line width is examined 
  776.    --  by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any 
  777.    --  effect during path construction. 
  778.    -- 
  779.    --  The default line width value is 2.0. 
  780.  
  781.    type Cairo_Line_Cap is 
  782.      (Cairo_Line_Cap_Butt, 
  783.       --  start(stop) the line exactly at the start(end) point 
  784.  
  785.       Cairo_Line_Cap_Round, 
  786.       --  use a round ending, the center of the circle is the end point 
  787.  
  788.       Cairo_Line_Cap_Square 
  789.       --  use squared ending, the center of the square is the end point 
  790.      ); 
  791.    --  Specifies how to render the endpoints of the path when stroking. 
  792.    -- 
  793.    --  The default line cap style is Cairo_Line_Cap_Butt. 
  794.  
  795.    procedure Set_Line_Cap (Cr : Cairo_Context; Line_Cap : Cairo_Line_Cap); 
  796.    --  Cr: a cairo context 
  797.    --  Line_Cap: a line cap style 
  798.    -- 
  799.    --  Sets the current line cap style within the cairo context. See 
  800.    --  Cairo_Line_Cap for details about how the available line cap 
  801.    --  styles are drawn. 
  802.    -- 
  803.    --  As with the other stroke parameters, the current line cap style is 
  804.    --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not 
  805.    --  have any effect during path construction. 
  806.    -- 
  807.    --  The default line cap style is Cairo_Line_Cap_Butt. 
  808.  
  809.    type Cairo_Line_Join is 
  810.      (Cairo_Line_Join_Miter, 
  811.       --  use a sharp (angled) corner, see Set_Miter_Limit 
  812.  
  813.       Cairo_Line_Join_Round, 
  814.       --  use a rounded join, the center of the circle is the joint point 
  815.  
  816.       Cairo_Line_Join_Bevel 
  817.       --  use a cut-off join, the join is cut off at half the line width from 
  818.       --  the joint point 
  819.      ); 
  820.    --  Specifies how to render the junction of two lines when stroking. 
  821.    -- 
  822.    --  The default line join style is Cairo_Line_Join_Miter. 
  823.  
  824.    procedure Set_Line_Join 
  825.      (Cr        : Cairo_Context; 
  826.       Line_Join : Cairo_Line_Join); 
  827.    --  Cr: a cairo context 
  828.    --  Line_Join: a line join style 
  829.    -- 
  830.    --  Sets the current line join style within the cairo context. See 
  831.    --  Cairo_Line_Join for details about how the available line join styles are 
  832.    --  drawn. 
  833.    -- 
  834.    --  As with the other stroke parameters, the current line join style is 
  835.    --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does 
  836.    --  not have any effect during path construction. 
  837.    -- 
  838.    --  The default line join style is Cairo_Line_Join_Miter. 
  839.  
  840.    type Dash_Array is array (Natural range <>) of Gdouble; 
  841.  
  842.    No_Dashes : constant Dash_Array (1 .. 0) := (others => 0.0); 
  843.  
  844.    procedure Set_Dash 
  845.      (Cr         : Cairo_Context; 
  846.       Dashes     : Dash_Array; 
  847.       Offset     : Gdouble); 
  848.    --  Cr: a cairo context 
  849.    --  Dashes: an array specifying alternate lengths of on and off stroke 
  850.    --  portions 
  851.    --  Offset: an Offset into the dash pattern at which the stroke should start 
  852.    -- 
  853.    --  Sets the dash pattern to be used by Stroke. A dash pattern 
  854.    --  is specified by dashes, an array of positive values. Each value 
  855.    --  provides the length of alternate "on" and "off" portions of the 
  856.    --  stroke. The offset specifies an offset into the pattern at which 
  857.    --  the stroke begins. 
  858.    -- 
  859.    --  Each "on" segment will have caps applied as if the segment were a 
  860.    --  separate sub-path. In particular, it is valid to use an "on" length 
  861.    --  of 0.0 with Cairo_Line_Cap_Round or Cairo_Line_Cap_Square in order 
  862.    --  to distributed dots or squares along a path. 
  863.    -- 
  864.    --  Note: The length values are in user-space units as evaluated at the 
  865.    --  time of stroking. This is not necessarily the same as the user 
  866.    --  space at the time of Set_Dash. 
  867.    -- 
  868.    --  If the array is No_Dashes, dashing is disabled. 
  869.    -- 
  870.    --  If the array contains only one element symmetric pattern is assumed with 
  871.    --  alternating on and off portions of the size specified by the single 
  872.    --  value in dashes. 
  873.    -- 
  874.    --  If any value in dashes is negative, or if all values are 0, then 
  875.    --  cr will be put into an error state with a status of 
  876.    --  Cairo_Status_Invalid_Dash. 
  877.  
  878.    procedure Set_Miter_Limit (Cr : Cairo_Context; Limit : Gdouble); 
  879.    --  Cr: a cairo context 
  880.    --  Limit: miter Limit to set 
  881.    -- 
  882.    --  Sets the current miter limit within the cairo context. 
  883.    -- 
  884.    --  If the current line join style is set to Cairo_Line_Join_Miter 
  885.    --  (see Cairo_Set_Line_Join), the miter limit is used to determine 
  886.    --  whether the lines should be joined with a bevel instead of a miter. 
  887.    --  Cairo divides the length of the miter by the line width. 
  888.    --  If the result is greater than the miter limit, the style is 
  889.    --  converted to a bevel. 
  890.    -- 
  891.    --  As with the other stroke parameters, the current line miter limit is 
  892.    --  examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not 
  893.    --  have any effect during path construction. 
  894.    -- 
  895.    --  The default miter limit value is 10.0, which will convert joins 
  896.    --  with interior angles less than 11 degrees to bevels instead of 
  897.    --  miters. For reference, a miter limit of 2.0 makes the miter cutoff 
  898.    --  at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 
  899.    --  degrees. 
  900.    -- 
  901.    --  A miter limit for a desired angle can be computed as: miter limit = 
  902.    --  1/sin(angle/2) 
  903.  
  904.    procedure Translate (Cr : Cairo_Context; Tx : Gdouble; Ty : Gdouble); 
  905.    --  Cr: a cairo context 
  906.    --  Tx: amount to translate in the X direction 
  907.    --  Ty: amount to translate in the Y direction 
  908.    -- 
  909.    --  Modifies the current transformation matrix (CTM) by translating the 
  910.    --  user-space origin by (tx, ty). This offset is interpreted as a 
  911.    --  user-space coordinate according to the CTM in place before the new 
  912.    --  call to Translate. In other words, the translation of the 
  913.    --  user-space origin takes place after any existing transformation. 
  914.  
  915.    procedure Scale (Cr : Cairo_Context; Sx : Gdouble; Sy : Gdouble); 
  916.    --  Cr: a cairo context 
  917.    --  Sx: scale factor for the X dimension 
  918.    --  Sy: scale factor for the Y dimension 
  919.    -- 
  920.    --  Modifies the current transformation matrix (CTM) by scaling the X 
  921.    --  and Y user-space axes by sx and sy respectively. The scaling of 
  922.    --  the axes takes place after any existing transformation of user 
  923.    --  space. 
  924.  
  925.    procedure Rotate (Cr : Cairo_Context; Angle : Gdouble); 
  926.    --  Cr: a cairo context 
  927.    --  Angle: Angle (in radians) by which the user-space axes will be 
  928.    --  rotated 
  929.    -- 
  930.    --  Modifies the current transformation matrix (CTM) by rotating the 
  931.    --  user-space axes by angle radians. The rotation of the axes takes 
  932.    --  places after any existing transformation of user space. The 
  933.    --  rotation direction for positive angles is from the positive X axis 
  934.    --  toward the positive Y axis. 
  935.  
  936.    procedure Transform 
  937.      (Cr     : Cairo_Context; 
  938.       Matrix : access Cairo_Matrix); 
  939.    --  Cr: a cairo context 
  940.    --  Matrix: a transformation to be applied to the user-space axes 
  941.    -- 
  942.    --  Modifies the current transformation matrix (CTM) by applying 
  943.    --  matrix as an additional transformation. The new transformation of 
  944.    --  user space takes place after any existing transformation. 
  945.  
  946.    procedure Set_Matrix 
  947.      (Cr     : Cairo_Context; 
  948.       Matrix : access Cairo_Matrix); 
  949.    --  Cr: a cairo context 
  950.    --  Matrix: a transformation Matrix from user space to device space 
  951.    -- 
  952.    --  Modifies the current transformation matrix (CTM) by setting it 
  953.    --  equal to matrix. 
  954.  
  955.    procedure Identity_Matrix (Cr : Cairo_Context); 
  956.    --  Cr: a cairo context 
  957.    -- 
  958.    --  Resets the current transformation matrix (CTM) by setting it equal 
  959.    --  to the identity matrix. That is, the user-space and device-space 
  960.    --  axes will be aligned and one user-space unit will transform to one 
  961.    --  device-space unit. 
  962.  
  963.    procedure User_To_Device 
  964.      (Cr : Cairo_Context; 
  965.       X  : access Gdouble; 
  966.       Y  : access Gdouble); 
  967.    --  Cr: a cairo context 
  968.    --  X: X value of coordinate (in/out parameter) 
  969.    --  Y: Y value of coordinate (in/out parameter) 
  970.    -- 
  971.    --  Transform a coordinate from user space to device space by 
  972.    --  multiplying the given point by the current transformation matrix 
  973.    --  (CTM). 
  974.  
  975.    procedure User_To_Device_Distance 
  976.      (Cr : Cairo_Context; 
  977.       Dx : access Gdouble; 
  978.       Dy : access Gdouble); 
  979.    --  Cr: a cairo context 
  980.    --  Dx: X component of a distance vector (in/out parameter) 
  981.    --  Dy: Y component of a distance vector (in/out parameter) 
  982.    -- 
  983.    --  Transform a distance vector from user space to device space. This 
  984.    --  function is similar to User_To_Device except that the translation 
  985.    --  components of the CTM will be ignored when transforming (Dx,Dy). 
  986.  
  987.    procedure Device_To_User 
  988.      (Cr : Cairo_Context; 
  989.       X  : access Gdouble; 
  990.       Y  : access Gdouble); 
  991.    --  Cr: a cairo 
  992.    --  X: X value of coordinate (in/out parameter) 
  993.    --  Y: Y value of coordinate (in/out parameter) 
  994.    -- 
  995.    --  Transform a coordinate from device space to user space by 
  996.    --  multiplying the given point by the inverse of the current 
  997.    --  transformation matrix (CTM). 
  998.  
  999.    procedure Device_To_User_Distance 
  1000.      (Cr : Cairo_Context; 
  1001.       Dx : access Gdouble; 
  1002.       Dy : access Gdouble); 
  1003.    --  Cr: a cairo context 
  1004.    --  Dx: X component of a distance vector (in/out parameter) 
  1005.    --  Dy: Y component of a distance vector (in/out parameter) 
  1006.    -- 
  1007.    --  Transform a distance vector from device space to user space. This 
  1008.    --  function is similar to Device_To_User except that the 
  1009.    --  translation components of the inverse CTM will be ignored when 
  1010.    --  transforming (Dx,dy). 
  1011.  
  1012.    ------------------- 
  1013.    -- Path creation -- 
  1014.    ------------------- 
  1015.  
  1016.    procedure New_Path (Cr : Cairo_Context); 
  1017.    --  Cr: a cairo context 
  1018.    -- 
  1019.    --  Clears the current path. After this call there will be no path and 
  1020.    --  no current point. 
  1021.  
  1022.    procedure Move_To (Cr : Cairo_Context; X : Gdouble; Y : Gdouble); 
  1023.    --  Cr: a cairo context 
  1024.    --  X: the X coordinate of the new position 
  1025.    --  Y: the Y coordinate of the new position 
  1026.    -- 
  1027.    --  Begin a new sub-path. After this call the current point will be (X, Y). 
  1028.  
  1029.    procedure New_Sub_Path (Cr : Cairo_Context); 
  1030.    --  Cr: a cairo context 
  1031.    -- 
  1032.    --  Begin a new sub-path. Note that the existing path is not 
  1033.    --  affected. After this call there will be no current point. 
  1034.    -- 
  1035.    --  In many cases, this call is not needed since new sub-paths are 
  1036.    --  frequently started with Move_To. 
  1037.    -- 
  1038.    --  A call to New_Sub_Path is particularly useful when 
  1039.    --  beginning a new sub-path with one of the Arc calls. This 
  1040.    --  makes things easier as it is no longer necessary to manually 
  1041.    --  compute the arc's initial coordinates for a call to 
  1042.    --  Move_To. 
  1043.    -- 
  1044.    --  Since: 1.2 
  1045.  
  1046.    procedure Line_To (Cr : Cairo_Context; X : Gdouble; Y : Gdouble); 
  1047.    --  Cr: a cairo context 
  1048.    --  X: the X coordinate of the end of the new line 
  1049.    --  Y: the Y coordinate of the end of the new line 
  1050.    -- 
  1051.    --  Adds a line to the path from the current point to position (X, Y) 
  1052.    --  in user-space coordinates. After this call the current point 
  1053.    --  will be (X, Y). 
  1054.    -- 
  1055.    --  If there is no current point before the call to Line_To 
  1056.    --  this function will behave as Move_To (Cr, X, Y). 
  1057.  
  1058.    procedure Curve_To 
  1059.      (Cr : Cairo_Context; 
  1060.       X1 : Gdouble; 
  1061.       Y1 : Gdouble; 
  1062.       X2 : Gdouble; 
  1063.       Y2 : Gdouble; 
  1064.       X3 : Gdouble; 
  1065.       Y3 : Gdouble); 
  1066.    --  Cr: a cairo context 
  1067.    --  X1: the X coordinate of the first control point 
  1068.    --  Y1: the Y coordinate of the first control point 
  1069.    --  X2: the X coordinate of the second control point 
  1070.    --  Y2: the Y coordinate of the second control point 
  1071.    --  X3: the X coordinate of the end of the curve 
  1072.    --  Y3: the Y coordinate of the end of the curve 
  1073.    -- 
  1074.    --  Adds a cubic Bézier spline to the path from the current point to 
  1075.    --  position (X3, Y3) in user-space coordinates, using (X1, Y1) and 
  1076.    --  (X2, Y2) as the control points. After this call the current point 
  1077.    --  will be (X3, Y3). 
  1078.    -- 
  1079.    --  If there is no current point before the call to Curve_To 
  1080.    --  this function will behave as if preceded by a call to 
  1081.    --  Move_To (Cr, X1, Y1). 
  1082.  
  1083.    procedure Arc 
  1084.      (Cr     : Cairo_Context; 
  1085.       Xc     : Gdouble; 
  1086.       Yc     : Gdouble; 
  1087.       Radius : Gdouble; 
  1088.       Angle1 : Gdouble; 
  1089.       Angle2 : Gdouble); 
  1090.    --  Cr: a cairo context 
  1091.    --  Xc: X position of the center of the arc 
  1092.    --  Yc: Y position of the center of the arc 
  1093.    --  Radius: the Radius of the arc 
  1094.    --  Angle1: the start angle, in radians 
  1095.    --  Angle2: the end angle, in radians 
  1096.    -- 
  1097.    --  Adds a circular arc of the given radius to the current path.  The 
  1098.    --  arc is centered at (Xc, Yc), begins at Angle1 and proceeds in 
  1099.    --  the direction of increasing angles to end at Angle2. If Angle2 is 
  1100.    --  less than Angle1 it will be progressively increased by 2*M_PI 
  1101.    --  until it is greater than Angle1. 
  1102.    -- 
  1103.    --  If there is a current point, an initial line segment will be added 
  1104.    --  to the path to connect the current point to the beginning of the 
  1105.    --  arc. If this initial line is undesired, it can be avoided by 
  1106.    --  calling New_Sub_Path before calling Arc. 
  1107.    -- 
  1108.    --  Angles are measured in radians. An angle of 0.0 is in the direction 
  1109.    --  of the positive X axis (in user space). An angle of M_PI/2.0 radians 
  1110.    --  (90 degrees) is in the direction of the positive Y axis (in 
  1111.    --  user space). Angles increase in the direction from the positive X 
  1112.    --  axis toward the positive Y axis. So with the default transformation 
  1113.    --  matrix, angles increase in a clockwise direction. 
  1114.    -- 
  1115.    --  (To convert from degrees to radians, use degrees * (Pi / 180.0)) 
  1116.    -- 
  1117.    --  This function gives the arc in the direction of increasing angles; 
  1118.    --  see Cairo_Arc_Negative to get the arc in the direction of 
  1119.    --  decreasing angles. 
  1120.    -- 
  1121.    --  The arc is circular in user space. To achieve an elliptical arc, 
  1122.    --  you can scale the current transformation matrix by different 
  1123.    --  amounts in the X and Y directions. For example, to draw an ellipse 
  1124.    --  in the box given by X, Y, Width, Height: 
  1125.    -- 
  1126.    --  Cairo_Save (Cr); 
  1127.    --  Cairo_Translate (Cr, X + Width / 2.0, Y + Height / 2.0); 
  1128.    --  Cairo_Scale (Cr, Width / 2.0, Height / 2.0); 
  1129.    --  Cairo_Arc (Cr, 0.0, 0.0, 1.0, 0.0, 2 * Pi); 
  1130.    --  Cairo_Restore (Cr); 
  1131.  
  1132.    procedure Arc_Negative 
  1133.      (Cr     : Cairo_Context; 
  1134.       Xc     : Gdouble; 
  1135.       Yc     : Gdouble; 
  1136.       Radius : Gdouble; 
  1137.       Angle1 : Gdouble; 
  1138.       Angle2 : Gdouble); 
  1139.    --  Cr: a cairo context 
  1140.    --  Xc: X position of the center of the arc 
  1141.    --  Yc: Y position of the center of the arc 
  1142.    --  Radius: the Radius of the arc 
  1143.    --  Angle1: the start angle, in radians 
  1144.    --  Angle2: the end angle, in radians 
  1145.    -- 
  1146.    --  Adds a circular arc of the given radius to the current path.  The 
  1147.    --  arc is centered at (Xc, Yc), begins at Angle1 and proceeds in 
  1148.    --  the direction of decreasing angles to end at Angle2. If Angle2 is 
  1149.    --  greater than Angle1 it will be progressively decreased by 2*Pi 
  1150.    --  until it is less than Angle1. 
  1151.    -- 
  1152.    --  See Arc for more details. This function differs only in the 
  1153.    --  direction of the arc between the two angles. 
  1154.  
  1155.    procedure Rel_Move_To (Cr : Cairo_Context; Dx : Gdouble; Dy : Gdouble); 
  1156.    --  Cr: a cairo context 
  1157.    --  Dx: the X offset 
  1158.    --  Dy: the Y offset 
  1159.    -- 
  1160.    --  Begin a new sub-path. After this call the current point will offset 
  1161.    --  by (X, Y). 
  1162.    -- 
  1163.    --  Given a current point of (X, Y), Rel_Move_To (Cr, Dx, Dy) 
  1164.    --  is logically equivalent to Move_To (Cr, X + Dx, Y + Dy). 
  1165.    -- 
  1166.    --  It is an error to call this function with no current point. Doing 
  1167.    --  so will cause cr to shutdown with a status of 
  1168.    --  Cairo_Status_No_Current_Point. 
  1169.  
  1170.    procedure Rel_Line_To (Cr : Cairo_Context; Dx : Gdouble; Dy : Gdouble); 
  1171.    --  Cr: a cairo context 
  1172.    --  Dx: the X offset to the end of the new line 
  1173.    --  Dy: the Y offset to the end of the new line 
  1174.    -- 
  1175.    --  Relative-coordinate version of Line_To. Adds a line to the 
  1176.    --  path from the current point to a point that is offset from the 
  1177.    --  current point by (Dx, Dy) in user space. After this call the 
  1178.    --  current point will be offset by (Dx, Dy). 
  1179.    -- 
  1180.    --  Given a current point of (X, Y), Rel_Line_To (Cr, Dx, Dy) 
  1181.    --  is logically equivalent to Cairo_Line_To(Cr, X + Dx, Y + Dy). 
  1182.    -- 
  1183.    --  It is an error to call this function with no current point. Doing 
  1184.    --  so will cause cr to shutdown with a status of 
  1185.    --  Cairo_Status_No_Current_Point. 
  1186.  
  1187.    procedure Rel_Curve_To 
  1188.      (Cr  : Cairo_Context; 
  1189.       Dx1 : Gdouble; 
  1190.       Dy1 : Gdouble; 
  1191.       Dx2 : Gdouble; 
  1192.       Dy2 : Gdouble; 
  1193.       Dx3 : Gdouble; 
  1194.       Dy3 : Gdouble); 
  1195.    --  Cr: a cairo context 
  1196.    --  Dx1: the X offset to the first control point 
  1197.    --  Dy1: the Y offset to the first control point 
  1198.    --  Dx2: the X offset to the second control point 
  1199.    --  Dy2: the Y offset to the second control point 
  1200.    --  Dx3: the X offset to the end of the curve 
  1201.    --  Dy3: the Y offset to the end of the curve 
  1202.    -- 
  1203.    --  Relative-coordinate version of Cairo_Curve_To. All offsets are 
  1204.    --  relative to the current point. Adds a cubic Bézier spline to the 
  1205.    --  path from the current point to a point offset from the current 
  1206.    --  point by (Dx3, Dy3), using points offset by (Dx1, Dy1) and 
  1207.    --  (Dx2, Dy2) as the control points. After this call the current 
  1208.    --  point will be offset by (Dx3, Dy3). 
  1209.    -- 
  1210.    --  Given a current point of (X, Y), Cairo_Rel_Curve_To(Cr, Dx1, 
  1211.    --  Dy1, Dx2, Dy2, Dx3, Dy3) is logically equivalent to 
  1212.    --  Cairo_Curve_To(Cr, X+Dx1, Y+Dy1, X+Dx2, Y+Dy2, X+Dx3, Y+Dy3). 
  1213.    -- 
  1214.    --  It is an error to call this function with no current point. Doing 
  1215.    --  so will cause cr to shutdown with a status of 
  1216.    --  Cairo_Status_No_Current_Point. 
  1217.  
  1218.    procedure Rectangle 
  1219.      (Cr     : Cairo_Context; 
  1220.       X      : Gdouble; 
  1221.       Y      : Gdouble; 
  1222.       Width  : Gdouble; 
  1223.       Height : Gdouble); 
  1224.    --  Cr: a cairo context 
  1225.    --  X: the X coordinate of the top left corner of the rectangle 
  1226.    --  Y: the Y coordinate to the top left corner of the rectangle 
  1227.    --  Width: the Width of the rectangle 
  1228.    --  Height: the Height of the rectangle 
  1229.    -- 
  1230.    --  Adds a closed sub-path rectangle of the given size to the current 
  1231.    --  path at position (X, Y) in user-space coordinates. 
  1232.    -- 
  1233.    --  This function is logically equivalent to: 
  1234.    -- 
  1235.    --  Move_To (Cr, x, Y); 
  1236.    --  Rel_Line_To (Cr, Width, 0); 
  1237.    --  Rel_Line_To (Cr, 0, Height); 
  1238.    --  Rel_Line_To (Cr, -Width, 0); 
  1239.    --  Close_Path (Cr); 
  1240.  
  1241.    procedure Close_Path (Cr : Cairo_Context); 
  1242.    --  Cr: a cairo context 
  1243.    -- 
  1244.    --  Adds a line segment to the path from the current point to the 
  1245.    --  beginning of the current sub-path, (the most recent point passed to 
  1246.    --  Move_To), and closes this sub-path. After this call the 
  1247.    --  current point will be at the joined endpoint of the sub-path. 
  1248.    -- 
  1249.    --  The behavior of Close_Path is distinct from simply calling 
  1250.    --  Line_To with the equivalent coordinate in the case of 
  1251.    --  stroking. When a closed sub-path is stroked, there are no caps on 
  1252.    --  the ends of the sub-path. Instead, there is a line join connecting 
  1253.    --  the final and initial segments of the sub-path. 
  1254.    -- 
  1255.    --  If there is no current point before the call to Close_Path, 
  1256.    --  this function will have no effect. 
  1257.    -- 
  1258.    --  Note: As of cairo version 1.2.4 any call to Close_Path will 
  1259.    --  place an explicit MOVE_TO element into the path immediately after 
  1260.    --  the CLOSE_PATH element, (which can be seen in Copy_Path for 
  1261.    --  example). This can simplify path processing in some cases as it may 
  1262.    --  not be necessary to save the "last move_to point" during processing 
  1263.    --  as the MOVE_TO immediately after the CLOSE_PATH will provide that 
  1264.    --  point. 
  1265.  
  1266.    procedure Path_Extents 
  1267.      (Cr : Cairo_Context; 
  1268.       X1 : access Gdouble; 
  1269.       Y1 : access Gdouble; 
  1270.       X2 : access Gdouble; 
  1271.       Y2 : access Gdouble); 
  1272.    --  Cr: a cairo context 
  1273.    --  X1: left of the resulting extents 
  1274.    --  Y1: top of the resulting extents 
  1275.    --  X2: right of the resulting extents 
  1276.    --  Y2: bottom of the resulting extents 
  1277.    -- 
  1278.    --  Computes a bounding box in user-space coordinates covering the 
  1279.    --  points on the current path. If the current path is empty, returns 
  1280.    --  an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, 
  1281.    --  surface dimensions and clipping are not taken into account. 
  1282.    -- 
  1283.    --  Contrast with Fill_Extents and Stroke_Extents which 
  1284.    --  return the extents of only the area that would be "inked" by 
  1285.    --  the corresponding drawing operations. 
  1286.    -- 
  1287.    --  The result of Path_Extents is defined as equivalent to the 
  1288.    --  limit of Stroke_Extents with Cairo_Line_Cap_Round as the 
  1289.    --  line width approaches 0.0, (but never reaching the empty-rectangle 
  1290.    --  returned by Cairo_Stroke_Extents for a line width of 0.0). 
  1291.    -- 
  1292.    --  Specifically, this means that zero-area sub-paths such as 
  1293.    --  Move_To;Line_To segments, (even degenerate cases where the coordinates 
  1294.    --  to both calls are identical), will be considered as contributing to the 
  1295.    --  extents. However, a lone Move_To will not contribute to the results of 
  1296.    --  Path_Extents. 
  1297.    -- 
  1298.    --  Since: 1.6 
  1299.  
  1300.    -------------- 
  1301.    -- Painting -- 
  1302.    -------------- 
  1303.  
  1304.    procedure Paint (Cr : Cairo_Context); 
  1305.    --  Cr: a cairo context 
  1306.    -- 
  1307.    --  A drawing operator that paints the current source everywhere within 
  1308.    --  the current clip region. 
  1309.  
  1310.    procedure Paint_With_Alpha (Cr : Cairo_Context; Alpha : Gdouble); 
  1311.    --  Cr: a cairo context 
  1312.    --  Alpha: Alpha value, between 0 (transparent) and 1 (opaque) 
  1313.    -- 
  1314.    --  A drawing operator that paints the current source everywhere within the 
  1315.    --  current clip region using a mask of constant alpha value alpha. The 
  1316.    --  effect is similar to Paint, but the drawing is faded out using the alpha 
  1317.    --  value. 
  1318.  
  1319.    procedure Mask (Cr : Cairo_Context; Pattern : Cairo_Pattern); 
  1320.    --  Cr: a cairo context 
  1321.    --  Pattern: a Cairo_Pattern 
  1322.    -- 
  1323.    --  A drawing operator that paints the current source using the alpha 
  1324.    --  channel of pattern as a mask. (Opaque areas of pattern are painted with 
  1325.    --  the source, transparent areas are not painted.) 
  1326.  
  1327.    procedure Mask_Surface 
  1328.      (Cr        : Cairo_Context; 
  1329.       Surface   : Cairo_Surface; 
  1330.       Surface_X : Gdouble; 
  1331.       Surface_Y : Gdouble); 
  1332.    --  Cr: a cairo context 
  1333.    --  Surface: a Cairo_Surface 
  1334.    --  Surface_X: X coordinate at which to place the origin of surface 
  1335.    --  Surface_Y: Y coordinate at which to place the origin of surface 
  1336.    -- 
  1337.    --  A drawing operator that paints the current source 
  1338.    --  using the alpha channel of surface as a mask. (Opaque 
  1339.    --  areas of surface are painted with the source, transparent 
  1340.    --  areas are not painted.) 
  1341.  
  1342.    procedure Stroke (Cr : Cairo_Context); 
  1343.    --  Cr: a cairo context 
  1344.    -- 
  1345.    --  A drawing operator that strokes the current path according to the 
  1346.    --  current line width, line join, line cap, and dash settings. After 
  1347.    --  Cairo_Stroke, the current path will be cleared from the cairo 
  1348.    --  context. See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, 
  1349.    --  and Stroke_Preserve. 
  1350.    -- 
  1351.    --  Note: Degenerate segments and sub-paths are treated specially and 
  1352.    --  provide a useful result. These can result in two different 
  1353.    --  situations: 
  1354.    -- 
  1355.    --  1. Zero-length "on" segments set in Set_Dash. If the cap 
  1356.    --  style is Cairo_Line_Cap_Round or Cairo_Line_Cap_Square then these 
  1357.    --  segments will be drawn as circular dots or squares respectively. In 
  1358.    --  the case of Cairo_Line_Cap_Square, the orientation of the squares 
  1359.    --  is determined by the direction of the underlying path. 
  1360.    -- 
  1361.    --  2. A sub-path created by Cairo_Move_To followed by either a 
  1362.    --  Cairo_Close_Path or one or more calls to Cairo_Line_To to the 
  1363.    --  same coordinate as the Cairo_Move_To. If the cap style is 
  1364.    --  Cairo_Line_Cap_Round then these sub-paths will be drawn as circular 
  1365.    --  dots. Note that in the case of Cairo_Line_Cap_Square a degenerate 
  1366.    --  sub-path will not be drawn at all, (since the correct orientation 
  1367.    --  is indeterminate). 
  1368.    -- 
  1369.    --  In no case will a cap style of Cairo_Line_Cap_Butt cause anything 
  1370.    --  to be drawn in the case of either degenerate segments or sub-paths. 
  1371.  
  1372.    procedure Stroke_Preserve (Cr : Cairo_Context); 
  1373.    --  Cr: a cairo context 
  1374.    -- 
  1375.    --  A drawing operator that strokes the current path according to the 
  1376.    --  current line width, line join, line cap, and dash settings. Unlike 
  1377.    --  Cairo_Stroke, Cairo_Stroke_Preserve preserves the path within the 
  1378.    --  cairo context. 
  1379.    -- 
  1380.    --  See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and 
  1381.    --  Stroke_Preserve. 
  1382.  
  1383.    procedure Fill (Cr : Cairo_Context); 
  1384.    --  Cr: a cairo context 
  1385.    -- 
  1386.    --  A drawing operator that fills the current path according to the 
  1387.    --  current fill rule, (each sub-path is implicitly closed before being 
  1388.    --  filled). After Fill, the current path will be cleared from 
  1389.    --  the cairo context. See Set_Fill_Rule and Fill_Preserve. 
  1390.  
  1391.    procedure Fill_Preserve (Cr : Cairo_Context); 
  1392.    --  Cr: a cairo context 
  1393.    -- 
  1394.    --  A drawing operator that fills the current path according to the 
  1395.    --  current fill rule, (each sub-path is implicitly closed before being 
  1396.    --  filled). Unlike Fill, Fill_Preserve preserves the path within the 
  1397.    --  cairo context. 
  1398.    -- 
  1399.    --  See Set_Fill_Rule and Fill. 
  1400.  
  1401.    procedure Copy_Page (Cr : Cairo_Context); 
  1402.    --  Cr: a cairo context 
  1403.    -- 
  1404.    --  Emits the current page for backends that support multiple pages, but 
  1405.    --  doesn't clear it, so, the contents of the current page will be retained 
  1406.    --  for the next page too.  Use Show_Page if you want to get an 
  1407.    --  empty page after the emission. 
  1408.    -- 
  1409.    --  This is a convenience function that simply calls 
  1410.    --  Cairo.Surface.Copy_Page on Cr's target. 
  1411.  
  1412.    procedure Show_Page (Cr : Cairo_Context); 
  1413.    --  Cr: a cairo context 
  1414.    -- 
  1415.    --  Emits and clears the current page for backends that support multiple 
  1416.    --  pages.  Use Copy_Page if you don't want to clear the page. 
  1417.    -- 
  1418.    --  This is a convenience function that simply calls 
  1419.    --  Cairo.Surface.Show_Page on cr's target. 
  1420.  
  1421.    ------------------------ 
  1422.    -- Insideness testing -- 
  1423.    ------------------------ 
  1424.  
  1425.    type Cairo_Bool is new Boolean; 
  1426.  
  1427.    function In_Stroke 
  1428.      (Cr   : Cairo_Context; 
  1429.       X    : Gdouble; 
  1430.       Y    : Gdouble) 
  1431.       return Cairo_Bool; 
  1432.    --  Cr: a cairo context 
  1433.    --  X: X coordinate of the point to test 
  1434.    --  Y: Y coordinate of the point to test 
  1435.    -- 
  1436.    --  Tests whether the given point is inside the area that would be 
  1437.    --  affected by a Stroke operation given the current path and 
  1438.    --  stroking parameters. Surface dimensions and clipping are not taken 
  1439.    --  into account. 
  1440.    -- 
  1441.    --  See Stroke, Set_Line_Width, Set_Line_Join, 
  1442.    --  Set_Line_Cap, Set_Dash, and Stroke_Preserve. 
  1443.    -- 
  1444.    --  Return value: A non-zero value if the point is inside, or zero if 
  1445.    --  outside. 
  1446.  
  1447.    function In_Fill 
  1448.      (Cr   : Cairo_Context; 
  1449.       X    : Gdouble; 
  1450.       Y    : Gdouble) 
  1451.       return Cairo_Bool; 
  1452.    --  Cr: a cairo context 
  1453.    --  X: X coordinate of the point to test 
  1454.    --  Y: Y coordinate of the point to test 
  1455.    -- 
  1456.    --  Tests whether the given point is inside the area that would be 
  1457.    --  affected by a Fill operation given the current path and 
  1458.    --  filling parameters. Surface dimensions and clipping are not taken 
  1459.    --  into account. 
  1460.    -- 
  1461.    --  See Fill, Set_Fill_Rule and Fill_Preserve. 
  1462.    -- 
  1463.    --  Return value: A non-zero value if the point is inside, or zero if 
  1464.    --  outside. 
  1465.  
  1466.    ------------------------- 
  1467.    -- Rectangular extents -- 
  1468.    ------------------------- 
  1469.  
  1470.    procedure Stroke_Extents 
  1471.      (Cr : Cairo_Context; 
  1472.       X1 : access Gdouble; 
  1473.       Y1 : access Gdouble; 
  1474.       X2 : access Gdouble; 
  1475.       Y2 : access Gdouble); 
  1476.    --  Cr: a cairo context 
  1477.    --  X1: left of the resulting extents 
  1478.    --  Y1: top of the resulting extents 
  1479.    --  X2: right of the resulting extents 
  1480.    --  Y2: bottom of the resulting extents 
  1481.    -- 
  1482.    --  Computes a bounding box in user coordinates covering the area that 
  1483.    --  would be affected, (the "inked" area), by a Stroke 
  1484.    --  operation given the current path and stroke parameters. 
  1485.    --  If the current path is empty, returns an empty rectangle ((0,0), (0,0)). 
  1486.    --  Surface dimensions and clipping are not taken into account. 
  1487.    -- 
  1488.    --  Note that if the line width is set to exactly zero, then 
  1489.    --  Stroke_Extents will return an empty rectangle. Contrast with 
  1490.    --  Path_Extents which can be used to compute the non-empty 
  1491.    --  bounds as the line width approaches zero. 
  1492.    -- 
  1493.    --  Note that Stroke_Extents must necessarily do more work to 
  1494.    --  compute the precise inked areas in light of the stroke parameters, 
  1495.    --  so Path_Extents may be more desirable for sake of 
  1496.    --  performance if non-inked path extents are desired. 
  1497.    -- 
  1498.    --  See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and 
  1499.    --  Stroke_Preserve. 
  1500.  
  1501.    procedure Fill_Extents 
  1502.      (Cr : Cairo_Context; 
  1503.       X1 : access Gdouble; 
  1504.       Y1 : access Gdouble; 
  1505.       X2 : access Gdouble; 
  1506.       Y2 : access Gdouble); 
  1507.    --  Cr: a cairo context 
  1508.    --  X1: left of the resulting extents 
  1509.    --  Y1: top of the resulting extents 
  1510.    --  X2: right of the resulting extents 
  1511.    --  Y2: bottom of the resulting extents 
  1512.    -- 
  1513.    --  Computes a bounding box in user coordinates covering the area that 
  1514.    --  would be affected, (the "inked" area), by a Fill operation 
  1515.    --  given the current path and fill parameters. If the current path is 
  1516.    --  empty, returns an empty rectangle ((0,0), (0,0)). Surface 
  1517.    --  dimensions and clipping are not taken into account. 
  1518.    -- 
  1519.    --  Contrast with Path_Extents, which is similar, but returns 
  1520.    --  non-zero extents for some paths with no inked area, (such as a 
  1521.    --  simple line segment). 
  1522.    -- 
  1523.    --  Note that Fill_Extents must necessarily do more work to 
  1524.    --  compute the precise inked areas in light of the fill rule, so 
  1525.    --  Path_Extents may be more desirable for sake of performance 
  1526.    --  if the non-inked path extents are desired. 
  1527.    -- 
  1528.    --  See Fill, Set_Fill_Rule and Fill_Preserve. 
  1529.  
  1530.    -------------- 
  1531.    -- Clipping -- 
  1532.    -------------- 
  1533.  
  1534.    procedure Reset_Clip (Cr : Cairo_Context); 
  1535.    --  Cr: a cairo context 
  1536.    -- 
  1537.    --  Reset the current clip region to its original, unrestricted 
  1538.    --  state. That is, set the clip region to an infinitely large shape 
  1539.    --  containing the target surface. Equivalently, if infinity is too 
  1540.    --  hard to grasp, one can imagine the clip region being reset to the 
  1541.    --  exact bounds of the target surface. 
  1542.    -- 
  1543.    --  Note that code meant to be reusable should not call 
  1544.    --  Reset_Clip as it will cause results unexpected by higher-level code 
  1545.    --  which calls Clip. Consider using Save and Restore around Clip as a more 
  1546.    --  robust means of temporarily restricting the clip region. 
  1547.  
  1548.    procedure Clip (Cr : Cairo_Context); 
  1549.    --  Cr: a cairo context 
  1550.    -- 
  1551.    --  Establishes a new clip region by intersecting the current clip 
  1552.    --  region with the current path as it would be filled by Fill 
  1553.    --  and according to the current fill rule (see Set_Fill_Rule). 
  1554.    -- 
  1555.    --  After Clip, the current path will be cleared from the cairo 
  1556.    --  context. 
  1557.    -- 
  1558.    --  The current clip region affects all drawing operations by 
  1559.    --  effectively masking out any changes to the surface that are outside 
  1560.    --  the current clip region. 
  1561.    -- 
  1562.    --  Calling Clip can only make the clip region smaller, never 
  1563.    --  larger. But the current clip is part of the graphics state, so a 
  1564.    --  temporary restriction of the clip region can be achieved by 
  1565.    --  calling Clip within a Save/Restore 
  1566.    --  pair. The only other means of increasing the size of the clip 
  1567.    --  region is Reset_Clip. 
  1568.  
  1569.    procedure Clip_Preserve (Cr : Cairo_Context); 
  1570.    --  Cr: a cairo context 
  1571.    -- 
  1572.    --  Establishes a new clip region by intersecting the current clip 
  1573.    --  region with the current path as it would be filled by Fill 
  1574.    --  and according to the current fill rule (see Set_Fill_Rule). 
  1575.    -- 
  1576.    --  Unlike Clip, Clip_Preserve preserves the path within 
  1577.    --  the cairo context. 
  1578.    -- 
  1579.    --  The current clip region affects all drawing operations by 
  1580.    --  effectively masking out any changes to the surface that are outside 
  1581.    --  the current clip region. 
  1582.    -- 
  1583.    --  Calling Clip_Preserve can only make the clip region smaller, never 
  1584.    --  larger. But the current clip is part of the graphics state, so a 
  1585.    --  temporary restriction of the clip region can be achieved by 
  1586.    --  calling Clip_Preserve within a Save/Restore 
  1587.    --  pair. The only other means of increasing the size of the clip 
  1588.    --  region is Reset_Clip. 
  1589.  
  1590.    procedure Clip_Extents 
  1591.      (Cr : Cairo_Context; 
  1592.       X1 : access Gdouble; 
  1593.       Y1 : access Gdouble; 
  1594.       X2 : access Gdouble; 
  1595.       Y2 : access Gdouble); 
  1596.    --  Cr: a cairo context 
  1597.    --  X1: left of the resulting extents 
  1598.    --  Y1: top of the resulting extents 
  1599.    --  X2: right of the resulting extents 
  1600.    --  Y2: bottom of the resulting extents 
  1601.    -- 
  1602.    --  Computes a bounding box in user coordinates covering the area inside the 
  1603.    --  current clip. 
  1604.    -- 
  1605.    --  Since: 1.4 
  1606.  
  1607.    type Cairo_Rectangle is record 
  1608.       X      : aliased Gdouble; 
  1609.       Y      : aliased Gdouble; 
  1610.       Width  : aliased Gdouble; 
  1611.       Height : aliased Gdouble; 
  1612.    end record; 
  1613.    --  X: X coordinate of the left side of the rectangle 
  1614.    --  Y: Y coordinate of the the top side of the rectangle 
  1615.    --  Width: Width of the rectangle 
  1616.    --  Height: Height of the rectangle 
  1617.    -- 
  1618.    --  A data structure for holding a rectangle. 
  1619.    -- 
  1620.    --  Since: 1.4 
  1621.  
  1622.    type Cairo_Rectangle_Array is array (Natural) of Cairo_Rectangle; 
  1623.    type Cairo_Rectangle_Array_Access is access all Cairo_Rectangle_Array; 
  1624.  
  1625.    type Cairo_Rectangle_List is record 
  1626.       Status         : aliased Cairo_Status; 
  1627.       Rectangles     : Cairo_Rectangle_Array_Access; 
  1628.       --  Warning: for efficiency reasons, Rectangles is a direct mapping to 
  1629.       --  the C structure. Therefore, there is no bounds checking on this 
  1630.       --  array, user needs to make sure only to access data between indexes 0 
  1631.       --  and Num_Rectanges-1. 
  1632.       Num_Rectangles : aliased Gint; 
  1633.    end record; 
  1634.    --  Status: Error Status of the rectangle list 
  1635.    --  Rectangles: Array containing the Rectangles 
  1636.    --  Num_Rectangles: Number of rectangles in this list 
  1637.    -- 
  1638.    --  A data structure for holding a Dynamically allocated 
  1639.    --  array of rectangles. 
  1640.    -- 
  1641.    --  Since: 1.4 
  1642.    pragma Convention (C_Pass_By_Copy, Cairo_Rectangle_List); 
  1643.  
  1644.    type Cairo_Rectangle_List_Access is access all Cairo_Rectangle_List; 
  1645.  
  1646.    function Copy_Clip_Rectangle_List 
  1647.      (Cr   : Cairo_Context) 
  1648.       return Cairo_Rectangle_List_Access; 
  1649.    --  Cr: a cairo context 
  1650.    -- 
  1651.    --  Gets the current clip region as a list of rectangles in user 
  1652.    --  coordinates. 
  1653.    --  Never returns NULL. 
  1654.    -- 
  1655.    --  The status in the list may be Cairo_Status_Clip_Not_Representable to 
  1656.    --  indicate that the clip region cannot be represented as a list of 
  1657.    --  user-space rectangles. The status may have other values to indicate 
  1658.    --  other errors. 
  1659.    -- 
  1660.    --  Returns: the current clip region as a list of rectangles in user 
  1661.    --  coordinates, 
  1662.    --  which should be destroyed using Rectangle_List_Destroy. 
  1663.    -- 
  1664.    --  Since: 1.4 
  1665.  
  1666.    procedure Rectangle_List_Destroy 
  1667.      (Rectangle_List : access Cairo_Rectangle_List); 
  1668.    --  Rectangle_List: a rectangle list, as obtained from Copy_Clip_Rectangles 
  1669.    -- 
  1670.    --  Unconditionally frees Rectangle_List and all associated 
  1671.    --  references. After this call, the Rectangle_List pointer must not 
  1672.    --  be dereferenced. 
  1673.    -- 
  1674.    --  Since: 1.4 
  1675.  
  1676.    ------------------------- 
  1677.    -- Font/Text functions -- 
  1678.    ------------------------- 
  1679.  
  1680.    type Cairo_Scaled_Font is private; 
  1681.    --  A Cairo_Scaled_Font is a font scaled to a particular size and device 
  1682.    --  resolution. A Cairo_Scaled_Font is most useful for low-level font 
  1683.    --  usage where a library or application wants to cache a reference 
  1684.    --  to a scaled font to speed up the computation of metrics. 
  1685.    -- 
  1686.    --  There are various types of scaled fonts, depending on the font backend 
  1687.    --  they use. The type of a scaled font can be queried using 
  1688.    --  Cairo.Scaled_Font.Get_Type. 
  1689.    -- 
  1690.    --  Memory management of Cairo_Scaled_Font is done with 
  1691.    --  Cairo.Scaled_Font.Reference and Cairo.Scaled_Font.Destroy. 
  1692.  
  1693.    type Cairo_Font_Face is private; 
  1694.    --  A Cairo_Font_Face specifies all aspects of a font other 
  1695.    --  than the size or font matrix (a font matrix is used to distort 
  1696.    --  a font by sheering it or scaling it unequally in the two 
  1697.    --  directions) . A font face can be set on a Cairo_Context by using 
  1698.    --  Set_Font_Face; the size and font matrix are set with 
  1699.    --  Set_Font_Size and Set_Font_Matrix. 
  1700.    -- 
  1701.    --  There are various types of font faces, depending on the font backend 
  1702.    --  they use. The type of a font face can be queried using 
  1703.    --  Cairo.Font_Face.Get_Type. 
  1704.    -- 
  1705.    --  Memory management of Cairo_Font_Face is done with 
  1706.    --  Cairo.Font_Face.Reference and Cairo.Font_Face.Destroy. 
  1707.    -- 
  1708.    --  The Cairo_glyph structure holds information about a single glyph when 
  1709.    --  drawing or measuring text. A font is (in simple terms) a collection of 
  1710.    --  shapes used to draw text. A glyph is one of these shapes. There can be 
  1711.    --  multiple glyphs for a single character (alternates to be used in 
  1712.    --  different contexts, for example), or a glyph can be a ligature of 
  1713.    --  multiple characters. Cairo doesn't expose any way of converting input 
  1714.    --  text into glyphs, so in order to use the Cairo interfaces that take 
  1715.    --  arrays of glyphs, you must directly access the appropriate underlying 
  1716.    --  font system. 
  1717.    -- 
  1718.    --  Note that the offsets given by X and Y are not cumulative. When 
  1719.    --  drawing or measuring text, each glyph is individually positioned 
  1720.    --  with respect to the overall origin 
  1721.    type Cairo_Glyph is record 
  1722.       Index : aliased Gulong; 
  1723.       --  Glyph Index in the font. The exact interpretation of the 
  1724.       --  glyph index depends on the font technology being used. 
  1725.  
  1726.       X     : aliased Gdouble; 
  1727.       --  The offset in the X direction between the origin used for 
  1728.       --  drawing or measuring the string and the origin of this glyph. 
  1729.  
  1730.       Y     : aliased Gdouble; 
  1731.       --  The offset in the Y direction between the origin used for drawing or 
  1732.       --  measuring the string and the origin of this glyph. 
  1733.    end record; 
  1734.    pragma Convention (C_Pass_By_Copy, Cairo_Glyph); 
  1735.  
  1736.    type Cairo_Text_Cluster is record 
  1737.       Num_Bytes  : aliased Gint; 
  1738.       --  The number of bytes of UTF-8 text covered by cluster 
  1739.  
  1740.       Num_Glyphs : aliased Gint; 
  1741.       --  The number of glyphs covered by cluster 
  1742.    end record; 
  1743.    --  The Cairo_text_cluster structure holds information about a single text 
  1744.    --  cluster. A text cluster is a minimal mapping of some glyphs 
  1745.    --  corresponding to some UTF-8 text. 
  1746.    -- 
  1747.    --  For a cluster to be valid, both num_bytes and num_glyphs should 
  1748.    --  be non-negative, and at least one should be non-zero. 
  1749.    --  Note that clusters with zero glyphs are not as well supported as 
  1750.    --  normal clusters.  For example, PDF rendering applications typically 
  1751.    --  ignore those clusters when PDF text is being selected. 
  1752.    -- 
  1753.    --  See Show_Text_Glyphs for how clusters are used in advanced 
  1754.    --  text operations. 
  1755.    -- 
  1756.    --  Since: 1.8 
  1757.    pragma Convention (C_Pass_By_Copy, Cairo_Text_Cluster); 
  1758.  
  1759.    subtype Cairo_Text_Cluster_Flags is Guint; 
  1760.    --  Specifies properties of a text cluster mapping. 
  1761.    -- 
  1762.    --  Since: 1.8 
  1763.  
  1764.    Cairo_Text_Cluster_Flag_Backward : constant Cairo_Text_Cluster_Flags := 1; 
  1765.    --  The clusters in the cluster array map to glyphs in the glyph array from 
  1766.    --  end to start. 
  1767.  
  1768.    type Cairo_Text_Extents is record 
  1769.       X_Bearing : aliased Gdouble; 
  1770.       --  The horizontal distance from the origin to the 
  1771.       --  leftmost part of the glyphs as drawn. Positive if the 
  1772.       --  glyphs lie entirely to the right of the origin. 
  1773.  
  1774.       Y_Bearing : aliased Gdouble; 
  1775.       --  The vertical distance from the origin to the 
  1776.       --  topmost part of the glyphs as drawn. Positive only if the 
  1777.       --  glyphs lie completely below the origin; will usually be 
  1778.       --  negative. 
  1779.  
  1780.       Width     : aliased Gdouble; 
  1781.       --  Width of the glyphs as drawn 
  1782.  
  1783.       Height    : aliased Gdouble; 
  1784.       --  Height of the glyphs as drawn 
  1785.  
  1786.       X_Advance : aliased Gdouble; 
  1787.       --  Distance to advance in the X direction after drawing these glyphs 
  1788.  
  1789.       Y_Advance : aliased Gdouble; 
  1790.       --  Distance to advance in the Y direction 
  1791.       --  after drawing these glyphs. Will typically be zero except 
  1792.       --  for vertical text layout as found in East-Asian languages. 
  1793.    end record; 
  1794.    --  The Cairo_text_extents structure stores the extents of a single glyph 
  1795.    --  or a string of glyphs in user-space coordinates. Because text extents 
  1796.    --  are in user-space coordinates, they are mostly, but not entirely, 
  1797.    --  independent of the current transformation matrix. If you call 
  1798.    --  Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported 
  1799.    --  text extents will not be doubled. They will change slightly due to 
  1800.    --  hinting (so you can't assume that metrics are independent of the 
  1801.    --  transformation matrix), but otherwise will remain unchanged. 
  1802.    pragma Convention (C_Pass_By_Copy, Cairo_Text_Extents); 
  1803.  
  1804.    type Cairo_Font_Extents is record 
  1805.       Ascent        : aliased Gdouble; 
  1806.       --  The distance that the font extends above the baseline. 
  1807.       --  Note that this is not always exactly equal to the maximum 
  1808.       --  of the extents of all the glyphs in the font, but rather 
  1809.       --  is picked to express the font designer's intent as to 
  1810.       --  how the font should align with elements above it. 
  1811.  
  1812.       Descent       : aliased Gdouble; 
  1813.       --  The distance that the font extends below the baseline. 
  1814.       --  This value is positive for typical fonts that include 
  1815.       --  portions below the baseline. Note that this is not always 
  1816.       --  exactly equal to the maximum of the extents of all the 
  1817.       --  glyphs in the font, but rather is picked to express the 
  1818.       --  font designer's intent as to how the the font should 
  1819.       --  align with elements below it. 
  1820.  
  1821.       Height        : aliased Gdouble; 
  1822.       --  The recommended vertical distance between baselines when 
  1823.       --  setting consecutive lines of text with the font. This 
  1824.       --  is greater than ascent+descent by a 
  1825.       --  quantity known as the line spacing or external leading. When space is 
  1826.       --  at a premium, most fonts can be set with only a distance of 
  1827.       --  ascent+descent between lines. 
  1828.  
  1829.       Max_X_Advance : aliased Gdouble; 
  1830.       --  The maximum distance in the X direction that 
  1831.       --  the the origin is advanced for any glyph in the font. 
  1832.  
  1833.       Max_Y_Advance : aliased Gdouble; 
  1834.       --  The maximum distance in the Y direction that 
  1835.       --  the the origin is advanced for any glyph in the font. 
  1836.       --  this will be zero for normal fonts used for horizontal 
  1837.       --  writing. (The scripts of East Asia are sometimes written 
  1838.       --  vertically.) 
  1839.    end record; 
  1840.    --  The Cairo_font_extents structure stores metric information for 
  1841.    --  a font. Values are given in the current user-space coordinate 
  1842.    --  system. 
  1843.    -- 
  1844.    --  Because font metrics are in user-space coordinates, they are 
  1845.    --  mostly, but not entirely, independent of the current transformation 
  1846.    --  matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as 
  1847.    --  big, but the reported text extents will not be doubled. They will 
  1848.    --  change slightly due to hinting (so you can't assume that metrics are 
  1849.    --  independent of the transformation matrix), but otherwise will remain 
  1850.    --  unchanged. 
  1851.    pragma Convention (C_Pass_By_Copy, Cairo_Font_Extents); 
  1852.  
  1853.    type Cairo_Font_Slant is ( 
  1854.                              Cairo_Font_Slant_Normal, 
  1855.                              Cairo_Font_Slant_Italic, 
  1856.                              Cairo_Font_Slant_Oblique); 
  1857.    --  Specifies variants of a font face based on their slant. 
  1858.    pragma Convention (C, Cairo_Font_Slant); 
  1859.  
  1860.    type Cairo_Font_Weight is ( 
  1861.                               Cairo_Font_Weight_Normal, 
  1862.                               Cairo_Font_Weight_Bold); 
  1863.    --  Specifies variants of a font face based on their weight. 
  1864.    pragma Convention (C, Cairo_Font_Weight); 
  1865.  
  1866.    type Cairo_Subpixel_Order is 
  1867.      (Cairo_Subpixel_Order_Default, 
  1868.       --  Use the default subpixel order for the target device 
  1869.  
  1870.       Cairo_Subpixel_Order_Rgb, 
  1871.       --  Subpixel elements are arranged horizontally with red at the left 
  1872.  
  1873.       Cairo_Subpixel_Order_Bgr, 
  1874.       --  Subpixel elements are arranged horizontally with blue at the left 
  1875.  
  1876.       Cairo_Subpixel_Order_Vrgb, 
  1877.       --  Subpixel elements are arranged vertically with red at the top 
  1878.  
  1879.       Cairo_Subpixel_Order_Vbgr 
  1880.       --  Subpixel elements are arranged vertically with blue at the top 
  1881.      ); 
  1882.    --  The subpixel order specifies the order of color elements within 
  1883.    --  each pixel on the display device when rendering with an 
  1884.    --  antialiasing mode of CAIRO_ANTIALIAS_SUBPIXEL. 
  1885.    pragma Convention (C, Cairo_Subpixel_Order); 
  1886.  
  1887.    type Cairo_Hint_Style is 
  1888.      (Cairo_Hint_Style_Default, 
  1889.       --  Use the default hint style for font backend and target device 
  1890.  
  1891.       Cairo_Hint_Style_None, 
  1892.       --  Do not hint outlines 
  1893.  
  1894.       Cairo_Hint_Style_Slight, 
  1895.       --  Hint outlines slightly to improve contrast while retaining good 
  1896.       --  fidelity to the original shapes. 
  1897.  
  1898.       Cairo_Hint_Style_Medium, 
  1899.       --  Hint outlines with medium strength giving a compromise between 
  1900.       --  fidelity to the original shapes and contrast 
  1901.  
  1902.       Cairo_Hint_Style_Full 
  1903.       --  Hint outlines to maximize contrast 
  1904.      ); 
  1905.    --  Specifies the type of hinting to do on font outlines. Hinting 
  1906.    --  is the process of fitting outlines to the pixel grid in order 
  1907.    --  to improve the appearance of the result. Since hinting outlines 
  1908.    --  involves distorting them, it also reduces the faithfulness 
  1909.    --  to the original outline shapes. Not all of the outline hinting 
  1910.    --  styles are supported by all font backends. 
  1911.    -- 
  1912.    --  New entries may be added in future versions. 
  1913.    pragma Convention (C, Cairo_Hint_Style); 
  1914.  
  1915.    type Cairo_Hint_Metrics is 
  1916.      (Cairo_Hint_Metrics_Default, 
  1917.       --  Hint metrics in the default manner for the font backend and target 
  1918.       --  device 
  1919.  
  1920.       Cairo_Hint_Metrics_Off, 
  1921.       --  Do not hint font metrics 
  1922.  
  1923.       Cairo_Hint_Metrics_On 
  1924.       --  Hint font metrics 
  1925.      ); 
  1926.    --  Specifies whether to hint font metrics; hinting font metrics 
  1927.    --  means quantizing them so that they are integer values in 
  1928.    --  device space. Doing this improves the consistency of 
  1929.    --  letter and line spacing, however it also means that text 
  1930.    --  will be laid out differently at different zoom factors. 
  1931.    pragma Convention (C, Cairo_Hint_Metrics); 
  1932.  
  1933.    type Cairo_Font_Options is private; 
  1934.    --  An opaque structure holding all options that are used when 
  1935.    --  rendering fonts. 
  1936.    -- 
  1937.    --  Individual features of a Cairo_Font_Options can be set or 
  1938.    --  accessed using functions named 
  1939.    --  Cairo.Font_Options.Set_<feature_Name> and 
  1940.    --  Cairo.Font_Options.Get_<feature_Name>, like 
  1941.    --  Cairo.Font_Options.Set_Antialias and 
  1942.    --  Cairo.Font_Options.Get_Antialias. 
  1943.    -- 
  1944.    --  New features may be added to a Cairo_font_options in the 
  1945.    --  future.  For this reason, Cairo.Font_Options.Copy, 
  1946.    --  Cairo.Font_Options.Equal, Cairo.Font_Options.Merge, and 
  1947.    --  Cairo.Font_Options.Hash should be used to copy, check 
  1948.    --  for equality, merge, or compute a hash value of 
  1949.    --  Cairo_Font_Options objects. 
  1950.  
  1951.    --  This interface is for dealing with text as text, not caring about the 
  1952.    --  font object inside the the Cairo_Context. 
  1953.  
  1954.    procedure Select_Font_Face 
  1955.      (Cr     : Cairo_Context; 
  1956.       Family : String; 
  1957.       Slant  : Cairo_Font_Slant; 
  1958.       Weight : Cairo_Font_Weight); 
  1959.    --  Cr: a Cairo_Context 
  1960.    --  Family: a font Family name, encoded in UTF-8 
  1961.    --  Slant: the Slant for the font 
  1962.    --  Weight: the Weight for the font 
  1963.    -- 
  1964.    --  Note: The Select_Font_Face function call is part of what 
  1965.    --  the cairo designers call the "toy" text API. It is convenient for 
  1966.    --  short demos and simple programs, but it is not expected to be 
  1967.    --  adequate for serious text-using applications. 
  1968.    -- 
  1969.    --  Selects a family and style of font from a simplified description as 
  1970.    --  a family name, slant and weight. Cairo provides no operation to 
  1971.    --  list available family names on the system (this is a "toy", 
  1972.    --  remember), but the standard CSS2 generic family names, ("serif", 
  1973.    --  "sans-serif", "cursive", "fantasy", "monospace"), are likely to 
  1974.    --  work as expected. 
  1975.    -- 
  1976.    --  It is expected that most applications will need to use a more 
  1977.    --  comprehensive font handling and text layout library, (for example, 
  1978.    --  pango), in conjunction with cairo. 
  1979.    -- 
  1980.    --  If text is drawn without a call to Select_Font_Face, (nor 
  1981.    --  Set_Font_Face nor Set_Scaled_Font), the default 
  1982.    --  family is platform-specific, but is essentially "sans-serif". 
  1983.    --  Default slant is Cairo_Font_Slant_Normal, and default weight is 
  1984.    --  Cairo_Font_Weight_Normal. 
  1985.    -- 
  1986.    --  This function is equivalent to a call to 
  1987.    --  Cairo.Font_Face.Toy_Font_Face_Create followed by Set_Font_Face. 
  1988.  
  1989.    procedure Set_Font_Size (Cr : Cairo_Context; Size : Gdouble); 
  1990.    --  Cr: a Cairo_Context 
  1991.    --  Size: the new font Size, in user space units 
  1992.    -- 
  1993.    --  Sets the current font matrix to a scale by a factor of size, replacing 
  1994.    --  any font matrix previously set with Set_Font_Size or 
  1995.    --  Set_Font_Matrix. This results in a font size of size user space 
  1996.    --  units. (More precisely, this matrix will result in the font's 
  1997.    --  em-square being a size by size square in user space.) 
  1998.    -- 
  1999.    --  If text is drawn without a call to Set_Font_Size, (nor Set_Font_Matrix 
  2000.    --  nor Set_Scaled_Font), the default font size is 10.0. 
  2001.  
  2002.    procedure Set_Font_Matrix 
  2003.      (Cr     : Cairo_Context; 
  2004.       Matrix : access Cairo_Matrix); 
  2005.    --  Cr: a Cairo_Context 
  2006.    --  Matrix: a Cairo_Matrix describing a transform to be applied to 
  2007.    --  the current font. 
  2008.    -- 
  2009.    --  Sets the current font matrix to matrix. The font matrix gives a 
  2010.    --  transformation from the design space of the font (in this space, 
  2011.    --  the em-square is 1 unit by 1 unit) to user space. Normally, a 
  2012.    --  simple scale is used (see Set_Font_Size), but a more 
  2013.    --  complex font matrix can be used to shear the font 
  2014.    --  or stretch it unequally along the two axes 
  2015.  
  2016.    procedure Get_Font_Matrix 
  2017.      (Cr     : Cairo_Context; 
  2018.       Matrix : access Cairo_Matrix); 
  2019.    --  Cr: a Cairo_Context 
  2020.    --  Matrix: return value for the Matrix 
  2021.    -- 
  2022.    --  Stores the current font matrix into matrix. See Set_Font_Matrix. 
  2023.  
  2024.    procedure Set_Font_Options 
  2025.      (Cr      : Cairo_Context; 
  2026.       Options : Cairo_Font_Options); 
  2027.    --  Cr: a Cairo_Context 
  2028.    --  Options: font Options to use 
  2029.    -- 
  2030.    --  Sets a set of custom font rendering options for the Cairo_Context. 
  2031.    --  Rendering options are derived by merging these options with the 
  2032.    --  options derived from underlying surface; if the value in options 
  2033.    --  has a default value (like Cairo_Antialias_Default), then the value 
  2034.    --  from the surface is used. 
  2035.  
  2036.    procedure Get_Font_Options 
  2037.      (Cr      : Cairo_Context; 
  2038.       Options : Cairo_Font_Options); 
  2039.    --  Cr: a Cairo_Context 
  2040.    --  Options: a Cairo_Font_Options object into which to store 
  2041.    --    the retrieved options. All existing values are overwritten 
  2042.    -- 
  2043.    --  Retrieves font rendering options set via Set_Font_Options. 
  2044.    --  Note that the returned options do not include any options derived 
  2045.    --  from the underlying surface; they are literally the options 
  2046.    --  passed to Set_Font_Options. 
  2047.  
  2048.    procedure Set_Font_Face 
  2049.      (Cr        : Cairo_Context; 
  2050.       Font_Face : Cairo_Font_Face); 
  2051.    --  Cr: a Cairo_Context 
  2052.    --  Font_Face: a Cairo_Font_Face, or Null_Font_Face to restore to the 
  2053.    --  default font 
  2054.    -- 
  2055.    --  Replaces the current Cairo_Font_Face object in the Cairo_Context with 
  2056.    --  font_face. The replaced font face in the Cairo_Context will be 
  2057.    --  destroyed if there are no other references to it. 
  2058.  
  2059.    function Get_Font_Face (Cr : Cairo_Context) return Cairo_Font_Face; 
  2060.    --  Cr: a Cairo_Context 
  2061.    -- 
  2062.    --  Gets the current font face for a Cairo_Context. 
  2063.    -- 
  2064.    --  Return value: the current font face.  This object is owned by 
  2065.    --  cairo. To keep a reference to it, you must call 
  2066.    --  Cairo.Font_Face.Reference. 
  2067.    -- 
  2068.    --  This function never returns Null_Font_Face. If memory cannot be 
  2069.    --  allocated, a special "nil" Cairo_Font_Face object will be returned on 
  2070.    --  which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this 
  2071.    --  nil object will cause its error state to propagate to other objects it 
  2072.    --  is passed to, (for example, calling Set_Font_Face with a nil font 
  2073.    --  will trigger an error that will shutdown the Cairo_Context object). 
  2074.  
  2075.    procedure Set_Scaled_Font 
  2076.      (Cr          : Cairo_Context; 
  2077.       Scaled_Font : access Cairo_Scaled_Font); 
  2078.    --  Cr: a Cairo_Context 
  2079.    --  Scaled_Font: a Cairo_Scaled_Font 
  2080.    -- 
  2081.    --  Replaces the current font face, font matrix, and font options in 
  2082.    --  the Cairo_Context with those of the Cairo_Scaled_Font.  Except for 
  2083.    --  some translation, the current CTM of the Cairo_Context should be the 
  2084.    --  same as that of the Cairo_Scaled_Font, which can be accessed 
  2085.    --  using Cairo.Scaled_Font.Get_Ctm. 
  2086.    -- 
  2087.    --  Since: 1.2 
  2088.  
  2089.    function Get_Scaled_Font (Cr : Cairo_Context) return Cairo_Scaled_Font; 
  2090.    --  Cr: a Cairo_Context 
  2091.    -- 
  2092.    --  Gets the current scaled font for a Cairo_Context. 
  2093.    -- 
  2094.    --  Return value: the current scaled font. This object is owned by 
  2095.    --  cairo. To keep a reference to it, you must call 
  2096.    --  Cairo.Scaled_Font.Reference. 
  2097.    -- 
  2098.    --  This function never returns Null_Font_Face. If memory cannot be 
  2099.    --  allocated, a special "nil" Cairo_Scaled_Font object will be returned on 
  2100.    --  which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this 
  2101.    --  nil object will cause its error state to propagate to other objects it 
  2102.    --  is passed to, (for example, calling Set_Font_Face with a nil font 
  2103.    --  will trigger an error that will shutdown the Cairo_Context object). 
  2104.    -- 
  2105.    --  Since: 1.4 
  2106.  
  2107.    procedure Show_Text 
  2108.      (Cr   : Cairo_Context; 
  2109.       Utf8 : String); 
  2110.    --  Cr: a cairo context 
  2111.    --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr 
  2112.    -- 
  2113.    --  A drawing operator that generates the shape from a string of UTF-8 
  2114.    --  characters, rendered according to the current Font_Face, Font_Size 
  2115.    --  (Font_Matrix), and Font_Options. 
  2116.    -- 
  2117.    --  This function first computes a set of glyphs for the string of 
  2118.    --  text. The first glyph is placed so that its origin is at the 
  2119.    --  current point. The origin of each subsequent glyph is offset from 
  2120.    --  that of the previous glyph by the advance values of the previous 
  2121.    --  glyph. 
  2122.    -- 
  2123.    --  After this call the current point is moved to the origin of where 
  2124.    --  the next glyph would be placed in this same progression. That is, 
  2125.    --  the current point will be at the origin of the final glyph offset 
  2126.    --  by its advance values. This allows for easy display of a single 
  2127.    --  logical string with multiple calls to Show_Text. 
  2128.    -- 
  2129.    --  Note: The Show_Text function call is part of what the cairo 
  2130.    --  designers call the "toy" text API. It is convenient for short demos 
  2131.    --  and simple programs, but it is not expected to be adequate for 
  2132.    --  serious text-using applications. See Show_Glyphs for the 
  2133.    --  "real" text display API in cairo. 
  2134.  
  2135.    procedure Show_Glyphs 
  2136.      (Cr         : Cairo_Context; 
  2137.       Glyphs     : access Cairo_Glyph; 
  2138.       Num_Glyphs : Gint); 
  2139.    --  Cr: a cairo context 
  2140.    --  Glyphs: array of Glyphs to show 
  2141.    --  Num_Glyphs: number of glyphs to show 
  2142.    -- 
  2143.    --  A drawing operator that generates the shape from an array of glyphs, 
  2144.    --  rendered according to the current font face, font size 
  2145.    --  (font matrix), and font options. 
  2146.  
  2147.    procedure Text_Path 
  2148.      (Cr   : Cairo_Context; 
  2149.       Utf8 : String); 
  2150.    --  Cr: a cairo context 
  2151.    --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr 
  2152.    -- 
  2153.    --  Adds closed paths for text to the current path.  The generated 
  2154.    --  path if filled, achieves an effect similar to that of 
  2155.    --  Show_Text. 
  2156.    -- 
  2157.    --  Text conversion and positioning is done similar to Show_Text. 
  2158.    -- 
  2159.    --  Like Show_Text, After this call the current point is 
  2160.    --  moved to the origin of where the next glyph would be placed in 
  2161.    --  this same progression.  That is, the current point will be at 
  2162.    --  the origin of the final glyph offset by its advance values. 
  2163.    --  This allows for chaining multiple calls to to Cairo_Text_Path 
  2164.    --  without having to set current point in between. 
  2165.    -- 
  2166.    --  Note: The Text_Path function call is part of what the cairo 
  2167.    --  designers call the "toy" text API. It is convenient for short demos 
  2168.    --  and simple programs, but it is not expected to be adequate for 
  2169.    --  serious text-using applications. See Glyph_Path for the 
  2170.    --  "real" text path API in cairo. 
  2171.  
  2172.    procedure Text_Extents 
  2173.      (Cr      : Cairo_Context; 
  2174.       Utf8    : Interfaces.C.Strings.chars_ptr; 
  2175.       Extents : access Cairo_Text_Extents); 
  2176.    --  Cr: a Cairo_Context 
  2177.    --  Utf8: a NUL-terminated string of text encoded in UTF-8, or Null_Ptr 
  2178.    --  Extents: a Cairo_Text_Extents object into which the results 
  2179.    --  will be stored 
  2180.    -- 
  2181.    --  Gets the extents for a string of text. The extents describe a 
  2182.    --  user-space rectangle that encloses the "inked" portion of the text, 
  2183.    --  (as it would be drawn by Show_Text). Additionally, the 
  2184.    --  x_advance and y_advance values indicate the amount by which the 
  2185.    --  current point would be advanced by Cairo_Show_Text. 
  2186.    -- 
  2187.    --  Note that whitespace characters do not directly contribute to the 
  2188.    --  size of the rectangle (extents.width and extents.height). They do 
  2189.    --  contribute indirectly by changing the position of non-whitespace 
  2190.    --  characters. In particular, trailing whitespace characters are 
  2191.    --  likely to not affect the size of the rectangle, though they will 
  2192.    --  affect the x_advance and y_advance values. 
  2193.  
  2194.    procedure Glyph_Extents 
  2195.      (Cr         : Cairo_Context; 
  2196.       Glyphs     : access Cairo_Glyph; 
  2197.       Num_Glyphs : Gint; 
  2198.       Extents    : access Cairo_Text_Extents); 
  2199.    --  Cr: a Cairo_Context 
  2200.    --  Glyphs: an array of Cairo_Glyph objects 
  2201.    --  Num_Glyphs: the number of elements in glyphs 
  2202.    --  Extents: a Cairo_Text_Extents object into which the results 
  2203.    --  will be stored 
  2204.    -- 
  2205.    --  Gets the extents for an array of glyphs. The extents describe a 
  2206.    --  user-space rectangle that encloses the "inked" portion of the 
  2207.    --  glyphs, (as they would be drawn by Show_Glyphs). 
  2208.    --  Additionally, the X_Advance and Y_Advance values indicate the 
  2209.    --  amount by which the current point would be advanced by 
  2210.    --  Show_Glyphs. 
  2211.    -- 
  2212.    --  Note that whitespace glyphs do not contribute to the size of the 
  2213.    --  rectangle (Extents.Width and Extents.Height). 
  2214.  
  2215.    procedure Font_Extents 
  2216.      (Cr      : Cairo_Context; 
  2217.       Extents : access Cairo_Font_Extents); 
  2218.    --  Cr: a Cairo_Context 
  2219.    --  Extents: a Cairo_Font_Extents object into which the results 
  2220.    --  will be stored. 
  2221.    -- 
  2222.    --  Gets the font extents for the currently selected font. 
  2223.  
  2224.    type Cairo_Font_Type is 
  2225.      (Cairo_Font_Type_Toy, 
  2226.       --  The font was created using cairo's toy font api (Since: 1.8) 
  2227.  
  2228.       Cairo_Font_Type_Ft, 
  2229.       --  The font is of type FreeType 
  2230.  
  2231.       Cairo_Font_Type_Win32, 
  2232.       --  The font is of type Win32 
  2233.  
  2234.       Cairo_Font_Type_Quartz, 
  2235.       --  The font is of type Quartz (Since: 1.6) 
  2236.  
  2237.       Cairo_Font_Type_User 
  2238.       --  The font was create using cairo's user font api 
  2239.      ); 
  2240.    --  Cairo_font_type is used to describe the type of a given font 
  2241.    --  face or scaled font. The font types are also known as "font 
  2242.    --  backends" within Cairo. 
  2243.    -- 
  2244.    --  The type of a font face is determined by the function used to 
  2245.    --  create it, which will generally be of the form 
  2246.    --  <type>_Font_Face_Create. The font face type 
  2247.    --  can be queried 
  2248.    --  with Cairo.Font_Face.Get_Type 
  2249.    -- 
  2250.    --  The various Cairo_Font_Face functions can be used with a font face 
  2251.    --  of any type. 
  2252.    -- 
  2253.    --  The type of a scaled font is determined by the type of the font 
  2254.    --  face passed to Cairo.Scaled_Font.Create. The scaled font type can 
  2255.    --  be queried with Cairo.Scaled_Font.Get_Type 
  2256.    -- 
  2257.    --  The various Cairo_scaled_font functions can be used with scaled 
  2258.    --  fonts of any type, but some font backends also provide 
  2259.    --  type-specific functions that must only be called with a scaled font 
  2260.    --  of the appropriate type. These functions have names that begin with 
  2261.    --  <type>_Scaled_Font such as Ft_Scaled_Font_Lock_Face. 
  2262.    -- 
  2263.    --  The behavior of calling a type-specific function with a scaled font 
  2264.    --  of the wrong type is undefined. 
  2265.    -- 
  2266.    --  New entries may be added in future versions. 
  2267.    -- 
  2268.    --  Since: 1.2 
  2269.    pragma Convention (C, Cairo_Font_Type); 
  2270.  
  2271.    --------------------- 
  2272.    -- Query functions -- 
  2273.    --------------------- 
  2274.  
  2275.    function Get_Operator (Cr : Cairo_Context) return Cairo_Operator; 
  2276.    --  Cr: a cairo context 
  2277.    -- 
  2278.    --  Gets the current compositing operator for a cairo context. 
  2279.    -- 
  2280.    --  Return value: the current compositing operator. 
  2281.  
  2282.    function Get_Source (Cr : Cairo_Context) return Cairo_Pattern; 
  2283.    --  Cr: a cairo context 
  2284.    -- 
  2285.    --  Gets the current source pattern for Cr. 
  2286.    -- 
  2287.    --  Return value: the current source pattern. This object is owned by 
  2288.    --  cairo. To keep a reference to it, you must call 
  2289.    --  Cairo.Pattern.Reference. 
  2290.  
  2291.    function Get_Tolerance (Cr : Cairo_Context) return Gdouble; 
  2292.    --  Cr: a cairo context 
  2293.    -- 
  2294.    --  Gets the current tolerance value, as set by Set_Tolerance. 
  2295.    -- 
  2296.    --  Return value: the current tolerance value. 
  2297.  
  2298.    function Get_Antialias (Cr : Cairo_Context) return Cairo_Antialias; 
  2299.    --  Cr: a cairo context 
  2300.    -- 
  2301.    --  Gets the current shape antialiasing mode, as set by Set_Antialias. 
  2302.    -- 
  2303.    --  Return value: the current shape antialiasing mode. 
  2304.  
  2305.    function Has_Current_Point (Cr : Cairo_Context) return Cairo_Bool; 
  2306.    --  Cr: a cairo context 
  2307.    -- 
  2308.    --  Returns whether a current point is defined on the current path. 
  2309.    --  See Get_Current_Point for details on the current point. 
  2310.    -- 
  2311.    --  Return value: whether a current point is defined. 
  2312.    -- 
  2313.    --  Since: 1.6 
  2314.  
  2315.    procedure Get_Current_Point 
  2316.      (Cr : Cairo_Context; 
  2317.       X  : access Gdouble; 
  2318.       Y  : access Gdouble); 
  2319.    --  Cr: a cairo context 
  2320.    --  X: return value for X coordinate of the current point 
  2321.    --  Y: return value for Y coordinate of the current point 
  2322.    -- 
  2323.    --  Gets the current point of the current path, which is 
  2324.    --  conceptually the final point reached by the path so far. 
  2325.    -- 
  2326.    --  The current point is returned in the user-space coordinate 
  2327.    --  system. If there is no defined current point or if cr is in an 
  2328.    --  error status, X and Y will both be set to 0.0. It is possible to 
  2329.    --  check this in advance with Has_Current_Point. 
  2330.    -- 
  2331.    --  Most path construction functions alter the current point. See the 
  2332.    --  following for details on how they affect the current point: 
  2333.    --  New_Path, New_Sub_Path, Append_Path, Close_Path, Move_To, Line_To, 
  2334.    --  Curve_To, Rel_Move_To, Rel_Line_To, Rel_Curve_To, Arc, Arc_Negative, 
  2335.    --  Rectangle, Text_Path, Glyph_Path, Stroke_To_Path. 
  2336.    -- 
  2337.    --  Some functions use and alter the current point but do not otherwise 
  2338.    --  change current path: Show_Text. 
  2339.    -- 
  2340.    --  Some functions unset the current path and as a result, current point: 
  2341.    --  Fill, Stroke. 
  2342.  
  2343.    function Get_Fill_Rule (Cr : Cairo_Context) return Cairo_Fill_Rule; 
  2344.    --  Cr: a cairo context 
  2345.    -- 
  2346.    --  Gets the current fill rule, as set by Set_Fill_Rule. 
  2347.    -- 
  2348.    --  Return value: the current fill rule. 
  2349.  
  2350.    function Get_Line_Width (Cr : Cairo_Context) return Gdouble; 
  2351.    --  Cr: a cairo context 
  2352.    -- 
  2353.    --  This function returns the current line width value exactly as set by 
  2354.    --  Set_Line_Width. Note that the value is unchanged even if 
  2355.    --  the CTM has changed between the calls to Set_Line_Width and 
  2356.    --  Get_Line_Width. 
  2357.    -- 
  2358.    --  Return value: the current line width. 
  2359.  
  2360.    function Get_Line_Cap (Cr : Cairo_Context) return Cairo_Line_Cap; 
  2361.    --  Cr: a cairo context 
  2362.    -- 
  2363.    --  Gets the current line cap style, as set by Set_Line_Cap. 
  2364.    -- 
  2365.    --  Return value: the current line cap style. 
  2366.  
  2367.    function Get_Line_Join (Cr : Cairo_Context) return Cairo_Line_Join; 
  2368.    --  Cr: a cairo context 
  2369.    -- 
  2370.    --  Gets the current line join style, as set by Set_Line_Join. 
  2371.    -- 
  2372.    --  Return value: the current line join style. 
  2373.  
  2374.    function Get_Miter_Limit (Cr : Cairo_Context) return Gdouble; 
  2375.    --  Cr: a cairo context 
  2376.    -- 
  2377.    --  Gets the current miter limit, as set by Set_Miter_Limit. 
  2378.    -- 
  2379.    --  Return value: the current miter limit. 
  2380.  
  2381.    function Get_Dash_Count (Cr : Cairo_Context) return Gint; 
  2382.    --  Cr: a Cairo_Context 
  2383.    -- 
  2384.    --  This function returns the length of the dash array in cr (0 if dashing 
  2385.    --  is not currently in effect). 
  2386.    -- 
  2387.    --  See also Set_Dash and Get_Dash. 
  2388.    -- 
  2389.    --  Return value: the length of the dash array, or 0 if no dash array set. 
  2390.    -- 
  2391.    --  Since: 1.4 
  2392.  
  2393.    type Dash_Array_Access is access all Dash_Array; 
  2394.  
  2395.    procedure Get_Dash 
  2396.      (Cr     : Cairo_Context; 
  2397.       Dashes : out Dash_Array_Access; 
  2398.       Offset : out Gdouble); 
  2399.    --  Cr: a Cairo_Context 
  2400.    --  Dashes: return value for the dash array, or null 
  2401.    --  Offset: return value for the current dash Offset, or null 
  2402.    -- 
  2403.    --  Gets the current dash array. 
  2404.    -- 
  2405.    --  Since: 1.4 
  2406.  
  2407.    procedure Get_Matrix (Cr : Cairo_Context; Matrix : access Cairo_Matrix); 
  2408.    --  Cr: a cairo context 
  2409.    --  Matrix: return value for the Matrix 
  2410.    -- 
  2411.    --  Stores the current transformation matrix (CTM) into matrix. 
  2412.  
  2413.    function Get_Target (Cr : Cairo_Context) return Cairo_Surface; 
  2414.    --  Cr: a cairo context 
  2415.    -- 
  2416.    --  Gets the target surface for the cairo context as passed to Create. 
  2417.    -- 
  2418.    --  This function will always return a valid pointer, but the result 
  2419.    --  can be a "nil" surface if cr is already in an error state, 
  2420.    --  (ie. Cairo_Status /= Cairo_Status_Success). 
  2421.    --  A nil surface is indicated by 
  2422.    --  Cairo.Surface.Status/= Cairo_Status_Success. 
  2423.    -- 
  2424.    --  Return value: the target surface. This object is owned by cairo. To 
  2425.    --  keep a reference to it, you must call Cairo.Surface.Reference. 
  2426.  
  2427.    function Get_Group_Target (Cr : Cairo_Context) return Cairo_Surface; 
  2428.    --  Cr: a cairo context 
  2429.    -- 
  2430.    --  Gets the current destination surface for the context. This is either 
  2431.    --  the original target surface as passed to Create or the target 
  2432.    --  surface for the current group as started by the most recent call to 
  2433.    --  Push_Group or Push_Group_With_Content. 
  2434.    -- 
  2435.    --  This function will always return a valid pointer, but the result 
  2436.    --  can be a "nil" surface if cr is already in an error state, 
  2437.    --  (ie. Cairo_Status /= Cairo_Status_Success). 
  2438.    --  A nil surface is indicated by Cairo_Status /= Cairo_Status_Success. 
  2439.    -- 
  2440.    --  Return value: the target surface. This object is owned by cairo. To 
  2441.    --  keep a reference to it, you must call Cairo.Surface.Reference. 
  2442.    -- 
  2443.    --  Since: 1.2 
  2444.  
  2445.    type Cairo_Path_Data_Type is 
  2446.      (Cairo_Path_Move_To,    --  A move-to operation 
  2447.       Cairo_Path_Line_To,    --  A line-to operation 
  2448.       Cairo_Path_Curve_To,   --  A curve-to operation 
  2449.       Cairo_Path_Close_Path  --  A close-path operation 
  2450.      ); 
  2451.    --  Cairo_path_data is used to describe the type of one portion 
  2452.    --  of a path when represented as a Cairo_Path. 
  2453.    --  See Cairo_Path_Data for details. 
  2454.    pragma Convention (C, Cairo_Path_Data_Type); 
  2455.  
  2456.    type Header_Type is record 
  2457.       Path_Type : aliased Cairo_Path_Data_Type; 
  2458.       Length    : aliased Gint; 
  2459.    end record; 
  2460.    --  A Path header. See Cairo_Path_Data for details. 
  2461.  
  2462.    type Point_Type is record 
  2463.       X : aliased Gdouble; 
  2464.       Y : aliased Gdouble; 
  2465.    end record; 
  2466.    --  A geometrical point. See Cairo_Path_Data for details. 
  2467.  
  2468.    type Cairo_Path_Data (Discr : Guint := 0) is record 
  2469.       case Discr is 
  2470.          when 0 => 
  2471.             Header : aliased Header_Type; 
  2472.          when others => 
  2473.             Point : aliased Point_Type; 
  2474.       end case; 
  2475.    end record; 
  2476.    --  Cairo_path_data is used to represent the path data inside a 
  2477.    --  Cairo_path. 
  2478.    -- 
  2479.    --  The data structure is designed to try to balance the demands of 
  2480.    --  efficiency and ease-of-use. A path is represented as an array of 
  2481.    --  Cairo_Path_Data, which is a union of headers and points. 
  2482.    -- 
  2483.    --  Each portion of the path is represented by one or more elements in 
  2484.    --  the array, (one header followed by 0 or more points). The length 
  2485.    --  value of the header is the number of array elements for the current 
  2486.    --  portion including the header, (ie. length == 1 +  of points), and 
  2487.    --  where the number of points for each element type is as follows: 
  2488.    -- 
  2489.    --      Cairo_Path_Move_To:     1 point 
  2490.    --      Cairo_Path_Line_To:     1 point 
  2491.    --      Cairo_Path_Curve_To:    3 points 
  2492.    --      Cairo_Path_Close_Path:  0 points 
  2493.    -- 
  2494.    --  The semantics and ordering of the coordinate values are consistent 
  2495.    --  with Move_To, Line_To, Curve_To, and Close_Path. 
  2496.    -- 
  2497.    --  Here is sample code for iterating through a Cairo_Path: 
  2498.    -- 
  2499.    --    declare 
  2500.    --       J    : Gint; 
  2501.    --       Path : Cairo_Path; 
  2502.    --       Data : Cairo_Path_Data; 
  2503.    --     begin 
  2504.    --       Path = Copy_Path (Cr); 
  2505.    -- 
  2506.    --       J := 0; 
  2507.    --       while J < Path.Num_Data loop 
  2508.    --          Data := Path.Data(J); 
  2509.    -- 
  2510.    --          case Data.Header.Path_Type is 
  2511.    -- 
  2512.    --              when Cairo_Path_Move_To => 
  2513.    --                 Do_Move_To_Things (Data(1).Point.X, Data(1).Point.Y); 
  2514.    -- 
  2515.    --              when Cairo_Path_Line_To => 
  2516.    --                 Do_Line_To_Things (Data(1).Point.X, Data(1).Point.Y); 
  2517.    -- 
  2518.    --              when Cairo_Path_Curve_To => 
  2519.    --                 Do_Curve_To_Things (Data(1).Point.X, Data(1).Point.Y, 
  2520.    --                                     Data(2).Point.X, Data(2).Point.Y, 
  2521.    --                                     Data(3).Point.X, Data(3).Point.Y); 
  2522.    -- 
  2523.    --              when Cairo_Path_Curve_To => 
  2524.    --                 Do_Close_Path_Things; 
  2525.    --          end case; 
  2526.    -- 
  2527.    --          J := J + Path.Data[J].Header.Length; 
  2528.    --       end loop; 
  2529.    -- 
  2530.    --       Path_Destroy (Path); 
  2531.    --    end; 
  2532.    -- 
  2533.    --  As of cairo 1.4, cairo does not mind if there are more elements in 
  2534.    --  a portion of the path than needed.  Such elements can be used by 
  2535.    --  users of the cairo API to hold extra values in the path data 
  2536.    --  structure.  For this reason, it is recommended that applications 
  2537.    --  always use Data.Header.Length to iterate over the path data, instead of 
  2538.    --  hardcoding the number of elements for each element type. 
  2539.  
  2540.    type Path_Data_Array is array (Natural) of Cairo_Path_Data; 
  2541.    type Path_Data_Array_Access is access all Path_Data_Array; 
  2542.  
  2543.    type Cairo_Path is record 
  2544.       Status   : aliased Cairo_Status; 
  2545.       Data     : Path_Data_Array_Access; 
  2546.       --  Warning: for efficiency reasons, Data is a direct mapping to the C 
  2547.       --  structure. Therefore, there is no bounds checking on this array, 
  2548.       --  the user needs to make sure only to access data between indexes 
  2549.       --  0 and Num_Data-1. 
  2550.       Num_Data : aliased Gint; 
  2551.    end record; 
  2552.    type Cairo_Path_Access is access all Cairo_Path; 
  2553.    --  Status: the current error Status 
  2554.    --  Data: the elements in the path 
  2555.    --  Num_Data: the number of elements in the data array 
  2556.    -- 
  2557.    --  A data structure for holding a path. This data structure serves as the 
  2558.    --  return value for Copy_Path and Copy_Path_Flat as well the input value 
  2559.    --  for Append_Path. 
  2560.    -- 
  2561.    --  See Cairo_Path_Data for hints on how to iterate over the 
  2562.    --  actual data within the path. 
  2563.    -- 
  2564.    --  The num_data member gives the number of elements in the data 
  2565.    --  array. This number is larger than the number of independent path 
  2566.    --  portions (defined in Cairo_Path_Data_Type), since the data 
  2567.    --  includes both headers and coordinates for each portion. 
  2568.  
  2569.    function Copy_Path (Cr : Cairo_Context) return Cairo_Path_Access; 
  2570.    --  Cr: a cairo context 
  2571.    -- 
  2572.    --  Creates a copy of the current path and returns it to the user as a 
  2573.    --  Cairo_Path. See Cairo_Path_Data for hints on how to iterate 
  2574.    --  over the returned data structure. 
  2575.    -- 
  2576.    --  This function will always return a valid pointer, but the result 
  2577.    --  will have no data (Data = null and Num_Data = 0), if 
  2578.    --  either of the following conditions hold: 
  2579.    -- 
  2580.    --  -> If there is insufficient memory to copy the path. In this 
  2581.    --      case Path.Status will be set to Cairo_Status_No_Memory 
  2582.    -- 
  2583.    --  -> If Cr is already in an error state. In this case 
  2584.    --     Path.Status will contain the same status that 
  2585.    --     would be returned by Status. 
  2586.    -- 
  2587.    --  Return value: the copy of the current path. The caller owns the 
  2588.    --  returned object and should call Path_Destroy when finished with it. 
  2589.  
  2590.    function Copy_Path_Flat (Cr : Cairo_Context) return Cairo_Path_Access; 
  2591.    --  Cr: a cairo context 
  2592.    -- 
  2593.    --  Gets a flattened copy of the current path and returns it to the 
  2594.    --  user as a Cairo_Path. See Cairo_Path_Data for hints on 
  2595.    --  how to iterate over the returned data structure. 
  2596.    -- 
  2597.    --  This function is like Copy_Path except that any curves 
  2598.    --  in the path will be approximated with piecewise-linear 
  2599.    --  approximations, (accurate to within the current tolerance 
  2600.    --  value). That is, the result is guaranteed to not have any elements 
  2601.    --  of type Cairo_Path_Curve_To which will instead be replaced by a 
  2602.    --  series of Cairo_Path_Line_To elements. 
  2603.    -- 
  2604.    --  This function will always return a valid pointer, but the result will 
  2605.    --  have no data (Data = null and Num_Data = 0), if either of the following 
  2606.    --  conditions hold: 
  2607.    -- 
  2608.    --  -> If there is insufficient memory to copy the path. In this 
  2609.    --      case Path.Status will be set to Cairo_Status_No_Memory 
  2610.    -- 
  2611.    --  -> If Cr is already in an error state. In this case 
  2612.    --     Path.Status will contain the same status that 
  2613.    --     would be returned by Status. 
  2614.    -- 
  2615.    --  Return value: the copy of the current path. The caller owns the 
  2616.    --  returned object and should call Path_Destroy when finished 
  2617.    --  with it. 
  2618.  
  2619.    procedure Append_Path 
  2620.      (Cr   : Cairo_Context; 
  2621.       Path : access Cairo_Path); 
  2622.    --  Cr: a cairo context 
  2623.    --  Path: Path to be appended 
  2624.    -- 
  2625.    --  Append the path onto the current path. The path may be either the return 
  2626.    --  value from one of Copy_Path or Copy_Path_Flat or it may be constructed 
  2627.    --  manually. See Cairo_Path for details on how the path data structure 
  2628.    --  should be initialized, and note that Path.Status must be initialized to 
  2629.    --  Cairo_Status_Success. 
  2630.  
  2631.    procedure Path_Destroy (Path : access Cairo_Path); 
  2632.    --  Path: a path previously returned by either Copy_Path or Copy_Path_Flat. 
  2633.    -- 
  2634.    --  Immediately releases all memory associated with Path. After a call 
  2635.    --  to Path_Destroy the Path pointer is no longer valid and should not be 
  2636.    --  used further. 
  2637.    -- 
  2638.    --  Note: Path_Destroy should only be called with an access to a 
  2639.    --  Cairo_Path returned by a cairo function. Any path that is created 
  2640.    --  manually (ie. outside of cairo) should be destroyed manually as well. 
  2641.  
  2642.    -------------------------- 
  2643.    -- Error status queries -- 
  2644.    -------------------------- 
  2645.  
  2646.    function Status (Cr : Cairo_Context) return Cairo_Status; 
  2647.    --  Cr: a cairo context 
  2648.    -- 
  2649.    --  Checks whether an error has previously occurred for this context. 
  2650.    -- 
  2651.    --  Returns: the current status of this context, see Cairo_Status 
  2652.  
  2653.    Null_Context      : constant Cairo_Context; 
  2654.    Null_Surface      : constant Cairo_Surface; 
  2655.    Null_Pattern      : constant Cairo_Pattern; 
  2656.    Null_Scaled_Font  : constant Cairo_Scaled_Font; 
  2657.    Null_Font_Face    : constant Cairo_Font_Face; 
  2658.    Null_Font_Options : constant Cairo_Font_Options; 
  2659.  
  2660. private 
  2661.  
  2662.    pragma Convention (C, Cairo_Destroy_Func); 
  2663.    pragma Convention (C, Cairo_Bool); 
  2664.    pragma Convention (C, Cairo_Status); 
  2665.    pragma Convention (C, Cairo_Operator); 
  2666.    pragma Convention (C, Cairo_Antialias); 
  2667.    pragma Convention (C, Cairo_Fill_Rule); 
  2668.    pragma Convention (C, Cairo_Line_Cap); 
  2669.    pragma Convention (C, Cairo_Line_Join); 
  2670.    pragma Convention (C, Path_Data_Array_Access); 
  2671.    pragma Convention (C_Pass_By_Copy, Cairo_Path); 
  2672.    pragma Convention (C_Pass_By_Copy, Cairo_Rectangle); 
  2673.    pragma Convention (C, Cairo_Rectangle_Array_Access); 
  2674.  
  2675.    pragma Convention (C_Pass_By_Copy, Header_Type); 
  2676.    pragma Convention (C_Pass_By_Copy, Point_Type); 
  2677.    pragma Convention (C_Pass_By_Copy, Cairo_Path_Data); 
  2678.    pragma Unchecked_Union (Cairo_Path_Data); 
  2679.  
  2680.    type Cairo_Context is new System.Address; 
  2681.    Null_Context : constant Cairo_Context := 
  2682.      Cairo_Context (System.Null_Address); 
  2683.    type Cairo_Surface is new System.Address; 
  2684.    Null_Surface : constant Cairo_Surface := 
  2685.      Cairo_Surface (System.Null_Address); 
  2686.    type Cairo_Pattern is new System.Address; 
  2687.    Null_Pattern : constant Cairo_Pattern := 
  2688.      Cairo_Pattern (System.Null_Address); 
  2689.    type Cairo_Scaled_Font is new System.Address; 
  2690.    Null_Scaled_Font : constant Cairo_Scaled_Font := 
  2691.      Cairo_Scaled_Font (System.Null_Address); 
  2692.    type Cairo_Font_Face is new System.Address; 
  2693.    Null_Font_Face : constant Cairo_Font_Face := 
  2694.      Cairo_Font_Face (System.Null_Address); 
  2695.    type Cairo_Font_Options is new System.Address; 
  2696.    Null_Font_Options : constant Cairo_Font_Options := 
  2697.      Cairo_Font_Options (System.Null_Address); 
  2698.    pragma Import (C, Create, "cairo_create"); 
  2699.    pragma Import (C, Reference, "cairo_reference"); 
  2700.    pragma Import (C, Destroy, "cairo_destroy"); 
  2701.    pragma Import (C, Get_Reference_Count, "cairo_get_reference_count"); 
  2702.    pragma Import (C, Get_User_Data, "cairo_get_user_data"); 
  2703.    pragma Import (C, Set_User_Data, "cairo_set_user_data"); 
  2704.    pragma Import (C, Save, "cairo_save"); 
  2705.    pragma Import (C, Restore, "cairo_restore"); 
  2706.    pragma Import (C, Push_Group, "cairo_push_group"); 
  2707.    pragma Import 
  2708.      (C, 
  2709.       Push_Group_With_Content, 
  2710.       "cairo_push_group_with_content"); 
  2711.    pragma Import (C, Pop_Group, "cairo_pop_group"); 
  2712.    pragma Import (C, Pop_Group_To_Source, "cairo_pop_group_to_source"); 
  2713.    pragma Import (C, Set_Operator, "cairo_set_operator"); 
  2714.    pragma Import (C, Set_Source, "cairo_set_source"); 
  2715.    pragma Import (C, Set_Source_Rgb, "cairo_set_source_rgb"); 
  2716.    pragma Import (C, Set_Source_Rgba, "cairo_set_source_rgba"); 
  2717.    pragma Import (C, Set_Source_Surface, "cairo_set_source_surface"); 
  2718.    pragma Import (C, Set_Tolerance, "cairo_set_tolerance"); 
  2719.    pragma Import (C, Set_Antialias, "cairo_set_antialias"); 
  2720.    pragma Import (C, Set_Fill_Rule, "cairo_set_fill_rule"); 
  2721.    pragma Import (C, Set_Line_Width, "cairo_set_line_width"); 
  2722.    pragma Import (C, Set_Line_Cap, "cairo_set_line_cap"); 
  2723.    pragma Import (C, Set_Line_Join, "cairo_set_line_join"); 
  2724.    pragma Import (C, Set_Miter_Limit, "cairo_set_miter_limit"); 
  2725.    pragma Import (C, Translate, "cairo_translate"); 
  2726.    pragma Import (C, Scale, "cairo_scale"); 
  2727.    pragma Import (C, Rotate, "cairo_rotate"); 
  2728.    pragma Import (C, Transform, "cairo_transform"); 
  2729.    pragma Import (C, Set_Matrix, "cairo_set_matrix"); 
  2730.    pragma Import (C, Identity_Matrix, "cairo_identity_matrix"); 
  2731.    pragma Import (C, User_To_Device, "cairo_user_to_device"); 
  2732.    pragma Import 
  2733.      (C, 
  2734.       User_To_Device_Distance, 
  2735.       "cairo_user_to_device_distance"); 
  2736.    pragma Import (C, Device_To_User, "cairo_device_to_user"); 
  2737.    pragma Import 
  2738.      (C, 
  2739.       Device_To_User_Distance, 
  2740.       "cairo_device_to_user_distance"); 
  2741.    pragma Import (C, New_Path, "cairo_new_path"); 
  2742.    pragma Import (C, Move_To, "cairo_move_to"); 
  2743.    pragma Import (C, New_Sub_Path, "cairo_new_sub_path"); 
  2744.    pragma Import (C, Line_To, "cairo_line_to"); 
  2745.    pragma Import (C, Curve_To, "cairo_curve_to"); 
  2746.    pragma Import (C, Arc, "cairo_arc"); 
  2747.    pragma Import (C, Arc_Negative, "cairo_arc_negative"); 
  2748.    pragma Import (C, Rel_Move_To, "cairo_rel_move_to"); 
  2749.    pragma Import (C, Rel_Line_To, "cairo_rel_line_to"); 
  2750.    pragma Import (C, Rel_Curve_To, "cairo_rel_curve_to"); 
  2751.    pragma Import (C, Rectangle, "cairo_rectangle"); 
  2752.    pragma Import (C, Close_Path, "cairo_close_path"); 
  2753.    pragma Import (C, Path_Extents, "cairo_path_extents"); 
  2754.    pragma Import (C, Paint, "cairo_paint"); 
  2755.    pragma Import (C, Paint_With_Alpha, "cairo_paint_with_alpha"); 
  2756.    pragma Import (C, Mask, "cairo_mask"); 
  2757.    pragma Import (C, Mask_Surface, "cairo_mask_surface"); 
  2758.    pragma Import (C, Stroke, "cairo_stroke"); 
  2759.    pragma Import (C, Stroke_Preserve, "cairo_stroke_preserve"); 
  2760.    pragma Import (C, Fill, "cairo_fill"); 
  2761.    pragma Import (C, Fill_Preserve, "cairo_fill_preserve"); 
  2762.    pragma Import (C, Copy_Page, "cairo_copy_page"); 
  2763.    pragma Import (C, Show_Page, "cairo_show_page"); 
  2764.    pragma Import (C, In_Stroke, "cairo_in_stroke"); 
  2765.    pragma Import (C, In_Fill, "cairo_in_fill"); 
  2766.    pragma Import (C, Stroke_Extents, "cairo_stroke_extents"); 
  2767.    pragma Import (C, Fill_Extents, "cairo_fill_extents"); 
  2768.    pragma Import (C, Reset_Clip, "cairo_reset_clip"); 
  2769.    pragma Import (C, Clip, "cairo_clip"); 
  2770.    pragma Import (C, Clip_Preserve, "cairo_clip_preserve"); 
  2771.    pragma Import (C, Clip_Extents, "cairo_clip_extents"); 
  2772.    pragma Import 
  2773.      (C, 
  2774.       Copy_Clip_Rectangle_List, 
  2775.       "cairo_copy_clip_rectangle_list"); 
  2776.    pragma Import (C, Rectangle_List_Destroy, "cairo_rectangle_list_destroy"); 
  2777.    pragma Import (C, Set_Font_Size, "cairo_set_font_size"); 
  2778.    pragma Import (C, Set_Font_Matrix, "cairo_set_font_matrix"); 
  2779.    pragma Import (C, Get_Font_Matrix, "cairo_get_font_matrix"); 
  2780.    pragma Import (C, Set_Font_Options, "cairo_set_font_options"); 
  2781.    pragma Import (C, Get_Font_Options, "cairo_get_font_options"); 
  2782.    pragma Import (C, Set_Font_Face, "cairo_set_font_face"); 
  2783.    pragma Import (C, Get_Font_Face, "cairo_get_font_face"); 
  2784.    pragma Import (C, Set_Scaled_Font, "cairo_set_scaled_font"); 
  2785.    pragma Import (C, Get_Scaled_Font, "cairo_get_scaled_font"); 
  2786.    pragma Import (C, Show_Glyphs, "cairo_show_glyphs"); 
  2787.    --     pragma Import (C, Show_Text_Glyphs, "cairo_show_text_glyphs"); 
  2788.    --     pragma Import (C, Glyph_Path, "cairo_glyph_path"); 
  2789.    pragma Import (C, Text_Extents, "cairo_text_extents"); 
  2790.    pragma Import (C, Glyph_Extents, "cairo_glyph_extents"); 
  2791.    pragma Import (C, Font_Extents, "cairo_font_extents"); 
  2792.    pragma Import (C, Get_Operator, "cairo_get_operator"); 
  2793.    pragma Import (C, Get_Source, "cairo_get_source"); 
  2794.    pragma Import (C, Get_Tolerance, "cairo_get_tolerance"); 
  2795.    pragma Import (C, Get_Antialias, "cairo_get_antialias"); 
  2796.    pragma Import (C, Has_Current_Point, "cairo_has_current_point"); 
  2797.    pragma Import (C, Get_Current_Point, "cairo_get_current_point"); 
  2798.    pragma Import (C, Get_Fill_Rule, "cairo_get_fill_rule"); 
  2799.    pragma Import (C, Get_Line_Width, "cairo_get_line_width"); 
  2800.    pragma Import (C, Get_Line_Cap, "cairo_get_line_cap"); 
  2801.    pragma Import (C, Get_Line_Join, "cairo_get_line_join"); 
  2802.    pragma Import (C, Get_Miter_Limit, "cairo_get_miter_limit"); 
  2803.    pragma Import (C, Get_Dash_Count, "cairo_get_dash_count"); 
  2804.    pragma Import (C, Get_Matrix, "cairo_get_matrix"); 
  2805.    pragma Import (C, Get_Target, "cairo_get_target"); 
  2806.    pragma Import (C, Get_Group_Target, "cairo_get_group_target"); 
  2807.    pragma Import (C, Copy_Path, "cairo_copy_path"); 
  2808.    pragma Import (C, Copy_Path_Flat, "cairo_copy_path_flat"); 
  2809.    pragma Import (C, Append_Path, "cairo_append_path"); 
  2810.    pragma Import (C, Path_Destroy, "cairo_path_destroy"); 
  2811.    pragma Import (C, Status, "cairo_status"); 
  2812.  
  2813. end Cairo;