@fluxgpu/engine

WebGPU executor and high-level API for FluxGPU.

Overview

This package provides the main GPU execution layer based on the hexagonal architecture:

AdapterExecutor: High-level WebGPU executor that works with any IGPUAdapter implementation
Resource management (buffers, textures, shaders, pipelines)
Command encoding and submission
Frame-based rendering

Installation

pnpm add @fluxgpu/engine @fluxgpu/host-browser @fluxgpu/contracts

Usage

Initialize Executor

import { AdapterExecutor } from '@fluxgpu/engine';
import { BrowserGPUAdapter } from '@fluxgpu/host-browser';

const canvas = document.getElementById('canvas') as HTMLCanvasElement;

// Create adapter and executor
const adapter = new BrowserGPUAdapter({ canvas });
const executor = new AdapterExecutor({ adapter });

// Initialize (async)
await executor.initialize();

Create Resources

import { BufferUsage } from '@fluxgpu/contracts';

// Create buffer
const buffer = executor.createBuffer({
  size: 1024,
  usage: BufferUsage.STORAGE | BufferUsage.COPY_DST,
});

// Write data to buffer
const data = new Float32Array([1, 2, 3, 4]);
executor.writeBuffer(buffer, data);

// Read data from buffer
const result = await executor.readBuffer(buffer);

// Create texture
const texture = executor.createTexture({
  size: { width: 512, height: 512 },
  format: 'rgba8unorm',
  usage: TextureUsage.RENDER_ATTACHMENT | TextureUsage.TEXTURE_BINDING,
});

// Create shader module
const shader = executor.createShaderModule(wgslCode);

Create Pipelines

// Compute pipeline
const computePipeline = await executor.createComputePipeline({
  shader: computeShader,
  entryPoint: 'main',
});

// Render pipeline
const renderPipeline = await executor.createRenderPipeline({
  vertex: {
    shader: vertexShader,
    entryPoint: 'main',
  },
  fragment: {
    shader: fragmentShader,
    entryPoint: 'main',
    targets: [{ format: executor.getPreferredFormat() }],
  },
});

Execute Commands

// Single frame execution
executor.frame((encoder) => {
  // Compute pass
  const computePass = encoder.beginComputePass();
  computePass.setPipeline(computePipeline);
  computePass.setBindGroup(0, computeBindGroup);
  computePass.dispatchWorkgroups(64);
  computePass.end();

  // Render pass
  const renderTarget = executor.getCurrentTexture();
  if (renderTarget) {
    const renderPass = encoder.beginRenderPass({
      colorAttachments: [{
        view: renderTarget.createView(),
        clearValue: { r: 0, g: 0, b: 0.1, a: 1 },
        loadOp: 'clear',
        storeOp: 'store',
      }],
    });
    renderPass.setPipeline(renderPipeline);
    renderPass.setBindGroup(0, renderBindGroup);
    renderPass.draw(vertexCount);
    renderPass.end();
  }
});

// Or manual command encoding
const encoder = executor.createCommandEncoder();
// ... encode commands ...
executor.submit(encoder);

Cleanup

// Destroy specific resource
executor.destroyResource(buffer.id);

// Dispose all resources and executor
executor.dispose();

API Reference

AdapterExecutor

Method	Description
`initialize()`	Initialize the executor (async)
`isInitialized()`	Check if executor is initialized
`getPreferredFormat()`	Get preferred texture format
`supportsFeature(feature)`	Check if a GPU feature is supported
`createBuffer(descriptor)`	Create a GPU buffer
`createTexture(descriptor)`	Create a GPU texture
`createShaderModule(code)`	Create a shader module from WGSL code
`createComputePipeline(descriptor)`	Create a compute pipeline (async)
`createRenderPipeline(descriptor)`	Create a render pipeline (async)
`writeBuffer(buffer, data, offset?)`	Write data to a buffer
`readBuffer(buffer)`	Read data from a buffer (async)
`createCommandEncoder()`	Create a command encoder
`submit(encoder)`	Submit encoded commands
`frame(callback)`	Execute a frame with automatic command encoding
`getCurrentTexture()`	Get current render target texture
`getResource(id)`	Get a managed resource by ID
`destroyResource(id)`	Destroy a specific resource
`getAdapter()`	Get the underlying IGPUAdapter
`dispose()`	Dispose all resources and cleanup

Configuration

interface AdapterExecutorConfig {
  /** GPU adapter - dependency injection */
  adapter: IGPUAdapter;
}

Hexagonal Architecture

The AdapterExecutor is designed following hexagonal architecture principles:

Depends on interfaces: Uses IGPUAdapter interface, not concrete implementations
Environment agnostic: Can work with any adapter (browser, worker, node, etc.)
Testable: Easy to mock the adapter for testing
Extensible: New adapters can be created for different environments

┌─────────────────────────────────────────┐
│           AdapterExecutor               │
│         (Domain/Application)            │
└─────────────────────────────────────────┘
                    │
                    │ depends on
                    ▼
┌─────────────────────────────────────────┐
│            IGPUAdapter                  │
│              (Port)                     │
└─────────────────────────────────────────┘
                    │
                    │ implemented by
                    ▼
┌─────────────────────────────────────────┐
│         BrowserGPUAdapter               │
│            (Adapter)                    │
└─────────────────────────────────────────┘