@link annotations for host directed linking

[mighdoll]

@link is intended to give host application code (e.g. TypeScript or Rust) fine grained control of the WESL linking process at the level of e.g. fn elements. Host applications gain the power to flexibly assemble a shader from parts based on user settings, runtime environment, or other application specific runtime considerations.

By comparison, WESL import statements specify shader module assembly from WESL code, with limited control by the host application, e.g. via @if conditions.

Use.GPU makes extensive use of @link annotations (see below) and has demonstrated a number of examples of the flexibility from pervasive app controlled linking. @link is also potential enabler for a data abstraction layer (issue TBD).

The idea is to declare wgsl elements like functions without implementation, e.g.

@link fn getVertColor(i:u32) -> f32 {} // no implementation

@vertex
fn main(@builtin(instance_index) instanceIndex: u32) {
   getVertColor(instanceIndex);
}

Then several WESL modules might implement functions matching the signature of getVertColor, and use a runtime linker option to assign one of them.
e.g.

import { getVertColor } from "./shader/root.wgsl";
import { randomColor } from "./shader/colorUtil.wgsl";

const linker = new Linker();
linker.link({links: {getVertColor: randomColor}});

See also issue TBD about providing host code handles to WGSL elements to supply to the linker.

In some scenarios, the linker might generate WGSL to fulfill the @link, see for example issue TBD describing how to use @link as a polymorphic data get abstraction.

We should consider how @link might be useful for specific needs expressed by community projects, e.g. perhaps for bevy's materials extension points (issue TBD).

Related work we've discussed in WESL includes @ncthbrt module function signatures as part of her 5 WESL proposals and @k2d222's generics proposal for generic function signatures with @override.

It is tempting to see if we can allow fulfilling @link entries statically as well as dynamically.

Use.GPU also includes a @optional @link variation that provides a default implementation along with the declaration.

Some background on Use.GPU:
. Use.GPU WESL discussion slides
. Use.GPU WGSL language extensions
. Using extended shaders in Use.GPU
. video see: 47:00+
. extended WGSL in use in Use.GPU
. also: general docs, blog

[ncthbrt]

Had a thought that generics kind of fulfill a similar role to link (if we allow specialisation externally to the source code). In which case having both feels redundant

[mighdoll]

Had a thought that generics kind of fulfill a similar role to link (if we allow specialisation externally to the source code). In which case having both feels redundant

I had an experimental feature in the legacy version of the typescript wgsl-linker kind of like that. ext. prefixed generic parameters would be set by the host. So if fn foo took a generic parameter, you could import foo(ext.opName) from ./bar, and the linker would expect opName to be set in TypeScript.

[ncthbrt]

I was thinking more about being able to specialise at link time by passing in a path expression as the entry point but your approach is also an interesting angle, @mighdoll

[mighdoll]

Yeah, the ext. prefix thing seems clunky to me too.

The basic idea of generic parameters being settable from host code seems interesting in that it's another path toward unifying host directed linking with WESL directed linking. i.e. rather than a module saying it expects host code to fill in an @link reference, a module could take a generic fn argument and then allow that argument to specified by host code passing arguments to the linker, or by WESL code e.g. in an import statement.

I'm not sure if overloading generic arguments to do @link too would be too much though.