Rename puglPostRedisplay() to puglObscureView()

For consistency with event types (since "obscure" is opposite "expose") and the
upcoming puglObscureRegion().

18 files changed, 58 insertions, 44 deletions

diff --git a/bindings/cpp/include/pugl/pugl.hpp b/bindings/cpp/include/pugl/pugl.hpp
index a4ee273..c74962b 100644
--- a/bindings/cpp/include/pugl/pugl.hpp
+++ b/bindings/cpp/include/pugl/pugl.hpp
@@ -609,10 +609,10 @@ public:
   /// @copydoc puglGetContext
   void* context() noexcept { return puglGetContext(cobj()); }
 
-  /// @copydoc puglPostRedisplay
-  Status postRedisplay() noexcept
+  /// @copydoc puglObscure
+  Status obscure() noexcept
   {
-    return static_cast<Status>(puglPostRedisplay(cobj()));
+    return static_cast<Status>(puglObscureView(cobj()));
   }
 
   /// @copydoc puglPostRedisplayRect
diff --git a/doc/c/event-loop.rst b/doc/c/event-loop.rst
index be4e315..430566f 100644
--- a/doc/c/event-loop.rst
+++ b/doc/c/event-loop.rst
@@ -23,12 +23,11 @@ while those that draw continuously may use a significant fraction of the frame p
 Redrawing
 *********
 
-Occasional redrawing can be requested by calling :func:`puglPostRedisplay` or :func:`puglPostRedisplayRect`.
+Occasional redrawing can be requested by calling :func:`puglObscureView` or :func:`puglPostRedisplayRect`.
 After these are called,
 a :struct:`PuglExposeEvent` will be dispatched on the next call to :func:`puglUpdate`.
 
-For continuous redrawing,
-call :func:`puglPostRedisplay` while handling a :struct:`PuglUpdateEvent` event.
+For continuous redrawing, obscure the view while handling a :struct:`PuglUpdateEvent` event.
 This event is sent just before views are redrawn,
 so it can be used as a hook to expand the update region right before the view is exposed.
 Anything else that needs to be done every frame can be handled similarly.
diff --git a/doc/cpp/event-loop.rst b/doc/cpp/event-loop.rst
index 1d2ac41..3223069 100644
--- a/doc/cpp/event-loop.rst
+++ b/doc/cpp/event-loop.rst
@@ -24,14 +24,13 @@ while those that draw continuously may use a significant fraction of the frame p
 Redrawing
 *********
 
-Occasional redrawing can be requested by calling :func:`View::postRedisplay` or :func:`View::postRedisplayRect`.
+Occasional redrawing can be requested by calling :func:`View::obscure`.
 After these are called,
 a :type:`ExposeEvent` will be dispatched on the next call to :func:`World::update`.
 Note, however, that this will not wake up a blocked :func:`World::update` call on MacOS
 (which does not handle drawing via events).
 
-For continuous redrawing,
-call :func:`View::postRedisplay` while handling a :type:`UpdateEvent`.
+For continuous redrawing, obscure the view while handling a :type:`UpdateEvent`.
 This event is sent just before views are redrawn,
 so it can be used as a hook to expand the update region right before the view is exposed.
 Anything else that needs to be done every frame can be handled similarly.
diff --git a/examples/pugl_cairo_demo.c b/examples/pugl_cairo_demo.c
index 6608bab..2859ff0 100644
--- a/examples/pugl_cairo_demo.c
+++ b/examples/pugl_cairo_demo.c
@@ -225,15 +225,15 @@ onEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_POINTER_IN:
     app->entered = true;
-    puglPostRedisplay(view);
+    puglObscureView(view);
     break;
   case PUGL_POINTER_OUT:
     app->entered = false;
-    puglPostRedisplay(view);
+    puglObscureView(view);
     break;
   case PUGL_UPDATE:
     if (app->opts.continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_EXPOSE:
diff --git a/examples/pugl_clipboard_demo.c b/examples/pugl_clipboard_demo.c
index efeb1eb..78ea4e8 100644
--- a/examples/pugl_clipboard_demo.c
+++ b/examples/pugl_clipboard_demo.c
@@ -116,7 +116,7 @@ static void
 redisplayView(PuglTestApp* app, PuglView* view)
 {
   if (!app->continuous) {
-    puglPostRedisplay(view);
+    puglObscureView(view);
   }
 }
 
@@ -135,7 +135,7 @@ onEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_UPDATE:
     if (app->continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_EXPOSE:
diff --git a/examples/pugl_cpp_demo.cpp b/examples/pugl_cpp_demo.cpp
index 2b3c0a1..6b52d18 100644
--- a/examples/pugl_cpp_demo.cpp
+++ b/examples/pugl_cpp_demo.cpp
@@ -53,8 +53,8 @@ CubeView::onEvent(const pugl::ConfigureEvent& event) noexcept
 pugl::Status
 CubeView::onEvent(const pugl::UpdateEvent&) noexcept
 {
-  // Normally, we would post a redisplay:
-  // return postRedisplay();
+  // Normally, we would obscure the view
+  // return obscure();
 
   // But for testing, use sendEvent() instead:
   return sendEvent(pugl::ExposeEvent{
diff --git a/examples/pugl_embed_demo.c b/examples/pugl_embed_demo.c
index 0274ab4..c14afde 100644
--- a/examples/pugl_embed_demo.c
+++ b/examples/pugl_embed_demo.c
@@ -92,8 +92,8 @@ swapFocus(PuglTestApp* app)
   }
 
   if (!app->continuous) {
-    puglPostRedisplay(app->parent);
-    puglPostRedisplay(app->child);
+    puglObscureView(app->parent);
+    puglObscureView(app->child);
   }
 }
 
@@ -146,7 +146,7 @@ onParentEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_UPDATE:
     if (app->continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_EXPOSE:
@@ -195,7 +195,7 @@ onEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_UPDATE:
     if (app->continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_EXPOSE:
@@ -213,14 +213,14 @@ onEvent(PuglView* view, const PuglEvent* event)
     app->lastMouseX = event->motion.x;
     app->lastMouseY = event->motion.y;
     if (!app->continuous) {
-      puglPostRedisplay(view);
-      puglPostRedisplay(app->parent);
+      puglObscureView(view);
+      puglObscureView(app->parent);
     }
     break;
   case PUGL_SCROLL:
     app->dist = fmaxf(10.0f, app->dist + (float)event->scroll.dy);
     if (!app->continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_POINTER_IN:
diff --git a/examples/pugl_management_demo.c b/examples/pugl_management_demo.c
index 2807837..51d2f43 100644
--- a/examples/pugl_management_demo.c
+++ b/examples/pugl_management_demo.c
@@ -203,7 +203,7 @@ onCommonEvent(PuglView* view, const PuglEvent* const event)
     }
     break;
   case PUGL_CONFIGURE:
-    return puglPostRedisplay(view);
+    return puglObscureView(view);
   case PUGL_EXPOSE:
     return onExpose(view, &event->expose);
   case PUGL_KEY_PRESS:
diff --git a/examples/pugl_shader_demo.c b/examples/pugl_shader_demo.c
index 4d6821a..2b122a9 100644
--- a/examples/pugl_shader_demo.c
+++ b/examples/pugl_shader_demo.c
@@ -168,7 +168,7 @@ onEvent(PuglView* view, const PuglEvent* event)
     onConfigure(view, event->configure.width, event->configure.height);
     break;
   case PUGL_UPDATE:
-    puglPostRedisplay(view);
+    puglObscureView(view);
     break;
   case PUGL_EXPOSE:
     onExpose(view);
@@ -195,7 +195,7 @@ onEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_TIMER:
     if (event->timer.id == resizeTimerId) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   default:
diff --git a/examples/pugl_vulkan_cpp_demo.cpp b/examples/pugl_vulkan_cpp_demo.cpp
index fd93394..a1d6954 100644
--- a/examples/pugl_vulkan_cpp_demo.cpp
+++ b/examples/pugl_vulkan_cpp_demo.cpp
@@ -1522,7 +1522,7 @@ View::onEvent(const pugl::ConfigureEvent& event)
 pugl::Status
 View::onEvent(const pugl::UpdateEvent&)
 {
-  return postRedisplay();
+  return obscure();
 }
 
 VkResult
@@ -1708,7 +1708,7 @@ View::onEvent(const pugl::LoopEnterEvent&)
 pugl::Status
 View::onEvent(const pugl::TimerEvent&)
 {
-  return postRedisplay();
+  return obscure();
 }
 
 pugl::Status
diff --git a/examples/pugl_vulkan_demo.c b/examples/pugl_vulkan_demo.c
index 35be97f..708a28f 100644
--- a/examples/pugl_vulkan_demo.c
+++ b/examples/pugl_vulkan_demo.c
@@ -1009,7 +1009,7 @@ onEvent(PuglView* const view, const PuglEvent* const e)
 
   switch (e->type) {
   case PUGL_UPDATE:
-    return app->opts.continuous ? puglPostRedisplay(view) : PUGL_SUCCESS;
+    return app->opts.continuous ? puglObscureView(view) : PUGL_SUCCESS;
   case PUGL_EXPOSE:
     return onExpose(view);
   case PUGL_CONFIGURE:
diff --git a/examples/pugl_window_demo.c b/examples/pugl_window_demo.c
index 67086bb..cd4fd67 100644
--- a/examples/pugl_window_demo.c
+++ b/examples/pugl_window_demo.c
@@ -95,7 +95,7 @@ static void
 redisplayView(PuglTestApp* app, PuglView* view)
 {
   if (!app->continuous) {
-    puglPostRedisplay(view);
+    puglObscureView(view);
   }
 }
 
@@ -115,7 +115,7 @@ onEvent(PuglView* view, const PuglEvent* event)
     break;
   case PUGL_UPDATE:
     if (app->continuous) {
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;
   case PUGL_EXPOSE:
diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h
index b70b91d..49e5fe5 100644
--- a/include/pugl/pugl.h
+++ b/include/pugl/pugl.h
@@ -298,9 +298,9 @@ typedef PuglAnyEvent PuglCloseEvent;
 
    This event is sent to every view near the end of a main loop iteration when
    any pending exposures are about to be redrawn.  It is typically used to mark
-   regions to expose with puglPostRedisplay() or puglPostRedisplayRect().  For
-   example, to continuously animate, a view calls puglPostRedisplay() when an
-   update event is received, and it will then shortly receive an expose event.
+   regions to expose with puglObscureView() or puglPostRedisplayRect().  For
+   example, to continuously animate, obscure the view when an update event is
+   received, and it will receive an expose event shortly afterwards.
 */
 typedef PuglAnyEvent PuglUpdateEvent;
 
@@ -1422,13 +1422,13 @@ puglGetContext(PuglView* view);
 */
 PUGL_API
 PuglStatus
-puglPostRedisplay(PuglView* view);
+puglObscureView(PuglView* view);
 
 /**
    Request a redisplay of the given rectangle within the view.
 
-   This has the same semantics as puglPostRedisplay(), but allows giving a
-   precise region for redrawing only a portion of the view.
+   This has the same semantics as puglObscureView(), but allows giving a precise
+   region for redrawing only a portion of the view.
 */
 PUGL_API
 PuglStatus
@@ -2194,6 +2194,22 @@ puglGetParentWindow(PuglView* view)
   return puglGetParent(view);
 }
 
+/**
+   Request a redisplay for the entire view.
+
+   This will cause an expose event to be dispatched later.  If called from
+   within the event handler, the expose should arrive at the end of the current
+   event loop iteration, though this is not strictly guaranteed on all
+   platforms.  If called elsewhere, an expose will be enqueued to be processed
+   in the next event loop iteration.
+*/
+static inline PUGL_DEPRECATED_BY("puglObscureView")
+PuglStatus
+puglPostRedisplay(PuglView* view)
+{
+  return puglObscureView(view);
+}
+
 #endif // PUGL_DISABLE_DEPRECATED
 
 /**
diff --git a/src/mac.m b/src/mac.m
index 2f43ace..bf8e0f4 100644
--- a/src/mac.m
+++ b/src/mac.m
@@ -1644,7 +1644,7 @@ puglGetTime(const PuglWorld* world)
 }
 
 PuglStatus
-puglPostRedisplay(PuglView* view)
+puglObscureView(PuglView* view)
 {
   [view->impl->drawView setNeedsDisplay:YES];
   return PUGL_SUCCESS;
diff --git a/src/win.c b/src/win.c
index d9f1b75..a0d0778 100644
--- a/src/win.c
+++ b/src/win.c
@@ -1042,7 +1042,7 @@ puglSetViewStyle(PuglView* const view, const PuglViewStyleFlags flags)
   const bool newMaximized = styleIsMaximized(flags);
   if (oldMaximized != newMaximized) {
     ShowWindow(impl->hwnd, newMaximized ? SW_SHOWMAXIMIZED : SW_RESTORE);
-    puglPostRedisplay(view);
+    puglObscureView(view);
   }
 
   return PUGL_SUCCESS;
@@ -1209,7 +1209,7 @@ puglGetTime(const PuglWorld* world)
 }
 
 PuglStatus
-puglPostRedisplay(PuglView* view)
+puglObscureView(PuglView* view)
 {
   InvalidateRect(view->impl->hwnd, NULL, false);
   return PUGL_SUCCESS;
diff --git a/src/x11.c b/src/x11.c
index 6b45fd4..235af39 100644
--- a/src/x11.c
+++ b/src/x11.c
@@ -744,7 +744,7 @@ puglShow(PuglView* const view, const PuglShowCommand command)
     }
 
     if (view->stage == PUGL_VIEW_STAGE_CONFIGURED) {
-      st = puglPostRedisplay(view);
+      st = puglObscureView(view);
     }
   }
 
@@ -1877,7 +1877,7 @@ puglGetTime(const PuglWorld* const world)
 }
 
 PuglStatus
-puglPostRedisplay(PuglView* const view)
+puglObscureView(PuglView* const view)
 {
   PuglRect rect = puglGetFrame(view);
   rect.x        = 0;
diff --git a/test/test_redisplay.c b/test/test_redisplay.c
index 1276136..f17e4c7 100644
--- a/test/test_redisplay.c
+++ b/test/test_redisplay.c
@@ -140,7 +140,7 @@ main(int argc, char** argv)
   }
 
   // Redisplay from outside the event handler
-  puglPostRedisplay(test.view);
+  puglObscureView(test.view);
   while (test.state != REREDISPLAYED) {
     assert(!puglUpdate(test.world, timeout));
   }
diff --git a/test/test_update.c b/test/test_update.c
index 4710ca2..c5997ba 100644
--- a/test/test_update.c
+++ b/test/test_update.c
@@ -63,7 +63,7 @@ onEvent(PuglView* view, const PuglEvent* event)
   case PUGL_UPDATE:
     if (test->state == EXPOSED1) {
       test->state = UPDATED;
-      puglPostRedisplay(view);
+      puglObscureView(view);
     }
     break;