# Swappy for OpenGL extras

Extra utility functions to use Swappy with OpenGL.

## Summary

| ### Functions ||
|---|---|
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga9aa019c7c13b089f32853aed43543a26()` | `void` Clears the frame statistics collected so far. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga1191b042d23c0e3d9da59afd94d3c4b9(bool enabled)` | `void` Toggle statistics collection on/off. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1gaeb47f26ddfc9f4309033c275ade33d77(https://developer.android.com/games/sdk/reference/frame-pacing/struct/swappy-stats#struct_swappy_stats *swappyStats)` | `void` Returns the stats collected, if statistics collection was toggled on. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga0889b2c0bcdb70c695aea3b1c243f699(const https://developer.android.com/games/sdk/reference/frame-pacing/struct/swappy-tracer#struct_swappy_tracer *t)` | `void` Pass callbacks to be called each frame to trace execution. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga6b794e82d01b0991bb44cce88ef4d54b(int64_t frameTimeNanos)` | `void` If an app wishes to use the Android choreographer to provide ticks to Swappy, it can call this function. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga553b8bb47d7e4fd5b1ec5ce3e606bb4f(EGLDisplay display, EGLSurface surface)` | `void` Should be called if stats have been enabled with SwappyGL_enableStats. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga3483d0a5de5552f6d274da1ef623cb0e(bool enabled)` | `void` Toggle auto-pipeline mode on/off. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1gab8ab8e5c4005249c5c7e6e7575e90801(bool enabled)` | `void` Toggle auto-swap interval detection on/off. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1gaab7a296634c932e15649dda7567e761b(uint64_t max_swap_ns)` | `void` Sets the maximal duration for auto-swap interval in milliseconds. |
| `https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1gad4c7e569907c6ac2d1809a23999bda3a(const https://developer.android.com/games/sdk/reference/frame-pacing/struct/swappy-tracer#struct_swappy_tracer *t)` | `void` Remove callbacks that were previously added using SwappyGL_injectTracer. |

## Functions

### SwappyGL_clearStats

```scdoc
void SwappyGL_clearStats()
```
Clears the frame statistics collected so far.

All the frame statistics collected are reset to 0, frame statistics are collected normally after this call.

### SwappyGL_enableStats

```scdoc
void SwappyGL_enableStats(
  bool enabled
)
```
Toggle statistics collection on/off.

By default, stats collection is off and there is no overhead related to stats. An app can turn on stats collection by calling `SwappyGL_enableStats(true)`. Then, the app is expected to call [SwappyGL_recordFrameStart](https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga553b8bb47d7e4fd5b1ec5ce3e606bb4f) for each frame before starting to do any CPU related work. Stats will be logged to logcat with a 'FrameStatistics' tag. An app can get the stats by calling [SwappyGL_getStats](https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1gaeb47f26ddfc9f4309033c275ade33d77).

### SwappyGL_getStats

```scdoc
void SwappyGL_getStats(
  SwappyStats *swappyStats
)
```
Returns the stats collected, if statistics collection was toggled on.


**See also:**
[SwappyStats](https://developer.android.com/games/sdk/reference/frame-pacing/struct/swappy-stats#struct_swappy_stats)
**See also:**
[SwappyGL_enableStats](https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga1191b042d23c0e3d9da59afd94d3c4b9)

| Details ||
|---|---|
| Parameters | |---|---| | `swappyStats` | Pointer to a [SwappyStats](https://developer.android.com/games/sdk/reference/frame-pacing/struct/swappy-stats#struct_swappy_stats) that will be populated with collected stats. | |

### SwappyGL_injectTracer

```gdscript
void SwappyGL_injectTracer(
  const SwappyTracer *t
)
```
Pass callbacks to be called each frame to trace execution.

### SwappyGL_onChoreographer

```scdoc
void SwappyGL_onChoreographer(
  int64_t frameTimeNanos
)
```
If an app wishes to use the Android choreographer to provide ticks to Swappy, it can call this function.

This function *must* be called before the first `Swappy_swap()` call. Afterwards, call this function every choreographer tick.

### SwappyGL_recordFrameStart

```scdoc
void SwappyGL_recordFrameStart(
  EGLDisplay display,
  EGLSurface surface
)
```
Should be called if stats have been enabled with SwappyGL_enableStats.

When stats collection is enabled with SwappyGL_enableStats, the app is expected to call this function for each frame before starting to do any CPU related work.

**See also:** [SwappyGL_enableStats](https://developer.android.com/games/sdk/reference/frame-pacing/group/swappy-g-l-extra#group__swappy_g_l__extra_1ga1191b042d23c0e3d9da59afd94d3c4b9).

### SwappyGL_setAutoPipelineMode

```scdoc
void SwappyGL_setAutoPipelineMode(
  bool enabled
)
```
Toggle auto-pipeline mode on/off.

By default, if auto-swap interval is on, auto-pipelining is on and Swappy will try to reduce latency by scheduling cpu and gpu work in the same pipeline stage, if it fits.

### SwappyGL_setAutoSwapInterval

```scdoc
void SwappyGL_setAutoSwapInterval(
  bool enabled
)
```
Toggle auto-swap interval detection on/off.

By default, Swappy will adjust the swap interval based on actual frame rendering time. If an app wants to override the swap interval calculated by Swappy, it can call `SwappyGL_setSwapIntervalNS`. This will temporarily override Swappy's frame timings but, unless `SwappyGL_setAutoSwapInterval(false)` is called, the timings will continue to be be updated dynamically, so the swap interval may change.

### SwappyGL_setMaxAutoSwapIntervalNS

```scdoc
void SwappyGL_setMaxAutoSwapIntervalNS(
  uint64_t max_swap_ns
)
```
Sets the maximal duration for auto-swap interval in milliseconds.

If Swappy is operating in auto-swap interval and the frame duration is longer than `max_swap_ns`, Swappy will not do any pacing and just submit the frame as soon as possible.

### SwappyGL_uninjectTracer

```gdscript
void SwappyGL_uninjectTracer(
  const SwappyTracer *t
)
```
Remove callbacks that were previously added using SwappyGL_injectTracer.