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 surface types you can currently use: TCairoImageSurface - draws to an in-memory image. TCairoPDFSurface - creates a PDF representation of the image(s). TCairoPSSurface - creates a Postscript representation of the image(s). To create a TCairo object for drawing onto a pixmap you could do the following : Local surface:TCairoImageSurface = TCairoImageSurface.CreateForPixmap(256,256) Local cairo:TCairo = TCairo.Create(surface) which would create a new pixmap for the surface, and tell cairo to draw on it. Also, you could use CreateForImage, which uses an existing TImage object to draw onto : Local image:TImage = CreateImage(256, 256, 1, DYNAMICIMAGE) Local surface:TCairoImageSurface = TCairoImageSurface.CreateForImage(image) Local cairo:TCairo = TCairo.Create(surface) (There are other operations for using pre-existing pixmaps, and even PNG files.) On creation, a cairo context is already created for you, but whenever Destroy is called you will have to create a new context using CreateContext before you can use it again. In normal usage you would perform the following operations during the life of a context: CreateContext() ...draw stuff on the context Destroy() To re-use a context, you can also Clear it with a given color, and subsequently perform drawing operations on what is essentially a clean sheet. The following simple example draws a circle filled yellow with a black outline : SuperStrict Import BaH.Cairo Local cairo:TCairo = TCairo.Create(TCairoImageSurface.CreateForPixmap(256,256)) ' set the line width cairo.SetLineWidth(5) ' draw an arc of 360 degrees (a circle) with radius 125. cairo.arc(128, 128, 125, 0, 360) ' set draw color to yellow cairo.SetSourceRGB(1, 1, 0) ' fix fill color to current cairo.FillPreserve() ' set draw color to black cairo.SetSourceRGB(0, 0, 0) ' draw it cairo.Stroke() ' destroy context and resources cairo.Destroy() ' Retrieve the image data from the pixmap Local image:TImage = LoadImage(TCairoImageSurface(cairo.getTarget()).pixmap()) Graphics 256, 256,0 SetBlend ALPHABLEND SetClsColor 255,255,255 Repeat Cls DrawImage image, 0, 0 Flip Until KeyHit(key_escape) End For information on creating Surfaces Examples The following is a list of examples that you can run: arc.bmx arc_image.bmx - The arc example using a TImage. arc_negative.bmx clip.bmx clip_image.bmx curve_rectangle.bmx curve_to.bmx fill_and_stroke.bmx fill_and_stroke2.bmx fill_and_stroke3.bmx - Shows SetDash usage. gradient.bmx image_pattern.bmx path.bmx pattern_fill.bmx set_line_cap.bmx set_line_join.bmx text.bmx text_align_center.bmx text_extents.bmx xxx_long_lines.bmx clock.bmx - a more advanced example of an analogue clock. clock_image.bmx - The analogue clock example using a TImage. clock_gtk_panel_pixmap.bmx - The analogue clock example drawing on a panel pixmap. Resize the window and watch it tile!! pdf_output_1.bmx - a small example showing creation of a PDF. Globals CAIRO_USER_FONTPATH Global CAIRO_USER_FONTPATH:String = "." Description: User derived font path. Information: Add your own here. Types TCairo The Cairo context wrapper type Methods CreateContext AppendPath Arc ArcNegative Clear Clip ClipPreserve ClosePath CopyPage CopyPath CopyPathFlat CurveTo Destroy DeviceToUser DeviceToUserDistance Fill FillExtents FillPreserve GetAntialias GetCurrentPoint GetFillRule GetFontFace GetFontMatrix GetGroupTarget GetLineCap GetLineJoin GetLineWidth GetMiterLimit GetOperator GetSource GetTarget GetTolerance IdentityMatrix InFill InStroke LineTo Mask MaskSurface MoveTo NewPath NewSubPath Paint PaintWithAlpha PopGroup PopGroupToSource PushGroup PushGroupWithContent Rectangle Reference RelCurveTo RelLineTo RelMoveTo ResetClip Restore Rotate Save Scale SelectFontFace SetAntialias SetDash SetFillRule SetFontFace SetFontMatrix SetFontOptions SetFontSize SetLineCap SetLineJoin SetLineWidth SetMatrix SetMiterLimit SetOperator SetScaledFont SetSource SetSourceRGB SetSourceRGBA SetSourceSurface SetTolerance ShowPage ShowText Status Stroke StrokeExtents StrokePreserve TextExtents TextPath Transform Translate UserToDevice UserToDeviceDistance Functions Create StatusToString Version VersionString TCairo: Methods CreateContext Method CreateContext() Description: Create a new Cairo context for objects to be drawn on. Information: Typical usage might look something like: CreateContext() ... draw stuff Destroy() AppendPath Method AppendPath(p:TCairoPath) Description: Append the path onto the current path. Arc Method Arc(XCenter:Double, YCenter:Double, Radius:Double, .. Description: Adds a circular arc of the given radius to the current path. Information: The arc is centered at (XCenter, YCenter), begins at StartAngle and proceeds in the direction of increasing angles to end at EndAngle. If EndAngle is less than StartAngle it will be progressively increased by 360 degrees until it is greater than StartAngle. If there is a current point, an initial line segment will be added to the path to connect the current point to the beginning of the arc. Angles are measured in degrees. An angle of 0 is in the direction of the positive X axis (in user-space). An angle of 90 degrees is in the direction of the positive Y axis (in user-space). Angles increase in the direction from the positive X axis toward the positive Y axis. So with the default transformation matrix, angles increase in a clockwise direction. This function gives the arc in the direction of increasing angles; see ArcNegative to get the arc in the direction of decreasing angles. The arc is circular in user-space. To achieve an elliptical arc, you can scale the current transformation matrix by different amounts in the X and Y directions. For example, to draw an ellipse in the box given by x, y, width, height: Save() Translate(x + width / 2.0, y + height / 2.0) Scale (1.0 / (height / 2.0), 1.0 / (width / 2.0)) Arc(0, 0, 1, 0, 360) Restore() Parameters: XCenter : X position of the center of the arc YCenter : Y position of the center of the arc Radius : the radius of the arc StartAngle : the start angle, in degrees EndAngle : the end angle, in degrees ArcNegative Method ArcNegative(XCenter:Double, YCenter:Double, Radius:Double, .. Description: Adds a circular arc of the given radius to the current path. Information: The arc is centered at (XCenter, YCenter), begins at StartAndle and proceeds in the direction of decreasing angles to end at EndAngle. If EndAngle is greater than StartAndle it will be progressively decreased by 360 until it is greater than StartAndle. See Arc for more details. This function differs only in the direction of the arc between the two angles. Parameters: XCenter : X position of the center of the arc YCenter : Y position of the center of the arc Radius : the radius of the arc StartAngle : the start angle, in degrees EndAngle : the end angle, in degrees Clear Method Clear(red:Double, green:Double, blue:Double, width:Double, height:Double) Description: Clear an area of the context with the specified color at the current translation point. Information: A convenience method for clearing / coloring an area of the context. You can use this for clearing the whole visible area of a context. Parameters: red : red component of color green : blue component of color blue : green component of color width : width of the area to be cleared height : height of the area to be cleared Clip Method Clip() Description: Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see SetFillRule). Information: After Clip, the current path will be cleared from the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling Clip can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling Clip within a Save / Restore pair. The only other means of increasing the size of the clip region is ResetClip. ClipPreserve Method ClipPreserve() Description: Establishes a new clip region by intersecting the current clip region with the current path as it would be filled by Fill and according to the current fill rule (see SetFillRule). Information: Unlike Clip, ClipPreserve preserves the path within the cairo context. The current clip region affects all drawing operations by effectively masking out any changes to the surface that are outside the current clip region. Calling ClipPreserve can only make the clip region smaller, never larger. But the current clip is part of the graphics state, so a temporary restriction of the clip region can be achieved by calling ClipPreserve within a Save / Restore pair. The only other means of increasing the size of the clip region is ResetClip. ClosePath Method ClosePath() Description: Adds a line segment to the path from the current point to the beginning of the current subpath, (the most recent point passed to MoveTo), and closes this subpath. Information: The behavior of ClosePath is distinct from simply calling LineTo with the equivalent coordinate in the case of stroking. When a closed subpath is stroked, there are no caps on the ends of the subpath. Instead, there is a line join connecting the final and initial segments of the subpath. CopyPage Method CopyPage() Description: Takes a copy of the current surface to create a new Page. Information: This is not supported by all surfaces and therefore may not appear to do anything. CopyPath Method CopyPath:TCairoPath() Description: Creates a copy of the current path and returns it to the user as a TCairoPath. Returns: The copy of the current path. The caller owns the returned object and should call Destroy when finished with it. CopyPathFlat Method CopyPathFlat:TCairoPath() Description: Gets a flattened copy of the current path and returns it to the user as a TCairoPath. Returns: The copy of the current path. The caller owns the returned object and should call Destroy when finished with it. Information: This function is like CopyPath except that any curves in the path will be approximated with piecewise-linear approximations, (accurate to within the current tolerance value). That is, the result is guaranteed to not have any elements of type CAIRO_PATH_CURVE_TO which will instead be replaced by a series of CAIRO_PATH_LINE_TO elements. CurveTo Method CurveTo(x1:Double,y1:Double, x2:Double,y2:Double, x3:Double,y3:Double) Description: Adds a cubic Bézier spline to the path from the current point to position (x3, y3) in user-space coordinates, using (x1, y1) and (x2, y2) as the control points. Information: After this call the current point will be (x3, y3). Parameters: x1 : the X coordinate of the first control point y1 : the Y coordinate of the first control point x2 : the X coordinate of the second control point y2 : the Y coordinate of the second control point x3 : the X coordinate of the end of the curve y3 : the Y coordinate of the end of the curve Destroy Method Destroy() Description: Decreases the reference count by one. Information: If the result is zero, then all associated resources are freed. DeviceToUser Method DeviceToUser(x:Double Var, y:Double Var) Description: Transform a coordinate from device space to user space by multiplying the given point by the inverse of the current transformation matrix Information: Parameters: x : X value of coordinate (in/out parameter) y : Y value of coordinate (in/out parameter) DeviceToUserDistance Method DeviceToUserDistance(dx:Double Var, dy:Double Var) Description: Transform a distance vector from device space to user space. Information: This function is similar to DeviceToUser except that the translation components of the inverse current transformation matrix will be ignored when transforming (dx,dy). Parameters: dx : X component of a distance vector (in/out parameter) dy : Y component of a distance vector (in/out parameter) Fill Method Fill() Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Information: After Fill, the current path will be cleared from the cairo context. See SetFillRule and FillPreserve. FillExtents Method FillExtents(x1:Double Var,y1:Double Var, x2:Double Var,y2:Double Var) Description: Returns the extents for the current fill. FillPreserve Method FillPreserve() Description: A drawing operator that fills the current path according to the current fill rule, (each sub-path is implicitly closed before being filled). Information: Unlike Fill, FillPreserve preserves the path within the cairo context. GetAntialias Method GetAntialias:Int() Description: Gets the current shape antialiasing mode, as set by SetAntialias. returns : the current shape antialiasing mode. GetCurrentPoint Method GetCurrentPoint(x:Double Var,y:Double Var) Description: Returns the current point in the context. GetFillRule Method GetFillRule:Int() Description: Gets the current fill rule, as set by SetFillRule. returns : the current fill rule. GetFontFace Method GetFontFace:TCairoFontFace() Description: Gets the current font face for the context. Returns: The current font object. Can return Null on out-of-memory or if the context is already in an error state. This object is owned by cairo. To keep a reference to it, you must call fontface.Reference() GetFontMatrix Method GetFontMatrix:TCairoMatrix() Description: Gets the current font matrix Returns: return value for the matrix. Information: See TCairoMatrix for more information. GetGroupTarget Method GetGroupTarget:TCairoSurface() Description: Gets the target surface for the current group as started by the most recent call to PushGroup or PushGroupWithContent. Returns: The target group surface, or Null if none. This object is owned by cairo. To keep a reference to it, you must call surface.Reference(). Information: This method will return Null if called "outside" of any group rendering blocks, (that is, after the last balancing call to PopGroup or PopGroupToSource ). GetLineCap Method GetLineCap:Int() Description: Gets the current line cap style, as set by SetLineCap. returns : the current line cap style. GetLineJoin Method GetLineJoin:Int() Description: Gets the current line join style, as set by SetLineJoin. returns : the current line join style. GetLineWidth Method GetLineWidth:Double() Description: Gets the current line width, as set by SetLineWidth. returns : the current line width, in user-space units. GetMiterLimit Method GetMiterLimit:Double() Description: Gets the miter limit, as set by SetMiterLimit. returns : the current miter limit. GetOperator Method GetOperator:Int() Description: Gets the current compositing operator for the cairo context. Information: See SetOperator for details of returnable values. returns : the current compositing operator. GetSource Method GetSource:TCairoPattern() Description: Gets the current source pattern for the context. Returns: The current source pattern. This object is owned by cairo. To keep a reference to it, you must call pattern.Reference() GetTarget Method GetTarget:TCairoSurface() Description: Gets the target surface for the cairo context as passed to Create. Returns: The target surface. This object is owned by cairo. To keep a reference to it, you must call cairosurface.Reference() Information: This function will always return a valid object, but the result can be a "nil" surface if the context is already in an error state, (i.e. cairo.Status() CAIRO_STATUS_SUCCESS). A nil surface is indicated by cairosurface.Status() CAIRO_STATUS_SUCCESS. GetTolerance Method GetTolerance:Double() Description: Gets the current tolerance value, as set by SetTolerance. returns : the current tolerance value. IdentityMatrix Method IdentityMatrix() Description: Resets the current transformation matrix by setting it equal to the identity matrix. Information: That is, the user-space and device-space axes will be aligned and one user-space unit will transform to one device-space unit. InFill Method InFill:Int(X:Double, Y:Double) Description: Tests whether the given point is inside the area that would be filled by doing a Fill operation given the current path and filling parameters. Returns: A non-zero value if the point is inside, or zero if outside. Information: See Fill, SetFillRule and FillPreserve. Parameters: x : X coordinate of the point to test y : Y coordinate of the point to test InStroke Method InStroke:Int(X:Double, Y:Double) Description: Tests whether the given point is inside the area that would be stroked by doing a Stroke operation given the current path and stroking parameters. Returns: A non-zero value if the point is inside, or zero if outside. Information: See Stroke, SetLineWidth, SetLineJoin, SetLineCap, SetDash, and StrokePreserve. Parameters: x : X coordinate of the point to test y : Y coordinate of the point to test LineTo Method LineTo(x:Double, y:Double) Description: Adds a line to the path from the current point to position (x, y) in user-space coordinates. Information: After this call the current point will be (x, y). Parameters: x : the X coordinate of the end of the new line y : the Y coordinate of the end of the new line Mask Method Mask(pattern:TCairoPattern) Description: A drawing operator that paints the current source using the alpha channel of pattern as a mask. Information: Opaque areas of mask are painted with the source, transparent areas are not painted. Parameters: pattern : a TCairoPattern MaskSurface Method MaskSurface(surface:TCairoSurface, SurfaceX:Double, SurfaceY:Double) Description: A drawing operator that paints the current source using the alpha channel of surface as a mask. Information: Opaque areas of surface are painted with the source, transparent areas are not painted. Parameters: surface : a TCairoSurface surface_x : X coordinate at which to place the origin of surface surface_y : Y coordinate at which to place the origin of surface MoveTo Method MoveTo(x:Double, y:Double) Description: If the current subpath is not empty, begin a new subpath. Information: After this call the current point will be (x, y). Parameters: x : the X coordinate of the new position y : the Y coordinate of the new position NewPath Method NewPath() Description: Clears the current path. Information: After this call there will be no current point. NewSubPath Method NewSubPath() Description: Begin a new sub-path. Information: Note that the existing path is not affected. After this call there will be no current point. In many cases, this call is not needed since new sub-paths are frequently started with MoveTo. A call to NewSubPath is particularly useful when beginning a new sub-path with one of the Arc calls. This makes things easier as it is no longer necessary to manually compute the arc's initial coordinates for a call to MoveTo. Paint Method Paint() Description: A drawing operator that paints the current source everywhere within the current clip region. PaintWithAlpha Method PaintWithAlpha(alpha:Double) Description: A drawing operator that paints the current source everywhere within the current clip region using a mask of constant alpha value alpha. Information: The effect is similar to Paint, but the drawing is faded out using the alpha value. Parameters: alpha : alpha value, between 0 (transparent) and 1 (opaque) PopGroup Method PopGroup:TCairoPattern() Description: Terminates the redirection begun by a call to PushGroup or PushGroupWithContent and returns a new pattern containing the results of all drawing operations performed to the group. Returns: A newly created (surface) pattern containing the results of all drawing operations performed to the group. The TCairoPattern should be destroyed when finished with. Information: The PopGroup method calls Restore, (balancing a call to Save by the PushGroup method), so that any changes to the graphics state will not be visible outside the group. PopGroupToSource Method PopGroupToSource() Description: Terminates the redirection begun by a call to PushGroup or PushGroupWithContent and installs the resulting pattern as the source pattern in the cairo context. Information: The behavior of this function is equivalent to the sequence of operations: local group:TCairoPattern = cairo.PopGroup() cairo.SetSource(group) group.Destroy() but is more convenient as there is no need for a variable to store the short-lived pointer to the pattern. The PopGroup method calls Restore, (balancing a call to Save by the PushGroup method), so that any changes to the graphics state will not be visible outside the group. PushGroup Method PushGroup() Description: Temporarily redirects drawing to an intermediate surface known as a group. Information: The redirection lasts until the group is completed by a call to PopGroup or PopGroupToSource. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). This group functionality can be convenient for performing intermediate compositing. One common use of a group is to render objects as opaque within the group, (so that they occlude each other), and then blend the result with translucence onto the destination. Groups can be nested arbitrarily deep by making balanced calls to PushGroup / PopGroup. Each call pushes/pops the new target group onto/from a stack. The PushGroup function calls Save so that any changes to the graphics state will not be visible outside the group, (the pop_group functions call Restore ). By default the intermediate group will have a content type of CAIRO_CONTENT_COLOR_ALPHA. Other content types can be chosen for the group by using PushGroupWithContent instead. As an example, here is how one might fill and stroke a path with translucence, but without any portion of the fill being visible under the stroke: cairo.PushGroup() cairo.SetSource(fill_pattern) cairo.FillPreserve() cairo.SetSource(stroke_pattern) cairo.Stroke() cairo.PopGroupToSource() cairo.PaintWithAlpha(alpha) PushGroupWithContent Method PushGroupWithContent(content:Int) Description: Temporarily redirects drawing to an intermediate surface known as a group. Information: The redirection lasts until the group is completed by a call to PopGroup or PopGroupToSource. These calls provide the result of any drawing to the group as a pattern, (either as an explicit object, or set as the source pattern). The group will have a content type of content (see below). The ability to control this content type is the only distinction between this function and PushGroup which you should see for a more detailed description of group rendering. 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: face : a TCairoFontFace object. SetFontMatrix Method SetFontMatrix(matrix:TCairoMatrix) Description: Set the current font matrix within the cairo context. Information: Parameters: matrix : a TCairoMatrix object. SetFontOptions Method SetFontOptions(options:TCairoFontOptions) Description: Set the current font options within the cairo context. Information: Parameters: options : a TCairoFontOptions object. SetFontSize Method SetFontSize(size:Double) Description: Sets the current font size. Information: Parameters: size : the new font size to set. SetLineCap Method SetLineCap(cap:Int) Description: Sets the current line cap style within the cairo context. Information: As with the other stroke parameters, the current line cap style is examined by Stroke, StrokeExtents, and StrokeToPath, but does not have any effect during path construction. The following details how the available line cap styles are drawn : 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 Create Function Create:TCairo(surf:TCairoSurface) Description: Create a new TCairo object using the provided surface. Returns: A new TCairo object. Information: Parameters: surf : a TCairoSurface object. StatusToString Function StatusToString:String(s:Int) Description: Provides a human-readable description of the status value. Returns: A string representation of the status. Information: See Status for a list of valid status values to pass into this method. Parameters: s : a cairo status. Version Function Version:Int() Description: Returns the version of the cairo library encoded in a single integer. Returns: The encoded version. VersionString Function VersionString:String() Description: Returns the version of the cairo library as a human-readable string of the form "X.Y.Z". Returns: A string containing the version. TCairoSurface A TCairoSurface represents an image either as the destination of a drawing operation or as source when drawing onto another surface. You should use one of the following sub-types which define the different drawing backends : TCairoImageSurface - draws to an in-memory image. TCairoPDFSurface - creates a PDF representation of the image(s). TCairoPSSurface - creates a Postscript representation of the image(s). Methods Destroy Finish Flush GetContent GetDeviceOffset GetType MarkDirty MarkDirtyRectangle Reference SetDeviceOffset SetFallbackResolution Status WriteToPNG Functions CreateSimilar TCairoSurface: Methods Destroy Method Destroy() Description: Decreases the reference count on surface by one. Information: If the result is zero, then surface and all associated resources are freed. See Reference. Finish Method Finish() Description: This function finishes the surface and drops all references to external resources. Information: After calling Finish the only valid operations on a surface are getting and setting user data and referencing and destroying it. Further drawing to the surface will not affect the surface but will instead trigger a CAIRO_STATUS_SURFACE_FINISHED error. When the last call to Destroy decreases the reference count to zero, cairo will call Finish if it hasn't been called already, before freeing the resources associated with the surface. Flush Method Flush() Description: Do any pending drawing for the surface and also restore any temporary modification's cairo has made to the surface's state. Information: This function must be called before switching from drawing on the surface with cairo to drawing on it directly with native APIs. If the surface doesn't support direct access, then this function does nothing. GetContent Method GetContent:Int() Description: Returns the content type of surface which indicates whether the surface contains color and/or alpha information. Returns: The content type. Information: Content types are : 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 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 A TCairoSurface for rendering PDF documents. Methods SetSize Functions CreateForPDF TCairoPDFSurface: Methods SetSize Method SetSize(width:Double, height:Double) Description: Changes the size of a PDF surface for the current (and subsequent) pages. Information: This method should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either ShowPage or CopyPage. Parameters: width : new surface width, in points (1 point == 1/72.0 inch) height : new surface height, in points (1 point == 1/72.0 inch) TCairoPDFSurface: Functions CreateForPDF Function CreateForPDF:TCairoPDFSurface(filename:String, width:Double, height:Double) Description: Creates an PDF surface for the specified filename (which will be created) and dimensions. Returns: The newly created surface. Information: Parameters: filename : the name of the PDF file to create. width : width of the surface, in points. (1 point == 1/72.0 inch) height : height of the surface, in points. (1 point == 1/72.0 inch) TCairoPSSurface A TCairoSurface for rendering Postscript documents. Methods SetSize Functions CreateForPS TCairoPSSurface: Methods SetSize Method SetSize(width:Double, height:Double) Description: Changes the size of a PostScript surface for the current (and subsequent) pages. Information: This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either ShowPage or CopyPage. Parameters: width : new surface width, in points (1 point == 1/72.0 inch) height : new surface height, in points (1 point == 1/72.0 inch) TCairoPSSurface: Functions CreateForPS Function CreateForPS:TCairoPSSurface(filename:String, width:Double, height:Double) Description: Creates an Postscript surface for the specified filename (which will be created) and dimensions. Returns: The newly created surface. Information: Parameters: filename : the name of the postscript file to create. width : width of the surface, in pixels. height : height of the surface, in pixels. TCairoImageSurface Image surfaces provide the ability to render to memory buffers either allocated by cairo or by the calling code Methods Pixmap GetData getFormat GetHeight GetStride GetWidth Functions Create CreateFromPNG CreateForPixmap CreateFromImage CreateFromPixmap TCairoImageSurface: Methods Pixmap Method Pixmap:TPixmap() Description: Returns the pixmap instance, if one exists. GetData Method GetData:Byte Ptr() Description: Get a pointer to the data of the image surface, for direct inspection or modification. Returns: A pointer to the image data of this surface or Null if surface is not an image surface. getFormat Method getFormat:Int() Description: Get the format of the surface. Returns: The format of the surface. Information: See TCairoImageSurface for list of formats. GetHeight Method GetHeight:Int() Description: Get the height of the image surface in pixels. Returns: The height of the surface in pixels. GetStride Method GetStride:Int() Description: Get the stride of the image surface in bytes. Returns: The stride of the image surface in bytes (or 0 if surface is not an image surface). Information: The stride is the distance in bytes from the beginning of one row of the image data to the beginning of the next row. GetWidth Method GetWidth:Int() Description: Get the width of the image surface in pixels. Returns: The width of the surface in pixels. TCairoImageSurface: Functions Create Function Create:TCairoImageSurface(width:Int, height:Int, format:Int) Description: Creates an image surface of the specified format and dimensions. Returns: The newly created surface. The caller owns the surface and should call Destroy when done with it. This function always returns a valid surface, but it will return a "nil" surface if an error such as out of memory occurs. You can use Status to check for this. Information: The initial contents of the surface is undefined; you must explicitly clear the buffer, using, for example, Rectangle and Fill if you want it cleared. The list of available formats are as follows: 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 Gradients and filtered sources. Methods AddColorStopRGB AddColorStopRGBA Destroy GetExtend GetFilter GetType Reference SetExtend SetFilter SetMatrix Status Functions CreateForSurface CreateLinear CreateRadial CreateRGB CreateRGBA TCairoPattern: Methods AddColorStopRGB Method AddColorStopRGB(offset:Double, red:Double, green:Double, blue:Double) Description: Adds an opaque color stop to a gradient pattern. Information: The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in SetSourceRGB. Note: If the pattern is not a gradient pattern, (e.g. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH. Parameters: offset : an offset in the range [0.0 .. 1.0]. red : red component of color. green : green component of color. blue : blue component of color. AddColorStopRGBA Method AddColorStopRGBA(offset:Double, red:Double, green:Double, blue:Double, alpha:Double) Description: Adds a translucent color stop to a gradient pattern. Information: The offset specifies the location along the gradient's control vector. For example, a linear gradient's control vector is from (x0,y0) to (x1,y1) while a radial gradient's control vector is from any point on the start circle to the corresponding point on the end circle. The color is specified in the same way as in SetSourceRGBA. Note: If the pattern is not a gradient pattern, (e.g. a linear or radial pattern), then the pattern will be put into an error status with a status of CAIRO_STATUS_PATTERN_TYPE_MISMATCH. Parameters: offset : an offset in the range [0.0 .. 1.0]. red : red component of color. green : green component of color. blue : blue component of color. alpha : alpha component of color. Destroy Method Destroy() Description: Decreases the reference count on pattern by one. Information: If the result is zero, then pattern and all associated resources are freed. See Reference. GetExtend Method GetExtend:Int() Description: Get the current extend mode for the pattern. Returns: The extend mode. See SetExtend for the list of possible values. GetFilter Method GetFilter:Int() Description: Get the current pattern filter. Returns: The pattern filter. See SetFilter for the list of possible values. GetType Method GetType:Int() Description: This function returns the type of the pattern. Returns: The type of pattern. Information: The type of a pattern is determined by the function used to create it. The CreateRGB and CreateRGBA functions create SOLID patterns. The remaining pattern create functions map to pattern types in obvious ways. Most pattern methods can be called with a pattern of any type, (though trying to change the extend or filter for a solid pattern will have no effect). A notable exception is AddColorStopRGB and AddColorStopRGBA which must only be called with gradient patterns (either LINEAR or RADIAL). Otherwise the pattern will be shutdown and put into an error state. New entries may be added in future versions. Current patterns are: 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 CreateForSurface Function CreateForSurface:TCairoPattern(surface:TCairoSurface) Description: Create a new TCairoPattern for the given surface. Returns: A new TCairoPattern object CreateLinear Function CreateLinear:TCairoPattern(x0:Double, y0:Double, x1:Double, y1:Double) Description: Create a new linear gradient cairo_pattern_t along the line defined by (x0, y0) and (x1, y1). Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status. Information: Before using the gradient pattern, a number of color stops should be defined using AddColorStopRGB or AddColorStopRGBA. Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with SetMatrix. Parameters: x0 : x coordinate of the start point. y0 : y coordinate of the start point. x1 : x coordinate of the end point. y1 : y coordinate of the end point. CreateRadial Function CreateRadial:TCairoPattern(cx0:Double,cy0:Double,radius0:Double, cx1:Double,cy1:Double,radius1:Double) Description: Creates a new radial gradient cairo_pattern_t between the two circles defined by (x0, y0, c0) and (x1, y1, c0). Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status. Information: Before using the gradient pattern, a number of color stops should be defined using AddColorStopRGB or AddColorStopRGBA. Note: The coordinates here are in pattern space. For a new pattern, pattern space is identical to user space, but the relationship between the spaces can be changed with SetMatrix. Parameters: cx0 : x coordinate for the center of the start circle. cy0 : y coordinate for the center of the start circle. radius0 : radius of the start cirle in degrees. cx1 : x coordinate for the center of the end circle. cy1 : y coordinate for the center of the end circle. radius1 : radius of the end cirle in degrees. CreateRGB Function CreateRGB:TCairoPattern(red:Double, green:Double, blue:Double) Description: Creates a new TCairoPattern corresponding to an opaque color Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status. Information: The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. Parameters: red : red component of color. green : green component of color. blue : blue component of color. CreateRGBA Function CreateRGBA:TCairoPattern(red:Double, green:Double, blue:Double, alpha:Double) Description: Creates a new cairo_pattern_t corresponding to a translucent color. Returns: The newly created TCairoPattern if successful, or an error pattern in case of no memory. The caller owns the returned object and should call Destroy when finished with it. This function will always return a valid object, but if an error occurred the pattern status will be set to an error. To inspect the status of a pattern use Status. Information: The color components are floating point numbers in the range 0 to 1. If the values passed in are outside that range, they will be clamped. Parameters: red : red component of color. green : green component of color. blue : blue component of color. alpha : alpha component of the color. TCairoMatrixStruct A TCairoMatrixStruct holds an affine transformation, such as a scale, rotation, shear, or a combination of those. The transformation of a point (x, y) is given by: x_new = xx * x + xy * y + x0 y_new = yx * x + yy * y + y0 Fields xx yx xy yy x0 y0 TCairoMatrixStruct: Fields xx Field xx:Double Description: xx component of the affine transformation yx Field yx:Double Description: yx component of the affine transformation xy Field xy:Double Description: xy component of the affine transformation yy Field yy:Double Description: yy component of the affine transformation x0 Field x0:Double Description: X translation component of the affine transformation y0 Field y0:Double Description: Y translation component of the affine transformation TCairoMatrix TCairoMatrix is used throughout cairo to convert between different coordinate spaces. A TCairoMatrix holds an affine transformation, such as a scale, rotation, shear, or a combination of these. The transformation of a point (x,y) is given by: x_new = xx * x + xy * y + x0 y_new = yx * x + yy * y + y0 The current transformation matrix of a TCairo, represented as a TCairoMatrix, defines the transformation from user-space coordinates to device-space coordinates. See GetMatrix and SetMatrix. You can access the specific values of the transformation through the matrix field (a TCairoMatrixStruct) of the TCairoMatrix. Methods Init InitIdentity InitRotate InitScale InitTranslate Invert Rotate Scale TransformDistance TransformPoint Translate Functions Create CreateIdentity CreateRotate CreateScale CreateTranslate Multiply TCairoMatrix: Methods Init Method Init(xx:Double, yx:Double, xy:Double, yy:Double, x0:Double, y0:Double) Description: Sets matrix to be the affine transformation given by xx, yx, xy, yy, x0, y0. Information: The transformation is given by: x_new = xx * x + xy * y + x0 y_new = yx * x + yy * y + y0 Parameters: xx : xx component of the affine transformation. yx : yx component of the affine transformation. xy : xy component of the affine transformation. yy : yy component of the affine transformation. x0 : X translation component of the affine transformation. y0 : Y translation component of the affine transformation. InitIdentity Method InitIdentity() Description: Modifies matrix to be an identity transformation. InitRotate Method InitRotate(degrees:Double) Description: Initialized matrix to a transformation that rotates by degrees. Information: Parameters: degrees : angle of rotation, in degrees. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction. InitScale Method InitScale(sx:Double, sy:Double) Description: Initializes matrix to a transformation that scales by sx and sy in the X and Y dimensions, respectively. Information: Parameters: sx : scale factor in the X direction. sy : scale factor in the Y direction. InitTranslate Method InitTranslate(tx:Double, ty:Double) Description: Initializes matrix to a transformation that translates by tx and ty in the X and Y dimensions, respectively. Information: Parameters: tx : amount to translate in the X direction. ty : amount to translate in the Y direction. Invert Method Invert:Int() Description: Changes matrix to be the inverse of its original value. Returns: If matrix has an inverse, modifies matrix to be the inverse matrix and returns CAIRO_STATUS_SUCCESS. Otherwise, CAIRO_STATUS_INVALID_MATRIX. Information: Not all transformation matrices have inverses; if the matrix collapses points together (it is degenerate), then it has no inverse and this function will fail. Rotate Method Rotate(degrees:Double) Description: Applies rotation by degrees to the transformation in matrix. The effect of the new transformation is to first rotate the coordinates by degrees, then apply the original transformation to the coordinates. Parameters: degrees : angle of rotation, in degrees. The direction of rotation is defined such that positive angles rotate in the direction from the positive X axis toward the positive Y axis. With the default axis orientation of cairo, positive angles rotate in a clockwise direction. Scale Method Scale(sx:Double, sy:Double) Description: Applies scaling by sx, sy to the transformation in matrix. Information: The effect of the new transformation is to first scale the coordinates by sx and sy, then apply the original transformation to the coordinates. Parameters: sx : scale factor in the X direction. sy : scale factor in the Y direction. TransformDistance Method TransformDistance(dx:Double Var,dy:Double Var) Description: Transforms the distance vector (dx,dy) by the matrix. Information: This is similar to Transform except that the translation components of the transformation are ignored. The calculation of the returned vector is as follows: dx2 = dx1 * a + dy1 * c dy2 = dx1 * b + dy1 * d Affine transformations are position invariant, so the same vector always transforms to the same vector. If (x1,y1) transforms to (x2,y2) then (x1 + dx1, y1 + dy1) will transform to (x1 + dx2, y1 + dy2) for all values of x1 and x2. Parameters: dx : X component of a distance vector. An in/out parameter. dy : Y component of a distance vector. An in/out parameter. TransformPoint Method TransformPoint(x:Double Var,y:Double Var) Description: Transforms the point ( x, y ) by the matrix. Information: Parameters: x : X position. An in/out parameter. y : X position. An in/out parameter. Translate Method Translate(tx:Double, ty:Double) Description: Applies a translation by tx, ty to the transformation in matrix. Information: The effect of the new transformation is to first translate the coordinates by tx and ty, then apply the original transformation to the coordinates. Parameters: tx : amount to translate in the X direction. ty : amount to translate in the Y direction. TCairoMatrix: Functions Create Function Create:TCairoMatrix(xx:Double,yx:Double, xy:Double,yy:Double, x0:Double,y0:Double) Description: Creates a new TCairoMatrix to be the given affine transformation. Returns: A new matrix object. Information: See Init for more details. CreateIdentity Function CreateIdentity:TCairoMatrix() Description: Creates a new TCairoMatrix as an identity transformation. Returns: A new matrix object. Information: See InitIdentity for more details. CreateRotate Function CreateRotate:TCairoMatrix(degrees:Double) Description: Creates a new TCairoMatrix to be a transformation that rotates by degreesn. Returns: A new matrix object. Information: See InitRotate for more details. CreateScale Function CreateScale:TCairoMatrix(sx:Double, sy:Double) Description: Creates a new TCairoMatrix to be a transformation that scales by sx and sy in the X and Y dimensions, respectively. Returns: A new matrix object. Information: See InitScale for more details. CreateTranslate Function CreateTranslate:TCairoMatrix(tx:Double, ty:Double) Description: Creates a new TCairoMatrix to be a transformation that translates by tx and ty in the X and Y dimensions, respectively. Returns: A new matrix object. Information: See InitTranslate for more details. Multiply Function Multiply:TCairoMatrix(mat1:TCairoMatrix, mat2:TCairoMatrix) Description: Multiplies the affine transformations in mat1 and mat2 together and stores the result in result. Returns: The result of the multiplication of the two matrices. Information: The effect of the resulting transformation is to first apply the transformation in a to the coordinates and then apply the transformation in b to the coordinates. It is allowable for result to be identical to either mat1 or mat2. Parameters: mat1 : a TCairoMatrix. mat2 : a TCairoMatrix. TCairoFontFace A TCairoFontFace specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions). A font face can be set on a TCairo by using SetFontFace. The size and font matrix are set with SetFontSize and SetFontMatrix. Methods Destroy GetType Reference Status TCairoFontFace: Methods Destroy Method Destroy() Description: Decreases the reference count on font_face by one. Information: If the result is zero, then font_face and all associated resources are freed. See Reference. GetType Method GetType:Int() Description: This function returns the type of the backend used to create a font face. Information: The following lists the possible font types: 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 How a font should be rendered. Methods Copy Destroy EqualTo GetAntialias GetHintMetrics GetHintStyle GetSubpixelOrder Hash Merge SetAntialias SetHintMetrics SetHintStyle SetSubpixelOrder Status Functions Create TCairoFontOptions: Methods Copy Method Copy:TCairoFontOptions() Description: Allocates a new font options object copying the option values from this one. Returns: A newly allocated TCairoFontOptions object. Free with Destroy. This function always returns a valid object; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with Status. Destroy Method Destroy() Description: Destroys a TCairoFontOptions object created with Create or Copy. EqualTo Method EqualTo:Int(other:TCairoFontOptions) Description: Compares two font options objects for equality. Returns: True if all fields of the two font options objects match. Information: Parameters: other : another TCairoFontOptions. GetAntialias Method GetAntialias:Int() Description: Gets the antialising mode for the font options object. Returns: The antialiasing mode. GetHintMetrics Method GetHintMetrics:Int() Description: Gets the metrics hinting mode for the font options object. Returns: The metrics hinting mode for the font options object. Information: See SetHintMetrics for more details. GetHintStyle Method GetHintStyle:Int() Description: Gets the hint style for font outlines for the font options object. Returns: The hint style for the font options object. Information: See SetHintStyle for more information. GetSubpixelOrder Method GetSubpixelOrder:Int() Description: Gets the subpixel order for the font options object. Returns: The subpixel order for the font options object. Information: See SetSubpixelOrder for more details. Hash Method Hash:Long() Description: Compute a hash for the font options object. Returns: The hash value for the font options object. The return value can be cast to a 32-bit type if a 32-bit hash value is needed. Information: This value will be useful when storing an object containing a TCairoFontOptions in a hash table. Merge Method Merge(other:TCairoFontOptions) Description: Merges non-default options from other into this one, replacing existing values. Information: This operation can be thought of as somewhat similar to compositing other onto options with the operation of CAIRO_OPERATION_OVER. Parameters: other : another TCairoFontOptions. SetAntialias Method SetAntialias(aa:Int) Description: Sets the antiliasing mode for the font options object. Information: This specifies the type of antialiasing to do when rendering text. Possible Antialias values : 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 Create Function Create:TCairoFontOptions() Description: Allocates a new font options object with all options initialized to default values. Returns: A newly allocated TCairoFontOptions object. Free with Destroy. This function always returns a valid object; if memory cannot be allocated, then a special error object is returned where all operations on the object do nothing. You can check for this with Status. TCairoPath A data structure for holding a path. This data structure serves as the return value for CopyPath and CopyPathFlat as well the input value for AppendPath. Methods Destroy TCairoPath: Methods Destroy Method Destroy() Description: Immediately releases all memory associated with path. Information: After a call to Destroy the path pointer is no longer valid and should not be used further. TCairoTextExtents The TCairoTextExtents structure stores the extents of a single glyph or a string of glyphs in user-space coordinates. Because text extents are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged. Fields x_bearing y_bearing width height x_advance y_advance TCairoTextExtents: Fields x_bearing Field x_bearing:Double Description: The horizontal distance from the origin to the leftmost part of the glyphs as drawn. Information: Positive if the glyphs lie entirely to the right of the origin. y_bearing Field y_bearing:Double Description: The vertical distance from the origin to the topmost part of the glyphs as drawn. Information: Positive only if the glyphs lie completely below the origin; will usually be negative. width Field width:Double Description: Width of the glyphs as drawn. height Field height:Double Description: Height of the glyphs as drawn. x_advance Field x_advance:Double Description: Distance to advance in the X direction after drawing these glyphs. y_advance Field y_advance:Double Description: Distance to advance in the Y direction after drawing these glyphs. about; Will typically be zero except for vertical text layout as found in East-Asian languages. TCairoScaledFont A TCairoScaledFont is a font scaled to a particular size and device resolution. A TCairoScaledFont is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics. Methods Destroy Extents GetCTM GetFontFace GetFontMatrix GetFontOptions GetType Reference Status TextExtents Functions Create TCairoScaledFont: Methods Destroy Method Destroy() Description: Decreases the reference count on font by one. Information: If the result is zero, then font and all associated resources are freed. See Reference. Extents Method Extents:TCairoFontExtents() Description: Gets the metrics for a TCairoScaledFont. Returns: A TCairoFontExtents object. GetCTM Method GetCTM:TCairoMatrix() Description: Returns the CTM with which the scaled font was created. Returns: The CTM. GetFontFace Method GetFontFace:TCairoFontFace() Description: Gets the font face that this scaled font was created for. Returns: The TCairoFontFace with which the scaled font was created. GetFontMatrix Method GetFontMatrix:TCairoMatrix() Description: Returns the font matrix with which the scaled font was created. Returns: The font matrix. GetFontOptions Method GetFontOptions:TCairoFontOptions() Description: Returns the font options with which the scaled font was created. Returns: The font options. GetType Method GetType:Int() Description: This method returns the type of the backend used to create a scaled font. Returns: The type of scaled font. Information: The following lists the possible font types: 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 Create Function Create:TCairoScaledFont(font_face:TCairoFontFace, font_matrix:TCairoMatrix, .. Description: Creates a TCairoScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used. Returns: A newly created TCairoScaledFont. Destroy with Destroy. TCairoFontExtents The TCairoFontExtents type stores metric information for a font. Values are given in the current user-space coordinate system. Because font metrics are in user-space coordinates, they are mostly, but not entirely, independent of the current transformation matrix. If you call Scale(2.0, 2.0), text will be drawn twice as big, but the reported text extents will not be doubled. They will change slightly due to hinting (so you can't assume that metrics are independent of the transformation matrix), but otherwise will remain unchanged. Fields ascent descent height max_x_advance max_y_advance TCairoFontExtents: Fields ascent Field ascent:Double Description: The distance that the font extends above the baseline. Information: Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements above it. descent Field descent:Double Description: The distance that the font extends below the baseline. Information: This value is positive for typical fonts that include portions below the baseline. Note that this is not always exactly equal to the maximum of the extents of all the glyphs in the font, but rather is picked to express the font designer's intent as to how the font should align with elements below it. height Field height:Double Description: The recommended vertical distance between baselines when setting consecutive lines of text with the font. Information: This is greater than ascent + descent by a quantity known as the line spacing or external leading. When space is at a premium, most fonts can be set with only a distance of ascent + descent between lines. max_x_advance Field max_x_advance:Double Description: The maximum distance in the X direction that the origin is advanced for any glyph in the font max_y_advance Field max_y_advance:Double Description: The maximum distance in the Y direction that the origin is advanced for any glyph in the font. Information: This will be zero for normal fonts used for horizontal writing. (The scripts of East Asia are sometimes written vertically.) TCairoPaperDimension Dimensions of a sheet of paper. Fields width height TCairoPaperDimension: Fields width Field width:Double Description: The paper width. height Field height:Double Description: The paper height.