Interface: CanvasRenderingContext2D
CanvasView.CanvasRenderingContext2D
The Canvas 2D API provided by the React Native PyTorch Core canvas
is going to match the W3C specification of the
2dcontext
(and MDN CanvasRenderingContext2D).
The motivation behind this is to have a canvas API for mobile that matches the standardized Web canvas API, which ultimately will allow us to write demos once and run them on mobile and web.
info
The canvas API currently only implements a subset of the 2dcontext API and
we will gradually add more functionality as needed.
info
The documenation for the canvas is adapted from the MDN
CanvasRenderingContext2D.
Properties
fillStyle
• fillStyle: string
The fillStyle property of the Canvas 2D API specifies the color inside
shapes. The default style is #000 (black).
Options
color A CSS <color> value as string.
font
• font: string
The font property of the Canvas 2D API specifies the current text style
to use when drawing text. This string uses the same syntax as the CSS font
specifier.
Options
value A string parsed as CSS font value. The default font is 10px sans-serif.
lineCap
• lineCap: LineCap
The lineCap property of the Canvas 2D API determines the shape used to
draw the end points of lines.
note
Lines can be drawn with the stroke, strokeRect, and strokeText functions.
Options
"butt"The ends of lines are squared off at the endpoints. Default value."round"The ends of lines are rounded."square"The ends of lines are squared off by adding a box with an equal width and half the height of the line's thickness.
lineJoin
• lineJoin: LineJoin
The lineJoin property of the Canvas 2D API determines the shape used to
join two line segments where they meet.
This property has no effect wherever two connected segments have the same direction, because no joining area will be added in this case. Degenerate segments with a length of zero (i.e., with all endpoints and control points at the exact same position) are also ignored.
note
Lines can be drawn with the stroke, strokeRect, and strokeText functions.
Options
There are three possible values for this property: "round", "bevel",
and "miter". The default is "miter".
"round"Rounds off the corners of a shape by filling an additional sector of disc centered at the common endpoint of connected segments. The radius for these rounded corners is equal to the line width."bevel"Fills an additional triangular area between the common endpoint of connected segments, and the separate outside rectangular corners of each segment."miter"Connected segments are joined by extending their outside edges to connect at a single point, with the effect of filling an additional lozenge-shaped area. This setting is affected by the miterLimit property. Default value.
lineWidth
• lineWidth: number
The lineWidth property of the Canvas 2D API sets the thickness of lines.
Options
value A number specifying the line width, in coordinate space units. Zero, negative, Infinity, and NaN values are ignored. This value is 1.0 by default.
miterLimit
• miterLimit: number
The miterLimit property of the Canvas 2D API sets the miter limit ratio.
value A number specifying the miter limit ratio, in coordinate space units. Zero, negative, [[Infinity]], and [[NaN]] values are ignored. The default value is 10.0.
strokeStyle
• strokeStyle: string
The strokeStyle property of the Canvas 2D API specifies the color to use
for the strokes (outlines) around shapes. The default is #000 (black).
Options
color A CSS <color> value as string.
textAlign
• textAlign: TextAlign
The textAlign property of the Canvas 2D API specifies the current text
alignment used when drawing text.
The alignment is relative to the x value of the fillText method. For
example, if textAlign is "center", then the text's left edge will be at
x - (textWidth / 2).
Options
"left"The text is left-aligned."right"The text is right-aligned."center"The text is centered.
Methods
arc
▸ arc(x, y, radius, startAngle, endAngle, anticlockwise?): void
The arc() function of the Canvas 2D API adds a circular arc to the
current sub-path.
ctx.beginPath();
ctx.arc(100, 75, 50, 0, 2 * Math.PI);
ctx.stroke();
The arc() function creates a circular arc centered at (x, y) with a
radius of radius. The path starts at startAngle, ends at endAngle,
travels in the direction given by counterclockwise (defaulting to
clockwise).
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The horizontal coordinate of the arc's center. |
y | number | The vertical coordinate of the arc's center. |
radius | number | The arc's radius. Must be positive. |
startAngle | number | The angle at which the arc starts in radians, measured from the positive x-axis. |
endAngle | number | The angle at which the arc ends in radians, measured from the positive x-axis. |
anticlockwise? | boolean | An optional Boolean. If true, draws the arc counter-clockwise between the start and end angles. The default is false (clockwise). |
Returns
void
beginPath
▸ beginPath(): void
The beginPath() function of the Canvas 2D API starts a new path by
emptying the list of sub-paths. Call this function when you want to create
a new path.
Returns
void
clear
▸ clear(): void
Clears the entire canvas to be transparent.
deprecated This function will be removed in the beta release.
Returns
void
clearRect
▸ clearRect(x, y, width, height): void
The clearRect() function of the Canvas 2D API erases the pixels in a
rectangular area by setting them to transparent black.
The clearRect() function sets the pixels in a rectangular area to
transparent black (rgba(0,0,0,0)). The rectangle's corner is at
(x, y), and its size is specified by width and height.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the rectangle's starting point. |
y | number | The y-axis coordinate of the rectangle's starting point. |
width | number | The rectangle's width. Positive values are to the right, and negative to the left. |
height | number | The rectangle's height. Positive values are down, and negative are up. |
Returns
void
closePath
▸ closePath(): void
The closePath() function of the Canvas 2D API attempts to add a straight
line from the current point to the start of the current sub-path. If the
shape has already been closed or has only one point, this function does
nothing.
This function doesn't draw anything to the canvas directly. You can render the path using the stroke or fill functions.
Returns
void
drawCircle
▸ drawCircle(x, y, radius): void
Draws a circle at (x, y) with the given radius.
deprecated This function will be removed in the beta release.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the circle's starting point. |
y | number | The y-axis coordinate of the circle's starting point. |
radius | number | The circle's radius. Must be positive. |
Returns
void
drawImage
▸ drawImage(image, dx, dy): void
The drawImage() function of the Canvas 2D API provides different ways
to draw an image onto the canvas.
Parameters
| Name | Type | Description |
|---|---|---|
image | Image | An element to draw into the context. The specification permits an Image source. |
dx | number | The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
dy | number | The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
Returns
void
▸ drawImage(image, dx, dy, dWidth, dHeight): void
The drawImage() function of the Canvas 2D API provides different ways
to draw an image onto the canvas.
Parameters
| Name | Type | Description |
|---|---|---|
image | Image | An element to draw into the context. The specification permits an Image source. |
dx | number | The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
dy | number | The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
dWidth | number | The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn. Note that this argument is not included in the 3-argument syntax. |
dHeight | number | The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn. Note that this argument is not included in the 3-argument syntax. |
Returns
void
▸ drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight): void
The drawImage() function of the Canvas 2D API provides different ways to
draw an image onto the canvas.
Parameters
| Name | Type | Description |
|---|---|---|
image | Image | An element to draw into the context. The specification permits an Image source. |
sx | number | The x-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context. Note that this argument is not included in the 3- or 5-argument syntax. |
sy | number | The y-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context. Note that this argument is not included in the 3- or 5-argument syntax. |
sWidth | number | The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by sx and sy to the bottom-right corner of the image is used. Note that this argument is not included in the 3- or 5-argument syntax. |
sHeight | number | The height of the sub-rectangle of the source image to draw into the destination context. Note that this argument is not included in the 3- or 5-argument syntax. |
dx | number | The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
dy | number | The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image. |
dWidth | number | The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn. Note that this argument is not included in the 3-argument syntax. |
dHeight | number | The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn. Note that this argument is not included in the 3-argument syntax. |
Returns
void
fill
▸ fill(): void
The fill() function of the Canvas 2D API fills the current or given path
with the current fillStyle.
caution
The fill() function differs from the 2dcontext specification and is
subject to change. It currently does not take additional fillRule
or path and fillRule params.
// Create path
let region = new Path2D();
region.moveTo(30, 90);
region.lineTo(110, 20);
region.lineTo(240, 130);
region.lineTo(60, 130);
region.lineTo(190, 20);
region.lineTo(270, 90);
region.closePath();
// Fill path
ctx.fillStyle = 'green';
ctx.fill(region, 'evenodd');
Returns
void
fillCircle
▸ fillCircle(x, y, radius): void
Fill a circle at (x, y) with the given radius.
deprecated This function will be removed in the beta release.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the circle's starting point. |
y | number | The y-axis coordinate of the circle's starting point. |
radius | number | The circle's radius. Must be positive. |
Returns
void
fillRect
▸ fillRect(x, y, width, height): void
The fillRect() function of the Canvas 2D API draws a rectangle that is filled according to the current fillStyle.
The fillRect() function draws a filled rectangle whose starting point is at (x, y) and whose size is specified by width and height. The fill style is determined by the current fillStyle attribute.
ctx.fillRect(10, 20, 30, 40);
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the rectangle's starting point. |
y | number | The y-axis coordinate of the rectangle's starting point. |
width | number | The rectangle's width. Positive values are to the right, and negative to the left. |
height | number | The rectangle's height. Positive values are down, and negative are up. |
Returns
void
fillText
▸ fillText(text, x, y): void
The fillText() function, part of the Canvas 2D API, draws a text string
at the specified coordinates, filling the string's characters with the
current fillStyle.
ctx.fillText('Hello world', 50, 90);
caution
The strokeText() function does not support textAlign, textBaseline,
and direction.
ctx.font = '50px serif';
ctx.fillText('Hello world', 50, 90);
Parameters
| Name | Type | Description |
|---|---|---|
text | string | A string specifying the text string to render into the context. The text is rendered using the settings specified by font. |
x | number | The x-axis coordinate of the point at which to begin drawing the text, in pixels. |
y | number | The y-axis coordinate of the baseline on which to begin drawing the text, in pixels. |
Returns
void
getImageData
▸ getImageData(sx, sy, sw, sh): Promise<ImageData>
The getImageData() of the Canvas 2D API returns an ImageData object
representing the underlying pixel data for a specified portion of the
canvas.
caution
The getImageData() function differs from the 2dcontext specification and
is subject to change. The function is async and returns a [[Promise]] with
an ImageData rather than synchronously returning the ImageData. It
currently does not support working with the ImageData.data of the
returned ImageData object.
The following is not yet implemented:
This function is not affected by the canvas's transformation matrix. If the specified rectangle extends outside the bounds of the canvas, the pixels outside the canvas are transparent black in the returned ImageData object.
Parameters
| Name | Type | Description |
|---|---|---|
sx | number | The x-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted. |
sy | number | The y-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted. |
sw | number | The width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left. |
sh | number | The height of the rectangle from which the ImageData will be extracted. Positive values are down, and negative are up. |
Returns
Promise<ImageData>
invalidate
▸ invalidate(): Promise<void>
Invalidate the canvas resulting in a repaint.
Returns
Promise<void>
lineTo
▸ lineTo(x, y): void
The lineTo(), part of the Canvas 2D API, adds a straight line to the
current sub-path by connecting the sub-path's last point to the specified
(x, y) coordinates.
Like other functions that modify the current path, this function does not directly render anything. To draw the path onto a canvas, you can use the fill or stroke functions.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the line's end point. |
y | number | The y-axis coordinate of the line's end point. |
Returns
void
moveTo
▸ moveTo(x, y): void
The moveTo() function of the Canvas 2D API begins a new sub-path at the
point specified by the given (x, y) coordinates.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis (horizontal) coordinate of the point. |
y | number | The y-axis (vertical) coordinate of the point. |
Returns
void
putImageData
▸ putImageData(imageData, dx, dy): void
The putImageData() function of the Canvas 2D API paints data from the
given ImageData object onto the canvas. If a dirty rectangle is
provided, only the pixels from that rectangle are painted. This function
is not affected by the canvas transformation matrix.
note
Image data can be retrieved from a canvas using the getImageData()
function.
caution
The putImageData() does not implement dirtyX, dirtyY, dirtyWidth,
and dirtyHeight params.
Parameters
| Name | Type | Description |
|---|---|---|
imageData | ImageData | An ImageData object containing the array of pixel values. |
dx | number | Horizontal position (x coordinate) at which to place the image data in the destination canvas. |
dy | number | Vertical position (y coordinate) at which to place the image data in the destination canvas. |
Returns
void
rect
▸ rect(x, y, width, height): void
The rect() method of the Canvas 2D API adds a rectangle to the current
path.
Like other methods that modify the current path, this method does not directly render anything. To draw the rectangle onto a canvas, you can use the fill or stroke methods.
note
To both create and render a rectangle in one step, use the fillRect or strokeRect functions.
The rect() method creates a rectangular path whose starting point is at
(x, y) and whose size is specified by width and height.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the rectangle's starting point. |
y | number | The y-axis coordinate of the rectangle's starting point. |
width | number | The rectangle's width. Positive values are to the right, and negative to the left. |
height | number | The rectangle's height. Positive values are down, and negative are up. |
Returns
void
restore
▸ restore(): void
The restore() function of the Canvas 2D API restores the most recently
saved canvas state by popping the top entry in the drawing state stack. If
there is no saved state, this function does nothing.
For more information about the drawing state, see CanvasRenderingContext2D.save.
Returns
void
rotate
▸ rotate(angle): void
The rotate() function of the Canvas 2D API adds a rotation to the
transformation matrix.
The rotation center point is always the canvas origin. To change the center point, you will need to move the canvas by using the translate function.
Parameters
| Name | Type | Description |
|---|---|---|
angle | number | The rotation angle, clockwise in radians. You can use degree * Math.PI / 180 to calculate a radian from a degree. |
Returns
void
save
▸ save(): void
The save() function of the Canvas 2D API saves the entire state of the
canvas by pushing the current state onto a stack.
The drawing state
The drawing state that gets saved onto a stack consists of:
- The current transformation matrix.
- The current values of the following attributes: strokeStyle, fillStyle.
Returns
void
scale
▸ scale(x, y): void
The scale() function of the Canvas 2D API adds a scaling transformation
to the canvas units horizontally and/or vertically.
By default, one unit on the canvas is exactly one pixel. A scaling
transformation modifies this behavior. For instance, a scaling factor of
0.5 results in a unit size of 0.5 pixels; shapes are thus drawn at half
the normal size. Similarly, a scaling factor of 2.0 increases the unit
size so that one unit becomes two pixels; shapes are thus drawn at twice
the normal size.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | Scaling factor in the horizontal direction. A negative value flips pixels across the vertical axis. A value of 1 results in no horizontal scaling. |
y | number | Scaling factor in the vertical direction. A negative value flips pixels across the horizontal axis. A value of 1 results in no vertical scaling. |
Returns
void
setTransform
▸ setTransform(a, b, c, d, e, f): void
The setTransform() function of the Canvas 2D API resets (overrides) the
current transformation to the identity matrix, and then invokes a
transformation described by the arguments of this function. This lets you
scale, rotate, translate (move), and skew the context.
The transformation matrix is described by:
setTransform() has two types of parameter that it can accept. The older type consists of several parameters representing the individual components of the transformation matrix to set:
The newer type consists of a single parameter, matrix, representing a 2D transformation matrix to set.
Parameters
| Name | Type | Description |
|---|---|---|
a | number | Horizontal scaling. A value of 1 results in no scaling. |
b | number | Vertical skewing. |
c | number | Horizontal skewing. |
d | number | Vertical scaling. A value of 1 results in no scaling. |
e | number | Horizontal translation (moving). |
f | number | Vertical translation (moving). |
Returns
void
stroke
▸ stroke(): void
The stroke() function of the Canvas 2D API strokes (outlines) the
current or given path with the current stroke style.
Strokes are aligned to the center of a path; in other words, half of the stroke is drawn on the inner side, and half on the outer side.
The stroke is drawn using the non-zero winding rule, which means that path intersections will still get filled.
caution
The stroke() function differs from the 2dcontext specification and is
subject to change. It currently does not take additional path param.
void ctx.stroke(path);
Returns
void
strokeRect
▸ strokeRect(x, y, width, height): void
The strokeRect() function of the Canvas 2D API draws a rectangle that is
stroked (outlined) according to the current strokeStyle and other
context settings.
The strokeRect() function draws a stroked rectangle whose starting point is at (x, y) and whose size is specified by width and height.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | The x-axis coordinate of the rectangle's starting point. |
y | number | The y-axis coordinate of the rectangle's starting point. |
width | number | The rectangle's width. Positive values are to the right, and negative to the left. |
height | number | The rectangle's height. Positive values are down, and negative are up. |
Returns
void
strokeText
▸ strokeText(text, x, y): void
The strokeText(), part of the Canvas 2D API, strokes — that is, draws
the outlines of — the characters of a text string at the specified
coordinates. An optional parameter allows specifying a maximum width for
the rendered text, which the user agent will achieve by condensing the
text or by using a lower font size.
This function draws directly to the canvas without modifying the current path, so any subsequent fill or stroke calls will have no effect on it.
caution
The strokeText() function does not support textAlign, textBaseline,
and direction.
ctx.font = '50px serif';
ctx.strokeText('Hello world', 50, 90);
Parameters
| Name | Type | Description |
|---|---|---|
text | string | A string specifying the text string to render into the context. The text is rendered using the settings specified by font. |
x | number | The x-axis coordinate of the point at which to begin drawing the text. |
y | number | The y-axis coordinate of the point at which to begin drawing the text. |
Returns
void
translate
▸ translate(x, y): void
The translate() function of the Canvas 2D API adds a translation
transformation to the current matrix.
The translate() function adds a translation transformation to the
current matrix by moving the canvas and its origin x units horizontally
and y units vertically on the grid.
Parameters
| Name | Type | Description |
|---|---|---|
x | number | Distance to move in the horizontal direction. Positive values are to the right, and negative to the left. |
y | number | Distance to move in the vertical direction. Positive values are down, and negative are up. |
Returns
void