gdk: Update Suspend/Resume best practices.

Updated testgdk to demonstrate correct handling of suspend/resume and the new Render APIs, and updated the docs to explain the correct usage of these GDK functions.

VisualC-GDK/tests/testgdk/src/testgdk.cpp

@@ -30,7 +30,9 @@ extern "C" {
 #include <XGameRuntime.h>
 
 #define NUM_SPRITES    100
-#define MAX_SPEED     1
+#define MAX_SPEED      1
+#define SUSPEND_CODE   0
+#define RESUME_CODE    1
 
 static SDLTest_CommonState *state;
 static int num_sprites;
@@ -291,7 +293,7 @@ static void DrawSprites(SDL_Renderer * renderer, SDL_Texture * sprite)
     SDL_RenderPresent(renderer);
 }
 
-static void update()
+static void update(bool *suppressdraw)
 {
     SDL_Event event;
 
@@ -305,6 +307,25 @@ static void update()
         if (event.type != SDL_EVENT_KEY_DOWN) {
             SDLTest_CommonEvent(state, &event, &done);
         }
+
+        if (event.type == SDL_EVENT_USER) {
+            if (event.user.code == SUSPEND_CODE) {
+                for (int i = 0; i < state->num_windows; ++i) {
+                    if (state->windows[i] != NULL) {
+                        SDL_GDKSuspendRenderer(state->renderers[i]);
+                    }
+                }
+                *suppressdraw = true;
+                SDL_GDKSuspendComplete();
+            } else if (event.user.code == RESUME_CODE) {
+                for (int i = 0; i < state->num_windows; ++i) {
+                    if (state->windows[i] != NULL) {
+                        SDL_GDKResumeRenderer(state->renderers[i]);
+                    }
+                }
+                *suppressdraw = false;
+            }
+        }
 #else
         SDLTest_CommonEvent(state, &event, &done);
 #endif
@@ -316,24 +337,33 @@ static void draw()
 {
     int i;
     for (i = 0; i < state->num_windows; ++i) {
-        if (state->windows[i] == NULL) {
-            continue;
+        if (state->windows[i] != NULL) {
+            DrawSprites(state->renderers[i], sprites[i]);
         }
-        DrawSprites(state->renderers[i], sprites[i]);
     }
 }
 
 static bool SDLCALL GDKEventWatch(void* userdata, SDL_Event* event)
 {
-    bool *suppressdraw = (bool *)userdata;
-    SDL_assert(suppressdraw != NULL);
+    /* This callback may be on a different thread, so we'll
+     * push these events as USER events so they appear
+     * in the main thread's event loop.
+     *
+     * That allows us to cancel drawing before/after we finish
+     * drawing a frame, rather than mid-draw (which can crash).
+     */
     if (event->type == SDL_EVENT_DID_ENTER_BACKGROUND) {
-        *suppressdraw = true;
-        SDL_GDKSuspendComplete();
+        SDL_Event evt;
+        evt.type = SDL_EVENT_USER;
+        evt.user.code = 0;
+        SDL_PushEvent(&evt);
     } else if (event->type == SDL_EVENT_WILL_ENTER_FOREGROUND) {
-        *suppressdraw = false;
+        SDL_Event evt;
+        evt.type = SDL_EVENT_USER;
+        evt.user.code = 1;
+        SDL_PushEvent(&evt);
     }
-    return true;
+    return false;
 }
 
 int main(int argc, char *argv[])
@@ -408,8 +438,8 @@ int main(int argc, char *argv[])
         quit(2);
     }
 
-    /* By this point the renderers are made, so we can now add this watcher */
-    SDL_AddEventWatch(GDKEventWatch, &suppressdraw);
+    /* Set up the lifecycle event watcher */
+    SDL_AddEventWatch(GDKEventWatch, NULL);
 
     /* Create the windows, initialize the renderers, and load the textures */
     sprites =
@@ -462,7 +492,7 @@ int main(int argc, char *argv[])
     AddUserSilent();
 
     while (!done) {
-        update();
+        update(&suppressdraw);
         if (!suppressdraw) {
             draw();
         }