1. Knowledge base
2. renderer

Constrained GPU Mode

Large venues with high-resolution background images can exhaust GPU memory on mobile devices, causing the browser tab to crash. The renderer now auto-detects device capabilities at initialization and adapts its rendering strategy. On constrained devices, a two-layer texture system replaces the full-resolution background upload, keeping GPU memory usage within safe limits while preserving visual quality when the user zooms in.

No code changes are required in host applications – the optimization is automatic and transparent.

How detection works

At renderer initialization, a GPU micro-benchmark runs to classify the device into one of two tiers:

The detection uses a three-layer heuristic, evaluated in order:

1. Screen-based (fastest): Devices with DPR >= 3 or total screen pixels > 8 million are classified as constrained
2. WebGL-based: Devices reporting max texture size <= 8192 are classified as constrained
3. Benchmark-based: A 512x512 RGBA texture is uploaded to the GPU 10 times; devices scoring above 30ms total are classified as constrained

If none of the checks trigger, the device is classified as high.

What changes in constrained mode

Two-layer texture system

In constrained mode, the renderer maintains two texture layers:

Layer 1 – Preview (permanent): A pre-compressed preview image (~1000px wide) stays in GPU memory at all times. This provides the full-venue view when zoomed out.

Layer 2 – Detail (on-demand): When the user zooms into a section past a computed threshold, a high-resolution crop of the visible area is generated and uploaded to the GPU. The crop is capped to 2048px on its longest side and includes a 30% margin around the viewport to reduce re-crops during small pan movements.

The detail texture is automatically disposed when the user zooms back out below the threshold, freeing GPU memory. A generation counter prevents stale crops from being applied during rapid zoom changes.

Configuration

The GPU tier is resolved in this priority order:

1. Auto-detect (default)

No configuration needed. The renderer runs the micro-benchmark and classifies the device automatically.

const renderer = new SeatmapBookingRenderer(container, {
  publicKey: 'your-public-key',
  // gpuTier not set -- auto-detected
});

2. Settings override

Force a specific tier via the gpuTier setting. Useful for kiosk deployments or when you know the target device fleet.

const renderer = new SeatmapBookingRenderer(container, {
  publicKey: 'your-public-key',
  gpuTier: 'constrained',  // or 'high'
});

3. URL parameter

Override via query string for testing or per-device overrides in iframe embeds:

https://your-site.com/venue/123?gpuTier=constrained

When to force constrained mode

Auto-detection works well for most scenarios. Consider forcing gpuTier: 'constrained' when:

• Kiosk / digital signage: Known hardware with limited GPU memory
• Low-end device fleet: Mobile ticket scanners or point-of-sale tablets
• User-reported crashes: A quick mitigation while investigating the root cause
• Testing: Verify the constrained path works correctly on a desktop machine

Debug output

Enable debug: true in renderer settings to see GPU detection details in the browser console:

[seatmap] GPU tier: constrained (DPR=3, screen=8.5M px, maxCanvas=2048, source=auto)
[seatmap] GPU: Apple A15 (maxTex=4096, mem=6GB, bench=45ms)

The source field shows where the tier decision came from: settings (explicit override), url (query parameter), or auto (micro-benchmark result).

Background image load events include the texture type and timing:

[seatmap] Background loaded: type=detail-crop, 1024x768, 3.0MB GPU, 87ms

Benchmark reference

Typical micro-benchmark scores for reference:

The 30ms threshold was chosen based on empirical testing across devices. Devices near the threshold may vary between sessions – this is expected and both tiers provide correct rendering.