Ogre::Viewport Class Reference

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

#include <OgreViewport.h>

Inheritance diagram for Ogre::Viewport:

Public Member Functions
	Viewport (RenderTarget *target, Real left, Real top, Real width, Real height)
	The usual constructor.
virtual	~Viewport ()
	Default destructor.
void	_clearUpdatedFlag (void)
bool	_isUpdated (void) const
void	_setVisibilityMask (uint32 mask, uint32 lightMask)
	Sets a per-viewport visibility mask.
void	_updateCullPhase01 (Camera *camera, const Camera *lodCamera, uint8 firstRq, uint8 lastRq)
	Instructs the viewport to updates its contents.
void	_updateDimensions (void)
	Notifies the viewport of a possible change in dimensions.
void	_updateRenderPhase02 (Camera *camera, const Camera *lodCamera, uint8 firstRq, uint8 lastRq)
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.
bool	coversEntireTarget (void) const
void	discard (unsigned int buffers=FBT_COLOUR|FBT_DEPTH)
	Instructs the viewport to 'discard' the buffers.
void	getActualDimensions (int &left, int &top, int &width, int &height) const
	Access to actual dimensions (based on target size).
int	getActualHeight (void) const
	Gets one of the actual dimensions of the viewport, a value in pixels.
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.
bool	getColourWrite (void) const
ColourBufferType	getDrawBuffer () const
	Returns the current colour buffer type for this viewport.
Real	getHeight (void) const
	Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
Real	getLeft (void) const
	Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
uint32	getLightVisibilityMask (void) const
const String &	getMaterialScheme (void) const
	Get the material scheme which the viewport should use.
OrientationMode	getOrientationMode () const
	Get the orientation mode of the viewport.
bool	getOverlaysEnabled (void) const
	Returns whether or not Overlay objects (created in the SceneManager) are displayed in this viewport.
bool	getReadOnlStencil (void) const
bool	getReadOnlyDepth (void) const
int	getScissorActualHeight (void) const
int	getScissorActualLeft (void) const
int	getScissorActualTop (void) const
int	getScissorActualWidth (void) const
Real	getScissorHeight (void) const
Real	getScissorLeft (void) const
Real	getScissorTop (void) const
Real	getScissorWidth (void) const
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.
Real	getTop (void) const
	Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
uint8	getViewportRenderTargetFlags (void) const
uint32	getVisibilityMask (void) const
	Gets a per-viewport visibility mask.
Real	getWidth (void) const
	Gets one of the relative dimensions of the viewport, a value between 0.0 and 1.0.
void	operator delete (void *ptr)
void	operator delete (void *ptr, const char *, int, const char *)
void	operator delete (void *ptr, void *)
void	operator delete[] (void *ptr)
void	operator delete[] (void *ptr, const char *, int, const char *)
void *	operator new (size_t sz)
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 *ptr)
	placement operator new
void *	operator new[] (size_t sz)
void *	operator new[] (size_t sz, const char *file, int line, const char *func)
	array operator new, with debug line info
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)
bool	scissorsMatchViewport (void) const
void	setColourWrite (bool colourWrite)
void	setDimensions (Real left, Real top, Real width, Real height, bool overrideScissors=true)
	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	setOrientationMode (OrientationMode orientationMode, bool setDefault=true)
	Set the orientation mode of the viewport.
void	setOverlaysEnabled (bool enabled)
	Tells this viewport whether it should display Overlay objects.
void	setReadOnly (bool readOnlyDepth, bool readOnlyStencil)
void	setScissors (Real left, Real top, Real width, Real height)
	Only sets the scissor regions.
void	setSkiesEnabled (bool enabled)
	Tells this viewport whether it should display skies.

Static Public Member Functions
static OrientationMode	getDefaultOrientationMode ()
	Get the initial orientation mode of viewports.
static void	setDefaultOrientationMode (OrientationMode orientationMode)
	Set the initial orientation mode of viewports.

Public Attributes
size_t	mGlobalIndex
	Index in the vector holding this MO reference (could be our parent node, or a global array tracking all movable objecst to avoid memory leaks).

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	(	RenderTarget *	target,
		Real	left,
		Real	top,
		Real	width,
		Real	height
	)

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.

~Viewport()

virtual Ogre::Viewport::~Viewport ( )

virtual

Default destructor.

Member Function Documentation

_clearUpdatedFlag()

void Ogre::Viewport::_clearUpdatedFlag

(

void

)

_isUpdated()

bool Ogre::Viewport::_isUpdated

(

void

)

const

_setVisibilityMask()

void Ogre::Viewport::_setVisibilityMask	(	uint32	mask,
		uint32	lightMask
	)

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.

Viewport's visibility mask assumes the user knows what he's doing with the reserved flags!

_updateCullPhase01()

void Ogre::Viewport::_updateCullPhase01	(	Camera *	camera,
		const Camera *	lodCamera,
		uint8	firstRq,
		uint8	lastRq
	)

Instructs the viewport to updates its contents.

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

_updateRenderPhase02()

void Ogre::Viewport::_updateRenderPhase02	(	Camera *	camera,
		const Camera *	lodCamera,
		uint8	firstRq,
		uint8	lastRq
	)

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

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

coversEntireTarget()

bool Ogre::Viewport::coversEntireTarget

(

void

)

const

discard()

void Ogre::Viewport::discard

(

unsigned int

buffers = FBT_COLOUR|FBT_DEPTH

)

Instructs the viewport to 'discard' the buffers.

See also

CompositorPassClearDef::mDiscardOnly

getActualDimensions()

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

Access to actual dimensions (based on target size).

getActualHeight()

int Ogre::Viewport::getActualHeight

(

void

)

const

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

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.

getColourWrite()

bool Ogre::Viewport::getColourWrite

(

void

)

const

getDefaultOrientationMode()

static OrientationMode Ogre::Viewport::getDefaultOrientationMode ( )

static

Get the initial orientation mode of viewports.

getDrawBuffer()

ColourBufferType Ogre::Viewport::getDrawBuffer

(

)

const

Returns the current colour buffer type for this viewport.

getHeight()

Real Ogre::Viewport::getHeight

(

void

)

const

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

getLeft()

Real Ogre::Viewport::getLeft

(

void

)

const

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

getLightVisibilityMask()

uint32 Ogre::Viewport::getLightVisibilityMask ( void  ) const

inline

getMaterialScheme()

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

inline

Get the material scheme which the viewport should use.

getOrientationMode()

OrientationMode Ogre::Viewport::getOrientationMode

(

)

const

Get the orientation mode of the viewport.

getOverlaysEnabled()

bool Ogre::Viewport::getOverlaysEnabled

(

void

)

const

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

getReadOnlStencil()

bool Ogre::Viewport::getReadOnlStencil

(

void

)

const

getReadOnlyDepth()

bool Ogre::Viewport::getReadOnlyDepth

(

void

)

const

getScissorActualHeight()

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

inline

getScissorActualLeft()

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

inline

getScissorActualTop()

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

inline

getScissorActualWidth()

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

inline

getScissorHeight()

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

inline

getScissorLeft()

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

inline

getScissorTop()

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

inline

getScissorWidth()

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

inline

getSkiesEnabled()

bool Ogre::Viewport::getSkiesEnabled

(

void

)

const

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

getTarget()

RenderTarget * Ogre::Viewport::getTarget

(

void

)

const

Retrieves a pointer to the render target for this viewport.

getTop()

Real Ogre::Viewport::getTop

(

void

)

const

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

getViewportRenderTargetFlags()

uint8 Ogre::Viewport::getViewportRenderTargetFlags ( void  ) const

inline

getVisibilityMask()

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

inline

Gets a per-viewport visibility mask.

See also

Viewport::setVisibilityMask

getWidth()

Real Ogre::Viewport::getWidth

(

void

)

const

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

operator delete() [1/3]

template<class Alloc >

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

inlineinherited

operator delete() [2/3]

template<class Alloc >

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

inlineinherited

operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr, void *    )

inlineinherited

operator delete[]() [1/2]

template<class Alloc >

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

inlineinherited

operator delete[]() [2/2]

template<class Alloc >

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

inlineinherited

operator new() [1/3]

template<class Alloc >

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

inlineinherited

operator new() [2/3]

template<class Alloc >

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

inlineinherited

operator new, with debug line info

operator new() [3/3]

template<class Alloc >

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

inlineinherited

placement operator new

operator new[]() [1/2]

template<class Alloc >

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

inlineinherited

operator new[]() [2/2]

template<class Alloc >

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

inlineinherited

array operator new, with debug line info

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
	)

scissorsMatchViewport()

bool Ogre::Viewport::scissorsMatchViewport

(

void

)

const

setColourWrite()

void Ogre::Viewport::setColourWrite

(

bool

colourWrite

)

setDefaultOrientationMode()

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

static

Set the initial orientation mode of viewports.

setDimensions()

void Ogre::Viewport::setDimensions	(	Real	left,
		Real	top,
		Real	width,
		Real	height,
		bool	overrideScissors = true
	)

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.
overrideScissors	When true, the scissor dimensions will be the same as the viewport's @See setScissors

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.

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

buffer

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

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

setOrientationMode()

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

Set the orientation mode of the viewport.

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

enabled

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

setReadOnly()

void Ogre::Viewport::setReadOnly	(	bool	readOnlyDepth,
		bool	readOnlyStencil
	)

setScissors()

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

Only sets the scissor regions.

The scissor rectangle must be fully inside the viewport rectangle. @See setDimensions for param description

Remarks

Only the scissor rect is set here; but the HLMS macroblock controls whether scissor testing is enabled or not (@See HlmsMacroblock). On some RenderSystem implementations (i.e. OpenGL), scissor testing needs to be enabled when clearing a region of the screen. In those cases, if scissor testing is disabled at the time of the clear, scissor testing will be temporarily enabled and then disabled.

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

enabled

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

Member Data Documentation

mGlobalIndex

size_t Ogre::Viewport::mGlobalIndex

Index in the vector holding this MO reference (could be our parent node, or a global array tracking all movable objecst to avoid memory leaks).

Used for O(1) removals.

Remarks

It is the parent (or our creator) the one that sets this value, not ourselves. Do NOT modify it manually.

---

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

• OgreViewport.h