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
-@ref GlutApplication::drawEvent() "drawEvent()". The class can be then used
-directly in `main()`, but for convenience and portability it's better to use
-@ref MAGNUM_GLUTAPPLICATION_MAIN() macro.
+implement at least @ref GlutApplication::drawEvent() "drawEvent()" function.
+The class can be then used directly in `main()`, but for convenience and
+portability it's better to use @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
-able to draw on the screen. The subclass can be then used directly in `main()`
--- see convenience macro @ref MAGNUM_GLUTAPPLICATION_MAIN().
+You need to implement at least @ref drawEvent() to be able to draw on the
+screen. The subclass can be then used directly in `main()` -- see convenience
+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
-able to draw on the screen. The subclass can be then used directly in `main()`
--- see convenience macro @ref MAGNUM_GLXAPPLICATION_MAIN().
+You need to implement at least @ref drawEvent() to be able to draw on the
+screen. The subclass can be then used directly in `main()` -- see convenience
+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
-able to draw on the screen. The subclass must be then registered to NaCl API
-using @ref MAGNUM_NACLAPPLICATION_MAIN() macro.
+You need to implement at least @ref drawEvent() to be able to draw on the
+screen. The subclass must be then registered to NaCl API using
+@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
-         * least pass the new size to @ref DefaultFramebuffer::setViewport().
-         *
-         * 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().
+         * @ref BasicScreen::viewportEvent() "viewportEvent()". Default
+         * implementation does nothing. See @ref Sdl2Application::viewportEvent() "*Application::viewportEvent()"
+         * for more information.
          */
-        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
-able to draw on the screen. The subclass can be then used directly in `main()`
--- see convenience macro @ref MAGNUM_SDL2APPLICATION_MAIN().
+You need to implement at least @ref drawEvent() to be able to draw on the
+screen. The subclass can be then used directly in `main()` -- see convenience
+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
-         * @ref DefaultFramebuffer::setViewport() and possibly elsewhere
-         * (cameras, other framebuffers...).
+         * Called when window size changes. The default implementation does
+         * nothing, if you want to respond to size changes, you should pass the
+         * 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
-         * state yourself, viewport of default framebuffer can be retrieved
-         * from @ref DefaultFramebuffer::viewport().
+         * size doesn't change. You should configure the initial state of your
+         * cameras, framebuffers etc. in application constructor rather than
+         * 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
-able to draw on the screen.  The subclass can be then used directly in `main()`
--- see convenience macro @ref MAGNUM_XEGLAPPLICATION_MAIN().
+You need to implement at least @ref drawEvent() to be able to draw on the
+screen.  The subclass can be then used directly in `main()` -- see convenience
+macro @ref MAGNUM_XEGLAPPLICATION_MAIN(). See @ref platform for more
+information.
 @code
 class MyApplication: public Platform::XEglApplication {
     // implement required methods...