You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can see for yourself what `getGradientColor` resolves to by calling [`tgpu.resolve`](/TypeGPU/fundamentals/resolve), all relevant definitions will be automatically included:
434
434
435
435
```wgsl
436
-
// results of calling tgpu.resolve({ externals: { getGradientColor } })
436
+
// results of calling tgpu.resolve([getGradientColor])
@@ -4,24 +4,170 @@ description: Resolve API can be used to extend shader code with WGSL definitions
4
4
---
5
5
6
6
Defining shader schemas and objects in JS/TS has lots of benefits, but having to keep them in sync with the corresponding WGSL code is hard to maintain.
7
-
The `tgpu.resolve` API takes in a WGSL template, all TypeGPU schemas that you want to use in the shader, and generates a ready-to-use WGSL bundle.
7
+
The `tgpu.resolve` API takes in TypeGPU resources (and optionally a WGSL template) and generates a ready-to-use WGSL bundle containing all transitive dependencies of the passed in objects.
8
8
9
9
:::note
10
10
`tgpu.resolve` is essentially a dedicated TypeGPU linker.
11
11
:::
12
12
13
+
## Resolving resources
14
+
15
+
The first `tgpu.resolve` overload takes in an array of items to resolve, and an optional argument with options. Here's a simple example:
As you may note, the resolved WGSL code contains exactly the set of definitions required for the objects passed in the argument to be valid.
57
+
58
+
You can also resolve other resources, like consts, buffers, textures, entry point functions or even entire pipelines. Here's an example with a pipeline:
the `.draw()` and `.dispatchWorkgroups()` methods perform the resolution and shader compilation under the hood,
102
+
eliminating the need for manual resolve calls.
103
+
:::
104
+
105
+
:::tip
106
+
To resolve all items from a layout, you can use `tgpu.resolve([...Object.values(layout.bound)])`.
107
+
:::
108
+
109
+
110
+
## Resolving with a template
111
+
112
+
The second `tgpu.resolve` overload has only one argument -- an object with options, that requires two extra props: `template` and `externals`.
113
+
The goal of this overload is to extend the existing WGSL code provided as `template`, with additional definitions from `externals`.
114
+
115
+
:::tip
116
+
This variant of `tgpu.resolve` can often be omitted by using [WGSL-implemented functions](/TypeGPU/fundamentals/functions/#implementing-functions-in-wgsl).
117
+
Use it when you are already provided with existing WGSL code and want to extend it.
As you may note, in this case `tgpu.resolve` uses the structure of the `externals` property to detect that `buffers.time`, `buffers.range` and `offset` need to be replaced, and that their definitions should be included.
160
+
161
+
Here is another example. Assume, that the bind group index `0` is already taken by some existing code:
162
+
163
+
```ts twoslash
164
+
importtgpufrom'typegpu';
165
+
import*asdfrom'typegpu/data';
166
+
// ---cut---
167
+
const LightSource =d.struct({
168
+
ambientColor: d.vec3f,
169
+
intensity: d.f32,
170
+
}).$name('Source');
25
171
// ^ giving the struct an explicit name (optional)
If you wish to resolve just a single TGSL function and its dependencies, you can call resolve with that function in the externals and with no template.
You can also resolve TypeGPU schemas or even entire pipelines the same way.
102
-
:::
103
-
104
-
## Template
105
-
106
-
This optional property of the `tgpu.resolve` function argument is a string containing WGSL code, that is meant to be extended with additional definitions.
107
-
It can contain references to objects passed in the `externals` record.
108
-
109
-
## Externals
110
-
111
-
This is a record with TypeGPU objects that are to be included in the final resolved shader code.
112
-
The values in the mapping are the objects themselves, while the keys are the names by which they are referenced in the template code.
113
-
Each object is resolved to its WGSL declaration, which is included in the final shader code.
114
-
Moreover, each reference to the object in the template is replaced with the name used in its newly generated declaration.
115
-
116
-
If an object is being referenced only by another TypeGPU object in *externals*, it doesn't have to be included in the record.
117
-
Any passed-in object's dependencies are automatically resolved and included in the final result.
118
-
119
-
:::note
120
-
To resolve bindings you can access each entry of a [bindGroupLayout](/TypeGPU/fundamentals/bind-groups) via the `layout.bound` property.
121
-
122
-
```ts
123
-
externals: {
124
-
lightSource: layout.bound.lightSource,
125
-
sampling: layout.bound.sampling,
126
-
bgTexture: layout.bound.bgTexture,
127
-
}
128
-
129
-
// As long as the names in the shader match the
130
-
// layout keys, it can be shortened to:
131
-
externals: {
132
-
...layout.bound,
133
-
}
134
-
```
135
-
136
-
:::
137
-
138
233
## Naming scheme
139
234
140
-
When externals are being resolved, they are given new names based on the specified naming scheme (`names` parameter).
235
+
When items are being resolved, they are given new unique names based on their name in code and the specified naming scheme (`names` parameter in options).
141
236
142
237
The default naming scheme is `"random"`.
143
238
It uses labels assigned to the objects via `.$name("foo")` method or, if they aren't present, the keys in the *externals* record.
0 commit comments