API reference

rate: Int
samples: List[Int]

Rendered sound: sample rate plus 16-bit signed samples (mono).

fn render(source: Text) -> Result[Sound, Text]

Synthesizes .pta source text into a Sound (formats/pta-audio.md).

fn silence(ms: Int) -> Sound

Silence of the given length.

fn tone(note: Text, ms: Int, wave: Text, volume: Int) -> Result[Sound, Text]

A single synthesized note, e.g. tone("c4", 500, "sine", 80).

fn append(a: Sound, b: Sound) -> Sound

b played after a.

fn mix(a: Sound, b: Sound) -> Sound

a and b played together (summed, clamped); length is the longer one.

fn gain(s: Sound, percent: Int) -> Sound

The sound scaled to `percent` loudness (0–200), clamped.

fn repeat(s: Sound, times: Int) -> Sound

The sound repeated `times` times.

fn adsr(s: Sound, attack_ms: Int, decay_ms: Int, sustain: Int, release_ms: Int) -> Sound

The classic ADSR envelope applied over the sound's full length: linear attack and decay to `sustain` percent, then a linear release over the final `release_ms`.

fn to_wav_bytes(sound: Sound) -> Bytes

The single export bridge for playback: RIFF/WAVE PCM bytes.

width: Int
height: Int
pixels: List[Int]

A rendered image: dimensions plus a flat RGB pixel list (3 ints per pixel, row-major, values 0–255).

fn canvas(width: Int, height: Int, r: Int, g: Int, b: Int) -> Image

A solid-color canvas.

fn set_pixel(img: Image, x: Int, y: Int, r: Int, g: Int, b: Int) -> Image

The image with one pixel set (ignores out-of-canvas coordinates).

fn get_pixel(img: Image, x: Int, y: Int) -> Option[List[Int]]

The red/green/blue triple at (x, y), or None outside the canvas.

fn draw_rect(img: Image, x: Int, y: Int, w: Int, h: Int, r: Int, g: Int, b: Int) -> Image

The image with a filled rectangle drawn on it (clipped to the canvas).

fn draw_line(img: Image, x1: Int, y1: Int, x2: Int, y2: Int, r: Int, g: Int, b: Int) -> Image

The image with a straight line drawn on it (Bresenham, clipped).

fn draw_circle(img: Image, cx: Int, cy: Int, radius: Int, r: Int, g: Int, b: Int) -> Image

The image with a filled circle drawn on it (clipped).

fn to_ppm_bytes(img: Image) -> Bytes

The single export bridge for viewing: binary PPM (P6) bytes.

fn from_ppm_bytes(raw: Bytes) -> Result[Image, Text]

The inverse bridge (since Sprint 27): parses the P6 bytes to_ppm_bytes writes — and any binary PPM with maxval 255 — back into an Image, so existing pictures can enter the toolkit.

fn draw_gradient(img: Image, x: Int, y: Int, w: Int, h: Int, r1: Int, g1: Int, b1: Int, r2: Int, g2: Int, b2: Int, direction: Text) -> Image

A linear (`"vertical"`/`"horizontal"`) or `"radial"` gradient fill over the clipped region — any other direction behaves as vertical (v2 toolkit, Sprint 35).

fn draw_polygon(img: Image, points: List[Int], r: Int, g: Int, b: Int) -> Image

A filled polygon from flat x/y pairs (even-odd scanline fill, clipped). Fewer than three points paints nothing (v2 toolkit).

fn flood_fill(img: Image, x: Int, y: Int, r: Int, g: Int, b: Int) -> Image

Four-connected flood fill from (x, y) — the v3 toolkit twin.

fn draw_ops(img: Image, ops: Text) -> Result[Image, Text]

Applies a draw-section's operations (v3 op set, hex colors) onto an existing image — the primitive that makes layers and imported pictures composable (Sprint 38): each op line is exactly a .pti draw: line without its indentation.

fn draw_text(img: Image, x: Int, y: Int, size: Int, r: Int, g: Int, b: Int, content: Text) -> Image

Draws text in the built-in 5×7 pixel font at (x, y), scaled by whole pixels (v4 toolkit, Sprint 40). Unknown characters draw nothing; letters are case-insensitive; spaces advance the pen.

fn crop(img: Image, x: Int, y: Int, w: Int, h: Int) -> Image

The w×h region of the image starting at (x, y); out-of-canvas parts read as black.

fn flip_x(img: Image) -> Image

The image mirrored left–right.

fn flip_y(img: Image) -> Image

The image mirrored top–bottom.

fn scale(img: Image, factor: Int) -> Image

The image scaled up by a whole factor (nearest neighbor).

fn blit(dst: Image, src: Image, x: Int, y: Int) -> Image

The destination with `src` painted onto it at (x, y), clipped.

fn map_pixels(img: Image, f: fn(Int, Int, Int) -> List[Int]) -> Image

A new image with `f` applied to every pixel's r/g/b triple; results are clamped to 0–255.

fn invert(img: Image) -> Image

Every channel inverted.

fn grayscale(img: Image) -> Image

Luma grayscale (Rec. 601 weights).

fn brighten(img: Image, amount: Int) -> Image

Every channel shifted by `amount` (negative darkens), clamped.

fn render(source: Text) -> Result[Image, Text]

Renders .pti source text into an Image (formats/pti-image.md).

fn min(a: Int, b: Int) -> Int

The smaller of two integers.

fn max(a: Int, b: Int) -> Int

The larger of two integers.

fn clamp(x: Int, lo: Int, hi: Int) -> Int

Clamps x into the inclusive range [lo, hi].

fn sign(x: Int) -> Int

-1 for negative numbers, 0 for zero, 1 for positive numbers.

fn is_even(n: Int) -> Bool

Whether n is divisible by two.

fn pow(base: Int, exp: Int) -> Int

base raised to a non-negative exponent (asserts exp >= 0).

fn gcd(a: Int, b: Int) -> Int

The greatest common divisor of two integers (always non-negative).

fn sum(xs: List[Int]) -> Int

The sum of all elements (0 for the empty list).

fn product(xs: List[Int]) -> Int

The product of all elements (1 for the empty list).

fn range(from: Int, to: Int) -> List[Int]

The integers from `from` (inclusive) to `to` (exclusive).

fn largest(xs: List[Int]) -> Option[Int]

The largest element, or None for the empty list.

fn smallest(xs: List[Int]) -> Option[Int]

The smallest element, or None for the empty list.

fn count_where(xs: List[Int], pred: fn(Int) -> Bool) -> Int

How many elements satisfy the predicate.

fn index_of[T](xs: List[T], x: T) -> Int

The index of the first element equal to `x`, or -1 (since Sprint 32 — the first generic functions in the stdlib).

fn reversed[T](xs: List[T]) -> List[T]

The list in reverse order.

fn take[T](xs: List[T], n: Int) -> List[T]

The first `n` elements (fewer when the list is shorter).

fn drop[T](xs: List[T], n: Int) -> List[T]

Everything after the first `n` elements.

fn zip[A, B](xs: List[A], ys: List[B]) -> List[Tuple[A, B]]

Pairs elements up to the shorter length (since Sprint 33 — the first generic function returning tuples of two parameters).

vertices: List[Float]
faces: List[Int]
colors: List[Int]

A triangle mesh: flat vertex coordinates (3 floats per vertex), flat face indices (3 zero-based vertex indices per triangle), and flat RGB colors (3 ints 0–255 per triangle, version 2).

fn add_box(m: Mesh, w: Float, h: Float, d: Float, x: Float, y: Float, z: Float) -> Mesh

A mesh with a cuboid appended: w×h×d, centered on x/z, base at y.

fn add_plane(m: Mesh, w: Float, d: Float, x: Float, y: Float, z: Float) -> Mesh

A mesh with a flat ground rectangle appended (w×d, centered).

fn add_sphere(m: Mesh, r: Float, segments: Int, x: Float, y: Float, z: Float) -> Mesh

A mesh with a UV sphere appended (radius r, `segments` around the equator, segments / 2 rings).

fn render(source: Text) -> Result[Mesh, Text]

Tessellates .ptm source text into a Mesh (formats/ptm-model.md).

fn to_obj_bytes(m: Mesh) -> Bytes

The single export bridge for viewing: Wavefront OBJ text as bytes.

fn render_view(m: Mesh, width: Int, height: Int, yaw: Float, pitch: Float) -> images.Image

A rendered orbit view of the mesh (Sprint 45): the camera is auto-framed on the model's bounding sphere (2.2 radii away), yaw orbits around y and pitch tilts the camera up (both in degrees), triangles are drawn back to front (painter's algorithm) with two-sided shading against a fixed world-space key light.

name: Text
min_version: Text

One dependency: a package name and the minimum version that works.

name: Text
pkg_version: Text
summary: Text
deps: List[Dep]
modules: List[Text]

A parsed package manifest.

fn render(source: Text) -> Result[Package, Text]

Parses polytone.pkg source text (formats/pkg-manifest.md).

name: Text
pkg_version: Text
summary: Text

One package listed by a registry index.

title: Text
packages: List[PackageRef]

A parsed registry index (formats/registry-index.md).

fn render_index(source: Text) -> Result[Registry, Text]

Parses index.ptr source text (formats/registry-index.md).

fn repeat(s: Text, times: Int) -> Text

s repeated `times` times ("" for zero or negative counts).

fn pad_left(s: Text, width: Int, fill: Text) -> Text

Pads s on the left with `fill` (one character) until it is `width` long.

fn pad_right(s: Text, width: Int, fill: Text) -> Text

Pads s on the right with `fill` (one character) until it is `width` long.

fn is_blank(s: Text) -> Bool

Whether s is empty or whitespace-only.

width: Int
height: Int
fps: Int
frames: List[Int]
audio: Text

Rendered video: dimensions, frame rate, flat RGB frame data (width × height × 3 ints per frame, frames in order) — and since v2 the relative address of the declared soundtrack (`""` = none); hosts resolve and render it through the audio codec (spec: the codec stays pure, references resolve outside).

fn render(source: Text) -> Result[Video, Text]

Renders .ptv source text into a Video (formats/ptv-video.md).

fn to_y4m_bytes(v: Video) -> Bytes

The single export bridge for playback: an uncompressed YUV4MPEG2 (C444) stream — `ffplay out.y4m` / `mpv out.y4m` play it directly.

Block.Heading(level: Int, text: Text)
Block.Paragraph(text: Text)
Block.Code(text: Text)
Block.Bullets(items: List[Text])
Block.Link(url: Text, label: Text)
Block.Image(source: Text, alt: Text)
Block.Film(source: Text, alt: Text)
Block.Sound(source: Text, alt: Text)
Block.Input(name: Text, label: Text)
Block.Button(target: Text, label: Text)
Block.Rule

One typed document block — markup never exists as strings. Image/Film/Sound reference native documents by relative address (since v2, Sprint 34).

title: Text
blocks: List[Block]

A parsed document: title plus blocks in order.

fn render(source: Text) -> Result[Document, Text]

Parses .ptw source text into a Document (formats/ptw-web.md).

fn form_value(submitted: List[Text], name: Text) -> Option[Text]

Reads a form field from program arguments (v3, Sprint 41): the viewer submits each input as one `name=value` argument with spaces encoded as '+'. Missing fields are None; empty submissions are Some("").

fn to_html_bytes(doc: Document, assets: Map[Text, images.Image]) -> Bytes

The single export bridge: a standalone HTML page as bytes. `assets` maps image-block sources to rendered images — supplied ones embed as BMP data URIs, so the page stays self-contained; missing ones (and film/sound blocks) render as addressed links (v2, Sprint 34).