DOCSEARCHbyAlgolia
Submit Docs

@pmndrs/detect-gpu

repository·master·Indexed 22 days ago

https://github.com/pmndrs/detect-gpu

A utility that classifies GPUs into tiers based on 3D rendering benchmark scores, allowing developers to adjust graphical intensity based on hardware capabilities. It provides the getGPUTier() function to detect GPU models, estimated FPS, and performance tiers, with support for self-hosting benchmark data and custom tier configurations for mobile and desktop devices.

Tokens
1.4K
Snippets
3
Records
8
Agent score
29%

What's inside @pmndrs/detect-gpu

  1. How to use getGPUTier()

    master

    Use getGPUTier() to classify a user's GPU based on 3D rendering benchmarks. This allows you to provide appropriate graphical settings for different hardware capabilities.

    getGPUTier() returns a promise that resolves to a result object containing the assigned tier, whether the device is mobile, the detection type, the measured fps (if applicable), and the GPU name.

    Tier Logic:

    • tier: 0: WebGL is unsupported, the GPU is blocklisted, or performance is < 15 fps.
    • tier: 1: $\ge$ 15 fps
    • tier: 2: $\ge$ 30 fps
    • tier: 3: $\ge$ 60 fps

    Note: Always provide a fallback for tier: 0 to ensure a non-WebGL experience is available.

    import { getGPUTier } from '@pmndrs/detect-gpu';

const gpuTier = await getGPUTier();

// Example output:
// {
//   "tier": 1,
//   "isMobile": false,
//   "type": "BENCHMARK",
//   "fps": 21,
//   "gpu": "intel iris graphics 6100"
// }

  3. Self-hosting benchmark data

    master

    By default, benchmark data is loaded from the UNPKG CDN. To serve the data yourself (for offline environments, strict CSP, or to avoid third-party CDNs):

    1. Download benchmarks.tar.gz.
    2. Extract it into a publicly served directory (e.g., public/benchmarks/).
    3. Pass the directory URL to getGPUTier using the benchmarksURL option.

    Note: The directory must be served at the exact URL passed; the library appends filenames like /benchmarks-d-*.json to the provided path.

    const gpuTier = await getGPUTier({
  benchmarksURL: '/benchmarks',
});

  4. Understand TierType classification results

    master

    The type field in the TierResult object indicates how the GPU was identified or why a specific tier was assigned:

    • SSR: The code is running in a Server-Side Rendering environment.
    • WEBGL_UNSUPPORTED: WebGL is not available in the current environment.
    • BLOCKLISTED: The GPU is explicitly blocklisted (often due to known bugs or extremely poor performance).
    • FALLBACK: The GPU could not be matched against benchmark data, so a generic fallback tier is provided.
    • BENCHMARK: The GPU was successfully matched against benchmark data.
    • BENCHMARK_FETCH_FAILED: The benchmark data could not be fetched (e.g., due to network issues, CORS, or CSP restrictions).

  5. Configure getGPUTier options

    master

    The getGPUTier function accepts an options object to customize detection behavior:

    • benchmarksURL (string): URL of directory where benchmark data is hosted. Defaults to UNPKG CDN.
    • glContext (WebGLRenderingContext | WebGL2RenderingContext): Optionally pass an existing WebGL context to avoid creating a temporary one internally.
    • failIfMajorPerformanceCaveat (boolean): Whether to fail if the system performance is low or if no hardware GPU is available. Defaults to false.
    • mobileTiers (number[]): Framerate per tier for mobile devices. Defaults to [0, 15, 30, 60].
    • desktopTiers (number[]): Framerate per tier for desktop devices. Defaults to [0, 15, 30, 60].
    • override (object): Used mainly for testing to override renderer, isIpad, isMobile, screenSize, or loadBenchmarks function.

  6. Understand getGPUTier result types

    master

    The type field in the returned object indicates how the GPU was classified. This is useful for determining if the result is a reliable benchmark or a fallback.

    typeMeaning
    BENCHMARKMatched a benchmark entry; fps reflects the measured framerate for that GPU.
    FALLBACKRenderer recognised but no benchmark match found. tier is a conservative default.
    BENCHMARK_FETCH_FAILEDBenchmark fetch failed (CDN outage, strict CSP, offline, etc.). Safe to retry.
    BLOCKLISTEDRenderer is on a known-bad list (drivers with severe issues). tier is always 0.
    WEBGL_UNSUPPORTEDNo WebGL context could be created. tier is always 0.
    SSRRunning server-side — no window, detection skipped.

    Note: The fps field is only populated for BENCHMARK results.

  7. Get GPU tier classification with getGPUTier()

    master

    Use the getGPUTier function to asynchronously detect the hardware capabilities of the user's GPU. It classifies the device into a tier (based on performance) and a type (representing the detection method or status).

    By default, it fetches benchmark data from a remote CDN to provide accurate FPS and model information. If the environment is SSR (Server-Side Rendering), it returns an SSR type. If WebGL is unavailable, it returns WEBGL_UNSUPPORTED. If the GPU is known to be low-performance or blocklisted, it returns BLOCKLISTED or FALLBACK types.

    Common use cases include adjusting graphics settings, enabling/disabling high-fidelity features, or providing warnings when hardware is insufficient.

  8. Reference the TierResult data structure

    master

    The getGPUTier function returns a TierResult object containing the following fields:

    FieldTypeDescription
    tiernumberThe calculated performance tier based on the provided tiers array.
    typeTierTypeThe classification type (e.g., BENCHMARK, FALLBACK, SSR).
    isMobileboolean (optional)Whether the device is identified as mobile.
    fpsnumber (optional)The estimated frames per second from benchmark data.
    gpustring (optional)The name of the detected GPU model.
    devicestring (optional)The name of the device associated with the benchmark.