1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/src/android/android_native_app_glue.h	Sat Oct 03 06:10:30 2015 +0300
     1.3 @@ -0,0 +1,349 @@
     1.4 +/*
     1.5 + * Copyright (C) 2010 The Android Open Source Project
     1.6 + *
     1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.8 + * you may not use this file except in compliance with the License.
     1.9 + * You may obtain a copy of the License at
    1.10 + *
    1.11 + *      http://www.apache.org/licenses/LICENSE-2.0
    1.12 + *
    1.13 + * Unless required by applicable law or agreed to in writing, software
    1.14 + * distributed under the License is distributed on an "AS IS" BASIS,
    1.15 + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    1.16 + * See the License for the specific language governing permissions and
    1.17 + * limitations under the License.
    1.18 + *
    1.19 + */
    1.20 +
    1.21 +#ifndef _ANDROID_NATIVE_APP_GLUE_H
    1.22 +#define _ANDROID_NATIVE_APP_GLUE_H
    1.23 +
    1.24 +#include <poll.h>
    1.25 +#include <pthread.h>
    1.26 +#include <sched.h>
    1.27 +
    1.28 +#include <android/configuration.h>
    1.29 +#include <android/looper.h>
    1.30 +#include <android/native_activity.h>
    1.31 +
    1.32 +#ifdef __cplusplus
    1.33 +extern "C" {
    1.34 +#endif
    1.35 +
    1.36 +/**
    1.37 + * The native activity interface provided by <android/native_activity.h>
    1.38 + * is based on a set of application-provided callbacks that will be called
    1.39 + * by the Activity's main thread when certain events occur.
    1.40 + *
    1.41 + * This means that each one of this callbacks _should_ _not_ block, or they
    1.42 + * risk having the system force-close the application. This programming
    1.43 + * model is direct, lightweight, but constraining.
    1.44 + *
    1.45 + * The 'android_native_app_glue' static library is used to provide a different
    1.46 + * execution model where the application can implement its own main event
    1.47 + * loop in a different thread instead. Here's how it works:
    1.48 + *
    1.49 + * 1/ The application must provide a function named "android_main()" that
    1.50 + *    will be called when the activity is created, in a new thread that is
    1.51 + *    distinct from the activity's main thread.
    1.52 + *
    1.53 + * 2/ android_main() receives a pointer to a valid "android_app" structure
    1.54 + *    that contains references to other important objects, e.g. the
    1.55 + *    ANativeActivity obejct instance the application is running in.
    1.56 + *
    1.57 + * 3/ the "android_app" object holds an ALooper instance that already
    1.58 + *    listens to two important things:
    1.59 + *
    1.60 + *      - activity lifecycle events (e.g. "pause", "resume"). See APP_CMD_XXX
    1.61 + *        declarations below.
    1.62 + *
    1.63 + *      - input events coming from the AInputQueue attached to the activity.
    1.64 + *
    1.65 + *    Each of these correspond to an ALooper identifier returned by
    1.66 + *    ALooper_pollOnce with values of LOOPER_ID_MAIN and LOOPER_ID_INPUT,
    1.67 + *    respectively.
    1.68 + *
    1.69 + *    Your application can use the same ALooper to listen to additional
    1.70 + *    file-descriptors.  They can either be callback based, or with return
    1.71 + *    identifiers starting with LOOPER_ID_USER.
    1.72 + *
    1.73 + * 4/ Whenever you receive a LOOPER_ID_MAIN or LOOPER_ID_INPUT event,
    1.74 + *    the returned data will point to an android_poll_source structure.  You
    1.75 + *    can call the process() function on it, and fill in android_app->onAppCmd
    1.76 + *    and android_app->onInputEvent to be called for your own processing
    1.77 + *    of the event.
    1.78 + *
    1.79 + *    Alternatively, you can call the low-level functions to read and process
    1.80 + *    the data directly...  look at the process_cmd() and process_input()
    1.81 + *    implementations in the glue to see how to do this.
    1.82 + *
    1.83 + * See the sample named "native-activity" that comes with the NDK with a
    1.84 + * full usage example.  Also look at the JavaDoc of NativeActivity.
    1.85 + */
    1.86 +
    1.87 +struct android_app;
    1.88 +
    1.89 +/**
    1.90 + * Data associated with an ALooper fd that will be returned as the "outData"
    1.91 + * when that source has data ready.
    1.92 + */
    1.93 +struct android_poll_source {
    1.94 +    // The identifier of this source.  May be LOOPER_ID_MAIN or
    1.95 +    // LOOPER_ID_INPUT.
    1.96 +    int32_t id;
    1.97 +
    1.98 +    // The android_app this ident is associated with.
    1.99 +    struct android_app* app;
   1.100 +
   1.101 +    // Function to call to perform the standard processing of data from
   1.102 +    // this source.
   1.103 +    void (*process)(struct android_app* app, struct android_poll_source* source);
   1.104 +};
   1.105 +
   1.106 +/**
   1.107 + * This is the interface for the standard glue code of a threaded
   1.108 + * application.  In this model, the application's code is running
   1.109 + * in its own thread separate from the main thread of the process.
   1.110 + * It is not required that this thread be associated with the Java
   1.111 + * VM, although it will need to be in order to make JNI calls any
   1.112 + * Java objects.
   1.113 + */
   1.114 +struct android_app {
   1.115 +    // The application can place a pointer to its own state object
   1.116 +    // here if it likes.
   1.117 +    void* userData;
   1.118 +
   1.119 +    // Fill this in with the function to process main app commands (APP_CMD_*)
   1.120 +    void (*onAppCmd)(struct android_app* app, int32_t cmd);
   1.121 +
   1.122 +    // Fill this in with the function to process input events.  At this point
   1.123 +    // the event has already been pre-dispatched, and it will be finished upon
   1.124 +    // return.  Return 1 if you have handled the event, 0 for any default
   1.125 +    // dispatching.
   1.126 +    int32_t (*onInputEvent)(struct android_app* app, AInputEvent* event);
   1.127 +
   1.128 +    // The ANativeActivity object instance that this app is running in.
   1.129 +    ANativeActivity* activity;
   1.130 +
   1.131 +    // The current configuration the app is running in.
   1.132 +    AConfiguration* config;
   1.133 +
   1.134 +    // This is the last instance's saved state, as provided at creation time.
   1.135 +    // It is NULL if there was no state.  You can use this as you need; the
   1.136 +    // memory will remain around until you call android_app_exec_cmd() for
   1.137 +    // APP_CMD_RESUME, at which point it will be freed and savedState set to NULL.
   1.138 +    // These variables should only be changed when processing a APP_CMD_SAVE_STATE,
   1.139 +    // at which point they will be initialized to NULL and you can malloc your
   1.140 +    // state and place the information here.  In that case the memory will be
   1.141 +    // freed for you later.
   1.142 +    void* savedState;
   1.143 +    size_t savedStateSize;
   1.144 +
   1.145 +    // The ALooper associated with the app's thread.
   1.146 +    ALooper* looper;
   1.147 +
   1.148 +    // When non-NULL, this is the input queue from which the app will
   1.149 +    // receive user input events.
   1.150 +    AInputQueue* inputQueue;
   1.151 +
   1.152 +    // When non-NULL, this is the window surface that the app can draw in.
   1.153 +    ANativeWindow* window;
   1.154 +
   1.155 +    // Current content rectangle of the window; this is the area where the
   1.156 +    // window's content should be placed to be seen by the user.
   1.157 +    ARect contentRect;
   1.158 +
   1.159 +    // Current state of the app's activity.  May be either APP_CMD_START,
   1.160 +    // APP_CMD_RESUME, APP_CMD_PAUSE, or APP_CMD_STOP; see below.
   1.161 +    int activityState;
   1.162 +
   1.163 +    // This is non-zero when the application's NativeActivity is being
   1.164 +    // destroyed and waiting for the app thread to complete.
   1.165 +    int destroyRequested;
   1.166 +
   1.167 +    // -------------------------------------------------
   1.168 +    // Below are "private" implementation of the glue code.
   1.169 +
   1.170 +    pthread_mutex_t mutex;
   1.171 +    pthread_cond_t cond;
   1.172 +
   1.173 +    int msgread;
   1.174 +    int msgwrite;
   1.175 +
   1.176 +    pthread_t thread;
   1.177 +
   1.178 +    struct android_poll_source cmdPollSource;
   1.179 +    struct android_poll_source inputPollSource;
   1.180 +
   1.181 +    int running;
   1.182 +    int stateSaved;
   1.183 +    int destroyed;
   1.184 +    int redrawNeeded;
   1.185 +    AInputQueue* pendingInputQueue;
   1.186 +    ANativeWindow* pendingWindow;
   1.187 +    ARect pendingContentRect;
   1.188 +};
   1.189 +
   1.190 +enum {
   1.191 +    /**
   1.192 +     * Looper data ID of commands coming from the app's main thread, which
   1.193 +     * is returned as an identifier from ALooper_pollOnce().  The data for this
   1.194 +     * identifier is a pointer to an android_poll_source structure.
   1.195 +     * These can be retrieved and processed with android_app_read_cmd()
   1.196 +     * and android_app_exec_cmd().
   1.197 +     */
   1.198 +    LOOPER_ID_MAIN = 1,
   1.199 +
   1.200 +    /**
   1.201 +     * Looper data ID of events coming from the AInputQueue of the
   1.202 +     * application's window, which is returned as an identifier from
   1.203 +     * ALooper_pollOnce().  The data for this identifier is a pointer to an
   1.204 +     * android_poll_source structure.  These can be read via the inputQueue
   1.205 +     * object of android_app.
   1.206 +     */
   1.207 +    LOOPER_ID_INPUT = 2,
   1.208 +
   1.209 +    /**
   1.210 +     * Start of user-defined ALooper identifiers.
   1.211 +     */
   1.212 +    LOOPER_ID_USER = 3,
   1.213 +};
   1.214 +
   1.215 +enum {
   1.216 +    /**
   1.217 +     * Command from main thread: the AInputQueue has changed.  Upon processing
   1.218 +     * this command, android_app->inputQueue will be updated to the new queue
   1.219 +     * (or NULL).
   1.220 +     */
   1.221 +    APP_CMD_INPUT_CHANGED,
   1.222 +
   1.223 +    /**
   1.224 +     * Command from main thread: a new ANativeWindow is ready for use.  Upon
   1.225 +     * receiving this command, android_app->window will contain the new window
   1.226 +     * surface.
   1.227 +     */
   1.228 +    APP_CMD_INIT_WINDOW,
   1.229 +
   1.230 +    /**
   1.231 +     * Command from main thread: the existing ANativeWindow needs to be
   1.232 +     * terminated.  Upon receiving this command, android_app->window still
   1.233 +     * contains the existing window; after calling android_app_exec_cmd
   1.234 +     * it will be set to NULL.
   1.235 +     */
   1.236 +    APP_CMD_TERM_WINDOW,
   1.237 +
   1.238 +    /**
   1.239 +     * Command from main thread: the current ANativeWindow has been resized.
   1.240 +     * Please redraw with its new size.
   1.241 +     */
   1.242 +    APP_CMD_WINDOW_RESIZED,
   1.243 +
   1.244 +    /**
   1.245 +     * Command from main thread: the system needs that the current ANativeWindow
   1.246 +     * be redrawn.  You should redraw the window before handing this to
   1.247 +     * android_app_exec_cmd() in order to avoid transient drawing glitches.
   1.248 +     */
   1.249 +    APP_CMD_WINDOW_REDRAW_NEEDED,
   1.250 +
   1.251 +    /**
   1.252 +     * Command from main thread: the content area of the window has changed,
   1.253 +     * such as from the soft input window being shown or hidden.  You can
   1.254 +     * find the new content rect in android_app::contentRect.
   1.255 +     */
   1.256 +    APP_CMD_CONTENT_RECT_CHANGED,
   1.257 +
   1.258 +    /**
   1.259 +     * Command from main thread: the app's activity window has gained
   1.260 +     * input focus.
   1.261 +     */
   1.262 +    APP_CMD_GAINED_FOCUS,
   1.263 +
   1.264 +    /**
   1.265 +     * Command from main thread: the app's activity window has lost
   1.266 +     * input focus.
   1.267 +     */
   1.268 +    APP_CMD_LOST_FOCUS,
   1.269 +
   1.270 +    /**
   1.271 +     * Command from main thread: the current device configuration has changed.
   1.272 +     */
   1.273 +    APP_CMD_CONFIG_CHANGED,
   1.274 +
   1.275 +    /**
   1.276 +     * Command from main thread: the system is running low on memory.
   1.277 +     * Try to reduce your memory use.
   1.278 +     */
   1.279 +    APP_CMD_LOW_MEMORY,
   1.280 +
   1.281 +    /**
   1.282 +     * Command from main thread: the app's activity has been started.
   1.283 +     */
   1.284 +    APP_CMD_START,
   1.285 +
   1.286 +    /**
   1.287 +     * Command from main thread: the app's activity has been resumed.
   1.288 +     */
   1.289 +    APP_CMD_RESUME,
   1.290 +
   1.291 +    /**
   1.292 +     * Command from main thread: the app should generate a new saved state
   1.293 +     * for itself, to restore from later if needed.  If you have saved state,
   1.294 +     * allocate it with malloc and place it in android_app.savedState with
   1.295 +     * the size in android_app.savedStateSize.  The will be freed for you
   1.296 +     * later.
   1.297 +     */
   1.298 +    APP_CMD_SAVE_STATE,
   1.299 +
   1.300 +    /**
   1.301 +     * Command from main thread: the app's activity has been paused.
   1.302 +     */
   1.303 +    APP_CMD_PAUSE,
   1.304 +
   1.305 +    /**
   1.306 +     * Command from main thread: the app's activity has been stopped.
   1.307 +     */
   1.308 +    APP_CMD_STOP,
   1.309 +
   1.310 +    /**
   1.311 +     * Command from main thread: the app's activity is being destroyed,
   1.312 +     * and waiting for the app thread to clean up and exit before proceeding.
   1.313 +     */
   1.314 +    APP_CMD_DESTROY,
   1.315 +};
   1.316 +
   1.317 +/**
   1.318 + * Call when ALooper_pollAll() returns LOOPER_ID_MAIN, reading the next
   1.319 + * app command message.
   1.320 + */
   1.321 +int8_t android_app_read_cmd(struct android_app* android_app);
   1.322 +
   1.323 +/**
   1.324 + * Call with the command returned by android_app_read_cmd() to do the
   1.325 + * initial pre-processing of the given command.  You can perform your own
   1.326 + * actions for the command after calling this function.
   1.327 + */
   1.328 +void android_app_pre_exec_cmd(struct android_app* android_app, int8_t cmd);
   1.329 +
   1.330 +/**
   1.331 + * Call with the command returned by android_app_read_cmd() to do the
   1.332 + * final post-processing of the given command.  You must have done your own
   1.333 + * actions for the command before calling this function.
   1.334 + */
   1.335 +void android_app_post_exec_cmd(struct android_app* android_app, int8_t cmd);
   1.336 +
   1.337 +/**
   1.338 + * Dummy function you can call to ensure glue code isn't stripped.
   1.339 + */
   1.340 +void app_dummy();
   1.341 +
   1.342 +/**
   1.343 + * This is the function that application code must implement, representing
   1.344 + * the main entry to the app.
   1.345 + */
   1.346 +extern void android_main(struct android_app* app);
   1.347 +
   1.348 +#ifdef __cplusplus
   1.349 +}
   1.350 +#endif
   1.351 +
   1.352 +#endif /* _ANDROID_NATIVE_APP_GLUE_H */