Index

Package: Pattern

Description

package Cairo.Pattern is

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_<type> or implicitly through Cairo.Set_Source_<type> subprograms.

Binding from C File version 1.8.8

Types

Cairo_Pattern_Type 

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.
     );
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

Cairo_Extend 

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)
     );
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.

Cairo_Filter 

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.
     );
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.

Subprograms & Entries

Create_Rgb 

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.

Create_Rgba 

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.

Create_For_Surface 

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.

Create_Linear 

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.

Create_Radial 

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.

Reference 

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.

Destroy 

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.

Get_Reference_Count 

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

Status 

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.

Get_User_Data 

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

Set_User_Data 

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

Get_Type 

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

Add_Color_Stop_Rgb 

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.

Add_Color_Stop_Rgba 

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.

Set_Matrix 

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.

Get_Matrix 

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.

Set_Extend 

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.

Get_Extend 

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.

Set_Filter 

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);

Get_Filter 

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.

Get_Rgba 

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

Get_Surface 

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

Get_Color_Stop_Rgba 

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

Get_Color_Stop_Count 

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

Get_Linear_Points 

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

Get_Radial_Circles 

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