# Native App Glue library

The glue library to interface your game loop with [GameActivity](https://developer.android.com/reference/games/game-activity/struct/game-activity#struct_game_activity).

## Summary

| ### Enumerations ||
|---|---|
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gab1238b3017ceefa7fdfbcc79eee6c289{ https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289abef47f70e30b5c9f77e384924103f4ea, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a0d6fca4488718da1af972b5eb76b4e70, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289ae4454163b5148d7feb2c1398e87f1bd5, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a448514d4220320ec7a7e7324e019f42c, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a1b0e01d7dd6e8ca91e8a51033ca3e59a, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a867d94e17fcae1afb7a1518b7716f3f4, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a185c97bb056e5f4b95ddadecbec20e7e, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a0288cde5cba1809643528f87a08b7652, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a1e522859766d39850cbc3f1c015b632c, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a81f8fd5d321c73ce40ac190c097dfc07, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289af3fe7e75c6650752c617380c1dae3e5a, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289ae74474be4b21cdcde2ef833e6e8cd239, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a90c4a6ced7ede689613ce2b1e0f95d66, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a074614e1c74af041e42a982d85a22fee, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a85fd01d255415043aeb43f552ae1c970, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289af816e28d8f833b5e9597b40ce725974f, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggab1238b3017ceefa7fdfbcc79eee6c289a0bf022a41cfefbf6f5336a986499a99e }` | enumCommands passed from the application's main Java thread to the game's thread. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gad823af8a0d39a5531590f615230a224e{ https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggad823af8a0d39a5531590f615230a224ea66661a2e57566ddd214710ca3494b0b9 = 1, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggad823af8a0d39a5531590f615230a224ea5e50c78fcf09cc1b0ab723f71aa7004a = 2, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ggad823af8a0d39a5531590f615230a224ea9310453935dbed3c38ca54243f8d1114 = 3 }` | enumLooper ID of commands coming from the app's main thread, an AInputQueue or user-defined sources. |

| ### Typedefs ||
|---|---|
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga60f0998490c7b4c161cce4a085ba9812)(const GameActivityKeyEvent *)` | typedef `bool(*` Function pointer declaration for the filtering of key events. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga2ff8350158f837d9eb2e856fc62dd816)(const GameActivityMotionEvent *)` | typedef `bool(*` Function pointer definition for the filtering of motion events. |

| ### Functions ||
|---|---|
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga4545c60e3979515d48bc2865a6da183b(struct https://developer.android.com/reference/games/game-activity/structandroid/input-buffer#structandroid__input__buffer *inputBuffer)` | `void` Clear the array of key events that were waiting to be handled, and release each of them. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga52a157ed8fceabd8d082c6ca7620fb29(struct https://developer.android.com/reference/games/game-activity/structandroid/input-buffer#structandroid__input__buffer *inputBuffer)` | `void` Clear the array of motion events that were waiting to be handled, and release each of them. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gaf0b682de686fba098479227bc5a2f044(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *android_app, int8_t cmd)` | `void` Call with the command returned by [android_app_read_cmd()](https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365) to do the final post-processing of the given command. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga19fcc2ceab1c8d7f0664f9436950bf18(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *android_app, int8_t cmd)` | `void` Call with the command returned by [android_app_read_cmd()](https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365) to do the initial pre-processing of the given command. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *android_app)` | `int8_t` Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next app command message. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga95a27ef920f3bccfa8f3489b7892cce5(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *app, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga60f0998490c7b4c161cce4a085ba9812 filter)` | `void` Set the filter to use when processing key events. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga314992c09107d51f5266fb95e750d470(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *app, https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga2ff8350158f837d9eb2e856fc62dd816 filter)` | `void` Set the filter to use when processing touch and motion events. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gaf34ed0a28a3d137eaad6b04f1c21bd6a(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *android_app)` | `struct https://developer.android.com/reference/games/game-activity/structandroid/input-buffer#structandroid__input__buffer *` Call this before processing input events to get the events buffer. |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gae5bda2e48680274cd2bc04d6b6e27b46(struct https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app *app)` | `void` This is the function that application code must implement, representing the main entry to the app. |

| ### Macros ||
|---|---|
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga55d72dc7a61b7daed8424deaf731c699 4` |   |
| `https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1gabd62bdf165bd1abb482e623e69fc7f61 16` |   |

| ### Structs ||
|---|---|
| [android_app](https://developer.android.com/reference/games/game-activity/structandroid/app) | This is the interface for the standard glue code of a threaded application. |
| [android_input_buffer](https://developer.android.com/reference/games/game-activity/structandroid/input-buffer) |   |
| [android_poll_source](https://developer.android.com/reference/games/game-activity/structandroid/poll-source) | Data associated with an ALooper fd that will be returned as the "outData" when that source has data ready. |

## Enumerations

### NativeAppGlueAppCmd

```text
 NativeAppGlueAppCmd
```
Commands passed from the application's main Java thread to the game's thread.

| Properties ||
|---|---|
| `APP_CMD_CONFIG_CHANGED` | Command from main thread: the current device configuration has changed. |
| `APP_CMD_CONTENT_RECT_CHANGED` | Command from main thread: the content area of the window has changed, such as from the soft input window being shown or hidden. You can find the new content rect in [android_app::contentRect](https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app_1a8502b9a38db281f86421191fba5e82ab). |
| `APP_CMD_DESTROY` | Command from main thread: the app's activity is being destroyed, and waiting for the app thread to clean up and exit before proceeding. |
| `APP_CMD_GAINED_FOCUS` | Command from main thread: the app's activity window has gained input focus. |
| `APP_CMD_INIT_WINDOW` | Command from main thread: a new ANativeWindow is ready for use. Upon receiving this command, android_app-\>window will contain the new window surface. |
| `APP_CMD_LOST_FOCUS` | Command from main thread: the app's activity window has lost input focus. |
| `APP_CMD_LOW_MEMORY` | Command from main thread: the system is running low on memory. Try to reduce your memory use. |
| `APP_CMD_PAUSE` | Command from main thread: the app's activity has been paused. |
| `APP_CMD_RESUME` | Command from main thread: the app's activity has been resumed. |
| `APP_CMD_SAVE_STATE` | Command from main thread: the app should generate a new saved state for itself, to restore from later if needed. If you have saved state, allocate it with malloc and place it in [android_app.savedState](https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app_1a25fd3ec42798fb7cffc243502b35a5e3) with the size in [android_app.savedStateSize](https://developer.android.com/reference/games/game-activity/structandroid/app#structandroid__app_1a2194e58c113f617e474728d15193e4e1). The will be freed for you later. |
| `APP_CMD_START` | Command from main thread: the app's activity has been started. |
| `APP_CMD_STOP` | Command from main thread: the app's activity has been stopped. |
| `APP_CMD_TERM_WINDOW` | Command from main thread: the existing ANativeWindow needs to be terminated. Upon receiving this command, android_app-\>window still contains the existing window; after calling android_app_exec_cmd it will be set to NULL. |
| `APP_CMD_WINDOW_INSETS_CHANGED` | Command from main thread: the app's insets have changed. |
| `APP_CMD_WINDOW_REDRAW_NEEDED` | Command from main thread: the system needs that the current ANativeWindow be redrawn. You should redraw the window before handing this to android_app_exec_cmd() in order to avoid transient drawing glitches. |
| `APP_CMD_WINDOW_RESIZED` | Command from main thread: the current ANativeWindow has been resized. Please redraw with its new size. |
| `UNUSED_APP_CMD_INPUT_CHANGED` | Unused. Reserved for future use when usage of AInputQueue will be supported. |

### NativeAppGlueLooperId

```text
 NativeAppGlueLooperId
```
Looper ID of commands coming from the app's main thread, an AInputQueue or user-defined sources.

| Properties ||
|---|---|
| `LOOPER_ID_INPUT` | Unused. Reserved for future use when usage of AInputQueue will be supported. |
| `LOOPER_ID_MAIN` | Looper data ID of commands coming from the app's main thread, which is returned as an identifier from ALooper_pollOnce(). The data for this identifier is a pointer to an [android_poll_source](https://developer.android.com/reference/games/game-activity/structandroid/poll-source#structandroid__poll__source) structure. These can be retrieved and processed with [android_app_read_cmd()](https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365) and android_app_exec_cmd(). |
| `LOOPER_ID_USER` | Start of user-defined ALooper identifiers. |

## Typedefs

### android_key_event_filter

```gdscript
bool(* android_key_event_filter)(const GameActivityKeyEvent *)
```
Function pointer declaration for the filtering of key events.

A function with this signature should be passed to android_app_set_key_event_filter and return false for any events that should not be handled by android_native_app_glue. These events will be handled by the system instead.

### android_motion_event_filter

```gdscript
bool(* android_motion_event_filter)(const GameActivityMotionEvent *)
```
Function pointer definition for the filtering of motion events.

A function with this signature should be passed to android_app_set_motion_event_filter and return false for any events that should not be handled by android_native_app_glue. These events will be handled by the system instead.

## Functions

### android_app_clear_key_events

```scdoc
void android_app_clear_key_events(
  struct android_input_buffer *inputBuffer
)
```
Clear the array of key events that were waiting to be handled, and release each of them.

This method should be called after you have processed the key up events in your game loop. You should handle events at each iteration of your game loop.

### android_app_clear_motion_events

```scdoc
void android_app_clear_motion_events(
  struct android_input_buffer *inputBuffer
)
```
Clear the array of motion events that were waiting to be handled, and release each of them.

This method should be called after you have processed the motion events in your game loop. You should handle events at each iteration of your game loop.

### android_app_post_exec_cmd

```scdoc
void android_app_post_exec_cmd(
  struct android_app *android_app,
  int8_t cmd
)
```
Call with the command returned by [android_app_read_cmd()](https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365) to do the final post-processing of the given command.

You must have done your own actions for the command before calling this function.

### android_app_pre_exec_cmd

```scdoc
void android_app_pre_exec_cmd(
  struct android_app *android_app,
  int8_t cmd
)
```
Call with the command returned by [android_app_read_cmd()](https://developer.android.com/reference/games/game-activity/group/android-native-app-glue#group__android__native__app__glue_1ga05d3cc727656e360f4d2bb290ceec365) to do the initial pre-processing of the given command.

You can perform your own actions for the command after calling this function.

### android_app_read_cmd

```scdoc
int8_t android_app_read_cmd(
  struct android_app *android_app
)
```
Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next app command message.

### android_app_set_key_event_filter

```scdoc
void android_app_set_key_event_filter(
  struct android_app *app,
  android_key_event_filter filter
)
```
Set the filter to use when processing key events.

Any events for which the filter returns false will be ignored by android_native_app_glue. If filter is set to NULL, no filtering is done.

The default key filter will filter out volume and camera button presses.

### android_app_set_motion_event_filter

```scdoc
void android_app_set_motion_event_filter(
  struct android_app *app,
  android_motion_event_filter filter
)
```
Set the filter to use when processing touch and motion events.

Any events for which the filter returns false will be ignored by android_native_app_glue. If filter is set to NULL, no filtering is done.

Note that the default motion event filter will only allow touchscreen events through, in order to mimic NativeActivity's behaviour, so for controller events to be passed to the app, set the filter to NULL.

### android_app_swap_input_buffers

```scdoc
struct android_input_buffer * android_app_swap_input_buffers(
  struct android_app *android_app
)
```
Call this before processing input events to get the events buffer.

The function returns NULL if there are no events to process.

### android_main

```scdoc
void android_main(
  struct android_app *app
)
```
This is the function that application code must implement, representing the main entry to the app.

## Macros

### NATIVE_APP_GLUE_MAX_NUM_KEY_EVENTS

```scdoc
 NATIVE_APP_GLUE_MAX_NUM_KEY_EVENTS 4
```

### NATIVE_APP_GLUE_MAX_NUM_MOTION_EVENTS

```scdoc
 NATIVE_APP_GLUE_MAX_NUM_MOTION_EVENTS 16
```