Platform: make viewportEvent() only optional.

Don't do anything to respond to viewport size by default, as the window
has fixed size in most cases anyway (always fullscreen, canvas of fixed
size in browser etc.). Makes the initial implementation requirements
much simpler and shorter.

doc/platform.dox

@@ -47,10 +47,9 @@ Windowed applications provide a window and keyboard and mouse handling. The
 most basic toolkit (and toolkit packaged for most systems) is GLUT, which is
 implemented in @ref Platform::GlutApplication. As said above, the usage is
 similar for all toolkits, you must provide one-argument constructor and
-implement at least @ref GlutApplication::viewportEvent() "viewportEvent()" and
+implement at least @ref GlutApplication::drawEvent() "drawEvent()" function.
-@ref GlutApplication::drawEvent() "drawEvent()". The class can be then used
+The class can be then used directly in `main()`, but for convenience and
-directly in `main()`, but for convenience and portability it's better to use
+portability it's better to use @ref MAGNUM_GLUTAPPLICATION_MAIN() macro.
-@ref MAGNUM_GLUTAPPLICATION_MAIN() macro.
 
 To simplify the porting, the library provides `Platform::Application` typedef
 and `MAGNUM_APPLICATION_MAIN()` macro (but only if only one application header
@@ -78,7 +77,6 @@ class MyApplication: public Platform::Application {
         MyApplication(const Arguments& arguments);
 
     private:
-        void viewportEvent(const Vector2i& viewport) override;
         void drawEvent() override;
 };
 
@@ -87,11 +85,6 @@ MyApplication::MyApplication(const Arguments& arguments): Platform::Application(
     Renderer::setClearColor({0.0f, 0.0f, 0.4f});
 }
 
-void MyApplication::viewportEvent(const Vector2i& size) {
-    // Resize the framebuffer to new window size
-    defaultFramebuffer.setViewport({{}, size});
-}
-
 void MyApplication::drawEvent() {
     // Clear the window
     defaultFramebuffer.clear(DefaultFramebuffer::Clear::Color);
@@ -104,6 +97,28 @@ void MyApplication::drawEvent() {
 MAGNUM_APPLICATION_MAIN(MyApplication)
 @endcode
 
+@subsection platform-windowed-viewport Responding to viewport size changes
+
+By default the application doesn't respond to window size changes in any way,
+as the window has fixed size in most cases. To respond to size change for
+example by resizing the default framebuffer, you need to reimplement
+@ref GlutApplication::viewportEvent() "viewportEvent()" function and pass the
+new size to the framebuffer:
+@code
+class MyApplication: public Platform::Application {
+    // ...
+
+    private:
+        void viewportEvent(const Vector2i& size) override;
+};
+
+// ...
+
+void MyApplication::viewportEvent(const Vector2i& size) {
+    defaultFramebuffer.setViewport({{}, size});
+}
+@endcode
+
 @section platform-windowless Windowless applications
 
 Windowless applications provide just a context for ofscreen rendering or

src/Platform/AbstractXApplication.cpp

@@ -169,6 +169,7 @@ int AbstractXApplication::exec() {
     return 0;
 }
 
+void AbstractXApplication::viewportEvent(const Vector2i&) {}
 void AbstractXApplication::keyPressEvent(KeyEvent&) {}
 void AbstractXApplication::keyReleaseEvent(KeyEvent&) {}
 void AbstractXApplication::mousePressEvent(MouseEvent&) {}

src/Platform/AbstractXApplication.h

@@ -125,7 +125,7 @@ class AbstractXApplication {
     private:
     #endif
         /** @copydoc Sdl2Application::viewportEvent() */
-        virtual void viewportEvent(const Vector2i& size) = 0;
+        virtual void viewportEvent(const Vector2i& size);
 
         /** @copydoc Sdl2Application::drawEvent() */
         virtual void drawEvent() = 0;

src/Platform/GlutApplication.cpp

@@ -111,6 +111,7 @@ void GlutApplication::staticMouseMoveEvent(int x, int y) {
     instance->mouseMoveEvent(e);
 }
 
+void GlutApplication::viewportEvent(const Vector2i&) {}
 void GlutApplication::keyPressEvent(KeyEvent&) {}
 void GlutApplication::keyReleaseEvent(KeyEvent&) {}
 void GlutApplication::mousePressEvent(MouseEvent&) {}

src/Platform/GlutApplication.h

@@ -58,13 +58,14 @@ in CMake, add `${MAGNUM_GLUTAPPLICATION_INCLUDE_DIRS}` to include path and link
 to `${MAGNUM_GLUTAPPLICATION_LIBRARIES}`. If no other application is requested,
 you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section GlutApplication-usage Usage
 
-You need to implement at least @ref drawEvent() and @ref viewportEvent() to be
+You need to implement at least @ref drawEvent() to be able to draw on the
-able to draw on the screen. The subclass can be then used directly in `main()`
+screen. The subclass can be then used directly in `main()` -- see convenience
--- see convenience macro @ref MAGNUM_GLUTAPPLICATION_MAIN().
+macro @ref MAGNUM_GLUTAPPLICATION_MAIN(). See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::GlutApplication {
     // implement required methods...
@@ -151,7 +152,7 @@ class GlutApplication {
     private:
     #endif
         /** @copydoc Sdl2Application::viewportEvent() */
-        virtual void viewportEvent(const Vector2i& size) = 0;
+        virtual void viewportEvent(const Vector2i& size);
 
         /** @copydoc Sdl2Application::drawEvent() */
         virtual void drawEvent() = 0;

src/Platform/GlxApplication.h

@@ -46,13 +46,14 @@ CMake. To use it, you need to request `%GlxApplication` component in CMake, add
 `${MAGNUM_GLXAPPLICATION_LIBRARIES}`. If no other application is requested, you
 can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section GlxApplication-usage Usage
 
-You need to implement at least @ref drawEvent() and @ref viewportEvent() to be
+You need to implement at least @ref drawEvent() to be able to draw on the
-able to draw on the screen. The subclass can be then used directly in `main()`
+screen. The subclass can be then used directly in `main()` -- see convenience
--- see convenience macro @ref MAGNUM_GLXAPPLICATION_MAIN().
+macro @ref MAGNUM_GLXAPPLICATION_MAIN(). See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::GlxApplication {
     // implement required methods...

src/Platform/NaClApplication.cpp

@@ -251,6 +251,7 @@ void NaClApplication::mouseLockCallback(void* applicationInstance, std::int32_t)
     instance->flags |= Flag::MouseLocked;
 }
 
+void NaClApplication::viewportEvent(const Vector2i&) {}
 void NaClApplication::keyPressEvent(KeyEvent&) {}
 void NaClApplication::keyReleaseEvent(KeyEvent&) {}
 void NaClApplication::mousePressEvent(MouseEvent&) {}

src/Platform/NaClApplication.h

@@ -63,13 +63,14 @@ to request `%NaClApplication` component in CMake, add
 `${MAGNUM_NACLAPPLICATION_LIBRARIES}`. If no other application is requested,
 you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section NaClApplication-usage Usage
 
-You need to implement at least @ref drawEvent() and @ref viewportEvent() to be
+You need to implement at least @ref drawEvent() to be able to draw on the
-able to draw on the screen. The subclass must be then registered to NaCl API
+screen. The subclass must be then registered to NaCl API using
-using @ref MAGNUM_NACLAPPLICATION_MAIN() macro.
+@ref MAGNUM_NACLAPPLICATION_MAIN() macro. See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::NaClApplication {
     // implement required methods...
@@ -218,7 +219,7 @@ class NaClApplication: public pp::Instance, public pp::Graphics3DClient, public
     private:
     #endif
         /** @copydoc Sdl2Application::viewportEvent() */
-        virtual void viewportEvent(const Vector2i& size) = 0;
+        virtual void viewportEvent(const Vector2i& size);
 
         /** @copydoc Sdl2Application::drawEvent() */
         virtual void drawEvent() = 0;

src/Platform/ScreenedApplication.h

@@ -170,15 +170,11 @@ template<class Application> class BasicScreenedApplication: public Application,
          * @brief Global viewport event
          *
          * Called when window size changes, *before* all screens'
-         * @ref BasicScreen::viewportEvent() "viewportEvent()". You should at
+         * @ref BasicScreen::viewportEvent() "viewportEvent()". Default
-         * least pass the new size to @ref DefaultFramebuffer::setViewport().
+         * implementation does nothing. See @ref Sdl2Application::viewportEvent() "*Application::viewportEvent()"
-         *
+         * for more information.
-         * Note that this function might not get called at all if the window
-         * size doesn't change. You are responsible for configuring the initial
-         * state yourself, viewport of default framebuffer can be retrieved
-         * from @ref DefaultFramebuffer::viewport().
          */
-        virtual void globalViewportEvent(const Vector2i& size) = 0;
+        virtual void globalViewportEvent(const Vector2i& size);
 
         /**
          * @brief Draw event

src/Platform/ScreenedApplication.hpp

@@ -72,6 +72,8 @@ template<class Application> BasicScreenedApplication<Application>& BasicScreened
     return *this;
 }
 
+template<class Application> void BasicScreenedApplication<Application>::globalViewportEvent(const Vector2i&) {}
+
 template<class Application> void BasicScreenedApplication<Application>::viewportEvent(const Vector2i& size) {
     /* Call viewport event after all other (because of framebuffer resizing) */
     globalViewportEvent(size);

src/Platform/Sdl2Application.cpp

@@ -244,6 +244,7 @@ void Sdl2Application::setMouseLocked(bool enabled) {
     #endif
 }
 
+void Sdl2Application::viewportEvent(const Vector2i&) {}
 void Sdl2Application::keyPressEvent(KeyEvent&) {}
 void Sdl2Application::keyReleaseEvent(KeyEvent&) {}
 void Sdl2Application::mousePressEvent(MouseEvent&) {}

src/Platform/Sdl2Application.h

@@ -64,13 +64,14 @@ to find SDL2), request `%Sdl2Application` component in CMake, add
 `${MAGNUM_SDL2APPLICATION_LIBRARIES}`. If no other application is requested,
 you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section Sdl2Application-usage Usage
 
-You need to implement at least @ref drawEvent() and @ref viewportEvent() to be
+You need to implement at least @ref drawEvent() to be able to draw on the
-able to draw on the screen. The subclass can be then used directly in `main()`
+screen. The subclass can be then used directly in `main()` -- see convenience
--- see convenience macro @ref MAGNUM_SDL2APPLICATION_MAIN().
+macro @ref MAGNUM_SDL2APPLICATION_MAIN(). See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::Sdl2Application {
     // implement required methods...
@@ -235,16 +236,19 @@ class Sdl2Application {
         /**
          * @brief Viewport event
          *
-         * Called when window size changes. You should pass the new size to
+         * Called when window size changes. The default implementation does
-         * @ref DefaultFramebuffer::setViewport() and possibly elsewhere
+         * nothing, if you want to respond to size changes, you should pass the
-         * (cameras, other framebuffers...).
+         * new size to @ref DefaultFramebuffer::setViewport() and possibly
+         * elsewhere (to @ref SceneGraph::AbstractCamera::setViewport() "SceneGraph::Camera*D::setViewport()",
+         * other framebuffers...).
          *
          * Note that this function might not get called at all if the window
-         * size doesn't change. You are responsible for configuring the initial
+         * size doesn't change. You should configure the initial state of your
-         * state yourself, viewport of default framebuffer can be retrieved
+         * cameras, framebuffers etc. in application constructor rather than
-         * from @ref DefaultFramebuffer::viewport().
+         * relying on this function to be called. Viewport of default
+         * framebuffer can be retrieved via @ref DefaultFramebuffer::viewport().
          */
-        virtual void viewportEvent(const Vector2i& size) = 0;
+        virtual void viewportEvent(const Vector2i& size);
 
         /**
          * @brief Draw event

src/Platform/WindowlessGlxApplication.h

@@ -56,12 +56,13 @@ include path and link to `${MAGNUM_WINDOWLESSGLXAPPLICATION_LIBRARIES}`. If no
 other windowless application is requested, you can also use generic
 `${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section WindowlessGlxApplication-usage Usage
 
 Place your code into @ref exec(). The subclass can be then used directly in
 `main()` -- see convenience macro @ref MAGNUM_WINDOWLESSGLXAPPLICATION_MAIN().
+See @ref platform for more information.
 @code
 class MyApplication: public Platform::WindowlessGlxApplication {
     // implement required methods...

src/Platform/WindowlessNaClApplication.h

@@ -60,12 +60,13 @@ you need to request `%WindowlessNaClApplication` component in CMake, add
 application is requested, you can also use generic
 `${MAGNUM_WINDOWLESSAPPLICATION_INCLUDE_DIRS}` and
 `${MAGNUM_WINDOWLESSAPPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section WindowlessNaClApplication-usage Usage
 
 Place your code into @ref exec(). The subclass must be then registered to NaCl
-API using @ref MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() macro.
+API using @ref MAGNUM_WINDOWLESSNACLAPPLICATION_MAIN() macro. See @ref platform
+for more information.
 @code
 class MyApplication: public Platform::WindowlessNaClApplication {
     // implement required methods...

src/Platform/XEglApplication.h

@@ -47,13 +47,14 @@ request `%XEglApplication` component in CMake, add `${MAGNUM_XEGLAPPLICATION_INC
 to include path and link to `${MAGNUM_XEGLAPPLICATION_LIBRARIES}`.  If no other
 application is requested, you can also use generic `${MAGNUM_APPLICATION_INCLUDE_DIRS}`
 and `${MAGNUM_APPLICATION_LIBRARIES}` aliases to simplify porting. See
-@ref building, @ref cmake and @ref platform for more information.
+@ref building and @ref cmake for more information.
 
 @section XEglApplication-usage Usage
 
-You need to implement at least @ref drawEvent() and @ref viewportEvent() to be
+You need to implement at least @ref drawEvent() to be able to draw on the
-able to draw on the screen.  The subclass can be then used directly in `main()`
+screen.  The subclass can be then used directly in `main()` -- see convenience
--- see convenience macro @ref MAGNUM_XEGLAPPLICATION_MAIN().
+macro @ref MAGNUM_XEGLAPPLICATION_MAIN(). See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::XEglApplication {
     // implement required methods...