Cleanup of WindowWrapper classes

include/openspace/engine/wrapper/windowwrapper.h

@@ -33,34 +33,124 @@
 
 namespace openspace {
 
+/**
+ * A WindowWrapper is a class that handles the abstraction between OpenSpace and a
+ * specific window creation framework.<br>
+ * Every new windowing framework needs to have its own WindowWrapper subclass exposing the
+ * required features.
+ */
 class WindowWrapper {
 public:
-    virtual void setBarrier(bool enabled) = 0;
-    virtual void clearAllWindows() = 0;
+    /**
+     * This method enables or disables a framelock barrier. If the specific windowing
+     * framework does not provide a framelock, this method defaults to a no-op.
+     * \param enabled If <code>true</code> the framelock is enabled, <code>false</code>
+     * disables it
+     */
+    virtual void setBarrier(bool enabled);
+    
+    /**
+     * This method clears all the rendering windows with the specified \p clearColor. In
+     * most OpenGL cases, this will end up with one or mode <code>glClear</code> calls.
+     * \param clearColor The color with which to clear all windows
+     */
+    virtual void clearAllWindows(const glm::vec4& clearColor) = 0;
+    
+    /**
+     * Returns whether the current window has been resized recently.
+     * \return <code>true</code> if the current window has been resized recently,
+     * <code>false</code> otherwise
+     */
     virtual bool windowHasResized() const = 0;
-    virtual double time() const = 0;
-    virtual double averageDeltaTime() const = 0;
-    virtual uint32_t mouseButtons(int maxNumber = 8) const = 0;
-    virtual glm::vec2 mousePosition() const = 0;
-    virtual glm::ivec2 currentWindowSize() const = 0;
-    virtual glm::ivec2 currentWindowResolution() const = 0;
-    virtual bool isRegularRendering() const = 0;
 
+    /**
+     * Returns the average frametime in seconds.
+     * \return The average frametime in seconds
+     */
+    virtual double averageDeltaTime() const = 0;
+
+    /**
+     * Returns the location of the mouse cursor in pixel screen coordinates.
+     * \return The location of the mouse cursor in pixel screen coordinates
+     */
+    virtual glm::vec2 mousePosition() const = 0;
+    
+    /**
+     * Returns a bitmask of the status of all available mouse buttons. Bit <code>i</code>
+     * is <code>1</code> if mouse button <code>i</code> is pressed down;
+     * <code>false</code> otherwise.
+     * \param maxNumber The maximum number of mouse buttons that should be queried 
+     * \return A bitmask showing the status of all mouse buttons (up to \p maxNumber)
+     */
+    virtual uint32_t mouseButtons(int maxNumber = 8) const = 0;
+    
+    /**
+     * Returns the size of the currently active window in pixel coordinates.
+     * \return The size of the currently active window in pixel coordinates
+     */
+    virtual glm::ivec2 currentWindowSize() const = 0;
+    
+    /**
+     * Returns the resolution of the currently active window in pixel coordinates.
+     * \return The resolution of the currently active window in pixel coordinates
+     */
+    virtual glm::ivec2 currentWindowResolution() const;
+    
+    /**
+     * Returns <code>true</code> if the current rendering method is regular, i.e., it is
+     * a flat projection without non-linear distortions. Returns <code>false</code> in
+     * other cases, for example fisheye projections.
+     * \return Whether the current rendering method is a regular method
+     */
+    virtual bool isRegularRendering() const;
+
+    /**
+     * Returns the currently employed view-projection matrix.
+     * \return The currently employed view-projection matrix
+     */
     virtual glm::mat4 viewProjectionMatrix() const = 0;
+    
+    /**
+     * Sets the near and far clipping planes of the rendering window.
+     * \param near The near clipping plane
+     * \param far The far clipping plane
+     */
     virtual void setNearFarClippingPlane(float near, float far) = 0;
     
-    virtual glm::ivec4 viewportPixelCoordinates() const = 0;
+    /**
+     * Returns the location and size of the current viewport (<code>x</code>,
+     * <code>width</code>, <code>y</code>, and <code>height</code>). If there is only a
+     * single viewport, <code>x</code> and <code>y</code> are <code>0</code> whereas
+     * <code>width</code> and <code>height</code> are equal to #currentWindowResolution.
+     * \return The location and size of the current viewport
+     */
+    virtual glm::ivec4 viewportPixelCoordinates() const;
     
-    virtual bool isExternalControlConnected() const = 0;
-    virtual void sendMessageToExternalControl(const std::vector<char>& message) const = 0;
+    /**
+     * Returns <code>true</code> if there is an external control connected, i.e., an
+     * application that can receive control commands.
+     * \return If there is an external control connected
+     */
+    virtual bool isExternalControlConnected() const;
     
-    // true for single viewport, single window; false otherwise
-    virtual bool isSimpleRendering() const = 0;
+    /**
+     * Sends a \p message to an external control.
+     * \param message The message to be sent
+     */
+    virtual void sendMessageToExternalControl(const std::vector<char>& message) const;
     
+    /**
+     * Returns <code>true</code> if the rendering is a single viewport with an single
+     * window; <code>false</code> otherwise.
+     * \returns <code>true</code> if the rendering is a single viewport with an single
+     * widnow; <code>false</code> otherwise
+     */
+    virtual bool isSimpleRendering() const;
+
+    /**
+     * Advises the windowing system to take a screenshot.
+     */
     virtual void takeScreenshot() const = 0;
-    
-    //virtual void forEachWindow(std::function<void (void)> function) = 0;
-    
 };
 
 } // namespace openspace