diff options
author | David Robillard <d@drobilla.net> | 2021-01-06 23:53:31 +0100 |
---|---|---|
committer | David Robillard <d@drobilla.net> | 2021-01-06 23:53:31 +0100 |
commit | d2a6fd3f725f7f174535c49d78d07567e12c84d8 (patch) | |
tree | 8ebbe1d224363f94610e64af167a2592390787b4 /doc/cpp/event-loop.rst | |
parent | 31d059bf849045f45c8c9db361efd093e88a109c (diff) | |
download | pugl-d2a6fd3f725f7f174535c49d78d07567e12c84d8.tar.gz pugl-d2a6fd3f725f7f174535c49d78d07567e12c84d8.tar.bz2 pugl-d2a6fd3f725f7f174535c49d78d07567e12c84d8.zip |
Split overview into multiple documents
Diffstat (limited to 'doc/cpp/event-loop.rst')
-rw-r--r-- | doc/cpp/event-loop.rst | 37 |
1 files changed, 37 insertions, 0 deletions
diff --git a/doc/cpp/event-loop.rst b/doc/cpp/event-loop.rst new file mode 100644 index 0000000..1d2ac41 --- /dev/null +++ b/doc/cpp/event-loop.rst @@ -0,0 +1,37 @@ +.. default-domain:: cpp +.. highlight:: cpp +.. namespace:: pugl + +###################### +Driving the Event Loop +###################### + +Pugl does not contain any threads or other event loop "magic". +For flexibility, the event loop is driven manually by repeatedly calling :func:`World::update`, +which processes events from the window system and dispatches them to views when necessary. + +The exact use of :func:`World::update` depends on the application. +Plugins typically call it with a ``timeout`` of 0 in a callback driven by the host. +This avoids blocking the main loop, +since other plugins and the host itself need to run as well. + +A program can use whatever timeout is appropriate: +event-driven applications may wait forever by using a ``timeout`` of -1, +while those that draw continuously may use a significant fraction of the frame period +(with enough time left over to render). + +********* +Redrawing +********* + +Occasional redrawing can be requested by calling :func:`View::postRedisplay` or :func:`View::postRedisplayRect`. +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`. +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. |