feat: Support other console functionalities (#1855)

Author: aleksanderkatan

apps/typegpu-docs/src/content/docs/fundamentals/utils.mdx

@@ -191,11 +191,12 @@ When using `console.log`, atomic operations are injected into the WGSL code to s
 This synchronization can introduce overhead and significantly impact shader performance.
 :::
 
+Other supported `console` functionalities include `console.debug`, `console.info`, `console.warn`, `console.error` and `console.clear`.
+
 There are some limitations (some of which we intend to alleviate in the future):
 
 - `console.log` only works when used in TGSL, when calling or resolving a TypeGPU pipeline.
 Otherwise, for example when using `tgpu.resolve` on a WGSL template, logs are ignored.
 - `console.log` only works in fragment and compute shaders.
 This is due to a [WebGPU limitation](https://www.w3.org/TR/WGSL/#address-space) that does not allow modifying buffers during the vertex shader stage.
-- `console.log` currently does not support template literals and string substitutions.
-- Other `console` methods like `clear` or `warn` are not yet supported.
+- `console.log` currently does not support template literals (but you can use [string substitutions](https://developer.mozilla.org/en-US/docs/Web/API/console#using_string_substitutions), or just pass multiple arguments instead).

apps/typegpu-docs/src/examples/tests/log-test/index.ts

@@ -182,6 +182,37 @@ export const controls = {
       test.dispatchThreads();
     },
   },
+  'String interpolation': {
+    onButtonClick: async () =>
+      root['~unstable'].createGuardedComputePipeline(() => {
+        'use gpu';
+        console.log(
+          'The values %d, %f and %s were interpolated in this message.',
+          987,
+          1.26,
+          d.vec4f(1, 2, 3, 4),
+        );
+        console.log(
+          'TypeGPU resources can be used as strings (%s) or objects (%o).',
+          d.vec3f(1, 2, 3),
+          d.vec3f(1, 2, 3),
+          'This sentence is the fourth argument of the log.',
+        );
+      }).dispatchThreads(),
+  },
+  'Different log functionalities': {
+    onButtonClick: async () =>
+      root['~unstable'].createGuardedComputePipeline(() => {
+        'use gpu';
+        console.log('This message should be cleared.');
+        console.clear();
+        console.log('This is a log message.', 'Index:', 1);
+        console.debug('This is a debug message.', 'Index:', 2);
+        console.info('This is an info message.', 'Index:', 3);
+        console.warn('This is a warn message.', 'Index:', 4);
+        console.error('This is an error message.', 'Index:', 5);
+      }).dispatchThreads(),
+  },
   'Render pipeline': {
     onButtonClick: () => {
       const context = canvas.getContext('webgpu') as GPUCanvasContext;

packages/typegpu/src/data/dataTypes.ts

@@ -259,7 +259,7 @@ export class MatrixColumnsAccess {
 
 export class ConsoleLog {
   [$internal] = true;
-  constructor() {
+  constructor(readonly op: string) {
     setName(this, 'consoleLog');
   }
 }

packages/typegpu/src/resolutionCtx.ts

@@ -436,8 +436,8 @@ export class ResolutionCtxImpl implements ResolutionCtx {
     this._itemStateStack.popBlockScope();
   }
 
-  generateLog(args: Snippet[]): Snippet {
-    return this.#logGenerator.generateLog(this, args);
+  generateLog(op: string, args: Snippet[]): Snippet {
+    return this.#logGenerator.generateLog(this, op, args);
   }
 
   get logResources(): LogResources | undefined {

packages/typegpu/src/tgsl/consoleLog/deserializers.ts

@@ -27,7 +27,7 @@ import type { Infer } from '../../shared/repr.ts';
 import { niceStringify } from '../../shared/stringify.ts';
 import { bitcastU32toF32, bitcastU32toI32 } from '../../std/bitcast.ts';
 import { unpack2x16float } from '../../std/packing.ts';
-import type { LogResources } from './types.ts';
+import type { LogMeta, LogResources } from './types.ts';
 
 const toF = (n: number | undefined) => bitcastU32toF32(n ?? 0);
 const toI = (n: number | undefined) => bitcastU32toI32(n ?? 0);
@@ -159,10 +159,9 @@ function deserializeCompound(
 export function deserializeAndStringify(
   serializedData: Uint32Array,
   argTypes: (AnyWgslData | string)[],
-): string {
+): string[] {
   return deserializeCompound(serializedData, argTypes)
-    .map(niceStringify)
-    .join(' ');
+    .map(niceStringify);
 }
 
 /**
@@ -175,22 +174,26 @@ export function deserializeAndStringify(
  * - After processing, the index buffer and the data buffer are cleared.
  */
 export function logDataFromGPU(resources: LogResources) {
-  const { indexBuffer, dataBuffer, logIdToArgTypes, options } = resources;
+  const { indexBuffer, dataBuffer, logIdToMeta, options } = resources;
 
   dataBuffer.read().then((data) => {
     data
       .filter((e) => e.id)
       .forEach(({ id, serializedData }) => {
-        const argTypes = logIdToArgTypes.get(id) as (AnyWgslData | string)[];
-        const result = deserializeAndStringify(
+        const { argTypes, op } = logIdToMeta.get(id) as LogMeta;
+        const results = deserializeAndStringify(
           new Uint32Array(serializedData),
           argTypes,
         );
-        console.log(
-          `${options.messagePrefix}${result}`,
+        if (results.length === 0) {
+          results.push('');
+        }
+        console[op](...[
+          `%c${options.messagePrefix}%c ${results[0]}`,
           'background: #936ff5; color: white;',
-          '',
-        );
+          'color: inherit; background: none',
+          ...results.slice(1),
+        ]);
       });
   });
 

packages/typegpu/src/tgsl/consoleLog/logGenerator.ts

@@ -20,19 +20,24 @@ import {
   type GenerationCtx,
 } from '../generationHelpers.ts';
 import { createLoggingFunction } from './serializers.ts';
-import type {
-  LogGenerator,
-  LogGeneratorOptions,
-  LogResources,
-  SerializedLogCallData,
+import {
+  type LogGenerator,
+  type LogGeneratorOptions,
+  type LogMeta,
+  type LogResources,
+  type SerializedLogCallData,
+  type SupportedLogOps,
+  supportedLogOps,
 } from './types.ts';
 
 const defaultOptions: Required<LogGeneratorOptions> = {
   logCountLimit: 64,
   logSizeLimit: 252,
-  messagePrefix: '%c GPU %c ',
+  messagePrefix: ' GPU ',
 };
 
+const fallbackSnippet = snip('/* console.log() */', Void);
+
 export class LogGeneratorNullImpl implements LogGenerator {
   get logResources(): undefined {
     return undefined;
@@ -41,20 +46,20 @@ export class LogGeneratorNullImpl implements LogGenerator {
     console.warn(
       "'console.log' is currently only supported in compute pipelines.",
     );
-    return snip('/* console.log() */', Void);
+    return fallbackSnippet;
   }
 }
 
 export class LogGeneratorImpl implements LogGenerator {
   #options: Required<LogGeneratorOptions>;
-  #logIdToArgTypes: Map<number, (string | AnyWgslData)[]>;
+  #logIdToMeta: Map<number, LogMeta>;
   #firstUnusedId = 1;
   #indexBuffer: TgpuMutable<Atomic<U32>>;
   #dataBuffer: TgpuMutable<WgslArray<SerializedLogCallData>>;
 
   constructor(root: TgpuRoot) {
     this.#options = { ...defaultOptions, ...root[$internal].logOptions };
-    this.#logIdToArgTypes = new Map();
+    this.#logIdToMeta = new Map();
 
     const SerializedLogData = struct({
       id: u32,
@@ -77,7 +82,16 @@ export class LogGeneratorImpl implements LogGenerator {
    * @param args Argument snippets. Snippets of UnknownType will be treated as string literals.
    * @returns A snippet containing the call to the logging function.
    */
-  generateLog(ctx: GenerationCtx, args: Snippet[]): Snippet {
+  generateLog(
+    ctx: GenerationCtx,
+    op: string,
+    args: Snippet[],
+  ): Snippet {
+    if (!supportedLogOps.includes(op as SupportedLogOps)) {
+      console.warn(`Unsupported log method '${op}' was used in TGSL.`);
+      return fallbackSnippet;
+    }
+
     const concreteArgs = concretizeSnippets(args);
     const id = this.#firstUnusedId++;
 
@@ -92,15 +106,14 @@ export class LogGeneratorImpl implements LogGenerator {
       this.#options,
     );
 
-    this.#logIdToArgTypes.set(
-      id,
-      concreteArgs.map((e) =>
-        e.dataType === UnknownData
-          ? (e.value as string)
-          : e.dataType as AnyWgslData
-      ),
+    const argTypes = concreteArgs.map((e) =>
+      e.dataType === UnknownData
+        ? (e.value as string)
+        : e.dataType as AnyWgslData
     );
 
+    this.#logIdToMeta.set(id, { op: op as SupportedLogOps, argTypes });
+
     return snip(stitch`${ctx.resolve(logFn).value}(${nonStringArgs})`, Void);
   }
 
@@ -109,7 +122,7 @@ export class LogGeneratorImpl implements LogGenerator {
       dataBuffer: this.#dataBuffer,
       indexBuffer: this.#indexBuffer,
       options: this.#options,
-      logIdToArgTypes: this.#logIdToArgTypes,
+      logIdToMeta: this.#logIdToMeta,
     };
   }
 }

packages/typegpu/src/tgsl/consoleLog/types.ts

@@ -27,7 +27,7 @@ export interface LogGeneratorOptions {
   logSizeLimit?: number;
   /**
    * The prefix attached to each log call.
-   * @default "%c GPU %c "
+   * @default ' GPU '
    */
   messagePrefix?: string;
 }
@@ -37,22 +37,42 @@ export type SerializedLogCallData = WgslStruct<{
   serializedData: WgslArray<U32>;
 }>;
 
+export interface LogMeta {
+  op: SupportedLogOps;
+  argTypes: (string | AnyWgslData)[];
+}
+
 /**
  * The resources required for logging within the TGSL console.
  *
  * @property indexBuffer - A buffer used for indexing log entries. Needs to be cleared after each dispatch/draw.
  * @property dataBuffer - A buffer containing an array of serialized log call data.
  * @property options - The configuration options for the LogGenerator.
- * @property logIdToArgTypes - A mapping from log identifiers to their corresponding argument types.
+ * @property logIdToMeta - A mapping from log identifiers to an object containing the corresponding log op and argument types.
  */
 export interface LogResources {
   indexBuffer: TgpuMutable<Atomic<U32>>;
   dataBuffer: TgpuMutable<WgslArray<SerializedLogCallData>>;
   options: Required<LogGeneratorOptions>;
-  logIdToArgTypes: Map<number, (string | AnyWgslData)[]>;
+  logIdToMeta: Map<number, LogMeta>;
 }
 
 export interface LogGenerator {
-  generateLog(ctx: GenerationCtx, args: Snippet[]): Snippet;
+  generateLog(
+    ctx: GenerationCtx,
+    op: string,
+    args: Snippet[],
+  ): Snippet;
   get logResources(): LogResources | undefined;
 }
+
+export const supportedLogOps = [
+  'log',
+  'debug',
+  'info',
+  'warn',
+  'error',
+  'clear',
+] as const;
+
+export type SupportedLogOps = (typeof supportedLogOps)[number];

packages/typegpu/src/tgsl/generationHelpers.ts

@@ -219,7 +219,7 @@ export type GenerationCtx = ResolutionCtx & {
   dedent(): string;
   pushBlockScope(): void;
   popBlockScope(): void;
-  generateLog(args: Snippet[]): Snippet;
+  generateLog(op: string, args: Snippet[]): Snippet;
   getById(id: string): Snippet | null;
   defineVariable(id: string, snippet: Snippet): void;
 

packages/typegpu/src/tgsl/wgslGenerator.ts

@@ -274,7 +274,10 @@ ${this.ctx.pre}}`;
       const target = this.expression(targetNode);
 
       if (target.value === console) {
-        return snip(new ConsoleLog(), UnknownData);
+        return snip(
+          new ConsoleLog(property),
+          UnknownData,
+        );
       }
 
       if (
@@ -508,7 +511,7 @@ ${this.ctx.pre}}`;
         }
 
         if (callee.value instanceof ConsoleLog) {
-          return this.ctx.generateLog(convertedArguments);
+          return this.ctx.generateLog(callee.value.op, convertedArguments);
         }
 
         // Assuming that `callee` is callable