webgpubridge 0.1.0

package/README.md

@@ -0,0 +1,66 @@
+<div align="center">
+
+# WebGPUbridge
+
+### A small, explicit bridge from portable 3D descriptions to WebGPU.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Module](https://img.shields.io/badge/module-ESM-f7df1e?logo=javascript&logoColor=111827)](package.json) [![WebGPU](https://img.shields.io/badge/WebGPU-native-005a9c?logo=webgpu&logoColor=white)](https://www.w3.org/TR/webgpu/) [![Status](https://img.shields.io/badge/status-pre--alpha-f5a623)](https://shaderlab.dev)
+
+[shaderlab.dev](https://shaderlab.dev)
+
+</div>
+
+WebGPUbridge materializes Web3D Kit descriptors as WebGPU-ready data and
+caller-owned GPU resources. It keeps scene descriptions portable while leaving
+adapter selection, device ownership, rendering, and asset loading explicit.
+
+## Install
+
+```sh
+npm install webgpubridge web3d-kit
+```
+
+```ts
+import { mesh, planeGeometry, shaderMaterial } from "web3d-kit";
+import { createWebGPUObject } from "webgpubridge";
+
+const object = createWebGPUObject(
+  mesh({
+    geometry: planeGeometry({ width: 2, height: 2 }),
+    material: shaderMaterial({ vertexShader, fragmentShader }),
+  }),
+);
+```
+
+## Architecture
+
+```text
+shader-runtime        webgl-kit
+      │                  │
+      └─────────┬────────┘
+                ▼
+            web3d-kit
+                │
+                ▼
+           webgpubridge
+                │
+                ▼
+              WebGPU
+```
+
+`web3d-kit` owns portable descriptions; `webgpubridge` materializes those
+descriptions without taking ownership of a WebGPU adapter, device, or queue.
+
+## Supported conversions
+
+- vectors, transforms, bounds, scenes, groups, meshes, and cameras
+- plane, box, sphere, and simple position/index buffer geometry
+- basic, standard, and shader material envelopes
+- tightly packed scalar and vector uniform blocks
+- explicit GPU buffer, shader module, and render-pipeline helpers
+
+## Lifecycle
+
+Use `disposeWebGPUBuffer` or `disposeWebGPUGeometry` explicitly. The bridge
+does not request an adapter or device, submit work, or dispose caller-owned
+pipelines and textures.

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import type { Bounds3D, CameraDescriptor, ColorValue, GeometryDescriptor, MaterialDescriptor, SceneDescriptor, SceneNode, Transform3D, UniformMap, UniformValue, Vec2, Vec3, Vec4 } from "web3d-kit";
+/** The small subset of WebGPU used by this adapter, kept structural so the
+ * package can be used with browser and Node WebGPU implementations alike. */
+export interface WebGPUDevice {
+    createBuffer(descriptor: {
+        size: number;
+        usage: number;
+        mappedAtCreation?: boolean;
+    }): WebGPUBuffer;
+    createShaderModule(descriptor: {
+        code: string;
+        label?: string;
+    }): WebGPUShaderModule;
+}
+export interface WebGPUBuffer {
+    destroy(): void;
+    getMappedRange?(): ArrayBuffer;
+    unmap?(): void;
+}
+export interface WebGPUShaderModule {
+    readonly label?: string;
+}
+export interface WebGPUQueue {
+    writeBuffer(buffer: WebGPUBuffer, offset: number, data: ArrayBufferView): void;
+}
+export interface WebGPURenderPipelineDescriptor {
+    layout?: unknown;
+    vertex: {
+        module: WebGPUShaderModule;
+        entryPoint?: string;
+        buffers?: readonly unknown[];
+    };
+    fragment?: {
+        module: WebGPUShaderModule;
+        entryPoint?: string;
+        targets?: readonly unknown[];
+    };
+    primitive?: Record<string, unknown>;
+}
+export interface WebGPUTransform {
+    position?: Vec3;
+    rotation?: Vec3;
+    scale?: Vec3;
+}
+export interface WebGPUUniform {
+    value: UniformValue;
+    offset: number;
+}
+export interface WebGPUUniformBlock {
+    data: Float32Array;
+    uniforms: Readonly<Record<string, WebGPUUniform>>;
+}
+export interface WebGPUGeometry {
+    readonly positions: Float32Array;
+    readonly indices?: Uint32Array;
+    readonly bounds?: Bounds3D;
+}
+export interface WebGPUBufferGeometry extends WebGPUGeometry {
+    readonly vertexBuffer: WebGPUBuffer;
+    readonly indexBuffer?: WebGPUBuffer;
+    readonly vertexCount: number;
+    readonly indexCount: number;
+}
+export interface WebGPUMaterial {
+    readonly type: MaterialDescriptor["type"];
+    readonly color?: ColorValue;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+    readonly side?: MaterialDescriptor["side"];
+    readonly vertexShader?: string;
+    readonly fragmentShader?: string;
+    readonly uniforms: UniformBlock;
+}
+export type UniformBlock = WebGPUUniformBlock;
+export interface WebGPUObject {
+    type: "mesh" | "group";
+    name?: string;
+    visible: boolean;
+    transform?: Transform3D;
+    metadata?: SceneNode["metadata"];
+    geometry?: WebGPUGeometry;
+    material?: WebGPUMaterial;
+    children: WebGPUObject[];
+}
+export interface WebGPUScene {
+    type: "scene";
+    metadata?: SceneDescriptor["metadata"];
+    children: WebGPUObject[];
+}
+export declare const toWebGPUVector2: (value: Vec2) => Float32Array;
+export declare const toWebGPUVector3: (value: Vec3) => Float32Array;
+export declare const toWebGPUVector4: (value: Vec4) => Float32Array;
+export declare function applyWebGPUTransform(target: {
+    transform?: Transform3D;
+}, transform?: Transform3D): typeof target;
+export declare function toWebGPUGeometry(descriptor: GeometryDescriptor): WebGPUGeometry;
+/** Converts uniforms to a tightly packed scalar/vector block. Values remain immutable. */
+export declare function toWebGPUUniforms(uniforms?: UniformMap): WebGPUUniformBlock;
+export declare function toWebGPUMaterial(descriptor: MaterialDescriptor): WebGPUMaterial;
+export declare function createWebGPUBufferGeometry(device: WebGPUDevice, descriptor: GeometryDescriptor, queue?: WebGPUQueue): WebGPUBufferGeometry;
+export declare function createWebGPUShaderModule(device: WebGPUDevice, code: string, label?: string): WebGPUShaderModule;
+export declare function createWebGPURenderPipeline(device: WebGPUDevice, descriptor: WebGPURenderPipelineDescriptor): unknown;
+export declare function createWebGPUObject(descriptor: SceneNode): WebGPUObject;
+export declare function toWebGPUScene(descriptor: SceneDescriptor): WebGPUScene;
+export declare function toWebGPUCamera(descriptor: CameraDescriptor): CameraDescriptor;
+export declare function disposeWebGPUBuffer(buffer: WebGPUBuffer): void;
+export declare function disposeWebGPUGeometry(geometry: WebGPUBufferGeometry): void;

package/dist/index.js

@@ -0,0 +1 @@
+const m=e=>new Float32Array(e),p=e=>new Float32Array(e),b=e=>new Float32Array(e);function d(e,t){return t&&(e.transform={...t,position:t.position&&[...t.position],rotation:t.rotation&&[...t.rotation],scale:t.scale&&[...t.scale]}),e}function l(e){if(e.type==="buffer")return{positions:new Float32Array(e.positions.flat()),indices:e.indices&&new Uint32Array(e.indices)};if(e.type==="plane"){const n=e.width/2,o=e.height/2;return{positions:new Float32Array([-n,-o,0,n,-o,0,n,o,0,-n,o,0]),indices:new Uint32Array([0,1,2,0,2,3])}}if(e.type==="box"){const n=e.width/2,o=e.height/2,i=e.depth/2,s=[[-n,-o,-i],[n,-o,-i],[n,o,-i],[-n,o,-i],[-n,-o,i],[n,-o,i],[n,o,i],[-n,o,i]];return{positions:new Float32Array(s.flat()),indices:new Uint32Array([0,1,2,0,2,3,4,6,5,4,7,6,0,4,5,0,5,1,2,6,7,2,7,3,0,3,7,0,7,4,1,5,6,1,6,2])}}const t=Math.max(3,e.heightSegments??16),a=Math.max(3,e.widthSegments??32),r=[],f=[];for(let n=0;n<=t;n++)for(let o=0;o<=a;o++){const i=n/t,s=o/a,u=i*Math.PI,y=s*Math.PI*2;r.push(Math.sin(u)*Math.cos(y)*e.radius,Math.cos(u)*e.radius,Math.sin(u)*Math.sin(y)*e.radius)}for(let n=0;n<t;n++)for(let o=0;o<a;o++){const i=n*(a+1)+o;f.push(i,i+a+1,i+1,i+1,i+a+1,i+a+2)}return{positions:new Float32Array(r),indices:new Uint32Array(f)}}function P(e){return l(e)}function c(e={}){const t=[],a={};for(const[r,f]of Object.entries(e)){const n=t.length;typeof f=="boolean"||typeof f=="number"?t.push(typeof f=="boolean"?f?1:0:f):t.push(...f),a[r]={value:f,offset:n}}return{data:new Float32Array(t),uniforms:a}}function x(e){return{type:e.type,color:"color"in e?e.color:void 0,opacity:e.opacity,transparent:e.transparent??(e.opacity!==void 0&&e.opacity<1),side:e.side,vertexShader:e.type==="shader"?e.vertexShader:void 0,fragmentShader:e.type==="shader"?e.fragmentShader:void 0,uniforms:c(e.type==="shader"?e.uniforms:{})}}function U(e,t,a){const r=l(t),f=e.createBuffer({size:r.positions.byteLength,usage:40});a?.writeBuffer(f,0,r.positions);const n=r.indices?e.createBuffer({size:r.indices.byteLength,usage:24}):void 0;return n&&r.indices&&a?.writeBuffer(n,0,r.indices),{...r,vertexBuffer:f,indexBuffer:n,vertexCount:r.positions.length/3,indexCount:r.indices?.length??0}}function w(e,t,a){return e.createShaderModule({code:t,...a?{label:a}:{}})}function G(e,t){const a=e.createRenderPipeline;if(!a)throw new TypeError("The supplied WebGPU device does not support createRenderPipeline.");return a.call(e,t)}function h(e){const t={type:e.type,name:e.name,visible:e.visible??!0,transform:e.transform,metadata:e.metadata,children:[]};return e.type==="mesh"?(t.geometry=l(e.geometry),t.material=x(e.material)):t.children=(e.children??[]).map(h),t}function g(e){return{type:"scene",metadata:e.metadata,children:(e.children??[]).map(h)}}function W(e){return{...e,transform:e.transform&&{...e.transform}}}function A(e){e.destroy()}function M(e){e.vertexBuffer.destroy(),e.indexBuffer?.destroy()}export{d as applyWebGPUTransform,U as createWebGPUBufferGeometry,h as createWebGPUObject,G as createWebGPURenderPipeline,w as createWebGPUShaderModule,A as disposeWebGPUBuffer,M as disposeWebGPUGeometry,W as toWebGPUCamera,P as toWebGPUGeometry,x as toWebGPUMaterial,g as toWebGPUScene,c as toWebGPUUniforms,m as toWebGPUVector2,p as toWebGPUVector3,b as toWebGPUVector4};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "webgpubridge",
+  "version": "0.1.0",
+  "description": "Small adapters between portable Web3D Kit descriptors and WebGPU.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "homepage": "https://shaderlab.dev",
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "postbuild": "npm run dist --prefix \"$npm_config_local_prefix\" -- \"$PWD\"",
+    "pretest": "npm run build",
+    "test": "node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "web3d-kit": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}