diff options
Diffstat (limited to 'doc/src/webkit/guide/chapter_canvas.qdoc')
| -rw-r--r-- | doc/src/webkit/guide/chapter_canvas.qdoc | 909 |
1 files changed, 358 insertions, 551 deletions
diff --git a/doc/src/webkit/guide/chapter_canvas.qdoc b/doc/src/webkit/guide/chapter_canvas.qdoc index a2688f8..eea2236 100644 --- a/doc/src/webkit/guide/chapter_canvas.qdoc +++ b/doc/src/webkit/guide/chapter_canvas.qdoc @@ -40,55 +40,55 @@ /*! \page qtwebkit-guide-canvas.html -\title Canvas Graphics +\title QtWebKit Guide - Canvas Graphics \chapter Canvas Graphics +This section of the \l{QtWebKit Guide} serves as an introduction to the +\l{HTML5 Canvas API} features of QtWebKit. -HTML5\'s Canvas API enables you to draw within a Web page or Web App -using JavaScript. After you define a rectangle that serves as your -drawing canvas, you can draw straight and curved lines, simple -and complex shapes, graphs, and referenced graphic images. You can add -text, color, shadows, gradients, and patterns. The canvas API also enables -you to save or export the canvas as a .png or .jpeg image file. +The \l{HTML5 Canvas API} enables you to draw within a Web page or Web App using +JavaScript. After you define a rectangle that serves as your drawing canvas, you +can draw straight and curved lines, simple and complex shapes, graphs, and +referenced graphic images. You can add text, color, shadows, gradients, and +patterns. The canvas API also enables you to save or export the canvas as a .png +or .jpeg image file. -To define the drawing area, set the \c{width} and \c{height} of a -\c{<canvas>} element. For example, the following sets a drawing area -with a height of 100 pixels and width of 200 pixels: +To define the drawing area, set the \c{width} and \c{height} of a \c{<canvas>} +element. For example, the following sets a drawing area with a height of 100 +pixels and width of 200 pixels: \code <canvas id="mycanvas" width="100" height="200"></canvas> \endcode -By default, \c{canvas} elements are sized 150 pixels high and 300 -pixels wide. You can also set the size of the canvas using CSS: +By default, \c{canvas} elements are sized 150 pixels high and 300 pixels wide. +You can also set the size of the canvas using CSS: \code canvas { height : 200px; width : 100px; } \endcode -The \c{canvas} element is transparent and has no visible borders until -you \l{Accessing the Rendering Context}{access the 2D rendering -context}. +The \c{canvas} element is transparent and has no visible borders until you +\l{Accessing the Rendering Context}{access the 2D rendering context}. -Resetting the width or height of an existing canvas erases its -contents and resets all the context properties of the canvas to their -default values. +Resetting the width or height of an existing canvas erases its contents and +resets all the context properties of the canvas to their default values. \section1 Accessing the Rendering Context -The rendering \bold{context} defines the methods and attributes needed -to draw on the canvas. QtWebKit currently supports the two-dimensional -rendering context. The following assigns the canvas rendering context -to a \c{context} variable: +The rendering \bold{context} defines the methods and attributes needed to draw +on the canvas. QtWebKit currently supports the two-dimensional rendering +context. The following assigns the canvas rendering context to a \c{context} +variable: \code var context = canvas.getContext("2d") \endcode -The 2d context renders the canvas as a coordinate system whose origin -(0,0) is at the top left corner, as shown in the figure below. -Coordinates increase along the \c{x} axis from left to right and along -the \c{y} axis from top to bottom of the canvas. +The 2d context renders the canvas as a coordinate system whose origin (0,0) is +at the top left corner, as shown in the figure below. Coordinates increase along +the \c{x} axis from left to right and along the \c{y} axis from top to bottom of +the canvas. \image webkit-guide/canvas_context.gif @@ -96,6 +96,7 @@ the \c{y} axis from top to bottom of the canvas. The 2D rendering context supports rectangles, lines, and arcs, which you can combine to build complex shapes and graphic images. + \section2 Drawing Rectangles The rectangle is the only geometric shape that is built in to the @@ -113,17 +114,12 @@ you can combine to build complex shapes and graphic images. Each method accepts the following series of arguments: \list - \o \c{x} is the position on the canvas to the right of the origin (0,0) of the top left corner of the rectangle - \o \c{y} is the position on the canvas below the origin of the top left corner of the rectangle - \o \c{width} is the width of the rectangle to be drawn - \o \c{height} is the height of the rectangle to be drawn - \endlist For example, the following code draws concentric rectangles: @@ -139,7 +135,7 @@ you can combine to build complex shapes and graphic images. \section2 Drawing Lines - To draw a line, you first have to "put your pencil down" on the canvas + To draw a line, you first have to \e{"put your pencil down"} on the canvas by creating a path. The \c{context.beginPath()} method sets a new path in the canvas. Each line that you draw is stored as a sub-path. Sub-paths can be closed to form a shape, or they can be left open. @@ -149,12 +145,12 @@ you can combine to build complex shapes and graphic images. After calling \c{beginPath()}, you set your starting position on the canvas by calling the \c{context.moveTo(x,y)} method. The \c{moveTo(x,y)} method creates a new subpath on the canvas that begins - at the point (x,y). + at the Cartesian point \c{(x,y)}. To draw a straight line, call the \c{context.lineTo(x,y)} method. This adds the point (x,y) to the current subpath and connects it to the previous subpath by a straight line. In other words, (x,y) are the - coordinates of the line\'s endpoint. For example: + coordinates of the line's endpoint. For example: \code context.beginPath(); @@ -162,24 +158,24 @@ you can combine to build complex shapes and graphic images. context.lineTo(30,30); \endcode - To get the "pencil" to actually draw on the canvas, first use the + To get the \e{pencil} to actually draw on the canvas, first use the \c{strokeStyle} property to set the color to a value such as black - (#000): + (\c{#000}): \code context.strokeStyle(#000); \endcode - (The \c{strokeStyle} property can be a CSS color, a pattern, or a - gradient.) Then use the \c{context.stroke()} method to actually draw - the line on the canvas: + (The \c{strokeStyle} property can be a CSS color, a pattern, or a gradient.) + Then use the \c{context.stroke()} method to actually draw the line on the + canvas: \code context.stroke(); \endcode - This produces the image below. The numeric coordinates are added for - clarity but are not part of the image drawn by the code: + This produces the image below. The numeric coordinates are added for clarity + but are not part of the image drawn by the code: \image webkit-guide/canvas_lineStrokeTo.gif @@ -205,59 +201,43 @@ you can combine to build complex shapes and graphic images. context.fill(); // fill the triangle \endcode - The above commands, if coded fully, would create the shape below: + The commands, if coded fully, would create the shape below: \image webkit-guide/canvas_closepath.gif - \bold{NOTE:} It is not necessary to close the path when calling the - \c{fill()} method. Calling \c{fill()} closes the path and creates the - completed shape. + \note It is not necessary to close the path when calling the \c{fill()} + method. Calling \c{fill()} closes the path and creates the completed shape. - You can draw lines of various widths, endcap types, and joining - options by configuring the following attributes: + You can draw lines of various widths, endcap types, and joining options by + configuring the following attributes: \list - - \o \c{lineWidth} sets the thickness of the current line. The value can - be any number greater than 0. For example, \c{context.lineWidth = 10} - sets the line thickness to 10 units. The default value is 1 unit, - which is not the same as 1 pixel. Instead, the line is centered on the - current path, with half its thickness on each side of the path. - - \o \c{lineCap} sets the type of endpoint of the current line. The - value can be either \c{butt}, \c{square}, or \c{round}. (The - default value is \c{butt}.) - + \o \c{lineWidth} sets the thickness of the current line. The value can be + any number greater than \c 0. For example, \c{context.lineWidth = 10} sets + the line thickness to \c 10 units. The default value is \c 1 unit, which is + not the same as \c 1 \e pixel. Instead, the line is centered on the current + path, with half its thickness on each side of the path. + \o \c{lineCap} sets the type of endpoint of the current line. The value can + be either \c{butt}, \c{square}, or \c{round}. (The default value is + \c{butt}.) \list - \o \c{butt}- the ends of the line abutt the line guide. - \o \c{square} adds a box at both ends of the line. - \o \c{round} adds a semicircle at both ends of the line. - \endlist \o \c{lineJoin} sets the style with which lines are joined. The value can be either \c{bevel}, \c{round}, or \c{miter}. (The default value is \c{miter}.) - - \list - - \o \c{bevel} flattens the corners at which the lines join - - \o \c{round} rounds the corners at which the lines join - - \o \c{miter} joins the lines at a single point - - \endlist - - \o \c{miterLimit} sets the miter limit ratio. The value can be any - number greater than 0. The miter limit ratio determines how far the - connection point of the outside of the lines can be from the - connection point of the inside of the lines. (The default value is - 10.) - + \list + \o \c{bevel} flattens the corners at which the lines join + \o \c{round} rounds the corners at which the lines join + \o \c{miter} joins the lines at a single point + \endlist + \o \c{miterLimit} sets the \e{miter limit ratio}. The value can be any + number greater than \c 0. The miter limit ratio determines how far the + connection point of the outside of the lines can be from the connection + point of the inside of the lines. (The default value is \c 10.) \endlist \image webkit-guide/canvas_linecap.png @@ -268,35 +248,30 @@ you can combine to build complex shapes and graphic images. a line: \list 1 - - \o Call the \c{context.beginPath()} method to "put your pencil down" on the - canvas and set a new path. - - \o Call the \c{context.moveTo(x,y)} method to set your starting - position on the canvas at the point (x,y). - - \o To draw an arc or circle, call the - \c{context.arcTo(x1,y1,x2,y2,radius)} method. This adds an arc with - starting point \c{(x1,y1)}, ending point \c{(x2,y2)}, and radius \c{radius} to the - current subpath and connects it to the previous subpath by a straight - line. + \o Call the \c{context.beginPath()} method to \e{"put your pencil down"} on + the canvas and set a new path. + \o Call the \c{context.moveTo(x,y)} method to set your starting position on + the canvas at the point (x,y). + \o To draw an arc or circle, call the \c{context.arcTo(x1,y1,x2,y2,radius)} + method. This adds an arc with starting point \c{(x1,y1)}, ending point + \c{(x2,y2)}, and radius \c{radius} to the current subpath and connects it to + the previous subpath by a straight line. \image webkit-guide/canvas_arcTo.png \o An alternative way to draw an arc or circle is to call the - \c{context.arc(x,y,radius,startAngle,endAngle,anticlockwise)} - method. This adds an arc to the current subpath that lies on the - circumference of the circle whose center is at the point (x,y) and - whose radius is \c{radius}. + \c{context.arc(x,y,radius,startAngle,endAngle,anticlockwise)} method. This + adds an arc to the current subpath that lies on the circumference of the + circle whose center is at the point (x,y) and whose radius is \c{radius}. \image webkit-guide/canvas_arcTo2.png - Both \c{startAngle} and \c{endAngle} are measured from the x axis in - units of radians. + Both \c{startAngle} and \c{endAngle} are measured from the x axis in units + of radians. - A complete circle is 360 degrees, or 2\pi radians. A semicircle is 180 - degrees, or \pi radians. The number of radians is the number of - degrees multiplied by \pi/180, expressed in JavaScript as: + A complete circle is \c 360 degrees, or 2\pi radians. A semicircle is \c 180 + degrees, or \pi radians. The number of radians is the number of degrees + multiplied by \pi/180, expressed in JavaScript as: \code var radians = (Math.PI/180)*degrees; @@ -327,42 +302,33 @@ you can combine to build complex shapes and graphic images. \endlist - \bold{NOTE:} It is not necessary to close the path if you are going to call + \note It is not necessary to close the path if you are going to call the \c{fill()} method. The fill closes the path and creates the completed shape. To create complex shapes, combine lines and arcs: \list 1 - - \o Call the \c{context.beginPath()} method to "put your pencil down" - on the canvas and set a new path. - - \o Call the \c{context.moveTo(x,y)} method to set your starting - position on the canvas at the point (x,y). - + \o Call the \c{context.beginPath()} method to \e{"put your pencil down"} on + the canvas and set a new path. + \o Call the \c{context.moveTo(x,y)} method to set your starting position on + the canvas at the point (x,y). \o Draw any combination of lines and arcs by calling the \c{lineTo}, - \c{arcTo}, \c{arc}, \c{moveTo}, \c{closePath}, \c{stroke}, and - \c{fill} methods and setting the line attributes and fill colors as - described above. - + \c{arcTo}, \c{arc}, \c{moveTo}, \c{closePath}, \c{stroke}, and \c{fill} + methods and setting the line attributes and fill colors as described above. \endlist - You can also create complex shapes by removing portions of the shapes - you draw. The \c{clip()} method creates a clipping path that defines - the area along which your "scissor" will cut. Any parts of the shape - outside the clipping path are not displayed. To create a complex shape - using the \c{clip()} method: + You can also create complex shapes by removing portions of the shapes you + draw. The \c{clip()} method creates a clipping path that defines the area + along which your "scissor" will cut. Any parts of the shape outside the + clipping path are not displayed. To create a complex shape using the + \c{clip()} method: \list 1 - \o Call the \c{context.beginPath()} method to set the clipping path. - - \o Define the clipping path by calling any combination of the - \c{lineTo}, \c{arcTo}, \c{arc}, \c{moveTo}, and \c{closePath} methods. - + \o Define the clipping path by calling any combination of the \c{lineTo}, + \c{arcTo}, \c{arc}, \c{moveTo}, and \c{closePath} methods. \o Call the \c{context.clip()} method. - \endlist The new shape displays. The following shows how a clipping path can @@ -372,217 +338,165 @@ you can combine to build complex shapes and graphic images. \section1 Compositing -You can build complex shapes by drawing shapes on top of each -other. It is also possible to draw shapes behind existing shapes and -to mask parts of shapes by using compositing operations. The -\c{globalCompositeOperation} attribute sets the way shapes can be -combined. +You can build complex shapes by drawing shapes on top of each other. It is also +possible to draw shapes behind existing shapes and to mask parts of shapes by +using \e{compositing operations}. The \c{globalCompositeOperation} attribute +sets the way shapes can be combined. -The first shape drawn on the canvas to which additional shapes are -added is called the destination shape. The shape drawn on the canvas -afterwards to create the composite image is called the source shape. -The value of the \c{globalCompositeOperation} attribute must be set to -one of the following: +The first shape drawn on the canvas to which additional shapes are added is +called the \e{destination} shape. The shape drawn on the canvas afterwards to +create the composite image is called the \e{source} shape. The value of the +\c{globalCompositeOperation} attribute must be set to one of the following: \list +\o \c{source-over} displays the source (newer) shape over the destination +(older) shape unless the source shape is transparent. (This is the default +value) -\o \c{source-over} displays the source (newer) shape over the -destination (older) shape unless the source shape is transparent. -(This is the default value) - -\o \c{source-in} displays only the portion of the source shape that is -opaque and overlaps the destination shape. Everything else is -transparent. +\o \c{source-in} displays only the portion of the source shape that is opaque +and overlaps the destination shape. Everything else is transparent. -\o \c{source-out} displays only the portion of the source shape that -does not overlap the destination shape. +\o \c{source-out} displays only the portion of the source shape that does not +overlap the destination shape. -\o \c{source-atop} displays only the portion of the opaque source -shape that overlaps the destination shape and the portion of the -destination shape that is not covered by the opaque source shape. +\o \c{source-atop} displays only the portion of the opaque source shape that +overlaps the destination shape and the portion of the destination shape that is +not covered by the opaque source shape. -\o \c{destination-over} displays the destination shape over the source -shape. In areas where both shapes are opaque and overlap, the older -shape displays. +\o \c{destination-over} displays the destination shape over the source shape. In +areas where both shapes are opaque and overlap, the older shape displays. -\o \c{destination-in} displays only the portion of the destination -shape that is opaque and overlaps the source shape. Everything else is -transparent. The source (newer) shape is not visible. +\o \c{destination-in} displays only the portion of the destination shape that is +opaque and overlaps the source shape. Everything else is transparent. The source +(newer) shape is not visible. -\o \c{destination-out} displays only the portion of the destination -shape that does not overlap the source shape. The source shape is not -visible. +\o \c{destination-out} displays only the portion of the destination shape that +does not overlap the source shape. The source shape is not visible. -\o \c{destination-atop} displays only the portion of the opaque -destination shape that overlaps the source shape and the portion of -the source shape that is not covered by the opaque destination shape. +\o \c{destination-atop} displays only the portion of the opaque destination +shape that overlaps the source shape and the portion of the source shape that is +not covered by the opaque destination shape. -\o \c{lighter} displays both the source and destination shapes. Where -the shapes overlap, the their color values are added, producing a -lighter color. +\o \c{lighter} displays both the source and destination shapes. Where the shapes +overlap, the their color values are added, producing a lighter color. -\o \c{copy} displays only the source shape. The destination shape is -ignored. - -\o \c{xor} displays both the source and the destination shapes except -the areas of overlap, in which both shapes are completely transparent. +\o \c{copy} displays only the source shape. The destination shape is ignored. +\o \c{xor} displays both the source and the destination shapes except the areas +of overlap, in which both shapes are completely transparent. \endlist The following figure shows the various compositing effects: - \image webkit-guide/canvas_composite.png \section1 Saving and Exporting Canvas Drawings as Image Files -You can save or export your canvas drawings as .png or .jpeg image -files by calling the \c{toDataURL()} method: +You can save or export your canvas drawings as .png or .jpeg image files by +calling the \c{toDataURL()} method: \code canvas.toDataURL([type, ...]) \endcode - where: - -\list - -\o \c{type} is the MIME type to which you want to save or export your -canvas. Possible values are: - \list - -\o \c{"image\png"} (Default value) -\o \c{"image\jpeg"} - -\endlist - +\o \c{type} is the MIME type to which you want to save or export your canvas. +Possible values are: + \list + \o \c{"image\png"} (Default value) + \o \c{"image\jpeg"} + \endlist \o\c{...} represents additional arguments that depend on the MIME type. - -\list - -\o If \c{type} is \c{png}, this argument is \c{" "} -\o If \c{type} is \c{jpeg}, this argument is the desired quality level of the image. The value is a number in the range 0.0 to 1.0, inclusive. - -\endlist + \list + \o If \c{type} is \c{png}, this argument is \c{" "} + \o If \c{type} is \c{jpeg}, this argument is the desired quality level of the + image. The value is a number in the range 0.0 to 1.0, inclusive. + \endlist \endlist \section1 Drawing Text -You can draw text on your canvas by setting the following font -attributes on the 2d drawing context: +You can draw text on your canvas by setting the following font attributes on the +2d drawing context: \list +\o \c{font} refers to any font, expressed the same way as in CSS properties. +This attribute's value can include any font style, variant, weight, size, +height, and family. For example: -\o \c{font} refers to any font, expressed the same way as in CSS -properties. This attribute\'s value can include any font style, -variant, weight, size, height, and family. For example: - -\code -context.font = "12pt Arial"; -\endcode - -The default value is \c{10px sans-serif}. - -If you set the \c{font} attribute to a relative font size, the browser -multiplies it by the computed font size of the \c{<canvas>} element -itself. For example: - -\code -context.font = "200%"; -\endcode - -\o \c{textAlign} specifies the alignment of the text. The values can -be one of the following: - -\list - -\o \c{left} for left-aligned text - -\o \c{right} for right-aligned text - -\o \c{center} for text that is centered within each line - -\o \c{start} (default) - the text is aligned at the beginning of the -line. Text is left- or right-justified based on locale-specific -writing method: left when text is left-to-right, right when text is -right-to-left. - -\o \c{end} - the text is aligned at the end of the line, either left or -right depending on locale-specific writing method. - -\endlist - -\o \c{textBaseline} specifies the position at which text is drawn -relative to a baseline. The figure below, from -\l{http://dev.w3.org/html5/canvas-api/canvas-2d-api.html}{the World -Wide Web Consortium}, illustrates the possible values for the -\c{textBaseline} attribute: - -\list - -\o \c{top} is the top of the em square, which approximates the top of the -glyphs in a font - -\o \c{hanging} specifies a hanging baseline, where the tops of some -glyphs are anchored. - -\o \c{middle} is the mid-point of the em square + \code + context.font = "12pt Arial"; + \endcode -\o \c{alphabetic} (default) is the anchor point of many alphabetic -characters + The default value is \c{10px sans-serif}. -\o \c{ideographic} is the anchor point of many ideograms, such as the -characters used in the writing systems of many Asian languages + If you set the \c{font} attribute to a + relative font size, the browser multiplies it by the computed font size of the + \c{<canvas>} element itself. For example: -\o \c{bottom} is the bottom of the em square + \code + context.font = "200%"; + \endcode -\endlist +\o \c{textAlign} specifies the alignment of the text. The values can be one of +the following: + \list + \o \c{left} for left-aligned text + \o \c{right} for right-aligned text + \o \c{center} for text that is centered within each line + \o \c{start} (default) - the text is aligned at the beginning of the line. Text + is left- or right-justified based on locale-specific writing method: left when + text is left-to-right, right when text is right-to-left. + \o \c{end} - the text is aligned at the end of the line, either left or right + depending on locale-specific writing method. + \endlist +\o \c{textBaseline} specifies the position at which text is drawn relative to a +baseline. The figure below, from \l{HTML5 Canvas API}, illustrates the possible +values for the \c{textBaseline} attribute: + \list + \o \c{top} is the top of the em square, which approximates the top of the glyphs + in a font + \o \c{hanging} specifies a hanging baseline, where the tops of some glyphs are + anchored. + \o \c{middle} is the mid-point of the em square + \o \c{alphabetic} (default) is the anchor point of many alphabetic characters + \o \c{ideographic} is the anchor point of many ideograms, such as the characters + used in the writing systems of many Asian languages + \o \c{bottom} is the bottom of the em square + \endlist \endlist \image webkit-guide/canvas_text.png To draw text on a canvas: - \list 1 - \o Set the \c{font} attribute on the drawing context. For example: - -\code -context.font = "bold 11px arial" -\endcode - -\o Measure the text that you want to draw by calling the \c{measureText} -method: - -\code -TextMetrics measureText("Text to draw"); -\endcode - -where \c{TextMetrics} is the object returned. Its \c{width} attribute -is the width, in pixels, that the "Text to draw" would be when drawn -with the font specified by the \c{font} attribute. - + \code + context.font = "bold 11px arial" + \endcode +\o Measure the text that you want to draw by calling the \c{measureText} method: + \code + TextMetrics measureText("Text to draw"); + \endcode +where \c{TextMetrics} is the object returned. Its \c{width} attribute is the +width, in pixels, that the \c{"Text to draw"} would be when drawn with the font +specified by the \c{font} attribute. \o Call either of the following methods: + \list + \o \c{fillText} draws the text with the font style specified by the \c{font} + attribute, the alignment specified by the \c{textAlign} attribute, and the + baseline specified by the \c{textBaseline} attribute. For example: + \code + context.fillText("Text to draw",x,y,maximumWidth); + \endcode +where \c{x} and \c{y} are the coordinates at which the drawing begins (the +anchor point), and \c{maximumWidth} is the maximum width of the text string +(optional). If the \c{width} returned in step 2 is larger than the +\c{maximumWidth}, the font is scaled down until the width of the text string is +less than the \c{maximumWidth} specified. -\list - -\o \c{fillText} draws the text with the font style specified by the -\c{font} attribute, the alignment specified by the \c{textAlign} attribute, -and the baseline specified by the \c{textBaseline} attribute. For example: - -\code -context.fillText("Text to draw",x,y,maximumWidth); -\endcode - -where \c{x} and \c{y} are the coordinates at which the drawing begins -(the anchor point), and \c{maximumWidth} is the maximum width of the -text string (optional). If the \c{width} returned in step 2 is larger -than the \c{maximumWidth}, the font is scaled down until the width of -the text string is less than the \c{maximumWidth} specified. - -If you don\'t specify the \c{font} attribute, the text inherits the -font size and style of the \c{<canvas>} element itself. +If you don't specify the \c{font} attribute, the text inherits the font size and +style of the \c{<canvas>} element itself. \o \c{strokeText} is the same as the \c{fillText} method, except that a stroke style is applied to the text instead of a fill style, @@ -651,30 +565,23 @@ context.drawImage(image, sx, sy, sw, sh, dx, dy, dw, dh) \endcode where: - \list - -\o \c{sx} is the x coordinate of the upper left corner of the cropped -source image - -\o \c{sy} is the y coordinate of the upper left corner of the cropped -source image - +\o \c{sx} is the x coordinate of the upper left corner of the cropped source +image +\o \c{sy} is the y coordinate of the upper left corner of the cropped source +image \o \c{sw} is the width of the cropped source image - \o \c{sh} is the height of the cropped source image - \endlist -Use this method if you want to crop the source image to the rectangle -(sx, sy, sw, sh) before drawing it on the canvas. The destination -image will have width dw, height dh, and upper left corner at -coordinates (dx,dy) on the canvas. +Use this method if you want to crop the source image to the rectangle (sx, sy, +sw, sh) before drawing it on the canvas. The destination image will have width +\c dw, height \c dh, and upper left corner at coordinates \c{(dx,dy)} on the +canvas. -To create a new image using JavaScript, create an \c{Image} object and -define its source. Use an \c{onload} event handler to ensure that the -\c{drawImage} method is not called until the image has finished loading. -For example: +To create a new image using JavaScript, create an \c{Image} object and define +its source. Use an \c{onload} event handler to ensure that the \c{drawImage} +method is not called until the image has finished loading. For example: \code var graphic = new Image(); @@ -708,30 +615,25 @@ graphic.onload = function(){ that is repeated to form a pattern. The image must be fully loaded before you can draw it on the canvas. The reference cannot be a URL. Instead, it should be referenced via standard DOM - methods such as \o \c{document.images} and \o - \c{document.getElementById}. For example: - - \code - <canvas id="demo1" width="100" height="150"></canvas> - - var canvas = document.getElementById("demo1"); - var context = canvas.getContext("2d"); - \endcode - - \o \c{repetition} is the direction in which the image repeats to form - the pattern. Possible values are: - - \list - - \o \c{repeat} (default) the image repeats both horizontally and - vertically - - \o \c{repeat-x} the image repeats horizontally - - \o \c{repeat-y} the image repeats vertically - - \endlist - + methods such as + \list + \o \c{document.images} and + \o \c{document.getElementById}. For example: + + \code + <canvas id="demo1" width="100" height="150"></canvas> + + var canvas = document.getElementById("demo1"); + var context = canvas.getContext("2d"); + \endcode + \endlist + \o \c{repetition} is the direction in which the image repeats to form the + pattern. Possible values are: + \list + \o \c{repeat} (default) the image repeats both horizontally and vertically + \o \c{repeat-x} the image repeats horizontally + \o \c{repeat-y} the image repeats vertically + \endlist \endlist The repeated images are the same size as the source image. The @@ -759,40 +661,32 @@ graphic.onload = function(){ \section1 Applying Colors -To draw the outline of a shape in color, -set the \c{strokeStyle} attribute to any valid -\l{http://www.w3schools.com/css/css_colors.asp}{CSS color value}. -The color value can be in hexadecimal notation or in RGB/HSL notation, -as described in \l{Specifying Color and Opacity}. -For example, -either of the following sets a shape\'s outline to red: +To draw the outline of a shape in color, set the \c{strokeStyle} attribute to +any valid \l{CSS Color Value}{CSS color value}. The color value can be in +hexadecimal notation or in RGB/HSL notation, as described in \l{Specifying Color +and Opacity}. For example, either of the following sets a shape's outline to +red: \code context.strokeStyle = "#FF0000" context.strokeStyle = "rgb(255,0,0)" \endcode -To fill a shape with color, -set the \c{fillStyle} attribute to a -\l{http://www.w3schools.com/css/css_colors.asp}{CSS color value}. -The color value can be in hexadecimal notation or in RGB/HSL -notation. -For example, either of the following colors a shape\'s interior as -blue: +To fill a shape with color, set the \c{fillStyle} attribute to a l{CSS Color +Value}{CSS color value}. The color value can be in hexadecimal notation or in +RGB/HSL notation. For example, either of the following colors a shape's interior +as blue: \code context.fillStyle = "#0000FF" context.fillStyle = "rgb(0,0,255)" \endcode -The -\l{http://www.w3.org/TR/2003/CR-css3-color-20030514/#numerical}{CSS3 -Color Module specification} extends both RGB and HSL color models to -include a color\'s opacity, -referred to as its \bold{alpha}. -These extended models are known as RGBA and HSLA. -There are no hexadecimal notations for RGBA and HSLA values. -The following specifies varying levels of opacity for a blue shape: +The \l{CSS3 Color Module specification} extends both RGB and HSL color models to +include a color's opacity, referred to as its \e{alpha}. These extended +models are known as RGBA and HSLA. There are no hexadecimal notations for RGBA +and HSLA values. The following specifies varying levels of opacity for a blue +shape: \code context.fillStyle = rgba(0, 0, 255, 0) // transparent @@ -800,50 +694,41 @@ context.fillStyle = rgba(0, 0, 255, 0.5) // semi-transparent context.fillStyle = rgba(0, 0, 255, 1) // opaque \endcode -When you set the \c{context.strokeStyle} or \c{context.fillStyle} -attributes, -whatever value you set becomes the default value for all subsequently -drawn shapes, -until you set a new value. +When you set the \c{context.strokeStyle} or \c{context.fillStyle} attributes, +whatever value you set becomes the default value for all subsequently drawn +shapes, until you set a new value. \section2 Applying Gradients - A gradient is a smooth transition between colors. There are two types - of gradients: linear and radial. + A gradient is a smooth transition between colors. There are two types of + gradients: linear and radial. - A linear gradient transitions the color along a line between two - points. To create a linear gradient, call the \c{createLinearGradient} - method: + A linear gradient transitions the color along a line between two points. To + create a linear gradient, call the \c{createLinearGradient} method: \code createLinearGradient(x0, y0, x1, y1) \endcode - where \c{(x0, y0)} is the starting point and \c{(x1, y1)} is the ending point - for the linear gradient. + where \c{(x0, y0)} is the starting point and \c{(x1, y1)} is the ending + point for the linear gradient. - A radial gradient transitions the color along a cone between two - circles. To create a radial gradient, call the \c{createRadialGradient} - method: + A radial gradient transitions the color along a cone between two circles. To + create a radial gradient, call the \c{createRadialGradient} method: \code createRadialGradient(x0, y0, r0, x1, y1, r1) \endcode - where: - \list - \o \c{(x0, y0, r0)} represents the starting circle, whose origin is \c{(x0, y0)} and whose radius is \c{r0}. - \o \c{(x1, y1, r1)} represents the ending circle, whose origin is \c{(x1, y1)} and whose radius is \c{r1}. - \endlist - Gradients must have two or more \bold{color stops}, representing color - shifts positioned from 0 to 1 between to the gradient\'s starting and + Gradients must have two or more \e{color stops}, representing color + shifts positioned from \c 0 to \c 1 between to the gradient's starting and end points or circles: \code @@ -851,77 +736,56 @@ until you set a new value. \endcode where: - \list - \o \c{position} specifies the position of the color within the already - defined starting and end points or circles, expressed as a number - from 0 to 1. - + defined starting and end points or circles, expressed as a number from \c 0 + to \c 1. \o \c{color} specifies the CSS color at that position. - \endlist - For example, to define a gradient that varies from red to blue - horizontally along a rectangular area: - + For example, to define a gradient that varies from red to blue horizontally + along a rectangular area: \list 1 - \o Create a gradient object: - - \code - var redbluegradient = context.createLinearGradient(0,0,100,0); - \endcode - + \code + var redbluegradient = context.createLinearGradient(0,0,100,0); + \endcode \o Define the color stops: - - \code - redbluegradient.addColorStop(0, "rgb(255,0,0)"); // red at the left side of the rectangle - redbluegradient.addColorStop(1, "rgb(0,0,255)"); // blue at the right side of the rectangle - \endcode - + \code + redbluegradient.addColorStop(0, "rgb(255,0,0)"); // red at the left side of the rectangle + redbluegradient.addColorStop(1, "rgb(0,0,255)"); // blue at the right side of the rectangle + \endcode \o Draw the shape and set a \c{fillStyle} or \c{strokeStyle}: - - \code - context.fillStyle = redbluegradient; - context.fillRect(0,0,100,150); - \endcode - + \code + context.fillStyle = redbluegradient; + context.fillRect(0,0,100,150); + \endcode \endlist To define a gradient that varies from red to blue vertically along a rectangle: - \list 1 - \o Create a gradient object: - \code var redbluegradient = context.createLinearGradient(0,0,0,150); \endcode - \o Define the color stops: - \code redbluegradient.addColorStop(0, "rgb(255,0,0)"); // red at the top of the rectangle redbluegradient.addColorStop(1, "rgb(0,0,255)"); // blue at the bottom of the rectangle \endcode - \o Draw the shape and set a \c{fillStyle} or \c{strokeStyle}: - \code context.fillStyle = redbluegradient; context.fillRect(0,0,100,150); \endcode - \endlist - \bold{NOTE:} A canvas gradient\'s color stops behave slightly - differently than those used within non-canvas \l{Gradients}{CSS3 - Webkit gradients}. Webkit gradients specify mandatory \c{from} and - \c{to} colors, with optional \c{color-stop} values for additional - color shifts within the overall range of the gradient. For canvas - gradients, even the initial and final colors are defined as color + \note A canvas gradient's color stops behave slightly differently than those + used within non-canvas \l{Gradients}{gradients}. Webkit gradients specify + mandatory \c{from} and \c{to} colors, with optional \c{color-stop} values + for additional color shifts within the overall range of the gradient. For + canvas gradients, even the initial and final colors are defined as color stops. \section2 Applying Shadows @@ -930,25 +794,22 @@ until you set a new value. attributes: \list + \o \c{shadowColor} sets the color of the shadow. The value can be any CSS + color value. The default value is transparent black (\c{"rgba(0,0,0,0)"}). - \o \c{shadowColor} sets the color of the shadow. The value can be any - CSS color value. The default value is transparent black (\c{"rgba(0,0,0,0)"}). - - \o \c{shadowBlur} sets the amount of blur in the shadow, in - pixels. The value can be any positive number or 0. A value of 0 - produces a sharp shadow with no blur. + \o \c{shadowBlur} sets the amount of blur in the shadow, in pixels. The + value can be any positive number or 0. A value of 0 produces a sharp shadow + with no blur. \o \c{shadowOffsetX} sets the number of pixels the shadow extends - horizontally from the object drawn. If this value is a positive - number, the shadow extends to the right of the object. If negative, - the shadow extends to the left of the object. The default value is 0 - pixels. - - \o \c{shadowOffsetY} sets the number of pixels the shadow extends - vertically from the object drawn. If this value is a positive number, - the shadow extends below the object. If negative, the shadow extends - above the object. The default value is 0 pixels. - + horizontally from the object drawn. If this value is a positive number, the + shadow extends to the right of the object. If negative, the shadow extends + to the left of the object. The default value is 0 pixels. + + \o \c{shadowOffsetY} sets the number of pixels the shadow extends vertically + from the object drawn. If this value is a positive number, the shadow + extends below the object. If negative, the shadow extends above the object. + The default value is 0 pixels. \endlist The following example code adds a semi-transparent black shadow to the @@ -966,57 +827,45 @@ until you set a new value. \section1 Transforming Graphics -When drawing shapes and paths, you can translate the canvas\'s origin, -rotate the canvas around the origin, scale the units in the canvas -grid, and modify the transformation matrix directly. +When drawing shapes and paths, you can translate the canvas's origin, rotate the +canvas around the origin, scale the units in the canvas grid, and modify the +transformation matrix directly. \section2 Translating the Canvas Origin - Translating the origin enables you to draw patterns of different - objects on the canvas without having to measure the coordinates - manually for each shape. To translate the origin of the canvas, use - the \c{translate} method: - + Translating the origin enables you to draw patterns of different objects on + the canvas without having to measure the coordinates manually for each + shape. To translate the origin of the canvas, use the \c{translate} method: \code context.translate(x,y); \endcode - where: - \list - \o \c{x} is the horizontal distance that the origin is translated, in coordinate space units - \o \c{y} is the vertical distance that the origin is translated, in coordinate space units - \endlist \section2 Rotating the Canvas To rotate the canvas around the current origin, call the \c{rotate()} method: - \code context.rotate(angle); \endcode - where \c{angle} is the clockwise rotation angle in radians. - The number of radians is the number of degrees multiplied by \pi/180, expressed in JavaScript as: - \code var radians = (Math.PI/180)*degrees; \endcode - \image webkit-guide/canvas_rotate.png \section2 Scaling the Canvas Grid - To increase or decrease the size of each unit in the canvas grid, call - the \c{scale} method: + To increase or decrease the size of each unit in the canvas grid, call the + \c{scale} method: \code context.scale(x,y); @@ -1033,59 +882,42 @@ grid, and modify the transformation matrix directly. \endlist The scale factors are in multiples. For example, \c{scale(2.0, 0.5)} would - double the horizontal size of an object drawn on the canvas and half - its vertical size, as shown below: + double the horizontal size of an object drawn on the canvas and half its + vertical size, as shown below: \image webkit-guide/canvas_scale.png \section2 Manipulating the Transformation Matrix - Modifying the transformation matrix directly enables you to perform - scaling, rotating, and translating transformations in a single step. + Modifying the transformation matrix directly enables you to perform scaling, + rotating, and translating transformations in a single step. - The transformation matrix is an affine transformation matrix from - linear algebra. Affine transformations preserve colinearity and - relative distance in the transformed coordinate space. This means that - points in a line remain in a line, parallel lines remain parallel, and - the distance between lines and objects maintains the same ratio, even - if a scale factor is applied. Repositioning by translation, rotation, - or skewing is also possible. + The transformation matrix is an \e{affine transformation} matrix from linear + algebra. Affine transformations preserve colinearity and relative distance + in the transformed coordinate space. This means that points in a line remain + in a line, parallel lines remain parallel, and the distance between lines + and objects maintains the same ratio, even if a scale factor is applied. + Repositioning by translation, rotation, or skewing is also possible. - Each point on the canvas is multiplied by the matrix before anything - is drawn. The HTML5 canvas API defines the transformation matrix as: + Each point on the canvas is multiplied by the matrix before anything is + drawn. The \l{HTML5 Canvas API} defines the transformation matrix as: \image webkit-guide/canvas_math.png - where: - \list - \o \c{a} is the scale factor in the horizontal (x) direction - \image webkit-guide/canvas_scalex.png - \o \c{c} is the skew factor in the x direction - \image webkit-guide/canvas_skewx.png - \o \c{e} is the translation in the x direction - \image webkit-guide/canvas_translate.png - \o \c{b} is the skew factor in the y (vertical) direction - \image webkit-guide/canvas_skewy.png - \o \c{d} is the scale factor in the y direction - \image webkit-guide/canvas_scaley.png - \o \c{f} is the translation in the y direction - \image webkit-guide/canvas_translatey.png - \o the last row remains constant - \endlist The scale factors and skew factors are multiples; \c{e} and \c{f} are @@ -1096,114 +928,89 @@ grid, and modify the transformation matrix directly. \image webkit-guide/canvas_math_rotate.png - where the angle of rotation is in radians. + where the \c angle of rotation is in radians. - \sa + \bold{See Also:} \l{http://www.senocular.com/flash/tutorials/transformmatrix/}{senocular.com} for a good explanation of how transformation matrices are used - identically within Flash. + identically within Adobe Flash. \section1 Canvas Animations -You can animate a canvas drawing by repeatedly redrawing the canvas -for each frame and translating, -rotating, -skewing, -and scaling the drawn objects. - -To draw each frame by employing the HTML5 canvas API, -you should define the original canvas state and save it for future -reference. -The drawing context maintains a stack of drawing states. -Each state consists of the current transformation matrix, -current clipping region, -and current values of the following attributes: -\c{strokeStyle}, -\c{fillStyle}, -\c{globalAlpha}, -\c{lineWidth}, -\c{lineCap}, -\c{lineJoin}, -\c{miterLimit}, -\c{shadowOffsetX}, -\c{shadowOffsetY}, -\c{shadowBlur}, -\c{shadowColor}, -\c{globalCompositeOperation}, -\c{font}, -\c{textAlign}, -and -\c{textBaseline}. -The current path and the current bitmap are NOT part of the drawing -state. -The path can be reset only by invoking the \c{beginPath()} method. -The current bitmap is a property of the canvas, -not of the context. - -To save the original canvas state, -call the \c{save()} method: +You can animate a canvas drawing by repeatedly redrawing the canvas for each +frame and translating, rotating, skewing, and scaling the drawn objects. + +To draw each frame by employing the HTML5 canvas API, you should define the +original canvas state and save it for future reference. The drawing context +maintains a stack of drawing states. Each state consists of the current +transformation matrix, current clipping region, and current values of the +following attributes: +\list +\o\c{strokeStyle} +\o\c{fillStyle} +\o\c{globalAlpha} +\o\c{lineWidth} +\o\c{lineCap} +\o\c{lineJoin} +\o\c{miterLimit} +\o\c{shadowOffsetX} +\o\c{shadowOffsetY} +\o\c{shadowBlur} +\o\c{shadowColor} +\o\c{globalCompositeOperation} +\o\c{font} +\o\c{textAlign} +\o\c{textBaseline} +\endlist +The current path and the current bitmap are NOT part of the drawing state. +The path can be reset only by invoking the \c{beginPath()} method. The current +bitmap is a property of the canvas, not of the context. +To save the original canvas state, call the \c{save()} method: \code context.save(); \endcode -Before drawing each new frame, -you must clear the canvas: - +Before drawing each new frame, you must clear the canvas: \code canvas.clearRect(x,y,width,height); \endcode - where: - \list - -\o \c{x} is the position of the top left corner of the canvas on the -horizontal axis - -\o \c{y} is the position of the top left corner of the canvas on the -vertical axis - +\o \c{x} is the position of the top left corner of the canvas on the horizontal +axis +\o \c{y} is the position of the top left corner of the canvas on the vertical +axis \o \c{width} is the width of the canvas - \o \c{height} is the height of the canvas - \endlist -Draw the new frame using any of the methods provided by the canvas -API. -Then save it by calling the \c{save()} method. +Draw the new frame using any of the methods provided by the canvas API. Then +save it by calling the \c{save()} method. -If you wish to return to the state of the original frame as the basis -for each new frame that you draw, -call the \c{context.restore()} method. - -To execute the drawing methods repeatedly, -use the standard JavaScript-based animation technique, -calling the \c{setInterval()} and \c{clearInterval()} methods. -The following shows how to execute an animation function every 50 -milliseconds (corresponding to 20 times per second, -a typical animation frame rate), -then subsequently halt the animation: +If you wish to return to the state of the original frame as the basis for each +new frame that you draw, call the \c{context.restore()} method. +To execute the drawing methods repeatedly, use the standard JavaScript-based +animation technique, calling the \c{setInterval()} and \c{clearInterval()} +methods. The following shows how to execute an animation function every \c 50 +milliseconds (corresponding to 20 times per second, a typical animation frame +rate), then subsequently halt the animation: \code var id = setInterval(functionName, 50); clearInterval(id); \endcode \bold{See Also:} - \list - \o -\l{http://www.canvasdemos.com/2009/10/09/html-5-canvas-animation/}{CanvasDemos.com: -animated cartoon}, -which discusses how to use Canvas as an animation framework. +\l{http://www.canvasdemos.com/2009/10/09/html-5-canvas-animation/}{CanvasDemos.com: animated cartoon}, which discusses how to use Canvas as an animation framework. \o \l{http://blog.nihilogic.dk/2009/02/html5-canvas-cheat-sheet.html}{nihilogic.dk: HTML5 Canvas Cheat Sheet} +\o \l{QtWebKit Guide} -back to the main page \endlist */ |