/*************************************************************************/ /* android_native_app_glue.h */ /*************************************************************************/ /* This file is part of: */ /* GODOT ENGINE */ /* http://www.godotengine.org */ /*************************************************************************/ /* Copyright (c) 2007-2015 Juan Linietsky, Ariel Manzur. */ /* */ /* Permission is hereby granted, free of charge, to any person obtaining */ /* a copy of this software and associated documentation files (the */ /* "Software"), to deal in the Software without restriction, including */ /* without limitation the rights to use, copy, modify, merge, publish, */ /* distribute, sublicense, and/or sell copies of the Software, and to */ /* permit persons to whom the Software is furnished to do so, subject to */ /* the following conditions: */ /* */ /* The above copyright notice and this permission notice shall be */ /* included in all copies or substantial portions of the Software. */ /* */ /* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */ /* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */ /* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.*/ /* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */ /* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */ /* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */ /* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ /*************************************************************************/ * Copyright (C) 2010 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. * */ #ifndef _ANDROID_NATIVE_APP_GLUE_H #define _ANDROID_NATIVE_APP_GLUE_H #ifdef ANDROID_NATIVE_ACTIVITY #include #include #include #include #include #include #ifdef __cplusplus extern "C" { #endif /** * The native activity interface provided by * is based on a set of application-provided callbacks that will be called * by the Activity's main thread when certain events occur. * * This means that each one of this callbacks _should_ _not_ block, or they * risk having the system force-close the application. This programming * model is direct, lightweight, but constraining. * * The 'threaded_native_app' static library is used to provide a different * execution model where the application can implement its own main event * loop in a different thread instead. Here's how it works: * * 1/ The application must provide a function named "android_main()" that * will be called when the activity is created, in a new thread that is * distinct from the activity's main thread. * * 2/ android_main() receives a pointer to a valid "android_app" structure * that contains references to other important objects, e.g. the * ANativeActivity obejct instance the application is running in. * * 3/ the "android_app" object holds an ALooper instance that already * listens to two important things: * * - activity lifecycle events (e.g. "pause", "resume"). See APP_CMD_XXX * declarations below. * * - input events coming from the AInputQueue attached to the activity. * * Each of these correspond to an ALooper identifier returned by * ALooper_pollOnce with values of LOOPER_ID_MAIN and LOOPER_ID_INPUT, * respectively. * * Your application can use the same ALooper to listen to additional * file-descriptors. They can either be callback based, or with return * identifiers starting with LOOPER_ID_USER. * * 4/ Whenever you receive a LOOPER_ID_MAIN or LOOPER_ID_INPUT event, * the returned data will point to an android_poll_source structure. You * can call the process() function on it, and fill in android_app->onAppCmd * and android_app->onInputEvent to be called for your own processing * of the event. * * Alternatively, you can call the low-level functions to read and process * the data directly... look at the process_cmd() and process_input() * implementations in the glue to see how to do this. * * See the sample named "native-activity" that comes with the NDK with a * full usage example. Also look at the JavaDoc of NativeActivity. */ struct android_app; /** * Data associated with an ALooper fd that will be returned as the "outData" * when that source has data ready. */ struct android_poll_source { // The identifier of this source. May be LOOPER_ID_MAIN or // LOOPER_ID_INPUT. int32_t id; // The android_app this ident is associated with. struct android_app* app; // Function to call to perform the standard processing of data from // this source. void (*process)(struct android_app* app, struct android_poll_source* source); }; /** * This is the interface for the standard glue code of a threaded * application. In this model, the application's code is running * in its own thread separate from the main thread of the process. * It is not required that this thread be associated with the Java * VM, although it will need to be in order to make JNI calls any * Java objects. */ struct android_app { // The application can place a pointer to its own state object // here if it likes. void* userData; // Fill this in with the function to process main app commands (APP_CMD_*) void (*onAppCmd)(struct android_app* app, int32_t cmd); // Fill this in with the function to process input events. At this point // the event has already been pre-dispatched, and it will be finished upon // return. Return 1 if you have handled the event, 0 for any default // dispatching. int32_t (*onInputEvent)(struct android_app* app, AInputEvent* event); // The ANativeActivity object instance that this app is running in. ANativeActivity* activity; // The current configuration the app is running in. AConfiguration* config; // This is the last instance's saved state, as provided at creation time. // It is NULL if there was no state. You can use this as you need; the // memory will remain around until you call android_app_exec_cmd() for // APP_CMD_RESUME, at which point it will be freed and savedState set to NULL. // These variables should only be changed when processing a APP_CMD_SAVE_STATE, // at which point they will be initialized to NULL and you can malloc your // state and place the information here. In that case the memory will be // freed for you later. void* savedState; size_t savedStateSize; // The ALooper associated with the app's thread. ALooper* looper; // When non-NULL, this is the input queue from which the app will // receive user input events. AInputQueue* inputQueue; // When non-NULL, this is the window surface that the app can draw in. ANativeWindow* window; // Current content rectangle of the window; this is the area where the // window's content should be placed to be seen by the user. ARect contentRect; // Current state of the app's activity. May be either APP_CMD_START, // APP_CMD_RESUME, APP_CMD_PAUSE, or APP_CMD_STOP; see below. int activityState; // This is non-zero when the application's NativeActivity is being // destroyed and waiting for the app thread to complete. int destroyRequested; // ------------------------------------------------- // Below are "private" implementation of the glue code. pthread_mutex_t mutex; pthread_cond_t cond; int msgread; int msgwrite; pthread_t thread; struct android_poll_source cmdPollSource; struct android_poll_source inputPollSource; int running; int stateSaved; int destroyed; int redrawNeeded; AInputQueue* pendingInputQueue; ANativeWindow* pendingWindow; ARect pendingContentRect; }; enum { /** * 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_MAIN = 1, /** * Looper data ID of events coming from the AInputQueue of the * application's window, 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 read via the inputQueue * object of android_app. */ LOOPER_ID_INPUT = 2, /** * Start of user-defined ALooper identifiers. */ LOOPER_ID_USER = 3, }; enum { /** * Command from main thread: the AInputQueue has changed. Upon processing * this command, android_app->inputQueue will be updated to the new queue * (or NULL). */ APP_CMD_INPUT_CHANGED, /** * 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_INIT_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_TERM_WINDOW, /** * Command from main thread: the current ANativeWindow has been resized. * Please redraw with its new size. */ APP_CMD_WINDOW_RESIZED, /** * 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_REDRAW_NEEDED, /** * 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_CONTENT_RECT_CHANGED, /** * Command from main thread: the app's activity window has gained * input focus. */ APP_CMD_GAINED_FOCUS, /** * Command from main thread: the app's activity window has lost * input focus. */ APP_CMD_LOST_FOCUS, /** * Command from main thread: the current device configuration has changed. */ APP_CMD_CONFIG_CHANGED, /** * Command from main thread: the system is running low on memory. * Try to reduce your memory use. */ APP_CMD_LOW_MEMORY, /** * Command from main thread: the app's activity has been started. */ APP_CMD_START, /** * Command from main thread: the app's activity has been resumed. */ APP_CMD_RESUME, /** * 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_SAVE_STATE, /** * Command from main thread: the app's activity has been paused. */ APP_CMD_PAUSE, /** * Command from main thread: the app's activity has been stopped. */ APP_CMD_STOP, /** * 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_DESTROY, }; /** * Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next * app command message. */ int8_t android_app_read_cmd(struct android_app* android_app); /** * 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. */ 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 * final post-processing of the given command. You must have done your own * actions for the command before calling this function. */ void android_app_post_exec_cmd(struct android_app* android_app, int8_t cmd); /** * Dummy function you can call to ensure glue code isn't stripped. */ void app_dummy(); /** * This is the function that application code must implement, representing * the main entry to the app. */ extern void android_main(struct android_app* app); #ifdef __cplusplus } #endif #endif /* _ANDROID_NATIVE_APP_GLUE_H */ #endif