Rename create/destroy events to realize/unrealize

As evidence that this was confusing, the documentation for these was an
outright lie, and I've burned quite a bit of time in the past few days trying
to rework things based around that flawed understanding.

These names make it clear what these events actually are.  If we need actual
create/destroy events with a broader scope, they'll have to be added, but I
suspect those aren't actually useful anyway.

16 files changed, 99 insertions, 100 deletions

diff --git a/bindings/cpp/include/pugl/pugl.hpp b/bindings/cpp/include/pugl/pugl.hpp
index d24c52f..267b07c 100644
--- a/bindings/cpp/include/pugl/pugl.hpp
+++ b/bindings/cpp/include/pugl/pugl.hpp
@@ -108,11 +108,11 @@ using EventFlag    = PuglEventFlag;    ///< @copydoc PuglEventFlag
 using EventFlags   = PuglEventFlags;   ///< @copydoc PuglEventFlags
 using CrossingMode = PuglCrossingMode; ///< @copydoc PuglCrossingMode
 
-/// @copydoc PuglCreateEvent
-using CreateEvent = Event<PUGL_CREATE, PuglCreateEvent>;
+/// @copydoc PuglRealizeEvent
+using RealizeEvent = Event<PUGL_REALIZE, PuglRealizeEvent>;
 
-/// @copydoc PuglDestroyEvent
-using DestroyEvent = Event<PUGL_DESTROY, PuglDestroyEvent>;
+/// @copydoc PuglUnrealizeEvent
+using UnrealizeEvent = Event<PUGL_UNREALIZE, PuglUnrealizeEvent>;
 
 /// @copydoc PuglConfigureEvent
 using ConfigureEvent = Event<PUGL_CONFIGURE, PuglConfigureEvent>;
@@ -672,10 +672,10 @@ private:
     switch (event->type) {
     case PUGL_NOTHING:
       return Status::success;
-    case PUGL_CREATE:
-      return target.onEvent(CreateEvent{event->any});
-    case PUGL_DESTROY:
-      return target.onEvent(DestroyEvent{event->any});
+    case PUGL_REALIZE:
+      return target.onEvent(RealizeEvent{event->any});
+    case PUGL_UNREALIZE:
+      return target.onEvent(UnrealizeEvent{event->any});
     case PUGL_CONFIGURE:
       return target.onEvent(ConfigureEvent{event->configure});
     case PUGL_MAP:
diff --git a/doc/c/events.rst b/doc/c/events.rst
index 86f7c63..804c724 100644
--- a/doc/c/events.rst
+++ b/doc/c/events.rst
@@ -24,9 +24,9 @@ For example, a basic event handler might look something like this:
      MyApp* app = (MyApp*)puglGetHandle(view);
 
      switch (event->type) {
-     case PUGL_CREATE:
+     case PUGL_REALIZE:
        return setupGraphics(app);
-     case PUGL_DESTROY:
+     case PUGL_UNREALIZE:
        return teardownGraphics(app);
      case PUGL_CONFIGURE:
        return resize(app, event->configure.width, event->configure.height);
@@ -69,8 +69,8 @@ OpenGL Context
 
 The OpenGL context is only active during the handling of these events:
 
-- :struct:`PuglCreateEvent`
-- :struct:`PuglDestroyEvent`
+- :struct:`PuglRealizeEvent`
+- :struct:`PuglUnrealizeEvent`
 - :struct:`PuglConfigureEvent`
 - :struct:`PuglExposeEvent`
 
diff --git a/doc/c/view.rst b/doc/c/view.rst
index faf926f..ea261ff 100644
--- a/doc/c/view.rst
+++ b/doc/c/view.rst
@@ -167,8 +167,8 @@ If you need to perform some setup using the OpenGL API,
 there are two ways to do so.
 
 The OpenGL context is active when
-:enumerator:`PUGL_CREATE <PuglEventType.PUGL_CREATE>` and
-:enumerator:`PUGL_DESTROY <PuglEventType.PUGL_DESTROY>`
+:enumerator:`PUGL_REALIZE <PuglEventType.PUGL_REALIZE>` and
+:enumerator:`PUGL_UNREALIZE <PuglEventType.PUGL_UNREALIZE>`
 events are dispatched,
 so things like creating and destroying shaders and textures can be done then.
 
diff --git a/doc/cpp/view.rst b/doc/cpp/view.rst
index 5366731..49940c9 100644
--- a/doc/cpp/view.rst
+++ b/doc/cpp/view.rst
@@ -160,8 +160,8 @@ If you need to perform some setup using the OpenGL API,
 there are two ways to do so.
 
 The OpenGL context is active when
-:type:`CreateEvent` and
-:type:`DestroyEvent`
+:type:`RealizeEvent` and
+:type:`UnrealizeEvent`
 events are dispatched,
 so things like creating and destroying shaders and textures can be done then.
 
diff --git a/examples/pugl_shader_demo.c b/examples/pugl_shader_demo.c
index e3a1900..cea6d0a 100644
--- a/examples/pugl_shader_demo.c
+++ b/examples/pugl_shader_demo.c
@@ -131,10 +131,10 @@ onEvent(PuglView* view, const PuglEvent* event)
   printEvent(event, "Event: ", app->opts.verbose);
 
   switch (event->type) {
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     setupGl(app);
     break;
-  case PUGL_DESTROY:
+  case PUGL_UNREALIZE:
     teardownGl(app);
     break;
   case PUGL_CONFIGURE:
@@ -445,7 +445,7 @@ main(int argc, char** argv)
   // Create and configure world and view
   setupPugl(&app);
 
-  // Create window (which will send a PUGL_CREATE event)
+  // Realize window (which will send a PUGL_REALIZE event)
   const PuglStatus st = puglRealize(app.view);
   if (st) {
     return logError("Failed to create window (%s)\n", puglStrerror(st));
@@ -463,7 +463,7 @@ main(int argc, char** argv)
     puglPrintFps(app.world, &fpsPrinter, &app.framesDrawn);
   }
 
-  // Destroy window (which will send a PUGL_DESTROY event)
+  // Destroy window (which will send a PUGL_UNREALIZE event)
   puglFreeView(app.view);
 
   // Free everything else
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h
index fda8af2..7b021b8 100644
--- a/include/pugl/pugl.h
+++ b/include/pugl/pugl.h
@@ -77,8 +77,8 @@ typedef struct {
 /// The type of a PuglEvent
 typedef enum {
   PUGL_NOTHING,        ///< No event
-  PUGL_CREATE,         ///< View created, a #PuglCreateEvent
-  PUGL_DESTROY,        ///< View destroyed, a #PuglDestroyEvent
+  PUGL_REALIZE,        ///< View realized, a #PuglRealizeEvent
+  PUGL_UNREALIZE,      ///< View unrealizeed, a #PuglUnrealizeEvent
   PUGL_CONFIGURE,      ///< View moved/resized, a #PuglConfigureEvent
   PUGL_MAP,            ///< View made visible, a #PuglMapEvent
   PUGL_UNMAP,          ///< View made invisible, a #PuglUnmapEvent
@@ -132,7 +132,7 @@ typedef struct {
 */
 
 /**
-   View create event.
+   View realize event.
 
    This event is sent when a view is realized before it is first displayed,
    with the graphics context entered.  This is typically used for setting up
@@ -140,22 +140,19 @@ typedef struct {
 
    This event type has no extra fields.
 */
-typedef PuglAnyEvent PuglCreateEvent;
+typedef PuglAnyEvent PuglRealizeEvent;
 
 /**
-   View destroy event.
+   View unrealize event.
 
-   This event is the counterpart to #PuglCreateEvent, and it is sent when the
-   view is being destroyed.  This is typically used for tearing down the
-   graphics system, or otherwise freeing any resources allocated when the
-   create event was handled.
-
-   This is the last event sent to any view, and immediately after it is
-   processed, the view is destroyed and may no longer be used.
+   This event is the counterpart to #PuglRealizeEvent, and is sent when the
+   view will no longer be displayed.  This is typically used for tearing down
+   the graphics system, or otherwise freeing any resources allocated when the
+   realize event was handled.
 
    This event type has no extra fields.
 */
-typedef PuglAnyEvent PuglDestroyEvent;
+typedef PuglAnyEvent PuglUnrealizeEvent;
 
 /**
    View resize or move event.
@@ -604,8 +601,9 @@ typedef struct {
    to the appropriate type, or the union members used.
 
    The graphics system may only be accessed when handling certain events.  The
-   graphics context is active for #PUGL_CREATE, #PUGL_DESTROY, #PUGL_CONFIGURE,
-   and #PUGL_EXPOSE, but only enabled for drawing for #PUGL_EXPOSE.
+   graphics context is active for #PUGL_REALIZE, #PUGL_UNREALIZE,
+   #PUGL_CONFIGURE, and #PUGL_EXPOSE, but only enabled for drawing for
+   #PUGL_EXPOSE.
 */
 typedef union {
   PuglAnyEvent       any;       ///< Valid for all event types
@@ -1486,10 +1484,16 @@ puglSendEvent(PuglView* view, const PuglEvent* event);
    @{
 */
 
-PUGL_DEPRECATED_BY("PuglCreateEvent")
+PUGL_DEPRECATED_BY("PuglRealizeEvent")
+typedef PuglRealizeEvent PuglCreateEvent;
+
+PUGL_DEPRECATED_BY("PuglUnrealizeEvent")
+typedef PuglUnrealizeEvent PuglDestroyEvent;
+
+PUGL_DEPRECATED_BY("PuglRealizeEvent")
 typedef PuglCreateEvent PuglEventCreate;
 
-PUGL_DEPRECATED_BY("PuglDestroyEvent")
+PUGL_DEPRECATED_BY("PuglUnrealizeEvent")
 typedef PuglDestroyEvent PuglEventDestroy;
 
 PUGL_DEPRECATED_BY("PuglConfigureEvent")
diff --git a/src/internal.c b/src/internal.c
index ef1bcef..f1f2e65 100644
--- a/src/internal.c
+++ b/src/internal.c
@@ -131,7 +131,7 @@ puglPreRealize(PuglView* const view)
 PuglStatus
 puglDispatchSimpleEvent(PuglView* view, const PuglEventType type)
 {
-  assert(type == PUGL_CREATE || type == PUGL_DESTROY || type == PUGL_MAP ||
+  assert(type == PUGL_REALIZE || type == PUGL_UNREALIZE || type == PUGL_MAP ||
          type == PUGL_UNMAP || type == PUGL_UPDATE || type == PUGL_CLOSE ||
          type == PUGL_LOOP_ENTER || type == PUGL_LOOP_LEAVE);
 
@@ -183,17 +183,17 @@ puglDispatchEvent(PuglView* view, const PuglEvent* event)
   case PUGL_NOTHING:
     break;
 
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     assert(view->stage == PUGL_VIEW_STAGE_ALLOCATED);
     if (!(st0 = view->backend->enter(view, NULL))) {
       st0 = view->eventFunc(view, event);
       st1 = view->backend->leave(view, NULL);
     }
-    view->stage = PUGL_VIEW_STAGE_CREATED;
+    view->stage = PUGL_VIEW_STAGE_REALIZED;
     break;
 
-  case PUGL_DESTROY:
-    assert(view->stage >= PUGL_VIEW_STAGE_CREATED);
+  case PUGL_UNREALIZE:
+    assert(view->stage >= PUGL_VIEW_STAGE_REALIZED);
     if (!(st0 = view->backend->enter(view, NULL))) {
       st0 = view->eventFunc(view, event);
       st1 = view->backend->leave(view, NULL);
@@ -202,14 +202,13 @@ puglDispatchEvent(PuglView* view, const PuglEvent* event)
     break;
 
   case PUGL_CONFIGURE:
-    assert(view->stage >= PUGL_VIEW_STAGE_CREATED);
     if (puglMustConfigure(view, &event->configure)) {
       if (!(st0 = view->backend->enter(view, NULL))) {
         st0 = puglConfigure(view, event);
         st1 = view->backend->leave(view, NULL);
       }
     }
-    if (view->stage == PUGL_VIEW_STAGE_CREATED) {
+    if (view->stage == PUGL_VIEW_STAGE_REALIZED) {
       view->stage = PUGL_VIEW_STAGE_CONFIGURED;
     }
     break;
diff --git a/src/mac.m b/src/mac.m
index b8e30df..103e790 100644
--- a/src/mac.m
+++ b/src/mac.m
@@ -1163,9 +1163,7 @@ puglRealize(PuglView* view)
 
   [impl->wrapperView updateTrackingAreas];
 
-  puglDispatchSimpleEvent(view, PUGL_CREATE);
-
-  return PUGL_SUCCESS;
+  return puglDispatchSimpleEvent(view, PUGL_REALIZE);
 }
 
 PuglStatus
@@ -1176,7 +1174,7 @@ puglUnrealize(PuglView* const view)
     return PUGL_FAILURE;
   }
 
-  puglDispatchSimpleEvent(view, PUGL_DESTROY);
+  puglDispatchSimpleEvent(view, PUGL_UNREALIZE);
 
   if (view->backend) {
     view->backend->destroy(view);
diff --git a/src/types.h b/src/types.h
index 28d8548..072d3fe 100644
--- a/src/types.h
+++ b/src/types.h
@@ -36,7 +36,7 @@ typedef struct {
 /// Stage of a view along its lifespan
 typedef enum {
   PUGL_VIEW_STAGE_ALLOCATED,
-  PUGL_VIEW_STAGE_CREATED,
+  PUGL_VIEW_STAGE_REALIZED,
   PUGL_VIEW_STAGE_CONFIGURED,
   PUGL_VIEW_STAGE_MAPPED,
 } PuglViewStage;
diff --git a/src/win.c b/src/win.c
index 13ad090..73f0757 100644
--- a/src/win.c
+++ b/src/win.c
@@ -209,6 +209,14 @@ puglPollWinEvents(PuglWorld* world, const double timeout)
   return PUGL_SUCCESS;
 }
 
+static void
+ensureHint(PuglView* const view, const PuglViewHint hint, const int value)
+{
+  if (view->hints[hint] == PUGL_DONT_CARE) {
+    view->hints[hint] = value;
+  }
+}
+
 PuglStatus
 puglRealize(PuglView* view)
 {
@@ -225,19 +233,11 @@ puglRealize(PuglView* view)
     return st;
   }
 
-  // Getting depth from the display mode seems tedious, just set usual values
-  if (view->hints[PUGL_RED_BITS] == PUGL_DONT_CARE) {
-    view->hints[PUGL_RED_BITS] = 8;
-  }
-  if (view->hints[PUGL_BLUE_BITS] == PUGL_DONT_CARE) {
-    view->hints[PUGL_BLUE_BITS] = 8;
-  }
-  if (view->hints[PUGL_GREEN_BITS] == PUGL_DONT_CARE) {
-    view->hints[PUGL_GREEN_BITS] = 8;
-  }
-  if (view->hints[PUGL_ALPHA_BITS] == PUGL_DONT_CARE) {
-    view->hints[PUGL_ALPHA_BITS] = 8;
-  }
+  // Set default depth hints if the user hasn't specified any
+  ensureHint(view, PUGL_RED_BITS, 8);
+  ensureHint(view, PUGL_GREEN_BITS, 8);
+  ensureHint(view, PUGL_BLUE_BITS, 8);
+  ensureHint(view, PUGL_ALPHA_BITS, 8);
 
   // Get refresh rate for resize draw timer
   DEVMODEA devMode;
@@ -250,6 +250,7 @@ puglRealize(PuglView* view)
     return PUGL_REGISTRATION_FAILED;
   }
 
+  // Configure and create window
   if ((st = view->backend->configure(view)) ||
       (st = view->backend->create(view))) {
     return st;
@@ -269,9 +270,7 @@ puglRealize(PuglView* view)
   puglSetFrame(view, view->frame);
   SetWindowLongPtr(impl->hwnd, GWLP_USERDATA, (LONG_PTR)view);
 
-  puglDispatchSimpleEvent(view, PUGL_CREATE);
-
-  return PUGL_SUCCESS;
+  return puglDispatchSimpleEvent(view, PUGL_REALIZE);
 }
 
 PuglStatus
@@ -282,7 +281,7 @@ puglUnrealize(PuglView* const view)
     return PUGL_FAILURE;
   }
 
-  puglDispatchSimpleEvent(view, PUGL_DESTROY);
+  puglDispatchSimpleEvent(view, PUGL_UNREALIZE);
 
   if (view->backend) {
     view->backend->destroy(view);
@@ -972,7 +971,7 @@ puglUpdate(PuglWorld* world, double timeout)
   }
 
   for (size_t i = 0; i < world->numViews; ++i) {
-    if (world->views[i]->visible) {
+    if (puglGetVisible(world->views[i])) {
       puglDispatchSimpleEvent(world->views[i], PUGL_UPDATE);
     }
 
diff --git a/src/x11.c b/src/x11.c
index c3bf31f..a6daf72 100644
--- a/src/x11.c
+++ b/src/x11.c
@@ -475,7 +475,7 @@ puglRealize(PuglView* const view)
                           (XIM)0);
   }
 
-  puglDispatchSimpleEvent(view, PUGL_CREATE);
+  st = puglDispatchSimpleEvent(view, PUGL_REALIZE);
 
   /* Flush before returning for two reasons: so that hints are available to the
      view's parent via the X server during embedding, and so that the X server
@@ -484,8 +484,7 @@ puglRealize(PuglView* const view)
      increases the chances that an application will be cleanly configured once
      on startup with the correct position and size. */
   XFlush(display);
-
-  return PUGL_SUCCESS;
+  return st;
 }
 
 PuglStatus
@@ -496,7 +495,7 @@ puglUnrealize(PuglView* const view)
     return PUGL_FAILURE;
   }
 
-  puglDispatchSimpleEvent(view, PUGL_DESTROY);
+  puglDispatchSimpleEvent(view, PUGL_UNREALIZE);
   clearX11Clipboard(&impl->clipboard);
 
   if (impl->xic) {
diff --git a/test/test_realize.c b/test/test_realize.c
index cf2cde6..4bdafae 100644
--- a/test/test_realize.c
+++ b/test/test_realize.c
@@ -22,7 +22,7 @@
 
 typedef enum {
   START,
-  CREATED,
+  REALIZED,
 } State;
 
 typedef struct {
@@ -42,9 +42,9 @@ onEvent(PuglView* view, const PuglEvent* event)
   }
 
   switch (event->type) {
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     assert(test->state == START);
-    test->state = CREATED;
+    test->state = REALIZED;
     break;
   default:
     break;
@@ -77,7 +77,7 @@ main(int argc, char** argv)
   // Create initially invisible window
   assert(!puglRealize(test.view));
   assert(!puglGetVisible(test.view));
-  while (test.state < CREATED) {
+  while (test.state < REALIZED) {
     assert(!puglUpdate(test.world, -1.0));
   }
 
diff --git a/test/test_show_hide.c b/test/test_show_hide.c
index 1dc17a2..a5c8622 100644
--- a/test/test_show_hide.c
+++ b/test/test_show_hide.c
@@ -19,12 +19,12 @@
 
 typedef enum {
   START,
-  CREATED,
+  REALIZED,
   CONFIGURED,
   MAPPED,
   EXPOSED,
   UNMAPPED,
-  DESTROYED,
+  UNREALIZED,
 } State;
 
 typedef struct {
@@ -44,12 +44,12 @@ onEvent(PuglView* view, const PuglEvent* event)
   }
 
   switch (event->type) {
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     assert(test->state == START);
-    test->state = CREATED;
+    test->state = REALIZED;
     break;
   case PUGL_CONFIGURE:
-    if (test->state == CREATED) {
+    if (test->state == REALIZED) {
       test->state = CONFIGURED;
     }
     break;
@@ -65,9 +65,9 @@ onEvent(PuglView* view, const PuglEvent* event)
     assert(test->state == MAPPED || test->state == EXPOSED);
     test->state = UNMAPPED;
     break;
-  case PUGL_DESTROY:
+  case PUGL_UNREALIZE:
     assert(test->state == UNMAPPED);
-    test->state = DESTROYED;
+    test->state = UNREALIZED;
     break;
   default:
     break;
@@ -126,7 +126,7 @@ main(int argc, char** argv)
   // Create initially invisible window
   assert(!puglRealize(test.view));
   assert(!puglGetVisible(test.view));
-  while (test.state < CREATED) {
+  while (test.state < REALIZED) {
     tick(test.world);
   }
 
@@ -136,7 +136,7 @@ main(int argc, char** argv)
   // Unrealize view
   assert(!puglGetVisible(test.view));
   assert(!puglUnrealize(test.view));
-  assert(test.state == DESTROYED);
+  assert(test.state == UNREALIZED);
 
   // Realize and show again
   test.state = START;
@@ -146,7 +146,7 @@ main(int argc, char** argv)
 
   // Tear down
   puglFreeView(test.view);
-  assert(test.state == DESTROYED);
+  assert(test.state == UNREALIZED);
   puglFreeWorld(test.world);
 
   return 0;
diff --git a/test/test_size.c b/test/test_size.c
index 1c2f0c6..ef8b738 100644
--- a/test/test_size.c
+++ b/test/test_size.c
@@ -16,10 +16,10 @@
 
 typedef enum {
   START,
-  CREATED,
+  REALIZED,
   CONFIGURED,
   MAPPED,
-  DESTROYED,
+  UNREALIZED,
 } State;
 
 typedef struct {
@@ -40,12 +40,12 @@ onEvent(PuglView* view, const PuglEvent* event)
   }
 
   switch (event->type) {
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     assert(test->state == START);
-    test->state = CREATED;
+    test->state = REALIZED;
     break;
   case PUGL_CONFIGURE:
-    if (test->state == CREATED) {
+    if (test->state == REALIZED) {
       test->state = CONFIGURED;
     }
     test->configuredFrame.x      = event->configure.x;
@@ -56,8 +56,8 @@ onEvent(PuglView* view, const PuglEvent* event)
   case PUGL_MAP:
     test->state = MAPPED;
     break;
-  case PUGL_DESTROY:
-    test->state = DESTROYED;
+  case PUGL_UNREALIZE:
+    test->state = UNREALIZED;
     break;
   default:
     break;
diff --git a/test/test_utils.h b/test/test_utils.h
index 359f51d..fd2c15b 100644
--- a/test/test_utils.h
+++ b/test/test_utils.h
@@ -101,10 +101,10 @@ printEvent(const PuglEvent* event, const char* prefix, const bool verbose)
   switch (event->type) {
   case PUGL_NOTHING:
     return 0;
-  case PUGL_CREATE:
-    return fprintf(stderr, "%sCreate\n", prefix);
-  case PUGL_DESTROY:
-    return fprintf(stderr, "%sDestroy\n", prefix);
+  case PUGL_REALIZE:
+    return fprintf(stderr, "%sRealize\n", prefix);
+  case PUGL_UNREALIZE:
+    return fprintf(stderr, "%sUnrealize\n", prefix);
   case PUGL_MAP:
     return fprintf(stderr, "%sMap\n", prefix);
   case PUGL_UNMAP:
diff --git a/test/test_view.c b/test/test_view.c
index f8b0cb5..34bf124 100644
--- a/test/test_view.c
+++ b/test/test_view.c
@@ -18,7 +18,7 @@ typedef enum {
   START,
   CREATED,
   MAPPED,
-  DESTROYED,
+  UNREALIZED,
 } State;
 
 typedef struct {
@@ -38,15 +38,15 @@ onEvent(PuglView* view, const PuglEvent* event)
   }
 
   switch (event->type) {
-  case PUGL_CREATE:
+  case PUGL_REALIZE:
     assert(test->state == START);
     test->state = CREATED;
     break;
   case PUGL_MAP:
     test->state = MAPPED;
     break;
-  case PUGL_DESTROY:
-    test->state = DESTROYED;
+  case PUGL_UNREALIZE:
+    test->state = UNREALIZED;
     break;
   default:
     break;