Skip to main content
Version: 0.2.3

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

NameTypeDescription
xnumberThe horizontal coordinate of the arc's center.
ynumberThe vertical coordinate of the arc's center.
radiusnumberThe arc's radius. Must be positive.
startAnglenumberThe angle at which the arc starts in radians, measured from the positive x-axis.
endAnglenumberThe angle at which the arc ends in radians, measured from the positive x-axis.
anticlockwise?booleanAn 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.

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

NameTypeDescription
xnumberThe x-axis coordinate of the rectangle's starting point.
ynumberThe y-axis coordinate of the rectangle's starting point.
widthnumberThe rectangle's width. Positive values are to the right, and negative to the left.
heightnumberThe 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

NameTypeDescription
xnumberThe x-axis coordinate of the circle's starting point.
ynumberThe y-axis coordinate of the circle's starting point.
radiusnumberThe 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

NameTypeDescription
imageImageAn element to draw into the context. The specification permits an Image source.
dxnumberThe x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
dynumberThe 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

NameTypeDescription
imageImageAn element to draw into the context. The specification permits an Image source.
dxnumberThe x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
dynumberThe y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
dWidthnumberThe 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.
dHeightnumberThe 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

NameTypeDescription
imageImageAn element to draw into the context. The specification permits an Image source.
sxnumberThe 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.
synumberThe 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.
sWidthnumberThe 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.
sHeightnumberThe 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.
dxnumberThe x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
dynumberThe y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
dWidthnumberThe 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.
dHeightnumberThe 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

NameTypeDescription
xnumberThe x-axis coordinate of the circle's starting point.
ynumberThe y-axis coordinate of the circle's starting point.
radiusnumberThe 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

NameTypeDescription
xnumberThe x-axis coordinate of the rectangle's starting point.
ynumberThe y-axis coordinate of the rectangle's starting point.
widthnumberThe rectangle's width. Positive values are to the right, and negative to the left.
heightnumberThe 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

NameTypeDescription
textstringA string specifying the text string to render into the context. The text is rendered using the settings specified by font.
xnumberThe x-axis coordinate of the point at which to begin drawing the text, in pixels.
ynumberThe 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

NameTypeDescription
sxnumberThe x-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
synumberThe y-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
swnumberThe width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left.
shnumberThe 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

NameTypeDescription
xnumberThe x-axis coordinate of the line's end point.
ynumberThe 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

NameTypeDescription
xnumberThe x-axis (horizontal) coordinate of the point.
ynumberThe 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

NameTypeDescription
imageDataImageDataAn ImageData object containing the array of pixel values.
dxnumberHorizontal position (x coordinate) at which to place the image data in the destination canvas.
dynumberVertical 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

NameTypeDescription
xnumberThe x-axis coordinate of the rectangle's starting point.
ynumberThe y-axis coordinate of the rectangle's starting point.
widthnumberThe rectangle's width. Positive values are to the right, and negative to the left.
heightnumberThe 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

NameTypeDescription
anglenumberThe 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

NameTypeDescription
xnumberScaling factor in the horizontal direction. A negative value flips pixels across the vertical axis. A value of 1 results in no horizontal scaling.
ynumberScaling 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:

[acebdf001]\left[ \begin{array}{ccc} a & c & e \\ b & d & f \\ 0 & 0 & 1 \end{array} \right]

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

NameTypeDescription
anumberm11m_{11} Horizontal scaling. A value of 1 results in no scaling.
bnumberm12m_{12} Vertical skewing.
cnumberm21m_{21} Horizontal skewing.
dnumberm22m_{22} Vertical scaling. A value of 1 results in no scaling.
enumberdxdx Horizontal translation (moving).
fnumberdydy 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

NameTypeDescription
xnumberThe x-axis coordinate of the rectangle's starting point.
ynumberThe y-axis coordinate of the rectangle's starting point.
widthnumberThe rectangle's width. Positive values are to the right, and negative to the left.
heightnumberThe 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

NameTypeDescription
textstringA string specifying the text string to render into the context. The text is rendered using the settings specified by font.
xnumberThe x-axis coordinate of the point at which to begin drawing the text.
ynumberThe 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

NameTypeDescription
xnumberDistance to move in the horizontal direction. Positive values are to the right, and negative to the left.
ynumberDistance to move in the vertical direction. Positive values are down, and negative are up.

Returns

void