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. --  A Cairo_Surface is the abstract type representing all different drawing 
  31. --  targets that cairo can render to. The actual drawings are performed using a 
  32. --  Cairo_Context. 
  33. --  </description> 
  34. -- 
  35. --  <c_version>1.8.8</c_version> 
  36. --  <group>Cairo</group> 
  37.  
  38. with System; 
  39.  
  40. package Cairo.Surface is 
  41.  
  42.    -------------------------- 
  43.    -- Surface manipulation -- 
  44.    -------------------------- 
  45.  
  46.    type Cairo_Surface_Type is 
  47.      (Cairo_Surface_Type_Image, 
  48.       Cairo_Surface_Type_Pdf, 
  49.       Cairo_Surface_Type_Ps, 
  50.       Cairo_Surface_Type_Xlib, 
  51.       Cairo_Surface_Type_Xcb, 
  52.       Cairo_Surface_Type_Glitz, 
  53.       Cairo_Surface_Type_Quartz, 
  54.       Cairo_Surface_Type_Win32, 
  55.       Cairo_Surface_Type_Beos, 
  56.       Cairo_Surface_Type_Directfb, 
  57.       Cairo_Surface_Type_Svg, 
  58.       Cairo_Surface_Type_Os2, 
  59.       Cairo_Surface_Type_Win32_Printing, 
  60.       Cairo_Surface_Type_Quartz_Image); 
  61.    pragma Convention (C, Cairo_Surface_Type); 
  62.    --  Cairo_Surface_Type is used to describe the type of a given 
  63.    --  surface. The surface types are also known as "backends" or "surface 
  64.    --  backends" within cairo. 
  65.    -- 
  66.    --  The type of a surface is determined by the function used to create 
  67.    --  it, which will generally be of the form 
  68.    --  Cairo.<type>_Surface_Create, 
  69.    --  (though see Cairo.Surface.Create_Similar as well). 
  70.    -- 
  71.    --  The surface type can be queried with Cairo.Surface.Get_Type 
  72.    -- 
  73.    --  The various Cairo_surface functions can be used with surfaces of 
  74.    --  any type, but some backends also provide type-specific functions 
  75.    --  that must only be called with a surface of the appropriate 
  76.    --  type. These functions have names that begin with 
  77.    --  Cairo.<type>_Surface.* such as 
  78.    --  Cairo.Image_Surface.Get_Width. 
  79.    -- 
  80.    --  The behavior of calling a type-specific function with a surface of 
  81.    --  the wrong type is undefined. 
  82.    -- 
  83.    --  New entries may be added in future versions. 
  84.    -- 
  85.    --  Since: 1.2 
  86.  
  87.    function Create_Similar 
  88.      (Other   : Cairo_Surface; 
  89.       Content : Cairo_Content; 
  90.       Width   : Gint; 
  91.       Height  : Gint) 
  92.       return    Cairo_Surface; 
  93.    --  Other: an existing surface used to select the backend of the new surface 
  94.    --  Content: the Content for the new surface 
  95.    --  Width: Width of the new surface, (in device-space units) 
  96.    --  Height: Height of the new surface (in device-space units) 
  97.    -- 
  98.    --  Create a new surface that is as compatible as possible with an 
  99.    --  existing surface. For example the new surface will have the same 
  100.    --  fallback resolution and font options as other. Generally, the new 
  101.    --  surface will also use the same backend as other, unless that is 
  102.    --  not possible for some reason. The type of the returned surface may 
  103.    --  be examined with Cairo.Surface.Get_Type. 
  104.    -- 
  105.    --  Initially the surface contents are all 0 (transparent if contents 
  106.    --  have transparency, black otherwise.) 
  107.    -- 
  108.    --  Return value: a pointer to the newly allocated surface. The caller 
  109.    --  owns the surface and should call Cairo.Surface.Destroy when done 
  110.    --  with it. 
  111.    -- 
  112.    --  This function always returns a valid pointer, but it will return a 
  113.    --  pointer to a "nil" surface if other is already in an error state 
  114.    --  or any other error occurs. 
  115.  
  116.    function Reference (Surface : Cairo_Surface) return Cairo_Surface; 
  117.    --  Surface: a Cairo_Surface 
  118.    -- 
  119.    --  Increases the reference count on surface by one. This prevents 
  120.    --  surface from being destroyed until a matching call to 
  121.    --  Cairo.Surface.Destroy is made. 
  122.    -- 
  123.    --  The number of references to a Cairo_Surface can be get using 
  124.    --  Cairo.Surface.Get_Reference_Count. 
  125.    -- 
  126.    --  Return value: the referenced Cairo_Surface. 
  127.  
  128.    procedure Finish (Surface : Cairo_Surface); 
  129.    --  Surface: the Cairo_Surface to finish 
  130.    -- 
  131.    --  This function finishes the surface and drops all references to 
  132.    --  external resources.  For example, for the Xlib backend it means 
  133.    --  that cairo will no longer access the drawable, which can be freed. 
  134.    --  After calling Cairo.Surface.Finish the only valid operations on a 
  135.    --  surface are getting and setting user, referencing and 
  136.    --  destroying, and flushing and finishing it. 
  137.    --  Further drawing to the surface will not affect the 
  138.    --  surface but will instead trigger a Cairo_Status_Surface_Finished 
  139.    --  error. 
  140.    -- 
  141.    --  When the last call to Cairo.Surface.Destroy decreases the 
  142.    --  reference count to zero, cairo will call Cairo.Surface.Finish if 
  143.    --  it hasn't been called already, before freeing the resources 
  144.    --  associated with the surface. 
  145.  
  146.    procedure Destroy (Surface : Cairo_Surface); 
  147.    --  Surface: a Cairo_Surface 
  148.    -- 
  149.    --  Decreases the reference count on surface by one. If the result is 
  150.    --  zero, then surface and all associated resources are freed.  See 
  151.    --  Cairo.Surface.Reference. 
  152.  
  153.    function Get_Reference_Count (Surface : Cairo_Surface) return Guint; 
  154.    --  Surface: a Cairo_Surface 
  155.    -- 
  156.    --  Returns the current reference count of surface. 
  157.    -- 
  158.    --  Return value: the current reference count of surface.  If the 
  159.    --  object is a nil object, 0 will be returned. 
  160.    -- 
  161.    --  Since: 1.4 
  162.  
  163.    function Status (Surface : Cairo_Surface) return Cairo_Status; 
  164.    --  Surface: a Cairo_Surface 
  165.    -- 
  166.    --  Checks whether an error has previously occurred for this 
  167.    --  surface. 
  168.    -- 
  169.    --  Return value: Cairo_Status_Success, Cairo_Status_Null_Pointer, 
  170.    --     Cairo_Status_No_Memory, Cairo_Status_Read_Error, 
  171.    --     Cairo_Status_Invalid_Content, Cairo_Status_Invalid_Format, or 
  172.    --     Cairo_Status_Invalid_Visual. 
  173.  
  174.    function Get_Type (Surface : Cairo_Surface) return Cairo_Surface_Type; 
  175.    --  Surface: a Cairo_Surface 
  176.    -- 
  177.    --  This function returns the type of the backend used to create 
  178.    --  a surface. See Cairo_Surface_Type for available types. 
  179.    -- 
  180.    --  Return value: The type of surface. 
  181.    -- 
  182.    --  Since: 1.2 
  183.  
  184.    function Get_Content (Surface : Cairo_Surface) return Cairo_Content; 
  185.    --  Surface: a Cairo_Surface 
  186.    -- 
  187.    --  This function returns the content type of surface which indicates 
  188.    --  whether the surface contains color and/or alpha information. See 
  189.    --  Cairo_Content. 
  190.    -- 
  191.    --  Return value: The content type of surface. 
  192.    -- 
  193.    --  Since: 1.2 
  194.  
  195.    function Get_User_Data 
  196.      (Surface : Cairo_Surface; 
  197.       Key     : access Cairo_User_Data_Key) return System.Address; 
  198.    --  Surface: a Cairo_Surface 
  199.    --  Key: the address of the Cairo_User_Data_Key the user data was 
  200.    --  attached to 
  201.    -- 
  202.    --  Return user data previously attached to surface using the specified 
  203.    --  key.  If no user data has been attached with the given key this 
  204.    --  function returns null. 
  205.    -- 
  206.    --  Return value: the user data previously attached or null. 
  207.  
  208.    function Set_User_Data 
  209.      (Surface   : Cairo_Surface; 
  210.       Key       : access Cairo_User_Data_Key; 
  211.       User_Data : System.Address; 
  212.       Destroy   : Cairo_Destroy_Func) return Cairo_Status; 
  213.    --  Surface: a Cairo_Surface 
  214.    --  Key: the address of a Cairo_User_Data_Key to attach the user data to 
  215.    --  User_Data: the user data to attach to the surface 
  216.    --  Destroy: a Cairo_Destroy_Func which will be called when the 
  217.    --  surface is destroyed or when new user data is attached using the 
  218.    --  same key. 
  219.    -- 
  220.    --  Attach user data to surface.  To remove user data from a surface, 
  221.    --  call this function with the key that was used to set it and null 
  222.    --  for data. 
  223.    -- 
  224.    --  Return value: Cairo_Status_Success or Cairo_Status_No_Memory if a 
  225.    --  slot could not be allocated for the user data. 
  226.  
  227.    procedure Get_Font_Options 
  228.      (Surface : Cairo_Surface; 
  229.       Options : access Cairo_Font_Options); 
  230.    --  Surface: a Cairo_Surface 
  231.    --  Options: a Cairo_Font_Options object into which to store 
  232.    --    the retrieved options. All existing values are overwritten 
  233.    -- 
  234.    --  Retrieves the default font rendering options for the surface. 
  235.    --  This allows display surfaces to report the correct subpixel order 
  236.    --  for rendering on them, print surfaces to disable hinting of 
  237.    --  metrics and so forth. The result can then be used with 
  238.    --  Cairo.Scaled_Font.Create. 
  239.  
  240.    procedure Flush (Surface : Cairo_Surface); 
  241.    --  Surface: a Cairo_Surface 
  242.    -- 
  243.    --  Do any pending drawing for the surface and also restore any 
  244.    --  temporary modification's cairo has made to the surface's 
  245.    --  state. This function must be called before switching from 
  246.    --  drawing on the surface with cairo to drawing on it directly 
  247.    --  with native APIs. If the surface doesn't support direct access, 
  248.    --  then this function does nothing. 
  249.  
  250.    procedure Mark_Dirty (Surface : Cairo_Surface); 
  251.    --  Surface: a Cairo_Surface 
  252.    -- 
  253.    --  Tells cairo that drawing has been done to surface using means other 
  254.    --  than cairo, and that cairo should reread any cached areas. Note 
  255.    --  that you must call Cairo.Surface.Flush before doing such drawing. 
  256.  
  257.    procedure Mark_Dirty_Rectangle 
  258.      (Surface : Cairo_Surface; 
  259.       X       : Gint; 
  260.       Y       : Gint; 
  261.       Width   : Gint; 
  262.       Height  : Gint); 
  263.    --  Surface: a Cairo_Surface 
  264.    --  X: X coordinate of dirty rectangle 
  265.    --  Y: Y coordinate of dirtY rectangle 
  266.    --  Width: Width of dirty rectangle 
  267.    --  Height: Height of dirty rectangle 
  268.    -- 
  269.    --  Like Cairo.Surface.Mark_Dirty, but drawing has been done only to 
  270.    --  the specified rectangle, so that cairo can retain cached contents 
  271.    --  for other parts of the surface. 
  272.    -- 
  273.    --  Any cached clip set on the surface will be reset by this function, 
  274.    --  to make sure that future cairo calls have the clip set that they 
  275.    --  expect. 
  276.  
  277.    procedure Set_Device_Offset 
  278.      (Surface  : Cairo_Surface; 
  279.       X_Offset : Gdouble; 
  280.       Y_Offset : Gdouble); 
  281.    --  Surface: a Cairo_Surface 
  282.    --  X_Offset: the offset in the X direction, in device units 
  283.    --  Y_Offset: the offset in the Y direction, in device units 
  284.    -- 
  285.    --  Sets an offset that is added to the device coordinates determined 
  286.    --  by the CTM when drawing to surface. One use case for this function 
  287.    --  is when we want to create a Cairo_Surface that redirects drawing 
  288.    --  for a portion of an onscreen surface to an offscreen surface in a 
  289.    --  way that is completely invisible to the user of the cairo 
  290.    --  API. Setting a transformation via Cairo.Translate isn't 
  291.    --  sufficient to do this, since functions like 
  292.    --  Cairo.Device_To_User will expose the hidden offset. 
  293.    -- 
  294.    --  Note that the offset affects drawing to the surface as well as 
  295.    --  using the surface in a source pattern. 
  296.  
  297.    procedure Get_Device_Offset 
  298.      (Surface  : Cairo_Surface; 
  299.       X_Offset : access Gdouble; 
  300.       Y_Offset : access Gdouble); 
  301.    --  Surface: a Cairo_Surface 
  302.    --  X_Offset: the offset in the X direction, in device units 
  303.    --  Y_Offset: the offset in the Y direction, in device units 
  304.    -- 
  305.    --  This function returns the previous device offset set by 
  306.    --  Cairo.Surface.Set_Device_Offset. 
  307.    -- 
  308.    --  Since: 1.2 
  309.  
  310.    procedure Set_Fallback_Resolution 
  311.      (Surface           : Cairo_Surface; 
  312.       X_Pixels_Per_Inch : Gdouble; 
  313.       Y_Pixels_Per_Inch : Gdouble); 
  314.    --  Surface: a Cairo_Surface 
  315.    --  X_Pixels_Per_Inch: horizontal setting for pixels per inch 
  316.    --  Y_Pixels_Per_Inch: vertical setting for pixels per inch 
  317.    -- 
  318.    --  Set the horizontal and vertical resolution for image fallbacks. 
  319.    -- 
  320.    --  When certain operations aren't supported natively by a backend, 
  321.    --  cairo will fallback by rendering operations to an image and then 
  322.    --  overlaying that image onto the output. For backends that are 
  323.    --  natively vector-oriented, this function can be used to set the 
  324.    --  resolution used for these image fallbacks, (larger values will 
  325.    --  result in more detailed images, but also larger file sizes). 
  326.    -- 
  327.    --  Some examples of natively vector-oriented backends are the ps, pdf, 
  328.    --  and svg backends. 
  329.    -- 
  330.    --  For backends that are natively raster-oriented, image fallbacks are 
  331.    --  still possible, but they are always performed at the native 
  332.    --  device resolution. So this function has no effect on those 
  333.    --  backends. 
  334.    -- 
  335.    --  Note: The fallback resolution only takes effect at the time of 
  336.    --  completing a page (with Cairo.Show_Page or Cairo.Copy_Page) so 
  337.    --  there is currently no way to have more than one fallback resolution 
  338.    --  in effect on a single page. 
  339.    -- 
  340.    --  The default fallback resoultion is 300 pixels per inch in both 
  341.    --  dimensions. 
  342.    -- 
  343.    --  Since: 1.2 
  344.  
  345.    procedure Get_Fallback_Resolution 
  346.      (Surface           : Cairo_Surface; 
  347.       X_Pixels_Per_Inch : access Gdouble; 
  348.       Y_Pixels_Per_Inch : access Gdouble); 
  349.    --  Surface: a Cairo_Surface 
  350.    --  X_Pixels_Per_Inch: horizontal pixels per inch 
  351.    --  Y_Pixels_Per_Inch: vertical pixels per inch 
  352.    -- 
  353.    --  This function returns the previous fallback resolution set by 
  354.    --  Cairo.Surface.Set_Fallback_Resolution, or default fallback 
  355.    --  resolution if never set. 
  356.    -- 
  357.    --  Since: 1.8 
  358.  
  359.    procedure Copy_Page (Surface : Cairo_Surface); 
  360.    --  Surface: a Cairo_Surface 
  361.    -- 
  362.    --  Emits the current page for backends that support multiple pages, 
  363.    --  but doesn't clear it, so that the contents of the current page will 
  364.    --  be retained for the next page.  Use Cairo.Surface.Show_Page if you 
  365.    --  want to get an empty page after the emission. 
  366.    -- 
  367.    --  There is a convenience function for this that takes a Cairo_Context, 
  368.    --  namely Cairo.Copy_Page. 
  369.    -- 
  370.    --  Since: 1.6 
  371.  
  372.    procedure Show_Page (Surface : Cairo_Surface); 
  373.    --  Surface: a Cairo_Surface 
  374.    -- 
  375.    --  Emits and clears the current page for backends that support multiple 
  376.    --  pages.  Use Cairo.Surface.Copy_Page if you don't want to clear the page. 
  377.    -- 
  378.    --  There is a convenience function for this that takes a Cairo_Context, 
  379.    --  namely Cairo_Show_Page. 
  380.    -- 
  381.    --  Since: 1.6 
  382.  
  383.    function Has_Show_Text_Glyphs 
  384.      (Surface : Cairo_Surface) 
  385.       return    Cairo_Bool; 
  386.    --  Surface: a Cairo_Surface 
  387.    -- 
  388.    --  Returns whether the surface supports 
  389.    --  sophisticated Cairo_Show_Text_Glyphs operations.  That is, 
  390.    --  whether it actually uses the provided text and cluster data 
  391.    --  to a Cairo_Show_Text_Glyphs call. 
  392.    -- 
  393.    --  Note: Even if this function returns FALSE, a 
  394.    --  Cairo_Show_Text_Glyphs operation targeted at surface will 
  395.    --  still succeed.  It just will 
  396.    --  act like a Cairo_Show_Glyphs operation.  Users can use this 
  397.    --  function to avoid computing UTF-8 text and cluster mapping if the 
  398.    --  target surface does not use it. 
  399.    -- 
  400.    --  Return value: TRUE if surface supports 
  401.    --                Cairo_Show_Text_Glyphs, FALSE otherwise 
  402.    -- 
  403.    --  Since: 1.8 
  404.  
  405. private 
  406.  
  407.    pragma Import (C, Create_Similar, "cairo_surface_create_similar"); 
  408.    pragma Import (C, Reference, "cairo_surface_reference"); 
  409.    pragma Import (C, Finish, "cairo_surface_finish"); 
  410.    pragma Import (C, Destroy, "cairo_surface_destroy"); 
  411.    pragma Import 
  412.      (C, 
  413.       Get_Reference_Count, 
  414.       "cairo_surface_get_reference_count"); 
  415.    pragma Import (C, Status, "cairo_surface_status"); 
  416.    pragma Import (C, Get_Type, "cairo_surface_get_type"); 
  417.    pragma Import (C, Get_Content, "cairo_surface_get_content"); 
  418.    pragma Import (C, Get_User_Data, "cairo_surface_get_user_data"); 
  419.    pragma Import (C, Set_User_Data, "cairo_surface_set_user_data"); 
  420.    pragma Import (C, Get_Font_Options, "cairo_surface_get_font_options"); 
  421.    pragma Import (C, Flush, "cairo_surface_flush"); 
  422.    pragma Import (C, Mark_Dirty, "cairo_surface_mark_dirty"); 
  423.    pragma Import 
  424.      (C, 
  425.       Mark_Dirty_Rectangle, 
  426.       "cairo_surface_mark_dirty_rectangle"); 
  427.    pragma Import (C, Set_Device_Offset, "cairo_surface_set_device_offset"); 
  428.    pragma Import (C, Get_Device_Offset, "cairo_surface_get_device_offset"); 
  429.    pragma Import 
  430.      (C, 
  431.       Set_Fallback_Resolution, 
  432.       "cairo_surface_set_fallback_resolution"); 
  433.    pragma Import 
  434.      (C, 
  435.       Get_Fallback_Resolution, 
  436.       "cairo_surface_get_fallback_resolution"); 
  437.    pragma Import (C, Copy_Page, "cairo_surface_copy_page"); 
  438.    pragma Import (C, Show_Page, "cairo_surface_show_page"); 
  439.    pragma Import 
  440.      (C, 
  441.       Has_Show_Text_Glyphs, 
  442.       "cairo_surface_has_show_text_glyphs"); 
  443.  
  444. end Cairo.Surface;