diff --git a/apps/typegpu-docs/src/content/docs/advanced/naming-convention.mdx b/apps/typegpu-docs/src/content/docs/advanced/naming-convention.mdx index 8544c4cc2e..c965bf22bf 100644 --- a/apps/typegpu-docs/src/content/docs/advanced/naming-convention.mdx +++ b/apps/typegpu-docs/src/content/docs/advanced/naming-convention.mdx @@ -41,25 +41,14 @@ const boidsBuffer = root .$usage('uniform'); ``` -## Buffer usages +## Buffer bindings -We give buffer usages *camelCase* names with a suffix that corresponds to their usage. +We give buffer bindings *camelCase* names with a suffix that corresponds to their usage. ```ts -const boidsUniform = boidsBuffer.as('uniform'); -const boidsMutable = boidsBuffer.as('mutable'); -const boidsReadonly = boidsBuffer.as('readonly'); -``` - -## Buffer shorthands - -We give buffer shorthands *camelCase* names with no special suffix, since they represent both -the buffer, and the single permitted usage. - -```ts -const cells1 = root.createUniform(Cells); -const cells2 = root.createMutable(Cells); -const cells3 = root.createReadonly(Cells); +const cellsUniform = root.createUniform(Cells); +const cellsMutable = root.createMutable(Cells); +const cellsReadonly = root.createReadonly(Cells); ``` ## Slots diff --git a/apps/typegpu-docs/src/content/docs/apis/functions/index.mdx b/apps/typegpu-docs/src/content/docs/apis/functions/index.mdx index 36021eb3b0..dbcfd45313 100644 --- a/apps/typegpu-docs/src/content/docs/apis/functions/index.mdx +++ b/apps/typegpu-docs/src/content/docs/apis/functions/index.mdx @@ -399,7 +399,7 @@ const neighborhood = tgpu.fn([d.f32, d.f32], d.vec2f)/* wgsl */`(a, r) { ### Including external resources Shelled WGSL functions can use external resources passed via the `$uses` method. -*Externals* can include anything that can be resolved to WGSL by TypeGPU (numbers, vectors, matrices, constants, TypeGPU functions, buffer usages, textures, samplers, slots, accessors etc.). +*Externals* can include anything that can be resolved to WGSL by TypeGPU (numbers, vectors, matrices, constants, TypeGPU functions, buffer bindings, textures, samplers, slots, accessors etc.). ```ts twoslash import { tgpu, d } from 'typegpu'; diff --git a/apps/typegpu-docs/src/content/docs/apis/resolve.mdx b/apps/typegpu-docs/src/content/docs/apis/resolve.mdx index f0ad4eccdb..f05ef5265e 100644 --- a/apps/typegpu-docs/src/content/docs/apis/resolve.mdx +++ b/apps/typegpu-docs/src/content/docs/apis/resolve.mdx @@ -257,14 +257,14 @@ For example, a resource created in a function return statement will not be auto- Sometimes, it may not be clear which bind group layouts were used in a given resolution. This may occur especially when using: -- Buffer usages/shorthands, which use a hidden, automatically created "catchall" bind group, +- Buffer bindings, which use a hidden, automatically created "catchall" bind group, - TypeGPU functions implemented in JavaScript/TypeScript, which generate their externals automatically. For these cases, you can use `tgpu.resolveWithContext`, which has the same input API as `tgpu.resolve`, but in addition to the resolved code, it also returns information about the layouts used. `tgpu.resolveWithContext` returns an object with 3 props: - `code` - the resolved code, - `usedBindGroupLayouts` - a list of used `tgpu.bindGroupLayout`, -- `catchall` - a two-element array containing the bind group constructed for buffer usages and buffer shorthands, preceded by its index. +- `catchall` - a two-element array containing the bind group constructed for buffer bindings, preceded by its index. An example, where the "catchall" bind group is created: diff --git a/apps/typegpu-docs/src/content/docs/fundamentals/compute-shaders.mdx b/apps/typegpu-docs/src/content/docs/fundamentals/compute-shaders.mdx index a4a38d4309..cf9cd66d50 100644 --- a/apps/typegpu-docs/src/content/docs/fundamentals/compute-shaders.mdx +++ b/apps/typegpu-docs/src/content/docs/fundamentals/compute-shaders.mdx @@ -159,7 +159,7 @@ const bindGroupLayout = tgpu.bindGroupLayout({ Each key in the bind group layout maps to a single resource. For the buffer resources we have explored so far, the equivalent layout entries look like this: -| Fixed Resources shorthand | Laid Out Resources entry | +| Buffer binding | Layout entry | | --- | --- | | `root.createUniform(d.u32)` | `{ uniform: d.u32 }` | | `root.createReadonly(d.u32)` | `{ storage: d.u32 }` | diff --git a/packages/typegpu/src/core/buffer/buffer.ts b/packages/typegpu/src/core/buffer/buffer.ts index 71ae1768d5..cab7ab00af 100644 --- a/packages/typegpu/src/core/buffer/buffer.ts +++ b/packages/typegpu/src/core/buffer/buffer.ts @@ -31,7 +31,7 @@ import { type TgpuMutable, type TgpuReadonly, type TgpuUniform, -} from './bufferShorthand.ts'; +} from './bufferBinding.ts'; // ---------- // Public API @@ -81,7 +81,7 @@ type ViewUsages> = | (boolean extends TBuffer['usableAsUniform'] ? never : 'uniform') | (boolean extends TBuffer['usableAsStorage'] ? never : 'readonly' | 'mutable'); -type UsageTypeToBufferShorthand = { +type UsageTypeToBufferBinding = { uniform: TgpuUniform; mutable: TgpuMutable; readonly: TgpuReadonly; @@ -140,7 +140,7 @@ export interface TgpuBuffer extends TgpuNamable { ): this & UnionToIntersection>; $addFlags(flags: GPUBufferUsageFlags): this; - as>(usage: T): UsageTypeToBufferShorthand[T]; + as>(usage: T): UsageTypeToBufferBinding[T]; compileWriter(): void; write(data: InferInput, options?: BufferWriteOptions): void; @@ -432,8 +432,8 @@ class TgpuBufferImpl implements TgpuBuffer { return res; } - as>(usage: T): UsageTypeToBufferShorthand[T] { - return usageToUsageConstructor[usage](this as never) as UsageTypeToBufferShorthand[T]; + as>(usage: T): UsageTypeToBufferBinding[T] { + return usageToUsageConstructor[usage](this as never) as UsageTypeToBufferBinding[T]; } destroy() { diff --git a/packages/typegpu/src/core/buffer/bufferShorthand.ts b/packages/typegpu/src/core/buffer/bufferBinding.ts similarity index 87% rename from packages/typegpu/src/core/buffer/bufferShorthand.ts rename to packages/typegpu/src/core/buffer/bufferBinding.ts index 02340369b3..2174b30bcf 100644 --- a/packages/typegpu/src/core/buffer/bufferShorthand.ts +++ b/packages/typegpu/src/core/buffer/bufferBinding.ts @@ -24,7 +24,7 @@ import { isUsableAsStorage, isUsableAsUniform } from '../../types.ts'; // Public API // ---------- -interface TgpuBufferShorthandBase extends TgpuNamable { +interface TgpuBufferBindingBase extends TgpuNamable { readonly [$internal]: true; // Accessible on the CPU @@ -43,7 +43,7 @@ interface TgpuBufferShorthandBase extends TgpuNamable { readonly [$repr]: Infer; } -export interface TgpuMutable extends TgpuBufferShorthandBase { +export interface TgpuMutable extends TgpuBufferBindingBase { readonly resourceType: 'mutable'; readonly buffer: TgpuBuffer & StorageFlag; @@ -55,7 +55,7 @@ export interface TgpuMutable extends TgpuBufferShort readonly [$repr]: Infer; } -export interface TgpuReadonly extends TgpuBufferShorthandBase { +export interface TgpuReadonly extends TgpuBufferBindingBase { readonly resourceType: 'readonly'; readonly buffer: TgpuBuffer & StorageFlag; @@ -67,7 +67,7 @@ export interface TgpuReadonly extends TgpuBufferShor readonly [$repr]: Infer; } -export interface TgpuUniform extends TgpuBufferShorthandBase { +export interface TgpuUniform extends TgpuBufferBindingBase { readonly resourceType: 'uniform'; readonly buffer: TgpuBuffer & UniformFlag; @@ -76,22 +76,26 @@ export interface TgpuUniform extends TgpuBufferShort // --- } -export type TgpuBufferShorthand = +export type TgpuBufferBinding = | TgpuMutable | TgpuReadonly | TgpuUniform; -export function isBufferShorthand( +export function isBufferBinding( value: unknown, -): value is TgpuBufferShorthand { - return value instanceof TgpuBufferShorthandImpl; +): value is TgpuBufferBinding { + return value instanceof TgpuBufferBindingImpl; } +// TODO(#2666) - remove this +/** @deprecated Use 'isBufferBinding' instead. */ +export const isBufferShorthand = isBufferBinding; + // -------------- // Implementation // -------------- -export class TgpuBufferShorthandImpl< +export class TgpuBufferBindingImpl< TType extends 'mutable' | 'readonly' | 'uniform', TData extends BaseData, > implements SelfResolvable { @@ -178,7 +182,7 @@ export class TgpuBufferShorthandImpl< return mode.buffers.get(this.buffer) as InferGPU; } - return assertExhaustive(mode, 'bufferShorthand.ts#TgpuBufferShorthandImpl/$'); + return assertExhaustive(mode, 'bufferBinding.ts#TgpuBufferBindingImpl/$'); } set $(value: InferGPU) { @@ -198,7 +202,7 @@ export class TgpuBufferShorthandImpl< if (mode.type === 'codegen') { // The WGSL generator handles buffer assignment, and does not defer to // whatever's being assigned to generate the WGSL. - throw new Error('Unreachable bufferShorthand.ts#TgpuBufferShorthandImpl/$'); + throw new Error('Unreachable bufferBinding.ts#TgpuBufferBindingImpl/$'); } if (mode.type === 'simulate') { @@ -206,7 +210,7 @@ export class TgpuBufferShorthandImpl< return; } - assertExhaustive(mode, 'bufferShorthand.ts#TgpuBufferShorthandImpl/$'); + assertExhaustive(mode, 'bufferBinding.ts#TgpuBufferBindingImpl/$'); } get value(): InferGPU { @@ -218,7 +222,7 @@ export class TgpuBufferShorthandImpl< } toString(): string { - return `${this.resourceType}BufferShorthand:${getName(this) ?? ''}`; + return `${this.resourceType}BufferBinding:${getName(this) ?? ''}`; } [$resolve](ctx: ResolutionCtx): ResolvedSnippet { @@ -248,7 +252,7 @@ export class TgpuBufferShorthandImpl< const mutableUsageMap = new WeakMap< TgpuBuffer, - TgpuBufferShorthandImpl<'mutable', BaseData> + TgpuBufferBindingImpl<'mutable', BaseData> >(); export function mutable( @@ -262,7 +266,7 @@ export function mutable( let usage = mutableUsageMap.get(buffer); if (!usage) { - usage = new TgpuBufferShorthandImpl('mutable', buffer); + usage = new TgpuBufferBindingImpl('mutable', buffer); mutableUsageMap.set(buffer, usage); } return usage as unknown as TgpuMutable; @@ -270,7 +274,7 @@ export function mutable( const readonlyUsageMap = new WeakMap< TgpuBuffer, - TgpuBufferShorthandImpl<'readonly', BaseData> + TgpuBufferBindingImpl<'readonly', BaseData> >(); export function readonly( @@ -284,7 +288,7 @@ export function readonly( let usage = readonlyUsageMap.get(buffer); if (!usage) { - usage = new TgpuBufferShorthandImpl('readonly', buffer); + usage = new TgpuBufferBindingImpl('readonly', buffer); readonlyUsageMap.set(buffer, usage); } return usage as unknown as TgpuReadonly; @@ -292,7 +296,7 @@ export function readonly( const uniformUsageMap = new WeakMap< TgpuBuffer, - TgpuBufferShorthandImpl<'uniform', BaseData> + TgpuBufferBindingImpl<'uniform', BaseData> >(); export function uniform( @@ -306,7 +310,7 @@ export function uniform( let usage = uniformUsageMap.get(buffer); if (!usage) { - usage = new TgpuBufferShorthandImpl('uniform', buffer); + usage = new TgpuBufferBindingImpl('uniform', buffer); uniformUsageMap.set(buffer, usage); } return usage as unknown as TgpuUniform; diff --git a/packages/typegpu/src/core/buffer/bufferUsage.ts b/packages/typegpu/src/core/buffer/bufferUsage.ts index 1c3616afa4..9422acacb9 100644 --- a/packages/typegpu/src/core/buffer/bufferUsage.ts +++ b/packages/typegpu/src/core/buffer/bufferUsage.ts @@ -1,5 +1,5 @@ import { type BaseData } from '../../data/wgslTypes.ts'; -import type { TgpuMutable, TgpuReadonly, TgpuUniform } from './bufferShorthand.ts'; +import type { TgpuMutable, TgpuReadonly, TgpuUniform } from './bufferBinding.ts'; // TODO(#2666) - remove this file diff --git a/packages/typegpu/src/core/root/init.ts b/packages/typegpu/src/core/root/init.ts index f7b918d6d0..e59e871422 100644 --- a/packages/typegpu/src/core/root/init.ts +++ b/packages/typegpu/src/core/root/init.ts @@ -18,11 +18,11 @@ import type { ShaderGenerator } from '../../tgsl/shaderGenerator.ts'; import { INTERNAL_createBuffer, type TgpuBuffer, type VertexFlag } from '../buffer/buffer.ts'; import { isBuffer } from '../../types.ts'; import { - TgpuBufferShorthandImpl, + TgpuBufferBindingImpl, type TgpuMutable, type TgpuReadonly, type TgpuUniform, -} from '../buffer/bufferShorthand.ts'; +} from '../buffer/bufferBinding.ts'; import { computeFn } from '../function/tgpuComputeFn.ts'; import { fn } from '../function/tgpuFn.ts'; import { @@ -345,7 +345,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine .$usage('uniform' as any); - return new TgpuBufferShorthandImpl('uniform', buffer); + return new TgpuBufferBindingImpl('uniform', buffer); } createMutable( @@ -356,7 +356,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine .$usage('storage' as any); - return new TgpuBufferShorthandImpl('mutable', buffer); + return new TgpuBufferBindingImpl('mutable', buffer); } createReadonly( @@ -367,7 +367,7 @@ class TgpuRootImpl extends WithBindingImpl implements TgpuRoot, ExperimentalTgpu // oxlint-disable-next-line typescript/no-explicit-any -- i'm sure it's fine .$usage('storage' as any); - return new TgpuBufferShorthandImpl('readonly', buffer); + return new TgpuBufferBindingImpl('readonly', buffer); } createQuerySet( diff --git a/packages/typegpu/src/core/root/rootTypes.ts b/packages/typegpu/src/core/root/rootTypes.ts index fcab4a1a35..e06c2da95b 100644 --- a/packages/typegpu/src/core/root/rootTypes.ts +++ b/packages/typegpu/src/core/root/rootTypes.ts @@ -25,7 +25,7 @@ import type { LogGeneratorOptions } from '../../tgsl/consoleLog/types.ts'; import type { ShaderGenerator } from '../../tgsl/shaderGenerator.ts'; import type { Unwrapper } from '../../unwrapper.ts'; import type { TgpuBuffer, VertexFlag } from '../buffer/buffer.ts'; -import type { TgpuMutable, TgpuReadonly, TgpuUniform } from '../buffer/bufferShorthand.ts'; +import type { TgpuMutable, TgpuReadonly, TgpuUniform } from '../buffer/bufferBinding.ts'; import type { AnyAutoCustoms, AutoFragmentIn, diff --git a/packages/typegpu/src/core/slot/slotTypes.ts b/packages/typegpu/src/core/slot/slotTypes.ts index c42efa0ecf..985e7a60b0 100644 --- a/packages/typegpu/src/core/slot/slotTypes.ts +++ b/packages/typegpu/src/core/slot/slotTypes.ts @@ -4,7 +4,7 @@ import type { TgpuNamable } from '../../shared/meta.ts'; import type { GPUValueOf, Infer, InferGPU } from '../../shared/repr.ts'; import { $gpuValueOf, $internal, $providing } from '../../shared/symbols.ts'; import type { UnwrapRuntimeConstructor } from '../../tgpuBindGroupLayout.ts'; -import type { TgpuBufferShorthand } from '../buffer/bufferShorthand.ts'; +import type { TgpuBufferBinding } from '../buffer/bufferBinding.ts'; import type { TgpuConst } from '../constant/tgpuConstant.ts'; import type { Withable } from '../root/rootTypes.ts'; import type { TgpuTextureView } from '../texture/texture.ts'; @@ -57,7 +57,7 @@ export interface TgpuAccessor extends TgpuNamable type DataAccessorIn = | (() => DataAccessorIn) - | TgpuBufferShorthand + | TgpuBufferBinding | TgpuVar | TgpuConst | Infer; @@ -88,7 +88,7 @@ export interface TgpuMutableAccessor extends Tgpu type MutableDataAccessorIn = | (() => Infer | MutableDataAccessorIn) - | TgpuBufferShorthand + | TgpuBufferBinding | TgpuVar; type MutableTextureAccessorIn = diff --git a/packages/typegpu/src/indexNamedExports.ts b/packages/typegpu/src/indexNamedExports.ts index 33a2839fc2..ab260d04f0 100644 --- a/packages/typegpu/src/indexNamedExports.ts +++ b/packages/typegpu/src/indexNamedExports.ts @@ -22,7 +22,7 @@ export { isUsableAsIndex, isUsableAsStorage, } from './types.ts'; -export { isBufferShorthand } from './core/buffer/bufferShorthand.ts'; +export { isBufferBinding, isBufferShorthand } from './core/buffer/bufferBinding.ts'; export { isTgpuFn } from './core/function/tgpuFn.ts'; export { isTgpuFragmentFn } from './core/function/tgpuFragmentFn.ts'; export { isTgpuVertexFn } from './core/function/tgpuVertexFn.ts'; @@ -74,7 +74,7 @@ export type { TgpuBufferReadonly, TgpuBufferUniform, } from './core/buffer/bufferUsage.ts'; -export type { TgpuMutable, TgpuReadonly, TgpuUniform } from './core/buffer/bufferShorthand.ts'; +export type { TgpuMutable, TgpuReadonly, TgpuUniform } from './core/buffer/bufferBinding.ts'; export type { Eventual, TgpuAccessor, diff --git a/packages/typegpu/src/resolutionCtx.ts b/packages/typegpu/src/resolutionCtx.ts index ce1180cbb4..8686b05e8b 100644 --- a/packages/typegpu/src/resolutionCtx.ts +++ b/packages/typegpu/src/resolutionCtx.ts @@ -1076,7 +1076,7 @@ export class ResolutionCtxImpl implements ResolutionCtx { * * @param code - The resolved code. * @param usedBindGroupLayouts - List of used `tgpu.bindGroupLayout`s. - * @param catchall - Automatically constructed bind group for buffer usages and buffer shorthands, preceded by its index. + * @param catchall - Automatically constructed bind group for buffer usages and buffer bindings, preceded by its index. * @param logResources - Buffers and information about used console.logs needed to decode the raw data. */ export interface ResolutionResult { diff --git a/packages/typegpu/src/tgsl/consoleLog/logGenerator.ts b/packages/typegpu/src/tgsl/consoleLog/logGenerator.ts index 5ef8bf80b5..ebcf984717 100644 --- a/packages/typegpu/src/tgsl/consoleLog/logGenerator.ts +++ b/packages/typegpu/src/tgsl/consoleLog/logGenerator.ts @@ -1,4 +1,4 @@ -import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts'; +import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts'; import { stitch } from '../../core/resolve/stitch.ts'; import type { TgpuRoot } from '../../core/root/rootTypes.ts'; import { shaderStageSlot } from '../../core/slot/internalSlots.ts'; diff --git a/packages/typegpu/src/tgsl/consoleLog/serializers.ts b/packages/typegpu/src/tgsl/consoleLog/serializers.ts index 96193d2191..49a0196ef2 100644 --- a/packages/typegpu/src/tgsl/consoleLog/serializers.ts +++ b/packages/typegpu/src/tgsl/consoleLog/serializers.ts @@ -1,4 +1,4 @@ -import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts'; +import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts'; import { fn, type TgpuFn } from '../../core/function/tgpuFn.ts'; import { slot } from '../../core/slot/slot.ts'; import { privateVar } from '../../core/variable/tgpuVariable.ts'; diff --git a/packages/typegpu/src/tgsl/consoleLog/types.ts b/packages/typegpu/src/tgsl/consoleLog/types.ts index a3b1713b06..7f0114ea18 100644 --- a/packages/typegpu/src/tgsl/consoleLog/types.ts +++ b/packages/typegpu/src/tgsl/consoleLog/types.ts @@ -1,4 +1,4 @@ -import type { TgpuMutable } from '../../core/buffer/bufferShorthand.ts'; +import type { TgpuMutable } from '../../core/buffer/bufferBinding.ts'; import type { Snippet } from '../../data/snippet.ts'; import type { AnyWgslData, Atomic, U32, WgslArray, WgslStruct } from '../../data/wgslTypes.ts'; import type { GenerationCtx } from '../generationHelpers.ts'; diff --git a/packages/typegpu/src/types.ts b/packages/typegpu/src/types.ts index d9ba202653..be6c98c0f8 100644 --- a/packages/typegpu/src/types.ts +++ b/packages/typegpu/src/types.ts @@ -43,7 +43,7 @@ import type { WgslEnableExtension } from './wgslExtensions.ts'; import type { Infer } from './shared/repr.ts'; import type { ShaderGenerator } from './tgsl/shaderGenerator.ts'; import type { StorageFlag } from './extension.ts'; -import type { TgpuBufferShorthand } from './core/buffer/bufferShorthand.ts'; +import type { TgpuBufferBinding } from './core/buffer/bufferBinding.ts'; export type ResolvableObject = | SelfResolvable @@ -61,7 +61,7 @@ export type ResolvableObject = | TgpuExternalTexture | TgpuTexture | TgpuTextureView - | TgpuBufferShorthand + | TgpuBufferBinding | TgpuVar | AnyVecInstance | AnyMatInstance diff --git a/packages/typegpu/tests/bufferShorthands.test.ts b/packages/typegpu/tests/bufferBindings.test.ts similarity index 99% rename from packages/typegpu/tests/bufferShorthands.test.ts rename to packages/typegpu/tests/bufferBindings.test.ts index 685f23c441..f4107f6016 100644 --- a/packages/typegpu/tests/bufferShorthands.test.ts +++ b/packages/typegpu/tests/bufferBindings.test.ts @@ -527,7 +527,7 @@ describe('root.createUniform', () => { `); }); - it('allows creating shorthands only for buffers allowing them', ({ root }) => { + it('allows creating bindings only for buffers allowing them', ({ root }) => { root.createBuffer(d.u32, 2).$usage('uniform').as('uniform'); root.createBuffer(d.u32, 2).$usage('uniform', 'storage').as('uniform'); root.createBuffer(d.u32, 2).$usage('uniform', 'vertex').as('uniform'); diff --git a/packages/typegpu/tests/tgsl/shellless.test.ts b/packages/typegpu/tests/tgsl/shellless.test.ts index 5cf1efed34..0bcd987d20 100644 --- a/packages/typegpu/tests/tgsl/shellless.test.ts +++ b/packages/typegpu/tests/tgsl/shellless.test.ts @@ -374,7 +374,7 @@ describe('shellless', () => { expect(() => tgpu.resolve([main])).toThrowErrorMatchingInlineSnapshot(` [Error: Resolution of the following tree failed: - - - fn:main: Passed illegal value uniformBufferShorthand:myUniform as the #0 argument to fn(...) + - fn:main: Passed illegal value uniformBufferBinding:myUniform as the #0 argument to fn(...) Shellless functions can only accept arguments representing WGSL resources: constructible WGSL types, d.refs, samplers or texture views. Remember, that arguments such as samplers, texture views, accessors, slots etc. should be dereferenced via '.$' first.] `);