docs: Create a shader compilation tool (#1466)

Author: reczkok

apps/typegpu-docs/astro.config.mjs

@@ -9,6 +9,7 @@ import starlightBlog from 'starlight-blog';
 import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc';
 import typegpu from 'unplugin-typegpu/rollup';
 import { imagetools } from 'vite-imagetools';
+import wasm from 'vite-plugin-wasm';
 
 /**
  * @template T
@@ -26,10 +27,16 @@ export default defineConfig({
   vite: {
     // Allowing query params, for invalidation
     plugins: [
+      wasm(),
       tailwindVite(),
       typegpu({ include: [/\.m?[jt]sx?/] }),
       /** @type {any} */ imagetools(),
     ],
+    ssr: {
+      noExternal: [
+        'wgsl-wasm-transpiler-bundler',
+      ],
+    },
   },
   integrations: [
     starlight({

apps/typegpu-docs/package.json

@@ -52,7 +52,8 @@
     "typegpu": "workspace:*",
     "typescript": "catalog:types",
     "unplugin-typegpu": "workspace:*",
-    "wgpu-matrix": "catalog:example"
+    "wgpu-matrix": "catalog:example",
+    "wgsl-wasm-transpiler-bundler": "^0.0.1"
   },
   "devDependencies": {
     "@observablehq/plot": "^0.6.17",
@@ -66,6 +67,7 @@
     "tailwindcss": "^4.1.7",
     "tailwindcss-motion": "^1.0.1",
     "vite-imagetools": "catalog:frontend",
+    "vite-plugin-wasm": "^3.4.1",
     "yaml": "^2.8.0"
   }
 }

apps/typegpu-docs/src/pages/translator/index.astro

@@ -0,0 +1,19 @@
+---
+import { Image } from 'astro:assets';
+import PageLayout from '../../layouts/PageLayout.astro';
+import TranslatorApp from './translator-app';
+import TypeGPULogoDark from '../../assets/typegpu-logo-dark.svg';
+---
+
+<PageLayout title="WGSL Translator | TypeGPU" theme="dark">
+  <h1 class="w-full flex items-center justify-center">
+    <Image
+      src={TypeGPULogoDark}
+      alt="TypeGPU Logo"
+      class="w-40 relative"
+    />
+    <p class="text-lg font-sans">— translator</p>
+  </h1>
+
+  <TranslatorApp client:only="react" />
+</PageLayout>

apps/typegpu-docs/src/pages/translator/lib/constants.ts

@@ -0,0 +1,37 @@
+export const DEFAULT_WGSL = `@vertex
+fn vs_main(@builtin(vertex_index) vertex_index: u32) -> @builtin(position) vec4<f32> {
+  let pos = array<vec2<f32>, 3>(
+    vec2<f32>(-0.5, -0.5),
+    vec2<f32>( 0.5, -0.5),
+    vec2<f32>( 0.0,  0.5)
+  );
+  return vec4<f32>(pos[vertex_index], 0.0, 1.0);
+}
+
+@fragment
+fn fs_main() -> @location(0) vec4<f32> {
+  return vec4<f32>(1.0, 0.0, 0.0, 1.0);
+}`;
+
+export const LANGUAGE_MAP: Record<string, string> = {
+  wgsl: 'wgsl',
+  glsl: 'cpp',
+  hlsl: 'cpp',
+  metal: 'cpp',
+  spirv: 'plaintext',
+  'spirv-asm': 'plaintext',
+};
+
+export const commonEditorOptions = {
+  minimap: { enabled: false },
+  fontSize: 14,
+  fontFamily: 'Monaco, "Cascadia Code", "Roboto Mono", monospace',
+  wordWrap: 'off' as const,
+  scrollBeyondLastLine: false,
+  automaticLayout: true,
+  tabSize: 2,
+  renderWhitespace: 'selection' as const,
+  lineNumbers: 'on' as const,
+  folding: true,
+  bracketPairColorization: { enabled: true },
+} as const;

apps/typegpu-docs/src/pages/translator/lib/useShaderTranslator.ts

@@ -0,0 +1,147 @@
+import { useCallback, useEffect, useReducer } from 'react';
+import { DEFAULT_WGSL } from './constants.ts';
+import { compile, getErrorMessage, initializeWasm } from './wgslTool.ts';
+
+type State = {
+  status: 'initializing' | 'ready' | 'compiling' | 'success' | 'error';
+  errorMessage?: string;
+  formats: string[];
+  wgslCode: string;
+  output: string;
+  format: string;
+  loadingEditor: boolean;
+};
+
+type Action =
+  | { type: 'INIT_SUCCESS'; payload: string[] }
+  | { type: 'INIT_FAILURE'; payload: string }
+  | { type: 'COMPILE_START' }
+  | { type: 'COMPILE_SUCCESS'; payload: string }
+  | { type: 'COMPILE_FAILURE'; payload: string }
+  | { type: 'SET_WGSL_CODE'; payload: string }
+  | { type: 'SET_FORMAT'; payload: string }
+  | { type: 'EDITOR_LOADED' };
+
+const getInitialState = (): State => {
+  const persistedFormat = typeof window !== 'undefined'
+    ? localStorage.getItem('translator_format')
+    : null;
+  return {
+    status: 'initializing',
+    formats: [],
+    wgslCode: DEFAULT_WGSL,
+    output: '',
+    format: persistedFormat || 'glsl',
+    loadingEditor: true,
+  };
+};
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'INIT_SUCCESS':
+      return {
+        ...state,
+        status: 'ready',
+        formats: action.payload,
+      };
+    case 'INIT_FAILURE':
+      return {
+        ...state,
+        status: 'error',
+        errorMessage: action.payload,
+      };
+    case 'COMPILE_START':
+      return {
+        ...state,
+        status: 'compiling',
+      };
+    case 'COMPILE_SUCCESS':
+      return {
+        ...state,
+        status: 'success',
+        output: action.payload,
+      };
+    case 'COMPILE_FAILURE':
+      return {
+        ...state,
+        status: 'error',
+        errorMessage: action.payload,
+        output: '',
+      };
+    case 'SET_WGSL_CODE':
+      return { ...state, wgslCode: action.payload };
+    case 'SET_FORMAT':
+      return { ...state, format: action.payload, output: '' };
+    case 'EDITOR_LOADED':
+      return { ...state, loadingEditor: false };
+    default:
+      return state;
+  }
+}
+
+export function useShaderTranslator() {
+  const [state, dispatch] = useReducer(reducer, undefined, getInitialState);
+  const {
+    status,
+    errorMessage,
+    formats,
+    wgslCode,
+    output,
+    format,
+    loadingEditor,
+  } = state;
+
+  useEffect(() => {
+    try {
+      const fmts = initializeWasm();
+      dispatch({ type: 'INIT_SUCCESS', payload: fmts });
+    } catch (err) {
+      dispatch({ type: 'INIT_FAILURE', payload: getErrorMessage(err) });
+    }
+  }, []);
+
+  useEffect(() => {
+    localStorage.setItem('translator_format', format);
+  }, [format]);
+
+  const handleCompile = useCallback(() => {
+    if (status === 'compiling') return;
+    dispatch({ type: 'COMPILE_START' });
+    try {
+      const result = compile(wgslCode, format);
+      dispatch({ type: 'COMPILE_SUCCESS', payload: result });
+    } catch (err) {
+      dispatch({ type: 'COMPILE_FAILURE', payload: getErrorMessage(err) });
+    }
+  }, [wgslCode, format, status]);
+
+  const setWgslCode = (code: string) => {
+    dispatch({ type: 'SET_WGSL_CODE', payload: code });
+  };
+
+  const setFormat = (newFormat: string) => {
+    dispatch({ type: 'SET_FORMAT', payload: newFormat });
+  };
+
+  const setEditorLoaded = () => {
+    dispatch({ type: 'EDITOR_LOADED' });
+  };
+
+  const canCompile = formats.length > 0 && !loadingEditor &&
+    status !== 'compiling';
+
+  return {
+    status,
+    errorMessage,
+    formats,
+    wgslCode,
+    output,
+    format,
+    loadingEditor,
+    canCompile,
+    setWgslCode,
+    setFormat,
+    setEditorLoaded,
+    handleCompile,
+  };
+}

apps/typegpu-docs/src/pages/translator/lib/wgslTool.ts

@@ -0,0 +1,21 @@
+import {
+  compileShader,
+  getSupportedFormats,
+  init,
+} from 'wgsl-wasm-transpiler-bundler';
+
+/** Normalize any thrown value into a readable string */
+export function getErrorMessage(err: unknown): string {
+  if (typeof err === 'string') return err;
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+export function initializeWasm() {
+  init();
+  return getSupportedFormats();
+}
+
+export function compile(wgslCode: string, format: string) {
+  return compileShader(wgslCode, format);
+}