tgpu

const tgpu: object

Type declaration

~unstable

~unstable: object

~unstable.accessor()

accessor: <T>(schema, defaultValue?) => TgpuAccessor<T>

Type Parameters

• T extends AnyWgslData

Parameters

schema

T

defaultValue?

TgpuFn<() => T> | TgpuBufferUsage<T, BindableBufferUsage> | TgpuBufferShorthand<T> | Infer<T>

Returns

TgpuAccessor<T>

~unstable.comptime()

comptime: <T>(func) => TgpuComptime<T>

Creates a version of func that can called safely in a TypeGPU function to precompute and inject a value into the final shader code.

Note how the function passed into comptime doesn’t have to be marked with ‘use gpu’. That’s because the function doesn’t execute on the GPU, it gets executed before the shader code gets sent to the GPU.

Type Parameters

• T extends (…args) => unknown

Parameters

func

T

Returns

TgpuComptime<T>

Example

const injectRand01 = tgpu['~unstable']
  .comptime(() => Math.random());

const getColor = (diffuse: d.v3f) => {
  'use gpu';
  const albedo = hsvToRgb(injectRand01(), 1, 0.5);
  return albedo.mul(diffuse);
};

~unstable.computeFn()

computeFn: (options) => TgpuComputeFnShell<object><ComputeIn>(options) => TgpuComputeFnShell<ComputeIn>

Parameters

options

options.workgroupSize

number[]

Returns

TgpuComputeFnShell<object>

Type Parameters

• ComputeIn extends IORecord<AnyComputeBuiltin>

Parameters

options

options.in

ComputeIn

options.workgroupSize

number[]

Returns

TgpuComputeFnShell<ComputeIn>

~unstable.const()

const: <TDataType>(dataType, value) => TgpuConst<TDataType> = constant

Creates a module constant with specified value.

Type Parameters

• TDataType extends AnyWgslData

Parameters

dataType

TDataType

value

InferGPU<TDataType>

Returns

TgpuConst<TDataType>

~unstable.declare()

declare: (declaration) => TgpuDeclare

Allows defining extra declarations that shall be included in the final WGSL code, when resolving objects that use them.

Using this API is generally discouraged, as it shouldn’t be necessary in any common scenario. It was developed to ensure full compatibility of TypeGPU programs with current and future versions of WGSL.

Parameters

declaration

string

Returns

TgpuDeclare

~unstable.derived()

derived: <T>(compute) => TgpuDerived<T>

Type Parameters

• T

Parameters

compute

() => T

Returns

TgpuDerived<T>

~unstable.fn()

fn: <Args>(argTypes, returnType?) => TgpuFnShell<Args, Void><Args, Return>(argTypes, returnType) => TgpuFnShell<Args, Return>

Type Parameters

• Args extends [] | AnyData[]

Parameters

argTypes

Args

returnType?

undefined

Returns

TgpuFnShell<Args, Void>

Type Parameters

• Args extends [] | AnyData[]

• Return extends AnyData

Parameters

argTypes

Args

returnType

Return

Returns

TgpuFnShell<Args, Return>

~unstable.fragmentFn()

fragmentFn: <FragmentOut>(options) => TgpuFragmentFnShell<object, FragmentOut><FragmentIn, FragmentOut>(options) => TgpuFragmentFnShell<FragmentIn, FragmentOut>

Type Parameters

• FragmentOut extends FragmentOutConstrained

Parameters

options

options.out

FragmentOut

Returns

TgpuFragmentFnShell<object, FragmentOut>

Type Parameters

• FragmentIn extends FragmentInConstrained

• FragmentOut extends FragmentOutConstrained

Parameters

options

options.in

FragmentIn

options.out

FragmentOut

Returns

TgpuFragmentFnShell<FragmentIn, FragmentOut>

~unstable.namespace()

namespace: (options?) => Namespace

Parameters

options?

NamespaceOptions

Returns

Namespace

~unstable.privateVar()

privateVar: <TDataType>(dataType, initialValue?) => TgpuVar<"private", TDataType>

Defines a variable scoped to each entry function (private).

Type Parameters

• TDataType extends AnyData

Parameters

dataType

TDataType

The schema of the held data’s type

initialValue?

InferGPU<TDataType>

If not provided, the variable will be initialized to the dataType’s “zero-value”.

Returns

TgpuVar<"private", TDataType>

~unstable.rawCodeSnippet()

rawCodeSnippet: <TDataType>(expression, type, origin?) => TgpuRawCodeSnippet<TDataType>

An advanced API that creates a typed shader expression which can be injected into the final shader bundle upon use.

Type Parameters

• TDataType extends AnyData

Parameters

expression

string

The code snippet that will be injected in place of foo.$

type

TDataType

The type of the expression

origin?

RawCodeSnippetOrigin = 'runtime'

Where the value originates from.

— Which origin to choose?

Usually ‘runtime’ (the default) is a safe bet, but if you’re sure that the expression or computation is constant (either a reference to a constant, a numeric literal, or an operation on constants), then pass ‘constant’ as it might lead to better optimizations.

If what the expression is a direct reference to an existing value (e.g. a uniform, a storage binding, …), then choose from ‘uniform’, ‘mutable’, ‘readonly’, ‘workgroup’, ‘private’ or ‘handle’ depending on the address space of the referred value.

Returns

TgpuRawCodeSnippet<TDataType>

Example

// An identifier that we know will be in the
// final shader bundle, but we cannot
// refer to it in any other way.
const existingGlobal = tgpu['~unstable']
  .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');

const foo = () => {
  'use gpu';
  return existingGlobal.$ * 2;
};

const wgsl = tgpu.resolve([foo]);
// fn foo() -> f32 {
//   return EXISTING_GLOBAL * 2;
// }

~unstable.simulate()

simulate: <T>(callback) => SimulationResult<T>

Runs the provided callback in a simulated environment, giving it access to buffers and variables as if it were running on the GPU.

The result of the simulation is returned, and does not affect the actual GPU state, nor does it carry over to other simulations.

Type Parameters

• T

Parameters

callback

() => T

The callback to run in the simulated environment.

Returns

SimulationResult<T>

An object containing the result of the simulation, and the final state of the environment.

Example

const counter = tgpu.privateVar(d.u32);

const result = tgpu.simulate(() => {
 counter.$ += 1;
 counter.$ += 2;
 return counter.$;
});

console.log(result.value); // 3

~unstable.slot()

slot: <T>(defaultValue?) => TgpuSlot<T>

Type Parameters

• T

Parameters

defaultValue?

T

Returns

TgpuSlot<T>

~unstable.vertexFn()

vertexFn: <VertexOut>(options) => TgpuVertexFnShell<object, VertexOut><VertexIn, VertexOut>(options) => TgpuVertexFnShell<VertexIn, VertexOut>

Type Parameters

• VertexOut extends VertexOutConstrained

Parameters

options

options.out

VertexOut

Returns

TgpuVertexFnShell<object, VertexOut>

Type Parameters

• VertexIn extends VertexInConstrained

• VertexOut extends VertexOutConstrained

Parameters

options

options.in

VertexIn

options.out

VertexOut

Returns

TgpuVertexFnShell<VertexIn, VertexOut>

~unstable.vertexLayout()

vertexLayout: <TData>(schemaForCount, stepMode) => TgpuVertexLayout<TData>

Type Parameters

• TData extends WgslArray<BaseData> | Disarray<BaseData>

Parameters

schemaForCount

(count) => TData

stepMode

"vertex" | "instance"

Returns

TgpuVertexLayout<TData>

~unstable.workgroupVar()

workgroupVar: <TDataType>(dataType) => TgpuVar<"workgroup", TDataType>

Defines a variable scoped to the whole workgroup, shared between entry functions of the same invocation.

Type Parameters

• TDataType extends AnyData

Parameters

dataType

TDataType

The schema of the held data’s type

Returns

TgpuVar<"workgroup", TDataType>

bindGroupLayout()

bindGroupLayout: <Entries>(entries) => TgpuBindGroupLayout<{ [K in string | number | symbol]: Entries[K] }><Entries>(entries) => TgpuBindGroupLayout<{ [K in string | number | symbol]: MapLegacyTextureToUpToDate<Entries>[K] }>

Type Parameters

• Entries extends Record<string, null | TgpuLayoutEntry>

Parameters

entries

Entries

Returns

TgpuBindGroupLayout<{ [K in string | number | symbol]: Entries[K] }>

Type Parameters

• Entries extends Record<string, null | TgpuLegacyLayoutEntry>

Parameters

entries

Entries

Returns

TgpuBindGroupLayout<{ [K in string | number | symbol]: MapLegacyTextureToUpToDate<Entries>[K] }>

const()

const: <TDataType>(dataType, value) => TgpuConst<TDataType> = constant

Creates a module constant with specified value.

Type Parameters

• TDataType extends AnyWgslData

Parameters

dataType

TDataType

value

InferGPU<TDataType>

Returns

TgpuConst<TDataType>

fn()

fn: <Args>(argTypes, returnType?) => TgpuFnShell<Args, Void><Args, Return>(argTypes, returnType) => TgpuFnShell<Args, Return>

Type Parameters

• Args extends [] | AnyData[]

Parameters

argTypes

Args

returnType?

undefined

Returns

TgpuFnShell<Args, Void>

Type Parameters

• Args extends [] | AnyData[]

• Return extends AnyData

Parameters

argTypes

Args

returnType

Return

Returns

TgpuFnShell<Args, Return>

init()

init: (options?) => Promise<TgpuRoot>

Requests a new GPU device and creates a root around it. If a specific device should be used instead, use

Parameters

options?

InitOptions

Returns

Promise<TgpuRoot>

See

initFromDevice.

Examples

When given no options, the function will ask the browser for a suitable GPU device.

const root = await tgpu.init();

If there are specific options that should be used when requesting a device, you can pass those in.

const adapterOptions: GPURequestAdapterOptions = ...;
const deviceDescriptor: GPUDeviceDescriptor = ...;
const root = await tgpu.init({ adapter: adapterOptions, device: deviceDescriptor });

initFromDevice()

initFromDevice: (options) => TgpuRoot

Creates a root from the given device, instead of requesting it like

Parameters

options

InitFromDeviceOptions

Returns

TgpuRoot

See

init.

Example

const device: GPUDevice = ...;
const root = tgpu.initFromDevice({ device });

privateVar()

privateVar: <TDataType>(dataType, initialValue?) => TgpuVar<"private", TDataType>

Defines a variable scoped to each entry function (private).

Type Parameters

• TDataType extends AnyData

Parameters

dataType

TDataType

The schema of the held data’s type

initialValue?

InferGPU<TDataType>

If not provided, the variable will be initialized to the dataType’s “zero-value”.

Returns

TgpuVar<"private", TDataType>

resolve()

resolve: (options) => string(items, options?) => string

A shorthand for calling tgpu.resolveWithContext(...).code.

Parameters

options

TgpuExtendedResolveOptions

Returns

string

Examples

const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });

const resolved = tgpu.resolve([Gradient]);

console.log(resolved);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }

const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });

const code = tgpu.resolve({
  template: `
    fn getGradientAngle(gradient: Gradient) -> f32 {
      return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
    }
  `,
  externals: {
    Gradient,
  },
});

console.log(code);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }
// fn getGradientAngle(gradient: Gradient_0) -> f32 {
//   return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
// }

A shorthand for calling tgpu.resolveWithContext(...).code.

Parameters

items

ResolvableObject[]

options?

TgpuResolveOptions

Returns

string

Examples

const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });

const resolved = tgpu.resolve([Gradient]);

console.log(resolved);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }

const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });

const code = tgpu.resolve({
  template: `
    fn getGradientAngle(gradient: Gradient) -> f32 {
      return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
    }
  `,
  externals: {
    Gradient,
  },
});

console.log(code);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }
// fn getGradientAngle(gradient: Gradient_0) -> f32 {
//   return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
// }

resolveWithContext()

resolveWithContext: (options) => ResolutionResult(items, options?) => ResolutionResult

Resolves a template with external values. Each external that is used will get resolved to a code string and replaced in the template. Any dependencies of the externals will also be resolved and included in the output.

Parameters

options

TgpuExtendedResolveOptions

The options for the resolution.

Returns

ResolutionResult

Example

const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });

const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
  template: `
    fn getGradientAngle(gradient: Gradient) -> f32 {
      return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
    }
  `,
  externals: {
    Gradient,
  },
});

console.log(code);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }
// fn getGradientAngle(gradient: Gradient_0) -> f32 {
//   return atan(gradient.to.y - gradient.from.y, gradient.to.x - gradient.from.x);
// }

Resolves given TypeGPU resources. Any dependencies of the externals will also be resolved and included in the output.

Parameters

items

ResolvableObject[]

An array of items to resolve.

options?

TgpuResolveOptions

The options for the resolution.

Returns

ResolutionResult

Example

const Gradient = d.struct({
  from: d.vec3f,
  to: d.vec3f,
});

const { code, usedBindGroupLayouts, catchall } =
  tgpu.resolveWithContext([Gradient]);

console.log(code);
// struct Gradient_0 {
//   from: vec3f,
//   to: vec3f,
// }

slot()

slot: <T>(defaultValue?) => TgpuSlot<T>

Type Parameters

• T

Parameters

defaultValue?

T

Returns

TgpuSlot<T>

vertexLayout()

vertexLayout: <TData>(schemaForCount, stepMode) => TgpuVertexLayout<TData>

Type Parameters

• TData extends WgslArray<BaseData> | Disarray<BaseData>

Parameters

schemaForCount

(count) => TData

stepMode

"vertex" | "instance"

Returns

TgpuVertexLayout<TData>

workgroupVar()

workgroupVar: <TDataType>(dataType) => TgpuVar<"workgroup", TDataType>

Defines a variable scoped to the whole workgroup, shared between entry functions of the same invocation.

Type Parameters

• TDataType extends AnyData

Parameters

dataType

TDataType

The schema of the held data’s type

Returns

TgpuVar<"workgroup", TDataType>

Defined in

packages/typegpu/src/index.ts:25