Changeset 1622

Timestamp:

Jun 25, 2008, 9:07:55 PM (16 years ago)

Author:

rgrieder

Message:

Added documentation for OrxonoxOverlay and clarified the size/actual size mess.

Location:

code/branches/hud/src/orxonox/overlays

Files:

• OrxonoxOverlay.cc (modified) (15 diffs)
• OrxonoxOverlay.h (modified) (3 diffs)
• OverlayText.cc (modified) (1 diff)
• OverlayText.h (modified) (1 diff)
• hud/HUDNavigation.cc (modified) (1 diff)

code/branches/hud/src/orxonox/overlays/OrxonoxOverlay.cc

@@ -27 +27 @@
  */
 
+/**
+@file
+@brief Definition of the OrxonoxOverlay class.
+*/
+
 #include "OrxonoxStableHeaders.h"
 #include "OrxonoxOverlay.h"
 
 #include <cmath>
+#include <OgreOverlay.h>
 #include <OgreOverlayManager.h>
 #include <OgrePanelOverlayElement.h>
@@ -52 +58 @@
         : overlay_(0)
         , background_(0)
-        , windowAspectRatio_(1.0f)
-        , bCorrectAspect_(false)
-        , size_(1.0f, 1.0f)
-        , sizeCorrection_(1.0f, 1.0f)
-        , angle_(0.0f)
-        , position_(0.0f, 0.0f)
-        , origin_(0.0f, 0.0f)
     {
         RegisterObject(OrxonoxOverlay);
     }
 
+    /**
+    @brief
+        Make sure everything gets removed/destroyed.
+    @remark
+        We assume that the Ogre::OverlayManager exists (there is an assert in Ogre for that!)
+    */
     OrxonoxOverlay::~OrxonoxOverlay()
     {
-        if (this->background_)
-            Ogre::OverlayManager::getSingleton().destroyOverlayElement(this->background_);
-
+        // erase ourself from the map with all overlays
         std::map<std::string, OrxonoxOverlay*>::iterator it = overlays_s.find(this->getName());
         if (it != overlays_s.end())
             overlays_s.erase(it);
-    }
-
+
+        if (this->background_)
+            Ogre::OverlayManager::getSingleton().destroyOverlayElement(this->background_);
+        if (this->overlay_)
+            Ogre::OverlayManager::getSingleton().destroy(this->overlay_);
+    }
+
+    /**
+    @brief
+        Loads the OrxonoxOverlay.
+        
+        This has to be called before usage, otherwise strange behaviour is
+        guaranteed! (there should be no segfaults however).
+    @copydoc
+        BaseObject::XMLPort()
+    */
     void OrxonoxOverlay::XMLPort(Element& xmlElement, XMLPort::Mode mode)
     {
@@ -79 +96 @@
         if (mode == XMLPort::LoadObject)
         {
+            // set some default values
+            this->windowAspectRatio_ = 1.0f;
+            this->bCorrectAspect_    = false;
+            this->size_              = Vector2(1.0f, 1.0f);
+            this->sizeCorrection_    = Vector2(1.0f, 1.0f);
+            this->position_          = Vector2(0.0f, 0.0f);
+            this->pickPoint_         = Vector2(0.0f, 0.0f);
+            this->angle_             = Radian(0.0f);
+
+            // add this overlay to the static map of OrxonoxOverlays
             if (overlays_s.find(this->getName()) != overlays_s.end())
             {
@@ -85 +112 @@
             overlays_s[this->getName()] = this;
 
+            // create the Ogre::Overlay
             overlay_ = Ogre::OverlayManager::getSingleton().create("OrxonoxOverlay_overlay_"
                 + convertToString(hudOverlayCounter_s++));
 
-            // create background
+            // create background panel (can be used to show any picture)
             this->background_ = static_cast<Ogre::PanelOverlayElement*>(
                 Ogre::OverlayManager::getSingleton().createOverlayElement("Panel",
@@ -94 +122 @@
             this->overlay_->add2D(this->background_);
 
+            // We'll have to get the aspect ratio for the first. Afterwards windowResized() gets
+            // called automatically by the GraphicsEngine.
             this->windowResized(GraphicsEngine::getSingleton().getWindowWidth(),
                 GraphicsEngine::getSingleton().getWindowHeight());
@@ -99 +129 @@
 
         XMLPortParam(OrxonoxOverlay, "correctAspect", setAspectCorrection, getAspectCorrection, xmlElement, mode);
-        XMLPortParam(OrxonoxOverlay, "size", setSize, getUncorrectedSize, xmlElement, mode);
+        XMLPortParam(OrxonoxOverlay, "size", setSize, getSize, xmlElement, mode);
         XMLPortParam(OrxonoxOverlay, "rotation", setRotation, getRotation, xmlElement, mode);
-        XMLPortParam(OrxonoxOverlay, "origin", setOrigin, getOrigin, xmlElement, mode);
+        // see setPickPoint()
+        XMLPortParam(OrxonoxOverlay, "pickPoint", setPickPoint, getPickPoint, xmlElement, mode);
         XMLPortParam(OrxonoxOverlay, "position", setPosition, getPosition, xmlElement, mode);
         XMLPortParam(OrxonoxOverlay, "background", setBackgroundMaterial, getBackgroundMaterial, xmlElement, mode);
@@ -107 +138 @@
         if (mode == XMLPort::LoadObject)
         {
-            this->overlay_->show();
-            if (!this->isVisible())
-                this->overlay_->hide();
-
+            // call all the virtual 'setters'
+            this->changedVisibility();
+            this->angleChanged();
             this->sizeCorrectionChanged();
             this->sizeChanged();
+            // probably gets called 4 times (by all the methods), but sizeChanged() could be overwritten.
             this->positionChanged();
-            this->angleChanged();
         }
     }
 
+    //! Only sets the background material name if not ""
     void OrxonoxOverlay::setBackgroundMaterial(const std::string& material)
     {
@@ -124 +155 @@
     }
 
+    //! Returns the the material name of the background
     const std::string& OrxonoxOverlay::getBackgroundMaterial() const
     {
@@ -132 +164 @@
     }
 
+    //! Called by BaseObject when visibility has changed.
     void OrxonoxOverlay::changedVisibility()
     {
-        if (this->overlay_)
-        {
-            if (this->isVisible())
-                this->overlay_->show();
-            else
-                this->overlay_->hide();
-        }
-    }
-
+        if (!this->overlay_)
+            return;
+
+        if (this->isVisible())
+            this->overlay_->show();
+        else
+            this->overlay_->hide();
+    }
+
+    /**
+    @brief
+        Called by the GraphicsEngine whenever the window size changes.
+        Calculates the aspect ratio only.
+    */
     void OrxonoxOverlay::windowResized(int newWidth, int newHeight)
     {
         this->windowAspectRatio_ = newWidth/(float)newHeight;
-
-        this->setAspectCorrection(this->bCorrectAspect_);
-    }
-
-    void OrxonoxOverlay::setAspectCorrection(bool val)
-    {
-        this->bCorrectAspect_ = val;
         this->sizeCorrectionChanged();
     }
 
+    /**
+    @brief
+        Called whenever the rotation angle has changed.
+    */
+    void OrxonoxOverlay::angleChanged()
+    {
+        if (!this->overlay_)
+            return;
+
+        this->overlay_->setRotate(this->angle_);
+        this->sizeCorrectionChanged();
+    }
+
+    /**
+    @brief
+        Called whenever the aspect ratio or the angle has changed.
+        The method calculates a correction factor for the size to compensate
+        for aspect distortion if desired.
+    @remarks
+        This only works when the angle is about 0 or 90 degrees.
+    */
     void OrxonoxOverlay::sizeCorrectionChanged()
     {
@@ -165 +217 @@
             angle -= 180.0 * (int)(angle / 180.0);
 
+            // take the reverse if angle is about 90 degrees
             float tempAspect;
             if (angle > 89.0 && angle < 91.0)
@@ -183 +236 @@
             this->sizeCorrection_ = Vector2::UNIT_SCALE;
         }
+
         this->sizeChanged();
     }
 
     /**
-    @remarks
-        This function can be overriden by any derivative.
+    @brief
+        Sets the overlay size using the actual corrected size.
     */
     void OrxonoxOverlay::sizeChanged()
     {
+        if (!this->overlay_)
+            return;
+
         this->overlay_->setScale(size_.x * sizeCorrection_.x, size_.y * sizeCorrection_.y);
         positionChanged();
@@ -197 +254 @@
 
     /**
-    @remarks
-        This function can be overriden by any derivative.
-    */
-    void OrxonoxOverlay::angleChanged()
-    {
-        this->overlay_->setRotate(this->angle_);
-        this->sizeCorrectionChanged();
-    }
-
-    /**
-    @remarks
-        This function can be overriden by any derivative.
+    @brief
+        Determines the position of the overlay.
+        This works also well when a rotation angle is applied. The overlay always
+        gets aligned correctly as well as possible.
     */
     void OrxonoxOverlay::positionChanged()
     {
+        if (!this->overlay_)
+            return;
+
+        // transform the angle to a range of 0 - pi/2 first.
         float angle = this->angle_.valueRadians();
         if (angle < 0.0)
@@ -218 +271 @@
         if (angle > Ogre::Math::PI * 0.5)
             angle = Ogre::Math::PI - angle;
+        
+        // do some mathematical fiddling for a bounding box
         Vector2 actualSize = size_ * sizeCorrection_;
         float radius = actualSize.length();
         float phi = atan(actualSize.y / actualSize.x);
         Vector2 boundingBox(radius * cos(angle - phi), radius * sin(angle + phi));
-        Vector2 scroll = (position_ - 0.5 - boundingBox * (origin_ - 0.5)) * 2.0;
+
+        // calculate the scrolling offset
+        Vector2 scroll = (position_ - 0.5 - boundingBox * (pickPoint_ - 0.5)) * 2.0;
         this->overlay_->setScroll(scroll.x, -scroll.y);
     }
 
 
+    //########### Console commands ############
+
+    /**
+    @brief
+        Scales an overlay by its name.
+    @param name
+        The name of the overlay defined BaseObject::setName() (usually done with the "name"
+        attribute in the xml file.
+    */
     /*static*/ void OrxonoxOverlay::scaleOverlay(const std::string& name, float scale)
     {
@@ -234 +300 @@
     }
 
+    /**
+    @brief
+        Scrolls an overlay by its name.
+    @param name
+        The name of the overlay defined BaseObject::setName() (usually done with the "name"
+        attribute in the xml file.
+    */
     /*static*/ void OrxonoxOverlay::scrollOverlay(const std::string& name, const Vector2& scroll)
     {
@@ -241 +314 @@
     }
 
+    /**
+    @brief
+        Rotates an overlay by its name.
+    @param name
+        The name of the overlay defined BaseObject::setName() (usually done with the "name"
+        attribute in the xml file.
+    */
     /*static*/ void OrxonoxOverlay::rotateOverlay(const std::string& name, const Degree& angle)
     {

code/branches/hud/src/orxonox/overlays/OrxonoxOverlay.h

@@ -27 +27 @@
  */
 
+/**
+@file
+@brief Declaration of the OrxonoxOverlay class.
+*/
+
 #ifndef _OrxonoxOverlay_H__
 #define _OrxonoxOverlay_H__
@@ -39 +44 @@
 namespace orxonox
 {
+    /**
+    @brief
+        Base class to display content directly onto the screen.
+        This is merely a wrapper of the Ogre::Overlay to implement more features and integrate it
+        in our class hierarchy for xml loading and config values.
+        The mentioned features are:
+        - Automatic positioning depending on the scale and the rotation angle.
+          You can specify a "pick point" relative to the overlay itself. This point will always be exactly
+          at the position (position_) of the overlay. That allows for margin/corner aligment.
+          It even works when a rotation angle is applied.
+        - Virtual methods for changedVisibilty() (BaseObject), angleChanged(), sizeCorrectionChanged(),
+          sizeChanged() and positionChanged(), that can be overridden by any derivative. This enables for
+          custom configurability of the size, position and rotation attributes. For intance, the HUDNavigation
+          should behave differently to sizeChanged() than a standard overlay.
+        - Console commands for scale, rotate and scroll (accessed by name)
+        - Standard Ogre::PanelOverlayElement for a background image (class doesn't have to be derived
+          only for displaying a picture).
+        - Reacts to changes of the window aspect
+        - Last but not least: On demand you can tell the overlay to automatically resale to correct for
+          aspect distortion. E.g. if you play 1024x768 you wouldn't want a round object to be oval.
+          Remark: This can (due to the Ogre::Overlay transformation order) only work for angle that are
+                  multiples of 90 degrees. But it's only a small drawback.
+    */
     class _OrxonoxExport OrxonoxOverlay : public BaseObject, public WindowEventListener
     {
@@ -47 +75 @@
         virtual void XMLPort(Element& xmlElement, XMLPort::Mode mode);
 
+        //! Shows the overlay with an detour to BaseObject::visibility_
         void show() { this->setVisibility(true); }
+        //! Hides the overlay with an detour to BaseObject::visibility_
         void hide() { this->setVisibility(false); }
 
-        void setAspectCorrection(bool val);
-        bool getAspectCorrection() { return this->bCorrectAspect_; }
+        /** Sets whether the aspect of the overlay is corrected.
+            This is for instance useful for round objects that should stay round no matter
+            what the screen resolution is. */
+        void setAspectCorrection(bool val)        { this->bCorrectAspect_ = val; this->sizeCorrectionChanged(); }
+        //! Returns whether the window aspect is corrected
+        bool getAspectCorrection() const          { return this->bCorrectAspect_; }
 
-        /** Sets the position of this overlay. */
-        void setPosition(Vector2 pos) { this->position_ = pos; this->positionChanged(); }
+        //! Sets the position of this overlay on the screen.
+        void setPosition(Vector2 pos)             { this->position_ = pos; this->positionChanged(); }
 
-        /** Gets the current position. */
-        Vector2 getPosition() const { return this->position_; }
+        //! Returns the current position on the screen.
+        const Vector2& getPosition() const        { return this->position_; }
 
-        /** Scrolls the overlay by the offsets provided. */
-        void scroll(Vector2 scroll) { this->position_ += scroll; this->positionChanged(); }
+        //! Scrolls the overlay. @param offset The offset given.
+        void scroll(const Vector2& offset)        { this->position_ += offset; this->positionChanged(); }
 
-        /** Sets the origin point of this overlay. */
-        void setOrigin(Vector2 pos) { this->origin_ = pos; this->positionChanged(); }
+        /** Sets the point in the overlay where to pick it when translating.
+            For instance setting it to (1.0,1.0) means that the lower right corner of the
+            overlay will be put at position_.
+            This primarily helps aligning an overlay to any corner/margin on the screen. */
+        void setPickPoint(const Vector2& position){ this->pickPoint_ = position; this->positionChanged(); }
 
-        /** Gets the origin point of this overlay */
-        Vector2 getOrigin() const { return this->origin_; }
+        //! Gets the pick point of this overlay. @see setPickPoint()
+        const Vector2& getPickPoint() const       { return this->pickPoint_; }
 
-        /** Sets the rotation applied to this overlay.*/
-        void setRotation(const Degree& angle) { this->angle_ = angle; this->angleChanged(); }
+        //! Sets the rotation angle applied to this overlay in degrees.
+        void setRotation(const Degree& angle)     { this->angle_ = angle; this->angleChanged(); }
 
-        /** Gets the rotation applied to this overlay, in degrees.*/
-        const Radian& getRotation() const { return this->angle_; }
+        //! Gets the rotation angle applied to this overlay in degrees.
+        const Radian& getRotation() const         { return this->angle_; }
 
-        /** Adds the passed in angle to the rotation applied to this overlay. */
-        void rotate(const Degree& angle) { this->angle_ += angle; this->angleChanged(); }
+        //! Rotates the overlay by angle degrees.
+        void rotate(const Degree& angle)          { this->angle_ += angle; this->angleChanged(); }
 
-        /** Sets the size of this overlay. */
-        void setSize(const Vector2& size) { this->size_ = size; this->sizeChanged(); }
+        //! Sets the size of this overlay.
+        void setSize(const Vector2& size)         { this->size_ = size; this->sizeChanged(); }
 
-        /** Gets the current size (not corrected) */
-        Vector2 getUncorrectedSize() const { return this->size_; }
+        //! Gets the current size that was set (uncorrected)
+        Vector2 getSize() const                   { return this->size_ * this->sizeCorrection_; }
 
-        /** Gets the current size (corrected) */
-        Vector2 getSize() const { return this->size_ * this->sizeCorrection_; }
+        //! Gets the actual size of the overlay on the screen (corrected)
+        const Vector2& getActualSize() const      { return this->size_; }
 
-        /** Gets the current size correction */
-        Vector2 getSizeCorrection() const { return this->sizeCorrection_; }
+        //! Gets the current size correction (default: 1.0, 1.0)
+        const Vector2& getSizeCorrection() const  { return this->sizeCorrection_; }
 
-        /** Scales the overlay */
-        void scale(Vector2 scale) { this->size_ *= scale; this->sizeChanged(); }
+        //! Scales the overlay by scale.
+        void scale(const Vector2& scale)          { this->size_ *= scale; this->sizeChanged(); }
 
+        //! ConsoleCommand: Accesses the overlay by its name and scales it.
         static void scaleOverlay(const std::string& name, float scale);
+        //! ConsoleCommand: Accesses the overlay by its name and scrolls it.
         static void scrollOverlay(const std::string& name, const Vector2& scroll);
+        //! ConsoleCommand: Accesses the overlay by its name and rotates it.
         static void rotateOverlay(const std::string& name, const Degree& angle);
 
     protected:
         virtual void changedVisibility();
+        virtual void angleChanged();
+        virtual void sizeCorrectionChanged();
         virtual void sizeChanged();
-        virtual void angleChanged();
         virtual void positionChanged();
-        virtual void sizeCorrectionChanged();
 
         void setBackgroundMaterial(const std::string& material);
         const std::string& getBackgroundMaterial() const;
 
-        Ogre::Overlay* overlay_;
-        Ogre::PanelOverlayElement* background_;
-        float windowAspectRatio_;
-        bool bCorrectAspect_;
-        Vector2 size_;
-        Vector2 sizeCorrection_;
-        Radian angle_;
-        Vector2 position_;
-        Vector2 origin_;
+        Ogre::Overlay* overlay_;                   //!< The overlay the entire class is about.
+        Ogre::PanelOverlayElement* background_;    //!< Background image (blank per default).
+
+        float windowAspectRatio_;                  //!< Screen.width / screen.height
+        bool bCorrectAspect_;                      //!< Whether or not to correct the size. @see setAspectCorrection()
+        Vector2 size_;                             //!< Internal size of the overlay.
+        Vector2 sizeCorrection_;                   //!< Value to correct the size because of the window aspect.
+        Vector2 position_;                         //!< Position of the pickPoint on the screen.
+        Vector2 pickPoint_;                        //!< Point on the overlay to pick when translating
+        Radian angle_;                             //!< Rotation angle of the overlay
 
     private:
         void windowResized(int newWidth, int newHeight);
 
-        static unsigned int hudOverlayCounter_s;
+        static unsigned int hudOverlayCounter_s;   //!< Static counter for hud elements
+        /** Contains all the overlays in a map for quick access via console commands.
+            We could also use the ObjectList, but that doesn't guarantee XMLPort(.) was called and is slower. */
         static std::map<std::string, OrxonoxOverlay*> overlays_s;
   };

code/branches/hud/src/orxonox/overlays/OverlayText.cc

@@ -102 +102 @@
     void OverlayText::sizeChanged()
     {
-        this->overlay_->setScale(getSize().y, getSize().y);
+        this->overlay_->setScale(size_.y * sizeCorrection_.y, size_.y * sizeCorrection_.y);
         positionChanged();
     }

code/branches/hud/src/orxonox/overlays/OverlayText.h

@@ -56 +56 @@
 
         void setTextSize(float size) { this->setSize(Vector2(size, size)); }
-        float getTextSize() const    { return this->getUncorrectedSize().y; }
+        float getTextSize() const    { return this->getSize().y; }
 
         Ogre::TextAreaOverlayElement* text_;

code/branches/hud/src/orxonox/overlays/hud/HUDNavigation.cc

@@ -270 +270 @@
     {
         // use size to compensate for apspect ratio if enabled.
-        float xScale = this->getSize().x;
-        float yScale = this->getSize().y;
+        float xScale = this->getActualSize().x;
+        float yScale = this->getActualSize().y;
         if (this->navMarker_)
             navMarker_->setDimensions(navMarkerSize_ * xScale, navMarkerSize_ * yScale);