Unify event loop functions as puglUpdate()

The previous separation between polling and dispatching was a lie, especially
on MacOS where it is impossible to only poll for events without dispatching
anything.  Providing such an API is misleading, and problematic in various
other ways.

So, merge them into a single puglUpdate() function which can do the right thing
on all platforms.  This also adds the behaviour of actually processing all
events in the given time interval, which is almost always what clients actually
want to do when using a positive timeout (naively doing this before caused
terrible input lag).

1 files changed, 47 insertions, 17 deletions

diff --git a/pugl/pugl.h b/pugl/pugl.h
index d215749..85d0e8f 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -172,6 +172,7 @@ typedef enum {
 	PUGL_DESTROY,        ///< View destroyed, a #PuglEventAny
 	PUGL_MAP,            ///< View made visible, a #PuglEventAny
 	PUGL_UNMAP,          ///< View made invisible, a #PuglEventAny
+	PUGL_UPDATE,         ///< View ready to draw, a #PuglEventAny
 	PUGL_CONFIGURE,      ///< View moved/resized, a #PuglEventConfigure
 	PUGL_EXPOSE,         ///< View must be drawn, a #PuglEventExpose
 	PUGL_CLOSE,          ///< View will be closed, a #PuglEventAny
@@ -620,12 +621,21 @@ PUGL_API double
 puglGetTime(const PuglWorld* world);
 
 /**
-   Poll for events that are ready to be processed.
+   Update by processing events from the window system.
 
-   This polls for events that are ready for any view in the world, potentially
-   blocking depending on `timeout`.
+   This function is a single iteration of the main loop, and should be called
+   repeatedly to update all views.
 
-   @param world The world to poll for events.
+   If a positive timeout is given, then events will be processed for that
+   amount of time, starting from when this function was called.  For purely
+   event-driven programs, a timeout of -1.0 can be used to block indefinitely
+   until something happens.  For continuously animating programs, a timeout
+   that is a reasonable fraction of the ideal frame period should be used, to
+   minimise input latency by ensuring that as many input events are consumed as
+   possible before drawing.  Plugins should always use a timeout of 0.0 to
+   avoid blocking the host.
+
+   @param world The world to update.
 
    @param timeout Maximum time to wait, in seconds.  If zero, the call returns
    immediately, if negative, the call blocks indefinitely.
@@ -633,18 +643,7 @@ puglGetTime(const PuglWorld* world);
    @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if not, or an error.
 */
 PUGL_API PuglStatus
-puglPollEvents(PuglWorld* world, double timeout);
-
-/**
-   Dispatch any pending events to views.
-
-   This processes all pending events, dispatching them to the appropriate
-   views.  View event handlers will be called in the scope of this call.  This
-   function does not block, if no events are pending then it will return
-   immediately.
-*/
-PUGL_API PuglStatus
-puglDispatchEvents(PuglWorld* world);
+puglUpdate(PuglWorld* world, double timeout);
 
 /**
    @}
@@ -1263,6 +1262,37 @@ PUGL_API PUGL_DEPRECATED_BY("puglDispatchEvents") PuglStatus
 puglProcessEvents(PuglView* view);
 
 /**
+   Poll for events that are ready to be processed.
+
+   This polls for events that are ready for any view in the world, potentially
+   blocking depending on `timeout`.
+
+   @param world The world to poll for events.
+
+   @param timeout Maximum time to wait, in seconds.  If zero, the call returns
+   immediately, if negative, the call blocks indefinitely.
+
+   @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if not, or an error.
+
+   @deprecated Use puglUpdate().
+*/
+PUGL_API PUGL_DEPRECATED_BY("puglUpdate") PuglStatus
+puglPollEvents(PuglWorld* world, double timeout);
+
+/**
+   Dispatch any pending events to views.
+
+   This processes all pending events, dispatching them to the appropriate
+   views.  View event handlers will be called in the scope of this call.  This
+   function does not block, if no events are pending then it will return
+   immediately.
+
+   @deprecated Use puglUpdate().
+*/
+PUGL_API PUGL_DEPRECATED_BY("puglUpdate") PuglStatus
+puglDispatchEvents(PuglWorld* world);
+
+/**
    Enter the graphics context.
 
    Note that, unlike some similar libraries, Pugl automatically enters and