# Ogre::Viewport Class Reference

An abstraction of a viewport, i.e. More...

`#include <OgreViewport.h>`

List of all members.

## Public Member Functions

| Viewport (Camera *camera, RenderTarget *target, Real left, Real top, Real width, Real height, int ZOrder)
| The usual constructor.
virtual | ~Viewport ()
| Default destructor.
void | _updateDimensions (void)
| Notifies the viewport of a possible change in dimensions.
void | update (void)
| Instructs the viewport to updates its contents.
RenderTarget * | getTarget (void) const
| Retrieves a pointer to the render target for this viewport.
Camera * | getCamera (void) const
| Retrieves a pointer to the camera for this viewport.
void | setCamera (Camera *cam)
| Sets the camera to use for rendering to this viewport.
int | getZOrder (void) const
| Gets the Z-Order of this viewport.
Real | getLeft (void) const
| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
Real | getTop (void) const
| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
Real | getWidth (void) const
| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
Real | getHeight (void) const
| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
int | getActualLeft (void) const
| Gets one of the actual dimensions of the viewport, a value in pixels.
int | getActualTop (void) const
| Gets one of the actual dimensions of the viewport, a value in pixels.
int | getActualWidth (void) const
| Gets one of the actual dimensions of the viewport, a value in pixels.
int | getActualHeight (void) const
| Gets one of the actual dimensions of the viewport, a value in pixels.
void | setDimensions (Real left, Real top, Real width, Real height)
| Sets the dimensions (after creation).
void | setBackgroundColour (const ColourValue &colour)
| Sets the initial background colour of the viewport (before rendering).
const ColourValue & | getBackgroundColour (void) const
| Gets the background colour.
void | setClearEveryFrame (bool clear, unsigned int buffers=FBT_COLOUR|FBT_DEPTH)
| Determines whether to clear the viewport before rendering.
bool | getClearEveryFrame (void) const
| Determines if the viewport is cleared before every frame.
unsigned int | getClearBuffers (void) const
| Gets which buffers are to be cleared each frame.
void | setMaterialScheme (const String &schemeName)
| Set the material scheme which the viewport should use.
const String & | getMaterialScheme (void) const
| Get the material scheme which the viewport should use.
void | getActualDimensions (int &left, int &top, int &width, int &height) const
| Access to actual dimensions (based on target size).
bool | _isUpdated (void) const
void | _clearUpdatedFlag (void)
unsigned int | _getNumRenderedFaces (void) const
| Gets the number of rendered faces in the last update.
void | setOverlaysEnabled (bool enabled)
| Tells this viewport whether it should display Overlay objects.
bool | getOverlaysEnabled (void) const
| Returns whether or not Overlay objects (created in the SceneManager) are displayed in this viewport.
void | setSkiesEnabled (bool enabled)
| Tells this viewport whether it should display skies.
bool | getSkiesEnabled (void) const
| Returns whether or not skies (created in the SceneManager) are displayed in this viewport.
void | setShadowsEnabled (bool enabled)
| Tells this viewport whether it should display shadows.
bool | getShadowsEnabled (void) const
| Returns whether or not shadows (defined in the SceneManager) are displayed in this viewport.
virtual void | setRenderQueueInvocationSequenceName (const String &sequenceName)
| Sets the use of a custom RenderQueueInvocationSequence for rendering this target.
virtual const String & | getRenderQueueInvocationSequenceName (void) const
| Gets the name of the render queue invocation sequence for this target.
RenderQueueInvocationSequence * | _getRenderQueueInvocationSequence (void)
| Get the invocation sequence - will return null if using standard.

## Protected Attributes

Camera * | mCamera
RenderTarget * | mTarget
float | mRelLeft
float | mRelTop
float | mRelWidth
float | mRelHeight
int | mActLeft
int | mActTop
int | mActWidth
int | mActHeight
int | mZOrder
| ZOrder.
ColourValue | mBackColour
| Background options.
bool | mClearEveryFrame
unsigned int | mClearBuffers
bool | mUpdated
bool | mShowOverlays
bool | mShowSkies
bool | mShowShadows
String | mRQSequenceName
RenderQueueInvocationSequence * | mRQSequence
String | mMaterialSchemeName
| Material scheme.

## Detailed Description

An abstraction of a viewport, i.e.

a rendering region on a render target.

Remarks:
  A viewport is the meeting of a camera and a rendering surface - the camera renders the scene from a viewpoint, and places its results into some subset of a rendering target, which may be the whole surface or just a part of the surface. Each viewport has a single camera as source and a single target as destination. A camera only has 1 viewport, but a render target may have several. A viewport also has a Z-order, i.e. if there is more than one viewport on a single render target and they overlap, one must obscure the other in some predetermined way.

Definition at line 46 of file OgreViewport.h.

## Constructor & Destructor Documentation

Ogre::Viewport::Viewport | ( | Camera * | camera,
|  | RenderTarget * | target,
|  | Real | left,
|  | Real | top,
|  | Real | width,
|  | Real | height,
|  | int | ZOrder
| ) |

The usual constructor.

Parameters:

  | cam | Pointer to a camera to be the source for the image.
  | target | Pointer to the render target to be the destination for the rendering.
  | left |
  | top |
  | width |
  | height | Dimensions of the viewport, expressed as a value between 0 and 1. This allows the dimensions to apply irrespective of changes in the target's size: e.g. to fill the whole area, values of 0,0,1,1 are appropriate.
  | ZOrder | Relative Z-order on the target. Lower = further to the front.

virtual Ogre::Viewport::~Viewport | ( |  | ) | `[virtual]`

| Default destructor.

## Member Function Documentation

void Ogre::Viewport::_clearUpdatedFlag | ( | void |  | ) |

unsigned int Ogre::Viewport::_getNumRenderedFaces | ( | void |  | ) | const

| Gets the number of rendered faces in the last update.

RenderQueueInvocationSequence* Ogre::Viewport::_getRenderQueueInvocationSequence | ( | void |  | ) |

| Get the invocation sequence - will return null if using standard.

bool Ogre::Viewport::_isUpdated | ( | void |  | ) | const

void Ogre::Viewport::_updateDimensions | ( | void |  | ) |

Notifies the viewport of a possible change in dimensions.

Remarks:
  Used by the target to update the viewport's dimensions (usually the result of a change in target size).

Note:
  Internal use by Ogre only.

void Ogre::Viewport::getActualDimensions | ( | int & | left,
|  | int & | top,
|  | int & | width,
|  | int & | height
| ) | const

| Access to actual dimensions (based on target size).

int Ogre::Viewport::getActualHeight | ( | void |  | ) | const

| Gets one of the actual dimensions of the viewport, a value in pixels.

int Ogre::Viewport::getActualLeft | ( | void |  | ) | const

| Gets one of the actual dimensions of the viewport, a value in pixels.

int Ogre::Viewport::getActualTop | ( | void |  | ) | const

| Gets one of the actual dimensions of the viewport, a value in pixels.

int Ogre::Viewport::getActualWidth | ( | void |  | ) | const

| Gets one of the actual dimensions of the viewport, a value in pixels.

const ColourValue& Ogre::Viewport::getBackgroundColour | ( | void |  | ) | const

| Gets the background colour.

Camera* Ogre::Viewport::getCamera | ( | void |  | ) | const

| Retrieves a pointer to the camera for this viewport.

unsigned int Ogre::Viewport::getClearBuffers | ( | void |  | ) | const

| Gets which buffers are to be cleared each frame.

bool Ogre::Viewport::getClearEveryFrame | ( | void |  | ) | const

| Determines if the viewport is cleared before every frame.

Real Ogre::Viewport::getHeight | ( | void |  | ) | const

| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.

Real Ogre::Viewport::getLeft | ( | void |  | ) | const

| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.

const String& Ogre::Viewport::getMaterialScheme | ( | void |  | ) | const

| Get the material scheme which the viewport should use. Definition at line 201 of file OgreViewport.h.

bool Ogre::Viewport::getOverlaysEnabled | ( | void |  | ) | const

| Returns whether or not Overlay objects (created in the SceneManager) are displayed in this viewport.

virtual const String& Ogre::Viewport::getRenderQueueInvocationSequenceName | ( | void |  | ) | const`[virtual]`

| Gets the name of the render queue invocation sequence for this target.

bool Ogre::Viewport::getShadowsEnabled | ( | void |  | ) | const

| Returns whether or not shadows (defined in the SceneManager) are displayed in this viewport.

bool Ogre::Viewport::getSkiesEnabled | ( | void |  | ) | const

| Returns whether or not skies (created in the SceneManager) are displayed in this viewport.

RenderTarget* Ogre::Viewport::getTarget | ( | void |  | ) | const

| Retrieves a pointer to the render target for this viewport.

Real Ogre::Viewport::getTop | ( | void |  | ) | const

| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.

Real Ogre::Viewport::getWidth | ( | void |  | ) | const

| Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.

int Ogre::Viewport::getZOrder | ( | void |  | ) | const

| Gets the Z-Order of this viewport.

void Ogre::Viewport::setBackgroundColour | ( | const ColourValue & | colour | ) |

| Sets the initial background colour of the viewport (before rendering).

void Ogre::Viewport::setCamera | ( | Camera * | cam | ) |

| Sets the camera to use for rendering to this viewport.

void Ogre::Viewport::setClearEveryFrame | ( | bool | clear,
|  | unsigned int | buffers = `FBT_COLOUR|FBT_DEPTH`
| ) |

Determines whether to clear the viewport before rendering.

Remarks:
  You can use this method to set which buffers are cleared (if any) before rendering every frame.

Parameters:

  | clear | Whether or not to clear any buffers
  | buffers | One or more values from FrameBufferType denoting which buffers to clear, if clear is set to true. Note you should not clear the stencil buffer here unless you know what you're doing.

void Ogre::Viewport::setDimensions | ( | Real | left,
|  | Real | top,
|  | Real | width,
|  | Real | height
| ) |

Sets the dimensions (after creation).

Parameters:

  | left |
  | top |
  | width |
  | height | Dimensions relative to the size of the target, represented as real values between 0 and 1. i.e. the full target area is 0, 0, 1, 1.

void Ogre::Viewport::setMaterialScheme | ( | const String & | schemeName | ) |

Set the material scheme which the viewport should use.

Remarks:
  This allows you to tell the system to use a particular material scheme when rendering this viewport, which can involve using different techniques to render your materials.

See also:
  Technique::setSchemeName

Definition at line 196 of file OgreViewport.h.

void Ogre::Viewport::setOverlaysEnabled | ( | bool | enabled | ) |

Tells this viewport whether it should display Overlay objects.

Remarks:
  Overlay objects are layers which appear on top of the scene. They are created via SceneManager::createOverlay and every viewport displays these by default. However, you probably don't want this if you're using multiple viewports, because one of them is probably a picture-in-picture which is not supposed to have overlays of it's own. In this case you can turn off overlays on this viewport by calling this method.

Parameters:

  | enabled | If true, any overlays are displayed, if false they are not.

virtual void Ogre::Viewport::setRenderQueueInvocationSequenceName | ( | const String & | sequenceName | ) | `[virtual]`

Sets the use of a custom RenderQueueInvocationSequence for rendering this target.

Remarks:
  RenderQueueInvocationSequence instances are managed through Root. By setting this, you are indicating that you wish this RenderTarget to be updated using a custom sequence of render queue invocations, with potentially customised ordering and render state options. You should create the named sequence through Root first, then set the name here.

Parameters:

  | The | name of the RenderQueueInvocationSequence to use. If you specify a blank string, behaviour will return to the defaul render queue management.

void Ogre::Viewport::setShadowsEnabled | ( | bool | enabled | ) |

Tells this viewport whether it should display shadows.

Remarks:
  This setting enables you to disable shadow rendering for a given viewport. The global shadow technique set on SceneManager still controls the type and nature of shadows, but this flag can override the setting so that no shadows are rendered for a given viewport to save processing time where they are not required.

Parameters:

  | enabled | If true, any shadows are displayed, if false they are not.

void Ogre::Viewport::setSkiesEnabled | ( | bool | enabled | ) |

Tells this viewport whether it should display skies.

Remarks:
  Skies are layers which appear on background of the scene. They are created via SceneManager::setSkyBox, SceneManager::setSkyPlane and SceneManager::setSkyDome and every viewport displays these by default. However, you probably don't want this if you're using multiple viewports, because one of them is probably a picture-in-picture which is not supposed to have skies of it's own. In this case you can turn off skies on this viewport by calling this method.

Parameters:

  | enabled | If true, any skies are displayed, if false they are not.

void Ogre::Viewport::update | ( | void |  | ) |

| Instructs the viewport to updates its contents.

## Member Data Documentation

int Ogre::Viewport::mActHeight `[protected]`

| Definition at line 286 of file OgreViewport.h.

int Ogre::Viewport::mActLeft `[protected]`

| Definition at line 286 of file OgreViewport.h.

int Ogre::Viewport::mActTop `[protected]`

| Definition at line 286 of file OgreViewport.h.

int Ogre::Viewport::mActWidth `[protected]`

| Definition at line 286 of file OgreViewport.h.

ColourValue Ogre::Viewport::mBackColour `[protected]`

| Background options. Definition at line 290 of file OgreViewport.h.

Camera* Ogre::Viewport::mCamera `[protected]`

| Definition at line 281 of file OgreViewport.h.

unsigned int Ogre::Viewport::mClearBuffers `[protected]`

| Definition at line 292 of file OgreViewport.h.

bool Ogre::Viewport::mClearEveryFrame `[protected]`

| Definition at line 291 of file OgreViewport.h.

String Ogre::Viewport::mMaterialSchemeName `[protected]`

| Material scheme. Definition at line 301 of file OgreViewport.h.

float Ogre::Viewport::mRelHeight `[protected]`

| Definition at line 284 of file OgreViewport.h.

float Ogre::Viewport::mRelLeft `[protected]`

| Definition at line 284 of file OgreViewport.h.

float Ogre::Viewport::mRelTop `[protected]`

| Definition at line 284 of file OgreViewport.h.

float Ogre::Viewport::mRelWidth `[protected]`

| Definition at line 284 of file OgreViewport.h.

RenderQueueInvocationSequence* Ogre::Viewport::mRQSequence `[protected]`

| Definition at line 299 of file OgreViewport.h.

String Ogre::Viewport::mRQSequenceName `[protected]`

| Definition at line 298 of file OgreViewport.h.

bool Ogre::Viewport::mShowOverlays `[protected]`

| Definition at line 294 of file OgreViewport.h.

bool Ogre::Viewport::mShowShadows `[protected]`

| Definition at line 296 of file OgreViewport.h.

bool Ogre::Viewport::mShowSkies `[protected]`

| Definition at line 295 of file OgreViewport.h.

RenderTarget* Ogre::Viewport::mTarget `[protected]`

| Definition at line 282 of file OgreViewport.h.

bool Ogre::Viewport::mUpdated `[protected]`

| Definition at line 293 of file OgreViewport.h.

int Ogre::Viewport::mZOrder `[protected]`

| ZOrder. Definition at line 288 of file OgreViewport.h.

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

- OgreViewport.h

Copyright © 2000-2005 by The OGRE Team
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.
Last modified Sun Sep 17 15:44:21 2006