@motion-core/motion-gpu 0.1.0

package/dist/core/shader.d.ts

@@ -0,0 +1,42 @@
+import type { MaterialLineMap, MaterialSourceLocation } from './material-preprocess';
+import type { UniformLayout } from './types';
+/**
+ * 1-based map from generated WGSL lines to original material source lines.
+ */
+export type ShaderLineMap = Array<MaterialSourceLocation | null>;
+/**
+ * Result of shader source generation with line mapping metadata.
+ */
+export interface BuiltShaderSource {
+    /**
+     * Full WGSL source code.
+     */
+    code: string;
+    /**
+     * 1-based generated-line map to material source locations.
+     */
+    lineMap: ShaderLineMap;
+}
+/**
+ * Assembles complete WGSL shader source used by the fullscreen renderer pipeline.
+ *
+ * @param fragmentWgsl - User fragment shader code containing `frag(uv: vec2f) -> vec4f`.
+ * @param uniformLayout - Resolved uniform layout.
+ * @param textureKeys - Sorted texture keys.
+ * @param options - Shader build options.
+ * @returns Complete WGSL source for vertex + fragment stages.
+ */
+export declare function buildShaderSource(fragmentWgsl: string, uniformLayout: UniformLayout, textureKeys?: string[], options?: {
+    convertLinearToSrgb?: boolean;
+}): string;
+/**
+ * Assembles complete WGSL shader source with material-source line mapping metadata.
+ */
+export declare function buildShaderSourceWithMap(fragmentWgsl: string, uniformLayout: UniformLayout, textureKeys?: string[], options?: {
+    convertLinearToSrgb?: boolean;
+    fragmentLineMap?: MaterialLineMap;
+}): BuiltShaderSource;
+/**
+ * Converts source location metadata to user-facing diagnostics label.
+ */
+export declare function formatShaderSourceLocation(location: MaterialSourceLocation | null): string | null;

package/dist/core/shader.js

@@ -0,0 +1,196 @@
+import { assertUniformName } from './uniforms';
+/**
+ * Fallback uniform field used when no custom uniforms are provided.
+ */
+const DEFAULT_UNIFORM_FIELD = 'motiongpu_unused: vec4f,';
+/**
+ * Builds WGSL struct fields for user uniforms.
+ */
+function buildUniformStruct(layout) {
+    if (layout.entries.length === 0) {
+        return DEFAULT_UNIFORM_FIELD;
+    }
+    return layout.entries
+        .map((entry) => {
+        assertUniformName(entry.name);
+        return `${entry.name}: ${entry.type},`;
+    })
+        .join('\n\t');
+}
+/**
+ * Builds a numeric expression that references one uniform value to keep bindings alive.
+ */
+function getKeepAliveExpression(layout) {
+    if (layout.entries.length === 0) {
+        return 'motiongpuUniforms.motiongpu_unused.x';
+    }
+    const [firstEntry] = layout.entries;
+    if (!firstEntry) {
+        return 'motiongpuUniforms.motiongpu_unused.x';
+    }
+    if (firstEntry.type === 'f32') {
+        return `motiongpuUniforms.${firstEntry.name}`;
+    }
+    if (firstEntry.type === 'mat4x4f') {
+        return `motiongpuUniforms.${firstEntry.name}[0].x`;
+    }
+    return `motiongpuUniforms.${firstEntry.name}.x`;
+}
+/**
+ * Builds texture sampler/texture binding declarations.
+ */
+function buildTextureBindings(textureKeys) {
+    if (textureKeys.length === 0) {
+        return '';
+    }
+    const declarations = [];
+    for (let index = 0; index < textureKeys.length; index += 1) {
+        const key = textureKeys[index];
+        if (key === undefined) {
+            continue;
+        }
+        assertUniformName(key);
+        const binding = 2 + index * 2;
+        declarations.push(`@group(0) @binding(${binding}) var ${key}Sampler: sampler;`);
+        declarations.push(`@group(0) @binding(${binding + 1}) var ${key}: texture_2d<f32>;`);
+    }
+    return declarations.join('\n');
+}
+/**
+ * Optionally returns helper WGSL for linear-to-sRGB conversion.
+ */
+function buildColorTransformHelpers(enableSrgbTransform) {
+    if (!enableSrgbTransform) {
+        return '';
+    }
+    return `
+fn motiongpuLinearToSrgb(linearColor: vec3f) -> vec3f {
+	let cutoff = vec3f(0.0031308);
+	let lower = linearColor * 12.92;
+	let higher = vec3f(1.055) * pow(linearColor, vec3f(1.0 / 2.4)) - vec3f(0.055);
+	return select(lower, higher, linearColor > cutoff);
+}
+`;
+}
+/**
+ * Builds fragment output code with optional color-space conversion.
+ */
+function buildFragmentOutput(keepAliveExpression, enableSrgbTransform) {
+    if (enableSrgbTransform) {
+        return `
+	let fragColor = frag(in.uv);
+	let motiongpuKeepAlive = ${keepAliveExpression};
+	let motiongpuLinear = vec4f(fragColor.rgb + motiongpuKeepAlive * 0.0, fragColor.a);
+	let motiongpuSrgb = motiongpuLinearToSrgb(max(motiongpuLinear.rgb, vec3f(0.0)));
+	return vec4f(motiongpuSrgb, motiongpuLinear.a);
+`;
+    }
+    return `
+	let fragColor = frag(in.uv);
+	let motiongpuKeepAlive = ${keepAliveExpression};
+	return vec4f(fragColor.rgb + motiongpuKeepAlive * 0.0, fragColor.a);
+`;
+}
+/**
+ * Assembles complete WGSL shader source used by the fullscreen renderer pipeline.
+ *
+ * @param fragmentWgsl - User fragment shader code containing `frag(uv: vec2f) -> vec4f`.
+ * @param uniformLayout - Resolved uniform layout.
+ * @param textureKeys - Sorted texture keys.
+ * @param options - Shader build options.
+ * @returns Complete WGSL source for vertex + fragment stages.
+ */
+export function buildShaderSource(fragmentWgsl, uniformLayout, textureKeys = [], options) {
+    const uniformFields = buildUniformStruct(uniformLayout);
+    const keepAliveExpression = getKeepAliveExpression(uniformLayout);
+    const textureBindings = buildTextureBindings(textureKeys);
+    const enableSrgbTransform = options?.convertLinearToSrgb ?? false;
+    const colorTransformHelpers = buildColorTransformHelpers(enableSrgbTransform);
+    const fragmentOutput = buildFragmentOutput(keepAliveExpression, enableSrgbTransform);
+    return `
+struct MotionGPUFrame {
+	time: f32,
+	delta: f32,
+	resolution: vec2f,
+};
+
+struct MotionGPUUniforms {
+	${uniformFields}
+};
+
+@group(0) @binding(0) var<uniform> motiongpuFrame: MotionGPUFrame;
+@group(0) @binding(1) var<uniform> motiongpuUniforms: MotionGPUUniforms;
+${textureBindings}
+${colorTransformHelpers}
+
+struct MotionGPUVertexOut {
+	@builtin(position) position: vec4f,
+	@location(0) uv: vec2f,
+};
+
+@vertex
+fn motiongpuVertex(@builtin(vertex_index) index: u32) -> MotionGPUVertexOut {
+	var positions = array<vec2f, 3>(
+		vec2f(-1.0, -3.0),
+		vec2f(-1.0, 1.0),
+		vec2f(3.0, 1.0)
+	);
+
+	let position = positions[index];
+	var out: MotionGPUVertexOut;
+	out.position = vec4f(position, 0.0, 1.0);
+	out.uv = (position + vec2f(1.0, 1.0)) * 0.5;
+	return out;
+}
+
+${fragmentWgsl}
+
+@fragment
+fn motiongpuFragment(in: MotionGPUVertexOut) -> @location(0) vec4f {
+	${fragmentOutput}
+}
+`;
+}
+/**
+ * Assembles complete WGSL shader source with material-source line mapping metadata.
+ */
+export function buildShaderSourceWithMap(fragmentWgsl, uniformLayout, textureKeys = [], options) {
+    const code = buildShaderSource(fragmentWgsl, uniformLayout, textureKeys, options);
+    const fragmentStartIndex = code.indexOf(fragmentWgsl);
+    const lineCount = code.split('\n').length;
+    const lineMap = new Array(lineCount + 1).fill(null);
+    if (fragmentStartIndex === -1) {
+        return {
+            code,
+            lineMap
+        };
+    }
+    const fragmentStartLine = code.slice(0, fragmentStartIndex).split('\n').length;
+    const fragmentLineCount = fragmentWgsl.split('\n').length;
+    for (let line = 0; line < fragmentLineCount; line += 1) {
+        const generatedLine = fragmentStartLine + line;
+        lineMap[generatedLine] = options?.fragmentLineMap?.[line + 1] ?? {
+            kind: 'fragment',
+            line: line + 1
+        };
+    }
+    return {
+        code,
+        lineMap
+    };
+}
+/**
+ * Converts source location metadata to user-facing diagnostics label.
+ */
+export function formatShaderSourceLocation(location) {
+    if (!location) {
+        return null;
+    }
+    if (location.kind === 'fragment') {
+        return `fragment line ${location.line}`;
+    }
+    if (location.kind === 'include') {
+        return `include <${location.include}> line ${location.line}`;
+    }
+    return `define "${location.define}" line ${location.line}`;
+}

package/dist/core/texture-loader.d.ts

@@ -0,0 +1,129 @@
+import type { TextureUpdateMode } from './types';
+/**
+ * Options controlling bitmap decode behavior.
+ */
+export interface TextureDecodeOptions {
+    /**
+     * Controls color-space conversion during decode.
+     */
+    colorSpaceConversion?: 'default' | 'none';
+    /**
+     * Controls alpha premultiplication during decode.
+     */
+    premultiplyAlpha?: 'default' | 'none' | 'premultiply';
+    /**
+     * Controls bitmap orientation during decode.
+     */
+    imageOrientation?: 'none' | 'flipY';
+}
+/**
+ * Options controlling URL-based texture loading and decode behavior.
+ */
+export interface TextureLoadOptions {
+    /**
+     * Desired texture color space.
+     */
+    colorSpace?: 'srgb' | 'linear';
+    /**
+     * Fetch options forwarded to `fetch`.
+     */
+    requestInit?: RequestInit;
+    /**
+     * Decode options forwarded to `createImageBitmap`.
+     */
+    decode?: TextureDecodeOptions;
+    /**
+     * Optional cancellation signal for this request.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional runtime update strategy metadata attached to loaded textures.
+     */
+    update?: TextureUpdateMode;
+    /**
+     * Optional runtime flip-y metadata attached to loaded textures.
+     */
+    flipY?: boolean;
+    /**
+     * Optional runtime premultiplied-alpha metadata attached to loaded textures.
+     */
+    premultipliedAlpha?: boolean;
+    /**
+     * Optional runtime mipmap metadata attached to loaded textures.
+     */
+    generateMipmaps?: boolean;
+}
+/**
+ * Loaded texture payload returned by URL loaders.
+ */
+export interface LoadedTexture {
+    /**
+     * Source URL.
+     */
+    url: string;
+    /**
+     * Decoded bitmap source.
+     */
+    source: ImageBitmap;
+    /**
+     * Bitmap width in pixels.
+     */
+    width: number;
+    /**
+     * Bitmap height in pixels.
+     */
+    height: number;
+    /**
+     * Effective color space.
+     */
+    colorSpace: 'srgb' | 'linear';
+    /**
+     * Effective runtime update strategy.
+     */
+    update?: TextureUpdateMode;
+    /**
+     * Effective runtime flip-y metadata.
+     */
+    flipY?: boolean;
+    /**
+     * Effective runtime premultiplied-alpha metadata.
+     */
+    premultipliedAlpha?: boolean;
+    /**
+     * Effective runtime mipmap metadata.
+     */
+    generateMipmaps?: boolean;
+    /**
+     * Releases bitmap resources.
+     */
+    dispose: () => void;
+}
+/**
+ * Checks whether error represents abort cancellation.
+ */
+export declare function isAbortError(error: unknown): boolean;
+/**
+ * Builds deterministic resource cache key from full URL IO config.
+ */
+export declare function buildTextureResourceCacheKey(url: string, options?: TextureLoadOptions): string;
+/**
+ * Clears the internal texture resource cache.
+ */
+export declare function clearTextureBlobCache(): void;
+/**
+ * Loads a single texture from URL and converts it to an `ImageBitmap`.
+ *
+ * @param url - Texture URL.
+ * @param options - Loading options.
+ * @returns Loaded texture object.
+ * @throws {Error} When runtime does not support `createImageBitmap` or request fails.
+ */
+export declare function loadTextureFromUrl(url: string, options?: TextureLoadOptions): Promise<LoadedTexture>;
+/**
+ * Loads many textures in parallel from URLs.
+ *
+ * @param urls - Texture URLs.
+ * @param options - Shared loading options.
+ * @returns Promise resolving to loaded textures in input order.
+ */
+export declare function loadTexturesFromUrls(urls: string[], options?: TextureLoadOptions): Promise<LoadedTexture[]>;

package/dist/core/texture-loader.js

@@ -0,0 +1,295 @@
+const resourceCache = new Map();
+function createAbortError() {
+    try {
+        return new DOMException('Texture request was aborted', 'AbortError');
+    }
+    catch {
+        const error = new Error('Texture request was aborted');
+        error.name = 'AbortError';
+        return error;
+    }
+}
+/**
+ * Checks whether error represents abort cancellation.
+ */
+export function isAbortError(error) {
+    return (error instanceof Error &&
+        (error.name === 'AbortError' || error.message.toLowerCase().includes('aborted')));
+}
+function toBodyFingerprint(body) {
+    if (body == null) {
+        return null;
+    }
+    if (typeof body === 'string') {
+        return `string:${body}`;
+    }
+    if (body instanceof URLSearchParams) {
+        return `urlsearchparams:${body.toString()}`;
+    }
+    if (typeof FormData !== 'undefined' && body instanceof FormData) {
+        const entries = Array.from(body.entries()).map(([key, value]) => `${key}:${String(value)}`);
+        return `formdata:${entries.join('&')}`;
+    }
+    if (body instanceof Blob) {
+        return `blob:${body.type}:${body.size}`;
+    }
+    if (body instanceof ArrayBuffer) {
+        return `arraybuffer:${body.byteLength}`;
+    }
+    if (ArrayBuffer.isView(body)) {
+        return `view:${body.byteLength}`;
+    }
+    return `opaque:${Object.prototype.toString.call(body)}`;
+}
+function normalizeRequestInit(requestInit) {
+    if (!requestInit) {
+        return {};
+    }
+    const headers = new Headers(requestInit.headers);
+    const headerEntries = Array.from(headers.entries()).sort(([a], [b]) => a.localeCompare(b));
+    const normalized = {};
+    normalized.method = (requestInit.method ?? 'GET').toUpperCase();
+    normalized.mode = requestInit.mode ?? null;
+    normalized.cache = requestInit.cache ?? null;
+    normalized.credentials = requestInit.credentials ?? null;
+    normalized.redirect = requestInit.redirect ?? null;
+    normalized.referrer = requestInit.referrer ?? null;
+    normalized.referrerPolicy = requestInit.referrerPolicy ?? null;
+    normalized.integrity = requestInit.integrity ?? null;
+    normalized.keepalive = requestInit.keepalive ?? false;
+    normalized.priority = requestInit.priority ?? null;
+    normalized.headers = headerEntries;
+    normalized.body = toBodyFingerprint(requestInit.body);
+    return normalized;
+}
+function normalizeTextureLoadOptions(options) {
+    const colorSpace = options.colorSpace ?? 'srgb';
+    const normalized = {
+        colorSpace,
+        decode: {
+            colorSpaceConversion: options.decode?.colorSpaceConversion ?? (colorSpace === 'linear' ? 'none' : 'default'),
+            premultiplyAlpha: options.decode?.premultiplyAlpha ?? 'default',
+            imageOrientation: options.decode?.imageOrientation ?? 'none'
+        }
+    };
+    if (options.requestInit !== undefined) {
+        normalized.requestInit = options.requestInit;
+    }
+    if (options.signal !== undefined) {
+        normalized.signal = options.signal;
+    }
+    if (options.update !== undefined) {
+        normalized.update = options.update;
+    }
+    if (options.flipY !== undefined) {
+        normalized.flipY = options.flipY;
+    }
+    if (options.premultipliedAlpha !== undefined) {
+        normalized.premultipliedAlpha = options.premultipliedAlpha;
+    }
+    if (options.generateMipmaps !== undefined) {
+        normalized.generateMipmaps = options.generateMipmaps;
+    }
+    return normalized;
+}
+/**
+ * Builds deterministic resource cache key from full URL IO config.
+ */
+export function buildTextureResourceCacheKey(url, options = {}) {
+    const normalized = normalizeTextureLoadOptions(options);
+    return JSON.stringify({
+        url,
+        colorSpace: normalized.colorSpace,
+        requestInit: normalizeRequestInit(normalized.requestInit),
+        decode: normalized.decode
+    });
+}
+/**
+ * Clears the internal texture resource cache.
+ */
+export function clearTextureBlobCache() {
+    for (const entry of resourceCache.values()) {
+        if (!entry.settled) {
+            entry.controller.abort();
+        }
+    }
+    resourceCache.clear();
+}
+function acquireTextureBlob(url, options) {
+    const key = buildTextureResourceCacheKey(url, options);
+    const existing = resourceCache.get(key);
+    if (existing) {
+        existing.refs += 1;
+        let released = false;
+        return {
+            entry: existing,
+            release: () => {
+                if (released) {
+                    return;
+                }
+                released = true;
+                existing.refs = Math.max(0, existing.refs - 1);
+                if (existing.refs === 0) {
+                    if (!existing.settled) {
+                        existing.controller.abort();
+                    }
+                    resourceCache.delete(key);
+                }
+            }
+        };
+    }
+    const normalized = normalizeTextureLoadOptions(options);
+    const controller = new AbortController();
+    const requestInit = {
+        ...(normalized.requestInit ?? {}),
+        signal: controller.signal
+    };
+    const entry = {
+        key,
+        refs: 1,
+        controller,
+        settled: false,
+        blobPromise: fetch(url, requestInit)
+            .then(async (response) => {
+            if (!response.ok) {
+                throw new Error(`Texture request failed (${response.status}) for ${url}`);
+            }
+            return response.blob();
+        })
+            .then((blob) => {
+            entry.settled = true;
+            return blob;
+        })
+            .catch((error) => {
+            resourceCache.delete(key);
+            throw error;
+        })
+    };
+    resourceCache.set(key, entry);
+    let released = false;
+    return {
+        entry,
+        release: () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            entry.refs = Math.max(0, entry.refs - 1);
+            if (entry.refs === 0) {
+                if (!entry.settled) {
+                    entry.controller.abort();
+                }
+                resourceCache.delete(key);
+            }
+        }
+    };
+}
+async function awaitWithAbort(promise, signal) {
+    if (!signal) {
+        return promise;
+    }
+    if (signal.aborted) {
+        throw createAbortError();
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            reject(createAbortError());
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(resolve, reject).finally(() => {
+            signal.removeEventListener('abort', onAbort);
+        });
+    });
+}
+/**
+ * Loads a single texture from URL and converts it to an `ImageBitmap`.
+ *
+ * @param url - Texture URL.
+ * @param options - Loading options.
+ * @returns Loaded texture object.
+ * @throws {Error} When runtime does not support `createImageBitmap` or request fails.
+ */
+export async function loadTextureFromUrl(url, options = {}) {
+    if (typeof createImageBitmap !== 'function') {
+        throw new Error('createImageBitmap is not available in this runtime');
+    }
+    const normalized = normalizeTextureLoadOptions(options);
+    const { entry, release } = acquireTextureBlob(url, options);
+    let bitmap = null;
+    try {
+        const blob = await awaitWithAbort(entry.blobPromise, normalized.signal);
+        const bitmapOptions = {
+            colorSpaceConversion: normalized.decode.colorSpaceConversion,
+            premultiplyAlpha: normalized.decode.premultiplyAlpha,
+            imageOrientation: normalized.decode.imageOrientation
+        };
+        const allDefaults = bitmapOptions.colorSpaceConversion === 'default' &&
+            bitmapOptions.premultiplyAlpha === 'default' &&
+            bitmapOptions.imageOrientation === 'none';
+        bitmap = allDefaults
+            ? await createImageBitmap(blob)
+            : await createImageBitmap(blob, bitmapOptions);
+        if (normalized.signal?.aborted) {
+            bitmap.close();
+            throw createAbortError();
+        }
+        const loaded = {
+            url,
+            source: bitmap,
+            width: bitmap.width,
+            height: bitmap.height,
+            colorSpace: normalized.colorSpace,
+            dispose: () => {
+                bitmap?.close();
+            }
+        };
+        if (normalized.update !== undefined) {
+            loaded.update = normalized.update;
+        }
+        if (normalized.flipY !== undefined) {
+            loaded.flipY = normalized.flipY;
+        }
+        if (normalized.premultipliedAlpha !== undefined) {
+            loaded.premultipliedAlpha = normalized.premultipliedAlpha;
+        }
+        if (normalized.generateMipmaps !== undefined) {
+            loaded.generateMipmaps = normalized.generateMipmaps;
+        }
+        return loaded;
+    }
+    catch (error) {
+        if (bitmap) {
+            bitmap.close();
+        }
+        throw error;
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * Loads many textures in parallel from URLs.
+ *
+ * @param urls - Texture URLs.
+ * @param options - Shared loading options.
+ * @returns Promise resolving to loaded textures in input order.
+ */
+export async function loadTexturesFromUrls(urls, options = {}) {
+    const settled = await Promise.allSettled(urls.map((url) => loadTextureFromUrl(url, options)));
+    const loaded = [];
+    let firstError = null;
+    for (const entry of settled) {
+        if (entry.status === 'fulfilled') {
+            loaded.push(entry.value);
+            continue;
+        }
+        firstError ??= entry.reason;
+    }
+    if (firstError) {
+        for (const texture of loaded) {
+            texture.dispose();
+        }
+        throw firstError;
+    }
+    return loaded;
+}