TypeShade language guide

Do not learn TypeShade as a list of syntax forms. Start from TypeScript concepts you already know, then learn what changes when the same idea must execute on a GPU. Each topic moves from syntax to meaning, a small example, and a real shader use.

1. Start with `use typeshade`

"use typeshade" is a language boundary, not just a string literal. Inside the file, TypeScript-like authoring is combined with TypeShade rules for types, resources, stages and builtin inputs.

"use typeshade"

The first directive tells you that this file is not interpreted as an ordinary TypeScript module.

2. TypeScript syntax is the starting point

Variables, functions, type aliases, classes, conditionals and loops provide a familiar authoring surface. A shader does not execute like a JavaScript program, though. A construct has TypeShade meaning only when the compiler can lower its values and operations to GPU code.

TypeScript concept	TypeShade	What changes
function	helper / entry	The body must be GPU-lowerable.
type	GPU value shape	The shape is checked against GPU value semantics.
class	GPU struct	A struct and the functions written with it, with no runtime object.
if / for	GPU control flow	Only flow that compiles to GPU execution, not the whole JavaScript runtime.

3. GPU concepts stay visible in the source

TypeShade makes the GPU interface explicit. Resources use declare, stages use decorated top-level functions, and builtin inputs are declared as @builtin(...) parameters.

declare const camera: uniform<Camera>
declare const pixels: storage<array<f32>, "read_write">

@compute([64, 1, 1])
export function paint(@builtin("global_invocation_id") gid: vec3u) {
  const i = gid.x
  pixels[i] = pixels[i] + camera.pos.x
}

The shader does not create camera or pixels. gid is not injected as a global either; it is declared as an input to the function.

4. Functions describe value flow

As in TypeScript, parameters and return types describe a function contract. TypeShade adds shader-specific meaning through stages and builtin inputs.

function addBias(value: f32): f32 {
  return value + 0.5
}

@compute([64, 1, 1])
export function paint(@builtin("global_invocation_id") gid: vec3u) {
  pixels[gid.x] = addBias(camera.pos.x)
}

addBias is a reusable helper; paint is a compute entry. They share function syntax but have different roles in the pipeline.

5. Resources form the host boundary

uniform<T> and storage<T> are GPU resources supplied by the host, not JavaScript objects created by the shader. declare records that ownership boundary in source.

declare const camera: uniform<Camera>
declare const source: storage<f32>
declare const pixels: storage<f32, "read_write">

A resource is always declared const. Whether the shader may write a storage binding is part of its type, storage<T, "read_write">.

6. Entry functions start a pipeline stage

@vertex, @fragment and @compute declare which shader stage owns an entry function. Builtins are explicit parameters instead of automatically injected globals.

@vertex
export function vs(@builtin("vertex_index") vid: u32): vec4 {
  return positions[vid]
}

@fragment
export function fs(): vec4 {
  return vec4(1, 0, 0, 1)
}

7. Put the pieces together

Read the following example from top to bottom. The language directive, GPU struct, resources, compute stage and builtin parameter form one explicit program contract.

"use typeshade";

class Camera {
  view: mat4;
  pos: vec3;
}

declare const camera: uniform<Camera>;
declare const pixels: storage<array<f32>, "read_write">;

@compute([64, 1, 1])
export function paint(@builtin("global_invocation_id") gid: vec3u) {
  const i = gid.x;
  pixels[i] = pixels[i] + camera.pos.x;
}

8. What TypeScript gives you, and what changes

TypeScript	TypeShade
`declare`	`declare` describes host-provided GPU resources.
function parameter	GPU value or explicit stage builtin input.
class	GPU struct and field metadata.
number	Use explicit GPU numeric types such as `f32`, `i32`, `u32`.

TypeShade is therefore not a copy of TypeScript syntax. It connects the TypeScript authoring experience to a GPU language model.

9. Further reading

When learning a TypeShade concept, read the matching TypeScript type or function documentation, check the JavaScript execution model, and then connect it to the GPU concept.

10. Learning path

Build a first file in Quick start, then expand through Types, Functions, Control flow, GPU types, Resources and Shader stages, in that order. Quick start

Edit this page Report a problem