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.

  • Clears the specified rectangle to transparent black—RGBa(0,0,0,0).

    Declaration

    voidclearRect (in floatx, in floaty, in floatwidth, in floatheight);

    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.

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

    Declaration

    voidfillRect (in floatx, in floaty, in floatwidth, in floatheight);

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

  • Creates a rectangular subpath.

    Declaration

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

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

    Declaration

    voidstrokeRect (in double x, in double y, in double width, in double height);

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

Paths are made up of line segments, curves, and arcs. A path is drawn when you call the fill() or stroke() methods.

  • 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

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

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

    Declaration

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

  • Denotes the beginning of new path.

    Declaration

    voidbeginPath ();

    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.

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

    Declaration

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

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

    Declaration

    voidclip ();

    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.

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

    Declaration

    voidclosePath ();

    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.

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

    Declaration

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

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

    Declaration

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

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

    Declaration

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

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

    Declaration

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

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

    Declaration

    voidfill ();

    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.

  • fillStyle Property

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

    Declaration

    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.

  • lineCap Property

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

    Declaration

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

  • lineJoin Property

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

    Declaration

    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.

    See Also

    miterLimit

  • lineWidth Property

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

    Declaration

    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.

  • miterLimit Property

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

    Declaration

    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.

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

    Declaration

    voidstroke ();

    Discussion

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

  • strokeStyle Property

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

    Declaration

    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.

  • 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

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

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

    Declaration

    voidfillText (in DOMString text in double x in double y optional in double maxWidth);

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

  • font Property

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

    Declaration

    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.

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

    Declaration

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

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

    Declaration

    voidstrokeText (in DOMString text, in double x, in double y, optional in double maxWidth);

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

  • textAlign Property

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

    Declaration

    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.

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

    Declaration

    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.

The current transformation matrix is applied to the canvas coordinate system. These methods modify the current transformation matrix.

  • Rotates the canvas coordinate system.

    Declaration

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

  • Scales the canvas coordinate system horizontally and vertically.

    Declaration

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

  • Sets the transformation matrix.

    Declaration

    voidsetTransform (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
  • Transforms the current transformation matrix using another matrix.

    Declaration

    voidtransform (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
  • Moves the origin of the canvas coordinate system.

    Declaration

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

  • Saves the current context settings on the stack.

    Declaration

    voidsave ();

    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.

  • Restores the last saved set of context settings.

    Declaration

    voidrestore ();

    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.

  • globalAlpha Property

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

    Declaration

    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.

  • A string representing the compositing method for drawing operations.

    Declaration

    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.

Gradients or patterns can be used instead of colors as the stroke or fill style.

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

    Declaration

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

  • 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

    voidcreatePattern (in image image, in DOMString repeat);

    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.

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

    Declaration

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

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

    Declaration

    ImageDatacreateImageData (in float sw, in float sh);

    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.

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

    Declaration

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

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

    Declaration

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

If shadows are enabled, all stroke(), fill(), and drawImage() operations include a shadow. Shadows need not be turned on or off using a method. You can enable or disable shadows by setting the shadowColor, shadowBlur, shadowOffsetX, and shadowOffsetY properties.

  • Turns shadows off.

    Declaration

    voidclearShadow ();

    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.

  • shadowBlur Property

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

    Declaration

    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.

  • shadowColor Property

    A string that contains the RGBa color value of shadows.

    Declaration

    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.

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

    Declaration

    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.

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

    Declaration

    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.

Constants

  • Constants used to set the globalCompositeOperation property.

    Declaration

    Constants

    • 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

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

    • source-out

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

    • source-over

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

    • destination-atop

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

    • destination-in

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

    • destination-out

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

    • destination-over

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

    • lighter

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

    • copy

      Display the source image instead of the destination image.

    • xor

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

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

    Declaration

    Constants

    • top

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

    • hanging

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

    • middle

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

    • alphabetic

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

    • ideographic

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

    • bottom

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

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

    Declaration

    Constants

    • left

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

    • right

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

    • center

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

    • start

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

    • end

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