# Buoyancy Performance & Optimization

The Buoyancy system in Planetary Oceans calculates wave displacement on the CPU to apply physics forces to floating objects. 

{% hint style="success" %}

#### Asynchronous Computation

CPU FFT calculations run on **background worker threads** using ISPC's (Intel SPMD Program Compiler) parallel task system. They do not block the game thread, so the performance cost shows up as increased **overall CPU usage** rather than frame time spikes. This means:

* Your game thread remains responsive even during FFT computation

However, if your CPU cores are already saturated, additional FFT work can still impact frame rate indirectly through resource contention.
{% endhint %}

This page covers performance considerations and the new **per-cascade CPU compute controls** that allow you to fine-tune buoyancy performance based on your specific needs.

#### Understanding FFT Cascades

Planetary Oceans uses **4 FFT cascades** to represent different wave frequencies:

* **Cascade 0**: Shortest waves (ripples) — \~25m tile size by default
* **Cascade 1**: Medium-short waves — \~28m tile size
* **Cascade 2**: Medium-long waves — \~432m tile size
* **Cascade 3**: Longest waves (swell) — \~2000m tile size

All 4 cascades are combined to create the final ocean surface you see. The GPU always renders all cascades regardless of CPU settings.

#### Per-Cascade CPU Compute Toggle

Starting in version 2.1, you can independently **enable or disable each cascade** for CPU buoyancy calculations. This is found in the **Buoyancy** section of `BP_PlanetaryOcean`:

* `Compute Cascade 0 on CPU` (shortest waves)
* `Compute Cascade 1 on CPU`
* `Compute Cascade 2 on CPU`
* `Compute Cascade 3 on CPU` (longest waves / swell)

**Default**: All cascades enabled (preserves behavior from previous versions)

**How It Works**

When you disable a cascade:

* **GPU rendering continues** — the ocean surface visually displays all wave frequencies
* **CPU buoyancy ignores that cascade** — floating objects don't respond to those wave frequencies
* **Performance improves** — each disabled cascade reduces buoyancy computation cost

{% hint style="info" %}
The visual ocean surface and physical buoyancy are intentionally decoupled. If you disable short-wave cascades (0 and 1), you'll still **see** small ripples on the water, but large ships won't **react** to them — which is physically correct, as large vessels don't respond noticeably to small ripples.
{% endhint %}

#### Performance Benchmarks

Performance was measured with a **256×256 FFT grid** and **AVX2 CPU** (AMD Ryzen 9 5950X) on a typical scene:

| Configuration            | CPU Time | Speedup vs All |
| ------------------------ | -------- | -------------- |
| All 4 cascades (default) | 8.0 ms   | 1.0×           |
| Cascades 2 + 3 only      | 4.0 ms   | 2.0×           |
| Cascade 3 only           | 2.0 ms   | **4.0×**       |

{% hint style="warning" %}
The measured milliseconds represent **worker thread time**, not game thread stalls. On multi-core CPUs, this work happens in parallel with gameplay logic.
{% endhint %}

Each disabled cascade saves approximately **2.0 ms** of CPU time per buoyancy update.

#### Recommended Configurations

Choose cascade settings based on **which cascades make the most impact** on the ocean shape (it depends on your per-cascade parameters) and based on the **size of your floating objects**:

**Large Ships (>20 meters):** Cascade 3 (or 2) only

**Medium Boats (5-20 meters):** Cascades 2 + 3 (or 1 + 2)

**Small Boats and characters (<5 meters)**: Cascades 1 + 2 + 3 (or all 4)

#### Performance Debugging

To monitor buoyancy CPU cost in real-time, enable **Show CPU FFT Performance** in the Buoyancy section of the ocean actor:

```
✓ Show CPU FFT Performance
```

{% hint style="warning" %}
Buoyancy calculations run at the rate specified by `Buoyancy Update Tick Rate` (default: 0.15 seconds). If you need more responsive physics, reduce this value — but remember each update costs the full FFT calculation time.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.planetaryoceans.com/guide-v.-2.1/buoyancy-performance-and-optimization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.