Reference

When you begin a new project in jsCanvas you'll notice that it consists of a tab called Main and some template code. Your project can consist of several tabs, the initial one is always called Main. If you add more tabs they will be listed across the top.

function setup() {
    print("hello world");
}

function draw() {
    background(40,40,50);
    fill(150,200,30);
    stroke(200,30,150);
    strokeWidth(10);
    rect(20,20,100,100);
}

This is the framework that your project will use to run. There are two functions defined for you initially: setup() and draw().

setup() and draw() are executed by jsCanvas when you press the execute button to run your project. The setup() function is called once, at the start, and then the draw() function is called repeatedly. In setup() jsCanvas expects you to set up your initial program state, and in draw() you can tell jsCanvas to render graphics onto the screen, update your program state over time, and so on.

There are two other important functions that deal with one method for how the user can interact with a running jsCanvas program (the other method is to use parameters). These are the touched and key functions. The first deals with any touch or mouse events, the second with any keyboard events (note that on mobile devices, it may not be possible to use the keyboard). These functions are called between repeats of the draw function.

In the next two sections we will cover these functions in detail.

When you press the execute button, the draw() function is repeatedly executed by jsCanvas.

function draw() {
    // Set the background colour to blueish
    background(100,120,180);

    // Set the fill colour to red
    fill(255,0,0);

    // Set a wide outline
    strokeWidth(5);

    // Set the outline colour to white
    stroke(255);

    // Draw a red circle with a white outline
    // In the center of the screen
    ellipse( WIDTH/2, HEIGHT/2, 200 );
}

Note that the above code will run many times every second. That is, you are telling jsCanvas to paint the background blue and draw a red circle with a white outline several times per second, from scratch. It does this so that you can create smooth motion by changing your program state over time, and updating your drawing code to reflect the new state. For example, you might make the circle bounce on the ground by changing its Y-position (the second parameter to ellipse()) every frame.

When you press the execute button jsCanvas will call the setup() function once, before it begins calling the draw() function. In here you can perform any once-off computations, set up program state, set the display mode, and do things that you don't need to do every frame. For example, the setup() function below creates a global variable controlled by a slider. This variable is then used in the draw() function to control the Y-position of a circle.

The touched function deals with any mouse or touch events (specifically, those that occur on the canvas). After each time the draw function is called, the touched function is called for each mouse or touch event that occured during the previous draw function. It is passed one parameter, which is an object consisting of lots of information about the event.

A touch object has the following information:

The key function deals with any keyboard events (specifically, those that occur on the canvas). After each time the draw function is called, the key function is called for each keyboard event that occured during the previous draw function. It is passed one parameter, which is an object consisting of lots of information about the event.

Clears the background to the specified colour. You should generally call this at the start of your draw() function in order to clear the contents of the previous frame.

Draws an ellipse centered at x, y with horizontal and vertical dimensions specified by width and height. The ellipseMode() function sets how these parameters are interpreted. Use fill() to set the colour of an ellipse and stroke() to set its outline colour.

If only the width is specified, this is treated as the ellipse diameter (or radius, if ellipseMode( RADIUS ) is used) and the result is a circle. The interpretation of an ellipse's x, y, width and height parameters can be specified using the ellipseMode() function. ellipseMode() is set to CENTER by default.

Draws a circle centered at x, y with radius radius. The ellipseMode() function sets how these parameters are interpreted. Use fill() to set the colour of an circle and stroke() to set its outline colour. The interpretation of a circles x, y, and radius parameters can be specified using the ellipseMode() function. ellipseMode() is set to CENTER by default.

Draws a rectangle with its lower-left corner positioned at x, y and sized at width, height. Use fill() to set the colour of a rectangle and stroke() to set the outline colour.

The interpretation of a rectangle's x, y, width and height parameters can be specified using the rectMode() function. rectMode() is set to CORNER by default.

Draws a polygon with the specified vertices. Use fill() to set the colour of a polygon and stroke() to set the outline colour.

Draws a series of lines through with the specified points. Use fill() to set the colour of a polyline and stroke() to set the outline colour. The difference between a polyline and a polygon is that a polygon is a closed shape, whereas a polyline does not automatically join up.

Draws text at the given x, y location. You can set the font used by text() with the font() function. Text appearance can be further configured by using the fontSize() and fill() functions.

You can change the alignment and wrapping of text by using textAlign() and textWrapWidth(). If textWrapWidth() is set to 0 (the default) text will be drawn on one line. If textWrapWidth() is set to a value greater than 0 the text will word-wrap if it exceeds the width specified by textWrapWidth()

By default the x and y parameters set the location of the center of the text, the origin mode can be set using the textMode() and textValign() functions. Text colour can be changed with the fill() function.

If you need to get the dimensions of a string in the current style, see the textSize function documentation.

Draws a line between the two points specified by x1,y1 and x2,y2 (either or both can specified by a Vec2). A line's colour can be set with the stroke() function and its width can be set with the strokeWidth() function. A line's cap style can be changed with the lineCapMode() function.

Draws an arc as specified by the parameters. It starts at the point x,y and has radius radius. The span of the arc is specified by the angles startAngle and endAngle. The first is the initial angle. If arcMode is set to ABSOLUTE then endAngle is the final angle, otherwise it is the angle subtended by the arc (sometimes referred to as the delta angle). The final argument, a boolean, determines whether the arc is drawn anti-clockwise (true or blank) or clockwise (false). Angles are specified in degrees.

Draws a cubic bezier as specified by the parameters. It starts at the point x1,y1, ends at x4,y4, and has control points x2,y2 and x3,y3. The points can be Vec2s. If bezierMode is ABSOLUTE then the control points are the actual points, if bezierMode is RELATIVE then the control points are relative to the respective endpoints.

Translates all subsequent drawing operations by the specified x and y values. Translations are cumulative, so a call to translate( 50, 0 ) followed by a call to translate( 10, 10 ) will translate all subsequent drawing operations by 60, 10.

Specifies an amount of rotation (in degrees) to apply to all subsequent drawing. All subsequent drawing functions will be rotated by angle value specified in this function. Rotations are cumulative, so calling rotate(30) followed by rotate(20) has the same effect as rotate(50).

rotate() can also be called with a point, defined by the x, and y parameters. This allows rotation to occur about an arbitrary point.

Specifies an amount of scale to apply to all drawing. All subsequent drawing functions will be scaled by the x and y values specified in this function. Scale values are specified as a scalar multipliers, for example, scale(2.0, 2.0) will double the x and y dimensions of subsequent drawing commands. scale() is cumulative, so calling scale(0.5) followed by scale(0.5) will scale all subsequent drawing operations by 0.25 (i.e., one quarter of their original size).

Composes the transformation specified by transformation with the current model transformation. The current model transformation represents the world transform, this is the same transformation used in pushTransformation and popTransformation operations.

When called with no arguments, returns a transformation containing current world transformation. When called with a transformation argument, sets the current world transformation to the given transformation.

This type represents a colour with transparency information. You can provide this type as arguments to the style functions fill(), tint(), stroke(), and background(). You can specify the colour in a variety of ways, either by specifying the red, green, blue, and alpha components directly or by passing a string describing the colour in one of the CSS formats or as an SVG or X11 named colour.

This method computes a colour by blending two colour types. Colours are blended based on the first colour's alpha value. The blend amount is determined by the alpha value of the colour invoking this method.

This method computes a colour by mixing two colour types linearly. Colours are blended based on the specified mix value, amount. A value of 0.5 for amount will generate a colour that is half way between the two input colours.

Sets the blend mode for all further drawing. The blend mode decides how new drawing operations are blended with underlying pixels. See the MDN article on blendmodes for details.

Sets the origin of the ellipses and circles drawn with the ellipse() and circle() functions. The default is ellipseMode( CENTER ).

Sets the origin of the rectangles drawn with the rect() function. The default is rectMode( CORNER ).

Sets how the final angle is interpreted in the arc() function.

Sets how the control points are interpreted in the bezier() function.

Sets the origin of text drawn with the text() function. The default is textMode( CENTER ).

Sets the style of the line caps drawn with the line() function. The default is lineCapMode( ROUND ). Note that lineCapMode() only has an effect if smooth() is set.

Sets the colour used to fill shapes drawn with the ellipse() and rect() functions. Also sets the colour of text drawn with the text() function.

Sets the colour of the fill to completely transparent.

Sets the colour used to outline the shapes drawn with the ellipse() and rect() functions. Also sets the colour of lines drawn with the line() function.

Sets the width of the outline of shapes drawn with the ellipse() and rect() functions. Also sets the width of lines drawn with the line() function.

Sets the stroke width to zero.

This sets the current font to the font specified by name. If no argument is given font() returns the current font. The default font is "Helvetica".

This sets the current font size to the size specified by size. If no argument is given fontSize() returns the current font size. The default font size is 17 points.

This sets the horizontal alignment of text rendered with the text() function. This is generally used in conjunction with textWrapWidth() to produce multi-line, word-wrapped text aligned to the LEFT, CENTER or RIGHT. If called without arguments this function returns the current text alignment. The default text alignment is textAlign( LEFT ).

This sets the vertical alignment of text rendered with the text() function. If called without arguments this function returns the current text alignment. The default text alignment is textValign( BASELINE ).

This function returns the width of the specified string when rendered with the current font size and style. You can use this to, for example, render a button behind a piece of text, position text within a speech bubble, and so on.

The pushTransformation() function saves any transformations that have been made and pushes a copy of them onto the top of the stack. You can then perform further transforms (translations, rotations and scales), perform drawing operations, and return to the previous transformation by calling popTransformation(). You can nest calls to pushTransformation() and popTransformation() for more complex object placement.

The following transform calls are preserved when using pushTransformation() and popTransformation(): translate(), rotate(), scale()

The popTransformation() function saves any transformations that have been made and pushes a copy of them onto the top of the stack. You can then perform further transforms (translations, rotations and scales), perform drawing operations, and return to the previous transformation by calling popTransformation(). You can nest calls to pushTransformation() and popTransformation() for more complex object placement.

The following transform calls are preserved when using pushTransformation() and popTransformation(): translate(), rotate(), scale()

This function resets all transformation. It replaces the current transform transformation with the identity transformation. This effectively repositions all drawing at 0, 0, with no rotation and scaling.

The pushStyle() function saves the current graphics style and pushes a copy of the current style onto the top of the stack. You can then modify the style, perform drawing operations, and return to the previous style by calling popStyle(). You can nest calls to pushStyle() and popStyle() in order to provide more control.

Styles set with the following functions are preserved when using pushStyle() and popStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth(), font(), fontSize(), textAlign(), textMode() and textWrapWidth()

The pushStyle() function saves the current graphics style and pushes a copy of the current style onto the top of the stack. You can then modify the style, perform drawing operations, and return to the previous style by calling popStyle(). You can nest calls to pushStyle() and popStyle() in order to provide more control.

Styles set with the following functions are preserved when using pushStyle() and popStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth()

Calling resetStyle() will reset all style parameters to their default values. This will effect whatever style is currently on the top of the stack.

Styles set with the following functions are reset when using resetStyle(): fill(), noFill(), stroke(), noStroke(), tint(), noTint(), strokeWidth(), lineCapMode(), ellipseMode(), rectMode(), spriteMode(), smooth(), noSmooth()

Parameters are ways to elicit information from the user. A parameter defines a widget in the parameters panel (on the left of the browser window) which the user can interact with at any time during the execution of the script. To create parameter, you write:

p = new Parameter(options);

where options specifies the type and various options of the parameter. You would generally do this in the setup function.

All parameters except the action parameter have a value which can be accessed by the value attribute of the newly created parameter. Changing this value doesn't update the widget, for that you have to use:

p.setValue(value);

All parameters can be passed a callback function which is called whenever the value of the parameter is changed by the user. The callback function will be passed the new value.

The different types of parameter are:

• number
• text
• boolean
• select
• colour
• action
• watch

("watch" isn't technically a parameter but it operates on a similar principle so is included here.)

This parameter creates a visual slider in the parameter panel that can be used to get a number from the user. When you adjust the slider in the viewer, the variable will be set appropriately. The three parameters, min, max, and step allow you to set the minimum, maximum, and step value of your parameter respectively. If an initial value is not specified, then the parameter takes on the minimum value initially. If no minimum or maximum values are specified, the parameter uses the range [0, 1] with step value 0.1. If the minimum and maximum are specified but the step value is not, the step value is taken to be 1.

This function creates a visual colour sample in the viewer that can be used to get a colour from the user. Note that this uses the HTML5 colour picker. In some browsers, there is no obvious Select button and the picker should be dismissed by clicking the X button on its window.

This function creates a drop-down list in the viewer that can be used to get a choice from the user.

This function creates a visual switch in the viewer that can be used to get a boolean from the user.

This function creates a visual text box in the viewer. You can use this to get some text from the user.

This function creates a visual button in the viewer sidebar. Pressing the button will call the function defined by callback. This parameter has no value, so there is generally no need to assign it to a variable.

This function allows you to monitor the return value of a javascript function within the viewer.

This function clears the parameter list of all parameter widgets and watch values. You can then re-add parameters using the parameter group of functions.

This type represents a 2D vector.

This method returns the sum of two Vec2 types

This method increments a Vec2 by another. It modifies the calling object in place.

This method returns the result of subtracting one Vec2 from another

This method decrements a Vec2 by another. It modifies the calling object in place.

This method returns the product of a Vec2 and a number or another Vec2s. In the latter case, the Vec2s are treated as complex numbers.

This method multiplies this Vec2 by either a number or another Vec2, modifying the calling object.

This method returns the result of dividing this Vec2 by either a number or another Vec2. In the latter case, the division is that of complex numbers.

This method divides this Vec2 by either a number or another Vec2. In the latter case, the division is that of complex numbers. This modifies the calling object.

This method returns the negative of this Vec2

This method negates this Vec2, modifying the calling object

This method compares this Vec2 with another

This method returns a normalized version of the vector

This method returns a normalized version of the vector, modifying the calling object

This method returns the distance between two Vec2 types

This method returns the squared distance between two Vec2 types

This method returns the length of a Vec2

This method returns the squared length of a Vec2

This method returns the cross product between two Vec2 types

This method returns a rotated copy of a Vec2 type. The angle is assumed to be degrees.

This method returns a rotated copy of a Vec2 type. The angle is assumed to be degrees. This method modifies the calling object.

This method returns a copy of a Vec2 type, rotated 90 degrees.

This method returns a copy of a Vec2 type, rotated 90 degrees. This method modifies the calling object.

This method returns the angle between this Vec2 and v in degrees.

This method returns the angle between this Vec2 and the x-axis in degrees.

This constant is set to the width of the screen in pixels.

This constant is set to the height of the screen in pixels.

Query this variable to get the current elapsed time, in seconds, while running your project.

Query this variable to get the time elapsed, in seconds, since the last draw call while running your project.