DeviceError

Description

A GPU error that an error scope caught. Renderer::render returns one when a pipeline fails to build or a frame’s commands fail, in place of drawing nothing without a word.

It holds three values, under the same names in every language:

• kind, an ErrorKind: Validation, Internal or Memory.
• label, the step that raised it: render pipeline, compute pipeline, light binning pipeline or frame, and in Rust, Python, Swift and Kotlin also a bind group or texture view inside the frame.
• detail, the device’s own words about what went wrong.

Each language raises it in its own form:

• Rust returns RendererError::DeviceError { kind, label, detail }. On the web a readback, such as get_image, returns TextureError::DeviceError with the same fields.
• JavaScript throws an Error named DeviceError, with kind, label and detail properties.
• Python raises DeviceError, a FragmentColorError, with kind, label and detail attributes.
• Swift throws FragmentColorError.Device(kind:label:detail:).
• Kotlin throws FragmentColorException.Device(kind, label, detail).

Each language’s own text for the error carries all three, as Device error (validation) in 'frame': ...: Error.message in JavaScript, str(e) in Python, localizedDescription and description in Swift, and toString() in Kotlin. Kotlin’s Throwable.message lists the fields instead, as kind=VALIDATION, label=frame, detail=....

On the web the GPU reports an error after render has returned, so the next call throws it, as Renderer::render describes.

Example

Rust

use fragmentcolor::{Renderer, Shader};

let renderer = Renderer::new();
let target = renderer.create_texture_target([16, 16]).await?;
let shader = Shader::default();

// A GPU error in this frame returns as a DeviceError.
renderer.render(&shader, &target)?;

JavaScript

import { Renderer, Shader } from "fragmentcolor";

const renderer = new Renderer();
const target = await renderer.createTextureTarget([16, 16]);
const shader = Shader.default();

// A GPU error in this frame returns as a DeviceError.
renderer.render(shader, target);

Python

from fragmentcolor import Renderer, Shader

renderer = Renderer()
target = renderer.create_texture_target([16, 16])
shader = Shader.default()

# A GPU error in this frame returns as a DeviceError.
renderer.render(shader, target)

Swift

import FragmentColor

let renderer = Renderer()
let target = try await renderer.createTextureTarget([16, 16])
let shader = Shader.default()

// A GPU error in this frame returns as a DeviceError.
try renderer.render(shader, target)

Kotlin

import org.fragmentcolor.*

val renderer = Renderer()
val target = renderer.createTextureTarget(listOf(16u, 16u))
val shader = Shader.default()

// A GPU error in this frame returns as a DeviceError.
renderer.render(shader, target)