OGRE: Ogre::Viewport Class Reference

| OGRE 14.5 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::Viewport Class Reference
Core » RenderSystem

An abstraction of a viewport, i.e., a rendering region on a render target. More...

`#include <OgreViewport.h>`

Inheritance diagram for Ogre::Viewport:
[legend]

## Classes
class | Listener
| Listener interface so you can be notified of Viewport changes. More...

## Public Member Functions
| Viewport (Camera *camera, RenderTarget *target, float left, float top, float width, float height, int ZOrder)
| The usual constructor.
| Viewport (Camera *camera, RenderTarget *target, FloatRect relRect, int ZOrder)
| This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
virtual | ~Viewport ()
| Default destructor.
void | _clearUpdatedFlag (void)
unsigned int | _getNumRenderedBatches (void) const
| Gets the number of rendered batches in the last update.
unsigned int | _getNumRenderedFaces (void) const
| Gets the number of rendered faces in the last update.
bool | _isUpdated (void) const
void | _updateDimensions (void)
| Notifies the viewport of a possible change in dimensions.
void | addListener (Listener *l)
| Add a listener to this viewport.
void | clear (uint32 buffers=FBT_COLOUR|FBT_DEPTH, const ColourValue &colour=ColourValue::Black, float depth=1.0f, uint16 stencil=0)
void | getActualDimensions (int &left, int &top, int &width, int &height) const
const ColourValue & | getBackgroundColour (void) const
| Gets the background colour.
Camera * | getCamera (void) const
| Retrieves a pointer to the camera for this viewport.
unsigned int | getClearBuffers (void) const
| Gets which buffers are to be cleared each frame.
bool | getClearEveryFrame (void) const
| Determines if the viewport is cleared before every frame.
float | getDepthClear (void) const
| Gets the default depth buffer value to which the viewport is cleared.
ColourBufferType | getDrawBuffer () const
| Returns the current colour buffer type for this viewport.
const String & | getMaterialScheme (void) const
| Get the material scheme which the viewport should use.
bool | getOverlaysEnabled (void) const
| Returns whether or not Overlay objects (created with the OverlayManager) are displayed in this viewport.
bool | getShadowsEnabled (void) const
| Returns whether or not shadows (defined in the SceneManager) are displayed in this viewport.
bool | getSkiesEnabled (void) const
| Returns whether or not skies (created in the SceneManager) are displayed in this viewport.
RenderTarget * | getTarget (void) const
| Retrieves a pointer to the render target for this viewport.
uint | getVisibilityMask (void) const
| Gets a per-viewport visibility mask.
int | getZOrder (void) const
| Gets the Z-Order of this viewport.
bool | isAutoUpdated () const
| Gets whether this viewport is automatically updated if Ogre's rendering loop or RenderTarget::update is being used.
void | removeListener (Listener *l)
| Remove a listener to this viewport.
void | setAutoUpdated (bool autoupdate)
| Sets whether this viewport should be automatically updated if Ogre's rendering loop or RenderTarget::update is being used.
void | setBackgroundColour (const ColourValue &colour)
| Sets the initial background colour of the viewport (before rendering).
void | setCamera (Camera *cam)
| Sets the camera to use for rendering to this viewport.
void | setClearEveryFrame (bool clear, unsigned int buffers=FBT_COLOUR|FBT_DEPTH)
| Determines whether to clear the viewport before rendering.
void | setDepthClear (float depth)
| Sets the initial depth buffer value of the viewport (before rendering).
void | setDimensions (float left, float top, float width, float height)
| Sets the dimensions (after creation).
void | setDrawBuffer (ColourBufferType colourBuffer)
| Sets the draw buffer type for the next frame.
void | setMaterialScheme (const String &schemeName)
| Set the material scheme which the viewport should use.
void | setOverlaysEnabled (bool enabled)
| Tells this viewport whether it should display Overlay objects.
void | setShadowsEnabled (bool enabled)
| Tells this viewport whether it should display shadows.
void | setSkiesEnabled (bool enabled)
| Tells this viewport whether it should display skies.
void | setVisibilityMask (uint32 mask)
| Sets a per-viewport visibility mask.
void | update (void)
| Instructs the viewport to updates its contents.
Relative dimensions
These methods return the relative dimensions of the viewport, which are expressed as a value between 0.0 and 1.0.
float | getLeft (void) const
float | getTop (void) const
float | getWidth (void) const
float | getHeight (void) const
FloatRect | getDimensions (void) const
Actual dimensions
These methods return the actual dimensions of the viewport in pixels.
int | getActualLeft (void) const
int | getActualTop (void) const
int | getActualWidth (void) const
int | getActualHeight (void) const
Rect | getActualDimensions () const

## Detailed Description

An abstraction of a viewport, i.e., a rendering region on a render target.

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.

## Constructor & Destructor Documentation

## ◆ Viewport() [1/2]

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

The usual constructor.

Parameters

  camera | 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.

References Viewport().

Referenced by Viewport(), Ogre::Viewport::Listener::viewportCameraChanged(), Ogre::Viewport::Listener::viewportDestroyed(), and Ogre::Viewport::Listener::viewportDimensionsChanged().

## ◆ Viewport() [2/2]

Ogre::Viewport::Viewport | ( | Camera * | camera,
|  | RenderTarget * | target,
|  | FloatRect | relRect,
|  | int | ZOrder )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

## ◆ ~Viewport()

virtual Ogre::Viewport::~Viewport | ( |  | ) |
| virtual

Default destructor.

## Member Function Documentation

## ◆ _updateDimensions()

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

Notifies the viewport of a possible change in dimensions.

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.

## ◆ update()

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

Instructs the viewport to updates its contents.

## ◆ clear()

void Ogre::Viewport::clear | ( | uint32 | buffers = FBT_COLOUR|FBT_DEPTH,
|  | const ColourValue & | colour = ColourValue::Black,
|  | float | depth = 1.0f,
|  | uint16 | stencil = 0 )

Deprecated
  use RenderSystem::clearFrameBuffer instead

References Ogre::ColourValue::Black, Ogre::FBT_COLOUR, and Ogre::FBT_DEPTH.

Referenced by setClearEveryFrame().

## ◆ getTarget()

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

Retrieves a pointer to the render target for this viewport.

## ◆ getCamera()

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

Retrieves a pointer to the camera for this viewport.

## ◆ setCamera()

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

Sets the camera to use for rendering to this viewport.

## ◆ getZOrder()

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

Gets the Z-Order of this viewport.

## ◆ getLeft()

float Ogre::Viewport::getLeft | ( | void |  | ) | const
| inline

## ◆ getTop()

float Ogre::Viewport::getTop | ( | void |  | ) | const
| inline

## ◆ getWidth()

float Ogre::Viewport::getWidth | ( | void |  | ) | const
| inline

## ◆ getHeight()

float Ogre::Viewport::getHeight | ( | void |  | ) | const
| inline

## ◆ getDimensions()

FloatRect Ogre::Viewport::getDimensions | ( | void |  | ) | const
| inline

## ◆ setDimensions()

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

Sets the dimensions (after creation).

Parameters

  left | Left point of viewport.
  top | Top point of the viewport.
  width | Width of the viewport.
  height | Height of the viewport.

Note
  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.

## ◆ getActualLeft()

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

## ◆ getActualTop()

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

## ◆ getActualWidth()

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

## ◆ getActualHeight()

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

## ◆ getActualDimensions() [1/2]

Rect Ogre::Viewport::getActualDimensions | ( |  | ) | const
| inline

## ◆ setBackgroundColour()

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

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

## ◆ getBackgroundColour()

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

Gets the background colour.

## ◆ setDepthClear()

void Ogre::Viewport::setDepthClear | ( | float | depth | ) |
| inline

Sets the initial depth buffer value of the viewport (before rendering).

Default is 1

## ◆ getDepthClear()

float Ogre::Viewport::getDepthClear | ( | void |  | ) | const
| inline

Gets the default depth buffer value to which the viewport is cleared.

## ◆ setClearEveryFrame()

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

Determines whether to clear the viewport before rendering.

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.

References clear(), Ogre::FBT_COLOUR, and Ogre::FBT_DEPTH.

## ◆ getClearEveryFrame()

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

Determines if the viewport is cleared before every frame.

## ◆ getClearBuffers()

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

Gets which buffers are to be cleared each frame.

## ◆ setAutoUpdated()

void Ogre::Viewport::setAutoUpdated | ( | bool | autoupdate | ) |
| inline

Sets whether this viewport should be automatically updated if Ogre's rendering loop or RenderTarget::update is being used.

By default, if you use Ogre's own rendering loop (Root::startRendering) or call RenderTarget::update, all viewports are updated automatically. This method allows you to control that behaviour, if for example you have a viewport which you only want to update periodically.

Parameters

  autoupdate | If true, the viewport is updated during the automatic render loop or when RenderTarget::update() is called. If false, the viewport is only updated when its update() method is called explicitly.

## ◆ isAutoUpdated()

bool Ogre::Viewport::isAutoUpdated | ( |  | ) | const
| inline

Gets whether this viewport is automatically updated if Ogre's rendering loop or RenderTarget::update is being used.

## ◆ setMaterialScheme()

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

Set the material scheme which the viewport should use.

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

## ◆ getMaterialScheme()

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

Get the material scheme which the viewport should use.

## ◆ getActualDimensions() [2/2]

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

Deprecated

## ◆ _isUpdated()

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

## ◆ _clearUpdatedFlag()

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

## ◆ _getNumRenderedFaces()

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

Gets the number of rendered faces in the last update.

## ◆ _getNumRenderedBatches()

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

Gets the number of rendered batches in the last update.

## ◆ setOverlaysEnabled()

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

Tells this viewport whether it should display Overlay objects.

Overlay objects are layers which appear on top of the scene. They are created via OverlayManager::create 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.

## ◆ getOverlaysEnabled()

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

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

## ◆ setSkiesEnabled()

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

Tells this viewport whether it should display skies.

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.

## ◆ getSkiesEnabled()

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

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

## ◆ setShadowsEnabled()

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

Tells this viewport whether it should display shadows.

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.

## ◆ getShadowsEnabled()

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

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

## ◆ setVisibilityMask()

void Ogre::Viewport::setVisibilityMask | ( | uint32 | mask | ) |
| inline

Sets a per-viewport visibility mask.

The visibility mask is a way to exclude objects from rendering for a given viewport. For each object in the frustum, a check is made between this mask and the objects visibility flags, and if a binary 'and' returns zero, the object will not be rendered.

See also
  MovableObject::setVisibilityFlags

## ◆ getVisibilityMask()

uint Ogre::Viewport::getVisibilityMask | ( | void |  | ) | const
| inline

Gets a per-viewport visibility mask.

See also
  Viewport::setVisibilityMask

## ◆ addListener()

void Ogre::Viewport::addListener | ( | Listener * | l | ) |

Add a listener to this viewport.

## ◆ removeListener()

void Ogre::Viewport::removeListener | ( | Listener * | l | ) |

Remove a listener to this viewport.

## ◆ setDrawBuffer()

void Ogre::Viewport::setDrawBuffer | ( | ColourBufferType | colourBuffer | ) |
| inline

Sets the draw buffer type for the next frame.

Specifies the particular buffer that will be targeted by the render target. Should be used if the render target supports quad buffer stereo. If the render target does not support stereo (ie. left and right), then only back and front will be used.

Parameters

  colourBuffer | Specifies the particular buffer that will be targeted by the render target.

## ◆ getDrawBuffer()

ColourBufferType Ogre::Viewport::getDrawBuffer | ( |  | ) | const
| inline

Returns the current colour buffer type for this viewport.

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

- OgreViewport.h