BlitzMax/Modules/BaH/Cairo

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

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

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

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

There are three suface types you can currently use:
 * TCairoImageSurface - draws to an in-memory image.
 * TCairoPDFSurface - creates a PDF representation of the image(s).
 * TCairoPSSurface - creates a Postscript representation of the image(s).

To create a TCairo object for drawing onto a pixmap you could do the following : Local surface:TCairoImageSurface = TCairoImageSurface.CreateForPixmap(256,256) Local cairo:TCairo = TCairo.Create(surface)

which would create a new pixmap for the surface, and tell cairo to draw on it. Also, you could use CreateForImage, which uses an existing TImage object to draw onto : Local image:TImage = CreateImage(256, 256, 1, DYNAMICIMAGE) Local surface:TCairoImageSurface = TCairoImageSurface.CreateForImage(image) Local cairo:TCairo = TCairo.Create(surface)

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

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

In normal usage you would perform the following operations during the life of a context: CreateContext ...draw stuff on the context Destroy

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

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

Import BaH.Cairo

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

' set the line width cairo.SetLineWidth(5)

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

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

' destroy context and resources cairo.Destroy

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

Graphics 256, 256,0

SetBlend ALPHABLEND

SetClsColor 255,255,255

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

End

For information on creating Surfaces

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

=Globals=

CAIRO_USER_FONTPATH
Global CAIRO_USER_FONTPATH:String = "."

Description: User derived font path.

Information: Add your own here.

=Types=

TCairo
The Cairo context wrapper type


 * 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


 * Create
 * StatusToString
 * Version
 * VersionString

TCairo: Methods
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

Method AppendPath(p:TCairoPath)

Description: Append the path onto the current path.

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

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

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

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.

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.

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.

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.

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.

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.

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

Method Destroy

Description: Decreases the reference count by one.

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

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)

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)

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.

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

Description: Returns the extents for the current fill.

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.

Method GetAntialias:Int

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

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

Description: Returns the current point in the context.

Method GetFillRule:Int

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

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

Method GetFontMatrix:TCairoMatrix

Description: Gets the current font matrix

Returns: return value for the matrix.

Information: See TCairoMatrix for more information.

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

Method GetLineCap:Int

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

Method GetLineJoin:Int

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

Method GetLineWidth:Double

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

Method GetMiterLimit:Double

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

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.

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

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.

Method GetTolerance:Double

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

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.

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

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

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

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

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

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

Method NewPath

Description: Clears the current path.

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

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.

Method Paint

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

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)

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.

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.

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)

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.

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

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.

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

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

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

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.

Method Restore

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

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

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.

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

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

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 :

Parameters:
 * antialias : the new antialiasing mode

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)

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 :

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

Method SetFontFace(face:TCairoFontFace)

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

Information: Parameters:
 * face : a TCairoFontFace object.

Method SetFontMatrix(matrix:TCairoMatrix)

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

Information: Parameters:
 * matrix : a TCairoMatrix object.

Method SetFontOptions(options:TCairoFontOptions)

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

Information: Parameters:
 * options : a TCairoFontOptions object.

Method SetFontSize(size:Double)

Description: Sets the current font size.

Information: Parameters:
 * size : the new font size to set.

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 :

Parameters:
 * cap : a line cap style, specified as above

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 :

Parameters:
 * join : a line join style, specified as above

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

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

Method SetMiterLimit(limit:Double)

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

Information: Parameters:
 * limit : the limit to set

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 :

Parameters:
 * operator : a compositing operator, specified as above

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.

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.

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

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

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

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)

Method ShowPage

Description: Completes any required drawing operations for a Page.

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

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

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 :

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: 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. 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.
 * Zero-length &quot;on&quot; segments set in SetDash. If the cap style is CAIRO_LINE_CAP_ROUND or
 * A sub-path created by MoveTo followed by either a ClosePath or one or more

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

Description: Get the extents for the current stroke.

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.

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.

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.

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

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

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)

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
Function Create:TCairo(surf:TCairoSurface)

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

Returns: A new TCairo object.

Information: Parameters:
 * surf : a TCairoSurface object.

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.

Function Version:Int

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

Returns: The encoded version.

Function VersionString:String

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

Returns: A string containing the version.

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

You should use one of the following sub-types which define the different drawing backends :
 * TCairoImageSurface - draws to an in-memory image.
 * TCairoPDFSurface - creates a PDF representation of the image(s).
 * TCairoPSSurface - creates a Postscript representation of the image(s).


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


 * CreateSimilar

TCairoSurface: Methods
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.

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.

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.

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 :

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.

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 :

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.

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

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.

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

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

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.

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

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

TCairoPDFSurface
A TCairoSurface for rendering PDF documents.


 * SetSize


 * CreateForPDF

TCairoPDFSurface: Methods
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
Function CreateForPDF:TCairoPDFSurface(filename:String, width:Double, height:Double)

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

Returns: The newly created surface.

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

TCairoPSSurface
A TCairoSurface for rendering Postscript documents.


 * SetSize


 * CreateForPS

TCairoPSSurface: Methods
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
Function CreateForPS:TCairoPSSurface(filename:String, width:Double, height:Double)

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

Returns: The newly created surface.

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

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


 * Pixmap
 * GetData
 * getFormat
 * GetHeight
 * GetStride
 * GetWidth


 * Create
 * CreateFromPNG
 * CreateForPixmap
 * CreateFromImage
 * CreateFromPixmap

TCairoImageSurface: Methods
Method Pixmap:TPixmap

Description: Returns the pixmap instance, if one exists.

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.

Method getFormat:Int

Description: Get the format of the surface.

Returns: The format of the surface.

Information: See TCairoImageSurface for list of formats.

Method GetHeight:Int

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

Returns: The height of the surface in pixels.

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.

Method GetWidth:Int

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

Returns: The width of the surface in pixels.

TCairoImageSurface: Functions
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:

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.

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.

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.

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.

Function CreateFromPixmap:TCairoImageSurface(_pixmap:TPixmap)

Description: Creates an image surface from the provided pixmap.

Returns: The newly created surface.

Information: Parameters:
 * pixmap : an existing pixmap object.

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

TCairoPattern
Gradients and filtered sources.


 * AddColorStopRGB
 * AddColorStopRGBA
 * Destroy
 * GetExtend
 * GetFilter
 * GetType
 * Reference
 * SetExtend
 * SetFilter
 * SetMatrix
 * Status


 * CreateForSurface
 * CreateLinear
 * CreateRadial
 * CreateRGB
 * CreateRGBA

TCairoPattern: Methods
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.

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.

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.

Method GetExtend:Int

Description: Get the current extend mode for the pattern.

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

Method GetFilter:Int

Description: Get the current pattern filter.

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

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:

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.

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:

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

Method SetFilter(filter:Int)

Description: Set the pattern filter.

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

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

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.

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
Function CreateForSurface:TCairoPattern(surface:TCairoSurface)

Description: Create a new TCairoPattern for the given surface.

Returns: A new TCairoPattern object

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.

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.

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.

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

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

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

Information: The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped.

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

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

The transformation of a point (x, y) is given by: x_new = xx * x + xy * y + x0 y_new = yx * x + yy * y + y0


 * xx
 * yx
 * xy
 * yy
 * x0
 * y0

TCairoMatrixStruct: Fields
Field xx:Double

Description: xx component of the affine transformation

Field yx:Double

Description: yx component of the affine transformation

Field xy:Double

Description: xy component of the affine transformation

Field yy:Double

Description: yy component of the affine transformation

Field x0:Double

Description: X translation component of the affine transformation

Field y0:Double

Description: Y translation component of the affine transformation

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

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

The transformation of a point (x,y) is given by: x_new = xx * x + xy * y + x0 y_new = yx * x + yy * y + y0

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

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


 * Init
 * InitIdentity
 * InitRotate
 * InitScale
 * InitTranslate
 * Invert
 * Rotate
 * Scale
 * TransformDistance
 * TransformPoint
 * Translate


 * Create
 * CreateIdentity
 * CreateRotate
 * CreateScale
 * CreateTranslate
 * Multiply

TCairoMatrix: Methods
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.

Method InitIdentity

Description: Modifies matrix to be an identity transformation.

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.

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.

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.

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.

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.

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.

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.

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.

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

Function CreateIdentity:TCairoMatrix

Description: Creates a new TCairoMatrix as an identity transformation.

Returns: A new matrix object.

Information: See InitIdentity for more details.

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.

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.

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.

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

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

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

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

Parameters:
 * mat1 : a TCairoMatrix.
 * mat2 : a TCairoMatrix.

TCairoFontFace
A TCairoFontFace specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions).

A font face can be set on a TCairo by using SetFontFace. The size and font matrix are set with SetFontSize and SetFontMatrix.


 * Destroy
 * GetType
 * Reference
 * Status

TCairoFontFace: Methods
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.

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:

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.

Method Status:Int

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

Returns: CAIRO_STATUS_SUCCESS or another error such as CAIRO_STATUS_NO_MEMORY.

TCairoFontOptions
How a font should be rendered.


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


 * Create

TCairoFontOptions: Methods
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.

Method Destroy

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

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.

Method GetAntialias:Int

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

Returns: The antialiasing mode.

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.

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.

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.

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.

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.

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 :

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

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 :

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

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 :

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

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 :

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

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
Function Create:TCairoFontOptions

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

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

TCairoPath
A data structure for holding a path.

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


 * Destroy

TCairoPath: Methods
Method Destroy

Description: Immediately releases all memory associated with path.

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

TCairoTextExtents
The TCairoTextExtents structure stores the extents of a single glyph or a string of glyphs in user-space coordinates.

Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.


 * x_bearing
 * y_bearing
 * width
 * height
 * x_advance
 * y_advance

TCairoTextExtents: Fields
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.

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.

Field width:Double

Description: Width of the glyphs as drawn.

Field height:Double

Description: Height of the glyphs as drawn.

Field x_advance:Double

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

Field y_advance:Double

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

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

A TCairoScaledFont is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.


 * Destroy
 * Extents
 * GetCTM
 * GetFontFace
 * GetFontMatrix
 * GetFontOptions
 * GetType
 * Reference
 * Status
 * TextExtents


 * Create

TCairoScaledFont: Methods
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.

Method Extents:TCairoFontExtents

Description: Gets the metrics for a TCairoScaledFont.

Returns: A TCairoFontExtents object.

Method GetCTM:TCairoMatrix

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

Returns: The CTM.

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.

Method GetFontMatrix:TCairoMatrix

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

Returns: The font matrix.

Method GetFontOptions:TCairoFontOptions

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

Returns: The font options.

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:

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.

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.

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
Function Create:TCairoScaledFont(font_face:TCairoFontFace, font_matrix:TCairoMatrix, ..

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

Returns: A newly created TCairoScaledFont. Destroy with Destroy.

TCairoFontExtents
The TCairoFontExtents type stores metric information for a font.

Values are given in the current user-space coordinate system. Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged.


 * ascent
 * descent
 * height
 * max_x_advance
 * max_y_advance

TCairoFontExtents: Fields
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.

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.

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.

Field max_x_advance:Double

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

Field max_y_advance:Double

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

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

TCairoPaperDimension
Dimensions of a sheet of paper.


 * width
 * height

TCairoPaperDimension: Fields
Field width:Double

Description: The paper width.

Field height:Double

Description: The paper height.