Function initializeGPUContext

src/core/GPUContext.ts:122–242

(
  context: GPUContextState
)

 * @throws {Error} If already initialized
 */
export async function initializeGPUContext(
  context: GPUContextState
): Promise<GPUContextState> {
  if (context.initialized) {
    throw new Error('GPUContext is already initialized. Call destroyGPUContext() before reinitializing.');
  }

  // Be resilient: callers may construct GPUContextState manually.
  const sanitizedDevicePixelRatio =
    Number.isFinite(context.devicePixelRatio) && context.devicePixelRatio > 0 ? context.devicePixelRatio : 1.0;

  // Check for WebGPU support
  if (!navigator.gpu) {
    throw new Error(
      'WebGPU is not available in this browser. ' +
      'Please use a browser that supports WebGPU (Chrome 113+, Edge 113+, or Safari 18+). ' +
      'Ensure WebGPU is enabled in browser flags if needed.'
    );
  }

  let device: GPUDevice | null = null;

  try {
    // Request adapter with power preference from context
    const adapter = await navigator.gpu.requestAdapter({
      powerPreference: context.powerPreference,
    });

    if (!adapter) {
      throw new Error(
        'Failed to request WebGPU adapter. ' +
        'No compatible adapter found. This may occur if no GPU is available or WebGPU is disabled.'
      );
    }

    // Request device from adapter
    device = await adapter.requestDevice();

    if (!device) {
      throw new Error('Failed to request WebGPU device from adapter.');
    }

    // Set up device lost handler for error recovery
    device.addEventListener('uncapturederror', (event: GPUUncapturedErrorEvent) => {
      console.error('WebGPU uncaptured error:', event.error);
    });

    let canvasContext: GPUCanvasContext | null = null;
    let preferredFormat: GPUTextureFormat | null = null;

    // Configure canvas if provided
    if (context.canvas) {
      const webgpuContext = context.canvas.getContext('webgpu') as GPUCanvasContext | null;
      
      if (!webgpuContext) {
        // Clean up device before throwing
        try {
          device.destroy();