Ogre::Viewport Class Reference
[RenderSystem]

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.
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.
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.
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	setOrientationMode (OrientationMode orientationMode, bool setDefault=true)
	Set the orientation mode of the viewport.
OrientationMode	getOrientationMode () const
	Get the orientation mode of the viewport.
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	setDepthClear (Real depth)
	Sets the initial depth buffer value of the viewport (before rendering).
Real	getDepthClear (void) const
	Gets the default depth buffer value to which the viewport is cleared.
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	setAutoUpdated (bool autoupdate)
	Sets whether this viewport should be automatically updated if Ogre's rendering loop or RenderTarget::update is being used.
bool	isAutoUpdated () const
	Gets whether this viewport is automatically updated if Ogre's rendering loop or RenderTarget::update is being used.
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.
unsigned int	_getNumRenderedBatches (void) const
	Gets the number of rendered batches 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.
void	setVisibilityMask (uint32 mask)
	Sets a per-viewport visibility mask.
uint	getVisibilityMask (void) const
	Gets a per-viewport visibility mask.
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.
void	pointOrientedToScreen (const Vector2 &v, int orientationMode, Vector2 &outv)
	Convert oriented input point coordinates to screen coordinates.
void	pointOrientedToScreen (Real orientedX, Real orientedY, int orientationMode, Real &screenX, Real &screenY)
void	addListener (Listener *l)
	Add a listener to this camera.
void	removeListener (Listener *l)
	Remove a listener to this camera.
void *	operator new (size_t sz, const char file, int line, const char func)
	operator new, with debug line info
void *	operator new (size_t sz)
void *	operator new (size_t sz, void *ptr)
	placement operator new
void *	operator new[] (size_t sz, const char file, int line, const char func)
	array operator new, with debug line info
void *	operator new[] (size_t sz)
void	operator delete (void *ptr)
void	operator delete (void ptr, void )
void	operator delete (void ptr, const char , int, const char *)
void	operator delete[] (void *ptr)
void	operator delete[] (void ptr, const char , int, const char *)
Static Public Member Functions
static void	setDefaultOrientationMode (OrientationMode orientationMode)
	Set the initial orientation mode of viewports.
static OrientationMode	getDefaultOrientationMode ()
	Get the initial orientation mode of viewports.
Protected Types
typedef vector< Listener * >::type	ListenerList
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.
Real	mDepthClearValue
bool	mClearEveryFrame
unsigned int	mClearBuffers
bool	mUpdated
bool	mShowOverlays
bool	mShowSkies
bool	mShowShadows
uint32	mVisibilityMask
String	mRQSequenceName
RenderQueueInvocationSequence *	mRQSequence
String	mMaterialSchemeName
	Material scheme.
OrientationMode	mOrientationMode
	Viewport orientation mode.
bool	mIsAutoUpdated
	Automatic rendering on/off.
ListenerList	mListeners
Static Protected Attributes
static OrientationMode	mDefaultOrientationMode

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 56 of file OgreViewport.h.

Member Typedef Documentation

typedef vector<Listener*>::type Ogre::Viewport::ListenerList [protected]

Definition at line 425 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::_getNumRenderedBatches ( void ) const

Gets the number of rendered batches in the last update.

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::addListener ( Listener * l )

Add a listener to this camera.

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:

	buffers	Bitmask identifying which buffer elements to clear
	colour	The colour value to clear to, if FBT_COLOUR is included
	depth	The depth value to clear to, if FBT_DEPTH is included
	stencil	The stencil value to clear to, if FBT_STENCIL is included

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.

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

Get the initial orientation mode of viewports.

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

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

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 285 of file OgreViewport.h.

OrientationMode Ogre::Viewport::getOrientationMode ( ) const

Get the orientation mode of the viewport.

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.

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

Gets a per-viewport visibility mask.

See also:: Viewport::setVisibilityMask

Definition at line 364 of file OgreViewport.h.

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.

bool Ogre::Viewport::isAutoUpdated ( ) const

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

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 107 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete	(	void *	ptr,
		void *
	)			`[inherited]`

Definition at line 101 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void * ptr ) [inherited]

Definition at line 95 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[]	(	void *	ptr,
		const char *	,
		int	,
		const char *
	)			`[inherited]`

Definition at line 118 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] ( void * ptr ) [inherited]

Definition at line 112 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		void *	ptr
	)			`[inherited]`

placement operator new

Definition at line 78 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new ( size_t sz ) [inherited]

Definition at line 72 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

operator new, with debug line info

Definition at line 67 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t sz ) [inherited]

Definition at line 90 of file OgreMemoryAllocatedObject.h.

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[]	(	size_t	sz,
		const char *	file,
		int	line,
		const char *	func
	)			`[inherited]`

array operator new, with debug line info

Definition at line 85 of file OgreMemoryAllocatedObject.h.

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

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

Convert oriented input point coordinates to screen coordinates.

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

Remove a listener to this camera.

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:

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.

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.

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

Set the initial orientation mode of viewports.

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

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

Default is 1

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 280 of file OgreViewport.h.

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

Set the orientation mode of the viewport.

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 default 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::setVisibilityMask ( uint32 mask )

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 (