Bindings to the Cairo 2D graphics library. The Cairo_Context is the main object used when drawing with cairo. To draw with Cairo, you create a Context, set the target surface, and drawing options for the Cairo_Context, create shapes with functions like Move_To and Line_To, and then draw shapes with Stroke or Fill.
All drawing in Cairo is done on a Cairo_Context.
Drawing on on-screen Gtk widgets should be done in a callback to the "expose" event:
When the widget has been created, connect a drawing function:
declare
Area : Gtk_Drawing_Area;
package Event_Cb is new Gtk.Handlers.Return_Callback
(Gtk_Drawing_Area_Record, Boolean);
begin
Gtk_New (Area);
Event_Cb.Connect (Area, "expose_event",
Event_Cb.To_Marshaller (Expose_Cb'Access));
end;
In the callback, first get the context of the drawable on which you need to draw, using Gdk.Cairo.Create. Then do the drawing operations, and release the memory allocated to Cr using Cairo.Destroy.
In addition to drawing on on-screen widgets, drawing can also be done using the same Cairo calls to pixbufs (see Gdk.Cairo) to memory (see Cairo.Image_Surface), and to PNG or PDF files (see Cairo.Png and Cairo.Pdf).
Code samples demonstrating how to use various functionalities of Cairo can be found in the testcairo example, shipped with GtkAda.
<c_version>1.8.8</c_version> <group>Cairo</group>
procedure Append_Path
(Cr : Cairo_Context;
Path : access Cairo_Path)
Append the path onto the current path. The path may be either the return value from one of Copy_Path or Copy_Path_Flat or it may be constructed manually. See Cairo_Path for details on how the path data structure should be initialized, and note that Path.Status must be initialized to Cairo_Status_Success.
a cairo context
Path to be appended
procedure Arc
(Cr : Cairo_Context;
Xc : Gdouble;
Yc : Gdouble;
Radius : Gdouble;
Angle1 : Gdouble;
Angle2 : Gdouble)
Adds a circular arc of the given radius to the current path. The arc is centered at (Xc, Yc), begins at Angle1 and proceeds in the direction of increasing angles to end at Angle2. If Angle2 is less than Angle1 it will be progressively increased by 2*M_PI until it is greater than Angle1.
If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. If this initial line is undesired, it can be avoided by calling New_Sub_Path before calling Arc.
Angles are measured in radians. An angle of 0.0 is in the direction of the positive X axis (in user space). An angle of M_PI/2.0 radians (90 degrees) is in the direction of the positive Y axis (in user space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction.
(To convert from degrees to radians, use degrees * (Pi / 180.0))
This function gives the arc in the direction of increasing angles; see Cairo_Arc_Negative to get the arc in the direction of decreasing angles.
The arc is circular in user space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by X, Y, Width, Height:
Cairo_Save (Cr); Cairo_Translate (Cr, X + Width / 2.0, Y + Height / 2.0); Cairo_Scale (Cr, Width / 2.0, Height / 2.0); Cairo_Arc (Cr, 0.0, 0.0, 1.0, 0.0, 2 * Pi); Cairo_Restore (Cr);
a cairo context
X position of the center of the arc
Y position of the center of the arc
the Radius of the arc
the start angle, in radians
the end angle, in radians
procedure Arc_Negative
(Cr : Cairo_Context;
Xc : Gdouble;
Yc : Gdouble;
Radius : Gdouble;
Angle1 : Gdouble;
Angle2 : Gdouble)
Adds a circular arc of the given radius to the current path. The arc is centered at (Xc, Yc), begins at Angle1 and proceeds in the direction of decreasing angles to end at Angle2. If Angle2 is greater than Angle1 it will be progressively decreased by 2*Pi until it is less than Angle1.
See Arc for more details. This function differs only in the direction of the arc between the two angles.
a cairo context
X position of the center of the arc
Y position of the center of the arc
the Radius of the arc
the start angle, in radians
the end angle, in radians
type Cairo_Antialias is
(
Cairo_Antialias_Default,
Cairo_Antialias_None,
Cairo_Antialias_Gray,
Cairo_Antialias_Subpixel
);
Use the default antialiasing for the subsystem and target device
Use a bilevel alpha mask
Perform single-color antialiasing (using shades of gray for black text on a white background, for example).
subtype Cairo_Content is Guint;
Cairo_content is used to describe the content that a surface will contain, whether color information, alpha information (translucence vs. opacity), or both.
Note: The large values here are designed to keep Cairo_Content values distinct from Cairo_Format values so that the implementation can detect the error if users confuse the two types.
Cairo_Content_Alpha : constant Cairo_Content := 8192;
CAIRO_CONTENT_ALPHA: The surface will hold alpha content only.
Cairo_Content_Color : constant Cairo_Content := 4096;
The surface will hold color content only.
Cairo_Content_Color_Alpha : constant Cairo_Content := 12288;
CAIRO_CONTENT_COLOR_ALPHA: The surface will hold color and alpha content.
type Cairo_Context is private;
A Cairo_Context contains the current state of the rendering device, including coordinates of yet to be drawn shapes.
Cairo contexts, as Cairo_Context objects are named, are central to cairo and all drawing with cairo is always done to a Cairo_Context object.
Memory management of Cairo_Context is done with subprograms Reference and Destroy, see below.
type Cairo_Destroy_Func is access procedure (Arg1 : System.Address);
Data: The Data element being destroyed.
Cairo_destroy_func the type of function which is called when a data element is destroyed. It is passed the pointer to the data element and should free any memory and resources allocated for it.
type Cairo_Fill_Rule is
(Cairo_Fill_Rule_Winding,
Cairo_Fill_Rule_Even_Odd
);
If the path crosses the ray from left-to-right, counts +1. If the path crosses the ray from right to left, counts -1. (Left and right are determined from the perspective of looking along the ray from the starting point). If the total count is non-zero, the point will be filled.
type Cairo_Font_Extents is record
Ascent : aliased Gdouble;
Descent : aliased Gdouble;
Height : aliased Gdouble;
Max_X_Advance : aliased Gdouble;
Max_Y_Advance : aliased Gdouble;
end record;
The Cairo_font_extents structure stores metric information for a font. Values are given in the current user-space coordinate system.
Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.
The distance that the font extends above the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it.
The distance that the font extends below the baseline. This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the the font should align with elements below it.
The recommended vertical distance between baselines when setting consecutive lines of text with the font. This is greater than ascent+descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent+descent between lines.
The maximum distance in the X direction that the the origin is advanced for any glyph in the font.
The maximum distance in the Y direction that the the origin is advanced for any glyph in the font. this will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)
type Cairo_Font_Face is private;
A Cairo_Font_Face specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions) . A font face can be set on a Cairo_Context by using Set_Font_Face; the size and font matrix are set with Set_Font_Size and Set_Font_Matrix.
There are various types of font faces, depending on the font backend they use. The type of a font face can be queried using Cairo.Font_Face.Get_Type.
Memory management of Cairo_Font_Face is done with Cairo.Font_Face.Reference and Cairo.Font_Face.Destroy.
The Cairo_glyph structure holds information about a single glyph when drawing or measuring text. A font is (in simple terms) a collection of shapes used to draw text. A glyph is one of these shapes. There can be multiple glyphs for a single character (alternates to be used in different contexts, for example), or a glyph can be a ligature of multiple characters. Cairo doesn't expose any way of converting input text into glyphs, so in order to use the Cairo interfaces that take arrays of glyphs, you must directly access the appropriate underlying font system.
Note that the offsets given by X and Y are not cumulative. When drawing or measuring text, each glyph is individually positioned with respect to the overall origin
type Cairo_Font_Options is private;
An opaque structure holding all options that are used when rendering fonts.
Individual features of a Cairo_Font_Options can be set or accessed using functions named Cairo.Font_Options.Set_<feature_Name> and Cairo.Font_Options.Get_<feature_Name>, like Cairo.Font_Options.Set_Antialias and Cairo.Font_Options.Get_Antialias.
New features may be added to a Cairo_font_options in the future. For this reason, Cairo.Font_Options.Copy, Cairo.Font_Options.Equal, Cairo.Font_Options.Merge, and Cairo.Font_Options.Hash should be used to copy, check for equality, merge, or compute a hash value of Cairo_Font_Options objects.
type Cairo_Font_Slant is (
Cairo_Font_Slant_Normal,
Cairo_Font_Slant_Italic,
Cairo_Font_Slant_Oblique);
Specifies variants of a font face based on their slant.
type Cairo_Font_Type is
(Cairo_Font_Type_Toy,
Cairo_Font_Type_Ft,
Cairo_Font_Type_Win32,
Cairo_Font_Type_Quartz,
Cairo_Font_Type_User
);
Cairo_font_type is used to describe the type of a given font face or scaled font. The font types are also known as "font backends" within Cairo.
The type of a font face is determined by the function used to create it, which will generally be of the form <type>_Font_Face_Create. The font face type can be queried with Cairo.Font_Face.Get_Type
The various Cairo_Font_Face functions can be used with a font face of any type.
The type of a scaled font is determined by the type of the font face passed to Cairo.Scaled_Font.Create. The scaled font type can be queried with Cairo.Scaled_Font.Get_Type
The various Cairo_scaled_font functions can be used with scaled fonts of any type, but some font backends also provide type-specific functions that must only be called with a scaled font of the appropriate type. These functions have names that begin with <type>_Scaled_Font such as Ft_Scaled_Font_Lock_Face.
The behavior of calling a type-specific function with a scaled font of the wrong type is undefined.
New entries may be added in future versions.
Since: 1.2
The font was created using cairo's toy font api (Since: 1.8)
The font is of type FreeType
The font is of type Win32
The font is of type Quartz (Since: 1.6)
type Cairo_Font_Weight is (
Cairo_Font_Weight_Normal,
Cairo_Font_Weight_Bold);
Specifies variants of a font face based on their weight.
type Cairo_Format is (
Format_Invalid,
Format_ARGB32,
Format_RGB24,
Format_A8,
Format_A1,
Format_RGB16_565,
Format_RGB30);
Used to identify the memory format of image data
Format_ARGB32: each pixel is a 32-bit quantity, with alpha in the upper 8 bits, then red, then green, then blue. The 32-bit quantities are stored native-endian. Pre-multiplied alpha is used. (That is, 50% transparent red is 0x80800000, not 0x80ff0000.) (Since 1.0) Format_RGB_24: each pixel is a 32-bit quantity, with the upper 8 bits unused. Red, Green, and Blue are stored in the remaining 24 bits in that order. (Since 1.0) Format_A8: each pixel is a 8-bit quantity holding an alpha value. (Since 1.0) Format_A1: each pixel is a 1-bit quantity holding an alpha value. Pixels are packed together into 32-bit quantities. The ordering of the bits matches the endianess of the platform. On a big-endian machine, the first pixel is in the uppermost bit, on a little-endian machine the first pixel is in the least-significant bit. (Since 1.0) Format_RGB16_565: each pixel is a 16-bit quantity with red in the upper 5 bits, then green in the middle 6 bits, and blue in the lower 5 bits. (Since 1.2) Format_RGB30: like RGB24 but with 10bpc. (Since 1.12)
type Cairo_Glyph is record
Index : aliased Gulong;
X : aliased Gdouble;
Y : aliased Gdouble;
end record;
Glyph Index in the font. The exact interpretation of the glyph index depends on the font technology being used.
The offset in the X direction between the origin used for drawing or measuring the string and the origin of this glyph.
The offset in the Y direction between the origin used for drawing or measuring the string and the origin of this glyph.
type Cairo_Hint_Metrics is
(Cairo_Hint_Metrics_Default,
Cairo_Hint_Metrics_Off,
Cairo_Hint_Metrics_On
);
Specifies whether to hint font metrics; hinting font metrics means quantizing them so that they are integer values in device space. Doing this improves the consistency of letter and line spacing, however it also means that text will be laid out differently at different zoom factors.
Hint metrics in the default manner for the font backend and target device
Do not hint font metrics
type Cairo_Hint_Style is
(Cairo_Hint_Style_Default,
Cairo_Hint_Style_None,
Cairo_Hint_Style_Slight,
Cairo_Hint_Style_Medium,
Cairo_Hint_Style_Full
);
Specifies the type of hinting to do on font outlines. Hinting is the process of fitting outlines to the pixel grid in order to improve the appearance of the result. Since hinting outlines involves distorting them, it also reduces the faithfulness to the original outline shapes. Not all of the outline hinting styles are supported by all font backends.
New entries may be added in future versions.
Use the default hint style for font backend and target device
Do not hint outlines
Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
type Cairo_Line_Cap is
(Cairo_Line_Cap_Butt,
Cairo_Line_Cap_Round,
Cairo_Line_Cap_Square
);
Specifies how to render the endpoints of the path when stroking.
The default line cap style is Cairo_Line_Cap_Butt.
start(stop) the line exactly at the start(end) point
use a round ending, the center of the circle is the end point
type Cairo_Line_Join is
(Cairo_Line_Join_Miter,
Cairo_Line_Join_Round,
Cairo_Line_Join_Bevel
);
Specifies how to render the junction of two lines when stroking.
The default line join style is Cairo_Line_Join_Miter.
use a sharp (angled) corner, see Set_Miter_Limit
use a rounded join, the center of the circle is the joint point
type Cairo_Matrix is record
Xx : aliased Gdouble;
Yx : aliased Gdouble;
Xy : aliased Gdouble;
Yy : aliased Gdouble;
X0 : aliased Gdouble;
Y0 : aliased Gdouble;
end record;
Xx: Xx component of the affine transformation Yx: Yx component of the affine transformation Xy: Xy component of the affine transformation Yy: Yy component of the affine transformation X0: X translation component of the affine transformation Y0: Y translation component of the affine transformation
A Cairo_Matrix holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (X, Y) is given by:
X_New = Xx * X + Xy * Y + X0;
Y_New = Yx * X + Yy * Y + Y0;
type Cairo_Matrix_Access is access Cairo_Matrix;
type Cairo_Operator is
(Cairo_Operator_Clear,
Cairo_Operator_Source,
Cairo_Operator_Over,
Cairo_Operator_In,
Cairo_Operator_Out,
Cairo_Operator_Atop,
Cairo_Operator_Dest,
Cairo_Operator_Dest_Over,
,
,
,
,
…,
Cairo_Operator_Saturate
);
clear destination layer (bounded)
replace destination layer (bounded)
draw source layer on top of destination layer (bounded)
draw source where there was destination content (unbounded)
draw source where there was no destination content (unbounded)
draw source on top of destination content and only there
ignore the source
draw destination on top of source
leave destination only where there was source content (unbounded)
leave destination only where there was no source content
leave destination on top of source content and only there (unbounded)
source and destination are shown where there is only one of them
source and destination layers are accumulated
type Cairo_Path is record
Status : aliased Cairo_Status;
Data : Path_Data_Array_Access;
Num_Data : aliased Gint;
end record;
Status: the current error Status Data: the elements in the path Num_Data: the number of elements in the data array
A data structure for holding a path. This data structure serves as the return value for Copy_Path and Copy_Path_Flat as well the input value for Append_Path.
See Cairo_Path_Data for hints on how to iterate over the actual data within the path.
The num_data member gives the number of elements in the data array. This number is larger than the number of independent path portions (defined in Cairo_Path_Data_Type), since the data includes both headers and coordinates for each portion.
Warning: for efficiency reasons, Data is a direct mapping to the C structure. Therefore, there is no bounds checking on this array, the user needs to make sure only to access data between indexes 0 and Num_Data-1.
type Cairo_Path_Access is access all Cairo_Path;
Status: the current error Status Data: the elements in the path Num_Data: the number of elements in the data array
A data structure for holding a path. This data structure serves as the return value for Copy_Path and Copy_Path_Flat as well the input value for Append_Path.
See Cairo_Path_Data for hints on how to iterate over the actual data within the path.
The num_data member gives the number of elements in the data array. This number is larger than the number of independent path portions (defined in Cairo_Path_Data_Type), since the data includes both headers and coordinates for each portion.
type Cairo_Path_Data (Discr : Guint := 0) is record
case Discr is
when 0 =>
Header : aliased Header_Type;
when others =>
Point : aliased Point_Type;
end case;
end record;
Cairo_path_data is used to represent the path data inside a Cairo_path.
The data structure is designed to try to balance the demands of efficiency and ease-of-use. A path is represented as an array of Cairo_Path_Data, which is a union of headers and points.
Each portion of the path is represented by one or more elements in the array, (one header followed by 0 or more points). The length value of the header is the number of array elements for the current portion including the header, (ie. length == 1 + of points), and where the number of points for each element type is as follows:
Cairo_Path_Move_To: 1 point
Cairo_Path_Line_To: 1 point
Cairo_Path_Curve_To: 3 points
Cairo_Path_Close_Path: 0 points
The semantics and ordering of the coordinate values are consistent with Move_To, Line_To, Curve_To, and Close_Path.
Here is sample code for iterating through a Cairo_Path:
declare J : Gint; Path : Cairo_Path; Data : Cairo_Path_Data; begin Path = Copy_Path (Cr);
J := 0;
while J < Path.Num_Data loop
Data := Path.Data(J);
case Data.Header.Path_Type is
when Cairo_Path_Move_To =>
Do_Move_To_Things (Data(1).Point.X, Data(1).Point.Y);
when Cairo_Path_Line_To =>
Do_Line_To_Things (Data(1).Point.X, Data(1).Point.Y);
when Cairo_Path_Curve_To =>
Do_Curve_To_Things (Data(1).Point.X, Data(1).Point.Y,
Data(2).Point.X, Data(2).Point.Y,
Data(3).Point.X, Data(3).Point.Y);
when Cairo_Path_Curve_To =>
Do_Close_Path_Things;
end case;
J := J + Path.Data[J].Header.Length;
end loop;
Path_Destroy (Path);
end;
As of cairo 1.4, cairo does not mind if there are more elements in a portion of the path than needed. Such elements can be used by users of the cairo API to hold extra values in the path data structure. For this reason, it is recommended that applications always use Data.Header.Length to iterate over the path data, instead of hardcoding the number of elements for each element type.
type Cairo_Path_Data_Type is
(Cairo_Path_Move_To,
Cairo_Path_Line_To,
Cairo_Path_Curve_To,
Cairo_Path_Close_Path
);
Cairo_path_data is used to describe the type of one portion of a path when represented as a Cairo_Path. See Cairo_Path_Data for details.
A move-to operation
A line-to operation
A curve-to operation
A close-path operation
type Cairo_Pattern is private;
A Cairo_Pattern represents a source when drawing onto a surface. There are different subtypes of Cairo_Pattern, for different types of sources; for example, Cairo.Pattern.Create_Rgb creates a pattern for a solid opaque color.
Other than various Cairo.Pattern.Create_<type> functions, some of the pattern types can be implicitly created using various Set_Source_<type> functions; for example Set_Source_Rgb.
The type of a pattern can be queried with Cairo.Pattern.Get_Type.
Memory management of Cairo_Pattern is done with Cairo.Pattern.Reference and Cairo.Pattern.Destroy.
type Cairo_Rectangle is record
X : aliased Gdouble;
Y : aliased Gdouble;
Width : aliased Gdouble;
Height : aliased Gdouble;
end record;
X: X coordinate of the left side of the rectangle Y: Y coordinate of the the top side of the rectangle Width: Width of the rectangle Height: Height of the rectangle
A data structure for holding a rectangle.
Since: 1.4
type Cairo_Rectangle_Array is array (Natural) of Cairo_Rectangle;
type Cairo_Rectangle_Array_Access is access all Cairo_Rectangle_Array;
type Cairo_Rectangle_List is record
Status : aliased Cairo_Status;
Rectangles : Cairo_Rectangle_Array_Access;
Num_Rectangles : aliased Gint;
end record;
Status: Error Status of the rectangle list Rectangles: Array containing the Rectangles Num_Rectangles: Number of rectangles in this list
A data structure for holding a Dynamically allocated array of rectangles.
Since: 1.4
Warning: for efficiency reasons, Rectangles is a direct mapping to the C structure. Therefore, there is no bounds checking on this array, user needs to make sure only to access data between indexes 0 and Num_Rectanges-1.
type Cairo_Rectangle_List_Access is access all Cairo_Rectangle_List;
type Cairo_Scaled_Font is private;
A Cairo_Scaled_Font is a font scaled to a particular size and device resolution. A Cairo_Scaled_Font is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.
There are various types of scaled fonts, depending on the font backend they use. The type of a scaled font can be queried using Cairo.Scaled_Font.Get_Type.
Memory management of Cairo_Scaled_Font is done with Cairo.Scaled_Font.Reference and Cairo.Scaled_Font.Destroy.
type Cairo_Status is
(
Cairo_Status_Success,
Cairo_Status_No_Memory,
Cairo_Status_Invalid_Restore,
Cairo_Status_Invalid_Pop_Group,
Cairo_Status_No_Current_Point,
Cairo_Status_Invalid_Matrix,
Cairo_Status_Invalid_Status,
Cairo_Status_Null_Pointer,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
,
…,
Cairo_Status_Invalid_Weight
);
no error has occurred
out of memory
Cairo_Restore called without matching Cairo_Save
no saved group to pop
no current point defined
invalid matrix (not invertible)
invalid value for an input Cairo_status
NULL pointer
input string not valid UTF-8
input path data not valid
error while reading from input stream
error while writing to output stream
target surface has been finished
the surface type is not appropriate for the operation
the pattern type is not appropriate for the operation
invalid value for an input Cairo_content
invalid value for an input Cairo_format
invalid value for an input Visual*
file not found
invalid value for a dash setting
invalid value for a DSC comment (Since 1.2)
invalid index passed to getter (Since 1.4)
clip region not representable in desired format (Since 1.4)
error creating or writing to a temporary file (Since 1.6)
invalid value for stride (Since 1.6)
the font type is not appropriate for the operation (Since 1.8)
the user-font is immutable (Since 1.8)
error occurred in a user-font callback function (Since 1.8)
negative number used where it is not allowed (Since 1.8)
input clusters do not represent the accompanying text and glyph array (Since 1.8)
invalid value for an input Cairo_Font_Slant (Since 1.8)
type Cairo_Subpixel_Order is
(Cairo_Subpixel_Order_Default,
Cairo_Subpixel_Order_Rgb,
Cairo_Subpixel_Order_Bgr,
Cairo_Subpixel_Order_Vrgb,
Cairo_Subpixel_Order_Vbgr
);
The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of CAIRO_ANTIALIAS_SUBPIXEL.
Use the default subpixel order for the target device
Subpixel elements are arranged horizontally with red at the left
Subpixel elements are arranged horizontally with blue at the left
Subpixel elements are arranged vertically with red at the top
type Cairo_Surface is private;
A Cairo_Surface represents an image, either as the destination of a drawing operation or as source when drawing onto another surface. To draw to a Cairo_Surface, create a cairo context with the surface as the target, using Create.
There are different subtypes of Cairo_Surface for different drawing backends; for example, Cairo.Image_Surface.Create creates a bitmap image in memory. The type of a surface can be queried with Cairo.Surface.Get_Type.
Memory management of Cairo_Surface is done with Cairo.Surface.Reference and Cairo.Surface.Destroy.
type Cairo_Text_Cluster is record
Num_Bytes : aliased Gint;
Num_Glyphs : aliased Gint;
end record;
The Cairo_text_cluster structure holds information about a single text cluster. A text cluster is a minimal mapping of some glyphs corresponding to some UTF-8 text.
For a cluster to be valid, both num_bytes and num_glyphs should be non-negative, and at least one should be non-zero. Note that clusters with zero glyphs are not as well supported as normal clusters. For example, PDF rendering applications typically ignore those clusters when PDF text is being selected.
See Show_Text_Glyphs for how clusters are used in advanced text operations.
Since: 1.8
The number of bytes of UTF-8 text covered by cluster
The number of glyphs covered by cluster
Cairo_Text_Cluster_Flag_Backward : constant Cairo_Text_Cluster_Flags := 1;
The clusters in the cluster array map to glyphs in the glyph array from end to start.
subtype Cairo_Text_Cluster_Flags is Guint;
Specifies properties of a text cluster mapping.
Since: 1.8
type Cairo_Text_Extents is record
X_Bearing : aliased Gdouble;
Y_Bearing : aliased Gdouble;
Width : aliased Gdouble;
Height : aliased Gdouble;
X_Advance : aliased Gdouble;
Y_Advance : aliased Gdouble;
end record;
The Cairo_text_extents structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale (Cr, 2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.
The horizontal distance from the origin to the leftmost part of the glyphs as drawn. Positive if the glyphs lie entirely to the right of the origin.
The vertical distance from the origin to the topmost part of the glyphs as drawn. Positive only if the glyphs lie completely below the origin; will usually be negative.
Width of the glyphs as drawn
Height of the glyphs as drawn
Distance to advance in the X direction after drawing these glyphs
Distance to advance in the Y direction after drawing these glyphs. Will typically be zero except for vertical text layout as found in East-Asian languages.
type Cairo_User_Data_Key is record
Unused : aliased Gint;
end record;
Unused: not used; ignore.
Cairo_User_Data_Key is used for attaching user data to cairo data structures. The actual contents of the struct is never used, and there is no need to initialize the object; only the unique address of a Cairo_User_Data_Key object is used. Typically, you would just use the address of a static Cairo_User_Data_Key object.
procedure Clip (Cr : Cairo_Context)
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see Set_Fill_Rule).
After Clip, the current path will be cleared from the cairo context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling Clip can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Clip within a Save/Restore pair. The only other means of increasing the size of the clip region is Reset_Clip.
a cairo context
procedure Clip_Extents
(Cr : Cairo_Context;
X1 : out Gdouble;
Y1 : out Gdouble;
X2 : out Gdouble;
Y2 : out Gdouble)
Computes a bounding box in user coordinates covering the area inside the current clip.
@since 1.4
a cairo context
left of the resulting extents
top of the resulting extents
right of the resulting extents
bottom of the resulting extents
procedure Clip_Preserve (Cr : Cairo_Context)
Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see Set_Fill_Rule).
Unlike Clip, Clip_Preserve preserves the path within the cairo context.
The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region.
Calling Clip_Preserve can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Clip_Preserve within a Save/Restore pair. The only other means of increasing the size of the clip region is Reset_Clip.
a cairo context
procedure Close_Path (Cr : Cairo_Context)
Adds a line segment to the path from the current point to the beginning of the current sub-path, (the most recent point passed to Move_To), and closes this sub-path. After this call the current point will be at the joined endpoint of the sub-path.
The behavior of Close_Path is distinct from simply calling Line_To with the equivalent coordinate in the case of stroking. When a closed sub-path is stroked, there are no caps on the ends of the sub-path. Instead, there is a line join connecting the final and initial segments of the sub-path.
If there is no current point before the call to Close_Path, this function will have no effect.
Note: As of cairo version 1.2.4 any call to Close_Path will place an explicit MOVE_TO element into the path immediately after the CLOSE_PATH element, (which can be seen in Copy_Path for example). This can simplify path processing in some cases as it may not be necessary to save the "last move_to point" during processing as the MOVE_TO immediately after the CLOSE_PATH will provide that point.
a cairo context
subtype Color_Range is Gdouble range 0.0 .. 1.0;
function Copy_Clip_Rectangle_List
(Cr : Cairo_Context)
return Cairo_Rectangle_List_Access
Gets the current clip region as a list of rectangles in user coordinates. Never returns NULL.
The status in the list may be Cairo_Status_Clip_Not_Representable to indicate that the clip region cannot be represented as a list of user-space rectangles. The status may have other values to indicate other errors.
@since 1.4
a cairo context
the current clip region as a list of rectangles in user coordinates, which should be destroyed using Rectangle_List_Destroy.
procedure Copy_Page (Cr : Cairo_Context)
Emits the current page for backends that support multiple pages, but doesn't clear it, so, the contents of the current page will be retained for the next page too. Use Show_Page if you want to get an empty page after the emission.
This is a convenience function that simply calls Cairo.Surface.Copy_Page on Cr's target.
a cairo context
function Copy_Path (Cr : Cairo_Context) return Cairo_Path_Access
Creates a copy of the current path and returns it to the user as a Cairo_Path. See Cairo_Path_Data for hints on how to iterate over the returned data structure.
This function will always return a valid pointer, but the result will have no data (Data = null and Num_Data = 0), if either of the following conditions hold:
-> If there is insufficient memory to copy the path. In this case Path.Status will be set to Cairo_Status_No_Memory
-> If Cr is already in an error state. In this case Path.Status will contain the same status that would be returned by Status.
a cairo context
the copy of the current path. The caller owns the returned object and should call Path_Destroy when finished with it.
function Copy_Path_Flat (Cr : Cairo_Context) return Cairo_Path_Access
Gets a flattened copy of the current path and returns it to the user as a Cairo_Path. See Cairo_Path_Data for hints on how to iterate over the returned data structure.
This function is like Copy_Path except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type Cairo_Path_Curve_To which will instead be replaced by a series of Cairo_Path_Line_To elements.
This function will always return a valid pointer, but the result will have no data (Data = null and Num_Data = 0), if either of the following conditions hold:
-> If there is insufficient memory to copy the path. In this case Path.Status will be set to Cairo_Status_No_Memory
-> If Cr is already in an error state. In this case Path.Status will contain the same status that would be returned by Status.
a cairo context
the copy of the current path. The caller owns the returned object and should call Path_Destroy when finished with it.
function Create (Target : Cairo_Surface) return Cairo_Context
Creates a new Cairo_Context with all graphics state parameters set to default values and with target as a target surface. The target surface should be constructed with a backend-specific function such as Cairo.Image_Surface.Create.
This function references target, so you can immediately call Cairo.Surface.Destroy on it if you don't need to maintain a separate reference to it.
Target surface for the context
a newly allocated Cairo_Context with a reference count of 1. The initial reference count should be released with Destroy when you are done using the Cairo_Context. This function never returns NULL. If memory cannot be allocated, a special Cairo_Context object will be returned on which Status returns Cairo_Status_No_Memory. You can use this object normally, but no drawing will be done.
procedure Curve_To
(Cr : Cairo_Context;
X1 : Gdouble;
Y1 : Gdouble;
X2 : Gdouble;
Y2 : Gdouble;
X3 : Gdouble;
Y3 : Gdouble)
Adds a cubic Bézier spline to the path from the current point to position (X3, Y3) in user-space coordinates, using (X1, Y1) and (X2, Y2) as the control points. After this call the current point will be (X3, Y3).
If there is no current point before the call to Curve_To this function will behave as if preceded by a call to Move_To (Cr, X1, Y1).
a cairo context
the X coordinate of the first control point
the Y coordinate of the first control point
the X coordinate of the second control point
the Y coordinate of the second control point
the X coordinate of the end of the curve
the Y coordinate of the end of the curve
type Dash_Array is array (Natural range <>) of Gdouble;
type Dash_Array_Access is access all Dash_Array;
procedure Destroy (Cr : Cairo_Context)
Cr: a Cairo_Context
Decreases the reference count on cr by one. If the result is zero, then cr and all associated resources are freed. See Reference.
procedure Device_To_User
(Cr : Cairo_Context;
X : access Gdouble;
Y : access Gdouble)
Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix (CTM).
a cairo
X value of coordinate (in/out parameter)
Y value of coordinate (in/out parameter)
procedure Device_To_User_Distance
(Cr : Cairo_Context;
Dx : access Gdouble;
Dy : access Gdouble)
Transform a distance vector from device space to user space. This function is similar to Device_To_User except that the translation components of the inverse CTM will be ignored when transforming (Dx,dy).
a cairo context
X component of a distance vector (in/out parameter)
Y component of a distance vector (in/out parameter)
procedure Fill (Cr : Cairo_Context)
A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). After Fill, the current path will be cleared from the cairo context. See Set_Fill_Rule and Fill_Preserve.
a cairo context
procedure Fill_Extents
(Cr : Cairo_Context;
X1 : access Gdouble;
Y1 : access Gdouble;
X2 : access Gdouble;
Y2 : access Gdouble)
Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Fill operation given the current path and fill parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account.
Contrast with Path_Extents, which is similar, but returns non-zero extents for some paths with no inked area, (such as a simple line segment).
Note that Fill_Extents must necessarily do more work to compute the precise inked areas in light of the fill rule, so Path_Extents may be more desirable for sake of performance if the non-inked path extents are desired.
See Fill, Set_Fill_Rule and Fill_Preserve.
a cairo context
left of the resulting extents
top of the resulting extents
right of the resulting extents
bottom of the resulting extents
procedure Fill_Preserve (Cr : Cairo_Context)
A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Unlike Fill, Fill_Preserve preserves the path within the cairo context.
See Set_Fill_Rule and Fill.
a cairo context
procedure Font_Extents
(Cr : Cairo_Context;
Extents : access Cairo_Font_Extents)
Gets the font extents for the currently selected font.
a Cairo_Context
a Cairo_Font_Extents object into which the results will be stored.
function Get_Antialias (Cr : Cairo_Context) return Cairo_Antialias
Gets the current shape antialiasing mode, as set by Set_Antialias.
a cairo context
the current shape antialiasing mode.
function Get_Context
(Value : Glib.Values.GValue) return Cairo_Context
Support for callbacks that receive a Cairo_Context as parameter.
procedure Get_Current_Point
(Cr : Cairo_Context;
X : access Gdouble;
Y : access Gdouble)
Gets the current point of the current path, which is conceptually the final point reached by the path so far.
The current point is returned in the user-space coordinate system. If there is no defined current point or if cr is in an error status, X and Y will both be set to 0.0. It is possible to check this in advance with Has_Current_Point.
Most path construction functions alter the current point. See the following for details on how they affect the current point: New_Path, New_Sub_Path, Append_Path, Close_Path, Move_To, Line_To, Curve_To, Rel_Move_To, Rel_Line_To, Rel_Curve_To, Arc, Arc_Negative, Rectangle, Text_Path, Glyph_Path, Stroke_To_Path.
Some functions use and alter the current point but do not otherwise change current path: Show_Text.
Some functions unset the current path and as a result, current point: Fill, Stroke.
a cairo context
return value for X coordinate of the current point
return value for Y coordinate of the current point
procedure Get_Dash
(Cr : Cairo_Context;
Dashes : out Dash_Array_Access;
Offset : out Gdouble)
Gets the current dash array.
@since 1.4
a Cairo_Context
return value for the dash array, or null
return value for the current dash Offset, or null
function Get_Dash_Count (Cr : Cairo_Context) return Gint
This function returns the length of the dash array in cr (0 if dashing is not currently in effect).
See also Set_Dash and Get_Dash.
@since 1.4
a Cairo_Context
the length of the dash array, or 0 if no dash array set.
function Get_Fill_Rule (Cr : Cairo_Context) return Cairo_Fill_Rule
Gets the current fill rule, as set by Set_Fill_Rule.
a cairo context
the current fill rule.
function Get_Font_Face (Cr : Cairo_Context) return Cairo_Font_Face
Gets the current font face for a Cairo_Context.
This function never returns Null_Font_Face. If memory cannot be allocated, a special "nil" Cairo_Font_Face object will be returned on which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this nil object will cause its error state to propagate to other objects it is passed to, (for example, calling Set_Font_Face with a nil font will trigger an error that will shutdown the Cairo_Context object).
a Cairo_Context
the current font face. This object is owned by cairo. To keep a reference to it, you must call Cairo.Font_Face.Reference.
procedure Get_Font_Matrix
(Cr : Cairo_Context;
Matrix : access Cairo_Matrix)
Stores the current font matrix into matrix. See Set_Font_Matrix.
a Cairo_Context
return value for the Matrix
procedure Get_Font_Options
(Cr : Cairo_Context;
Options : Cairo_Font_Options)
Retrieves font rendering options set via Set_Font_Options. Note that the returned options do not include any options derived from the underlying surface; they are literally the options passed to Set_Font_Options.
a Cairo_Context
a Cairo_Font_Options object into which to store the retrieved options. All existing values are overwritten
function Get_Group_Target (Cr : Cairo_Context) return Cairo_Surface
Gets the current destination surface for the context. This is either the original target surface as passed to Create or the target surface for the current group as started by the most recent call to Push_Group or Push_Group_With_Content.
This function will always return a valid pointer, but the result can be a "nil" surface if cr is already in an error state, (ie. Cairo_Status /= Cairo_Status_Success). A nil surface is indicated by Cairo_Status /= Cairo_Status_Success.
@since 1.2
a cairo context
the target surface. This object is owned by cairo. To keep a reference to it, you must call Cairo.Surface.Reference.
function Get_Line_Cap (Cr : Cairo_Context) return Cairo_Line_Cap
Gets the current line cap style, as set by Set_Line_Cap.
a cairo context
the current line cap style.
function Get_Line_Join (Cr : Cairo_Context) return Cairo_Line_Join
Gets the current line join style, as set by Set_Line_Join.
a cairo context
the current line join style.
function Get_Line_Width (Cr : Cairo_Context) return Gdouble
This function returns the current line width value exactly as set by Set_Line_Width. Note that the value is unchanged even if the CTM has changed between the calls to Set_Line_Width and Get_Line_Width.
a cairo context
the current line width.
procedure Get_Matrix (Cr : Cairo_Context; Matrix : access Cairo_Matrix)
Stores the current transformation matrix (CTM) into matrix.
a cairo context
return value for the Matrix
function Get_Miter_Limit (Cr : Cairo_Context) return Gdouble
Gets the current miter limit, as set by Set_Miter_Limit.
a cairo context
the current miter limit.
function Get_Operator (Cr : Cairo_Context) return Cairo_Operator
Gets the current compositing operator for a cairo context.
a cairo context
the current compositing operator.
function Get_Reference_Count (Cr : Cairo_Context) return Guint
Returns the current reference count of cr.
@since 1.4
a Cairo_Context
the current reference count of cr. If the object is a nil object, 0 will be returned.
function Get_Scaled_Font (Cr : Cairo_Context) return Cairo_Scaled_Font
Gets the current scaled font for a Cairo_Context.
This function never returns Null_Font_Face. If memory cannot be allocated, a special "nil" Cairo_Scaled_Font object will be returned on which Cairo.Font_Face.Status returns Cairo_Status_No_Memory. Using this nil object will cause its error state to propagate to other objects it is passed to, (for example, calling Set_Font_Face with a nil font will trigger an error that will shutdown the Cairo_Context object).
@since 1.4
a Cairo_Context
the current scaled font. This object is owned by cairo. To keep a reference to it, you must call Cairo.Scaled_Font.Reference.
function Get_Source (Cr : Cairo_Context) return Cairo_Pattern
Gets the current source pattern for Cr.
a cairo context
the current source pattern. This object is owned by cairo. To keep a reference to it, you must call Cairo.Pattern.Reference.
function Get_Target (Cr : Cairo_Context) return Cairo_Surface
Gets the target surface for the cairo context as passed to Create.
This function will always return a valid pointer, but the result can be a "nil" surface if cr is already in an error state, (ie. Cairo_Status /= Cairo_Status_Success). A nil surface is indicated by Cairo.Surface.Status/= Cairo_Status_Success.
a cairo context
the target surface. This object is owned by cairo. To keep a reference to it, you must call Cairo.Surface.Reference.
function Get_Tolerance (Cr : Cairo_Context) return Gdouble
Gets the current tolerance value, as set by Set_Tolerance.
a cairo context
the current tolerance value.
function Get_User_Data
(Cr : Cairo_Context;
Key : access Cairo_User_Data_Key)
return System.Address
Return user data previously attached to cr using the specified key. If no user data has been attached with the given key this function returns NULL.
@since 1.4
a Cairo_Context
the address of the Cairo_User_Data_Key the user data was attached to
the user data previously attached or NULL.
procedure Glyph_Extents
(Cr : Cairo_Context;
Glyphs : access Cairo_Glyph;
Num_Glyphs : Gint;
Extents : access Cairo_Text_Extents)
Gets the extents for an array of glyphs. The extents describe a user-space rectangle that encloses the "inked" portion of the glyphs, (as they would be drawn by Show_Glyphs). Additionally, the X_Advance and Y_Advance values indicate the amount by which the current point would be advanced by Show_Glyphs.
Note that whitespace glyphs do not contribute to the size of the rectangle (Extents.Width and Extents.Height).
a Cairo_Context
an array of Cairo_Glyph objects
the number of elements in glyphs
a Cairo_Text_Extents object into which the results will be stored
function Has_Current_Point (Cr : Cairo_Context) return Boolean
Returns whether a current point is defined on the current path. See Get_Current_Point for details on the current point.
@since 1.6
a cairo context
whether a current point is defined.
type Header_Type is record
Path_Type : aliased Cairo_Path_Data_Type;
Length : aliased Gint;
end record;
A Path header. See Cairo_Path_Data for details.
procedure Identity_Matrix (Cr : Cairo_Context)
Resets the current transformation matrix (CTM) by setting it equal to the identity matrix. That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.
a cairo context
function In_Fill
(Cr : Cairo_Context;
X : Gdouble;
Y : Gdouble)
return Boolean
Tests whether the given point is inside the area that would be affected by a Fill operation given the current path and filling parameters. Surface dimensions and clipping are not taken into account.
See Fill, Set_Fill_Rule and Fill_Preserve.
a cairo context
X coordinate of the point to test
Y coordinate of the point to test
A non-zero value if the point is inside, or zero if outside.
function In_Stroke
(Cr : Cairo_Context;
X : Gdouble;
Y : Gdouble)
return Boolean
Tests whether the given point is inside the area that would be affected by a Stroke operation given the current path and stroking parameters. Surface dimensions and clipping are not taken into account.
See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.
a cairo context
X coordinate of the point to test
Y coordinate of the point to test
A non-zero value if the point is inside, or zero if outside.
procedure Line_To (Cr : Cairo_Context; X : Gdouble; Y : Gdouble)
Adds a line to the path from the current point to position (X, Y) in user-space coordinates. After this call the current point will be (X, Y).
If there is no current point before the call to Line_To this function will behave as Move_To (Cr, X, Y).
a cairo context
the X coordinate of the end of the new line
the Y coordinate of the end of the new line
procedure Mask (Cr : Cairo_Context; Pattern : Cairo_Pattern)
A drawing operator that paints the current source using the alpha channel of pattern as a mask. (Opaque areas of pattern are painted with the source, transparent areas are not painted.)
a cairo context
a Cairo_Pattern
procedure Mask_Surface
(Cr : Cairo_Context;
Surface : Cairo_Surface;
Surface_X : Gdouble;
Surface_Y : Gdouble)
A drawing operator that paints the current source using the alpha channel of surface as a mask. (Opaque areas of surface are painted with the source, transparent areas are not painted.)
a cairo context
a Cairo_Surface
X coordinate at which to place the origin of surface
Y coordinate at which to place the origin of surface
procedure Move_To (Cr : Cairo_Context; X : Gdouble; Y : Gdouble)
Begin a new sub-path. After this call the current point will be (X, Y).
a cairo context
the X coordinate of the new position
the Y coordinate of the new position
procedure New_Path (Cr : Cairo_Context)
Clears the current path. After this call there will be no path and no current point.
a cairo context
procedure New_Sub_Path (Cr : Cairo_Context)
Begin a new sub-path. Note that the existing path is not affected. After this call there will be no current point.
In many cases, this call is not needed since new sub-paths are frequently started with Move_To.
A call to New_Sub_Path is particularly useful when beginning a new sub-path with one of the Arc calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to Move_To.
@since 1.2
a cairo context
No_Dashes : constant Dash_Array (1 .. 0) := (others => 0.0);
Null_Context : constant Cairo_Context;
Null_Font_Face : constant Cairo_Font_Face;
Null_Font_Options : constant Cairo_Font_Options;
Null_Pattern : constant Cairo_Pattern;
Null_Scaled_Font : constant Cairo_Scaled_Font;
Null_Surface : constant Cairo_Surface;
procedure Paint (Cr : Cairo_Context)
A drawing operator that paints the current source everywhere within the current clip region.
a cairo context
procedure Paint_With_Alpha (Cr : Cairo_Context; Alpha : Gdouble)
A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha. The effect is similar to Paint, but the drawing is faded out using the alpha value.
a cairo context
Alpha value, between 0 (transparent) and 1 (opaque)
type Path_Data_Array is array (Natural) of Cairo_Path_Data;
type Path_Data_Array_Access is access all Path_Data_Array;
procedure Path_Destroy (Path : access Cairo_Path)
Immediately releases all memory associated with Path. After a call to Path_Destroy the Path pointer is no longer valid and should not be used further.
Note: Path_Destroy should only be called with an access to a Cairo_Path returned by a cairo function. Any path that is created manually (ie. outside of cairo) should be destroyed manually as well.
a path previously returned by either Copy_Path or Copy_Path_Flat.
procedure Path_Extents
(Cr : Cairo_Context;
X1 : access Gdouble;
Y1 : access Gdouble;
X2 : access Gdouble;
Y2 : access Gdouble)
Computes a bounding box in user-space coordinates covering the points on the current path. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Stroke parameters, fill rule, surface dimensions and clipping are not taken into account.
Contrast with Fill_Extents and Stroke_Extents which return the extents of only the area that would be "inked" by the corresponding drawing operations.
The result of Path_Extents is defined as equivalent to the limit of Stroke_Extents with Cairo_Line_Cap_Round as the line width approaches 0.0, (but never reaching the empty-rectangle returned by Cairo_Stroke_Extents for a line width of 0.0).
Specifically, this means that zero-area sub-paths such as Move_To;Line_To segments, (even degenerate cases where the coordinates to both calls are identical), will be considered as contributing to the extents. However, a lone Move_To will not contribute to the results of Path_Extents.
@since 1.6
a cairo context
left of the resulting extents
top of the resulting extents
right of the resulting extents
bottom of the resulting extents
procedure Pattern_Add_Color_Stop_Rgb
(Pattern : Cairo_Pattern;
Offset : Gdouble;
Red, Green, Blue : Gdouble)
procedure Pattern_Add_Color_Stop_Rgba
(Pattern : Cairo_Pattern;
Offset : Gdouble;
Red, Green, Blue, Alpha : Gdouble)
function Pattern_Create_For_Surface
(Surface : Cairo_Surface) return Cairo_Pattern
function Pattern_Create_Linear
(X0, Y0, X1, Y1 : Gdouble) return Cairo_Pattern
See Pattern_Add_Color_Stop to specify the colors
function Pattern_Create_Radial
(Cx0, Cy0, Radius0, Cx1, Cy1, Radius1 : Gdouble) return Cairo_Pattern
function Pattern_Create_Rgb
(Red, Green, Blue : Gdouble) return Cairo_Pattern
function Pattern_Create_Rgba
(Red, Green, Blue, Alpha : Gdouble) return Cairo_Pattern
procedure Pattern_Destroy (Pattern : Cairo_Pattern)
type Point_Type is record
X : aliased Gdouble;
Y : aliased Gdouble;
end record;
A geometrical point. See Cairo_Path_Data for details.
function Pop_Group (Cr : Cairo_Context) return Cairo_Pattern
Terminates the redirection begun by a call to Push_Group or Push_Group_With_Content and returns a new pattern containing the results of all drawing operations performed to the group.
The Pop_Group function calls Restore, (balancing a call to Save by the Push_Group function), so that any changes to the graphics state will not be visible outside the group.
@since 1.2
a cairo context
a newly created (surface) pattern containing the results of all drawing operations performed to the group. The caller owns the returned object and should call Cairo.Pattern.Destroy when finished with it.
procedure Pop_Group_To_Source (Cr : Cairo_Context)
Terminates the redirection begun by a call to Push_Group or Push_Group_With_Content and installs the resulting pattern as the source pattern in the given cairo context.
The behavior of this function is equivalent to the sequence of operations:
declare Group: Cairo_Pattern := Pop_Group (Cr); begin Set_Source (Cr, Group); Cairo.Pattern.Destroy (Group); end;
but is more convenient as their is no need for a variable to store the short-lived pointer to the pattern.
The Pop_Group function calls Restore, (balancing a call to Save by the push_group function), so that any changes to the graphics state will not be visible outside the group.
@since 1.2
a cairo context
procedure Push_Group (Cr : Cairo_Context)
Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Pop_Group or Pop_Group_To_Source.
These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern).
This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination.
Groups can be nested arbitrarily deep by making balanced calls to Push_Group/Pop_Group. Each call pushes/pops the new target group onto/from a stack.
The Push_Group function calls Save so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call Restore).
By default the intermediate group will have a content type of Cairo_Content_Color_Alphe. Other content types can be chosen for the group by using Push_Group_With_Content instead.
As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke:
Push_Group (Cr);
Set_Source (Cr, Fill_Pattern);
Fill_Preserve (Cr);
Set_Source (Cr, Stroke_Pattern);
Stroke (Cr);
Pop_Group_To_Source (Cr);
Paint_With_Alpha (Cr, Alpha);
@since 1.2
a cairo context
procedure Push_Group_With_Content
(Cr : Cairo_Context;
Content : Cairo_Content)
Temporarily redirects drawing to an intermediate surface known as a group. The redirection lasts until the group is completed by a call to Pop_Group or Pop_Group_To_Source. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern).
The group will have a content type of content. The ability to control this content type is the only distinction between this function and Push_Group which you should see for a more detailed description of group rendering.
@since 1.2
a cairo context
a Cairo_Content indicating the type of group that will be created
procedure Rectangle
(Cr : Cairo_Context;
X : Gdouble;
Y : Gdouble;
Width : Gdouble;
Height : Gdouble)
Adds a closed sub-path rectangle of the given size to the current path at position (X, Y) in user-space coordinates.
This function is logically equivalent to:
Move_To (Cr, x, Y); Rel_Line_To (Cr, Width, 0); Rel_Line_To (Cr, 0, Height); Rel_Line_To (Cr, -Width, 0); Close_Path (Cr);
a cairo context
the X coordinate of the top left corner of the rectangle
the Y coordinate to the top left corner of the rectangle
the Width of the rectangle
the Height of the rectangle
procedure Rectangle_List_Destroy
(Rectangle_List : access Cairo_Rectangle_List)
Unconditionally frees Rectangle_List and all associated references. After this call, the Rectangle_List pointer must not be dereferenced.
@since 1.4
a rectangle list, as obtained from Copy_Clip_Rectangles
function Reference (Cr : Cairo_Context) return Cairo_Context
Increases the reference count on cr by one. This prevents cr from being destroyed until a matching call to Destroy is made.
The number of references to a Cairo_Context can be retrieved using Get_Reference_Count.
a Cairo_Context
the referenced Cairo_Context.
procedure Rel_Curve_To
(Cr : Cairo_Context;
Dx1 : Gdouble;
Dy1 : Gdouble;
Dx2 : Gdouble;
Dy2 : Gdouble;
Dx3 : Gdouble;
Dy3 : Gdouble)
Relative-coordinate version of Cairo_Curve_To. All offsets are relative to the current point. Adds a cubic Bézier spline to the path from the current point to a point offset from the current point by (Dx3, Dy3), using points offset by (Dx1, Dy1) and (Dx2, Dy2) as the control points. After this call the current point will be offset by (Dx3, Dy3).
Given a current point of (X, Y), Cairo_Rel_Curve_To(Cr, Dx1, Dy1, Dx2, Dy2, Dx3, Dy3) is logically equivalent to Cairo_Curve_To(Cr, X+Dx1, Y+Dy1, X+Dx2, Y+Dy2, X+Dx3, Y+Dy3).
It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.
a cairo context
the X offset to the first control point
the Y offset to the first control point
the X offset to the second control point
the Y offset to the second control point
the X offset to the end of the curve
the Y offset to the end of the curve
procedure Rel_Line_To (Cr : Cairo_Context; Dx : Gdouble; Dy : Gdouble)
Relative-coordinate version of Line_To. Adds a line to the path from the current point to a point that is offset from the current point by (Dx, Dy) in user space. After this call the current point will be offset by (Dx, Dy).
Given a current point of (X, Y), Rel_Line_To (Cr, Dx, Dy) is logically equivalent to Cairo_Line_To(Cr, X + Dx, Y + Dy).
It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.
a cairo context
the X offset to the end of the new line
the Y offset to the end of the new line
procedure Rel_Move_To (Cr : Cairo_Context; Dx : Gdouble; Dy : Gdouble)
Begin a new sub-path. After this call the current point will offset by (X, Y).
Given a current point of (X, Y), Rel_Move_To (Cr, Dx, Dy) is logically equivalent to Move_To (Cr, X + Dx, Y + Dy).
It is an error to call this function with no current point. Doing so will cause cr to shutdown with a status of Cairo_Status_No_Current_Point.
a cairo context
the X offset
the Y offset
procedure Reset_Clip (Cr : Cairo_Context)
Reset the current clip region to its original, unrestricted state. That is, set the clip region to an infinitely large shape containing the target surface. Equivalently, if infinity is too hard to grasp, one can imagine the clip region being reset to the exact bounds of the target surface.
Note that code meant to be reusable should not call Reset_Clip as it will cause results unexpected by higher-level code which calls Clip. Consider using Save and Restore around Clip as a more robust means of temporarily restricting the clip region.
a cairo context
procedure Restore (Cr : Cairo_Context)
Restores cr to the state saved by a preceding call to Cairo_Save and removes that state from the stack of saved states.
a Cairo_Context
procedure Rotate (Cr : Cairo_Context; Angle : Gdouble)
Modifies the current transformation matrix (CTM) by rotating the user-space axes by angle radians. The rotation of the axes takes places after any existing transformation of user space. The rotation direction for positive angles is from the positive X axis toward the positive Y axis.
a cairo context
Angle (in radians) by which the user-space axes will be rotated
procedure Save (Cr : Cairo_Context)
Makes a copy of the current state of cr and saves it on an internal stack of saved states for cr. When Cairo_Restore is called, cr will be restored to the saved state. Multiple calls to Cairo_Save and Cairo_Restore can be nested; each call to Cairo_Restore restores the state from the matching paired Cairo_Save.
It isn't necessary to clear all saved states before a Cairo_Context is freed. If the reference count of a Cairo_Context drops to zero in response to a call to Cairo_Destroy, any saved states will be freed along with the Cairo_Context.
a Cairo_Context
procedure Scale (Cr : Cairo_Context; Sx : Gdouble; Sy : Gdouble)
Modifies the current transformation matrix (CTM) by scaling the X and Y user-space axes by sx and sy respectively. The scaling of the axes takes place after any existing transformation of user space.
a cairo context
scale factor for the X dimension
scale factor for the Y dimension
procedure Select_Font_Face
(Cr : Cairo_Context;
Family : String;
Slant : Cairo_Font_Slant;
Weight : Cairo_Font_Weight)
Note: The Select_Font_Face function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications.
Selects a family and style of font from a simplified description as a family name, slant and weight. Cairo provides no operation to list available family names on the system (this is a "toy", remember), but the standard CSS2 generic family names, ("serif", "sans-serif", "cursive", "fantasy", "monospace"), are likely to work as expected.
It is expected that most applications will need to use a more comprehensive font handling and text layout library, (for example, pango), in conjunction with cairo.
If text is drawn without a call to Select_Font_Face, (nor Set_Font_Face nor Set_Scaled_Font), the default family is platform-specific, but is essentially "sans-serif". Default slant is Cairo_Font_Slant_Normal, and default weight is Cairo_Font_Weight_Normal.
This function is equivalent to a call to Cairo.Font_Face.Toy_Font_Face_Create followed by Set_Font_Face.
a Cairo_Context
a font Family name, encoded in UTF-8
the Slant for the font
the Weight for the font
procedure Set_Antialias
(Cr : Cairo_Context;
Antialias : Cairo_Antialias)
Set the antialiasing mode of the rasterizer used for drawing shapes. This value is a hint, and a particular backend may or may not support a particular value. At the current time, no backend supports Cairo_Antialias_Subpixel when drawing shapes.
Note that this option does not affect text rendering, instead see Cairo.Font_Options.Set_Antialias.
a Cairo_Context
the new Antialiasing mode
procedure Set_Dash
(Cr : Cairo_Context;
Dashes : Dash_Array;
Offset : Gdouble)
Sets the dash pattern to be used by Stroke. A dash pattern is specified by dashes, an array of positive values. Each value provides the length of alternate "on" and "off" portions of the stroke. The offset specifies an offset into the pattern at which the stroke begins.
Each "on" segment will have caps applied as if the segment were a separate sub-path. In particular, it is valid to use an "on" length of 0.0 with Cairo_Line_Cap_Round or Cairo_Line_Cap_Square in order to distributed dots or squares along a path.
Note: The length values are in user-space units as evaluated at the time of stroking. This is not necessarily the same as the user space at the time of Set_Dash.
If the array is No_Dashes, dashing is disabled.
If the array contains only one element symmetric pattern is assumed with alternating on and off portions of the size specified by the single value in dashes.
If any value in dashes is negative, or if all values are 0, then cr will be put into an error state with a status of Cairo_Status_Invalid_Dash.
a cairo context
an array specifying alternate lengths of on and off stroke portions
an Offset into the dash pattern at which the stroke should start
procedure Set_Fill_Rule
(Cr : Cairo_Context;
Fill_Rule : Cairo_Fill_Rule)
Set the current fill rule within the cairo context. The fill rule is used to determine which regions are inside or outside a complex (potentially self-intersecting) path. The current fill rule affects both Fill and Clip. See Cairo_Fill_Rule for details on the semantics of each available fill rule.
The default fill rule is Cairo_Fill_Rule_Winding.
a Cairo_Context
a fill rule
procedure Set_Font_Face
(Cr : Cairo_Context;
Font_Face : Cairo_Font_Face)
Replaces the current Cairo_Font_Face object in the Cairo_Context with font_face. The replaced font face in the Cairo_Context will be destroyed if there are no other references to it.
a Cairo_Context
a Cairo_Font_Face, or Null_Font_Face to restore to the default font
procedure Set_Font_Matrix
(Cr : Cairo_Context;
Matrix : access Cairo_Matrix)
Sets the current font matrix to matrix. The font matrix gives a transformation from the design space of the font (in this space, the em-square is 1 unit by 1 unit) to user space. Normally, a simple scale is used (see Set_Font_Size), but a more complex font matrix can be used to shear the font or stretch it unequally along the two axes
a Cairo_Context
a Cairo_Matrix describing a transform to be applied to the current font.
procedure Set_Font_Options
(Cr : Cairo_Context;
Options : Cairo_Font_Options)
Sets a set of custom font rendering options for the Cairo_Context. Rendering options are derived by merging these options with the options derived from underlying surface; if the value in options has a default value (like Cairo_Antialias_Default), then the value from the surface is used.
a Cairo_Context
font Options to use
procedure Set_Font_Size (Cr : Cairo_Context; Size : Gdouble)
Sets the current font matrix to a scale by a factor of size, replacing any font matrix previously set with Set_Font_Size or Set_Font_Matrix. This results in a font size of size user space units. (More precisely, this matrix will result in the font's em-square being a size by size square in user space.)
If text is drawn without a call to Set_Font_Size, (nor Set_Font_Matrix nor Set_Scaled_Font), the default font size is 10.0.
a Cairo_Context
the new font Size, in user space units
procedure Set_Line_Cap (Cr : Cairo_Context; Line_Cap : Cairo_Line_Cap)
Sets the current line cap style within the cairo context. See Cairo_Line_Cap for details about how the available line cap styles are drawn.
As with the other stroke parameters, the current line cap style is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction.
The default line cap style is Cairo_Line_Cap_Butt.
a cairo context
a line cap style
procedure Set_Line_Join
(Cr : Cairo_Context;
Line_Join : Cairo_Line_Join)
Sets the current line join style within the cairo context. See Cairo_Line_Join for details about how the available line join styles are drawn.
As with the other stroke parameters, the current line join style is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction.
The default line join style is Cairo_Line_Join_Miter.
a cairo context
a line join style
procedure Set_Line_Width (Cr : Cairo_Context; Width : Gdouble)
Sets the current line width within the cairo context. The line width value specifies the diameter of a pen that is circular in user space, (though device-space pen may be an ellipse in general due to scaling/shear/rotation of the CTM).
Note: When the description above refers to user space and CTM it refers to the user space and CTM in effect at the time of the stroking operation, not the user space and CTM in effect at the time of the call to Set_Line_Width. The simplest usage makes both of these spaces identical. That is, if there is no change to the CTM between a call to Set_Line_Width and the stroking operation, then one can just pass user-space values to Set_Line_Width and ignore this note.
As with the other stroke parameters, the current line width is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction.
The default line width value is 2.0.
a Cairo_Context
a line Width
procedure Set_Matrix
(Cr : Cairo_Context;
Matrix : access Cairo_Matrix)
Modifies the current transformation matrix (CTM) by setting it equal to matrix.
a cairo context
a transformation Matrix from user space to device space
procedure Set_Miter_Limit (Cr : Cairo_Context; Limit : Gdouble)
Sets the current miter limit within the cairo context.
If the current line join style is set to Cairo_Line_Join_Miter (see Cairo_Set_Line_Join), the miter limit is used to determine whether the lines should be joined with a bevel instead of a miter. Cairo divides the length of the miter by the line width. If the result is greater than the miter limit, the style is converted to a bevel.
As with the other stroke parameters, the current line miter limit is examined by Stroke, Stroke_Extents, and Stroke_To_Path, but does not have any effect during path construction.
The default miter limit value is 10.0, which will convert joins with interior angles less than 11 degrees to bevels instead of miters. For reference, a miter limit of 2.0 makes the miter cutoff at 60 degrees, and a miter limit of 1.414 makes the cutoff at 90 degrees.
A miter limit for a desired angle can be computed as: miter limit = 1/sin(angle/2)
a cairo context
miter Limit to set
procedure Set_Operator (Cr : Cairo_Context; Op : Cairo_Operator)
Sets the compositing operator to be used for all drawing operations. See Cairo_Operator for details on the semantics of each available compositing operator.
The default operator is Cairo_Operator_Over.
a Cairo_Context
a compositing Operator, specified as a Cairo_Operator
procedure Set_Scaled_Font
(Cr : Cairo_Context;
Scaled_Font : access Cairo_Scaled_Font)
Replaces the current font face, font matrix, and font options in the Cairo_Context with those of the Cairo_Scaled_Font. Except for some translation, the current CTM of the Cairo_Context should be the same as that of the Cairo_Scaled_Font, which can be accessed using Cairo.Scaled_Font.Get_Ctm.
@since 1.2
a Cairo_Context
a Cairo_Scaled_Font
procedure Set_Source (Cr : Cairo_Context; Source : Cairo_Pattern)
Sets the source pattern within Cr to source. This pattern will then be used for any subsequent drawing operation until a new source pattern is set.
Note: The pattern's transformation matrix will be locked to the user space in effect at the time of Set_Source. This means that further modifications of the current transformation matrix will not affect the source pattern. See Cairo.Pattern.Set_Matrix.
The default source pattern is a solid pattern that is opaque black, (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).
a cairo context
a Cairo_Pattern to be used as the Source for subsequent drawing operations.
procedure Set_Source_Rgb
(Cr : Cairo_Context;
Red : Color_Range;
Green : Color_Range;
Blue : Color_Range)
Sets the source pattern within Cr to an opaque color. This opaque color will then be used for any subsequent drawing operation until a new source pattern is set.
The color components are floating point numbers in the range 0 to
If the values passed in are outside that range, they will be
clamped.
The default source pattern is opaque black, (that is, it is equivalent to Set_Source_Rgb (Cr, 0.0, 0.0, 0.0)).
a cairo context
Red component of color
Green component of color
Blue component of color
procedure Set_Source_Rgba
(Cr : Cairo_Context;
Red : Color_Range;
Green : Color_Range;
Blue : Color_Range;
Alpha : Color_Range)
Sets the source pattern within Cr to a translucent color. This color will then be used for any subsequent drawing operation until a new source pattern is set.
The color and alpha components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.
The default source pattern is opaque black, (that is, it is equivalent to Set_Source_Rgba (Cr, 0.0, 0.0, 0.0, 1.0)).
a cairo context
Red component of color
Green component of color
Blue component of color
Alpha component of color
procedure Set_Source_Surface
(Cr : Cairo_Context;
Surface : Cairo_Surface;
X : Gdouble;
Y : Gdouble)
This is a convenience function for creating a pattern from surface and setting it as the source in Cr with Set_Source.
The X and Y parameters give the user-space coordinate at which the surface origin should appear. (The surface origin is its upper-left corner before any transformation has been applied.) The X and Y patterns are negated and then set as translation values in the pattern matrix.
Other than the initial translation pattern matrix, as described above, all other pattern attributes, (such as its extend mode), are set to the default values as in Cairo.Pattern.Create_For_Surface. The resulting pattern can be queried with Get_Source so that these attributes can be modified if desired, (eg. to create a repeating pattern with Cairo.Pattern.Set_Extend).
a cairo context
a Surface to be used to set the source pattern
User-space X coordinate for surface origin
User-space Y coordinate for surface origin
procedure Set_Tolerance (Cr : Cairo_Context; Tolerance : Gdouble)
Sets the tolerance used when converting paths into trapezoids. Curved segments of the path will be subdivided until the maximum deviation between the original path and the polygonal approximation is less than tolerance. The default value is 0.1. A larger value will give better performance, a smaller value, better appearance. (Reducing the value from the default value of 0.1 is unlikely to improve appearance significantly.) The accuracy of paths within Cairo is limited by the precision of its internal arithmetic, and the prescribed tolerance is restricted to the smallest representable internal value.
a Cairo_Context
the Tolerance, in device units (typically pixels)
function Set_User_Data
(Cr : Cairo_Context;
Key : access Cairo_User_Data_Key;
User_Data : System.Address;
Destroy : Cairo_Destroy_Func)
return Cairo_Status
Attach user data to cr. To remove user data from a surface, call this function with the key that was used to set it and NULL for data.
@since 1.4
a Cairo_Context
the address of a Cairo_User_Data_Key to attach the user data to
the user data to attach to the Cairo_Context
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.
CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY if a slot could not be allocated for the user data.
procedure Show_Glyphs
(Cr : Cairo_Context;
Glyphs : access Cairo_Glyph;
Num_Glyphs : Gint)
A drawing operator that generates the shape from an array of glyphs, rendered according to the current font face, font size (font matrix), and font options.
a cairo context
array of Glyphs to show
number of glyphs to show
procedure Show_Page (Cr : Cairo_Context)
Emits and clears the current page for backends that support multiple pages. Use Copy_Page if you don't want to clear the page.
This is a convenience function that simply calls Cairo.Surface.Show_Page on cr's target.
a cairo context
procedure Show_Text
(Cr : Cairo_Context;
Utf8 : String)
A drawing operator that generates the shape from a string of UTF-8 characters, rendered according to the current Font_Face, Font_Size (Font_Matrix), and Font_Options.
This function first computes a set of glyphs for the string of text. The first glyph is placed so that its origin is at the current point. The origin of each subsequent glyph is offset from that of the previous glyph by the advance values of the previous glyph.
After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for easy display of a single logical string with multiple calls to Show_Text.
Note: The Show_Text function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Show_Glyphs for the "real" text display API in cairo.
a cairo context
a NUL-terminated string of text encoded in UTF-8, or Null_Ptr
function Status (Cr : Cairo_Context) return Cairo_Status
Checks whether an error has previously occurred for this context.
a cairo context
the current status of this context, see Cairo_Status
procedure Stroke (Cr : Cairo_Context)
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. After Cairo_Stroke, the current path will be cleared from the cairo context. See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.
Note: Degenerate segments and sub-paths are treated specially and provide a useful result. These can result in two different situations:
Zero-length "on" segments set in Set_Dash. If the cap
style is Cairo_Line_Cap_Round or Cairo_Line_Cap_Square then these segments will be drawn as circular dots or squares respectively. In the case of Cairo_Line_Cap_Square, the orientation of the squares is determined by the direction of the underlying path.
A sub-path created by Cairo_Move_To followed by either a
Cairo_Close_Path or one or more calls to Cairo_Line_To to the same coordinate as the Cairo_Move_To. If the cap style is Cairo_Line_Cap_Round then these sub-paths will be drawn as circular dots. Note that in the case of Cairo_Line_Cap_Square a degenerate sub-path will not be drawn at all, (since the correct orientation is indeterminate).
In no case will a cap style of Cairo_Line_Cap_Butt cause anything to be drawn in the case of either degenerate segments or sub-paths.
a cairo context
procedure Stroke_Extents
(Cr : Cairo_Context;
X1 : access Gdouble;
Y1 : access Gdouble;
X2 : access Gdouble;
Y2 : access Gdouble)
Computes a bounding box in user coordinates covering the area that would be affected, (the "inked" area), by a Stroke operation given the current path and stroke parameters. If the current path is empty, returns an empty rectangle ((0,0), (0,0)). Surface dimensions and clipping are not taken into account.
Note that if the line width is set to exactly zero, then Stroke_Extents will return an empty rectangle. Contrast with Path_Extents which can be used to compute the non-empty bounds as the line width approaches zero.
Note that Stroke_Extents must necessarily do more work to compute the precise inked areas in light of the stroke parameters, so Path_Extents may be more desirable for sake of performance if non-inked path extents are desired.
See Stroke, Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.
a cairo context
left of the resulting extents
top of the resulting extents
right of the resulting extents
bottom of the resulting extents
procedure Stroke_Preserve (Cr : Cairo_Context)
A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings. Unlike Cairo_Stroke, Cairo_Stroke_Preserve preserves the path within the cairo context.
See Set_Line_Width, Set_Line_Join, Set_Line_Cap, Set_Dash, and Stroke_Preserve.
a cairo context
procedure Surface_Destroy (Surface : Cairo_Surface)
Free the memory used by the surface
procedure Text_Extents
(Cr : Cairo_Context;
Utf8 : Gtkada.Types.Chars_Ptr;
Extents : access Cairo_Text_Extents)
Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by Show_Text). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Cairo_Show_Text.
Note that whitespace characters do not directly contribute to the size of the rectangle (extents.width and extents.height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.
a Cairo_Context
a NUL-terminated string of text encoded in UTF-8, or Null_Ptr
a Cairo_Text_Extents object into which the results will be stored
procedure Text_Path
(Cr : Cairo_Context;
Utf8 : String)
Adds closed paths for text to the current path. The generated path if filled, achieves an effect similar to that of Show_Text.
Text conversion and positioning is done similar to Show_Text.
Like Show_Text, After this call the current point is moved to the origin of where the next glyph would be placed in this same progression. That is, the current point will be at the origin of the final glyph offset by its advance values. This allows for chaining multiple calls to to Cairo_Text_Path without having to set current point in between.
Note: The Text_Path function call is part of what the cairo designers call the "toy" text API. It is convenient for short demos and simple programs, but it is not expected to be adequate for serious text-using applications. See Glyph_Path for the "real" text path API in cairo.
a cairo context
a NUL-terminated string of text encoded in UTF-8, or Null_Ptr
procedure Transform
(Cr : Cairo_Context;
Matrix : access Cairo_Matrix)
Modifies the current transformation matrix (CTM) by applying matrix as an additional transformation. The new transformation of user space takes place after any existing transformation.
a cairo context
a transformation to be applied to the user-space axes
procedure Translate (Cr : Cairo_Context; Tx : Gdouble; Ty : Gdouble)
Modifies the current transformation matrix (CTM) by translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the CTM in place before the new call to Translate. In other words, the translation of the user-space origin takes place after any existing transformation.
a cairo context
amount to translate in the X direction
amount to translate in the Y direction
procedure Unchecked_Free is new Ada.Unchecked_Deallocation
(Cairo_Matrix, Cairo_Matrix_Access);
procedure User_To_Device
(Cr : Cairo_Context;
X : access Gdouble;
Y : access Gdouble)
Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix (CTM).
a cairo context
X value of coordinate (in/out parameter)
Y value of coordinate (in/out parameter)
procedure User_To_Device_Distance
(Cr : Cairo_Context;
Dx : access Gdouble;
Dy : access Gdouble)
Transform a distance vector from user space to device space. This function is similar to User_To_Device except that the translation components of the CTM will be ignored when transforming (Dx,Dy).
a cairo context
X component of a distance vector (in/out parameter)
Y component of a distance vector (in/out parameter)