OGRE  1.12.0
Object-Oriented Graphics Rendering Engine
Ogre::Viewport Class Reference

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

#include <OgreViewport.h>

+ Inheritance diagram for Ogre::Viewport:

Classes

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

Public Member Functions

 Viewport (Camera *camera, RenderTarget *target, Real left, Real top, Real width, Real height, int ZOrder)
 The usual constructor. More...
 
virtual ~Viewport ()
 Default destructor. More...
 
void _clearUpdatedFlag (void)
 
unsigned int _getNumRenderedBatches (void) const
 Gets the number of rendered batches in the last update. More...
 
unsigned int _getNumRenderedFaces (void) const
 Gets the number of rendered faces in the last update. More...
 
RenderQueueInvocationSequence_getRenderQueueInvocationSequence (void)
 Get the invocation sequence - will return null if using standard. More...
 
bool _isUpdated (void) const
 
void _updateDimensions (void)
 Notifies the viewport of a possible change in dimensions. More...
 
void addListener (Listener *l)
 Add a listener to this viewport. More...
 
void clear (unsigned int buffers=FBT_COLOUR|FBT_DEPTH, const ColourValue &colour=ColourValue::Black, Real depth=1.0f, unsigned short stencil=0)
 Instructs the viewport to clear itself, without performing an update. More...
 
void getActualDimensions (int &left, int &top, int &width, int &height) const
 Access to actual dimensions (based on target size). More...
 
int getActualHeight (void) const
 Gets one of the actual dimensions of the viewport, a value in pixels. More...
 
int getActualLeft (void) const
 Gets one of the actual dimensions of the viewport, a value in pixels. More...
 
int getActualTop (void) const
 Gets one of the actual dimensions of the viewport, a value in pixels. More...
 
int getActualWidth (void) const
 Gets one of the actual dimensions of the viewport, a value in pixels. More...
 
const ColourValuegetBackgroundColour (void) const
 Gets the background colour. More...
 
CameragetCamera (void) const
 Retrieves a pointer to the camera for this viewport. More...
 
unsigned int getClearBuffers (void) const
 Gets which buffers are to be cleared each frame. More...
 
bool getClearEveryFrame (void) const
 Determines if the viewport is cleared before every frame. More...
 
Real getDepthClear (void) const
 Gets the default depth buffer value to which the viewport is cleared. More...
 
ColourBufferType getDrawBuffer () const
 Returns the current colour buffer type for this viewport. More...
 
Real getHeight (void) const
 Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0. More...
 
Real getLeft (void) const
 Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0. More...
 
const StringgetMaterialScheme (void) const
 Get the material scheme which the viewport should use. More...
 
OrientationMode getOrientationMode () const
 Get the orientation mode of the viewport. More...
 
bool getOverlaysEnabled (void) const
 Returns whether or not Overlay objects (created in the SceneManager) are displayed in this viewport. More...
 
virtual const StringgetRenderQueueInvocationSequenceName (void) const
 Gets the name of the render queue invocation sequence for this target. More...
 
bool getShadowsEnabled (void) const
 Returns whether or not shadows (defined in the SceneManager) are displayed in this viewport. More...
 
bool getSkiesEnabled (void) const
 Returns whether or not skies (created in the SceneManager) are displayed in this viewport. More...
 
RenderTargetgetTarget (void) const
 Retrieves a pointer to the render target for this viewport. More...
 
Real getTop (void) const
 Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0. More...
 
uint getVisibilityMask (void) const
 Gets a per-viewport visibility mask. More...
 
Real getWidth (void) const
 Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0. More...
 
int getZOrder (void) const
 Gets the Z-Order of this viewport. More...
 
bool isAutoUpdated () const
 Gets whether this viewport is automatically updated if Ogre's rendering loop or RenderTarget::update is being used. More...
 
void pointOrientedToScreen (const Vector2 &v, int orientationMode, Vector2 &outv)
 Convert oriented input point coordinates to screen coordinates. More...
 
void pointOrientedToScreen (Real orientedX, Real orientedY, int orientationMode, Real &screenX, Real &screenY)
 
void removeListener (Listener *l)
 Remove a listener to this viewport. More...
 
void setAutoUpdated (bool autoupdate)
 Sets whether this viewport should be automatically updated if Ogre's rendering loop or RenderTarget::update is being used. More...
 
void setBackgroundColour (const ColourValue &colour)
 Sets the initial background colour of the viewport (before rendering). More...
 
void setCamera (Camera *cam)
 Sets the camera to use for rendering to this viewport. More...
 
void setClearEveryFrame (bool clear, unsigned int buffers=FBT_COLOUR|FBT_DEPTH)
 Determines whether to clear the viewport before rendering. More...
 
void setDepthClear (Real depth)
 Sets the initial depth buffer value of the viewport (before rendering). More...
 
void setDimensions (Real left, Real top, Real width, Real height)
 Sets the dimensions (after creation). More...
 
void setDrawBuffer (ColourBufferType colourBuffer)
 Sets the draw buffer type for the next frame. More...
 
void setMaterialScheme (const String &schemeName)
 Set the material scheme which the viewport should use. More...
 
void setOrientationMode (OrientationMode orientationMode, bool setDefault=true)
 Set the orientation mode of the viewport. More...
 
void setOverlaysEnabled (bool enabled)
 Tells this viewport whether it should display Overlay objects. More...
 
virtual void setRenderQueueInvocationSequenceName (const String &sequenceName)
 Sets the use of a custom RenderQueueInvocationSequence for rendering this target. More...
 
void setShadowsEnabled (bool enabled)
 Tells this viewport whether it should display shadows. More...
 
void setSkiesEnabled (bool enabled)
 Tells this viewport whether it should display skies. More...
 
void setVisibilityMask (uint32 mask)
 Sets a per-viewport visibility mask. More...
 
void update (void)
 Instructs the viewport to updates its contents. More...
 

Static Public Member Functions

static OrientationMode getDefaultOrientationMode ()
 Get the initial orientation mode of viewports. More...
 
static void setDefaultOrientationMode (OrientationMode orientationMode)
 Set the initial orientation mode of viewports. More...
 

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.

Constructor & Destructor Documentation

◆ Viewport()

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

The usual constructor.

Parameters
cameraPointer to a camera to be the source for the image.
targetPointer to the render target to be the destination for the rendering.
left,top,width,heightDimensions 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.
ZOrderRelative Z-order on the target. Lower = further to the front.

◆ ~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.

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.

◆ update()

void Ogre::Viewport::update ( void  )

Instructs the viewport to updates its contents.

◆ clear()

void Ogre::Viewport::clear ( unsigned int  buffers = FBT_COLOUR|FBT_DEPTH,
const ColourValue colour = ColourValue::Black,
Real  depth = 1.0f,
unsigned short  stencil = 0 
)

Instructs the viewport to clear itself, without performing an update.

Remarks
You would not normally call this method when updating the viewport, since the viewport usually clears itself when updating anyway (
See also
Viewport::setClearEveryFrame). However, if you wish you have the option of manually clearing the frame buffer (or elements of it) using this method.
Parameters
buffersBitmask identifying which buffer elements to clear
colourThe colour value to clear to, if FBT_COLOUR is included
depthThe depth value to clear to, if FBT_DEPTH is included
stencilThe stencil value to clear to, if FBT_STENCIL is included

◆ getTarget()

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

Retrieves a pointer to the render target for this viewport.

◆ getCamera()

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

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

Gets the Z-Order of this viewport.

◆ getLeft()

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

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

◆ getTop()

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

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

◆ getWidth()

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

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

◆ getHeight()

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

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

◆ getActualLeft()

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

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

◆ getActualTop()

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

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

◆ getActualWidth()

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

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

◆ getActualHeight()

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

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

◆ setDimensions()

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

Sets the dimensions (after creation).

Parameters
leftLeft point of viewport.
topTop point of the viewport.
widthWidth of the viewport.
heightHeight 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.

◆ setOrientationMode()

void Ogre::Viewport::setOrientationMode ( OrientationMode  orientationMode,
bool  setDefault = true 
)

Set the orientation mode of the viewport.

◆ getOrientationMode()

OrientationMode Ogre::Viewport::getOrientationMode ( ) const

Get the orientation mode of the viewport.

◆ setDefaultOrientationMode()

static void Ogre::Viewport::setDefaultOrientationMode ( OrientationMode  orientationMode)
static

Set the initial orientation mode of viewports.

◆ getDefaultOrientationMode()

static OrientationMode Ogre::Viewport::getDefaultOrientationMode ( )
static

Get the initial orientation mode of viewports.

◆ setBackgroundColour()

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

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

◆ getBackgroundColour()

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

Gets the background colour.

◆ setDepthClear()

void Ogre::Viewport::setDepthClear ( Real  depth)

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

Default is 1

◆ getDepthClear()

Real Ogre::Viewport::getDepthClear ( void  ) const

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.

Remarks
You can use this method to set which buffers are cleared (if any) before rendering every frame.
Parameters
clearWhether or not to clear any buffers
buffersOne 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.

◆ getClearEveryFrame()

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

Determines if the viewport is cleared before every frame.

◆ getClearBuffers()

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

Gets which buffers are to be cleared each frame.

◆ setAutoUpdated()

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

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

Remarks
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
autoupdateIf 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

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.

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

◆ getMaterialScheme()

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

Get the material scheme which the viewport should use.

◆ getActualDimensions()

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

Access to actual dimensions (based on target size).

◆ _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)

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
enabledIf true, any overlays are displayed, if false they are not.

◆ getOverlaysEnabled()

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

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

◆ setSkiesEnabled()

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
enabledIf true, any skies are displayed, if false they are not.

◆ getSkiesEnabled()

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

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

◆ setShadowsEnabled()

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
enabledIf true, any shadows are displayed, if false they are not.

◆ getShadowsEnabled()

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

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.

Remarks
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 (
See also
MovableObject::setVisibilityFlags), and if a binary 'and' returns zero, the object will not be rendered.

◆ getVisibilityMask()

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

Gets a per-viewport visibility mask.

See also
Viewport::setVisibilityMask

◆ setRenderQueueInvocationSequenceName()

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
sequenceNameThe name of the RenderQueueInvocationSequence to use. If you specify a blank string, behaviour will return to the default render queue management.

◆ getRenderQueueInvocationSequenceName()

virtual const String& Ogre::Viewport::getRenderQueueInvocationSequenceName ( void  ) const
virtual

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

◆ _getRenderQueueInvocationSequence()

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

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

◆ pointOrientedToScreen() [1/2]

void Ogre::Viewport::pointOrientedToScreen ( const Vector2 v,
int  orientationMode,
Vector2 outv 
)

Convert oriented input point coordinates to screen coordinates.

◆ pointOrientedToScreen() [2/2]

void Ogre::Viewport::pointOrientedToScreen ( Real  orientedX,
Real  orientedY,
int  orientationMode,
Real screenX,
Real screenY 
)

◆ 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)

Sets the draw buffer type for the next frame.

Remarks
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
colourBufferSpecifies the particular buffer that will be targeted by the render target.

◆ getDrawBuffer()

ColourBufferType Ogre::Viewport::getDrawBuffer ( ) const

Returns the current colour buffer type for this viewport.


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