Safari Developer Library

Developer

CanvasRenderingContext2D Class Reference

Options
Deployment Target:

On This Page

CanvasRenderingContext2D

The CanvasRenderingContext2D class provides a 2D drawing context for a canvas element. Use the methods of this class to draw on the canvas. To obtain an instance of the CanvasRenderingContext2D, call the getContext('2d') method on a canvas object. See Safari HTML5 Canvas Guide for usage examples.

Inheritance


  • CanvasRenderingContext
  • CanvasRenderingContext2D

Conforms To


Not Applicable

Import Statement


Not Applicable Not Applicable

Availability


Available in Safari 3.0 and later.
Available in iOS 1.0 and later.
  • Clears the specified rectangle to transparent black—RGBa(0,0,0,0).

    Declaration

    JavaScript

    void clearRect (in float x, in float y, in float width, in float height);

    Parameters

    x

    The x-coordinate of the left edge of the rectangle, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the top of the rectangle, in pixels from the top of the canvas coordinate system.

    width

    The width of the rectangle, in pixels.

    height

    The height of the rectangle, in pixels.

    Discussion

    All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Fills a specified rectangle in the current fill color, gradient, or pattern.

    Declaration

    JavaScript

    void fillRect (in float x, in float y, in float width, in float height);

    Parameters

    x

    The x-coordinate of the left edge of the rectangle, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the top edge of the rectangle, in pixels from the top of the canvas coordinate system.

    width

    The width of the rectangle, in pixels.

    height

    The height of the rectangle, in pixels.

    Discussion

    All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates a rectangular subpath.

    Declaration

    JavaScript

    void rect (in float x, in float y, in float width, in float height);

    Parameters

    x

    The x-coordinate of the left edge of the rectangle, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the top of the rectangle, in pixels from the top of the canvas coordinate system.

    width

    The width of the rectangle, in canvas coordinate units.

    height

    The height of the rectangle, in canvas coordinate units.

    Discussion

    Creates a rectangular subpath that can be filled or stroked. The rectangle is not drawn until the stroke() or fill() method is called. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Draws a rectangle using the current stroke color, pattern, or gradient.

    Declaration

    JavaScript

    void strokeRect ();

    Parameters

    x

    The left edge of the rectangle, in units right from the origin of the canvas coordinate system.

    y

    The top of the rectangle, in units down from the origin of the canvas coordinate system.

    width

    The width of the rectangle, in canvas coordinate units.

    height

    The height of the rectangle, in canvas coordinate units.

    Discussion

    All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • arc

    Creates an arc at the specified x,y position, of the specified radius, from the specified start angle to the specified end angle, either clockwise (the default) or counterclockwise.

    Declaration

    JavaScript

    void arc (in float x, in float y, in float radius, in float startAngle, in float endAngle, in boolean anticlockwise);

    Parameters

    x

    The x-coordinate of the starting point of the arc, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the starting point of the arc, in pixels from the top of the canvas coordinate system.

    radius

    The radius of the arc, in pixels.

    startAngle

    The starting angle of the arc, in radians, with 0 being east.

    endAngle

    The ending angle of the arc, in radians, with 0 being east.

    anticlockwise

    If this parameter is provided, the arc is drawn counterclockwise. If this parameter is omitted, the arc is drawn clockwise.

    Discussion

    The x, y, and radius parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Connects the specified end points with an arc of the specified radius.

    Declaration

    JavaScript

    void arcTo (in float x1, in float y1, in float x2, in float y2, in float radius);

    Parameters

    x1

    The x-coordinate of the starting point of the arc, in pixels from the left edge of the canvas coordinate system.

    y1

    The y-coordinate of the starting point of the arc, in pixels from the top of the canvas coordinate system.

    x2

    The x-coordinate of the ending point of the arc, in pixels from the left edge of the canvas coordinate system.

    y2

    The y-coordinate of the ending point of the arc, in pixels from the top of the canvas coordinate system.

    radius

    The radius of the circle from which this arc would be a section, in pixels.

    Discussion

    Use this method to insert an arc into a path. The curvature of the arc is determined by the radius. The larger the radius, the shallower the arc. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Denotes the beginning of new path.

    Declaration

    JavaScript

    void beginPath ();

    Discussion

    Any calls to arcTo, bezierCurveTo, lineTo, moveTo, or quadraticCurveTo after a call to beginPath add elements to a single path. A subsequent call to strokePath or fillPath outlines or fills the shape defined by the path. It is not necessary to close a path in order to draw it.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Adds a Bezier curve from the current point on the path to the specified end point, using the two specified control points.

    Declaration

    JavaScript

    void bezierCurveTo (in float cp1x, in float cp1y, in float cp2x, in float cp2y, in float x, in float y);

    Parameters

    cp1x

    The x-coordinate of the first control point, in pixels from the left edge of the canvas coordinate system.

    cp1y

    The y-coordinate of the first control point, in pixels from the top of the canvas coordinate system.

    cp2x

    The x-coordinate of the second control point, in pixels from the left edge of the canvas coordinate system.

    cp2y

    The y-coordinate of the second control point, in pixels from the top of the canvas coordinate system.

    x

    The x-coordinate of the end point of the curve, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the end point of the curve, in pixels from the top of the canvas coordinate system.

    Discussion

    Use this method to insert a Bezier curve into a path. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Constrains the clipping region of the canvas to the current path.

    Declaration

    JavaScript

    void clip ();

    Discussion

    Use this method to treat the current path as a mask for drawing operations. For example, if you call drawImage() subsequent to calling clip(), the image is clipped at the borders of the current path.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates a line from the endpoint of the current path to the beginning point of the current subpath, creating a closed shape.

    Declaration

    JavaScript

    void closePath ();

    Discussion

    The current subpath may be the same as the current path, or it may be a separate discontinuous piece. A new subpath begins after a moveTo() or closePath() method is called.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Determines whether a specified point is within the area defined by the current path.

    Declaration

    JavaScript

    boolean isPointInPath (in float x, in float y);

    Parameters

    x

    The x-coordinate of the point in the canvas coordinate system.

    y

    The y-coordinate of the point in the canvas coordinate system.

    Return Value

    Returns true if the point is within the path.

    Discussion

    All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 2.0 and later.

  • Adds a line segment to the current path, from the current endpoint to the specified new endpoint.

    Declaration

    JavaScript

    void lineTo (in float x, in float y);

    Parameters

    x

    The x-coordinate of the new endpoint in the canvas coordinate system.

    y

    The y-coordinate of the new endpoint in the canvas coordinate system.

    Discussion

    The line segment is not drawn until the path is stroked or filled. The specified x,y coordinates become the new endpoint of the path. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Moves the current endpoint of the current path without adding a line segment to the path, creating a new subpath.

    Declaration

    JavaScript

    void moveTo (in float x, in float y);

    Parameters

    x

    The x-coordinate of the new endpoint, in the canvas coordinate system.

    y

    The y-coordinate of the new endpoint, in the canvas coordinate system.

    Discussion

    Use this method to specify the beginning point of a new path, or to create a new endpoint without connecting it to the current endpoint, thereby creating a discontinuous subpath. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Adds a Bezier curve with a single control point to the current path.

    Declaration

    JavaScript

    void quadraticCurveTo (in float cpx, in float cpy, in float x, in float y);

    Parameters

    cpx

    The x-coordinate of the control point, in pixels from the left edge of the canvas coordinate system.

    cpy

    The y-coordinate of the control point, in pixels from the top of the canvas coordinate system.

    x

    The x-coordinate of the new endpoint, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the new endpoint, in pixels from the top of the canvas coordinate system.

    Discussion

    Adds a quadratic Bezier curve from the current endpoint on the current path to the specified new endpoint, with the shape of the curve determined by the control point. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Fills the current path using the current fill color, gradient, or pattern.

    Declaration

    JavaScript

    void fill ();

    Discussion

    The fill() method makes a solid shape from the current path, even if the path is not closed. For complex paths, it is possible to create a filled shape with a unfilled areas. For example, to create a doughnut, rather than a circle, create a circular subpath, going clockwise or or counterclockwise, then create another circular subpath, completely inside the first circle or completely surrounding it, with the second circle going in the opposite direction clockwise from the first circle. The area between the two circles is filled, but the interior of the smaller circle is not. The fill() method uses the non-zero number winding rule to determine whether a point within a path should be filled or not.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • fillStyle Property

    A CSS color, a gradient, or a pattern used to fill shapes and text.

    Declaration

    JavaScript

    attribute custom fillStyle

    Discussion

    This property can be set to any CSS color—for example “red”, rgb(255,0,0), #ff0000, or rgba(255,0,0,1). This property can also be set to a gradient object or a pattern object.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • lineCap Property

    A string specifying the type of end cap to put on lines to be drawn using lineTo().

    Declaration

    JavaScript

    attribute DOMString lineCap

    Discussion

    Possible values are butt (no end cap), round (round end cap half a line width in radius), and square (square end cap half a line width thick).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • lineJoin Property

    A string specifying the manner in which line joins are drawn.

    Declaration

    JavaScript

    attribute DOMString lineJoin

    Discussion

    A join exists at any point in a subpath shared by two consecutive lines. When a subpath is closed, then a join also exists at its first point (equivalent to its last point) connecting the first and last lines in the subpath.

    In addition to the point where the join occurs, two additional points are relevant to each join, one for each line: the two corners found half the line width away from the join point, one perpendicular to each line, each on the side furthest from the other line.

    A filled triangle connecting these two opposite corners with a straight line, with the third point of the triangle being the join point, must be rendered at all joins. The lineJoin attribute controls whether anything else is rendered.

    Possible values are bevel (default), round, and miter.

    The bevel value means that this is all that is rendered at joins.

    The round value means that a filled arc connecting the two aforementioned corners of the join, abutting (and not overlapping) the aforementioned triangle, with the diameter equal to the line width and the origin at the point of the join, must be rendered at joins.

    The miter value means that a second filled triangle must (if it can given the miter length) be rendered at the join, with one line being the line between the two aforementioned corners, abutting the first triangle, and the other two being continuations of the outside edges of the two joining lines, as long as required to intersect without going over the miter length.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

    See Also

    miterLimit

  • lineWidth Property

    A floating-point number that controls the width of lines and strokes, in pixels.

    Declaration

    JavaScript

    attribute float lineWidth

    Discussion

    The default line width is 1 pixel. This property specifies not only the width of lines drawn with lineTo(), but also the stroke thickness of any stroke() operation.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • miterLimit Property

    A floating-point number that controls the miter limit ratio for mitered line joins.

    Declaration

    JavaScript

    attribute float miterLimit

    Discussion

    The miterLimit value must be a nonzero positive number. This property affects the appearance of line joins when the lineJoin property is set to miter.

    The miter length is the distance from the point where the join occurs to the intersection of the line edges on the outside of the join. The miter limit ratio is the maximum allowed ratio of the miter length to half the line width. If the miter length would cause the miter limit ratio to be exceeded, the second triangle of the miter join is not rendered, and the join is beveled.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Draws the outline of the current path using the current stroke style and line width.

    Declaration

    JavaScript

    void stroke ();

    Discussion

    The stroke style can be a color, gradient, or pattern.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • strokeStyle Property

    A CSS color, a gradient, or a pattern used to stroke lines and shapes.

    Declaration

    JavaScript

    attribute custom strokeStyle

    Discussion

    This property may be set to any CSS color, to a pattern object, or to a linear or radial gradient object. When the stroke(), strokeRect(), or strokeText() operation is performed, the lines are drawn using the style specified by strokeStyle.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Draws the specified image with its upper-left corner at the specified point on the canvas, optionally scaling the image to a specified width and height. Alternatively, draws a specified region of the image, mapped to a specified region of the canvas.

    Declaration

    JavaScript

    void drawImage (in image image, in double x, in double y);

    Parameters

    image

    An image object (an img, canvas, or video element).

    x

    The x-coordinate of the left edge of the destination for the drawing, in pixels from the left edge of the canvas coordinate system.

    y

    The y-coordinate of the top of the destination for the drawing, in pixels from the top of the canvas coordinate system.

    ow

    The width of the drawn image. This parameter is optional; if omitted, the native width of the image is used. If present, the image is scaled to this width.

    oh

    The height of the drawn image. This parameter is dependent on the ow parameter—if ow is supplied, oh must also be supplied; if ow is omitted, oh must be omitted. If omitted, the native height of the image is used. If present, the image is scaled to this height.

    sx

    The x-coordinate of the left edge of the region of the image to draw, in pixels from the left edge of the image.

    sy

    The y-coordinate of the top of the region of the image to draw, in pixels from the top of the image.

    sw

    The width of the region of the image to draw.

    sh

    The height of the region of the image to draw.

    dx

    The x-coordinate of the left edge of the region of the canvas where the image is to be drawn, in pixels from the left edge of the canvas coordinate system.

    dy

    The y-coordinate of the top of the region of the canvas where the image is to be drawn, in pixels from the top of the canvas coordinate system.

    dw

    The width of the drawn image. The specified region of the image is scaled to this width.

    dh

    The height of the drawn image. The specified region of the image is scaled to this height.

    Discussion

    The image object can be an img element, a canvas element, or a video element. Use of the video element is not supported in Safari on iOS, however.

    If you supply only the image and the x and y coordinates, the image is drawn at its native size at the specified x,y coordinates.

    If you supply a width and height, in addition to the image and x,y coordinates, the image is scaled to the specified width and height when it is drawn.

    If you specify the image, a source x and y, a source width and height, a destination x and y, and a destination width and height, the specified region of the image is drawn at the specified x,y coordinates on the canvas, scaled to the specified destination width and height.

    All drawing is subject to the current clipping region.

    All destination parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on). Source parameter values (sx, sy, sw, and sh) are in CSS pixels, and are not affected by the transformation matrix.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Draws a line of text at the specified x,y coordinates, optionally scaled to a specified maximum width.

    Declaration

    JavaScript

    void fillText ();

    Parameters

    text

    A string containing the text to draw.

    x

    The x-coordinate of the textAlign point (the left edge, right edge, or center of the text).

    y

    The y-coordinate of the textBaseline point.

    maxWidth

    The maximum width of the string, in pixels. This parameter is optional. If omitted, the current font size is used and text is clipped if it falls outside the canvas’s clipping region. If a maximum width is specified, the font size is scaled down if necessary to fit the text inside the specified width.

    Discussion

    Text is rendered in the current font, with the current textBaseline aligned with the y-coordinate and the current textAlign point (left, center, or right) aligned with the x-coordinate. The x, y, and maxWidth parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • font Property

    A string containing font settings, such as the font family, size, and weight.

    Declaration

    JavaScript

    attribute DOMString font

    Discussion

    Set this property to a string specifying all the font properties you wish to set, just as you would the CSS font property. Note that you must use the combined (all-in-one) font settings string. Setting individual font properties such as font-size is not supported.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Determines the width of the bounding box required to render the specified text with the current font settings.

    Declaration

    JavaScript

    TextMetrics measureText (in DOMString text);

    Parameters

    text

    A string containing the text to measure.

    Return Value

    An object whose width property contains the width in pixels of the bounding box needed to render the text without clipping.

    Discussion

    Use this method to determine how much space is needed to render a string, or to measure the width of an existing string.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Draws a line of text in outline at the specified x,y coordinates, optionally limited to a specified maximum width.

    Declaration

    JavaScript

    void strokeText ();

    Parameters

    text

    A string containing the text to draw.

    x

    The x-coordinate of the textAlign point (the left edge, right edge, or center of the text).

    y

    The y-coordinate of the textBaseline point.

    maxWidth

    The maximum width of the string, in pixels. This parameter is optional. If omitted, the string is drawn in the current font style; any text falling outside the canvas clipping region is clipped. If this parameter is provided, and the text would exceed the specified width, the text is scaled down until it fits within the specified width.

    Discussion

    The x, y, and maxWidth parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • textAlign Property

    A string that specifies whether text is left-justified, right-justified, or centered.

    Declaration

    JavaScript

    attribute DOMString textAlign

    Discussion

    Possible values are start (default), end, left, right, and center. The values start and end are equivalent to either left or right, depending on the text direction.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • textBaseline Property

    A string that specifies how the bounding box aligns vertically relative to the y-coordinate.

    Declaration

    JavaScript

    attribute DOMString textBaseline

    Discussion

    The y-coordinate of a line of text corresponds to the point on the text glyphs specified by textBaseline. Possible values are top, hanging, middle, alphabetic (default), ideographic, and bottom. The position of each value on the text glyphs is illustrated in Figure 1.

    Figure 1Text baseline values image: ../Art/baselines.jpg

    See textBaseline Constants for descriptions of the constants.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Rotates the canvas coordinate system.

    Declaration

    JavaScript

    void rotate (in float angle);

    Parameters

    angle

    The amount of rotation, in radians, clockwise.

    Discussion

    Changes to the coordinate system affect subsequent drawing operations, but do not affect anything already drawn. Rotation is clockwise around the origin, which by default is the upper-left corner.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Scales the canvas coordinate system horizontally and vertically.

    Declaration

    JavaScript

    void scale (in float sx, in float sy);

    Parameters

    sx

    The horizontal scalar.

    sy

    The vertical scalar.

    Discussion

    Drawing operations can be scaled up or down by setting the scale. All drawing operation x and y coordinates, widths and heights are multiplied by the scalars. The scalars must be nonzero, but may be negative (which reverses the sign of subsequent x and y coordinates.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Sets the transformation matrix.

    Declaration

    JavaScript

    void setTransform (in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);

    Parameters

    m11

    Column 1 row 1 matrix value (a).

    m12

    Column 1 row 2 matrix value (b).

    m21

    Column 2 row 1 matrix value (c).

    m22

    Column 2 row 2 matrix value (d).

    dx

    X scalar value (e).

    dy

    Y scalar value (f).

    Discussion

    Replaces the current transformation matrix with the matrix shown in Figure 2. Each point in the canvas coordinate system is multiplied by the transformation matrix.

    Figure 2The transformation matrix image: ../Art/matrix.jpg

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Transforms the current transformation matrix using another matrix.

    Declaration

    JavaScript

    void transform (in float m11, in float m12, in float m21, in float m22, in float dx, in float dy);

    Parameters

    m11

    Column 1 row 1 matrix value (a).

    m12

    Column 1 row 2 matrix value (b).

    m21

    Column 2 row 1 matrix value (c).

    m22

    Column 2 row 2 matrix value (d).

    dx

    X scalar (e).

    dy

    Y Scalar (f).

    Discussion

    This method replaces the current transformation matrix with the result of a matrix multiplication between the current transformation matrix and the specified transformation matrix shown in Figure 3.

    Figure 3The transformation matrix image: ../Art/matrix.jpg

    Availability

    Available in Safari 3.1 and later.

    Available in iOS 2.0 and later.

  • Moves the origin of the canvas coordinate system.

    Declaration

    JavaScript

    void translate (in float tx, in float ty);

    Parameters

    tx

    The x-coordinate in the current canvas coordinate system to be made the new origin.

    ty

    The y-coordinate in the current canvas coordinate system to be made the new origin.

    Discussion

    The specified point x,y in the canvas coordinate system becomes the point 0,0 and the entire coordinate system is translated accordingly.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Saves the current context settings on the stack.

    Declaration

    JavaScript

    void save ();

    Discussion

    You can save and restore all of the context settings: rotation, scale, translation, transformation matrix, stroke and fill styles, and text settings. This is a very fast, nestable operation.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Restores the last saved set of context settings.

    Declaration

    JavaScript

    void restore ();

    Discussion

    You can save and restore all of the context settings: rotation, scale, translation, transformation matrix, stroke and fill styles, and text settings. This is a very fast, nestable operation.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • globalAlpha Property

    A floating-point number controlling the degree of opacity for all drawing operations.

    Declaration

    JavaScript

    attribute float globalAlpha

    Discussion

    Set the globalAlpha to any value between 0 and 1, inclusive, to set the degree of opacity for all subsequent drawing operations, with 0 being completely transparent and 1 being completely opaque. Any pixels drawn subsequently have their alpha channel value multiplied by the globalAlpha value.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • A string representing the compositing method for drawing operations.

    Declaration

    JavaScript

    attribute DOMString globalCompositeOperation

    Discussion

    By default, drawings layer on top of one another in drawing order, with opaque areas obscuring existing layers and transparent or translucent areas being blended with existing layers according to their alpha value. Set the globalCompositeOperation property to one of the globalCompositeOperation constants to override the default compositing method. The allowed values are source-atop, source-in, source-out, source-over, destination-atop, destination-in, destination-out, destination-over, lighter, copy, and xor. See Global Compositing Operation Constants for details.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates a linear gradient object with a specified start point and a specified end point.

    Declaration

    JavaScript

    CanvasGradient createLinearGradient (in float x0, in float y0, in float x1, in float y1);

    Parameters

    x0

    The x-coordinate of the starting point, in pixels from the left edge of the canvas coordinate system.

    y0

    The y-coordinate of the starting point, in pixels from the top of the canvas coordinate system.

    x1

    The x-coordinate of the ending point, in pixels from the left edge of the canvas coordinate system.

    y1

    The y-coordinate of the ending point, in pixels from the top of the canvas coordinate system.

    Return Value

    A linear gradient object.

    Discussion

    You must add at least a starting and ending color stop to a linear gradient before it can be used. The direction of the gradient is specified by the start and end points. When setting the fill style or stroke style for drawing objects, you can pass in a linear gradient object instead of a color. Anything subsequently drawn or filled over the rectangle defined by the starting and ending points of the gradient are rendered using the gradient as a color. Anything drawn outside the rectangle is rendered using the color stop of the nearest edge of the rectangle. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates a pattern object using the specified image as a template. The pattern can be specified as repeating horizontally, vertically, both horizontally and vertically (the default), or not at all.

    Declaration

    JavaScript

    void createPattern ();

    Parameters

    image

    An image object.

    repeat

    An optional string. If the string value is "repeat-x", the pattern repeats horizontally only. If the string value is "repeat-y", the pattern repeats vertically only. If the string value is "repeat-none", the pattern does not repeat. If this parameter is omitted, the pattern repeats both horizontally and vertically.

    Discussion

    When specifying a stroke style or fill style, you can pass in a pattern object instead of a color. Subsequent drawing operations are stroked or filled using the specified image as a pattern. An image object can be obtained by setting a JavaScript variable equal to an HTML img element.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates a radial gradient object using the cone defined by the specified starting and ending circles.

    Declaration

    JavaScript

    CanvasGradient createRadialGradient (in float x0, in float y0, in float r0, in float x1, in float y1, in float r1);

    Parameters

    x0

    The x-coordinate of the center of the starting circle, in pixels from the left edge of the canvas coordinate system.

    y0

    The y-coordinate of the center of the starting circle, in pixels from the top of the canvas coordinate system.

    r0

    The radius of the starting circle.

    x1

    The x-coordinate of the center of the ending circle, in pixels from the left edge of the canvas coordinate system.

    y1

    The y-coordinate of the center of the ending circle, in pixels from the top of the canvas coordinate system.

    r1

    The radius of the ending circle.

    Return Value

    A radial gradient object.

    Discussion

    You must add at least a starting and ending color stop to a radial gradient before it can be used. The direction of the gradient is specified by the starting and ending circles. When setting the fill style or stroke style for drawing objects, you can pass in a radial gradient object instead of a color. Anything subsequently drawn or filled over the cone defined by the starting and ending circles of the gradient is rendered using the gradient as a color. Anything drawn outside the cone is rendered using the color stop of the nearest edge of the cone. All parameter values are in the canvas’s current coordinate system, subject to the current transformation matrix (rotation, scale, and so on).

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • Creates an opaque object whose data property contains a one-dimensional array of pixel values, initialized to transparent black.

    Declaration

    JavaScript

    ImageData createImageData ();

    Parameters

    sw

    The width of the pixel array.

    sh

    The height of the pixel array.

    Return Value

    An imageData object.

    Discussion

    This method is typically used to create additional pixel arrays that can be blitted to the canvas in a single operation. You can optionally pass in another imageData object as a parameter, instead of a width and height, to create a new imageData object with the same pixel dimensions as the specified object.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Gets an imageData object containing an RGBa pixel array corresponding to a rectangular area of the canvas.

    Declaration

    JavaScript

    ImageData getImageData (in float sx, in float sy, in float sw, in float sh);

    Parameters

    sx

    The x-coordinate of the left edge of the rectangle.

    sy

    The y-coordinate of the top of the rectangle.

    sw

    The width of the rectangle.

    sh

    The height of the rectangle.

    Return Value

    An imageData object.

    Discussion

    All parameter values are in pixels relative to the upper-left corner of the canvas, not the current canvas coordinate system. The returned imageData object has two read-only properties: width and height. The imageData object’s data property is a one-dimensional array of RGBa pixel values in row order from left to right, with four values for each pixel—red, green, blue, and alpha. The RGBa values are integers with a range of 0-255, inclusive.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Blits the contents of an imageData object to the canvas. Alternatively, blits a specified region of the imageData object to the canvas.

    Declaration

    JavaScript

    void putImageData (in imageData imageData, in double x, in double y);

    Parameters

    imageData

    An imageData object, containing a pixel array.

    x

    The x-coordinate of the section of the canvas on which to render the image data.

    y

    The x-coordinate of the section of the canvas on which to render the image data.

    dx

    The x-coordinate of the left edge of the region of the imageData pixel array to render.

    dy

    The y-coordinate of the top of the region of the imageData pixel array to render.

    dw

    The width of the region of the imageData pixel array to render.

    dh

    The height of the region of the imageData pixel array to render.

    Discussion

    This method blits either an imageData pixel array, or a region of the pixel array, to the canvas, at the specified x,y coordinates.

    If only the imageData object and an x,y coordinate pair are passed in, the entire imageData object is rendered immediately to the screen.

    If additional x, y, width, and height parameters are passed in, only the specified region of the imageData pixel array is rendered to the screen. The region of the imageData pixel array is rendered on the canvas in the same relative position on the canvas as it would be if the whole pixel array had been rendered.

    No parameters are individually optional—either just three or all seven parameters must be passed in.

    All x and y parameter values are in CSS pixels—they are unaffected by scaling, rotation, or other transformations to the canvas coordinate system.

    Availability

    Available in Safari 4.0 and later.

    Available in iOS 3.0 and later.

  • Turns shadows off.

    Declaration

    JavaScript

    void clearShadow ();

    Discussion

    When you set a shadow color or shadow blur, and a shadow offset, all subsequent drawing operations include a shadow of the current color and blur, at the specified offset. The clearShadow method is a convenient way to turn shadows off.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • shadowBlur Property

    A floating-point number that controls the degree of Gaussian blur applied to shadows.

    Declaration

    JavaScript

    attribute float shadowBlur

    Discussion

    If shadows are enabled, each shadow has a Gaussian blur applied to its alpha value, with a standard deviation of shadowBlur. The shadowBlur value must be a positive number, and may be zero.

    Shadows are cast if the value of the shadowBlur property is nonzero and the alpha value of shadowColor is nonzero.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • shadowColor Property

    A string that contains the RGBa color value of shadows.

    Declaration

    JavaScript

    attribute DOMString shadowColor

    Discussion

    The value may be any CSS color value. If the alpha value of shadowColor is nonzero, shadows are cast, provided that at least one of the three properties shadowBlur, shadowOffsetX, or shadowOffsetY is also nonzero.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • shadowOffsetX Property

    A floating-point number that controls the horizontal offset of shadows from the elements casting the shadows.

    Declaration

    JavaScript

    attribute float shadowOffsetX

    Discussion

    Shadows are cast shadowOffsetX pixels to the right, regardless of the canvas rotation, scale, or transformation. If shadowOffsetX is negative, shadows are cast to the left.

    Shadows are cast if shadowOffsetX is nonzero and the alpha value of shadowColor is nonzero.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

  • shadowOffsetY Property

    A floating-point number that controls the vertical offset of shadows from the elements casting the shadows.

    Declaration

    JavaScript

    attribute float shadowOffsetY

    Discussion

    Shadows are cast shadowOffsetY pixels down, regardless of the canvas rotation, scale, or transformation. If shadowOffsetY is negative, shadows are cast up.

    Shadows are cast if shadowOffsetY is nonzero and the alpha value of shadowColor is nonzero.

    Availability

    Available in Safari 3.0 and later.

    Available in iOS 1.0 and later.

Constants

  • Constants used to set the globalCompositeOperation property.

    Declaration

    Constants

    • source-atop

      source-atop

      Display the source image wherever both images are opaque. Display the destination image wherever the destination image is opaque but the source image is transparent. Display transparency elsewhere.

    • source-in

      source-in

      Display the source image wherever both the source image and destination image are opaque. Display transparency elsewhere.

    • source-out

      source-out

      Display the source image wherever the source image is opaque and the destination image is transparent. Display transparency elsewhere.

    • source-over

      source-over

      Display the source image wherever the source image is opaque. Display the destination image elsewhere.

    • destination-atop

      destination-atop

      Same as source-atop but using the destination image instead of the source image and vice versa.

    • destination-in

      destination-in

      Same as source-in but using the destination image instead of the source image and vice versa.

    • destination-out

      destination-out

      Same as source-out but using the destination image instead of the source image and vice versa.

    • destination-over

      destination-over

      Same as source-over but using the destination image instead of the source image and vice versa.

    • lighter

      lighter

      Display the sum of the source image and destination image, with color values approaching 255 (100%) as a limit.

    • copy

      copy

      Display the source image instead of the destination image.

    • xor

      xor

      Display the exclusive OR of the source image and the destination image.

    Import Statement

  • Constants used to set the textBaseline property that specify the vertical alignment of the bounding box relative to its y-coordinate.

    Declaration

    Constants

    • top

      top

      Aligns the y-coordinate of the bounding box with top of text glyphs.

    • hanging

      hanging

      Aligns the y-coordinate of the bounding box just below the top of text glyphs.

    • middle

      middle

      Aligns the y-coordinate of the bounding box with the middle of text glyphs.

    • alphabetic

      alphabetic

      Aligns the y-coordinate of the bounding box with the bottom of alphabetic text glyphs without descenders.

    • ideographic

      ideographic

      Aligns the y-coordinate of the bounding box with the bottom of ideographic text glyphs.

    • bottom

      bottom

      Aligns the y-coordinate of the bounding box with the bottom of text glyphs with descenders.

    Import Statement

  • Constants used with the textAlign property that specify the horizontal alignment of the bounding box relative to its x-coordinate.

    Declaration

    Constants

    • left

      left

      Specifies left-justified text. The right edge of the bounding box is aligned with the x-coordinate.

    • right

      right

      Specifies right-justified text. The left edge of the bounding box is aligned with the x-coordinate.

    • center

      center

      Specifies centered text. The middle of the bounding box is aligned with the x-coordinate.

    • start

      start

      Specifies left- or right-justified text, depending on the text direction.

    • end

      end

      Specifies left- or right-justified text, depending on the text direction.

    Import Statement