Jump to content

BlitzMax/Modules/BaH/Cairo

From Wikibooks, open books for an open world

Introduction

[edit | edit source]

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:

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

[edit | edit source]

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

[edit | edit source]

CAIRO_USER_FONTPATH

[edit | edit source]

Global CAIRO_USER_FONTPATH:String = "."

Description: User derived font path.

Information: Add your own here.

Types

[edit | edit source]

TCairo

[edit | edit source]

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

[edit | edit source]
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.

ConstantMeaning
CAIRO_CONTENT_COLORThe surface will hold color content only
CAIRO_CONTENT_ALPHAThe surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHAThe 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 :

ConstantMeaning
CAIRO_ANTIALIAS_DEFAULTUse the default antialiasing for the subsystem and target device
CAIRO_ANTIALIAS_NONEUse a bilevel alpha mask
CAIRO_ANTIALIAS_GRAYPerform single-color antialiasing (using shades of gray for black text on a white background, for example).
CAIRO_ANTIALIAS_SUBPIXELPerform 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 :

ConstantMeaning
CAIRO_FILL_RULE_WINDINGIf 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_ODDCounts 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:

SetFontMatrix

Method SetFontMatrix(matrix:TCairoMatrix)

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

Information: Parameters:

SetFontOptions

Method SetFontOptions(options:TCairoFontOptions)

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

Information: Parameters:

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 :

ConstantMeaning
CAIRO_LINE_CAP_BUTTstart(stop) the line exactly at the start(end) point
CAIRO_LINE_CAP_ROUNDuse a round ending, the center of the circle is the end point
CAIRO_LINE_CAP_SQUAREuse 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 :

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

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

ConstantMeaning
CAIRO_STATUS_SUCCESSno error has occurred
CAIRO_STATUS_NO_MEMORYout of memory
CAIRO_STATUS_INVALID_RESTORE#Restore without matching Save
CAIRO_STATUS_INVALID_POP_GROUPno saved group to pop
CAIRO_STATUS_NO_CURRENT_POINTno current point defined
CAIRO_STATUS_INVALID_MATRIXinvalid matrix (not invertible)
CAIRO_STATUS_INVALID_STATUSinvalid value for an input status
CAIRO_STATUS_NULL_POINTERNULL pointer
CAIRO_STATUS_INVALID_STRINGinput string not valid UTF-8
CAIRO_STATUS_INVALID_PATH_DATAinput path data not valid
CAIRO_STATUS_READ_ERRORerror while reading from input stream
CAIRO_STATUS_WRITE_ERRORerror while writing to output stream
CAIRO_STATUS_SURFACE_FINISHEDtarget surface has been finished
CAIRO_STATUS_SURFACE_TYPE_MISMATCHthe surface type is not appropriate for the operation
CAIRO_STATUS_PATTERN_TYPE_MISMATCHthe pattern type is not appropriate for the operation
CAIRO_STATUS_INVALID_CONTENTinvalid value for an input content
CAIRO_STATUS_INVALID_FORMATinvalid value for an input format
CAIRO_STATUS_INVALID_VISUALinvalid value for an input Visual
CAIRO_STATUS_FILE_NOT_FOUNDfile not found
CAIRO_STATUS_INVALID_DASHinvalid 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

[edit | edit source]
Create

Function Create:TCairo(surf:TCairoSurface)

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

Returns: A new TCairo object.

Information: Parameters:

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

[edit | edit source]

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 :

Methods
  • Destroy
  • Finish
  • Flush
  • GetContent
  • GetDeviceOffset
  • GetType
  • MarkDirty
  • MarkDirtyRectangle
  • Reference
  • SetDeviceOffset
  • SetFallbackResolution
  • Status
  • WriteToPNG
Functions
  • CreateSimilar

TCairoSurface: Methods

[edit | edit source]
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 :

ConstantMeaning
CAIRO_CONTENT_COLORThe surface will hold color content only
CAIRO_CONTENT_ALPHAThe surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHAThe 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 :

ConstantMeaning
CAIRO_SURFACE_TYPE_IMAGEThe surface is of type image
CAIRO_SURFACE_TYPE_PDFThe surface is of type pdf
CAIRO_SURFACE_TYPE_PSThe surface is of type ps
CAIRO_SURFACE_TYPE_XLIBThe surface is of type xlib
CAIRO_SURFACE_TYPE_XCBThe surface is of type xcb
CAIRO_SURFACE_TYPE_GLITZThe surface is of type glitz
CAIRO_SURFACE_TYPE_QUARTZThe surface is of type quartz
CAIRO_SURFACE_TYPE_WIN32The surface is of type win32
CAIRO_SURFACE_TYPE_BEOSThe surface is of type beos
CAIRO_SURFACE_TYPE_DIRECTFBThe surface is of type directfb
CAIRO_SURFACE_TYPE_SVGThe 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

[edit | edit source]
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 :

ConstantMeaning
CAIRO_CONTENT_COLORThe surface will hold color content only
CAIRO_CONTENT_ALPHAThe surface will hold alpha content only
CAIRO_CONTENT_COLOR_ALPHAThe 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

[edit | edit source]

A TCairoSurface for rendering PDF documents.

Methods
  • SetSize
Functions
  • CreateForPDF

TCairoPDFSurface: Methods

[edit | edit source]
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

[edit | edit source]
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

[edit | edit source]

A TCairoSurface for rendering Postscript documents.

Methods
  • SetSize
Functions
  • CreateForPS

TCairoPSSurface: Methods

[edit | edit source]
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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]
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:

ConstantMeaning
CAIRO_FORMAT_ARGB32each 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_RGB24each 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_A8each pixel is a 8-bit quantity holding an alpha value.
CAIRO_FORMAT_A1each 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

[edit | edit source]

Gradients and filtered sources.

Methods
  • AddColorStopRGB
  • AddColorStopRGBA
  • Destroy
  • GetExtend
  • GetFilter
  • GetType
  • Reference
  • SetExtend
  • SetFilter
  • SetMatrix
  • Status
Functions
  • CreateForSurface
  • CreateLinear
  • CreateRadial
  • CreateRGB
  • CreateRGBA

TCairoPattern: Methods

[edit | edit source]
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:

ConstantMeaning
CAIRO_PATTERN_TYPE_SOLIDThe pattern is a solid (uniform) color. It may be opaque or translucent
CAIRO_PATTERN_TYPE_SURFACEThe pattern is a based on a surface (an image)
CAIRO_PATTERN_TYPE_LINEARThe pattern is a linear gradient
CAIRO_PATTERN_TYPE_RADIALThe 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:

ConstantMeaning
CAIRO_EXTEND_NONEPixels outside of the source pattern are fully transparent
CAIRO_EXTEND_REPEATThe pattern is tiled by repeating
CAIRO_EXTEND_REFLECTThe pattern is tiled by reflecting at the edges (not implemented for surface patterns currently)
CAIRO_EXTEND_PADPixels 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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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:

ConstantMeaning
CAIRO_FONT_TYPE_TOYThe font was created using cairo's toy font api
CAIRO_FONT_TYPE_FTThe font is of type FreeType
CAIRO_FONT_TYPE_WIN32The font is of type Win32
CAIRO_FONT_TYPE_ATSUIThe 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

[edit | edit source]

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

[edit | edit source]
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 :

ConstantMeaning
CAIRO_ANTIALIAS_DEFAULTUse the default antialiasing for the subsystem and target device
CAIRO_ANTIALIAS_NONEUse a bilevel alpha mask
CAIRO_ANTIALIAS_GRAYPerform single-color antialiasing (using shades of gray for black text on a white background, for example).
CAIRO_ANTIALIAS_SUBPIXELPerform 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 :

ConstantMeaning
CAIRO_HINT_METRICS_DEFAULTHint metrics in the default manner for the font backend and target device
CAIRO_HINT_METRICS_OFFDo not hint font metrics
CAIRO_HINT_METRICS_ONHint 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 :

ConstantMeaning
CAIRO_HINT_STYLE_DEFAULTUse the default hint style for font backend and target device
CAIRO_HINT_STYLE_NONEDo not hint outlines
CAIRO_HINT_STYLE_SLIGHTHint outlines slightly to improve contrast while retaining good fidelity to the original shapes.
CAIRO_HINT_STYLE_MEDIUMHint outlines with medium strength giving a compromise between fidelity to the original shapes and contrast
CAIRO_HINT_STYLE_FULLHint 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 :

ConstantMeaning
CAIRO_SUBPIXEL_ORDER_DEFAULTUse the default subpixel order for the target device
CAIRO_SUBPIXEL_ORDER_RGBSubpixel elements are arranged horizontally with red at the left
CAIRO_SUBPIXEL_ORDER_BGRSubpixel elements are arranged horizontally with blue at the left
CAIRO_SUBPIXEL_ORDER_VRGBSubpixel elements are arranged vertically with red at the top
CAIRO_SUBPIXEL_ORDER_VBGRSubpixel 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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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:

ConstantMeaning
CAIRO_FONT_TYPE_TOYThe font was created using cairo's toy font api
CAIRO_FONT_TYPE_FTThe font is of type FreeType
CAIRO_FONT_TYPE_WIN32The font is of type Win32
CAIRO_FONT_TYPE_ATSUIThe 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

[edit | edit source]
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

[edit | edit source]

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

[edit | edit source]
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

[edit | edit source]

Dimensions of a sheet of paper.

Fields
  • width
  • height

TCairoPaperDimension: Fields

[edit | edit source]
width

Field width:Double

Description: The paper width.

height

Field height:Double

Description: The paper height.