----------------------------------------------------------------------- -- GtkAda - Ada95 binding for Gtk+/Gnome -- -- -- -- Copyright (C) 2010, AdaCore -- -- -- -- This library is free software; you can redistribute it and/or -- -- modify it under the terms of the GNU General Public -- -- License as published by the Free Software Foundation; either -- -- version 2 of the License, or (at your option) any later version. -- -- -- -- This library is distributed in the hope that it will be useful, -- -- but WITHOUT ANY WARRANTY; without even the implied warranty of -- -- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU -- -- General Public License for more details. -- -- -- -- You should have received a copy of the GNU General Public -- -- License along with this library; if not, write to the -- -- Free Software Foundation, Inc., 59 Temple Place - Suite 330, -- -- Boston, MA 02111-1307, USA. -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- ----------------------------------------------------------------------- -- -- A Cairo_Surface is the abstract type representing all different drawing -- targets that cairo can render to. The actual drawings are performed using a -- Cairo_Context. -- -- -- 1.8.8 -- Cairo with System; package Cairo.Surface is -------------------------- -- Surface manipulation -- -------------------------- type Cairo_Surface_Type is (Cairo_Surface_Type_Image, Cairo_Surface_Type_Pdf, Cairo_Surface_Type_Ps, Cairo_Surface_Type_Xlib, Cairo_Surface_Type_Xcb, Cairo_Surface_Type_Glitz, Cairo_Surface_Type_Quartz, Cairo_Surface_Type_Win32, Cairo_Surface_Type_Beos, Cairo_Surface_Type_Directfb, Cairo_Surface_Type_Svg, Cairo_Surface_Type_Os2, Cairo_Surface_Type_Win32_Printing, Cairo_Surface_Type_Quartz_Image); pragma Convention (C, Cairo_Surface_Type); -- Cairo_Surface_Type is used to describe the type of a given -- surface. The surface types are also known as "backends" or "surface -- backends" within cairo. -- -- The type of a surface is determined by the function used to create -- it, which will generally be of the form -- Cairo._Surface_Create, -- (though see Cairo.Surface.Create_Similar as well). -- -- The surface type can be queried with Cairo.Surface.Get_Type -- -- The various Cairo_surface functions can be used with surfaces of -- any type, but some backends also provide type-specific functions -- that must only be called with a surface of the appropriate -- type. These functions have names that begin with -- Cairo._Surface.* such as -- Cairo.Image_Surface.Get_Width. -- -- The behavior of calling a type-specific function with a surface of -- the wrong type is undefined. -- -- New entries may be added in future versions. -- -- Since: 1.2 function Create_Similar (Other : Cairo_Surface; Content : Cairo_Content; Width : Gint; Height : Gint) return Cairo_Surface; -- Other: an existing surface used to select the backend of the new surface -- Content: the Content for the new surface -- Width: Width of the new surface, (in device-space units) -- Height: Height of the new surface (in device-space units) -- -- Create a new surface that is as compatible as possible with an -- existing surface. For example the new surface will have the same -- fallback resolution and font options as other. Generally, the new -- surface will also use the same backend as other, unless that is -- not possible for some reason. The type of the returned surface may -- be examined with Cairo.Surface.Get_Type. -- -- Initially the surface contents are all 0 (transparent if contents -- have transparency, black otherwise.) -- -- Return value: a pointer to the newly allocated surface. The caller -- owns the surface and should call Cairo.Surface.Destroy when done -- with it. -- -- This function always returns a valid pointer, but it will return a -- pointer to a "nil" surface if other is already in an error state -- or any other error occurs. function Reference (Surface : Cairo_Surface) return Cairo_Surface; -- Surface: a Cairo_Surface -- -- Increases the reference count on surface by one. This prevents -- surface from being destroyed until a matching call to -- Cairo.Surface.Destroy is made. -- -- The number of references to a Cairo_Surface can be get using -- Cairo.Surface.Get_Reference_Count. -- -- Return value: the referenced Cairo_Surface. procedure Finish (Surface : Cairo_Surface); -- Surface: the Cairo_Surface to finish -- -- This function finishes the surface and drops all references to -- external resources. For example, for the Xlib backend it means -- that cairo will no longer access the drawable, which can be freed. -- After calling Cairo.Surface.Finish the only valid operations on a -- surface are getting and setting user, referencing and -- destroying, and flushing and finishing it. -- Further drawing to the surface will not affect the -- surface but will instead trigger a Cairo_Status_Surface_Finished -- error. -- -- When the last call to Cairo.Surface.Destroy decreases the -- reference count to zero, cairo will call Cairo.Surface.Finish if -- it hasn't been called already, before freeing the resources -- associated with the surface. procedure Destroy (Surface : Cairo_Surface); -- Surface: a Cairo_Surface -- -- Decreases the reference count on surface by one. If the result is -- zero, then surface and all associated resources are freed. See -- Cairo.Surface.Reference. function Get_Reference_Count (Surface : Cairo_Surface) return Guint; -- Surface: a Cairo_Surface -- -- Returns the current reference count of surface. -- -- Return value: the current reference count of surface. If the -- object is a nil object, 0 will be returned. -- -- Since: 1.4 function Status (Surface : Cairo_Surface) return Cairo_Status; -- Surface: a Cairo_Surface -- -- Checks whether an error has previously occurred for this -- surface. -- -- Return value: Cairo_Status_Success, Cairo_Status_Null_Pointer, -- Cairo_Status_No_Memory, Cairo_Status_Read_Error, -- Cairo_Status_Invalid_Content, Cairo_Status_Invalid_Format, or -- Cairo_Status_Invalid_Visual. function Get_Type (Surface : Cairo_Surface) return Cairo_Surface_Type; -- Surface: a Cairo_Surface -- -- This function returns the type of the backend used to create -- a surface. See Cairo_Surface_Type for available types. -- -- Return value: The type of surface. -- -- Since: 1.2 function Get_Content (Surface : Cairo_Surface) return Cairo_Content; -- Surface: a Cairo_Surface -- -- This function returns the content type of surface which indicates -- whether the surface contains color and/or alpha information. See -- Cairo_Content. -- -- Return value: The content type of surface. -- -- Since: 1.2 function Get_User_Data (Surface : Cairo_Surface; Key : access Cairo_User_Data_Key) return System.Address; -- Surface: a Cairo_Surface -- Key: the address of the Cairo_User_Data_Key the user data was -- attached to -- -- Return user data previously attached to surface using the specified -- key. If no user data has been attached with the given key this -- function returns null. -- -- Return value: the user data previously attached or null. function Set_User_Data (Surface : Cairo_Surface; Key : access Cairo_User_Data_Key; User_Data : System.Address; Destroy : Cairo_Destroy_Func) return Cairo_Status; -- Surface: a Cairo_Surface -- Key: the address of a Cairo_User_Data_Key to attach the user data to -- User_Data: the user data to attach to the surface -- Destroy: a Cairo_Destroy_Func which will be called when the -- surface is destroyed or when new user data is attached using the -- same key. -- -- Attach user data to surface. To remove user data from a surface, -- call this function with the key that was used to set it and null -- for data. -- -- Return value: Cairo_Status_Success or Cairo_Status_No_Memory if a -- slot could not be allocated for the user data. procedure Get_Font_Options (Surface : Cairo_Surface; Options : access Cairo_Font_Options); -- Surface: a Cairo_Surface -- Options: a Cairo_Font_Options object into which to store -- the retrieved options. All existing values are overwritten -- -- Retrieves the default font rendering options for the surface. -- This allows display surfaces to report the correct subpixel order -- for rendering on them, print surfaces to disable hinting of -- metrics and so forth. The result can then be used with -- Cairo.Scaled_Font.Create. procedure Flush (Surface : Cairo_Surface); -- Surface: a Cairo_Surface -- -- Do any pending drawing for the surface and also restore any -- temporary modification's cairo has made to the surface's -- state. This function must be called before switching from -- drawing on the surface with cairo to drawing on it directly -- with native APIs. If the surface doesn't support direct access, -- then this function does nothing. procedure Mark_Dirty (Surface : Cairo_Surface); -- Surface: a Cairo_Surface -- -- Tells cairo that drawing has been done to surface using means other -- than cairo, and that cairo should reread any cached areas. Note -- that you must call Cairo.Surface.Flush before doing such drawing. procedure Mark_Dirty_Rectangle (Surface : Cairo_Surface; X : Gint; Y : Gint; Width : Gint; Height : Gint); -- Surface: a Cairo_Surface -- X: X coordinate of dirty rectangle -- Y: Y coordinate of dirtY rectangle -- Width: Width of dirty rectangle -- Height: Height of dirty rectangle -- -- Like Cairo.Surface.Mark_Dirty, but drawing has been done only to -- the specified rectangle, so that cairo can retain cached contents -- for other parts of the surface. -- -- Any cached clip set on the surface will be reset by this function, -- to make sure that future cairo calls have the clip set that they -- expect. procedure Set_Device_Offset (Surface : Cairo_Surface; X_Offset : Gdouble; Y_Offset : Gdouble); -- Surface: a Cairo_Surface -- X_Offset: the offset in the X direction, in device units -- Y_Offset: the offset in the Y direction, in device units -- -- Sets an offset that is added to the device coordinates determined -- by the CTM when drawing to surface. One use case for this function -- is when we want to create a Cairo_Surface that redirects drawing -- for a portion of an onscreen surface to an offscreen surface in a -- way that is completely invisible to the user of the cairo -- API. Setting a transformation via Cairo.Translate isn't -- sufficient to do this, since functions like -- Cairo.Device_To_User will expose the hidden offset. -- -- Note that the offset affects drawing to the surface as well as -- using the surface in a source pattern. procedure Get_Device_Offset (Surface : Cairo_Surface; X_Offset : access Gdouble; Y_Offset : access Gdouble); -- Surface: a Cairo_Surface -- X_Offset: the offset in the X direction, in device units -- Y_Offset: the offset in the Y direction, in device units -- -- This function returns the previous device offset set by -- Cairo.Surface.Set_Device_Offset. -- -- Since: 1.2 procedure Set_Fallback_Resolution (Surface : Cairo_Surface; X_Pixels_Per_Inch : Gdouble; Y_Pixels_Per_Inch : Gdouble); -- Surface: a Cairo_Surface -- X_Pixels_Per_Inch: horizontal setting for pixels per inch -- Y_Pixels_Per_Inch: vertical setting for pixels per inch -- -- Set the horizontal and vertical resolution for image fallbacks. -- -- When certain operations aren't supported natively by a backend, -- cairo will fallback by rendering operations to an image and then -- overlaying that image onto the output. For backends that are -- natively vector-oriented, this function can be used to set the -- resolution used for these image fallbacks, (larger values will -- result in more detailed images, but also larger file sizes). -- -- Some examples of natively vector-oriented backends are the ps, pdf, -- and svg backends. -- -- For backends that are natively raster-oriented, image fallbacks are -- still possible, but they are always performed at the native -- device resolution. So this function has no effect on those -- backends. -- -- Note: The fallback resolution only takes effect at the time of -- completing a page (with Cairo.Show_Page or Cairo.Copy_Page) so -- there is currently no way to have more than one fallback resolution -- in effect on a single page. -- -- The default fallback resoultion is 300 pixels per inch in both -- dimensions. -- -- Since: 1.2 procedure Get_Fallback_Resolution (Surface : Cairo_Surface; X_Pixels_Per_Inch : access Gdouble; Y_Pixels_Per_Inch : access Gdouble); -- Surface: a Cairo_Surface -- X_Pixels_Per_Inch: horizontal pixels per inch -- Y_Pixels_Per_Inch: vertical pixels per inch -- -- This function returns the previous fallback resolution set by -- Cairo.Surface.Set_Fallback_Resolution, or default fallback -- resolution if never set. -- -- Since: 1.8 procedure Copy_Page (Surface : Cairo_Surface); -- Surface: a Cairo_Surface -- -- Emits the current page for backends that support multiple pages, -- but doesn't clear it, so that the contents of the current page will -- be retained for the next page. Use Cairo.Surface.Show_Page if you -- want to get an empty page after the emission. -- -- There is a convenience function for this that takes a Cairo_Context, -- namely Cairo.Copy_Page. -- -- Since: 1.6 procedure Show_Page (Surface : Cairo_Surface); -- Surface: a Cairo_Surface -- -- Emits and clears the current page for backends that support multiple -- pages. Use Cairo.Surface.Copy_Page if you don't want to clear the page. -- -- There is a convenience function for this that takes a Cairo_Context, -- namely Cairo_Show_Page. -- -- Since: 1.6 function Has_Show_Text_Glyphs (Surface : Cairo_Surface) return Cairo_Bool; -- Surface: a Cairo_Surface -- -- Returns whether the surface supports -- sophisticated Cairo_Show_Text_Glyphs operations. That is, -- whether it actually uses the provided text and cluster data -- to a Cairo_Show_Text_Glyphs call. -- -- Note: Even if this function returns FALSE, a -- Cairo_Show_Text_Glyphs operation targeted at surface will -- still succeed. It just will -- act like a Cairo_Show_Glyphs operation. Users can use this -- function to avoid computing UTF-8 text and cluster mapping if the -- target surface does not use it. -- -- Return value: TRUE if surface supports -- Cairo_Show_Text_Glyphs, FALSE otherwise -- -- Since: 1.8 private pragma Import (C, Create_Similar, "cairo_surface_create_similar"); pragma Import (C, Reference, "cairo_surface_reference"); pragma Import (C, Finish, "cairo_surface_finish"); pragma Import (C, Destroy, "cairo_surface_destroy"); pragma Import (C, Get_Reference_Count, "cairo_surface_get_reference_count"); pragma Import (C, Status, "cairo_surface_status"); pragma Import (C, Get_Type, "cairo_surface_get_type"); pragma Import (C, Get_Content, "cairo_surface_get_content"); pragma Import (C, Get_User_Data, "cairo_surface_get_user_data"); pragma Import (C, Set_User_Data, "cairo_surface_set_user_data"); pragma Import (C, Get_Font_Options, "cairo_surface_get_font_options"); pragma Import (C, Flush, "cairo_surface_flush"); pragma Import (C, Mark_Dirty, "cairo_surface_mark_dirty"); pragma Import (C, Mark_Dirty_Rectangle, "cairo_surface_mark_dirty_rectangle"); pragma Import (C, Set_Device_Offset, "cairo_surface_set_device_offset"); pragma Import (C, Get_Device_Offset, "cairo_surface_get_device_offset"); pragma Import (C, Set_Fallback_Resolution, "cairo_surface_set_fallback_resolution"); pragma Import (C, Get_Fallback_Resolution, "cairo_surface_get_fallback_resolution"); pragma Import (C, Copy_Page, "cairo_surface_copy_page"); pragma Import (C, Show_Page, "cairo_surface_show_page"); pragma Import (C, Has_Show_Text_Glyphs, "cairo_surface_has_show_text_glyphs"); end Cairo.Surface;