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);
rasterAdd
Two colours added channel by channel, each saturating at 255: how light adds.
rasterDim
A dimmer copy of the same hue.
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.
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.
rasterGlow
Light added around a point, brightest at the centre and falling off with the square of the distance: a halo.
rasterGradient
Every pixel of the frame, as a vertical gradient: a background.
rasterHue
The fully saturated colour at a hue, so a rainbow is rasterHue(phase + i * step).
rasterMix
a moved toward b by a fraction.
rasterMixWeight
a moved toward b by a 0..256 weight, which a per-pixel loop computes once with rasterWeight.
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.
rasterPixel
A pixel coordinate floored to an i32, clamped first so neither a huge value nor NaN can overflow the conversion.
rasterPushTrail
Add the newest point to a trail, forgetting the oldest when it is full.
rasterRect
The pixel rectangle x0..x1 × y0..y1 (right and bottom exclusive) set to a colour or blended toward it, clipped to the frame.
rasterRgb
A colour from three channels.
rasterSpawnParticle
A new particle in the pool's oldest slot, live or not, so a full pool replaces its oldest particle.
rasterStepParticles
One step of a pool: every live particle falls, slows, moves and ages.
rasterText
Text in the 5×7 font, each font pixel a scale × scale block of frame pixels.
rasterTextWidth
The width text takes in the 5×7 font: six font pixels a glyph, less the last gap.
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.
rasterWeight
A fraction as the 0..256 weight the mixes and rasterRect take.
RasterParticles
A fixed pool of particles: sparks, debris, fireworks.
RasterTrail
The last positions of something moving, newest last, in a ring made once: what rasterTrail draws behind it.
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-pixelsFramebufferlends itspixels(ani32[], which is the same type tonish) with itswidthandheight, passed throughrasterFrame, which returns the same array and exists only becausetscreadsInt32Arrayas the JavaScript view (runtime/nish.d.ts); -
a wasm program lends an
Int32Arrayit 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
ai32requiredone colour
bi32requiredthe other
returnsi32the sum
rasterDim
A dimmer copy of the same hue.
const rasterDim: (c: i32, k: f64) => i32
ci32requiredthe colour
kf64requiredthe factor every channel is multiplied by, clamped to 0..1
returnsi32the 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
cxf64requiredthe centre's x in pixels
cyf64requiredthe centre's y in pixels
rf64requiredthe radius in pixels; 0 or less draws nothing
colouri32requiredthe colour, 0xRRGGBB
alphaf64requiredthe 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[]requiredthe frame, such as a Framebuffer's pixels
returnsInt32Arraypixels 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
cxf64requiredthe centre's x in pixels
cyf64requiredthe centre's y in pixels
rf64requiredthe radius in pixels the light reaches; 0 or less draws nothing
colouri32requiredthe light's colour, 0xRRGGBB
strengthf64requiredhow 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
topi32requiredthe colour of the first row
bottomi32requiredthe 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
hf64requiredthe hue in turns: 0 is red, 1/3 green, 2/3 blue; any value wraps
returnsi32the colour
rasterMix
a moved toward b by a fraction.
const rasterMix: (a: i32, b: i32, t: f64) => i32
ai32requiredthe colour at 0
bi32requiredthe colour at 1
tf64requiredhow far, clamped to 0..1
returnsi32the 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
ai32requiredthe colour at weight 0
bi32requiredthe colour at weight 256
wi32requiredthe weight, 0 to RASTER_SOLID
returnsi32the 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
poolRasterParticlesrequiredthe pool
alphaf64requiredhow far between the last step and this one, 0..1
scalef64requiredframe pixels per pool unit
offsetXf64requiredthe pixel x of pool x 0
offsetYf64requiredthe 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
vf64requiredthe coordinate
returnsi32floor(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
trailRasterTrailrequiredthe trail
xf64requiredthe point's x
yf64requiredthe 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
x0i32requiredthe first column
y0i32requiredthe first row
x1i32requiredone past the last column
y1i32requiredone past the last row
colouri32requiredthe colour, 0xRRGGBB
weighti32requiredhow 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
ri32requiredred, clamped to 0..255
gi32requiredgreen, clamped to 0..255
bi32requiredblue, clamped to 0..255
returnsi32the 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
poolRasterParticlesrequiredthe pool
xf64requiredthe centre's x
yf64requiredthe centre's y
vxf64requiredunits a second across
vyf64requiredunits a second down
lifef64requiredseconds it lives; 0 or less spawns it dead
sizef64requiredthe side of its square
colouri32requiredits 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
poolRasterParticlesrequiredthe pool
dtf64requiredthe step in seconds
gravityf64requiredunits a second squared, down
dragf64requiredthe 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
xi32requiredthe left edge in pixels
yi32requiredthe top edge in pixels
scalei32requiredthe font scale; under 1 draws nothing, over RASTER_MAX_TEXT_SCALE draws at that
textstringrequiredthe text
colouri32requiredthe 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
textstringrequiredthe text, one glyph a byte, so a character outside ASCII takes one per UTF-8 byte
scalei32requiredthe font scale, frame pixels per font pixel
returnsi32the 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
pixelsInt32Arrayrequiredthe frame, row-major
widthi32requiredthe frame's width in pixels
heighti32requiredthe frame's height in pixels
trailRasterTrailrequiredthe trail
rf64requiredthe newest disc's radius, in the trail's units
colouri32requiredthe colour, 0xRRGGBB
alphaf64requiredthe newest disc's opacity
scalef64requiredframe pixels per trail unit
offsetXf64requiredthe pixel x of trail x 0
offsetYf64requiredthe pixel y of trail y 0
rasterWeight
A fraction as the 0..256 weight the mixes and rasterRect take.
const rasterWeight: (t: f64) => i32
tf64requiredthe fraction, clamped to 0..1; NaN is 0
returnsi32the 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".

