Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

Ignore:
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:
5 edited

Legend:

Unmodified
Added
Removed
  • code/branches/hud/src/orxonox/overlays/OrxonoxOverlay.cc

    r1618 r1622  
    2727 */
    2828
     29/**
     30@file
     31@brief Definition of the OrxonoxOverlay class.
     32*/
     33
    2934#include "OrxonoxStableHeaders.h"
    3035#include "OrxonoxOverlay.h"
    3136
    3237#include <cmath>
     38#include <OgreOverlay.h>
    3339#include <OgreOverlayManager.h>
    3440#include <OgrePanelOverlayElement.h>
     
    5258        : overlay_(0)
    5359        , background_(0)
    54         , windowAspectRatio_(1.0f)
    55         , bCorrectAspect_(false)
    56         , size_(1.0f, 1.0f)
    57         , sizeCorrection_(1.0f, 1.0f)
    58         , angle_(0.0f)
    59         , position_(0.0f, 0.0f)
    60         , origin_(0.0f, 0.0f)
    6160    {
    6261        RegisterObject(OrxonoxOverlay);
    6362    }
    6463
     64    /**
     65    @brief
     66        Make sure everything gets removed/destroyed.
     67    @remark
     68        We assume that the Ogre::OverlayManager exists (there is an assert in Ogre for that!)
     69    */
    6570    OrxonoxOverlay::~OrxonoxOverlay()
    6671    {
    67         if (this->background_)
    68             Ogre::OverlayManager::getSingleton().destroyOverlayElement(this->background_);
    69 
     72        // erase ourself from the map with all overlays
    7073        std::map<std::string, OrxonoxOverlay*>::iterator it = overlays_s.find(this->getName());
    7174        if (it != overlays_s.end())
    7275            overlays_s.erase(it);
    73     }
    74 
     76
     77        if (this->background_)
     78            Ogre::OverlayManager::getSingleton().destroyOverlayElement(this->background_);
     79        if (this->overlay_)
     80            Ogre::OverlayManager::getSingleton().destroy(this->overlay_);
     81    }
     82
     83    /**
     84    @brief
     85        Loads the OrxonoxOverlay.
     86       
     87        This has to be called before usage, otherwise strange behaviour is
     88        guaranteed! (there should be no segfaults however).
     89    @copydoc
     90        BaseObject::XMLPort()
     91    */
    7592    void OrxonoxOverlay::XMLPort(Element& xmlElement, XMLPort::Mode mode)
    7693    {
     
    7996        if (mode == XMLPort::LoadObject)
    8097        {
     98            // set some default values
     99            this->windowAspectRatio_ = 1.0f;
     100            this->bCorrectAspect_    = false;
     101            this->size_              = Vector2(1.0f, 1.0f);
     102            this->sizeCorrection_    = Vector2(1.0f, 1.0f);
     103            this->position_          = Vector2(0.0f, 0.0f);
     104            this->pickPoint_         = Vector2(0.0f, 0.0f);
     105            this->angle_             = Radian(0.0f);
     106
     107            // add this overlay to the static map of OrxonoxOverlays
    81108            if (overlays_s.find(this->getName()) != overlays_s.end())
    82109            {
     
    85112            overlays_s[this->getName()] = this;
    86113
     114            // create the Ogre::Overlay
    87115            overlay_ = Ogre::OverlayManager::getSingleton().create("OrxonoxOverlay_overlay_"
    88116                + convertToString(hudOverlayCounter_s++));
    89117
    90             // create background
     118            // create background panel (can be used to show any picture)
    91119            this->background_ = static_cast<Ogre::PanelOverlayElement*>(
    92120                Ogre::OverlayManager::getSingleton().createOverlayElement("Panel",
     
    94122            this->overlay_->add2D(this->background_);
    95123
     124            // We'll have to get the aspect ratio for the first. Afterwards windowResized() gets
     125            // called automatically by the GraphicsEngine.
    96126            this->windowResized(GraphicsEngine::getSingleton().getWindowWidth(),
    97127                GraphicsEngine::getSingleton().getWindowHeight());
     
    99129
    100130        XMLPortParam(OrxonoxOverlay, "correctAspect", setAspectCorrection, getAspectCorrection, xmlElement, mode);
    101         XMLPortParam(OrxonoxOverlay, "size", setSize, getUncorrectedSize, xmlElement, mode);
     131        XMLPortParam(OrxonoxOverlay, "size", setSize, getSize, xmlElement, mode);
    102132        XMLPortParam(OrxonoxOverlay, "rotation", setRotation, getRotation, xmlElement, mode);
    103         XMLPortParam(OrxonoxOverlay, "origin", setOrigin, getOrigin, xmlElement, mode);
     133        // see setPickPoint()
     134        XMLPortParam(OrxonoxOverlay, "pickPoint", setPickPoint, getPickPoint, xmlElement, mode);
    104135        XMLPortParam(OrxonoxOverlay, "position", setPosition, getPosition, xmlElement, mode);
    105136        XMLPortParam(OrxonoxOverlay, "background", setBackgroundMaterial, getBackgroundMaterial, xmlElement, mode);
     
    107138        if (mode == XMLPort::LoadObject)
    108139        {
    109             this->overlay_->show();
    110             if (!this->isVisible())
    111                 this->overlay_->hide();
    112 
     140            // call all the virtual 'setters'
     141            this->changedVisibility();
     142            this->angleChanged();
    113143            this->sizeCorrectionChanged();
    114144            this->sizeChanged();
     145            // probably gets called 4 times (by all the methods), but sizeChanged() could be overwritten.
    115146            this->positionChanged();
    116             this->angleChanged();
    117147        }
    118148    }
    119149
     150    //! Only sets the background material name if not ""
    120151    void OrxonoxOverlay::setBackgroundMaterial(const std::string& material)
    121152    {
     
    124155    }
    125156
     157    //! Returns the the material name of the background
    126158    const std::string& OrxonoxOverlay::getBackgroundMaterial() const
    127159    {
     
    132164    }
    133165
     166    //! Called by BaseObject when visibility has changed.
    134167    void OrxonoxOverlay::changedVisibility()
    135168    {
    136         if (this->overlay_)
    137         {
    138             if (this->isVisible())
    139                 this->overlay_->show();
    140             else
    141                 this->overlay_->hide();
    142         }
    143     }
    144 
     169        if (!this->overlay_)
     170            return;
     171
     172        if (this->isVisible())
     173            this->overlay_->show();
     174        else
     175            this->overlay_->hide();
     176    }
     177
     178    /**
     179    @brief
     180        Called by the GraphicsEngine whenever the window size changes.
     181        Calculates the aspect ratio only.
     182    */
    145183    void OrxonoxOverlay::windowResized(int newWidth, int newHeight)
    146184    {
    147185        this->windowAspectRatio_ = newWidth/(float)newHeight;
    148 
    149         this->setAspectCorrection(this->bCorrectAspect_);
    150     }
    151 
    152     void OrxonoxOverlay::setAspectCorrection(bool val)
    153     {
    154         this->bCorrectAspect_ = val;
    155186        this->sizeCorrectionChanged();
    156187    }
    157188
     189    /**
     190    @brief
     191        Called whenever the rotation angle has changed.
     192    */
     193    void OrxonoxOverlay::angleChanged()
     194    {
     195        if (!this->overlay_)
     196            return;
     197
     198        this->overlay_->setRotate(this->angle_);
     199        this->sizeCorrectionChanged();
     200    }
     201
     202    /**
     203    @brief
     204        Called whenever the aspect ratio or the angle has changed.
     205        The method calculates a correction factor for the size to compensate
     206        for aspect distortion if desired.
     207    @remarks
     208        This only works when the angle is about 0 or 90 degrees.
     209    */
    158210    void OrxonoxOverlay::sizeCorrectionChanged()
    159211    {
     
    165217            angle -= 180.0 * (int)(angle / 180.0);
    166218
     219            // take the reverse if angle is about 90 degrees
    167220            float tempAspect;
    168221            if (angle > 89.0 && angle < 91.0)
     
    183236            this->sizeCorrection_ = Vector2::UNIT_SCALE;
    184237        }
     238
    185239        this->sizeChanged();
    186240    }
    187241
    188242    /**
    189     @remarks
    190         This function can be overriden by any derivative.
     243    @brief
     244        Sets the overlay size using the actual corrected size.
    191245    */
    192246    void OrxonoxOverlay::sizeChanged()
    193247    {
     248        if (!this->overlay_)
     249            return;
     250
    194251        this->overlay_->setScale(size_.x * sizeCorrection_.x, size_.y * sizeCorrection_.y);
    195252        positionChanged();
     
    197254
    198255    /**
    199     @remarks
    200         This function can be overriden by any derivative.
    201     */
    202     void OrxonoxOverlay::angleChanged()
    203     {
    204         this->overlay_->setRotate(this->angle_);
    205         this->sizeCorrectionChanged();
    206     }
    207 
    208     /**
    209     @remarks
    210         This function can be overriden by any derivative.
     256    @brief
     257        Determines the position of the overlay.
     258        This works also well when a rotation angle is applied. The overlay always
     259        gets aligned correctly as well as possible.
    211260    */
    212261    void OrxonoxOverlay::positionChanged()
    213262    {
     263        if (!this->overlay_)
     264            return;
     265
     266        // transform the angle to a range of 0 - pi/2 first.
    214267        float angle = this->angle_.valueRadians();
    215268        if (angle < 0.0)
     
    218271        if (angle > Ogre::Math::PI * 0.5)
    219272            angle = Ogre::Math::PI - angle;
     273       
     274        // do some mathematical fiddling for a bounding box
    220275        Vector2 actualSize = size_ * sizeCorrection_;
    221276        float radius = actualSize.length();
    222277        float phi = atan(actualSize.y / actualSize.x);
    223278        Vector2 boundingBox(radius * cos(angle - phi), radius * sin(angle + phi));
    224         Vector2 scroll = (position_ - 0.5 - boundingBox * (origin_ - 0.5)) * 2.0;
     279
     280        // calculate the scrolling offset
     281        Vector2 scroll = (position_ - 0.5 - boundingBox * (pickPoint_ - 0.5)) * 2.0;
    225282        this->overlay_->setScroll(scroll.x, -scroll.y);
    226283    }
    227284
    228285
     286    //########### Console commands ############
     287
     288    /**
     289    @brief
     290        Scales an overlay by its name.
     291    @param name
     292        The name of the overlay defined BaseObject::setName() (usually done with the "name"
     293        attribute in the xml file.
     294    */
    229295    /*static*/ void OrxonoxOverlay::scaleOverlay(const std::string& name, float scale)
    230296    {
     
    234300    }
    235301
     302    /**
     303    @brief
     304        Scrolls an overlay by its name.
     305    @param name
     306        The name of the overlay defined BaseObject::setName() (usually done with the "name"
     307        attribute in the xml file.
     308    */
    236309    /*static*/ void OrxonoxOverlay::scrollOverlay(const std::string& name, const Vector2& scroll)
    237310    {
     
    241314    }
    242315
     316    /**
     317    @brief
     318        Rotates an overlay by its name.
     319    @param name
     320        The name of the overlay defined BaseObject::setName() (usually done with the "name"
     321        attribute in the xml file.
     322    */
    243323    /*static*/ void OrxonoxOverlay::rotateOverlay(const std::string& name, const Degree& angle)
    244324    {
  • code/branches/hud/src/orxonox/overlays/OrxonoxOverlay.h

    r1615 r1622  
    2727 */
    2828
     29/**
     30@file
     31@brief Declaration of the OrxonoxOverlay class.
     32*/
     33
    2934#ifndef _OrxonoxOverlay_H__
    3035#define _OrxonoxOverlay_H__
     
    3944namespace orxonox
    4045{
     46    /**
     47    @brief
     48        Base class to display content directly onto the screen.
     49        This is merely a wrapper of the Ogre::Overlay to implement more features and integrate it
     50        in our class hierarchy for xml loading and config values.
     51        The mentioned features are:
     52        - Automatic positioning depending on the scale and the rotation angle.
     53          You can specify a "pick point" relative to the overlay itself. This point will always be exactly
     54          at the position (position_) of the overlay. That allows for margin/corner aligment.
     55          It even works when a rotation angle is applied.
     56        - Virtual methods for changedVisibilty() (BaseObject), angleChanged(), sizeCorrectionChanged(),
     57          sizeChanged() and positionChanged(), that can be overridden by any derivative. This enables for
     58          custom configurability of the size, position and rotation attributes. For intance, the HUDNavigation
     59          should behave differently to sizeChanged() than a standard overlay.
     60        - Console commands for scale, rotate and scroll (accessed by name)
     61        - Standard Ogre::PanelOverlayElement for a background image (class doesn't have to be derived
     62          only for displaying a picture).
     63        - Reacts to changes of the window aspect
     64        - Last but not least: On demand you can tell the overlay to automatically resale to correct for
     65          aspect distortion. E.g. if you play 1024x768 you wouldn't want a round object to be oval.
     66          Remark: This can (due to the Ogre::Overlay transformation order) only work for angle that are
     67                  multiples of 90 degrees. But it's only a small drawback.
     68    */
    4169    class _OrxonoxExport OrxonoxOverlay : public BaseObject, public WindowEventListener
    4270    {
     
    4775        virtual void XMLPort(Element& xmlElement, XMLPort::Mode mode);
    4876
     77        //! Shows the overlay with an detour to BaseObject::visibility_
    4978        void show() { this->setVisibility(true); }
     79        //! Hides the overlay with an detour to BaseObject::visibility_
    5080        void hide() { this->setVisibility(false); }
    5181
    52         void setAspectCorrection(bool val);
    53         bool getAspectCorrection() { return this->bCorrectAspect_; }
     82        /** Sets whether the aspect of the overlay is corrected.
     83            This is for instance useful for round objects that should stay round no matter
     84            what the screen resolution is. */
     85        void setAspectCorrection(bool val)        { this->bCorrectAspect_ = val; this->sizeCorrectionChanged(); }
     86        //! Returns whether the window aspect is corrected
     87        bool getAspectCorrection() const          { return this->bCorrectAspect_; }
    5488
    55         /** Sets the position of this overlay. */
    56         void setPosition(Vector2 pos) { this->position_ = pos; this->positionChanged(); }
     89        //! Sets the position of this overlay on the screen.
     90        void setPosition(Vector2 pos)             { this->position_ = pos; this->positionChanged(); }
    5791
    58         /** Gets the current position. */
    59         Vector2 getPosition() const { return this->position_; }
     92        //! Returns the current position on the screen.
     93        const Vector2& getPosition() const        { return this->position_; }
    6094
    61         /** Scrolls the overlay by the offsets provided. */
    62         void scroll(Vector2 scroll) { this->position_ += scroll; this->positionChanged(); }
     95        //! Scrolls the overlay. @param offset The offset given.
     96        void scroll(const Vector2& offset)        { this->position_ += offset; this->positionChanged(); }
    6397
    64         /** Sets the origin point of this overlay. */
    65         void setOrigin(Vector2 pos) { this->origin_ = pos; this->positionChanged(); }
     98        /** Sets the point in the overlay where to pick it when translating.
     99            For instance setting it to (1.0,1.0) means that the lower right corner of the
     100            overlay will be put at position_.
     101            This primarily helps aligning an overlay to any corner/margin on the screen. */
     102        void setPickPoint(const Vector2& position){ this->pickPoint_ = position; this->positionChanged(); }
    66103
    67         /** Gets the origin point of this overlay */
    68         Vector2 getOrigin() const { return this->origin_; }
     104        //! Gets the pick point of this overlay. @see setPickPoint()
     105        const Vector2& getPickPoint() const       { return this->pickPoint_; }
    69106
    70         /** Sets the rotation applied to this overlay.*/
    71         void setRotation(const Degree& angle) { this->angle_ = angle; this->angleChanged(); }
     107        //! Sets the rotation angle applied to this overlay in degrees.
     108        void setRotation(const Degree& angle)     { this->angle_ = angle; this->angleChanged(); }
    72109
    73         /** Gets the rotation applied to this overlay, in degrees.*/
    74         const Radian& getRotation() const { return this->angle_; }
     110        //! Gets the rotation angle applied to this overlay in degrees.
     111        const Radian& getRotation() const         { return this->angle_; }
    75112
    76         /** Adds the passed in angle to the rotation applied to this overlay. */
    77         void rotate(const Degree& angle) { this->angle_ += angle; this->angleChanged(); }
     113        //! Rotates the overlay by angle degrees.
     114        void rotate(const Degree& angle)          { this->angle_ += angle; this->angleChanged(); }
    78115
    79         /** Sets the size of this overlay. */
    80         void setSize(const Vector2& size) { this->size_ = size; this->sizeChanged(); }
     116        //! Sets the size of this overlay.
     117        void setSize(const Vector2& size)         { this->size_ = size; this->sizeChanged(); }
    81118
    82         /** Gets the current size (not corrected) */
    83         Vector2 getUncorrectedSize() const { return this->size_; }
     119        //! Gets the current size that was set (uncorrected)
     120        Vector2 getSize() const                   { return this->size_ * this->sizeCorrection_; }
    84121
    85         /** Gets the current size (corrected) */
    86         Vector2 getSize() const { return this->size_ * this->sizeCorrection_; }
     122        //! Gets the actual size of the overlay on the screen (corrected)
     123        const Vector2& getActualSize() const      { return this->size_; }
    87124
    88         /** Gets the current size correction */
    89         Vector2 getSizeCorrection() const { return this->sizeCorrection_; }
     125        //! Gets the current size correction (default: 1.0, 1.0)
     126        const Vector2& getSizeCorrection() const { return this->sizeCorrection_; }
    90127
    91         /** Scales the overlay */
    92         void scale(Vector2 scale) { this->size_ *= scale; this->sizeChanged(); }
     128        //! Scales the overlay by scale.
     129        void scale(const Vector2& scale)          { this->size_ *= scale; this->sizeChanged(); }
    93130
     131        //! ConsoleCommand: Accesses the overlay by its name and scales it.
    94132        static void scaleOverlay(const std::string& name, float scale);
     133        //! ConsoleCommand: Accesses the overlay by its name and scrolls it.
    95134        static void scrollOverlay(const std::string& name, const Vector2& scroll);
     135        //! ConsoleCommand: Accesses the overlay by its name and rotates it.
    96136        static void rotateOverlay(const std::string& name, const Degree& angle);
    97137
    98138    protected:
    99139        virtual void changedVisibility();
     140        virtual void angleChanged();
     141        virtual void sizeCorrectionChanged();
    100142        virtual void sizeChanged();
    101         virtual void angleChanged();
    102143        virtual void positionChanged();
    103         virtual void sizeCorrectionChanged();
    104144
    105145        void setBackgroundMaterial(const std::string& material);
    106146        const std::string& getBackgroundMaterial() const;
    107147
    108         Ogre::Overlay* overlay_;
    109         Ogre::PanelOverlayElement* background_;
    110         float windowAspectRatio_;
    111         bool bCorrectAspect_;
    112         Vector2 size_;
    113         Vector2 sizeCorrection_;
    114         Radian angle_;
    115         Vector2 position_;
    116         Vector2 origin_;
     148        Ogre::Overlay* overlay_;                   //!< The overlay the entire class is about.
     149        Ogre::PanelOverlayElement* background_;    //!< Background image (blank per default).
     150
     151        float windowAspectRatio_;                  //!< Screen.width / screen.height
     152        bool bCorrectAspect_;                      //!< Whether or not to correct the size. @see setAspectCorrection()
     153        Vector2 size_;                             //!< Internal size of the overlay.
     154        Vector2 sizeCorrection_;                   //!< Value to correct the size because of the window aspect.
     155        Vector2 position_;                         //!< Position of the pickPoint on the screen.
     156        Vector2 pickPoint_;                        //!< Point on the overlay to pick when translating
     157        Radian angle_;                             //!< Rotation angle of the overlay
    117158
    118159    private:
    119160        void windowResized(int newWidth, int newHeight);
    120161
    121         static unsigned int hudOverlayCounter_s;
     162        static unsigned int hudOverlayCounter_s;   //!< Static counter for hud elements
     163        /** Contains all the overlays in a map for quick access via console commands.
     164            We could also use the ObjectList, but that doesn't guarantee XMLPort(.) was called and is slower. */
    122165        static std::map<std::string, OrxonoxOverlay*> overlays_s;
    123166  };
  • code/branches/hud/src/orxonox/overlays/OverlayText.cc

    r1616 r1622  
    102102    void OverlayText::sizeChanged()
    103103    {
    104         this->overlay_->setScale(getSize().y, getSize().y);
     104        this->overlay_->setScale(size_.y * sizeCorrection_.y, size_.y * sizeCorrection_.y);
    105105        positionChanged();
    106106    }
  • code/branches/hud/src/orxonox/overlays/OverlayText.h

    r1615 r1622  
    5656
    5757        void setTextSize(float size) { this->setSize(Vector2(size, size)); }
    58         float getTextSize() const    { return this->getUncorrectedSize().y; }
     58        float getTextSize() const    { return this->getSize().y; }
    5959
    6060        Ogre::TextAreaOverlayElement* text_;
  • code/branches/hud/src/orxonox/overlays/hud/HUDNavigation.cc

    r1621 r1622  
    270270    {
    271271        // use size to compensate for apspect ratio if enabled.
    272         float xScale = this->getSize().x;
    273         float yScale = this->getSize().y;
     272        float xScale = this->getActualSize().x;
     273        float yScale = this->getActualSize().y;
    274274        if (this->navMarker_)
    275275            navMarker_->setDimensions(navMarkerSize_ * xScale, navMarkerSize_ * yScale);
Note: See TracChangeset for help on using the changeset viewer.