----------------------------------------------------------------------- -- 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_Pattern is the paintbrush with which cairo draws. The primary use -- of patterns is as the source for all cairo drawing operations. -- -- A cairo pattern is created by using one of the many constructors, of the -- form Cairo_Pattern.Create_ or implicitly through -- Cairo.Set_Source_ subprograms. -- -- -- 1.8.8 -- Cairo with System; package Cairo.Pattern is -------------------------------- -- Pattern creation functions -- -------------------------------- -- Cairo_Pattern_Type is used to describe the type of a given pattern. -- -- The type of a pattern is determined by the function used to create -- it. The Cairo.Pattern.Create_Rgb and Cairo.Pattern.Create_Rgba -- functions create Solid patterns. The remaining -- Cairo.Pattern.Create_<> functions map to pattern types in obvious -- ways. -- -- The pattern type can be queried with Cairo.Pattern.Get_Type -- -- Most Cairo_Pattern functions can be called with a pattern of any type, -- (though trying to change the extend or filter for a solid pattern will -- have no effect). A notable exception is Cairo.Pattern.Add_Color_Stop_Rgb -- and Cairo.Pattern.Add_Color_Stop_Rgba which must only be called with -- gradient patterns (either Linear or Radial). Otherwise the pattern will -- be shutdown and put into an error state. -- -- New entries may be added in future versions. -- -- Since: 1.2 type Cairo_Pattern_Type is (Cairo_Pattern_Type_Solid, -- The pattern is a solid (uniform) color. It may be opaque or -- translucent. Cairo_Pattern_Type_Surface, -- The pattern is a based on a surface (an image). Cairo_Pattern_Type_Linear, -- The pattern is a linear gradient. Cairo_Pattern_Type_Radial -- The pattern is a radial gradient. ); pragma Convention (C, Cairo_Pattern_Type); -- Cairo_extend is used to describe how pattern color/alpha will be -- determined for areas "outside" the pattern's natural area, (for -- example, outside the surface bounds or outside the gradient -- geometry). -- -- The default extend mode is CAIRO_EXTEND_NONE for surface patterns -- and CAIRO_EXTEND_PAD for gradient patterns. -- -- New entries may be added in future versions. type Cairo_Extend is (Cairo_Extend_None, -- Pixels outside of the source pattern are fully transparent Cairo_Extend_Repeat, -- The pattern is tiled by repeating Cairo_Extend_Reflect, -- The pattern is tiled by reflecting at the edges (Implemented for -- surface patterns since 1.6) Cairo_Extend_Pad -- Pixels outside of the pattern copy -- the closest pixel from the source (Since 1.2; but only -- implemented for surface patterns since 1.6) ); pragma Convention (C, Cairo_Extend); -- Cairo_filter is used to indicate what filtering should be -- applied when reading pixel values from patterns. See -- Cairo.Pattern.Set_Source for indicating the desired filter to be -- used with a particular pattern. type Cairo_Filter is (Cairo_Filter_Fast, -- A high-performance filter, with quality similar to -- Cairo_Filter_Nearest Cairo_Filter_Good, -- A reasonable-performance filter, with quality similar to -- Cairo_Filter_Bilinear Cairo_Filter_Best, -- The highest-quality available, performance may -- not be suitable for interactive use. Cairo_Filter_Nearest, -- Nearest-neighbor filtering Cairo_Filter_Bilinear, -- Linear interpolation in two dimensions Cairo_Filter_Gaussian -- This filter value is currently unimplemented, and should not be used -- in current code. ); pragma Convention (C, Cairo_Filter); function Create_Rgb (Red : Gdouble; Green : Gdouble; Blue : Gdouble) return Cairo_Pattern; -- Red: Red component of the color -- Green: Green component of the color -- Blue: Blue component of the color -- -- Creates a new Cairo_Pattern corresponding to an opaque color. The -- color components are floating point numbers in the range 0 to 1. -- If the values passed in are outside that range, they will be -- clamped. -- -- Return value: the newly created Cairo_Pattern if successful, or -- an error pattern in case of no memory. The caller owns the -- returned object and should call Cairo.Pattern.Destroy when -- finished with it. -- -- This function will always return a valid pointer, but if an error -- occurred the pattern status will be set to an error. To inspect -- the status of a pattern use Cairo.Pattern.Status. function Create_Rgba (Red : Gdouble; Green : Gdouble; Blue : Gdouble; Alpha : Gdouble) return Cairo_Pattern; -- Red: Red component of the color -- Green: Green component of the color -- Blue: Blue component of the color -- Alpha: Alpha component of the color -- -- Creates a new Cairo_Pattern corresponding to a translucent color. -- The color components are floating point numbers in the range 0 to -- 1. If the values passed in are outside that range, they will be -- clamped. -- -- Return value: the newly created Cairo_Pattern if successful, or -- an error pattern in case of no memory. The caller owns the -- returned object and should call Cairo.Pattern.Destroy when -- finished with it. -- -- This function will always return a valid pointer, but if an error -- occurred the pattern status will be set to an error. To inspect -- the status of a pattern use Cairo.Pattern.Status. function Create_For_Surface (Surface : Cairo_Surface) return Cairo_Pattern; -- Surface: the Surface -- -- Create a new Cairo_Pattern for the given surface. -- -- Return value: the newly created Cairo_Pattern if successful, or -- an error pattern in case of no memory. The caller owns the -- returned object and should call Cairo.Pattern.Destroy when -- finished with it. -- -- This function will always return a valid pointer, but if an error -- occurred the pattern status will be set to an error. To inspect -- the status of a pattern use Cairo.Pattern.Status. function Create_Linear (X0 : Gdouble; Y0 : Gdouble; X1 : Gdouble; Y1 : Gdouble) return Cairo_Pattern; -- X0: x coordinate of the start point -- Y0: y coordinate of the start point -- X1: x coordinate of the end point -- Y1: y coordinate of the end point -- -- Create a new linear gradient Cairo_Pattern along the line defined -- by (X0, Y0) and (X1, Y1). Before using the gradient pattern, a -- number of color stops should be defined using -- Cairo.Pattern.Add_Color_Stop_Rgb or -- Cairo.Pattern.Add_Color_Stop_Rgba. -- -- Note: The coordinates here are in pattern space. For a new pattern, -- pattern space is identical to user space, but the relationship -- between the spaces can be changed with Cairo.Pattern.Set_Matrix. -- -- Return value: the newly created Cairo_Pattern if successful, or -- an error pattern in case of no memory. The caller owns the -- returned object and should call Cairo.Pattern.Destroy when -- finished with it. -- -- This function will always return a valid pointer, but if an error -- occurred the pattern status will be set to an error. To inspect -- the status of a pattern use Cairo.Pattern.Status. function Create_Radial (Cx0 : Gdouble; Cy0 : Gdouble; Radius0 : Gdouble; Cx1 : Gdouble; Cy1 : Gdouble; Radius1 : Gdouble) return Cairo_Pattern; -- Cx0: X coordinate for the center of the start circle -- Cy0: Y coordinate for the center of the start circle -- Radius0: radius of the start circle -- Cx1: X coordinate for the center of the end circle -- Cy1: Y coordinate for the center of the end circle -- Radius1: radius of the end circle -- -- Creates a new radial gradient Cairo_Pattern between the two circles -- defined by (Cx0, Cy0, Radius0) and (Cx1, Cy1, Radius1). Before using the -- gradient pattern, a number of color stops should be defined using -- Cairo.Pattern.Add_Color_Stop_Rgb or Cairo.Pattern.Add_Color_Stop_Rgba. -- -- Note: The coordinates here are in pattern space. For a new pattern, -- pattern space is identical to user space, but the relationship -- between the spaces can be changed with Cairo.Pattern.Set_Matrix. -- -- Return value: the newly created Cairo_Pattern if successful, or -- an error pattern in case of no memory. The caller owns the -- returned object and should call Cairo.Pattern.Destroy when -- finished with it. -- -- This function will always return a valid pointer, but if an error -- occurred the pattern status will be set to an error. To inspect -- the status of a pattern use Cairo.Pattern.Status. function Reference (Pattern : Cairo_Pattern) return Cairo_Pattern; -- Pattern: a Cairo_Pattern -- -- Increases the reference count on pattern by one. This prevents -- pattern from being destroyed until a matching call to -- Cairo.Pattern.Destroy is made. -- -- The number of references to a Cairo_Pattern can be get using -- Cairo.Pattern.Get_Reference_Count. -- -- Return value: the referenced Cairo_Pattern. procedure Destroy (Pattern : Cairo_Pattern); -- Pattern: a Cairo_Pattern -- -- Decreases the reference count on pattern by one. If the result is -- zero, then pattern and all associated resources are freed. See -- Cairo.Pattern.Reference. function Get_Reference_Count (Pattern : Cairo_Pattern) return Guint; -- Pattern: a Cairo_Pattern -- -- Returns the current reference count of pattern. -- -- Return value: the current reference count of pattern. If the -- object is a nil object, 0 will be returned. -- -- Since: 1.4 function Status (Pattern : Cairo_Pattern) return Cairo_Status; -- Pattern: a Cairo_Pattern -- -- Checks whether an error has previously occurred for this -- pattern. -- -- Return value: Cairo_Status_Success, Cairo_Status_No_Memory, or -- Cairo_Status_Pattern_Type_Mismatch. function Get_User_Data (Pattern : Cairo_Pattern; Key : access Cairo_User_Data_Key) return System.Address; -- Pattern: a Cairo_Pattern -- Key: the address of the Cairo_User_Data_Key the user data was -- attached to -- -- Return user data previously attached to pattern using the -- specified key. If no user data has been attached with the given -- key this function returns System.Null_Address. -- -- Return value: the user data previously attached or System.Null_Address. -- -- Since: 1.4 function Set_User_Data (Pattern : Cairo_Pattern; Key : access Cairo_User_Data_Key; User_Data : System.Address; Destroy : Cairo_Destroy_Func) return Cairo_Status; -- Pattern: a Cairo_Pattern -- Key: the address of a Cairo_User_Data_Key to attach the user data to -- User_Data: the user data to attach to the Cairo_Pattern -- Destroy: a Cairo_Destroy_Func which will be called when the -- Cairo_Context is destroyed or when new user data is attached using the -- same key. -- -- Attach user data to pattern. To remove user data from a surface, -- call this function with the key that was used to set it and Null_Address -- for data. -- -- Return value: Cairo_Status_Success or Cairo_Status_No_Memory if a -- slot could not be allocated for the user data. -- -- Since: 1.4 function Get_Type (Pattern : Cairo_Pattern) return Cairo_Pattern_Type; -- Pattern: a Cairo_Pattern -- -- This function returns the type a pattern. -- See Cairo_Pattern_Type for available types. -- -- Return value: The type of pattern. -- -- Since: 1.2 procedure Add_Color_Stop_Rgb (Pattern : Cairo_Pattern; Offset : Gdouble; Red : Gdouble; Green : Gdouble; Blue : Gdouble); -- Pattern: a Cairo_Pattern -- Offset: an Offset in the range [0.0 .. 1.0] -- Red: Red component of color -- Green: Green component of color -- Blue: Blue component of color -- -- Adds an opaque color stop to a gradient pattern. The offset -- specifies the location along the gradient's control vector. For -- example, a linear gradient's control vector is from (X0,Y0) to -- (X1,Y1) while a radial gradient's control vector is from any point -- on the start circle to the corresponding point on the end circle. -- -- The color is specified in the same way as in Cairo.Set_Source_Rgb. -- -- If two (or more) stops are specified with identical offset values, -- they will be sorted according to the order in which the stops are -- added, (stops added earlier will compare less than stops added -- later). This can be useful for reliably making sharp color -- transitions instead of the typical blend. -- -- -- Note: If the pattern is not a gradient pattern, (eg. a linear or -- radial pattern), then the pattern will be put into an error status -- with a status of Cairo_Status_Pattern_Type_Mismatch. procedure Add_Color_Stop_Rgba (Pattern : Cairo_Pattern; Offset : Gdouble; Red : Gdouble; Green : Gdouble; Blue : Gdouble; Alpha : Gdouble); -- Pattern: a Cairo_Pattern -- Offset: an Offset in the range [0.0 .. 1.0] -- Red: Red component of color -- Green: Green component of color -- Blue: Blue component of color -- Alpha: Alpha component of color -- -- Adds a translucent color stop to a gradient pattern. The offset -- specifies the location along the gradient's control vector. For -- example, a linear gradient's control vector is from (x0,y0) to -- (x1,y1) while a radial gradient's control vector is from any point -- on the start circle to the corresponding point on the end circle. -- -- The color is specified in the same way as in Cairo_Set_Source_Rgba. -- -- If two (or more) stops are specified with identical offset values, -- they will be sorted according to the order in which the stops are -- added, (stops added earlier will compare less than stops added -- later). This can be useful for reliably making sharp color -- transitions instead of the typical blend. -- -- Note: If the pattern is not a gradient pattern, (eg. a linear or -- radial pattern), then the pattern will be put into an error status -- with a status of Cairo_Status_Pattern_Type_Mismatch. procedure Set_Matrix (Pattern : Cairo_Pattern; Matrix : access Cairo_Matrix); -- Pattern: a Cairo_Pattern -- Matrix: a Cairo_Matrix -- -- Sets the pattern's transformation matrix to matrix. This matrix is -- a transformation from user space to pattern space. -- -- When a pattern is first created it always has the identity matrix -- for its transformation matrix, which means that pattern space is -- initially identical to user space. -- -- Important: Please note that the direction of this transformation -- matrix is from user space to pattern space. This means that if you -- imagine the flow from a pattern to user space (and on to device -- space), then coordinates in that flow will be transformed by the -- inverse of the pattern matrix. -- -- For example, if you want to make a pattern appear twice as large as -- it does by default the correct code to use is: -- -- Cairo.Matrix.Init_Scale (Matrix, 0.5, 0.5); -- Cairo.Pattern.Set_Matrix (Pattern, Matrix); -- -- Meanwhile, using values of 2.0 rather than 0.5 in the code above -- would cause the pattern to appear at half of its default size. -- -- Also, please note the discussion of the user-space locking -- semantics of Cairo_Set_Source. procedure Get_Matrix (Pattern : Cairo_Pattern; Matrix : access Cairo_Matrix); -- Pattern: a Cairo_Pattern -- Matrix: return value for the Matrix -- -- Stores the pattern's transformation matrix into matrix. procedure Set_Extend (Pattern : Cairo_Pattern; Extend : Cairo_Extend); -- Pattern: a Cairo_Pattern -- Extend: a Cairo_Extend describing how the area outside of the -- pattern will be drawn -- -- Sets the mode to be used for drawing outside the area of a pattern. -- See Cairo_Extend for details on the semantics of each extend -- strategy. -- -- The default extend mode is Cairo_Extend_None for surface patterns -- and Cairo_Extend_PAd for gradient patterns. function Get_Extend (Pattern : Cairo_Pattern) return Cairo_Extend; -- Pattern: a Cairo_Pattern -- -- Gets the current extend mode for a pattern. See Cairo_Extend -- for details on the semantics of each extend strategy. -- -- Return value: the current extend strategy used for drawing the -- pattern. procedure Set_Filter (Pattern : Cairo_Pattern; Filter : Cairo_Filter); -- Pattern: a Cairo_Pattern -- Filter: a Cairo_Filter describing the Filter to use for resizing -- the pattern -- -- Sets the filter to be used for resizing when using this pattern. -- See Cairo_Filter for details on each filter. -- -- Note that you might want to control filtering even when you do not -- have an explicit Cairo_Pattern object, (for example when using -- Cairo_Set_Source_Surface). In these cases, it is convenient to -- use Cairo_Get_Source to get access to the pattern that cairo -- creates implicitly. For example: -- -- Cairo_Set_Source_Surface (Cr, Image, X, Y); -- Cairo.Pattern.Set_Filter (Cairo_Get_Source (Cr), Cairo_Filter_Nearest); function Get_Filter (Pattern : Cairo_Pattern) return Cairo_Filter; -- Pattern: a Cairo_Pattern -- -- Gets the current filter for a pattern. See Cairo_Filter -- for details on each filter. -- -- Return value: the current filter used for resizing the pattern. function Get_Rgba (Pattern : Cairo_Pattern; Red : access Gdouble; Green : access Gdouble; Blue : access Gdouble; Alpha : access Gdouble) return Cairo_Status; -- Pattern: a Cairo_Pattern -- Red: return value for Red component of color, or null -- Green: return value for Green component of color, or null -- Blue: return value for Blue component of color, or null -- Alpha: return value for Alpha component of color, or null -- -- Gets the solid color for a solid color pattern. -- -- Return value: Cairo_Status_Success, or -- Cairo_Status_Pattern_Type_Mismatch if the pattern is not a solid -- color pattern. -- -- Since: 1.4 function Get_Surface (Pattern : Cairo_Pattern; Surface : Cairo_Surface) return Cairo_Status; -- Pattern: a Cairo_Pattern -- Surface: return value for Surface of pattern, or null -- -- Gets the surface of a surface pattern. The reference returned in -- surface is owned by the pattern; the caller should call -- Cairo.Surface.Reference if the surface is to be retained. -- -- Return value: Cairo_Status_Success, or -- Cairo_Status_Pattern_Type_Mismatch if the pattern is not a surface -- pattern. -- -- Since: 1.4 function Get_Color_Stop_Rgba (Pattern : Cairo_Pattern; Index : Gint; Offset : access Gdouble; Red : access Gdouble; Green : access Gdouble; Blue : access Gdouble; Alpha : access Gdouble) return Cairo_Status; -- Pattern: a Cairo_Pattern -- Index: Index of the stop to return data for -- Offset: return value for the Offset of the stop, or null -- Red: return value for Red component of color, or null -- Green: return value for Green component of color, or null -- Blue: return value for Blue component of color, or null -- Alpha: return value for Alpha component of color, or null -- -- Gets the color and offset information at the given index for a -- gradient pattern. Values of index are 0 to 1 less than the number -- returned by Cairo.Pattern.Get_Color_Stop_Count. -- -- Return value: Cairo_Status_Success, or Cairo_Status_Invalid_Index -- if index is not valid for the given pattern. If the pattern is -- not a gradient pattern, Cairo_Status_Pattern_Type_Mismatch is -- returned. -- -- Since: 1.4 function Get_Color_Stop_Count (Pattern : Cairo_Pattern; Count : access Gint) return Cairo_Status; -- Pattern: a Cairo_Pattern -- Count: return value for the number of color stops, or NULL -- -- Gets the number of color stops specified in the given gradient -- pattern. -- -- Return value: Cairo_Status_Success, or -- Cairo_Status_Pattern_Type_Mismatch if pattern is not a gradient -- pattern. -- -- Since: 1.4 function Get_Linear_Points (Pattern : Cairo_Pattern; X0 : access Gdouble; Y0 : access Gdouble; X1 : access Gdouble; Y1 : access Gdouble) return Cairo_Status; -- Pattern: a Cairo_Pattern -- X0: return value for the x coordinate of the first point, or null -- Y0: return value for the y coordinate of the first point, or null -- X1: return value for the x coordinate of the second point, or null -- Y1: return value for the y coordinate of the second point, or null -- -- Gets the gradient endpoints for a linear gradient. -- -- Return value: Cairo_Status_Success, or -- Cairo_Status_Pattern_Type_Mismatch if pattern is not a linear -- gradient pattern. -- -- Since: 1.4 function Get_Radial_Circles (Pattern : Cairo_Pattern; X0 : access Gdouble; Y0 : access Gdouble; R0 : access Gdouble; X1 : access Gdouble; Y1 : access Gdouble; R1 : access Gdouble) return Cairo_Status; -- Pattern: a Cairo_Pattern -- X0: return value for the x coordinate of the center of the first -- circle, or null -- Y0: return value for the y coordinate of the center of the first -- circle, or null -- R0: return value for the radius of the first circle, or null -- X1: return value for the x coordinate of the center of the second -- circle, or null -- Y1: return value for the y coordinate of the center of the second -- circle, or null -- R1: return value for the radius of the second circle, or null -- -- Gets the gradient endpoint circles for a radial gradient, each -- specified as a center coordinate and a radius. -- -- Return value: Cairo_Status_Success, or -- Cairo_Status_Pattern_Type_Mismatch if pattern is not a radial -- gradient pattern. -- -- Since: 1.4 private pragma Import (C, Create_Rgb, "cairo_pattern_create_rgb"); pragma Import (C, Create_Rgba, "cairo_pattern_create_rgba"); pragma Import (C, Create_For_Surface, "cairo_pattern_create_for_surface"); pragma Import (C, Create_Linear, "cairo_pattern_create_linear"); pragma Import (C, Create_Radial, "cairo_pattern_create_radial"); pragma Import (C, Reference, "cairo_pattern_reference"); pragma Import (C, Destroy, "cairo_pattern_destroy"); pragma Import (C, Get_Reference_Count, "cairo_pattern_get_reference_count"); pragma Import (C, Status, "cairo_pattern_status"); pragma Import (C, Get_User_Data, "cairo_pattern_get_user_data"); pragma Import (C, Set_User_Data, "cairo_pattern_set_user_data"); pragma Import (C, Get_Type, "cairo_pattern_get_type"); pragma Import (C, Add_Color_Stop_Rgb, "cairo_pattern_add_color_stop_rgb"); pragma Import (C, Add_Color_Stop_Rgba, "cairo_pattern_add_color_stop_rgba"); pragma Import (C, Set_Matrix, "cairo_pattern_set_matrix"); pragma Import (C, Get_Matrix, "cairo_pattern_get_matrix"); pragma Import (C, Set_Extend, "cairo_pattern_set_extend"); pragma Import (C, Get_Extend, "cairo_pattern_get_extend"); pragma Import (C, Set_Filter, "cairo_pattern_set_filter"); pragma Import (C, Get_Filter, "cairo_pattern_get_filter"); pragma Import (C, Get_Rgba, "cairo_pattern_get_rgba"); pragma Import (C, Get_Surface, "cairo_pattern_get_surface"); pragma Import (C, Get_Color_Stop_Rgba, "cairo_pattern_get_color_stop_rgba"); pragma Import (C, Get_Color_Stop_Count, "cairo_pattern_get_color_stop_count"); pragma Import (C, Get_Linear_Points, "cairo_pattern_get_linear_points"); pragma Import (C, Get_Radial_Circles, "cairo_pattern_get_radial_circles"); end Cairo.Pattern;