Simply2D

Introduction

This library for nodejs allows you, thanks to SDL2, to create windows and draw on the screen.

Installation

You can install this library using npm i simply2d. Node.js 22.22.2+, 24.15.0+, or 26+ is required. This library require SDL2 in order to run. Simple DirectMedia Layer is a cross-platform library designed to provide low level access to different resources such as video. SDL2 is available for windows, linux and macos as well.

For Windows

Visual Studio VC tools are required. For more, see https://github.com/nodejs/node-gyp#readme

For Linux

To use Simply2D you must have installed make, a C++17 compiler, Python 3, pkg-config and the SDL2 development packages. To install SDL2 you can use the following command:

For Ubuntu: sudo apt install build-essential python3 pkg-config libsdl2-dev libsdl2-image-dev libsdl2-ttf-dev
For Red Hat and Fedora: sudo dnf install gcc-c++ make python3 pkgconf-pkg-config SDL2-devel SDL2_image-devel SDL2_ttf-devel
For Arch Linux: sudo pacman -S --needed base-devel python pkgconf sdl2 sdl2_image sdl2_ttf

If you encounter any problems, it is recommended to install the latest version of python3 and run python3 -m pip install setuptools or just pip install setuptools

For contributors

On Windows you must create the following files in your project directory:

📁 bin
│  📁 sdl
│  │  📁 winx64
│  │  │  📄 SDl2.dll
│  │  │  📄 SDL2.lib
│  │  │  📄 SDL2main.lib
│  │  │  📄 SDL2test.lib
│  📁 sdlimg
│  │  📁 winx64
│  │  │  📄 SDL2_image.dll
│  │  │  📄 SDL2_image.lib
│  📁 sdlttf
│  │  📁 winx64
│  │  │  📄 SDL2_ttf.dll
│  │  │  📄 SDL2_ttf.lib

These files can be extracted from the following links:

Under the lib/x64 path

To build from source, run npm install, then npm run build. Run the small framebuffer smoke test with npm test (Linux uses offscreen video). Before packing a release, supply the Windows DLLs and import libraries above in bin/; these are included in the npm package. The Windows CI job downloads them before building.

API

Canvas

The Canvas class allows you to create a canvas and to draw on it

import { Canvas } from "simply2d";
const canvas = new Canvas(
	"my canvas",	// window title
	600,			// window width
	400,			// window height
);

You can specify other window options

const canvas = new Canvas("title", 200, 400, 0, 0, {
	mode: "fullscreen",
	resizable: false,
	scale: 2,
	antiAliasing: true
})

Canvas.show

show(): void

Show the window

Canvas.hide

hide(): void

Hide the window

Canvas.setBackgroundColor

setBackgroundColor(color: RGBAColor): void

Set the background color. An RGBAColor is an object that contains red, green, blue and alpha properties.

Canvas.sleep

sleep(ms: number): void

Sleep ms milliseconds

Canvas.drawPoint

drawPoint(color: RGBAColor, position: Position): void

Draw a point on the screen. Position is an object with the x and y properties.

Canvas.drawLine

drawLine(color: RGBAColor, from: Position, to: Position): void

Draw a line from from coordinates to to coordinates

Canvas.drawRectangle

drawRectangle(color: RGBAColor, pos: Position, width: number, height: number, fill?: boolean): void

Draw a rectangle in the canvas

get Canvas.width

get width(): number

Return the window width

get Canvas.height

get height(): number

Return the window height

Canvas.clear

clear(): void

Clear the screen

Canvas.loadRawData

loadRawData(pixels: Uint8Array, bitPerPixel: 8 | 16 | 24 | 32): void

Write directly into the video buffer

Canvas.loadPNG

loadPNG(filename: string): void

Write an PNG image into the canvas

Canvas.loadJPG

loadJPG(filename: string): void

Write a JPG image into the canvas

Canvas.dumpPNG

dumpPNG(filename: string): void

Save the canvas as a PNG file

Canvas.dumpJPG

dumpJPG(filename: string): void

Save the canvas as a JPG file

Canvas.getScale

getScale(): number

Return the scale factor

Canvas.onClick

onClick(callback: (x: number, y: number) => void): void

On click event

Canvas.onKeyDown

onKeyDown(callback: (key: Key) => void): void

On key down event

Canvas.onKeyUp

onKeyUp(callback: (key: Key) => void): void

On key up event

Canvas.initRenderSequence

initRenderSequence(): void

It is used to initialize the rendering sequence. Every drawing process will not be displayed until exposeRender is called

Canvas.exposeRender

exposeRender(): void

Shows rendering

Canvas.waitFrame

waitFrame(): void

Sleep for a certain time before the next frame is rendered

Canvas.loop

loop(callback: () => void): void

Start the rendering loop

Canvas.onKeysDown

onKeysDown(callback: (key: Key[]) => void): void

On keys down event

Canvas.onKeysUp

onKeysUp(callback: (key: Key[]) => void): void

On keys up event

Canvas.loadFont

loadFont(fontName: string, filePath: string): void

Load a new font

Canvas.drawText

drawText(text: string, fontName: string, size: number, color: RGBAColor, start: Position): void

Draw text on the canvas

Canvas.drawArc

drawArc(color: RGBAColor, center: Position, radius: number, startingAngle: number, endingAngle: number): void

Draw an arc

Canvas.convertPolarCords

static convertPolarCoords(center: Position, angle: number, radius: number): Position

Convert polar coordinates into x, y coordinates

Canvas.loadTexture

loadTexture(textureID: string, filePath: string): void

Load a new texture from the specified file

Canvas.drawTexture

drawTexture(textureID: string, pos: Position): void

Draw a previously loaded texture

Canvas.getScreenResolution

static getScreenResolution(): Resolution

Get the screen resolution

Canvas.getTextureResolution

getTextureResolution(textureID: string): Resolution

Get the resolution of a previously loaded texture

Canvas.drawPath

drawPath(path: Path, pos?: Position, color?: RGBAColor)

Draw a path

Canvas.addLayer

addLayer(layerId: string): void

Add a new layer

Canvas.removeLayer

removeLayer(layerId: string): void

Remove layer

Canvas.changeLayer

changeLayer(layerId: string): void

Change current layer

Canvas.useMainLayer

useMainLayer(): void

Change to the main default layer

get Canvas.frameTime

get frameTime(): number

Get current frame time, only if the scene is rendered with loop

get Canvas.fps

get fps(): number

Get current frame time, only if the scene is rendered with loop

Canvas.getLayers

getLayers(): Layer[]

Get layers in order of appearance

Canvas.activateLayer

activateLayer(layerID: string): void

Activate a layer

Canvas.deactivateLayer

deactivateLayer(layerID: string): void

Deactivate a layer

get Canvas.antialiasing

get antialiasing(): boolean

Get antialiasing flag

set Canvas.antialiasing

set antialiasing(): void

Set antialiasing flag

Canvas.clearAll

clearAll(): void

Clear all layers, including the main layer

Canvas.moveLayer

moveLayer(layerID: string, direction: "up" | "down", steps: number = 1): void

Change layer rendering priority

Canvas.attach

attach(buffer: Uint8Array, bitPerPixel: PixelFormat): void

Attach a buffer to the video memory. The loop and every other drawing functions will be disabled.

Canvas.detach

detach(): void

Detach the current buffer from the video memory

Canvas.close

close(): void

Close the window

Canvas.endLoop

endLoop(): void

Terminate the current loop

get Canvas.mousePosition

get mousePosition(): Position

Return the current mouse position

Canvas.applyFilter

applyFilter(fn: (value: number, index: number, buffer: Uint8Array) => number): void

Apply a callback to every byte of the current rendering target and display the result. The callback receives the byte value, byte index, and buffer. Updates happen in place, in index order; returned values are converted to unsigned bytes. This stops the render loop, like attach. Detach any existing buffer first. The temporary buffer is always detached, including when the callback throws.

canvas.applyFilter(value => Math.floor(value / 2));

Canvas options

type CanvasOptions = {
	mode?: "fullscreen" | "minimized" | "maximized" | "hidden" | "shown",
	resizable?: boolean,
	scale?: number,
	antiAliasing?: boolean,
	removeWindowDecoration?: boolean
}

Canvas constant positions

It is possible to access constant positions relative to the size of the canvas. Example:

import { Canvas, Colors } from "simply2d"

const canvas = new Canvas("myCanvas", 200, 200);
canvas.drawLine(Colors.BLUE, canvas.TOP_LEFT /* the top left corner */, canvas.BOTTOM_RIGHT /* the bottom right corner */);

Colors

Colors is an object that contains different standard colors and some useful function

import { Canvas, Colors } from "simply2d";
const canvas = new Canvas("title", 100, 100);
canvas.setBackgroundColor(Colors.RED);	// #FF0000 hex color
canvas.drawLine(
	Colors.BLACK, 	// #000000 hex color
	{
		x: 0,
		y: 0
	},
	{
		x: canvas.getWidth(),
		y: canvas.getHeight()
	}
);

Colors.from8bit

from8bit(color256: number): RGBAColor

Convert an 8 bit color into a 24 bit color

Colors.from16bit

from16bit(color: number): RGBAColor

Convert a 16 bit color into a 24 bit color

Colors.from24bit

from24bit(color: number): RGBAColor

Convert a 24 bit color number into a 24 bit color RGBAColor object

Colors.from32bit

from32bit(color: number): RGBAColor

Convert a 32 bit color number into a RGBAColor object

Position

Is a type for storing coordinates

import { Position } from "simply2d"	// only in typescript
let cord: Position = {
	x: 203,
	y: 301
}

RGBAColor

Used to save RGBA color values

import { RGBAColor } from "simply2d"	// only in typescript
let color: RGBAColor = {
	red: 255,
	green: 255,
	blue: 0,
	alpha: 255
}

Resolution

Used to save a pair of width and height values

import { Resolution } from "simply2d"
let res: Resolution = {
	w: 1920,
	h: 1080
}

Path

A path is an object used to represent a polyline

import { Path } from "simply2d";
const p = new Path();
p.setStart({ x: 10, y: 15 });
p.pushLine({ x: 20, y: 60 });
p.close();

PixelFormats

Static class that stores all the available pixel formats

PixelFormats.rgb332;
PixelFormats.rgb565;
PixelFormats.rgb888;
PixelFormats.rgba8888;

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
examples		examples
include		include
lib		lib
src		src
test		test
tools		tools
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
FUTURE.md		FUTURE.md
LICENSE.txt		LICENSE.txt
README.md		README.md
binding.gyp		binding.gyp
index.d.ts		index.d.ts
index.ts		index.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation