Introduction

Cairo is a 2D graphics library with support for multiple output devices.
Currently, the BlitzMax implementation supports Image, PDF and Postscript output.

The cairo API provides operations similar to the drawing operators of PostScript and PDF. Operations in cairo including stroking and filling cubic Bézier splines, transforming and compositing translucent images, and antialiased text rendering. All drawing operations can be transformed by any affine transformation (scale, rotation, shear, etc.)

The base type you will use is TCairo.
This is what is known as the drawing context. With it you can draw to any of the supported output devices, using the same commands regardless of the device in question. For example, you might preview a diagram on-screen, before creating a PDF containing it.

To create and initial a TCairo context, you need to create it with a TCairoSurface object.

There are three surface types you can currently use:

TCairoImageSurface - draws to an in-memory image.
TCairoPDFSurface - creates a PDF representation of the image(s).
TCairoPSSurface - creates a Postscript representation of the image(s).

To create a TCairo object for drawing onto a pixmap you could do the following :

Local surface:TCairoImageSurface = TCairoImageSurface.CreateForPixmap(256,256)
Local cairo:TCairo = TCairo.Create(surface)

which would create a new pixmap for the surface, and tell cairo to draw on it.
Also, you could use CreateForImage, which uses an existing TImage object to draw onto :

Local image:TImage = CreateImage(256, 256, 1, DYNAMICIMAGE)
Local surface:TCairoImageSurface = TCairoImageSurface.CreateForImage(image)
Local cairo:TCairo = TCairo.Create(surface)

(There are other operations for using pre-existing pixmaps, and even PNG files.)

On creation, a cairo context is already created for you, but whenever Destroy is called you will have to create a new context using CreateContext before you can use it again.

In normal usage you would perform the following operations during the life of a context:

CreateContext()
...draw stuff on the context
Destroy()

To re-use a context, you can also Clear it with a given color, and subsequently perform drawing operations on what is essentially a clean sheet.

The following simple example draws a circle filled yellow with a black outline :

SuperStrict

Import BaH.Cairo

Local cairo:TCairo = TCairo.Create(TCairoImageSurface.CreateForPixmap(256,256))

' set the line width
cairo.SetLineWidth(5)

' draw an arc of 360 degrees (a circle) with radius 125.
cairo.arc(128, 128, 125, 0, 360)

' set draw color to yellow
cairo.SetSourceRGB(1, 1, 0)
' fix fill color to current
cairo.FillPreserve()
' set draw color to black
cairo.SetSourceRGB(0, 0, 0)
' draw it
cairo.Stroke()

' destroy context and resources
cairo.Destroy()

' Retrieve the image data from the pixmap
Local image:TImage = LoadImage(TCairoImageSurface(cairo.getTarget()).pixmap())

Graphics 256, 256,0

SetBlend ALPHABLEND

SetClsColor 255,255,255

Repeat
Cls
DrawImage image, 0, 0
Flip
Until KeyHit(key_escape)

End

For information on creating Surfaces

Examples

The following is a list of examples that you can run:

arc.bmx
arc_image.bmx - The arc example using a TImage.
arc_negative.bmx
clip.bmx
clip_image.bmx
curve_rectangle.bmx
curve_to.bmx
fill_and_stroke.bmx
fill_and_stroke2.bmx
fill_and_stroke3.bmx - Shows SetDash usage.
gradient.bmx
image_pattern.bmx
path.bmx
pattern_fill.bmx
set_line_cap.bmx
set_line_join.bmx
text.bmx
text_align_center.bmx
text_extents.bmx
xxx_long_lines.bmx
clock.bmx - a more advanced example of an analogue clock.
clock_image.bmx - The analogue clock example using a TImage.
clock_gtk_panel_pixmap.bmx - The analogue clock example drawing on a panel pixmap. Resize the window and watch it tile!!
pdf_output_1.bmx - a small example showing creation of a PDF.

Globals

CAIRO_USER_FONTPATH

Global CAIRO_USER_FONTPATH:String = "."

Description: User derived font path.

Information: Add your own here.

Types

TCairo

The Cairo context wrapper type

Methods

CreateContext
AppendPath
Arc
ArcNegative
Clear
Clip
ClipPreserve
ClosePath
CopyPage
CopyPath
CopyPathFlat
CurveTo
Destroy
DeviceToUser
DeviceToUserDistance
Fill
FillExtents
FillPreserve
GetAntialias
GetCurrentPoint
GetFillRule
GetFontFace
GetFontMatrix
GetGroupTarget
GetLineCap
GetLineJoin
GetLineWidth
GetMiterLimit
GetOperator
GetSource
GetTarget
GetTolerance
IdentityMatrix
InFill
InStroke
LineTo
Mask
MaskSurface
MoveTo
NewPath
NewSubPath
Paint
PaintWithAlpha
PopGroup
PopGroupToSource
PushGroup
PushGroupWithContent
Rectangle
Reference
RelCurveTo
RelLineTo
RelMoveTo
ResetClip
Restore
Rotate
Save
Scale
SelectFontFace
SetAntialias
SetDash
SetFillRule
SetFontFace
SetFontMatrix
SetFontOptions
SetFontSize
SetLineCap
SetLineJoin
SetLineWidth
SetMatrix
SetMiterLimit
SetOperator
SetScaledFont
SetSource
SetSourceRGB
SetSourceRGBA
SetSourceSurface
SetTolerance
ShowPage
ShowText
Status
Stroke
StrokeExtents
StrokePreserve
TextExtents
TextPath
Transform
Translate
UserToDevice
UserToDeviceDistance

Functions

Create
StatusToString
Version
VersionString

TCairo: Methods

CreateContext

Method CreateContext()

Description: Create a new Cairo context for objects to be drawn on.

Information: Typical usage might look something like:

CreateContext()
...  draw stuff
Destroy()

AppendPath

Method AppendPath(p:TCairoPath)

Description: Append the path onto the current path.

Arc

Method Arc(XCenter:Double, YCenter:Double, Radius:Double, ..

Description: Adds a circular arc of the given radius to the current path.

Information: The arc is centered at (XCenter, YCenter), begins at StartAngle and proceeds in the direction of increasing angles to end at EndAngle. If EndAngle is less than StartAngle it will be progressively increased by 360 degrees until it is greater than StartAngle. 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. Angles are measured in degrees. An angle of 0 is in the direction of the positive X axis (in user-space). An angle of 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. This function gives the arc in the direction of increasing angles; see ArcNegative 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:

Save()
Translate(x + width / 2.0, y + height / 2.0)
Scale (1.0 / (height / 2.0), 1.0 / (width / 2.0))
Arc(0, 0, 1, 0, 360)
Restore()

Parameters:

XCenter : X position of the center of the arc
YCenter : Y position of the center of the arc
Radius : the radius of the arc
StartAngle : the start angle, in degrees
EndAngle : the end angle, in degrees

ArcNegative

Method ArcNegative(XCenter:Double, YCenter:Double, Radius:Double, ..

Description: Adds a circular arc of the given radius to the current path.

Information: The arc is centered at (XCenter, YCenter), begins at StartAndle and proceeds in the direction of decreasing angles to end at EndAngle. If EndAngle is greater than StartAndle it will be progressively decreased by 360 until it is greater than StartAndle. See Arc for more details. This function differs only in the direction of the arc between the two angles.

Parameters:

XCenter : X position of the center of the arc
YCenter : Y position of the center of the arc
Radius : the radius of the arc
StartAngle : the start angle, in degrees
EndAngle : the end angle, in degrees

Clear

Method Clear(red:Double, green:Double, blue:Double, width:Double, height:Double)

Description: Clear an area of the context with the specified color at the current translation point.

Information: A convenience method for clearing / coloring an area of the context. You can use this for clearing the whole visible area of a context.

Parameters:

red : red component of color
green : blue component of color
blue : green component of color
width : width of the area to be cleared
height : height of the area to be cleared

Clip

Method Clip()

Description: 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 SetFillRule).

Information: 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 ResetClip.

ClipPreserve

Method ClipPreserve()

Description: 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 SetFillRule).

Information: Unlike Clip, ClipPreserve 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 ClipPreserve 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 ClipPreserve within a Save / Restore pair. The only other means of increasing the size of the clip region is ResetClip.

ClosePath

Method ClosePath()

Description: Adds a line segment to the path from the current point to the beginning of the current subpath, (the most recent point passed to MoveTo), and closes this subpath.

Information: The behavior of ClosePath is distinct from simply calling LineTo with the equivalent coordinate in the case of stroking. When a closed subpath is stroked, there are no caps on the ends of the subpath. Instead, there is a line join connecting the final and initial segments of the subpath.

CopyPage

Method CopyPage()

Description: Takes a copy of the current surface to create a new Page.

Information: This is not supported by all surfaces and therefore may not appear to do anything.

CopyPath

Method CopyPath:TCairoPath()

Description: Creates a copy of the current path and returns it to the user as a TCairoPath.

Returns: The copy of the current path. The caller owns the returned object and should call Destroy when finished with it.

CopyPathFlat

Method CopyPathFlat:TCairoPath()

Description: Gets a flattened copy of the current path and returns it to the user as a TCairoPath.

Returns: The copy of the current path. The caller owns the returned object and should call Destroy when finished with it.

Information: This function is like CopyPath 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.

CurveTo

Method CurveTo(x1:Double,y1:Double, x2:Double,y2:Double, x3:Double,y3:Double)

Description: 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.

Information: After this call the current point will be (x3, y3).

Parameters:

x1 : the X coordinate of the first control point
y1 : the Y coordinate of the first control point
x2 : the X coordinate of the second control point
y2 : the Y coordinate of the second control point
x3 : the X coordinate of the end of the curve
y3 : the Y coordinate of the end of the curve

Destroy

Method Destroy()

Description: Decreases the reference count by one.

Information: If the result is zero, then all associated resources are freed.

DeviceToUser

Method DeviceToUser(x:Double Var, y:Double Var)

Description: Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix

Information: Parameters:

x : X value of coordinate (in/out parameter)
y : Y value of coordinate (in/out parameter)

DeviceToUserDistance

Method DeviceToUserDistance(dx:Double Var, dy:Double Var)

Description: Transform a distance vector from device space to user space.

Information: This function is similar to DeviceToUser except that the translation components of the inverse current transformation matrix will be ignored when transforming (dx,dy).

Parameters:

dx : X component of a distance vector (in/out parameter)
dy : Y component of a distance vector (in/out parameter)

Fill

Method Fill()

Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled).

Information: After Fill, the current path will be cleared from the cairo context. See SetFillRule and FillPreserve.

FillExtents

Method FillExtents(x1:Double Var,y1:Double Var, x2:Double Var,y2:Double Var)

Description: Returns the extents for the current fill.

FillPreserve

Method FillPreserve()

Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled).

Information: Unlike Fill, FillPreserve preserves the path within the cairo context.

GetAntialias

Method GetAntialias:Int()

Description: Gets the current shape antialiasing mode, as set by SetAntialias. returns : the current shape antialiasing mode.

GetCurrentPoint

Method GetCurrentPoint(x:Double Var,y:Double Var)

Description: Returns the current point in the context.

GetFillRule

Method GetFillRule:Int()

Description: Gets the current fill rule, as set by SetFillRule. returns : the current fill rule.

GetFontFace

Method GetFontFace:TCairoFontFace()

Description: Gets the current font face for the context.

Returns: The current font object. Can return Null on out-of-memory or if the context is already in an error state. This object is owned by cairo. To keep a reference to it, you must call fontface.Reference()

GetFontMatrix

Method GetFontMatrix:TCairoMatrix()

Description: Gets the current font matrix

Returns: return value for the matrix.

Information: See TCairoMatrix for more information.

GetGroupTarget

Method GetGroupTarget:TCairoSurface()

Description: Gets the target surface for the current group as started by the most recent call to PushGroup or PushGroupWithContent.

Returns: The target group surface, or Null if none. This object is owned by cairo. To keep a reference to it, you must call surface.Reference().

Information: This method will return Null if called "outside" of any group rendering blocks, (that is, after the last balancing call to PopGroup or PopGroupToSource ).

GetLineCap

Method GetLineCap:Int()

Description: Gets the current line cap style, as set by SetLineCap. returns : the current line cap style.

GetLineJoin

Method GetLineJoin:Int()

Description: Gets the current line join style, as set by SetLineJoin. returns : the current line join style.

GetLineWidth

Method GetLineWidth:Double()

Description: Gets the current line width, as set by SetLineWidth. returns : the current line width, in user-space units.

GetMiterLimit

Method GetMiterLimit:Double()

Description: Gets the miter limit, as set by SetMiterLimit. returns : the current miter limit.

GetOperator

Method GetOperator:Int()

Description: Gets the current compositing operator for the cairo context.

Information: See SetOperator for details of returnable values. returns : the current compositing operator.

GetSource

Method GetSource:TCairoPattern()

Description: Gets the current source pattern for the context.

Returns: The current source pattern. This object is owned by cairo. To keep a reference to it, you must call pattern.Reference()

GetTarget

Method GetTarget:TCairoSurface()

Description: Gets the target surface for the cairo context as passed to Create.

Returns: The target surface. This object is owned by cairo. To keep a reference to it, you must call cairosurface.Reference()

Information: This function will always return a valid object, but the result can be a "nil" surface if the context is already in an error state, (i.e. cairo.Status() CAIRO_STATUS_SUCCESS). A nil surface is indicated by cairosurface.Status() CAIRO_STATUS_SUCCESS.

GetTolerance

Method GetTolerance:Double()

Description: Gets the current tolerance value, as set by SetTolerance. returns : the current tolerance value.

IdentityMatrix

Method IdentityMatrix()

Description: Resets the current transformation matrix by setting it equal to the identity matrix.

Information: That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit.

InFill

Method InFill:Int(X:Double, Y:Double)

Description: Tests whether the given point is inside the area that would be filled by doing a Fill operation given the current path and filling parameters.

Returns: A non-zero value if the point is inside, or zero if outside.

Information: See Fill, SetFillRule and FillPreserve.

Parameters:

x : X coordinate of the point to test
y : Y coordinate of the point to test

InStroke

Method InStroke:Int(X:Double, Y:Double)

Description: Tests whether the given point is inside the area that would be stroked by doing a Stroke operation given the current path and stroking parameters.

Returns: A non-zero value if the point is inside, or zero if outside.

Information: See Stroke, SetLineWidth, SetLineJoin, SetLineCap, SetDash, and StrokePreserve.

Parameters:

x : X coordinate of the point to test
y : Y coordinate of the point to test

LineTo

Method LineTo(x:Double, y:Double)

Description: Adds a line to the path from the current point to position (x, y) in user-space coordinates.

Information: After this call the current point will be (x, y).

Parameters:

x : the X coordinate of the end of the new line
y : the Y coordinate of the end of the new line

Mask

Method Mask(pattern:TCairoPattern)

Description: A drawing operator that paints the current source using the alpha channel of pattern as a mask.

Information: Opaque areas of mask are painted with the source, transparent areas are not painted.

Parameters:

pattern : a TCairoPattern

MaskSurface

Method MaskSurface(surface:TCairoSurface, SurfaceX:Double, SurfaceY:Double)

Description: A drawing operator that paints the current source using the alpha channel of surface as a mask.

Information: Opaque areas of surface are painted with the source, transparent areas are not painted.

Parameters:

surface : a TCairoSurface
surface_x : X coordinate at which to place the origin of surface
surface_y : Y coordinate at which to place the origin of surface

MoveTo

Method MoveTo(x:Double, y:Double)

Description: If the current subpath is not empty, begin a new subpath.

Information: After this call the current point will be (x, y).

Parameters:

x : the X coordinate of the new position
y : the Y coordinate of the new position

NewPath

Method NewPath()

Description: Clears the current path.

Information: After this call there will be no current point.

NewSubPath

Method NewSubPath()

Description: Begin a new sub-path.

Information: 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 MoveTo. A call to NewSubPath 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 MoveTo.

Paint

Method Paint()

Description: A drawing operator that paints the current source everywhere within the current clip region.

PaintWithAlpha

Method PaintWithAlpha(alpha:Double)

Description: A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha.

Information: The effect is similar to Paint, but the drawing is faded out using the alpha value.

Parameters:

alpha : alpha value, between 0 (transparent) and 1 (opaque)

PopGroup

Method PopGroup:TCairoPattern()

Description: Terminates the redirection begun by a call to PushGroup or PushGroupWithContent and returns a new pattern containing the results of all drawing operations performed to the group.

Returns: A newly created (surface) pattern containing the results of all drawing operations performed to the group. The TCairoPattern should be destroyed when finished with.

Information: The PopGroup method calls Restore, (balancing a call to Save by the PushGroup method), so that any changes to the graphics state will not be visible outside the group.

PopGroupToSource

Method PopGroupToSource()

Description: Terminates the redirection begun by a call to PushGroup or PushGroupWithContent and installs the resulting pattern as the source pattern in the cairo context.

Information: The behavior of this function is equivalent to the sequence of operations:

local group:TCairoPattern = cairo.PopGroup()
cairo.SetSource(group)
group.Destroy()

but is more convenient as there is no need for a variable to store the short-lived pointer to the pattern. The PopGroup method calls Restore, (balancing a call to Save by the PushGroup method), so that any changes to the graphics state will not be visible outside the group.

PushGroup

Method PushGroup()

Description: Temporarily redirects drawing to an intermediate surface known as a group.

Information: The redirection lasts until the group is completed by a call to PopGroup or PopGroupToSource. 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 PushGroup / PopGroup. Each call pushes/pops the new target group onto/from a stack. The PushGroup 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_ALPHA. Other content types can be chosen for the group by using PushGroupWithContent 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:

cairo.PushGroup()
cairo.SetSource(fill_pattern)
cairo.FillPreserve()
cairo.SetSource(stroke_pattern)
cairo.Stroke()
cairo.PopGroupToSource()
cairo.PaintWithAlpha(alpha)

PushGroupWithContent

Method PushGroupWithContent(content:Int)

Description: Temporarily redirects drawing to an intermediate surface known as a group.

Information: The redirection lasts until the group is completed by a call to PopGroup or PopGroupToSource. 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 (see below). The ability to control this content type is the only distinction between this function and PushGroup which you should see for a more detailed description of group rendering.

Constant	Meaning
CAIRO_CONTENT_COLOR	The surface will hold color content only
CAIRO_CONTENT_ALPHA	The surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHA	The surface will hold color and alpha content

Rectangle

Method Rectangle(x:Double, y:Double, width:Double, height:Double)

Description: Adds a closed-subpath rectangle of the given size to the current path at position (x, y) in user-space coordinates.

Information: This function is logically equivalent to:

MoveTo(x, y)
RelLineTo(width, 0)
RelLineTo(0, height)
RelLineTo(-width, 0)
Close_path()

Parameters:

x : the X coordinate of the top left corner of the rectangle
y : the Y coordinate of the top left corner of the rectangle
width : the width of the rectangle
height : the height of the rectangle

Reference

Method Reference()

Description: Increases the reference count on the context by one.

Information: This prevents the context from being destroyed until a matching call to Destroy is made.

RelCurveTo

Method RelCurveTo(dx1:Double,dy1:Double, dx2:Double,dy2:Double, dx3:Double,dy3:Double)

Description: Relative-coordinate version of CurveTo.

Information: 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), RelCurveTo(dx1, dy1, dx2, dy2, dx3, dy3) is logically equivalent to CurveTo(x + dx1, y + dy1, x + dx2, y + dy2, x + dx3, y + dy3).

Parameters:

dx1 : the X offset to the first control point
dy1 : the Y offset to the first control point
dx2 : the X offset to the second control point
dy2 : the Y offset to the second control point
dx3 : the X offset to the end of the curve
dy3 : the Y offset to the end of the curve

RelLineTo

Method RelLineTo(dx:Double, dy:Double)

Description: Relative-coordinate version of LineTo.

Information: 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), RelLineTo(dx, dy) is logically equivalent to LineTo (x + dx, y + dy)

Parameters:

dx : the X offset to the end of the new line
dy : the Y offset to the end of the new line

RelMoveTo

Method RelMoveTo(dx:Double, dy:Double)

Description: If the current subpath is not empty, begin a new subpath.

Information: After this call the current point will offset by (dx, dy). Given a current point of (x, y), RelMoveTo(dx, dy) is logically equivalent to MoveTo(x + dx, y + dy).

Parameters:

dx : the X offset
dy : the Y offset

ResetClip

Method ResetClip()

Description: Reset the current clip region to its original, unrestricted state.

Information: 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 ResetClip as it will cause results unexpected by higher-level code which calls Clip. Consider using Save and Rrestore around Clip as a more robust means of temporarily restricting the clip region.

Restore

Method Restore()

Description: Restores the state saved by a preceding call to Save and removes that state from the stack of saved states.

Rotate

Method Rotate(angle:Double)

Description: Modifies the current transformation matrix by rotating the user-space axes by angle degrees.

Information: 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.

Parameters:

angle : angle (in degrees) by which the user-space axes will be rotated

Save

Method Save()

Description: Makes a copy of the current state and saves it on an internal stack of saved states.

Information: When Restore is called, it will be restored to the saved state. Multiple calls to Save and Restore can be nested; each call to Restore restores the state from the matching paired Save.
It isn't necessary to clear all saved states before an object is freed. If the reference count of a object drops to zero in response to a call to Destroy, any saved states will be freed along with the object.

Scale

Method Scale(sx:Double, sy:Double)

Description: Modifies the current transformation matrix by scaling the X and Y user-space axes.

Information: The scaling of the axes takes place after any existing transformation of user space.

Parameters:

sx : scale factor for the X dimension
sy : scale factor for the Y dimension

SelectFontFace

Method SelectFontFace( family:String, slant:Int, weight:Int)

Description: Selects a family and style of font from a simplified description as a family name, slant and weight.

Information: This function is meant to be used only for applications with simple font needs: Cairo doesn't provide for operations such as listing all available fonts on the system, and it is expected that most applications will need to use a more comprehensive font handling and text layout library in addition to cairo.

Parameters:

family : a font family name
slant : the slant for the font
weight : the weight for the font

SetAntialias

Method SetAntialias(aa:Int)

Description: Set the antialiasing mode of the rasterizer used for drawing shapes.

Information: 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 TCairoFontOptions.SetAntiAlias().

Possible Antialias values :

Constant	Meaning
CAIRO_ANTIALIAS_DEFAULT	Use the default antialiasing for the subsystem and target device
CAIRO_ANTIALIAS_NONE	Use a bilevel alpha mask
CAIRO_ANTIALIAS_GRAY	Perform single-color antialiasing (using shades of gray for black text on a white background, for example).
CAIRO_ANTIALIAS_SUBPIXEL	Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels

Parameters:

antialias : the new antialiasing mode

SetDash

Method SetDash(dashes:Double[], offset:Double = 0)

Description: Sets the dash pattern to be used by Stroke.

Information: A dash pattern is specified by dashes, an array of positive values. Each value provides the user-space 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 SetDash If num_dashes is 0 dashing is disabled. If num_dashes is 1 a 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 object will be put into an error state with a status of CAIRO_STATUS_INVALID_DASH.

Parameters:

dashes : an array specifying alternate lengths of on and off
offset : an offset into the dash pattern at which the stroke should start (optional)

SetFillRule

Method SetFillRule(rule:Int)

Description: Set the current fill rule within the cairo context.

Information: 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.

The following details the semantics of each available fill rule :

Constant	Meaning
CAIRO_FILL_RULE_WINDING	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.
CAIRO_FILL_RULE_EVEN_ODD	Counts the total number of intersections, without regard to the orientation of the contour. If the total number of intersections is odd, the point will be filled.

For both fill rules, whether or not a point is included in the fill is determined by taking a ray from that point to infinity and looking at intersections with the path. The ray can be in any direction, as long as it doesn't pass through the end point of a segment or have a tricky intersection such as intersecting tangent to the path. (Note that filling is not actually implemented in this way. This is just a description of the rule that is applied.)

Parameters:

fill_rule : a fill rule, specified as above

SetFontFace

Method SetFontFace(face:TCairoFontFace)

Description: Set the current font face within the cairo context.

Information: Parameters:

face : a TCairoFontFace object.

SetFontMatrix

Method SetFontMatrix(matrix:TCairoMatrix)

Description: Set the current font matrix within the cairo context.

Information: Parameters:

matrix : a TCairoMatrix object.

SetFontOptions

Method SetFontOptions(options:TCairoFontOptions)

Description: Set the current font options within the cairo context.

Information: Parameters:

options : a TCairoFontOptions object.

SetFontSize

Method SetFontSize(size:Double)

Description: Sets the current font size.

Information: Parameters:

size : the new font size to set.

SetLineCap

Method SetLineCap(cap:Int)

Description: Sets the current line cap style within the cairo context.

Information: As with the other stroke parameters, the current line cap style is examined by Stroke, StrokeExtents, and StrokeToPath, but does not have any effect during path construction.

The following details how the available line cap styles are drawn :

Constant	Meaning
CAIRO_LINE_CAP_BUTT	start(stop) the line exactly at the start(end) point
CAIRO_LINE_CAP_ROUND	use a round ending, the center of the circle is the end point
CAIRO_LINE_CAP_SQUARE	use squared ending, the center of the square is the end point

Parameters:

cap : a line cap style, specified as above

SetLineJoin

Method SetLineJoin(join:Int)

Description: Sets the current line join style within the cairo context.

Information: As with the other stroke parameters, the current line join style is examined by Stroke, StrokeExtents, and StrokeToPath, but does not have any effect during path construction.

The following details how the available line join styles are drawn :

Constant	Meaning
CAIRO_LINE_JOIN_MITER
CAIRO_LINE_JOIN_ROUND
CAIRO_LINE_JOIN_BEVEL

Parameters:

join : a line join style, specified as above

SetLineWidth

Method SetLineWidth(width:Double)

Description: Sets the current line width within the cairo context.

Information: The line width specifies the diameter of a pen that is circular in user-space.
As with the other stroke parameters, the current line cap style is examined by Stroke, StrokeExtents, and StrokeToPath(), but does not have any effect during path construction.

Parameters:

width : a line width, as a user-space value

SetMatrix

Method SetMatrix(matrix:TCairoMatrix)

Description: Modifies the current transformation matrix by setting it equal to matrix.

Information: Parameters:

matrix : a transformation matrix from user space to device space

SetMiterLimit

Method SetMiterLimit(limit:Double)

Description: Sets the current miter limit within the cairo context.

Information: Parameters:

limit : the limit to set

SetOperator

Method SetOperator(operator:Int)

Description: Sets the compositing operator to be used for all drawing operations.

Information: The following details the semantics of each available compositing operator :

Constant	Meaning
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_DEST_IN
CAIRO_OPERATOR_DEST_OUT
CAIRO_OPERATOR_DEST_ATOP
CAIRO_OPERATOR_XOR
CAIRO_OPERATOR_ADD
CAIRO_OPERATOR_SATURATE

Parameters:

operator : a compositing operator, specified as above

SetScaledFont

Method SetScaledFont(scaledFont:TCairoScaledFont)

Description: Replaces the current font face, font matrix, and font options in the context with those of the TCairoScaledFont object.

Information: Except for some translation, the current CTM of the context should be the same as that of the TCairoScaledFont, which can be accessed using the scaled font GetCTM() method.

SetSource

Method SetSource(pattern:TCairoPattern)

Description: Sets the source pattern to source.

Information: 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 SetSource. This means that further modifications of the current transformation matrix will not affect the source pattern.

Parameters:

source : a TCairoPattern to be used as the source for subsequent drawing operations.

SetSourceRGB

Method SetSourceRGB(r:Double, g:Double, b:Double)

Description: Sets the source pattern to an opaque color.

Information: 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 1. If the values passed in are outside that range, they will be clamped.

Parameters:

r : red component of color
g : blue component of color
b : green component of color

SetSourceRGBA

Method SetSourceRGBA(r:Double, g:Double, b:Double, a:Double)

Description: Sets the source pattern to a translucent color.

Information: 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.

Parameters:

r : red component of color
g : blue component of color
b : green component of color
a : alpha component of color

SetSourceSurface

Method SetSourceSurface(surface:TCairoSurface, x:Double,y:Double)

Description: This is a convenience function for creating a pattern from surface and setting it as the source with SetSource

Information: 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 TCairoPattern.CreateForSurface(). The resulting pattern can be queried with GetSource so that these attributes can be modified if desired, (e.g. to create a repeating pattern with TCairoPattern.SetExtend()).

Parameters:

surface : a surface to be used to set the source pattern
x : User-space X coordinate for surface origin
y : User-space Y coordinate for surface origin

SetTolerance

Method SetTolerance(tolerance:Double)

Description: Sets the tolerance used when converting paths into trapezoids.

Information: 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.)

Parameters:

tolerance : the tolerance, in device units (typically pixels)

ShowPage

Method ShowPage()

Description: Completes any required drawing operations for a Page.

Information: Not all surfaces support this, therefore nothing may actually happen.

ShowText

Method ShowText(text:String)

Description: A drawing operator that generates the shape from a string of characters, rendered according to the current font face, font size (font matrix), and font options.

Information: This method 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 ShowText.

Parameters:

text : a string of text

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this context.

Returns: the current status of this context.

Information: Possible values returned are :

Constant	Meaning
CAIRO_STATUS_SUCCESS	no error has occurred
CAIRO_STATUS_NO_MEMORY	out of memory
CAIRO_STATUS_INVALID_RESTORE	#Restore without matching Save
CAIRO_STATUS_INVALID_POP_GROUP	no saved group to pop
CAIRO_STATUS_NO_CURRENT_POINT	no current point defined
CAIRO_STATUS_INVALID_MATRIX	invalid matrix (not invertible)
CAIRO_STATUS_INVALID_STATUS	invalid value for an input status
CAIRO_STATUS_NULL_POINTER	NULL pointer
CAIRO_STATUS_INVALID_STRING	input string not valid UTF-8
CAIRO_STATUS_INVALID_PATH_DATA	input path data not valid
CAIRO_STATUS_READ_ERROR	error while reading from input stream
CAIRO_STATUS_WRITE_ERROR	error while writing to output stream
CAIRO_STATUS_SURFACE_FINISHED	target surface has been finished
CAIRO_STATUS_SURFACE_TYPE_MISMATCH	the surface type is not appropriate for the operation
CAIRO_STATUS_PATTERN_TYPE_MISMATCH	the pattern type is not appropriate for the operation
CAIRO_STATUS_INVALID_CONTENT	invalid value for an input content
CAIRO_STATUS_INVALID_FORMAT	invalid value for an input format
CAIRO_STATUS_INVALID_VISUAL	invalid value for an input Visual
CAIRO_STATUS_FILE_NOT_FOUND	file not found
CAIRO_STATUS_INVALID_DASH	invalid value for a dash setting

Stroke

Method Stroke()

Description: A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.

Information: After Stroke, the current path will be cleared from the cairo context. See SetLineWidth, SetLineJoin, SetLineCap, SetDash, and StrokePreserve.
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 SetDash. 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 MoveTo followed by either a ClosePath or one or more

calls to LineTo to the same coordinate as the MoveTo. 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.

StrokeExtents

Method StrokeExtents(x1:Double Var,y1:Double Var, x2:Double Var,y2:Double Var)

Description: Get the extents for the current stroke.

StrokePreserve

Method StrokePreserve()

Description: A drawing operator that strokes the current path according to the current line width, line join, line cap, and dash settings.

Information: Unlike Stroke, StrokePreserve preserves the path within the cairo context.

TextExtents

Method TextExtents:TCairoTextExtents(text:String)

Description: Gets the extents for a string of text.

Returns: A TCairoTextExtents object into which the results will be stored.

Information: The extents describe a user-space rectangle that encloses the "inked" portion of the text, (as it would be drawn by ShowText). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by ShowText.
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.

Parameters:

text : a string of text.

TextPath

Method TextPath(text:String)

Description: A drawing operator that generates the outline from a string of characters, rendered according to the current font face, font size (font matrix), and font options.

Information: See ShowText for more information.

Parameters:

text : a string of text.

Transform

Method Transform(matrix:TCairoMatrix)

Description: Modifies the current transformation matrix by applying matrix as an additional transformation.

Information: The new transformation of user space takes place after any existing transformation.

Parameters:

matrix : a transformation to be applied to the user-space axes

Translate

Method Translate(tx:Double, ty:Double)

Description: Modifies the current transformation matrix.

Information: By translating the user-space origin by (tx, ty). This offset is interpreted as a user-space coordinate according to the current transformation matrix in place before the new call to Translate. In other words, the translation of the user-space origin takes place after any existing transformation.

Parameters:

tx : amount to translate in the X direction
ty : amount to translate in the Y direction

UserToDevice

Method UserToDevice(x:Double Var, y:Double Var)

Description: Transform a coordinate from user space to device space by multiplying the given point by the current transformation matrix.

Information: Parameters:

x : X value of coordinate (in/out parameter)
y : Y value of coordinate (in/out parameter)

UserToDeviceDistance

Method UserToDeviceDistance(dx:Double Var,dy:Double Var)

Description: Transform a distance vector from user space to device space.

Information: This function is similar to UserToDevice except that the translation components of the current transformation matrix will be ignored when transforming (dx,dy).

Parameters:

dx : X component of a distance vector (in/out parameter)
dy : Y component of a distance vector (in/out parameter)

TCairo: Functions

Create

Function Create:TCairo(surf:TCairoSurface)

Description: Create a new TCairo object using the provided surface.

Returns: A new TCairo object.

Information: Parameters:

surf : a TCairoSurface object.

StatusToString

Function StatusToString:String(s:Int)

Description: Provides a human-readable description of the status value.

Returns: A string representation of the status.

Information: See Status for a list of valid status values to pass into this method.

Parameters:

s : a cairo status.

Version

Function Version:Int()

Description: Returns the version of the cairo library encoded in a single integer.

Returns: The encoded version.

VersionString

Function VersionString:String()

Description: Returns the version of the cairo library as a human-readable string of the form "X.Y.Z".

Returns: A string containing the version.

TCairoSurface

A TCairoSurface represents an image either as the destination of a drawing operation or as source when drawing onto another surface.

You should use one of the following sub-types which define the different drawing backends :

TCairoImageSurface - draws to an in-memory image.
TCairoPDFSurface - creates a PDF representation of the image(s).
TCairoPSSurface - creates a Postscript representation of the image(s).

Methods

Destroy
Finish
Flush
GetContent
GetDeviceOffset
GetType
MarkDirty
MarkDirtyRectangle
Reference
SetDeviceOffset
SetFallbackResolution
Status
WriteToPNG

Functions

CreateSimilar

TCairoSurface: Methods

Destroy

Method Destroy()

Description: Decreases the reference count on surface by one.

Information: If the result is zero, then surface and all associated resources are freed. See Reference.

Finish

Method Finish()

Description: This function finishes the surface and drops all references to external resources.

Information: After calling Finish the only valid operations on a surface are getting and setting user data and referencing and destroying it. Further drawing to the surface will not affect the surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED error.
When the last call to Destroy decreases the reference count to zero, cairo will call Finish if it hasn't been called already, before freeing the resources associated with the surface.

Flush

Method Flush()

Description: Do any pending drawing for the surface and also restore any temporary modification's cairo has made to the surface's state.

Information: This function must be called before switching from drawing on the surface with cairo to drawing on it directly with native APIs. If the surface doesn't support direct access, then this function does nothing.

GetContent

Method GetContent:Int()

Description: Returns the content type of surface which indicates whether the surface contains color and/or alpha information.

Returns: The content type.

Information: Content types are :

Constant	Meaning
CAIRO_CONTENT_COLOR	The surface will hold color content only
CAIRO_CONTENT_ALPHA	The surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHA	The surface will hold color and alpha content

GetDeviceOffset

Method GetDeviceOffset(xOffset:Double Var, yOffset:Double Var)

Description: This method returns the previous device offset set by SetDeviceOffset.

Information: Parameters:

xOffset : the offset in the X direction, in device units. An in/out parameter.
yOffset : the offset in the Y direction, in device units. An in/out parameter.

GetType

Method GetType:Int()

Description: This function returns the type of the backend used to create the surface.

Returns: The type of surface.

Information: The list of possible surfaces are :

Constant	Meaning
CAIRO_SURFACE_TYPE_IMAGE	The surface is of type image
CAIRO_SURFACE_TYPE_PDF	The surface is of type pdf
CAIRO_SURFACE_TYPE_PS	The surface is of type ps
CAIRO_SURFACE_TYPE_XLIB	The surface is of type xlib
CAIRO_SURFACE_TYPE_XCB	The surface is of type xcb
CAIRO_SURFACE_TYPE_GLITZ	The surface is of type glitz
CAIRO_SURFACE_TYPE_QUARTZ	The surface is of type quartz
CAIRO_SURFACE_TYPE_WIN32	The surface is of type win32
CAIRO_SURFACE_TYPE_BEOS	The surface is of type beos
CAIRO_SURFACE_TYPE_DIRECTFB	The surface is of type directfb
CAIRO_SURFACE_TYPE_SVG	The surface is of type svg

MarkDirty

Method MarkDirty()

Description: Tells cairo that drawing has been done to surface using means other than cairo, and that cairo should reread any cached areas.

Information: Note that you must call Flush before doing such drawing.

MarkDirtyRectangle

Method MarkDirtyRectangle(X:Int, Y:Int, Width:Int, Height:Int)

Description: Like MarkDirty, but drawing has been done only to the specified rectangle, so that cairo can retain cached contents for other parts of the surface.

Information: Parameters:

x : X coordinate of dirty rectangle
y : Y coordinate of dirty rectangle
width : width of dirty rectangle
height : height of dirty rectangle

Reference

Method Reference()

Description: Increases the reference count on surface by one.

Information: This prevents surface from being destroyed until a matching call to Destroy is made.

SetDeviceOffset

Method SetDeviceOffset(xOffset:Double, yOffset:Double)

Description: Sets an offset that is added to the device coordinates determined by the CTM when drawing to surface.

Information: One use case for this function is when we want to create a TCairoSurface that redirects drawing for a portion of an onscreen surface to an offscreen surface in a way that is completely invisible to the user of the cairo API. Setting a transformation via Translate isn't sufficient to do this, since functions like DeviceToUser will expose the hidden offset.
Note that the offset only affects drawing to the surface, not using the surface in a surface pattern.

Parameters:

xOffset : the offset in the X direction, in device units
yOffset : the offset in the Y direction, in device units

SetFallbackResolution

Method SetFallbackResolution(xPixelsPerInch:Double, yPixelsPerInch:Double)

Description: Set the horizontal and vertical resolution for image fallbacks.

Information: When certain operations aren't supported natively by a backend, cairo will fallback by rendering operations to an image and then overlaying that image onto the output. For backends that are natively vector-oriented, this method can be used to set the resolution used for these image fallbacks, (larger values will result in more detailed images, but also larger file sizes). Some examples of natively vector-oriented backends are the ps, pdf, and svg backends. For backends that are natively raster-oriented, image fallbacks are still possible, but they are always performed at the native device resolution. So this function has no effect on those backends. NOTE: The fallback resolution only takes effect at the time of completing a page (with ShowPage or CopyPage ) so there is currently no way to have more than one fallback resolution in effect on a single page.

Parameters:

xPixelsPerInch : horizontal setting for pixels per inch
yPixelsPerInch : vertical setting for pixels per inch

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this surface.

Returns: CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NULL_POINTER, CAIRO_STATUS_NO_MEMORY, CAIRO_STATUS_READ_ERROR, CAIRO_STATUS_INVALID_CONTENT, CAIRO_STATUS_INVALUE_FORMAT, or CAIRO_STATUS_INVALID_VISUAL.

WriteToPNG

Method WriteToPNG:Int(filename:String)

Description: Writes the contents of the surface to a new file filename as a PNG image.

Returns: CAIRO_STATUS_SUCCESS if the PNG file was written successfully. Otherwise, CAIRO_STATUS_NO_MEMORY if memory could not be allocated for the operation or 'CAIRO_STATUS_SURFACE_TYPE_MISMATCH if the surface does not have pixel contents, or CAIRO_STATUS_WRITE_ERROR if an I/O error occurs while attempting to write the file.

Information: Parameters:

filename : the name of a file to write to

TCairoSurface: Functions

CreateSimilar

Function CreateSimilar:TCairoSurface(otherSurface:TCairoSurface, content:Int, width:Int, height:Int)

Description: Create a new surface that is as compatible as possible with an existing surface.

Returns: A new TCairoSurface

Information: The new surface will use the same backend as other unless that is not possible for some reason.

Surface content is defined as one of the following options :

Constant	Meaning
CAIRO_CONTENT_COLOR	The surface will hold color content only
CAIRO_CONTENT_ALPHA	The surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHA	The surface will hold color and alpha content

Parameters:

otherSurface : an existing surface used to select the backend of the new surface
content : the content for the new surface. See above for values.
width : width of the new surface, (in device-space units)
height : height of the new surface (in device-space units)

TCairoPDFSurface

A TCairoSurface for rendering PDF documents.

Methods

SetSize

Functions

CreateForPDF

TCairoPDFSurface: Methods

SetSize

Method SetSize(width:Double, height:Double)

Description: Changes the size of a PDF surface for the current (and subsequent) pages.

Information: This method should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either ShowPage or CopyPage.

Parameters:

width : new surface width, in points (1 point == 1/72.0 inch)
height : new surface height, in points (1 point == 1/72.0 inch)

TCairoPDFSurface: Functions

CreateForPDF

Function CreateForPDF:TCairoPDFSurface(filename:String, width:Double, height:Double)

Description: Creates an PDF surface for the specified filename (which will be created) and dimensions.

Returns: The newly created surface.

Information: Parameters:

filename : the name of the PDF file to create.
width : width of the surface, in points. (1 point == 1/72.0 inch)
height : height of the surface, in points. (1 point == 1/72.0 inch)

TCairoPSSurface

A TCairoSurface for rendering Postscript documents.

Methods

SetSize

Functions

CreateForPS

TCairoPSSurface: Methods

SetSize

Method SetSize(width:Double, height:Double)

Description: Changes the size of a PostScript surface for the current (and subsequent) pages.

Information: This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either ShowPage or CopyPage.

Parameters:

width : new surface width, in points (1 point == 1/72.0 inch)
height : new surface height, in points (1 point == 1/72.0 inch)

TCairoPSSurface: Functions

CreateForPS

Function CreateForPS:TCairoPSSurface(filename:String, width:Double, height:Double)

Description: Creates an Postscript surface for the specified filename (which will be created) and dimensions.

Returns: The newly created surface.

Information: Parameters:

filename : the name of the postscript file to create.
width : width of the surface, in pixels.
height : height of the surface, in pixels.

TCairoImageSurface

Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code

Methods

Pixmap
GetData
getFormat
GetHeight
GetStride
GetWidth

Functions

Create
CreateFromPNG
CreateForPixmap
CreateFromImage
CreateFromPixmap

TCairoImageSurface: Methods

Pixmap

Method Pixmap:TPixmap()

Description: Returns the pixmap instance, if one exists.

GetData

Method GetData:Byte Ptr()

Description: Get a pointer to the data of the image surface, for direct inspection or modification.

Returns: A pointer to the image data of this surface or Null if surface is not an image surface.

getFormat

Method getFormat:Int()

Description: Get the format of the surface.

Returns: The format of the surface.

Information: See TCairoImageSurface for list of formats.

GetHeight

Method GetHeight:Int()

Description: Get the height of the image surface in pixels.

Returns: The height of the surface in pixels.

GetStride

Method GetStride:Int()

Description: Get the stride of the image surface in bytes.

Returns: The stride of the image surface in bytes (or 0 if surface is not an image surface).

Information: The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row.

GetWidth

Method GetWidth:Int()

Description: Get the width of the image surface in pixels.

Returns: The width of the surface in pixels.

TCairoImageSurface: Functions

Create

Function Create:TCairoImageSurface(width:Int, height:Int, format:Int)

Description: Creates an image surface of the specified format and dimensions.

Returns: The newly created surface. The caller owns the surface and should call Destroy when done with it. This function always returns a valid surface, but it will return a "nil" surface if an error such as out of memory occurs. You can use Status to check for this.

Information: The initial contents of the surface is undefined; you must explicitly clear the buffer, using, for example, Rectangle and Fill if you want it cleared.

The list of available formats are as follows:

Constant	Meaning
CAIRO_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.)
CAIRO_FORMAT_RGB24	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.
CAIRO_FORMAT_A8	each pixel is a 8-bit quantity holding an alpha value.
CAIRO_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 endianness 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.

Parameters:

width : width of the surface, in pixels.
height : height of the surface, in pixels.
format : format of pixels in the surface to create. See above for possible formats.

CreateFromPNG

Function CreateFromPNG:TCairoImageSurface(pngfilename:String)

Description: Creates an image surface from the specified png file.

Returns: The newly created surface.

Information: Parameters:

pngfilename : the name of the PNG file.

CreateForPixmap

Function CreateForPixmap:TCairoImageSurface(width:Int, height:Int, format:Int=PF_BGRA8888, align:Int=4)

Description: Creates an image surface from a new pixmap of the specified format and dimensions.

Returns: The newly created surface.

Information: Note - The parameters format and align are deprecated. They are no longer used.
The Pixmap format is now hard-coded to PF_BGRA8888 on LittleEndian (x86) platforms, and PF_ARGB8888 on BigEndian (PPC) platforms.

CreateFromImage

Function CreateFromImage:TCairoImageSurface(image:TImage)

Description: Creates an image surface from an existing TImage object.

Returns: The newly created surface.

Information: The image should be defined as a DYNAMICIMAGE.
Since BlitzMax internally caches the image data, the image should be locked (see LockImage ) before performing any cairo manipulation on the surface.
CreateFromImage performs an image lock during creation of the cairo surface, which will allow you to manipulate the image in cairo before the first DrawImage. After that, LockImage is required.
See arc_image and clock_image examples. Note - The image pixmap is set to the correct format before use. If the image doesn't have an internal pixmap, one is created for it.
On LittleEndian (x86), the format is PF_BGRA8888.
On BigEndian (PPC), the format is PF_ARGB8888.

CreateFromPixmap

Function CreateFromPixmap:TCairoImageSurface(_pixmap:TPixmap)

Description: Creates an image surface from the provided pixmap.

Returns: The newly created surface.

Information: Parameters:

pixmap : an existing pixmap object.

Note - If the pixmap is not of the format PF_BGRA8888 (x86) or PF_ARGB8888 (PPC), it is converted automatically.

TCairoPattern

Gradients and filtered sources.

Methods

AddColorStopRGB
AddColorStopRGBA
Destroy
GetExtend
GetFilter
GetType
Reference
SetExtend
SetFilter
SetMatrix
Status

Functions

CreateForSurface
CreateLinear
CreateRadial
CreateRGB
CreateRGBA

TCairoPattern: Methods

AddColorStopRGB

Method AddColorStopRGB(offset:Double, red:Double, green:Double, blue:Double)

Description: Adds an opaque color stop to a gradient pattern.

Information: 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 SetSourceRGB.
Note: If the pattern is not a gradient pattern, (e.g. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH.

Parameters:

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.

AddColorStopRGBA

Method AddColorStopRGBA(offset:Double, red:Double, green:Double, blue:Double, alpha:Double)

Description: Adds a translucent color stop to a gradient pattern.

Information: 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 SetSourceRGBA.
Note: If the pattern is not a gradient pattern, (e.g. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH.

Parameters:

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.

Destroy

Method Destroy()

Description: Decreases the reference count on pattern by one.

Information: If the result is zero, then pattern and all associated resources are freed. See Reference.

GetExtend

Method GetExtend:Int()

Description: Get the current extend mode for the pattern.

Returns: The extend mode. See SetExtend for the list of possible values.

GetFilter

Method GetFilter:Int()

Description: Get the current pattern filter.

Returns: The pattern filter. See SetFilter for the list of possible values.

GetType

Method GetType:Int()

Description: This function returns the type of the pattern.

Returns: The type of pattern.

Information: The type of a pattern is determined by the function used to create it. The CreateRGB and CreateRGBA functions create SOLID patterns. The remaining pattern create functions map to pattern types in obvious ways. Most pattern methods 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 AddColorStopRGB and AddColorStopRGBA 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.

Current patterns are:

Constant	Meaning
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

Reference

Method Reference()

Description: Increases the reference count on pattern by one.

Information: This prevents pattern from being destroyed until a matching call to Destroy is made.

SetExtend

Method SetExtend(extend:Int)

Description: Sets the pattern extend mode.

Information: The mode determines how the pattern repeats.

The following is a list of the available extend modes:

Constant	Meaning
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 (not implemented for surface patterns currently)
CAIRO_EXTEND_PAD	Pixels outside of the pattern copy the closest pixel from the source (not implemented for surface patterns currently)

Parameters:

extend : the extend mode to set. See above for details.

SetFilter

Method SetFilter(filter:Int)

Description: Set the pattern filter.

Information: The following is a list of possible filters to apply:

Constant
CAIRO_FILTER_FAST
CAIRO_FILTER_GOOD
CAIRO_FILTER_BEST
CAIRO_FILTER_NEAREST
CAIRO_FILTER_BILINEAR
CAIRO_FILTER_GAUSSIAN

Parameters:

filter : the filter to apply. See above for details.

SetMatrix

Method SetMatrix(matrix:TCairoMatrix)

Description: Sets the pattern's transformation matrix to matrix.

Information: 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:

matrix.InitScale(0.5, 0.5)
pattern.SetMatrix(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 SetSource.

Parameters:

matrix : a TCairoMatrix.

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this pattern.

Returns: CAIRO_STATUS_SUCCESS, CAIRO_STATUS_NO_MEMORY, or CAIRO_STATUS_PATTERN_TYPE_MISMATCH.

TCairoPattern: Functions

CreateForSurface

Function CreateForSurface:TCairoPattern(surface:TCairoSurface)

Description: Create a new TCairoPattern for the given surface.

Returns: A new TCairoPattern object

CreateLinear

Function CreateLinear:TCairoPattern(x0:Double, y0:Double, x1:Double, y1:Double)

Description: Create a new linear gradient cairo_pattern_t along the line defined by (x0, y0) and (x1, y1).

Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status.

Information: Before using the gradient pattern, a number of color stops should be defined using AddColorStopRGB or AddColorStopRGBA.
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 SetMatrix.

Parameters:

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.

CreateRadial

Function CreateRadial:TCairoPattern(cx0:Double,cy0:Double,radius0:Double, cx1:Double,cy1:Double,radius1:Double)

Description: Creates a new radial gradient cairo_pattern_t between the two circles defined by (x0, y0, c0) and (x1, y1, c0).

Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status.

Information: Before using the gradient pattern, a number of color stops should be defined using AddColorStopRGB or AddColorStopRGBA.
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 SetMatrix.

Parameters:

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 cirle in degrees.
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 cirle in degrees.

CreateRGB

Function CreateRGB:TCairoPattern(red:Double, green:Double, blue:Double)

Description: Creates a new TCairoPattern corresponding to an opaque color

Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status.

Information: 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.

Parameters:

red : red component of color.
green : green component of color.
blue : blue component of color.

CreateRGBA

Function CreateRGBA:TCairoPattern(red:Double, green:Double, blue:Double, alpha:Double)

Description: Creates a new cairo_pattern_t corresponding to a translucent color.

Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status.

Information: 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.

Parameters:

red : red component of color.
green : green component of color.
blue : blue component of color.
alpha : alpha component of the color.

TCairoMatrixStruct

A TCairoMatrixStruct 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

Fields

xx
yx
xy
yy
x0
y0

TCairoMatrixStruct: Fields

xx

Field xx:Double

Description: xx component of the affine transformation

yx

Field yx:Double

Description: yx component of the affine transformation

xy

Field xy:Double

Description: xy component of the affine transformation

yy

Field yy:Double

Description: yy component of the affine transformation

x0

Field x0:Double

Description: X translation component of the affine transformation

y0

Field y0:Double

Description: Y translation component of the affine transformation

TCairoMatrix

TCairoMatrix is used throughout cairo to convert between different coordinate spaces.

A TCairoMatrix holds an affine transformation, such as a scale, rotation, shear, or a combination of these.

The transformation of a point (x,y) is given by:

x_new = xx * x + xy * y + x0
y_new = yx * x + yy * y + y0

The current transformation matrix of a TCairo, represented as a TCairoMatrix, defines the transformation from user-space coordinates to device-space coordinates. See GetMatrix and SetMatrix.

You can access the specific values of the transformation through the matrix field (a TCairoMatrixStruct) of the TCairoMatrix.

Methods

Init
InitIdentity
InitRotate
InitScale
InitTranslate
Invert
Rotate
Scale
TransformDistance
TransformPoint
Translate

Functions

Create
CreateIdentity
CreateRotate
CreateScale
CreateTranslate
Multiply

TCairoMatrix: Methods

Init

Method Init(xx:Double, yx:Double, xy:Double, yy:Double, x0:Double, y0:Double)

Description: Sets matrix to be the affine transformation given by xx, yx, xy, yy, x0, y0.

Information: The transformation is given by:

x_new = xx * x + xy * y + x0
y_new = yx * x + yy * y + y0

Parameters:

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.

InitIdentity

Method InitIdentity()

Description: Modifies matrix to be an identity transformation.

InitRotate

Method InitRotate(degrees:Double)

Description: Initialized matrix to a transformation that rotates by degrees.

Information: Parameters:

degrees : angle of rotation, in degrees. The direction of rotation is defined such that positive angles

rotate in the direction from the positive X axis toward the positive Y axis. With the default axis

orientation of cairo, positive angles rotate in a clockwise direction.

InitScale

Method InitScale(sx:Double, sy:Double)

Description: Initializes matrix to a transformation that scales by sx and sy in the X and Y dimensions, respectively.

Information: Parameters:

sx : scale factor in the X direction.
sy : scale factor in the Y direction.

InitTranslate

Method InitTranslate(tx:Double, ty:Double)

Description: Initializes matrix to a transformation that translates by tx and ty in the X and Y dimensions, respectively.

Information: Parameters:

tx : amount to translate in the X direction.
ty : amount to translate in the Y direction.

Invert

Method Invert:Int()

Description: Changes matrix to be the inverse of its original value.

Returns: If matrix has an inverse, modifies matrix to be the inverse matrix and returns CAIRO_STATUS_SUCCESS. Otherwise, CAIRO_STATUS_INVALID_MATRIX.

Information: Not all transformation matrices have inverses; if the matrix collapses points together (it is degenerate), then it has no inverse and this function will fail.

Rotate

Method Rotate(degrees:Double)

Description: Applies rotation by degrees to the transformation in matrix. The effect of the new transformation is to first rotate the coordinates by degrees, then apply the original transformation to the coordinates.

Parameters:

degrees : angle of rotation, in degrees. The direction of rotation is defined such that positive angles

rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation

of cairo, positive angles rotate in a clockwise direction.

Scale

Method Scale(sx:Double, sy:Double)

Description: Applies scaling by sx, sy to the transformation in matrix.

Information: The effect of the new transformation is to first scale the coordinates by sx and sy, then apply the original transformation to the coordinates.

Parameters:

sx : scale factor in the X direction.
sy : scale factor in the Y direction.

TransformDistance

Method TransformDistance(dx:Double Var,dy:Double Var)

Description: Transforms the distance vector (dx,dy) by the matrix.

Information: This is similar to Transform except that the translation components of the transformation are ignored.

The calculation of the returned vector is as follows:

dx2 = dx1 * a + dy1 * c
dy2 = dx1 * b + dy1 * d

Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1,y1) transforms to (x2,y2) then (x1 + dx1, y1 + dy1) will transform to (x1 + dx2, y1 + dy2) for all values of x1 and x2.

Parameters:

dx : X component of a distance vector. An in/out parameter.
dy : Y component of a distance vector. An in/out parameter.

TransformPoint

Method TransformPoint(x:Double Var,y:Double Var)

Description: Transforms the point ( x, y ) by the matrix.

Information: Parameters:

x : X position. An in/out parameter.
y : X position. An in/out parameter.

Translate

Method Translate(tx:Double, ty:Double)

Description: Applies a translation by tx, ty to the transformation in matrix.

Information: The effect of the new transformation is to first translate the coordinates by tx and ty, then apply the original transformation to the coordinates.

Parameters:

tx : amount to translate in the X direction.
ty : amount to translate in the Y direction.

TCairoMatrix: Functions

Create

Function Create:TCairoMatrix(xx:Double,yx:Double, xy:Double,yy:Double, x0:Double,y0:Double)

Description: Creates a new TCairoMatrix to be the given affine transformation.

Returns: A new matrix object.

Information: See Init for more details.

CreateIdentity

Function CreateIdentity:TCairoMatrix()

Description: Creates a new TCairoMatrix as an identity transformation.

Returns: A new matrix object.

Information: See InitIdentity for more details.

CreateRotate

Function CreateRotate:TCairoMatrix(degrees:Double)

Description: Creates a new TCairoMatrix to be a transformation that rotates by degreesn.

Returns: A new matrix object.

Information: See InitRotate for more details.

CreateScale

Function CreateScale:TCairoMatrix(sx:Double, sy:Double)

Description: Creates a new TCairoMatrix to be a transformation that scales by sx and sy in the X and Y dimensions, respectively.

Returns: A new matrix object.

Information: See InitScale for more details.

CreateTranslate

Function CreateTranslate:TCairoMatrix(tx:Double, ty:Double)

Description: Creates a new TCairoMatrix to be a transformation that translates by tx and ty in the X and Y dimensions, respectively.

Returns: A new matrix object.

Information: See InitTranslate for more details.

Multiply

Function Multiply:TCairoMatrix(mat1:TCairoMatrix, mat2:TCairoMatrix)

Description: Multiplies the affine transformations in mat1 and mat2 together and stores the result in result.

Returns: The result of the multiplication of the two matrices.

Information: The effect of the resulting transformation is to first apply the transformation in a to the coordinates and then apply the transformation in b to the coordinates.
It is allowable for result to be identical to either mat1 or mat2.

Parameters:

mat1 : a TCairoMatrix.
mat2 : a TCairoMatrix.

TCairoFontFace

A TCairoFontFace 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 TCairo by using SetFontFace. The size and font matrix are set with SetFontSize and SetFontMatrix.

Methods

Destroy
GetType
Reference
Status

TCairoFontFace: Methods

Destroy

Method Destroy()

Description: Decreases the reference count on font_face by one.

Information: If the result is zero, then font_face and all associated resources are freed. See Reference.

GetType

Method GetType:Int()

Description: This function returns the type of the backend used to create a font face.

Information: The following lists the possible font types:

Constant	Meaning
CAIRO_FONT_TYPE_TOY	The font was created using cairo's toy font api
CAIRO_FONT_TYPE_FT	The font is of type FreeType
CAIRO_FONT_TYPE_WIN32	The font is of type Win32
CAIRO_FONT_TYPE_ATSUI	The font is of type ATSUI

Reference

Method Reference()

Description: Increases the reference count on font_face by one.

Information: This prevents the font face from being destroyed until a matching call to Destroy is made.

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this font face.

Returns: CAIRO_STATUS_SUCCESS or another error such as CAIRO_STATUS_NO_MEMORY.

TCairoFontOptions

How a font should be rendered.

Methods

Copy
Destroy
EqualTo
GetAntialias
GetHintMetrics
GetHintStyle
GetSubpixelOrder
Hash
Merge
SetAntialias
SetHintMetrics
SetHintStyle
SetSubpixelOrder
Status

Functions

Create

TCairoFontOptions: Methods

Copy

Method Copy:TCairoFontOptions()

Description: Allocates a new font options object copying the option values from this one.

Returns: A newly allocated TCairoFontOptions object. Free with Destroy. This function always returns a valid object; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with Status.

Destroy

Method Destroy()

Description: Destroys a TCairoFontOptions object created with Create or Copy.

EqualTo

Method EqualTo:Int(other:TCairoFontOptions)

Description: Compares two font options objects for equality.

Returns: True if all fields of the two font options objects match.

Information: Parameters:

other : another TCairoFontOptions.

GetAntialias

Method GetAntialias:Int()

Description: Gets the antialising mode for the font options object.

Returns: The antialiasing mode.

GetHintMetrics

Method GetHintMetrics:Int()

Description: Gets the metrics hinting mode for the font options object.

Returns: The metrics hinting mode for the font options object.

Information: See SetHintMetrics for more details.

GetHintStyle

Method GetHintStyle:Int()

Description: Gets the hint style for font outlines for the font options object.

Returns: The hint style for the font options object.

Information: See SetHintStyle for more information.

GetSubpixelOrder

Method GetSubpixelOrder:Int()

Description: Gets the subpixel order for the font options object.

Returns: The subpixel order for the font options object.

Information: See SetSubpixelOrder for more details.

Hash

Method Hash:Long()

Description: Compute a hash for the font options object.

Returns: The hash value for the font options object. The return value can be cast to a 32-bit type if a 32-bit hash value is needed.

Information: This value will be useful when storing an object containing a TCairoFontOptions in a hash table.

Merge

Method Merge(other:TCairoFontOptions)

Description: Merges non-default options from other into this one, replacing existing values.

Information: This operation can be thought of as somewhat similar to compositing other onto options with the operation of CAIRO_OPERATION_OVER.

Parameters:

other : another TCairoFontOptions.

SetAntialias

Method SetAntialias(aa:Int)

Description: Sets the antiliasing mode for the font options object.

Information: This specifies the type of antialiasing to do when rendering text.

Possible Antialias values :

Constant	Meaning
CAIRO_ANTIALIAS_DEFAULT	Use the default antialiasing for the subsystem and target device
CAIRO_ANTIALIAS_NONE	Use a bilevel alpha mask
CAIRO_ANTIALIAS_GRAY	Perform single-color antialiasing (using shades of gray for black text on a white background, for example).
CAIRO_ANTIALIAS_SUBPIXEL	Perform antialiasing by taking advantage of the order of subpixel elements on devices such as LCD panels

Parameters:

aa : the new antialiasing mode. See above for details.

SetHintMetrics

Method SetHintMetrics(hm:Int)

Description: Sets the metrics hinting mode for the font options object.

Information: This controls whether metrics are quantized to integer values in device units. The following describes the possible values :

Constant	Meaning
CAIRO_HINT_METRICS_DEFAULT	Hint metrics in the default manner for the font backend and target device
CAIRO_HINT_METRICS_OFF	Do not hint font metrics
CAIRO_HINT_METRICS_ON	Hint font metrics

Parameters:

hm : the new metrics hinting mode. See above for details.

SetHintStyle

Method SetHintStyle(hs:Int)

Description: Sets the hint style for font outlines for the font options object.

Information: This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast. The following describes the possible values :

Constant	Meaning
CAIRO_HINT_STYLE_DEFAULT	Use the default hint style for font backend and target device
CAIRO_HINT_STYLE_NONE	Do not hint outlines
CAIRO_HINT_STYLE_SLIGHT	Hint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
CAIRO_HINT_STYLE_MEDIUM	Hint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
CAIRO_HINT_STYLE_FULL	Hint outlines to maximize contrast

Parameters:

hs : the new hint style. See above for details.

SetSubpixelOrder

Method SetSubpixelOrder(spo:Int)

Description: Sets the subpixel order for the font options object.

Information: 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. The possible values are :

Constant	Meaning
CAIRO_SUBPIXEL_ORDER_DEFAULT	Use the default subpixel order for the target device
CAIRO_SUBPIXEL_ORDER_RGB	Subpixel elements are arranged horizontally with red at the left
CAIRO_SUBPIXEL_ORDER_BGR	Subpixel elements are arranged horizontally with blue at the left
CAIRO_SUBPIXEL_ORDER_VRGB	Subpixel elements are arranged vertically with red at the top
CAIRO_SUBPIXEL_ORDER_VBGR	Subpixel elements are arranged vertically with blue at the top

Parameters:

spo : the new subpixel order. See above for details.

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this font options object.

Returns: CAIRO_STATUS_SUCCESS or CAIRO_STATUS_NO_MEMORY

TCairoFontOptions: Functions

Create

Function Create:TCairoFontOptions()

Description: Allocates a new font options object with all options initialized to default values.

Returns: A newly allocated TCairoFontOptions object. Free with Destroy. This function always returns a valid object; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with Status.

TCairoPath

A data structure for holding a path.

This data structure serves as the return value for CopyPath and CopyPathFlat as well the input value for AppendPath.

Methods

Destroy

TCairoPath: Methods

Destroy

Method Destroy()

Description: Immediately releases all memory associated with path.

Information: After a call to Destroy the path pointer is no longer valid and should not be used further.

TCairoTextExtents

The TCairoTextExtents 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(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.

Fields

x_bearing
y_bearing
width
height
x_advance
y_advance

TCairoTextExtents: Fields

x_bearing

Field x_bearing:Double

Description: The horizontal distance from the origin to the leftmost part of the glyphs as drawn.

Information: Positive if the glyphs lie entirely to the right of the origin.

y_bearing

Field y_bearing:Double

Description: The vertical distance from the origin to the topmost part of the glyphs as drawn.

Information: Positive only if the glyphs lie completely below the origin; will usually be negative.

width

Field width:Double

Description: Width of the glyphs as drawn.

height

Field height:Double

Description: Height of the glyphs as drawn.

x_advance

Field x_advance:Double

Description: Distance to advance in the X direction after drawing these glyphs.

y_advance

Field y_advance:Double

Description: Distance to advance in the Y direction after drawing these glyphs. about; Will typically be zero except for vertical text layout as found in East-Asian languages.

TCairoScaledFont

A TCairoScaledFont is a font scaled to a particular size and device resolution.

A TCairoScaledFont 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.

Methods

Destroy
Extents
GetCTM
GetFontFace
GetFontMatrix
GetFontOptions
GetType
Reference
Status
TextExtents

Functions

Create

TCairoScaledFont: Methods

Destroy

Method Destroy()

Description: Decreases the reference count on font by one.

Information: If the result is zero, then font and all associated resources are freed. See Reference.

Extents

Method Extents:TCairoFontExtents()

Description: Gets the metrics for a TCairoScaledFont.

Returns: A TCairoFontExtents object.

GetCTM

Method GetCTM:TCairoMatrix()

Description: Returns the CTM with which the scaled font was created.

Returns: The CTM.

GetFontFace

Method GetFontFace:TCairoFontFace()

Description: Gets the font face that this scaled font was created for.

Returns: The TCairoFontFace with which the scaled font was created.

GetFontMatrix

Method GetFontMatrix:TCairoMatrix()

Description: Returns the font matrix with which the scaled font was created.

Returns: The font matrix.

GetFontOptions

Method GetFontOptions:TCairoFontOptions()

Description: Returns the font options with which the scaled font was created.

Returns: The font options.

GetType

Method GetType:Int()

Description: This method returns the type of the backend used to create a scaled font.

Returns: The type of scaled font.

Information: The following lists the possible font types:

Constant	Meaning
CAIRO_FONT_TYPE_TOY	The font was created using cairo's toy font api
CAIRO_FONT_TYPE_FT	The font is of type FreeType
CAIRO_FONT_TYPE_WIN32	The font is of type Win32
CAIRO_FONT_TYPE_ATSUI	The font is of type ATSUI

Reference

Method Reference()

Description: Increases the reference count on scaled font by one.

Information: This prevents scaled font from being destroyed until a matching call to Destroy is made.

Status

Method Status:Int()

Description: Checks whether an error has previously occurred for this scaled font.

Returns: CAIRO_STATUS_SUCCESS or another error such as CAIRO_STATUS_NO_MEMORY.

TextExtents

Method TextExtents:TCairoTextExtents(text:String)

Description: Gets the extents for a string of text.

Returns: a TCairoTextExtents object containing the retrieved extents.

Information: The extents describe a user-space rectangle that encloses the "inked" portion of the text drawn at the origin (0,0) (as it would be drawn by ShowText if the cairo graphics state were set to the same font face, font matrix, ctm, and font options as the scaled font). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by ShowText. 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.

Parameters:

text : a string of text.

TCairoScaledFont: Functions

Create

Function Create:TCairoScaledFont(font_face:TCairoFontFace, font_matrix:TCairoMatrix, ..

Description: Creates a TCairoScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.

Returns: A newly created TCairoScaledFont. Destroy with Destroy.

TCairoFontExtents

The TCairoFontExtents type 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(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.

Fields

ascent
descent
height
max_x_advance
max_y_advance

TCairoFontExtents: Fields

ascent

Field ascent:Double

Description: The distance that the font extends above the baseline.

Information: 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.

descent

Field descent:Double

Description: The distance that the font extends below the baseline.

Information: 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 font should align with elements below it.

height

Field height:Double

Description: The recommended vertical distance between baselines when setting consecutive lines of text with the font.

Information: 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.

max_x_advance

Field max_x_advance:Double

Description: The maximum distance in the X direction that the origin is advanced for any glyph in the font

max_y_advance

Field max_y_advance:Double

Description: The maximum distance in the Y direction that the origin is advanced for any glyph in the font.

Information: This will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.)

TCairoPaperDimension

Dimensions of a sheet of paper.

Fields

width
height

TCairoPaperDimension: Fields

width

Field width:Double

Description: The paper width.

height

Field height:Double

Description: The paper height.

BlitzMax/Modules/BaH/Cairo

Introduction

Examples

Globals

CAIRO_USER_FONTPATH

Types

TCairo

TCairo: Methods

TCairo: Functions

TCairoSurface

TCairoSurface: Methods

TCairoSurface: Functions

TCairoPDFSurface

TCairoPDFSurface: Methods

TCairoPDFSurface: Functions

TCairoPSSurface

TCairoPSSurface: Methods

TCairoPSSurface: Functions

TCairoImageSurface

TCairoImageSurface: Methods

TCairoImageSurface: Functions

TCairoPattern

TCairoPattern: Methods

TCairoPattern: Functions

TCairoMatrixStruct

TCairoMatrixStruct: Fields

TCairoMatrix

TCairoMatrix: Methods

TCairoMatrix: Functions

TCairoFontFace

TCairoFontFace: Methods

TCairoFontOptions

TCairoFontOptions: Methods

TCairoFontOptions: Functions

TCairoPath

TCairoPath: Methods

TCairoTextExtents

TCairoTextExtents: Fields

TCairoScaledFont

TCairoScaledFont: Methods

TCairoScaledFont: Functions

TCairoFontExtents

TCairoFontExtents: Fields

TCairoPaperDimension

TCairoPaperDimension: Fields