Graphics

Screens

To use Pi.js’s many graphics functions, you must first call the screen function. The screen function will create a canvas, set it as the default screen, and append it to the page.

$.screen( "320x200" );

// Set border color to yellow
$.setColor( "yellow" );

// Draw a rectangle with a blue fill color
$.rect( 150, 80, 40, 40, "blue" );

You can have multiple screens for a single page. They will be overlaid on top of each other in the order they are created. You can set the background color of the screen to transparent with setBgColor to see one screen behind another. When calling the screen function, it will return a screen object that you can use to access its graphics functions. If you use graphics functions without a screen object, then it will call the graphics function against the default screen which is the last screen object created or a screen that was set as default with the setScreen command.

let screen1 = $.screen( "320x200" );
let screen2 = $.screen( "80x50" );
screen2.setBgColor( "rgba(0,0,0,0)" );
$.setColor( "blue" );
$.line( 0, 0, 79, 49 );
screen1.setColor( "red" );
screen1.line( 319, 0, 0, 199 );

// Set to screen1 at index 0.
// Alternative would be to call $.setScreen( screen1 );
$.setScreen( 0 );
$.line( 0, 99, 319, 99 );

// Set to screen2 at index 1
$.setScreen( 1 );
$.line( 39, 0, 39, 49 );

Images

Pi.js has two ways to draw images, drawImage and drawSprite. The drawImage function will draw the entire image from a file. The drawSprite function will split the image file into multiple images that can be drawn independently. When dealing with image files and other assets, you will have to wait until they are loaded before you can use them. Use the ready function with a promise or callback that lets you run code after the assets are fully loaded.

// Draw an animated cat using requestAnimationFrame
$.screen( "150x100" );
$.loadSpritesheet( "media/cat_sprite.png", "cat", 34, 34, 1 );
$.ready( () => {
	const catData = $.getSpritesheetData( "cat" );
	const animate = ( t ) => {
		$.cls();
		const frame = Math.floor( t / 100 ) % catData.frameCount;
		$.drawSprite( "cat", frame, 75, 50, null, 0.5, 0.5 );
		requestAnimationFrame( animate );
	};
	requestAnimationFrame( animate );
} );

Primitives

One of the most basic graphics functions in Pi.js is line, which allows you to draw a line between two points. The syntax for line is straightforward: line(x1, y1, x2, y2). This function draws a straight line between the two specified points, making it ideal for creating basic geometric shapes and connecting various points in a drawing.

$.screen( "300x200" );
$.setColor( 4 );
$.line( 15, 15, 285, 185 );
$.setColor( 2 );
$.line( 15, 185, 285, 15 );

Another primitive graphics function in Pi.js is circle, which allows you to draw circles of varying sizes. The syntax for circle is: circle(x, y, radius, fillColor). This function draws a circle centered on the specified point with the given radius and optionally fills in the area inside the circle if a fillColor parameter is provided. It will use the current foreground color (light gray by default). You can change the foreground color by calling setColor.

$.screen( "300x200" );
$.circle( 150, 100, 50, "red" );

Colors

Pi.js provides a lot of great ways to add color to your Pi.js projects. By default there is a color palette that has 256 colors and you can reference the colors by index values from the palette.

$.screen( "360x300" );
const colors = $.getPal();
const size = 20;
let x = 0;
let y = 0;
for( let i = 0; i < colors.length; i++ ) {
	$.setColor( i );
	$.rect( x, y, size, size );
	$.setPosPx( x + 1, y + 4 );
	$.print( i, true );
	x += size;
	if( x >= $.width() ) {
		x = 0;
		y += size;
	}
}

You can use the index values on any Pi.js graphics methods that have a color parameter. You can also access colors by various other means such as color name, rgb values, or a color hex string.

$.screen( "300x200" );
$.setColor( 2 );
$.print( "This is color 2 which is green" );
$.setColor( "blue" );
$.print( "This is the color blue." );
$.setColor( "rgb(0,255,255)" );
$.print( "This is the color cyan" );
$.setColor( [ 255, 255, 255 ] );
$.print( "Below is a rectangle with a white border and purple fill" );
$.rect( 15, 50, 40, 40, "#837" );

You can set your own palettes and default palette to help you control the colors used in your projects. Note that palettes in Pi.js are for convenience, you are not restricted to using just the colors in the palette.

const colors = [ "brown", "darkgrey" ];
const brick = [
	"1111111211111112".split( "" ),
	"1111111211111112".split( "" ),
	"1111111211111112".split( "" ),
	"2222222222222222".split( "" ),
	"1112111111121111".split( "" ),
	"1112111111121111".split( "" ),
	"1112111111121111".split( "" ),
	"2222222222222222".split( "" ),
	"1111111211111112".split( "" ),
	"1111111211111112".split( "" ),
	"1111111211111112".split( "" ),
	"2222222222222222".split( "" ),
	"1112111111121111".split( "" ),
	"1112111111121111".split( "" ),
	"1112111111121111".split( "" ),
	"2222222222222222".split( "" )
];
$.setDefaultPal( colors );
$.screen( "300x200" );
$.put( brick, 16, 16 );
$.setPalColors( [ 1 ], [ "blue" ] );
$.put( brick, 32, 16 );

Please check out the Pi.js Reference page to see a full listing of graphics functions.