Orxonox: orxonox::OrxonoxOverlay Class Reference

# orxonox::OrxonoxOverlay Class Reference

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.

More...

`#include <src/orxonox/overlays/OrxonoxOverlay.h>`

Inheritance diagram for orxonox::OrxonoxOverlay:

List of all members.

## Public Types

enum | RotationState { Horizontal, Vertical, Inbetween }
| Describes the rotational state of a an overlay. Horizontal means 0/180 degrees, Vertical is 90/270 degrees and Inbetween is everything else. More...

## Public Member Functions

virtual void | changedName ()
| This function gets called if the name of the object changes.
virtual void | changedOverlayGroup ()
virtual void | changedOwner ()
virtual void | changedVisibility ()
| Called by BaseObject when visibility has changed.
Vector2 | getActualSize () const
| Gets the actual size of the overlay on the screen (corrected).
bool | getAspectCorrection () const
| Returns whether the window aspect is corrected.
OverlayGroup * | getOverlayGroup () const
BaseObject * | getOwner () const
const Vector2 & | getPickPoint () const
| Gets the pick point of this overlay.
const Vector2 & | getPosition () const
| Returns the current position on the screen.
const Degree & | getRotation () const
| Gets the rotation angle applied to this overlay in degrees.
const Vector2 & | getSize () const
| Gets the current size that was set (uncorrected).
const Vector2 & | getSizeCorrection () const
| Gets the current size correction (default: 1.0, 1.0).
void | hide ()
| Hides the overlay with an detour to BaseObject::visibility_.
| OrxonoxOverlay (BaseObject *creator)
void | rotate (const Degree &angle)
| Rotates the overlay by angle degrees.
void | scale (const Vector2 &scale)
| Scales the overlay by scale.
void | scroll (const Vector2 &offset)
| Scrolls the overlay.
void | setAspectCorrection (bool val)
void | setOverlayGroup (OverlayGroup *group)
void | setOwner (BaseObject *owner)
void | setPickPoint (const Vector2 &position)
void | setPosition (Vector2 pos)
| Sets the position of this overlay on the screen.
void | setRotation (const Degree &angle)
| Sets the rotation angle applied to this overlay in degrees.
void | setSize (const Vector2 &size)
| Sets the size of this overlay.
void | show ()
| Shows the overlay with an detour to BaseObject::visibility_.
virtual void | XMLPort (Element &xmlElement, XMLPort::Mode mode)
| Loads the OrxonoxOverlay.
virtual | ~OrxonoxOverlay ()
| Make sure everything gets removed/destroyed.

## Static Public Member Functions

static void | rotateOverlay (const std::string &name, const Degree &angle)
| ConsoleCommand: Accesses the overlay by its name and rotates it.
static void | scaleOverlay (const std::string &name, float scale)
| ConsoleCommand: Accesses the overlay by its name and scales it.
static void | scrollOverlay (const std::string &name, const Vector2 &scroll)
| ConsoleCommand: Accesses the overlay by its name and scrolls it.
static void | toggleVisibility (const std::string &name)
| Toggles the visibility of an Overlay by it's name.

## Protected Member Functions

virtual void | angleChanged ()
| Called whenever the rotation angle has changed.
const std::string & | getBackgroundMaterial () const
| Returns the the material name of the background.
virtual void | positionChanged ()
| 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 | setBackgroundMaterial (const std::string &material)
| Only sets the background material name if not "".
virtual void | sizeChanged ()
| Sets the overlay size using the actual corrected size.
virtual void | sizeCorrectionChanged ()
| 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.

## Protected Attributes

Degree | angle_
| Rotation angle of the overlay.
Ogre::PanelOverlayElement * | background_
| Background image (blank per default).
bool | bCorrectAspect_
| Whether or not to correct the size.
Ogre::Overlay * | overlay_
| The overlay the entire class is about.
Vector2 | pickPoint_
| Point on the overlay to pick when translating.
Vector2 | position_
| Position of the pickPoint on the screen.
RotationState | rotState_
| horizontal, vertical or inbetween
Vector2 | size_
| Internal size of the overlay.
Vector2 | sizeCorrection_
| Value to correct the size because of the window aspect.
float | windowAspectRatio_
| Screen.width / screen.height.

## Private Member Functions

void | windowResized (unsigned int newWidth, unsigned int newHeight)
| Called by the GraphicsManager whenever the window size changes. Calculates the aspect ratio only.

## Private Attributes

OverlayGroup * | group_
BaseObject * | owner_

## Static Private Attributes

static unsigned int | hudOverlayCounter_s = 0
| Static counter for hud elements.
static std::map< std::string, OrxonoxOverlay * > | overlays_s

## Detailed Description

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.

## Member Enumeration Documentation

enum orxonox::OrxonoxOverlay::RotationState

Describes the rotational state of a an overlay. Horizontal means 0/180 degrees, Vertical is 90/270 degrees and Inbetween is everything else.

Enumerator:

  Horizontal |
  Vertical |
  Inbetween |

## Constructor & Destructor Documentation

orxonox::OrxonoxOverlay::OrxonoxOverlay | ( | BaseObject * | creator | ) |

orxonox::OrxonoxOverlay::~OrxonoxOverlay | ( |  | ) | `[virtual]`

Make sure everything gets removed/destroyed.

Remarks:
  We assume that the Ogre::OverlayManager exists (there is an assert in Ogre for that!)

References background_, orxonox::BaseObject::getName(), orxonox::BaseObject::isInitialized(), overlay_, and overlays_s.

## Member Function Documentation

void orxonox::OrxonoxOverlay::angleChanged | ( |  | ) | `[protected, virtual]`

Called whenever the rotation angle has changed.

Reimplemented in orxonox::HUDNavigation.

References angle_, overlay_, and sizeCorrectionChanged().

void orxonox::OrxonoxOverlay::changedName | ( |  | ) | `[virtual]`

This function gets called if the name of the object changes.

Reimplemented from orxonox::BaseObject.

Reimplemented in orxonox::HUDHealthBar.

References COUT, orxonox::BaseObject::getName(), orxonox::BaseObject::getOldName(), overlays_s, and SUPER.

virtual void orxonox::OrxonoxOverlay::changedOverlayGroup | ( |  | ) | `[inline, virtual]`

Reimplemented in orxonox::HUDHealthBar.

virtual void orxonox::OrxonoxOverlay::changedOwner | ( |  | ) | `[inline, virtual]`

Reimplemented in orxonox::AnnounceMessage, orxonox::DeathMessage, orxonox::GametypeStatus, orxonox::HUDHealthBar, orxonox::HUDRadar, orxonox::HUDSpeedBar, orxonox::HUDTimer, orxonox::KillMessage, orxonox::PongScore, orxonox::TeamBaseMatchScore, orxonox::UnderAttackHealthBar, and orxonox::Map.

void orxonox::OrxonoxOverlay::changedVisibility | ( |  | ) | `[virtual]`

Called by BaseObject when visibility has changed.

Reimplemented from orxonox::BaseObject.

Reimplemented in orxonox::GUIOverlay, orxonox::HUDHealthBar, and orxonox::Scoreboard.

References orxonox::BaseObject::isVisible(), and overlay_.

Vector2 orxonox::OrxonoxOverlay::getActualSize | ( |  | ) | const`[inline]`

Gets the actual size of the overlay on the screen (corrected).

Referenced by orxonox::HUDNavigation::sizeChanged().

bool orxonox::OrxonoxOverlay::getAspectCorrection | ( |  | ) | const`[inline]`

Returns whether the window aspect is corrected.

Referenced by XMLPort().

const std::string & orxonox::OrxonoxOverlay::getBackgroundMaterial | ( |  | ) | const`[protected]`

Returns the the material name of the background.

References background_, and orxonox::BLANKSTRING.

Referenced by XMLPort().

OverlayGroup* orxonox::OrxonoxOverlay::getOverlayGroup | ( |  | ) | const`[inline]`

Referenced by orxonox::HUDHealthBar::changedOverlayGroup().

BaseObject* orxonox::OrxonoxOverlay::getOwner | ( |  | ) | const`[inline]`

Referenced by orxonox::Map::changedOwner(), orxonox::UnderAttackHealthBar::changedOwner(), orxonox::TeamBaseMatchScore::changedOwner(), orxonox::PongScore::changedOwner(), orxonox::KillMessage::changedOwner(), orxonox::HUDTimer::changedOwner(), orxonox::HUDSpeedBar::changedOwner(), orxonox::HUDRadar::changedOwner(), orxonox::HUDHealthBar::changedOwner(), orxonox::GametypeStatus::changedOwner(), orxonox::DeathMessage::changedOwner(), orxonox::AnnounceMessage::changedOwner(), and orxonox::QuestManager::getQuestTree().

const Vector2& orxonox::OrxonoxOverlay::getPickPoint | ( |  | ) | const`[inline]`

Gets the pick point of this overlay.

See also:
  setPickPoint()

Referenced by XMLPort().

const Vector2& orxonox::OrxonoxOverlay::getPosition | ( |  | ) | const`[inline]`

Returns the current position on the screen.

Referenced by XMLPort().

const Degree& orxonox::OrxonoxOverlay::getRotation | ( |  | ) | const`[inline]`

Gets the rotation angle applied to this overlay in degrees.

Referenced by XMLPort().

const Vector2& orxonox::OrxonoxOverlay::getSize | ( | void |  | ) | const`[inline]`

Gets the current size that was set (uncorrected).

Referenced by XMLPort().

const Vector2& orxonox::OrxonoxOverlay::getSizeCorrection | ( |  | ) | const`[inline]`

Gets the current size correction (default: 1.0, 1.0).

void orxonox::OrxonoxOverlay::hide | ( |  | ) | `[inline]`

Hides the overlay with an detour to BaseObject::visibility_.

Referenced by toggleVisibility().

void orxonox::OrxonoxOverlay::positionChanged | ( | void |  | ) | `[protected, virtual]`

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.

Reimplemented in orxonox::HUDNavigation.

References angle_, overlay_, pickPoint_, position_, scroll(), size_, sizeCorrection_, and orxonox::MT_Type::Vector2.

Referenced by orxonox::OverlayText::sizeChanged(), and sizeChanged().

void orxonox::OrxonoxOverlay::rotate | ( | const Degree & | angle | ) | `[inline]`

Rotates the overlay by angle degrees.

void orxonox::OrxonoxOverlay::rotateOverlay | ( | const std::string & | name,
|  | const Degree & | angle |
| ) |  |  | `[static]`

ConsoleCommand: Accesses the overlay by its name and rotates it.

Rotates an overlay by its name.

Parameters:

  | name | The name of the overlay defined BaseObject::setName() (usually done with the "name" attribute in the xml file).

References overlays_s.

void orxonox::OrxonoxOverlay::scale | ( | const Vector2 & | scale | ) | `[inline]`

Scales the overlay by scale.

void orxonox::OrxonoxOverlay::scaleOverlay | ( | const std::string & | name,
|  | float | scale |
| ) |  |  | `[static]`

ConsoleCommand: Accesses the overlay by its name and scales it.

Scales an overlay by its name.

Parameters:

  | name | The name of the overlay defined BaseObject::setName() (usually done with the "name" attribute in the xml file).

References overlays_s, and orxonox::MT_Type::Vector2.

void orxonox::OrxonoxOverlay::scroll | ( | const Vector2 & | offset | ) | `[inline]`

Scrolls the overlay.

Parameters:

  | offset | The offset given.

Referenced by orxonox::NotificationQueue::addNotification(), and positionChanged().

void orxonox::OrxonoxOverlay::scrollOverlay | ( | const std::string & | name,
|  | const Vector2 & | scroll |
| ) |  |  | `[static]`

ConsoleCommand: Accesses the overlay by its name and scrolls it.

Scrolls an overlay by its name.

Parameters:

  | name | The name of the overlay defined BaseObject::setName() (usually done with the "name" attribute in the xml file).

References overlays_s.

void orxonox::OrxonoxOverlay::setAspectCorrection | ( | bool | val | ) | `[inline]`

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.

Referenced by XMLPort().

void orxonox::OrxonoxOverlay::setBackgroundMaterial | ( | const std::string & | material | ) | `[protected]`

Only sets the background material name if not "".

References background_.

Referenced by XMLPort().

void orxonox::OrxonoxOverlay::setOverlayGroup | ( | OverlayGroup * | group | ) | `[inline]`

void orxonox::OrxonoxOverlay::setOwner | ( | BaseObject * | owner | ) | `[inline]`

Referenced by orxonox::OverlayGroup::addElement(), orxonox::UnderAttackHealthBar::changedOwner(), and orxonox::UnderAttackHealthBar::init().

void orxonox::OrxonoxOverlay::setPickPoint | ( | const Vector2 & | position | ) | `[inline]`

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.

Referenced by orxonox::UnderAttackHealthBar::UnderAttackHealthBar(), and XMLPort().

void orxonox::OrxonoxOverlay::setPosition | ( | Vector2 | pos | ) | `[inline]`

Sets the position of this overlay on the screen.

Referenced by orxonox::CreateLines::CreateLines(), orxonox::NotificationOverlay::defineOverlay(), and XMLPort().

void orxonox::OrxonoxOverlay::setRotation | ( | const Degree & | angle | ) | `[inline]`

Sets the rotation angle applied to this overlay in degrees.

Referenced by XMLPort().

void orxonox::OrxonoxOverlay::setSize | ( | const Vector2 & | size | ) | `[inline]`

Sets the size of this overlay.

Referenced by orxonox::CreateLines::CreateLines(), and XMLPort().

void orxonox::OrxonoxOverlay::show | ( |  | ) | `[inline]`

Shows the overlay with an detour to BaseObject::visibility_.

Referenced by toggleVisibility().

void orxonox::OrxonoxOverlay::sizeChanged | ( |  | ) | `[protected, virtual]`

Sets the overlay size using the actual corrected size.

Reimplemented in orxonox::HUDNavigation, and orxonox::OverlayText.

References overlay_, positionChanged(), size_, and sizeCorrection_.

Referenced by sizeCorrectionChanged().

void orxonox::OrxonoxOverlay::sizeCorrectionChanged | ( |  | ) | `[protected, virtual]`

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.

References angle_, bCorrectAspect_, Horizontal, Inbetween, rotState_, sizeChanged(), sizeCorrection_, Vertical, and windowAspectRatio_.

Referenced by angleChanged(), and windowResized().

void orxonox::OrxonoxOverlay::toggleVisibility | ( | const std::string & | name | ) | `[static]`

Toggles the visibility of an Overlay by it's name.

Parameters:

  | name | The name of the overlay defined BaseObject::setName() (usually done with the "name" attribute in the xml file).

References hide(), orxonox::BaseObject::isVisible(), overlays_s, and show().

void orxonox::OrxonoxOverlay::windowResized | ( | unsigned int | newWidth,
|  | unsigned int | newHeight |
| ) |  |  | `[private, virtual]`

Called by the GraphicsManager whenever the window size changes. Calculates the aspect ratio only.

Reimplemented from orxonox::WindowEventListener.

References sizeCorrectionChanged(), and windowAspectRatio_.

void orxonox::OrxonoxOverlay::XMLPort | ( | Element & | xmlElement,
|  | XMLPort::Mode | mode |
| ) |  |  | `[virtual]`

Loads the OrxonoxOverlay.

This has to be called before usage, otherwise strange behaviour is guaranteed! (there should be no segfaults however). XML loading and saving.

Parameters:

  | xmlelement | The XML-element
  | loading | Loading (true) or saving (false)

Returns:
  The XML-element

Reimplemented from orxonox::BaseObject.

Reimplemented in orxonox::FadeoutText, orxonox::GUIOverlay, orxonox::HUDBar, orxonox::HUDHealthBar, orxonox::HUDNavigation, orxonox::HUDRadar, orxonox::PongScore, orxonox::TeamBaseMatchScore, orxonox::UnderAttackHealthBar, orxonox::Map, orxonox::OverlayText, orxonox::Scoreboard, and orxonox::Stats.

References getAspectCorrection(), getBackgroundMaterial(), getPickPoint(), getPosition(), getRotation(), getSize(), setAspectCorrection(), setBackgroundMaterial(), setPickPoint(), setPosition(), setRotation(), setSize(), SUPER, and XMLPortParam.

Referenced by orxonox::Stats::XMLPort().

## Member Data Documentation

Degree orxonox::OrxonoxOverlay::angle_`[protected]`

Rotation angle of the overlay.

Referenced by angleChanged(), positionChanged(), and sizeCorrectionChanged().

Ogre::PanelOverlayElement* orxonox::OrxonoxOverlay::background_`[protected]`

Background image (blank per default).

Referenced by getBackgroundMaterial(), orxonox::HUDBar::HUDBar(), orxonox::HUDNavigation::HUDNavigation(), orxonox::OverlayText::OverlayText(), setBackgroundMaterial(), orxonox::Stats::Stats(), and ~OrxonoxOverlay().

bool orxonox::OrxonoxOverlay::bCorrectAspect_`[protected]`

Whether or not to correct the size.

See also:
  setAspectCorrection()

Referenced by sizeCorrectionChanged().

OverlayGroup* orxonox::OrxonoxOverlay::group_`[private]`

unsigned int orxonox::OrxonoxOverlay::hudOverlayCounter_s = 0`[static, private]`

Static counter for hud elements.

Ogre::Overlay* orxonox::OrxonoxOverlay::overlay_`[protected]`

The overlay the entire class is about.

Reimplemented in orxonox::Map.

Referenced by angleChanged(), changedVisibility(), orxonox::HUDRadar::displayObject(), orxonox::HUDRadar::HUDRadar(), positionChanged(), orxonox::OverlayText::sizeChanged(), sizeChanged(), orxonox::HUDNavigation::tick(), and ~OrxonoxOverlay().

std::map< std::string, OrxonoxOverlay * > orxonox::OrxonoxOverlay::overlays_s`[static, private]`

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.

Referenced by changedName(), rotateOverlay(), scaleOverlay(), scrollOverlay(), toggleVisibility(), and ~OrxonoxOverlay().

BaseObject* orxonox::OrxonoxOverlay::owner_`[private]`

Reimplemented in orxonox::AnnounceMessage, orxonox::DeathMessage, orxonox::GametypeStatus, orxonox::HUDHealthBar, orxonox::HUDRadar, orxonox::HUDSpeedBar, orxonox::HUDTimer, orxonox::KillMessage, orxonox::PongScore, orxonox::TeamBaseMatchScore, and orxonox::UnderAttackHealthBar.

Vector2 orxonox::OrxonoxOverlay::pickPoint_`[protected]`

Point on the overlay to pick when translating.

Referenced by positionChanged().

Vector2 orxonox::OrxonoxOverlay::position_`[protected]`

Position of the pickPoint on the screen.

Referenced by positionChanged().

RotationState orxonox::OrxonoxOverlay::rotState_`[protected]`

horizontal, vertical or inbetween

Referenced by orxonox::OverlayText::sizeChanged(), and sizeCorrectionChanged().

Vector2 orxonox::OrxonoxOverlay::size_`[protected]`

Internal size of the overlay.

Referenced by positionChanged(), orxonox::OverlayText::sizeChanged(), and sizeChanged().

Vector2 orxonox::OrxonoxOverlay::sizeCorrection_`[protected]`

Value to correct the size because of the window aspect.

Referenced by positionChanged(), orxonox::OverlayText::sizeChanged(), sizeChanged(), and sizeCorrectionChanged().

float orxonox::OrxonoxOverlay::windowAspectRatio_`[protected]`

Screen.width / screen.height.

Referenced by sizeCorrectionChanged(), and windowResized().

The documentation for this class was generated from the following files:

- src/orxonox/overlays/OrxonoxOverlay.h
- src/orxonox/overlays/OrxonoxOverlay.cc