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.

File:
1 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    {
Note: See TracChangeset for help on using the changeset viewer.