Add deviceTypes API for WebGPU support (#176)

* Add deviceTypes API for WebGPU support and update documentation

- Introduced a new `deviceTypes` prop in the Application component to specify graphics device types, allowing for fallback options between WebGPU and WebGL2.
- Updated the Application documentation to include details on the new `deviceTypes` prop and its usage.
- Enhanced the Application component to initialize the graphics device based on the specified device types.

* changeset

* Refactor Application tests to include deviceTypes prop

- Updated Application component tests to pass the new deviceTypes prop, ensuring compatibility with the latest graphics device initialization.
- Modified Container, Entity, Screen, and Script component tests to include deviceTypes for consistent testing across components.
- Cleaned up unused code and improved test structure for better readability and maintainability.

* Fix import path for GraphicsDeviceOptions in create-graphics-device.ts

* Update Application component to default deviceTypes to WebGL2 and optimize graphics device initialization

- Set default value for deviceTypes to [DEVICETYPE_WEBGL2] in the ApplicationWithoutCanvas component.
- Introduced memoization for deviceTypes to enhance performance during graphics device creation.
- Updated graphics device initialization to use memoized deviceTypes for improved consistency.

* Enhance Application component with deviceTypes validation and testing

- Added a test case to warn when an invalid deviceTypes prop is provided, ensuring proper validation.
- Refactored the Application component to improve graphics device initialization and memoization of deviceTypes.
- Updated the create-graphics-device utility to allow explicit device type specification without injecting additional devices.
- Adjusted validation error messages for deviceTypes to provide clearer feedback on incorrect usage.

* Update documentation for deviceTypes prop in Application component

- Clarified the description of the deviceTypes prop to specify its role in determining the graphics device order.
- Added information about the "null" device type for testing purposes, enhancing the documentation's comprehensiveness.

Author: marklundin

.changeset/rich-worlds-sleep.md

@@ -0,0 +1,5 @@
+---
+"@playcanvas/react": minor
+---
+
+Added new deviceTypes api for WebGPU and fallback devices

packages/docs/content/docs/api/application.mdx

@@ -55,6 +55,15 @@ Enables physics for the application. Learn more about [Physics in Playcanvas](ht
 Type: `boolean`
 Default: `false`
 
+### `deviceTypes`
+The `deviceTypes` prop determines the graphics device to use. It accepts an array of strings, each representing a different device which sets an order of fallback devices. The first device that gets successfully created, will be used. 
+
+For example, if you want to use WebGPU first, but fall back to WebGL2 when WebGPU is not supported, you can use `<Application deviceTypes={["webgpu", "webgl2"]} />`.
+
+- `"webgpu"` - Use the WebGPU device type
+- `"webgl2"` - Use the WebGL2 device type
+- `"null"` - Use the Null device type. Useful for testing.
+
 ### `fillMode`
 This prop determines how the canvas fills its container. It accepts one of the following values from PlayCanvas:
 

packages/lib/src/Application.test.tsx

@@ -1,43 +1,65 @@
 import { render, screen } from '@testing-library/react';
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { Application, ApplicationWithoutCanvas } from './Application.tsx';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import '@testing-library/jest-dom';
 import React from 'react';
+import { Application, ApplicationWithoutCanvas } from './Application.tsx';
 
 describe('Application', () => {
   beforeEach(() => {
     vi.clearAllMocks();
-    vi.stubEnv('NODE_ENV', 'development');
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
   });
 
   it('The Application component renders with default props', () => {
-    render(<Application />);
+    render(<Application deviceTypes={["null"]} />);
 
     const canvas = screen.getByLabelText('Interactive 3D Scene');
     expect(canvas).toBeInTheDocument();
   });
 
   it('The Application component applies className prop correctly', () => {
-    render(<Application className="test-class" />);
+    render(<Application className="test-class" deviceTypes={["null"]} />);
 
     const canvas = screen.getByLabelText('Interactive 3D Scene');
     expect(canvas).toHaveClass('test-class');
   });
 
   it('The Application component applies style prop correctly', () => {
-    render(<Application style={{ width: '200px', height: '200px' }} />);
+    render(<Application style={{ width: '200px', height: '200px' }} deviceTypes={["null"]} />);
 
     const canvas = screen.getByLabelText('Interactive 3D Scene');
     expect(canvas).toHaveStyle({ width: '200px', height: '200px' });
   });
 
+  
+  it('warns when invalid deviceTypes prop is provided', async () => {
+    // Spy on console.warn
+    const warnSpy = vi
+      .spyOn(console, 'warn')
+      .mockImplementation(() => {});
+
+    try {
+      // @ts-expect-error - we want to test the warning
+      render(<Application deviceTypes={['invalid_device_type']} />);
+
+      // Wait for the warning appears
+      await vi.waitFor(() =>
+        expect(warnSpy).toHaveBeenCalledWith(
+          "%c[PlayCanvas React]:",
+          expect.any(String),                          // the CSS string
+          expect.stringContaining(
+            'deviceTypes must be an array containing one or more of:'
+          )
+        )
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
   it.skip('The Application component applies canvasRef prop correctly', () => {
     const canvasRef = { current: document.createElement('canvas') };
     canvasRef.current.setAttribute('aria-label', 'test-canvas');
-    render(<ApplicationWithoutCanvas canvasRef={canvasRef} />);
+    render(<ApplicationWithoutCanvas canvasRef={canvasRef} deviceTypes={["null"]} />);
 
     const canvas = screen.getByLabelText('test-canvas');
     expect(canvas).toBe(canvasRef.current);

packages/lib/src/Application.tsx

@@ -9,7 +9,9 @@ import {
   TouchDevice,
   Entity as PcEntity,
   RESOLUTION_FIXED,
-  NullGraphicsDevice
+  DEVICETYPE_WEBGL2,
+  DEVICETYPE_WEBGPU,
+  DEVICETYPE_NULL,
 } from 'playcanvas';
 import { AppContext, ParentContext } from './hooks/index.ts';
 import { PointerEventsContext } from './contexts/pointer-events-context.tsx';
@@ -18,6 +20,7 @@ import { PhysicsProvider } from './contexts/physics-context.tsx';
 import { validatePropsWithDefaults, createComponentDefinition, Schema, getNullApplication, applyProps } from './utils/validation.ts';
 import { PublicProps } from './utils/types-utils.ts';
 import { GraphicsDeviceOptions, defaultGraphicsDeviceOptions } from './types/graphics-device-options.ts';
+import { DeviceType, internalCreateGraphicsDevice } from './utils/create-graphics-device.ts';
 
 /**
  * The **Application** component is the root node of the PlayCanvas React API. It creates a canvas element
@@ -47,7 +50,6 @@ export const Application: React.FC<ApplicationProps> = ({
         ref={canvasRef}
       />
 
-
       <ApplicationWithoutCanvas canvasRef={canvasRef} {...props}>
         {children}
       </ApplicationWithoutCanvas>
@@ -98,13 +100,33 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = (prop
     resolutionMode = RESOLUTION_AUTO,
     usePhysics = false,
     graphicsDeviceOptions,
+    deviceTypes = [DEVICETYPE_WEBGL2],
     ...otherProps
   } = validatedProps;
 
-  const localGraphicsDeviceOptions = {
-    ...defaultGraphicsDeviceOptions,
-    ...graphicsDeviceOptions
-  };
+  // Create a deviceTypes key to avoid re-rendering the application when the deviceTypes prop changes.
+  const deviceTypeKey = deviceTypes.join('-');
+
+  /**
+   * Also create a key for the graphicsDeviceOptions object to avoid 
+   * re-rendering the application when the graphicsDeviceOptions prop changes.
+   * We need to sort the keys to create a stable key.
+   */
+  const graphicsOptsKey = useMemo(() => {
+    if (!graphicsDeviceOptions) return 'none';
+    return Object.entries(graphicsDeviceOptions)
+      .sort(([a], [b]) => a.localeCompare(b))   // order-insensitive
+      .map(([k, v]) => `${k}:${String(v)}`)
+      .join('|');
+  }, [graphicsDeviceOptions]);
+
+  /**
+   * Memoize the graphicsDeviceOptions object to avoid re-rendering the application when the graphicsDeviceOptions prop changes.
+   */
+  const graphicsOpts = useMemo(
+    () => ({ ...defaultGraphicsDeviceOptions, ...graphicsDeviceOptions }),
+    [graphicsDeviceOptions]                    // ← only changes when *values* change
+  );
 
   const [app, setApp] = useState<PlayCanvasApplication | null>(null);
   const appRef = useRef<PlayCanvasApplication | null>(null);
@@ -113,28 +135,48 @@ export const ApplicationWithoutCanvas: FC<ApplicationWithoutCanvasProps> = (prop
   usePicker(appRef.current, canvasRef.current, pointerEvents);
 
   useLayoutEffect(() => {
-    const canvas = canvasRef.current;
-    if (canvas && !appRef.current) {
-      const localApp = new PlayCanvasApplication(canvas, {
+
+    // Tracks if the component is unmounted while awaiting for the graphics device to be created
+    let cancelled = false; 
+  
+    (async () => {
+      const canvas = canvasRef.current;
+      if (!canvas || appRef.current) return;
+  
+      // Create the graphics device
+      const dev = await internalCreateGraphicsDevice(canvas, {
+        deviceTypes,
+        ...graphicsOpts
+      });
+  
+      // Check if the component unmounted while we were awaiting, and destroy the device immediately and bail out
+      if (cancelled) {
+        dev.destroy?.();
+        return;
+      }
+  
+      // Proceed with normal PlayCanvas init
+      const pcApp = new PlayCanvasApplication(canvas, {
         mouse: new Mouse(canvas),
         touch: new TouchDevice(canvas),
-        graphicsDevice: process.env.NODE_ENV === 'test' ? new NullGraphicsDevice(canvas) : undefined,
-        graphicsDeviceOptions: localGraphicsDeviceOptions
+        graphicsDevice: dev
       });
-
-      localApp.start();
-
-      appRef.current = localApp;
-      setApp(localApp);
-    }
-
+      pcApp.start();
+  
+      appRef.current = pcApp;
+      setApp(pcApp);
+    })();
+  
+    // Cleanup create a cancellation flag to avoid re-rendering the application when the component is unmounted.
     return () => {
-      if (!appRef.current) return;
-      appRef.current.destroy();
-      appRef.current = null;
-      setApp(null);
+      cancelled = true;
+      if (appRef.current) {
+        appRef.current.destroy();
+        appRef.current = null;
+        setApp(null);
+      }
     };
-  }, [canvasRef, ...Object.values(localGraphicsDeviceOptions)]);
+  }, [graphicsOptsKey, deviceTypeKey]);        // ← stable deps
 
   // Separate useEffect for these props to avoid re-rendering
   useEffect(() => {
@@ -177,7 +219,6 @@ type CanvasProps = {
    */
   style?: Record<string, unknown>
 }
-
 interface ApplicationProps extends Partial<PublicProps<PlayCanvasApplication>>, CanvasProps {
 
   /** 
@@ -197,6 +238,20 @@ interface ApplicationProps extends Partial<PublicProps<PlayCanvasApplication>>,
    * @default false
    */
   usePhysics?: boolean,
+
+  /**
+   * The device types to use for the graphics device. This allows you to set an order of preference for the graphics device.
+   * The first device type in the array that is supported by the browser will be used.
+   * 
+   * @example
+   * <Application deviceTypes={[DEVICETYPE_WEBGPU, DEVICETYPE_WEBGL2]} />
+   * 
+   * This will use the WebGPU device if it is supported, otherwise it will use the WebGL2 device.
+   * 
+   * @default [DEVICETYPE_WEBGL2]
+   */
+  deviceTypes?: DeviceType[],
+
   /** Graphics Settings */
   graphicsDeviceOptions?: GraphicsDeviceOptions,
   /** The children of the application */
@@ -217,6 +272,17 @@ const componentDefinition = createComponentDefinition(
 
 componentDefinition.schema = {
   ...componentDefinition.schema,
+  deviceTypes: {
+    validate: (value: unknown) => Array.isArray(value) && value.every((v: unknown) => typeof v === 'string' && [DEVICETYPE_WEBGPU, DEVICETYPE_WEBGL2, DEVICETYPE_NULL].includes(v as typeof DEVICETYPE_WEBGPU | typeof DEVICETYPE_WEBGL2 | typeof DEVICETYPE_NULL)),
+    errorMsg: (value: unknown) => {
+      return `deviceTypes must be an array containing one or more of: '${DEVICETYPE_WEBGPU}', '${DEVICETYPE_WEBGL2}', '${DEVICETYPE_NULL}'. Received: ['${value}']`
+    },
+    /**
+     * In test environments, we default to a Null device, because we don't cant use WebGL2/WebGPU.
+     * This is just for testing purposes so we can test the fallback logic, without initializing WebGL2/WebGPU.
+     */
+    default: process.env.NODE_ENV === 'test' ? [DEVICETYPE_NULL] : [DEVICETYPE_WEBGL2]
+  },
   className: {
     validate: (value: unknown) => typeof value === 'string',
     errorMsg: (value: unknown) => `className must be a string. Received: ${value}`,

packages/lib/src/Container.test.tsx

@@ -4,10 +4,11 @@ import { Container } from './Container.tsx';
 import { Asset, Entity } from 'playcanvas';
 import { ReactNode } from 'react';
 import { Application } from './Application.tsx';
+import React from 'react';
 
 const renderWithProviders = (ui: ReactNode) => {
     return render(
-      <Application>
+      <Application deviceTypes={["null"]}>
         {ui}
       </Application>
     );

packages/lib/src/Entity.test.tsx

@@ -6,10 +6,11 @@ import { ReactNode, useContext } from 'react';
 import { Entity as PcEntity } from 'playcanvas';
 import { TEST_ENTITY_PROPS } from '../test/constants.ts';
 import { Application } from './Application.tsx';
+import React from 'react';
 
 const renderWithProviders = (ui: ReactNode) => {
   return render(
-    <Application>
+    <Application deviceTypes={["null"]}>
       {ui}
     </Application>
   );

packages/lib/src/components/Screen.test.tsx

@@ -7,7 +7,7 @@ import { Application } from '../Application.tsx';
 
 const renderWithProviders = (ui: React.ReactNode) => {
     return render(
-        <Application>
+        <Application deviceTypes={["null"]}>
             <Entity>
                 {ui}
             </Entity>