nish/raster

Software drawing into a frame of 0xRRGGBB pixels: colour arithmetic, rectangles, anti-aliased discs, additive glows, a vertical gradient, a 5×7 pixel font, and two fixed pools that move and draw themselves (a particle pool and a trail).

import {
  RASTER_GLYPH_ADVANCE,
  RASTER_GLYPH_H,
  RASTER_GLYPH_W,
  RASTER_MAX_TEXT_SCALE,
  RASTER_SOLID,
  RasterParticles,
  RasterTrail,
  rasterAdd,
  rasterDim,
  rasterDisc,
  rasterFrame,
  rasterGlow,
  rasterGradient,
  rasterHue,
  rasterMix,
  rasterMixWeight,
  rasterParticles,
  rasterPixel,
  rasterPushTrail,
  rasterRect,
  rasterRgb,
  rasterSpawnParticle,
  rasterStepParticles,
  rasterText,
  rasterTextWidth,
  rasterTrail,
  rasterWeight,
} from "nish/raster";
import { Framebuffer } from "nish/term-pixels";
import { rasterDisc, rasterGradient, rasterRgb } from "nish/raster";

const fb = new Framebuffer(320, 180);
const px = rasterFrame(fb.pixels);
rasterGradient(px, fb.width, fb.height, rasterRgb(10, 10, 40), 0);
rasterDisc(px, fb.width, fb.height, 160.0, 90.0, 12.0, 0xffcc00, 1.0);
What it draws into

Every drawing function takes the frame as three arguments, pixels: Int32Array, width: i32, height: i32, row-major with pixel (x, y) at y * width + x. An Int32Array parameter accepts both kinds of frame a program has, so neither path copies:

  • a nish/term-pixels Framebuffer lends its pixels (an i32[], which is the same type to nish) with its width and height, passed through rasterFrame, which returns the same array and exists only because tsc reads Int32Array as the JavaScript view (runtime/nish.d.ts);
  • a wasm program lends an Int32Array it declares as module storage, which the page reads in place (nish/host/game's frame is one).

The functions only index the frame, which is what lets module storage be lent to them. A frame shorter than width * height loses the rows it does not hold, and everything is clipped to the frame, so no coordinate, however wild, reads or writes outside it.

Shapes take pixel coordinates as f64 where a fraction matters (a disc's centre and radius) and as i32 where it does not (a rectangle's edges). The pools keep positions in whatever units the caller simulates in and draw through a transform, pixel = offset + v * scale, so a game can keep its world apart from the frame's size.

Nothing here allocates after a pool is made, and every shape touches each pixel it covers a bounded number of times, so a frame's cost follows the frame's size. Pure: no capability, no I/O and no clock.

Functions

rasterAdd

Two colours added channel by channel, each saturating at 255: how light adds.

const rasterAdd: (a: i32, b: i32) => i32
ai32required

one colour

bi32required

the other

returnsi32

the sum

rasterDim

A dimmer copy of the same hue.

const rasterDim: (c: i32, k: f64) => i32
ci32required

the colour

kf64required

the factor every channel is multiplied by, clamped to 0..1

returnsi32

the dimmed colour

rasterDisc

A disc blended over what is there, its edge anti-aliased: each pixel is weighed by how much of it the circle covers, so a disc a few pixels wide still looks round, and one narrower than a pixel fades out rather than stay a grey dot.

const rasterDisc: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  cx: f64,
  cy: f64,
  r: f64,
  colour: i32,
  alpha: f64,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

cxf64required

the centre's x in pixels

cyf64required

the centre's y in pixels

rf64required

the radius in pixels; 0 or less draws nothing

colouri32required

the colour, 0xRRGGBB

alphaf64required

the opacity, clamped to 0..1

rasterFrame

An i32[] frame as the Int32Array the drawing functions take: the same array, not a copy, so drawing through the result draws into pixels.

const rasterFrame: (pixels: i32[]) => Int32Array
pixelsi32[]required

the frame, such as a Framebuffer's pixels

returnsInt32Array

pixels itself

rasterGlow

Light added around a point, brightest at the centre and falling off with the square of the distance: a halo.

const rasterGlow: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  cx: f64,
  cy: f64,
  r: f64,
  colour: i32,
  strength: f64,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

cxf64required

the centre's x in pixels

cyf64required

the centre's y in pixels

rf64required

the radius in pixels the light reaches; 0 or less draws nothing

colouri32required

the light's colour, 0xRRGGBB

strengthf64required

how much: 1 adds the full colour at the centre

rasterGradient

Every pixel of the frame, as a vertical gradient: a background.

const rasterGradient: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  top: i32,
  bottom: i32,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

topi32required

the colour of the first row

bottomi32required

the colour of the last row

rasterHue

The fully saturated colour at a hue, so a rainbow is rasterHue(phase + i * step).

const rasterHue: (h: f64) => i32
hf64required

the hue in turns: 0 is red, 1/3 green, 2/3 blue; any value wraps

returnsi32

the colour

rasterMix

a moved toward b by a fraction.

const rasterMix: (a: i32, b: i32, t: f64) => i32
ai32required

the colour at 0

bi32required

the colour at 1

tf64required

how far, clamped to 0..1

returnsi32

the mixed colour

rasterMixWeight

a moved toward b by a 0..256 weight, which a per-pixel loop computes once with rasterWeight.

const rasterMixWeight: (a: i32, b: i32, w: i32) => i32
ai32required

the colour at weight 0

bi32required

the colour at weight 256

wi32required

the weight, 0 to RASTER_SOLID

returnsi32

the mixed colour

rasterParticles

Every live particle of a pool as a square blended over the frame, at its position alpha of the way from the last step to this one and faded by the life it has left. A position v is drawn at pixel offset + v * scale.

const rasterParticles: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  pool: RasterParticles,
  alpha: f64,
  scale: f64,
  offsetX: f64,
  offsetY: f64,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

poolRasterParticlesrequired

the pool

alphaf64required

how far between the last step and this one, 0..1

scalef64required

frame pixels per pool unit

offsetXf64required

the pixel x of pool x 0

offsetYf64required

the pixel y of pool y 0

rasterPixel

A pixel coordinate floored to an i32, clamped first so neither a huge value nor NaN can overflow the conversion.

const rasterPixel: (v: f64) => i32
vf64required

the coordinate

returnsi32

floor(v), held to ±1000000; NaN is -1000000

rasterPushTrail

Add the newest point to a trail, forgetting the oldest when it is full.

const rasterPushTrail: (
  trail: RasterTrail,
  x: f64,
  y: f64,
) => void
trailRasterTrailrequired

the trail

xf64required

the point's x

yf64required

the point's y

rasterRect

The pixel rectangle x0..x1 × y0..y1 (right and bottom exclusive) set to a colour or blended toward it, clipped to the frame.

const rasterRect: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  x0: i32,
  y0: i32,
  x1: i32,
  y1: i32,
  colour: i32,
  weight: i32,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

x0i32required

the first column

y0i32required

the first row

x1i32required

one past the last column

y1i32required

one past the last row

colouri32required

the colour, 0xRRGGBB

weighti32required

how much of colour, 0 to RASTER_SOLID (see rasterWeight); 0 draws nothing

rasterRgb

A colour from three channels.

const rasterRgb: (r: i32, g: i32, b: i32) => i32
ri32required

red, clamped to 0..255

gi32required

green, clamped to 0..255

bi32required

blue, clamped to 0..255

returnsi32

the colour as 0xRRGGBB

rasterSpawnParticle

A new particle in the pool's oldest slot, live or not, so a full pool replaces its oldest particle.

const rasterSpawnParticle: (
  pool: RasterParticles,
  x: f64,
  y: f64,
  vx: f64,
  vy: f64,
  life: f64,
  size: f64,
  colour: i32,
) => void
poolRasterParticlesrequired

the pool

xf64required

the centre's x

yf64required

the centre's y

vxf64required

units a second across

vyf64required

units a second down

lifef64required

seconds it lives; 0 or less spawns it dead

sizef64required

the side of its square

colouri32required

its colour, 0xRRGGBB

rasterStepParticles

One step of a pool: every live particle falls, slows, moves and ages.

const rasterStepParticles: (
  pool: RasterParticles,
  dt: f64,
  gravity: f64,
  drag: f64,
) => void
poolRasterParticlesrequired

the pool

dtf64required

the step in seconds

gravityf64required

units a second squared, down

dragf64required

the fraction of its speed a particle loses a second

rasterText

Text in the 5×7 font, each font pixel a scale × scale block of frame pixels. Text is pixel art, so it sits on whole pixels and is never blended. A byte outside ASCII 32..126 draws as ?, so a character outside ASCII draws as one ? for each of its UTF-8 bytes.

const rasterText: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  x: i32,
  y: i32,
  scale: i32,
  text: string,
  colour: i32,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

xi32required

the left edge in pixels

yi32required

the top edge in pixels

scalei32required

the font scale; under 1 draws nothing, over RASTER_MAX_TEXT_SCALE draws at that

textstringrequired

the text

colouri32required

the colour, 0xRRGGBB

rasterTextWidth

The width text takes in the 5×7 font: six font pixels a glyph, less the last gap.

const rasterTextWidth: (text: string, scale: i32) => i32
textstringrequired

the text, one glyph a byte, so a character outside ASCII takes one per UTF-8 byte

scalei32required

the font scale, frame pixels per font pixel

returnsi32

the width in frame pixels, 0 for empty text or a scale under 1

rasterTrail

A trail as a line of discs from oldest to newest, each larger and more opaque than the one before: a streak that fades out behind what made it. A point at v is drawn at pixel offset + v * scale.

const rasterTrail: (
  pixels: Int32Array,
  width: i32,
  height: i32,
  trail: RasterTrail,
  r: f64,
  colour: i32,
  alpha: f64,
  scale: f64,
  offsetX: f64,
  offsetY: f64,
) => void
pixelsInt32Arrayrequired

the frame, row-major

widthi32required

the frame's width in pixels

heighti32required

the frame's height in pixels

trailRasterTrailrequired

the trail

rf64required

the newest disc's radius, in the trail's units

colouri32required

the colour, 0xRRGGBB

alphaf64required

the newest disc's opacity

scalef64required

frame pixels per trail unit

offsetXf64required

the pixel x of trail x 0

offsetYf64required

the pixel y of trail y 0

rasterWeight

A fraction as the 0..256 weight the mixes and rasterRect take.

const rasterWeight: (t: f64) => i32
tf64required

the fraction, clamped to 0..1; NaN is 0

returnsi32

the weight, 0 to RASTER_SOLID

Classes

RasterParticles

A fixed pool of particles: sparks, debris, fireworks. Each particle's position, previous position, velocity, colour, size and life sit in parallel arrays made once, so spawning, stepping and drawing allocate nothing. Slots are reused in spawn order, so when every slot is live a new particle replaces the oldest. Positions and sizes are in the caller's units, speeds in those units a second.

class RasterParticles
Member
new RasterParticles(capacity: i32) A pool of dead particles.
colours: i32[] Each particle's colour.
lives: f64[] Seconds of life left; a particle at or under 0 is dead.
next: i32 The slot the next spawn takes: the oldest.
prevXs: f64[] x a step ago, which a draw interpolates from.
prevYs: f64[] y a step ago.
sizes: f64[] The side of each particle's square.
spans: f64[] The seconds of life each particle was spawned with, which its fade is measured against.
vxs: f64[] Units a second across.
vys: f64[] Units a second down.
xs: f64[] x now.
ys: f64[] y now.
capacity(): i32 How many particles the pool holds at once.
clear(): void Kill every particle.
has(i: i32): boolean Whether a slot is in every one of the parallel arrays, which the pool keeps the same length.
live(): i32 How many particles are alive.

RasterTrail

The last positions of something moving, newest last, in a ring made once: what rasterTrail draws behind it. rasterPushTrail adds a point; a full ring forgets its oldest. Positions are in the caller's units.

class RasterTrail
Member
new RasterTrail(capacity: i32) An empty trail.
count: i32 The points held, up to the capacity.
head: i32 The slot the next point goes in.
xs: f64[] The x of each point, in ring order.
ys: f64[] The y of each point, in ring order.
clear(): void Forget every point.

Limits

1,024

RASTER_MAX_TEXT_SCALE: i32

The largest font scale drawn; a larger one draws at this, so pixel arithmetic cannot overflow an i32.

Constants

6

RASTER_GLYPH_ADVANCE: i32

The step from one glyph to the next in font pixels: the glyph and a one-pixel gap.

7

RASTER_GLYPH_H: i32

A glyph's height in font pixels.

5

RASTER_GLYPH_W: i32

A glyph's width in font pixels.

256

RASTER_SOLID: i32

The weight rasterRect and the mixes read as "all of the new colour".