From 049a3f8fce1ac43a009098c7b9122838b16ac8fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 21 Oct 2024 23:27:43 +0200 Subject: [PATCH] Platform: document why tickEvent() isn't private. I attempted to make it private only to discover it was used by Magnum Player to make the workflow with opt-in tweakable constants more efficient. So let's document that. --- doc/snippets/Platform.cpp | 30 +++++++++++++++++++++++++++ src/Magnum/Platform/GlfwApplication.h | 17 +++++++++++++++ src/Magnum/Platform/Sdl2Application.h | 17 +++++++++++++++ 3 files changed, 64 insertions(+) diff --git a/doc/snippets/Platform.cpp b/doc/snippets/Platform.cpp index 24ce9b188..cceadb69b 100644 --- a/doc/snippets/Platform.cpp +++ b/doc/snippets/Platform.cpp @@ -26,6 +26,11 @@ #define DOXYGEN_ELLIPSIS(...) __VA_ARGS__ +#include +#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT)) || defined(CORRADE_TARGET_EMSCRIPTEN) +#include +#endif + /* [windowed] */ #include #include @@ -236,3 +241,28 @@ MyApplication::MyApplication(const Arguments& arguments): /* [exit-from-constructor] */ } + +#if defined(CORRADE_TARGET_UNIX) || (defined(CORRADE_TARGET_WINDOWS) && !defined(CORRADE_TARGET_WINDOWS_RT)) || defined(CORRADE_TARGET_EMSCRIPTEN) +namespace H { + +struct MyApplication: Platform::Application { + MyApplication(const Arguments& arguments); + + void tickEvent() override; + + Utility::Tweakable _tweakable; +}; + +/* [tickEvent-conditional] */ +void MyApplication::tickEvent() { + if(!_tweakable.isEnabled()) { + Platform::Application::tickEvent(); + return; + } + + _tweakable.update(); +} +/* [tickEvent-conditional] */ + +} +#endif diff --git a/src/Magnum/Platform/GlfwApplication.h b/src/Magnum/Platform/GlfwApplication.h index 80b3ea403..2dc833008 100644 --- a/src/Magnum/Platform/GlfwApplication.h +++ b/src/Magnum/Platform/GlfwApplication.h @@ -929,6 +929,23 @@ class GlfwApplication { * will effectively stop the tick event from being fired and the app * returns back to waiting for input events. This can be used to * disable the tick event when not needed. + * + * @m_class{m-block m-success} + * + * @par Opting out of tick events at runtime + * Unlike other event handlers, this function isn't @cpp private @ce + * in order to allow subclasses to conditionally disable the tick + * event by calling the base implementation. To the application it + * looks the same as if the tick event wasn't overriden at all, + * which effectively results in the function not being called ever + * again. This is useful for example with + * @relativeref{Corrade,Utility::Tweakable}, where periodical + * polling for file updates doesn't need to be done if tweakable + * constants aren't enabled at all. + * @par + * @snippet Platform.cpp tickEvent-conditional + * @par + * It's not possible to re-enable the tick event afterwards. */ virtual void tickEvent(); diff --git a/src/Magnum/Platform/Sdl2Application.h b/src/Magnum/Platform/Sdl2Application.h index 2ceea761c..54702f434 100644 --- a/src/Magnum/Platform/Sdl2Application.h +++ b/src/Magnum/Platform/Sdl2Application.h @@ -1448,6 +1448,23 @@ class Sdl2Application { * will effectively stop the tick event from being fired and the app * returns back to waiting for input events. This can be used to * disable the tick event when not needed. + * + * @m_class{m-block m-success} + * + * @par Opting out of tick events at runtime + * Unlike other event handlers, this function isn't @cpp private @ce + * in order to allow subclasses to conditionally disable the tick + * event by calling the base implementation. To the application it + * looks the same as if the tick event wasn't overriden at all, + * which effectively results in the function not being called ever + * again. This is useful for example with + * @relativeref{Corrade,Utility::Tweakable}, where periodical + * polling for file updates doesn't need to be done if tweakable + * constants aren't enabled at all. + * @par + * @snippet Platform.cpp tickEvent-conditional + * @par + * It's not possible to re-enable the tick event afterwards. */ virtual void tickEvent();