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