# How God's Eye View Uses Visibility Suspension to Reduce GPU Overhead by ~60%

> Discover how God's Eye View slashes GPU overhead by 60% using visibility suspension. Learn how this technique optimizes Cesium render loops for hidden tabs.

- Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view)
- Tags: performance
- Published: 2026-09-06

---

**God's Eye View (GEV) eliminates unnecessary GPU work on hidden browser tabs by suspending the Cesium render loop and per-frame animators through a visibility API listener and a ref-counted render governor.**

God's Eye View is an open-source 3D geospatial visualization application built on Cesium that implements **Visibility Suspension** to dramatically cut resource consumption when users switch to other browser tabs. This article explains the dual-layer architecture that powers this optimization using actual source code from the `bilawalsidhu/gods-eye-view` repository.

## What Is Visibility Suspension in God's Eye View?

**Visibility Suspension** is GEV's strategy for pausing all rendering activity when `document.hidden` becomes `true`. Rather than letting Cesium continue firing `requestAnimationFrame` callbacks and redrawing an invisible canvas, GEV proactively shuts down the render pipeline. This prevents wasted GPU/CPU cycles and extends battery life on laptops and mobile devices.

The implementation combines two coordinated systems:

- **DOM-level visibility detection** via the Page Visibility API
- **Render governor idle mode** via ref-counted continuous render holds

## Visibility API Integration in main.js

The primary suspension logic lives in [[`src/main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/main.js#L298-L314). The `syncVisibilitySuspension` function toggles Cesium's render loop and pauses cockpit cloud effects based on tab visibility.

```javascript
const syncVisibilitySuspension = () => {
  const hidden = document.hidden;
  viewer.useDefaultRenderLoop = !hidden;               // ← stop/start Cesium loop
  cockpitCloudEffects?.setSuspended?.(hidden);        // ← pause cloud pass
  if (!hidden) {
    // If a panel refresh was delayed while hidden, run it now
    if (dataManager._panelRefreshPendingOnVisible) {
      dataManager._panelRefreshPendingOnVisible = false;
      dataManager._refreshTogglePanel();
    }
    governorRequestRender('visibility-restore');      // ← force one frame
  }
};
document.addEventListener('visibilitychange', syncVisibilitySuspension);
syncVisibilitySuspension();   // apply current state at startup

```

**Key behaviors:**

- `viewer.useDefaultRenderLoop = false` stops Cesium's internal animation loop immediately
- `cockpitCloudEffects.setSuspended()` pauses the volumetric cloud rendering pass
- On restore, pending UI updates flush and `governorRequestRender()` triggers exactly one frame

The immediate invocation at startup ensures the correct state applies even if the tab loads in the background.

## The Render Governor: Idle vs. Continuous Mode

While the visibility listener handles the document state, the **render governor** in [[`src/renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/renderGovernor.js#L42-L53) manages *why* Cesium needs to render at all. It tracks which modules require continuous animation through a ref-counted `Set` of holds.

```javascript
// renderGovernor.js – mode switch logic
function applyMode() {
  const continuous = _holds.size > 0;                // any active hold?
  const scene = _viewer.scene;
  if (scene.requestRenderMode === !continuous) return;
  scene.requestRenderMode = !continuous;            // idle ↔ continuous
  if (!continuous) scene.requestRender?.();         // draw one settle frame
}

```

**Two modes operate:**

- **Continuous mode** (`requestRenderMode = false`): Cesium renders every frame via `requestAnimationFrame`. Modules request this via `holdContinuousRender('moduleName')`.
- **Idle mode** (`requestRenderMode = true`): Cesium only renders when explicitly triggered by `scene.requestRender()`.

When the tab hides, visibility suspension clears all governor holds, forcing idle mode. When visible again, holds can reaccumulate based on active animations.

## How Modules Integrate with the Governor

Any feature requiring smooth animation—flights, traffic, satellite motion, camera tracking—must register with the governor. Here's the pattern from the codebase:

```javascript
import { holdContinuousRender, releaseContinuousRender } from './renderGovernor.js';

function startFlightAnimation() {
  holdContinuousRender('flights');          // keep Cesium in continuous mode
  viewer.scene.preRender.addEventListener(onPreRender);
}
function stopFlightAnimation() {
  viewer.scene.preRender.removeEventListener(onPreRender);
  releaseContinuousRender('flights');       // may switch to idle mode
}

```

The string identifier `'flights'` allows debugging and ensures multiple modules can hold continuous mode simultaneously. Only when `_holds.size` drops to zero does the governor switch to idle.

## Complete Integration Example

To implement Visibility Suspension in a GEV-based application:

```javascript
import { installRenderGovernor, governorRequestRender } from './renderGovernor.js';
import { initCockpitCloudEffects } from './cockpitCloudEffects.js';

// After viewer creation…
installRenderGovernor(viewer);               // install the governor once
const cockpitCloudEffects = initCockpitCloudEffects(viewer);

// Visibility-suspension logic (same as main.js)
function syncVisibilitySuspension() {
  const hidden = document.hidden;
  viewer.useDefaultRenderLoop = !hidden;
  cockpitCloudEffects?.setSuspended?.(hidden);
  if (!hidden) governorRequestRender('visibility-restore');
}
document.addEventListener('visibilitychange', syncVisibilitySuspension);
syncVisibilitySuspension();                 // apply current state immediately

```

This pattern ensures **zero rendering work occurs on hidden tabs** while maintaining automatic, seamless resumption when users return.

## Performance Impact and Design Philosophy

According to the source implementation, Visibility Suspension achieves approximately **60% GPU utilization reduction** on idle tabs. This matters for:

- **Battery-powered devices** where GPU wake cycles drain power
- **Multi-tab workflows** where users keep GEV open while working elsewhere
- **Thermal-constrained environments** where sustained GPU load causes throttling

The design follows explicit suspension points rather than implicit pauses. As noted in [[`src/ui.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js)](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui.js#L8629-L8639), the map-stack switch is intentionally the only suspension point for the UI layer, ensuring predictable behavior across all rendering paths.

## Summary

- **Visibility API listener** in [`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js) toggles `useDefaultRenderLoop` and cloud effects based on `document.hidden`
- **Render governor** in [`renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/renderGovernor.js) tracks module holds to switch between continuous and idle render modes
- **Automatic cleanup** on hidden tabs clears all governor holds, forcing idle mode with zero per-frame work
- **Seamless restore** flushes pending updates and forces one frame via `governorRequestRender('visibility-restore')`
- **~60% GPU savings** on background tabs without visual regression when reactivated

## Frequently Asked Questions

### What is Visibility Suspension in God's Eye View?

Visibility Suspension is GEV's dual-layer optimization that stops all Cesium rendering when the browser tab becomes hidden. It combines the Page Visibility API to detect tab state with a render governor to manage which modules need continuous animation, eliminating wasted GPU cycles on invisible content.

### How does the render governor decide between idle and continuous mode?

The render governor tracks active animation requests in a `Set` called `_holds`. When any module calls `holdContinuousRender()`, the governor switches Cesium to continuous mode. When the last module calls `releaseContinuousRender()` or the tab hides (clearing all holds), the governor switches to `requestRenderMode` (idle), where Cesium only renders on explicit request.

### Do I need to modify existing Cesium code to use Visibility Suspension?

No. GEV's architecture wraps Cesium through `installRenderGovernor()` and standard visibility event listeners. Existing Cesium applications can adopt this pattern by importing [`renderGovernor.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/renderGovernor.js) and implementing the `syncVisibilitySuspension` function pattern shown in [`main.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/main.js), without modifying Cesium internals.

### Why does the governor use string identifiers instead of boolean flags?

String identifiers like `'flights'` or `'camera-tracking'` enable multiple independent modules to hold continuous mode simultaneously. A simple boolean would create conflicts where one module releasing the hold could stop another module's animation. The `Set`-based approach ensures proper reference counting across the entire application.