Function createGraphicsDevice

Parameters

• canvas: HTMLCanvasElement

  The canvas element.

• Optionaloptions: {
      alpha?: boolean;
      antialias?: boolean;
      depth?: boolean;
      deviceTypes?: string[];
      displayFormat?: string;
      glslangUrl?: string;
      powerPreference?: "default" | "high-performance" | "low-power";
      stencil?: boolean;
      transientColor?: boolean;
      transientDepth?: boolean;
      twgslUrl?: string;
      xrCompatible?: boolean;
  } = {}

  Graphics device options.

  • Optionalalpha?: boolean

    Boolean that indicates whether the canvas composites with the page behind it. Defaults to true. This is a compositing option rather than a memory one - neither backend has an alpha-less backbuffer format that saves any space. The backends implement it differently:

    • DEVICETYPE_WEBGL2: forwarded as the WebGL alpha context attribute, so the browser decides whether the drawing buffer actually has an alpha channel. When it does not, the device's backBufferFormat becomes PIXELFORMAT_RGB8 rather than PIXELFORMAT_RGBA8, which also changes the format of the scene color grab pass.
    • DEVICETYPE_WEBGPU: selects the canvas alpha mode ('premultiplied' when true, 'opaque' when false). The backbuffer always has an alpha channel, so backBufferFormat is unaffected and 'opaque' simply tells the compositor to ignore the alpha that is already there.

    Compositing is premultiplied on both backends, so a transparent canvas needs a camera CameraComponent#clearColor with both its alpha and its RGB set to zero. A non-zero color with zero alpha is not valid premultiplied data and composites inconsistently across browsers.

    Note that this default applies to this function. The legacy Application constructor instead defaults alpha to false.

  • Optionalantialias?: boolean

    Boolean that indicates whether or not to perform anti-aliasing if possible. Defaults to true.

  • Optionaldepth?: boolean

    Boolean that indicates that the drawing buffer is requested to have a depth buffer of at least 16 bits. Defaults to true.

  • OptionaldeviceTypes?: string[]

    An array of DEVICETYPE_*** constants, defining the order in which the devices are attempted to get created. Defaults to an empty array. If the specified array does not contain DEVICETYPE_WEBGL2, it is internally added to its end. Typically, you'd only specify DEVICETYPE_WEBGPU, or leave it empty. Use DEVICETYPE_WEBGPU_BARE to create a WebGPU device without optional features and with default spec limits, useful for testing on constrained devices.

  • OptionaldisplayFormat?: string

    The display format of the canvas. Defaults to DISPLAYFORMAT_LDR. Can be:

    • DISPLAYFORMAT_LDR
    • DISPLAYFORMAT_LDR_SRGB
    • DISPLAYFORMAT_HDR

  • OptionalglslangUrl?: string

    The URL to the glslang script. Required only if user-defined shaders or shader chunk overrides are specified in GLSL and need to be transpiled to WGSL for use with the DEVICETYPE_WEBGPU device type. This is not required if only the engine's built-in shaders are used, as those are provided directly in WGSL. Not used for DEVICETYPE_WEBGL2 device type creation.

  • OptionalpowerPreference?: "default" | "high-performance" | "low-power"

    A hint indicating what configuration of GPU would be selected. Possible values are:

    • 'default': Let the user agent decide which GPU configuration is most suitable. This is the default value.
    • 'high-performance': Prioritizes rendering performance over power consumption.
    • 'low-power': Prioritizes power saving over rendering performance.

    Defaults to 'default'.

  • Optionalstencil?: boolean

    Boolean that indicates that the drawing buffer is requested to have a stencil buffer of at least 8 bits. Defaults to true.

  • OptionaltransientColor?: boolean

    Boolean that requests the multi-sampled (MSAA) color attachment of the back-buffer to be allocated as a transient ("memoryless") attachment, allowing tile-based GPUs to keep its contents in on-chip memory and avoid VRAM allocation. WebGPU only, and only effective when anti-aliasing (MSAA) is enabled - it has no effect on single-sampled color, which is always presented. Ignored on devices without transient attachment support. Incompatible with a scene color grab pass (sceneColorMap): the attachment must be cleared on load and discarded on store. Defaults to false.

  • OptionaltransientDepth?: boolean

    Boolean that requests the back-buffer depth attachment to be allocated as a transient ("memoryless") attachment (see transientColor). Applies to both single- and multi-sampled depth. WebGPU only; ignored on devices without transient attachment support. Incompatible with a scene depth grab pass (sceneDepthMap), a depth prepass, or any depth resolve, as the depth cannot be sampled or copied out. Defaults to false.

  • OptionaltwgslUrl?: string

    An url to twgsl script, required if glslangUrl was specified.

  • OptionalxrCompatible?: boolean

    Boolean that hints to the user agent to use a compatible graphics adapter for an immersive XR device. When omitted in a browser, defaults to true if navigator.xr is present, otherwise false (see GraphicsDevice constructor).