Shader entry points and create*Pipeline API

[iwoplaza]

Entry functions

Compute entry functions

const computeMain = tgpu
  .computeFn([1])
  .does(() => {
    // ...
  });

Vertex & Fragment entry functions

const vertexMain = tgpu
  .vertexFn([], builtin.position)
  .does(() => {
    // ...
  });

const fragmentMain = tgpu
  .fragmentFn([d.vec4f], vec4f)
  .does(() => {
    // ...
  });

Pipelines

createComputePipeline

const computePipeline = root
  .with(size, 16) // adding constants (giving slots values)
  .withCompute(compute_main) // applying a compute stage
  .createPipeline();

// Executing

computePipeline
  .with(layout0, bindGroup0)
  .dispatchWorkgroups(32);

createRenderPipeline

type TgpuRenderPassColorAttachment = {
  /**
   * A view describing the texture that will be output to for this color attachment.
   */
  view: GPUTextureView;
  /**
   * Indicates the depth slice index of "3d" view that will be output to for this color
   * attachment.
   */
  depthSlice?: number;
  /** 
   * A view describing the texture that will receive the resolved output for this color
   * attachment if `view` is multisampled.
   */
  resolveTarget?: GPUTextureView;

  clearValue?: color;
  loadOp: GPULoadOp;
  storeOp: GPUStoreOp;
};

const renderPipeline = root
  .with(size, 16) // adding constants (giving slots values)
  .withVertex(vertex_main, [attrib.a, attrib.b]) // applying a vertex stage
  .withFragment(fragment_main)  // applying a fragment stage (optional)
  .withPrimitive({ topology: 'triangle-list' }) // (optional)
  .withDepthStepcil(...) // (optional)
  .withMultisample(...) // (optional)
  .createPipeline({ format: presentationFormat });

renderPipeline.draw({
  colorAttachments: {
    
  },
});

Example

import { compute_main, vertex_main, fragment_main, size } from './shader.js';

const root = await tgpu.init();

const computePipeline = root
  .with(size, 16)
  .withCompute(compute_main)
  .createPipeline();

const renderPipeline = root
  .with(size, 16)
  .withVertex(vertex_main, [attrib.a, attrib.b])
  .withFragment(fragment_main)
  .createPipeline({ format: presentationFormat });

// Executing

computePipeline
  .with(layout0, bindGroup0)
  .dispatchWorkgroups(32);

[iwoplaza]

We have since reworked a couple of ideas around typed entry functions, and how builtins should be exposed to entry functions.
The current idea is to explicitly define them alongside other inputs to the shader stage. The APIs diverge between entry points however, because they have different requirements.

• Vertex:
  • in: Attributes
  • in: Builtins
  • The output
• Fragment:
  • in: Vertex output
  • in: Builtins
  • The output
• Compute:
  • in: Workgroup size
  • in: Builtins

Note how the compute shader stage has no output.

For vertex and fragment shader entries, there are two arguments to pass when defining the shell.

const vertexMain = tgpu
  .vertexFn({ idx: builtin.vertexIndex }, { pos: builtin.position, uv: vec2f })

const fragmentMain = tgpu
  .fragmentFn(
    {
      pos: builtin.position /* TODO: Remove once builtins are properly purged from the types */,
      uv: vec2f,
    },
    vec4f,
  );

So for there, the first argument means 'input', and the second one means 'output'. This however does not apply to compute shader entries.

const mainInitWorld = tgpu
  .computeFn([builtin.globalInvocationId], { workgroupSize: [1] })

Since compute functions do not have an output, and they have an additional configuration of 'workgroupSize', the 'in', 'out' scheme no longer applies.

Possible solutions to unify the APIs

Record instead of arg list

const vertexMain = tgpu
  .vertexFn({
    in: { idx: builtin.vertexIndex },
    out: { pos: builtin.position, uv: vec2f },
  })

const fragmentMain = tgpu
  .fragmentFn({
    in: {
      pos: builtin.position /* TODO: Remove once builtins are properly purged from the types */,
      uv: vec2f,
    },
    out: vec4f,
  });

const mainInitWorld = tgpu
  .computeFn({
    in: { gid: builtin.globalInvocationId }, 
    workgroupSize: [1],
  })

undefined output

const mainInitWorld = tgpu
  .computeFn(
    { gid: builtin.globalInvocationId },
    undefined,
    {
      workgroupSize: [1],
    },
  )

[reczkok]

I like the idea with record as argument. It makes the functions more readable at a glance which could be an issue at the moment. More often than not the data type will be a struct so I don't think we have to worry about clutter.

[mhawryluk]

I like the proposal with passing a record instead of positional arguments too. it adds a little visual complexity, but makes it more readable