Native App Glue library

The glue library to interface your game loop with GameActivity.

Summary

Enumerations
NativeAppGlueAppCmd{
  UNUSED_APP_CMD_INPUT_CHANGED,
  APP_CMD_INIT_WINDOW,
  APP_CMD_TERM_WINDOW,
  APP_CMD_WINDOW_RESIZED,
  APP_CMD_WINDOW_REDRAW_NEEDED,
  APP_CMD_CONTENT_RECT_CHANGED,
  APP_CMD_GAINED_FOCUS,
  APP_CMD_LOST_FOCUS,
  APP_CMD_CONFIG_CHANGED,
  APP_CMD_LOW_MEMORY,
  APP_CMD_START,
  APP_CMD_RESUME,
  APP_CMD_SAVE_STATE,
  APP_CMD_PAUSE,
  APP_CMD_STOP,
  APP_CMD_DESTROY,
  APP_CMD_WINDOW_INSETS_CHANGED
} 		enum
Commands passed from the application's main Java thread to the game's thread.
NativeAppGlueLooperId{
  LOOPER_ID_MAIN = 1,
  LOOPER_ID_INPUT = 2,
  LOOPER_ID_USER = 3
} 		enum
Looper ID of commands coming from the app's main thread, an AInputQueue or user-defined sources.

Typedefs
android_key_event_filter)(const GameActivityKeyEvent *) typedef
bool(*
Function pointer declaration for the filtering of key events.
android_motion_event_filter)(const GameActivityMotionEvent *) typedef
bool(*
Function pointer definition for the filtering of motion events.

Functions
android_app_clear_key_events(struct android_input_buffer *inputBuffer)
void
Clear the array of key events that were waiting to be handled, and release each of them.
android_app_clear_motion_events(struct android_input_buffer *inputBuffer)
void
Clear the array of motion events that were waiting to be handled, and release each of them.
android_app_post_exec_cmd(struct android_app *android_app, int8_t cmd)
void
Call with the command returned by android_app_read_cmd() to do the final post-processing of the given command.
android_app_pre_exec_cmd(struct android_app *android_app, int8_t cmd)
void
Call with the command returned by android_app_read_cmd() to do the initial pre-processing of the given command.
android_app_read_cmd(struct android_app *android_app)
int8_t
Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next app command message.
android_app_set_key_event_filter(struct android_app *app, android_key_event_filter filter)
void
Set the filter to use when processing key events.
android_app_set_motion_event_filter(struct android_app *app, android_motion_event_filter filter)
void
Set the filter to use when processing touch and motion events.
android_app_swap_input_buffers(struct android_app *android_app)
Call this before processing input events to get the events buffer.
android_main(struct android_app *app)
void
This is the function that application code must implement, representing the main entry to the app.

Macros
NATIVE_APP_GLUE_MAX_NUM_KEY_EVENTS 4
NATIVE_APP_GLUE_MAX_NUM_MOTION_EVENTS 16

Structs
android_app

This is the interface for the standard glue code of a threaded application.

android_input_buffer
android_poll_source

Data associated with an ALooper fd that will be returned as the "outData" when that source has data ready.

Enumerations

NativeAppGlueAppCmd

 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.

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 with the size in android_app.savedStateSize. 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

 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 structure. These can be retrieved and processed with android_app_read_cmd() and android_app_exec_cmd().

LOOPER_ID_USER

Start of user-defined ALooper identifiers.

Typedefs

android_key_event_filter

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

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

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

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

void android_app_post_exec_cmd(
  struct android_app *android_app,
  int8_t cmd
)

Call with the command returned by android_app_read_cmd() 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

void android_app_pre_exec_cmd(
  struct android_app *android_app,
  int8_t cmd
)

Call with the command returned by android_app_read_cmd() 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

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

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

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

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

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

 NATIVE_APP_GLUE_MAX_NUM_KEY_EVENTS 4

NATIVE_APP_GLUE_MAX_NUM_MOTION_EVENTS

 NATIVE_APP_GLUE_MAX_NUM_MOTION_EVENTS 16