CanvasRenderingContext2D Class Reference

Inherits from
CanvasRenderingContext
Availability
Available in Safari 3.0 and later.
Available in iOS 1.0 and later.

Overview

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.

Tasks

Drawing Rectangles

Creating Paths (Lines, Curves, Arcs, and Shapes)

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

Filling and Stroking Lines and Paths

Drawing Images

Drawing Text

Changing the Coordinate System

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

Saving and Restoring Settings

Compositing

Creating Gradients and Patterns

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

Manipulating Pixels

Working with Shadows

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.

Properties

fillStyle

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

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
See Also

font

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

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

globalAlpha

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

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

globalCompositeOperation

A string representing the compositing method for drawing operations.

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

lineCap

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

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

lineJoin

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

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
See Also

lineWidth

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

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

miterLimit

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

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

shadowBlur

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

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

shadowColor

A string that contains the RGBa color value of shadows.

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

shadowOffsetX

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

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

shadowOffsetY

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

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

strokeStyle

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

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
See Also

textAlign

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

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

textBaseline

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

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 1  Text baseline values

See “textBaseline Constants” for descriptions of the constants.

Availability

Methods

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.

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.

arcTo

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

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.

beginPath

Denotes the beginning of new path.

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.

bezierCurveTo

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

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.

clearRect

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

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.

clearShadow

Turns shadows off.

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.

clip

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

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.

closePath

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

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.

createImageData

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

ImageData createImageData (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.

Availability
  • Available in Safari 4.0 and later.
  • Available in iOS 3.0 and later.

createLinearGradient

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

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.

createPattern

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.

void createPattern (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.

Availability
  • Available in Safari 3.0 and later.
  • Available in iOS 1.0 and later.

createRadialGradient

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

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.

drawImage

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.

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

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

void drawImage (in image image, in double sx, in double sy, in double sw, in double sh, in double dx, in double dy, in double dw, in double dh );
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.

fill

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

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.

fillRect

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

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.

fillText

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

void fillText (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).

Availability
  • Available in Safari 4.0 and later.
  • Available in iOS 3.0 and later.

getImageData

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

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.

isPointInPath

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

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.

lineTo

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

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.

measureText

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

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.

moveTo

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

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.

putImageData

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

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

void putImageData (in imageData imageData, in double x, in double y, in double dx, in double dy, in double dw, in double dh);
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.

quadraticCurveTo

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

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.

rect

Creates a rectangular subpath.

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.

restore

Restores the last saved set of context settings.

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.

rotate

Rotates the canvas coordinate system.

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.

save

Saves the current context settings on the stack.

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.

scale

Scales the canvas coordinate system horizontally and vertically.

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.

setTransform

Sets the transformation matrix.

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 2  The transformation matrix
Availability
  • Available in Safari 4.0 and later.
  • Available in iOS 3.0 and later.

stroke

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

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.

strokeRect

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

void strokeRect (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).

Availability
  • Available in Safari 3.0 and later.
  • Available in iOS 1.0 and later.

strokeText

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

void strokeText (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).

Availability
  • Available in Safari 4.0 and later.
  • Available in iOS 3.0 and later.

transform

Transforms the current transformation matrix using another matrix.

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 3  The transformation matrix
Availability
  • Available in Safari 3.1 and later.
  • Available in iOS 2.0 and later.

translate

Moves the origin of the canvas coordinate system.

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.

Constants

Global Compositing Operation Constants

Constants used to set the globalCompositeOperation property.

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.

textBaseline Constants

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

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.

textAlign Constants

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

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.