typegpu 0.8.1 → 0.9.0

package/index.d.ts

@@ -1,15 +1,68 @@
-import { $ as $internal, S as ShelllessRepository, T as TgpuSlot, R as ResolvedSnippet, a as TgpuDerived, b as TgpuBindGroupLayout, c as TgpuBindGroup, L as LogResources, W as Wgsl, C as Configurable, d as WgslExtension, e as ShaderGenerator, f as TgpuBuffer, A as AnyData, g as TgpuVar, h as LogGeneratorOptions, i as TgpuRoot, j as AnyWgslData, k as TgpuFn, l as TgpuBufferUsage, I as Infer, m as TgpuAccessor, n as TgpuVertexLayout, o as WgslArray, D as Disarray, p as fn, q as bindGroupLayout, v as vertexLayout, r as privateVar, w as workgroupVar, s as constant, t as fragmentFn, u as vertexFn, x as computeFn, y as declare } from './tgpuConstant-BU72w5qs.js';
-export { aw as BindLayoutEntry, aj as Eventual, ax as ExtractBindGroupInputFromLayout, aO as INTERNAL_GlobalExt, a7 as IndexFlag, ay as LayoutEntryToInput, an as RenderFlag, ao as SampledFlag, a3 as Storage, a4 as StorageFlag, am as TextureProps, ad as TgpuBufferMutable, ae as TgpuBufferReadonly, af as TgpuBufferUniform, ar as TgpuComparisonSampler, aL as TgpuComputeFn, aM as TgpuComputeFnShell, a6 as TgpuComputePipeline, ap as TgpuConst, aN as TgpuDeclare, as as TgpuFixedComparisonSampler, at as TgpuFixedSampler, aG as TgpuFnShell, aJ as TgpuFragmentFn, aK as TgpuFragmentFnShell, V as TgpuGuardedComputePipeline, az as TgpuLayoutComparisonSampler, aA as TgpuLayoutEntry, aB as TgpuLayoutExternalTexture, aC as TgpuLayoutSampler, aD as TgpuLayoutStorage, aE as TgpuLayoutTexture, aF as TgpuLayoutUniform, ag as TgpuMutable, av as TgpuQuerySet, ah as TgpuReadonly, a5 as TgpuRenderPipeline, au as TgpuSampler, ak as TgpuTexture, al as TgpuTextureView, ai as TgpuUniform, aH as TgpuVertexFn, aI as TgpuVertexFnShell, a8 as Uniform, a9 as UniformFlag, aa as ValidUsagesFor, X as ValidateBufferSchema, Y as ValidateStorageSchema, Z as ValidateUniformSchema, aq as VariableScope, ab as Vertex, ac as VertexFlag, _ as WithBinding, a0 as WithCompute, a1 as WithFragment, a2 as WithVertex, z as isBuffer, P as isBufferShorthand, G as isComparisonSampler, E as isDerived, H as isSampler, F as isSlot, J as isTexture, Q as isTgpuFn, K as isUsableAsRender, M as isUsableAsSampled, N as isUsableAsStorage, O as isUsableAsUniform, B as isUsableAsVertex, U as isVariable } from './tgpuConstant-BU72w5qs.js';
+import { A as AnyData, O as Origin, I as InferGPU, $ as $internal, S as ShelllessRepository, T as TgpuSlot, R as ResolvedSnippet, a as TgpuDerived, b as TgpuBindGroupLayout, c as TgpuBindGroup, L as LogResources, C as Configurable, W as WgslExtension, d as ShaderGenerator, e as Wgsl, f as ResolvableObject, g as TgpuBuffer, h as TgpuVar, i as LogGeneratorOptions, j as TgpuRoot, k as AnyWgslData, l as TgpuFn, m as TgpuBufferUsage, n as TgpuBufferShorthand, o as Infer, p as TgpuAccessor, q as TgpuVertexLayout, r as WgslArray, D as Disarray, s as fn, t as bindGroupLayout, v as vertexLayout, u as privateVar, w as workgroupVar, x as constant, y as fragmentFn, z as vertexFn, B as computeFn, E as declare } from './tgpuConstant-BOn7U_lv.js';
+export { aA as BindLayoutEntry, an as Eventual, aB as ExtractBindGroupInputFromLayout, aS as INTERNAL_GlobalExt, ab as IndexFlag, aC as LayoutEntryToInput, ar as RenderFlag, as as SampledFlag, a7 as Storage, a8 as StorageFlag, aq as TextureProps, ah as TgpuBufferMutable, ai as TgpuBufferReadonly, aj as TgpuBufferUniform, av as TgpuComparisonSampler, aP as TgpuComputeFn, aQ as TgpuComputeFnShell, aa as TgpuComputePipeline, at as TgpuConst, aR as TgpuDeclare, aw as TgpuFixedComparisonSampler, ax as TgpuFixedSampler, aK as TgpuFnShell, aN as TgpuFragmentFn, aO as TgpuFragmentFnShell, _ as TgpuGuardedComputePipeline, aD as TgpuLayoutComparisonSampler, aE as TgpuLayoutEntry, aF as TgpuLayoutExternalTexture, aG as TgpuLayoutSampler, aH as TgpuLayoutStorage, aI as TgpuLayoutTexture, aJ as TgpuLayoutUniform, ak as TgpuMutable, az as TgpuQuerySet, al as TgpuReadonly, a9 as TgpuRenderPipeline, ay as TgpuSampler, ao as TgpuTexture, ap as TgpuTextureView, am as TgpuUniform, aL as TgpuVertexFn, aM as TgpuVertexFnShell, ac as Uniform, ad as UniformFlag, ae as ValidUsagesFor, a0 as ValidateBufferSchema, a1 as ValidateStorageSchema, a2 as ValidateUniformSchema, au as VariableScope, af as Vertex, ag as VertexFlag, a3 as WithBinding, a4 as WithCompute, a5 as WithFragment, a6 as WithVertex, F as isBuffer, X as isBufferShorthand, K as isComparisonSampler, H as isDerived, M as isSampler, J as isSlot, N as isTexture, Y as isTgpuFn, P as isUsableAsRender, Q as isUsableAsSampled, U as isUsableAsStorage, V as isUsableAsUniform, G as isUsableAsVertex, Z as isVariable } from './tgpuConstant-BOn7U_lv.js';
+import { c as comptime } from './comptime-DKpw1IVu.js';
+export { T as TgpuComptime } from './comptime-DKpw1IVu.js';
 import 'tinyest';
 
+/**
+ * Extra declaration that will be included in final WGSL code
+ * when resolving objects that use it.
+ */
+interface TgpuRawCodeSnippet<TDataType extends AnyData> {
+    $: InferGPU<TDataType>;
+    value: InferGPU<TDataType>;
+    $uses(dependencyMap: Record<string, unknown>): this;
+}
+type RawCodeSnippetOrigin = Exclude<Origin, 'function' | 'this-function' | 'argument' | 'constant-ref'>;
+/**
+ * An advanced API that creates a typed shader expression which
+ * can be injected into the final shader bundle upon use.
+ *
+ * @param expression The code snippet that will be injected in place of `foo.$`
+ * @param type The type of the expression
+ * @param [origin='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.
+ *
+ * @example
+ * ```ts
+ * // 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;
+ * // }
+ * ```
+ */
+declare function rawCodeSnippet<TDataType extends AnyData>(expression: string, type: TDataType, origin?: RawCodeSnippetOrigin | undefined): TgpuRawCodeSnippet<TDataType>;
+
 interface NameRegistry {
     /**
      * Creates a valid WGSL identifier, each guaranteed to be unique
      * in the lifetime of a single resolution process.
      * Should append "_" to primer, followed by some id.
      * @param primer Used in the generation process, makes the identifier more recognizable.
+     * @param global Whether the name should be registered in the global scope (true), or in the current function scope (false)
      */
-    makeUnique(primer?: string): string;
+    makeUnique(primer: string | undefined, global: boolean): string;
     /**
      * Creates a valid WGSL identifier.
      * Renames identifiers that are WGSL reserved words.
@@ -22,6 +75,8 @@ interface NameRegistry {
      * makeValid("_"); // ERROR (too difficult to make valid to care)
      */
     makeValid(primer: string): string;
+    pushFunctionScope(): void;
+    popFunctionScope(): void;
 }
 
 type SlotToValueMap = Map<TgpuSlot<unknown>, unknown>;
@@ -72,15 +127,6 @@ interface ResolutionResult {
 }
 
 interface TgpuResolveOptions {
-    /**
-     * Map of external names to their resolvable values.
-     */
-    externals: Record<string, Wgsl | object>;
-    /**
-     * The code template to use for the resolution. All external names will be replaced with their resolved values.
-     * @default ''
-     */
-    template?: string | undefined;
     /**
      * The naming strategy used for generating identifiers for resolved externals and their dependencies.
      *
@@ -108,8 +154,19 @@ interface TgpuResolveOptions {
      */
     shaderGenerator?: ShaderGenerator | undefined;
 }
+interface TgpuExtendedResolveOptions extends TgpuResolveOptions {
+    /**
+     * Map of external names to their resolvable values.
+     */
+    externals: Record<string, Wgsl | object>;
+    /**
+     * The code template to use for the resolution. All external names will be replaced with their resolved values.
+     * @default ''
+     */
+    template?: string | undefined;
+}
 /**
- * Resolves a template with external values. Each external will get resolved to a code string and replaced in the template.
+ * 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.
  * @param options - The options for the resolution.
  *
@@ -117,10 +174,7 @@ interface TgpuResolveOptions {
  *
  * @example
  * ```ts
- * const Gradient = d.struct({
- *   from: d.vec3f,
- *   to: d.vec3f,
- * });
+ * const Gradient = d.struct({ from: d.vec3f, to: d.vec3f });
  *
  * const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
  *   template: `
@@ -143,13 +197,14 @@ interface TgpuResolveOptions {
  * // }
  * ```
  */
-declare function resolveWithContext(options: TgpuResolveOptions): ResolutionResult;
+declare function resolveWithContext(options: TgpuExtendedResolveOptions): ResolutionResult;
 /**
- * Resolves a template with external values. Each external will get resolved to a code string and replaced in the template.
+ * Resolves given TypeGPU resources.
  * Any dependencies of the externals will also be resolved and included in the output.
+ * @param items - An array of items to resolve.
  * @param options - The options for the resolution.
  *
- * @returns The resolved code.
+ * @returns {ResolutionResult}
  *
  * @example
  * ```ts
@@ -158,7 +213,38 @@ declare function resolveWithContext(options: TgpuResolveOptions): ResolutionResu
  *   to: d.vec3f,
  * });
  *
- * const resolved = tgpu.resolve({
+ * const { code, usedBindGroupLayouts, catchall } =
+ *   tgpu.resolveWithContext([Gradient]);
+ *
+ * console.log(code);
+ * // struct Gradient_0 {
+ * //   from: vec3f,
+ * //   to: vec3f,
+ * // }
+ * ```
+ */
+declare function resolveWithContext(items: ResolvableObject[], options?: TgpuResolveOptions): ResolutionResult;
+/**
+ * A shorthand for calling `tgpu.resolveWithContext(...).code`.
+ *
+ * @example
+ * ```ts
+ * 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,
+ * // }
+ * ```
+ *
+ * @example
+ * ```ts
+ * 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);
@@ -169,7 +255,7 @@ declare function resolveWithContext(options: TgpuResolveOptions): ResolutionResu
  *   },
  * });
  *
- * console.log(resolved);
+ * console.log(code);
  * // struct Gradient_0 {
  * //   from: vec3f,
  * //   to: vec3f,
@@ -179,7 +265,8 @@ declare function resolveWithContext(options: TgpuResolveOptions): ResolutionResu
  * // }
  * ```
  */
-declare function resolve(options: TgpuResolveOptions): string;
+declare function resolve(options: TgpuExtendedResolveOptions): string;
+declare function resolve(items: ResolvableObject[], options?: TgpuResolveOptions): string;
 
 interface SimulationResult<T> {
     value: T;
@@ -272,7 +359,7 @@ declare function init(options?: InitOptions): Promise<TgpuRoot>;
  */
 declare function initFromDevice(options: InitFromDeviceOptions): TgpuRoot;
 
-declare function accessor<T extends AnyWgslData>(schema: T, defaultValue?: TgpuFn<() => T> | TgpuBufferUsage<T> | Infer<T>): TgpuAccessor<T>;
+declare function accessor<T extends AnyWgslData>(schema: T, defaultValue?: TgpuFn<() => T> | TgpuBufferUsage<T> | TgpuBufferShorthand<T> | Infer<T>): TgpuAccessor<T>;
 
 declare function derived<T>(compute: () => T): TgpuDerived<T>;
 
@@ -338,6 +425,7 @@ declare const tgpu: {
         fragmentFn: typeof fragmentFn;
         vertexFn: typeof vertexFn;
         computeFn: typeof computeFn;
+        comptime: typeof comptime;
         /**
          * @deprecated This feature is now stable, use tgpu.vertexLayout.
          */
@@ -362,8 +450,9 @@ declare const tgpu: {
          */
         const: typeof constant;
         declare: typeof declare;
+        rawCodeSnippet: typeof rawCodeSnippet;
         simulate: typeof simulate;
     };
 };
 
-export { Configurable, type InitFromDeviceOptions, type InitOptions, MissingBindGroupsError, MissingLinksError, MissingSlotValueError, MissingVertexBuffersError, type Namespace, NotUniformError, ResolutionError, TgpuAccessor, TgpuBindGroup, TgpuBindGroupLayout, TgpuBuffer, TgpuDerived, TgpuFn, TgpuRoot, TgpuSlot, TgpuVar, TgpuVertexLayout, tgpu as default, tgpu };
+export { Configurable, type InitFromDeviceOptions, type InitOptions, MissingBindGroupsError, MissingLinksError, MissingSlotValueError, MissingVertexBuffersError, type Namespace, NotUniformError, type RawCodeSnippetOrigin, ResolutionError, TgpuAccessor, TgpuBindGroup, TgpuBindGroupLayout, TgpuBuffer, TgpuDerived, TgpuFn, type TgpuRawCodeSnippet, TgpuRoot, TgpuSlot, TgpuVar, TgpuVertexLayout, tgpu as default, tgpu };