Ogre::PlanarReflections Class Reference

Planar Reflections can be used with both Unlit and PBS, but they're setup differently. More...

#include <OgrePlanarReflections.h>

Classes
struct	TrackedRenderable

Public Types
enum	CustomParameterBits { UseActiveActor = 0x80 , FlushPending = 0x60 , InactiveActor = 0x40 }

Public Member Functions
	PlanarReflections (SceneManager *sceneManager, CompositorManager2 *compositorManager, Real maxDistance, Camera *lockCamera)
	~PlanarReflections ()
bool	_isUpdatingRenderablesHlms (void) const
void	_notifyRenderableFlushedHlmsDatablock (Renderable *renderable)
PlanarReflectionActor *	addActor (const PlanarReflectionActor &actor)
	Adds an actor plane that other objects can use as source for reflections if they're close enough to it (and aligned enough to the normal).
void	addRenderable (const TrackedRenderable &trackedRenderable)
	Once you add a Renderable, we will automatically update its PBS material to use reflection if it's close to any active actor.
void	beginFrame (void)
bool	cameraMatches (const Camera *camera)
	Returns true if the Camera settings (position, orientation, aspect ratio, etc) match with the reflection we have in cache.
void	destroyActor (PlanarReflectionActor *actor)
void	destroyAllActors (void)
void	fillConstBufferData (RenderTarget *renderTarget, Camera *camera, const Matrix4 &projectionMatrix, float *RESTRICT_ALIAS passBufferPtr) const
	Fills 'passBufferPtr' with the necessary data for PlanarReflections.
size_t	getConstBufferSize (void) const
	Returns the amount of bytes that fillConstBufferData is going to fill.
uint8	getMaxActiveActors (void) const
TexturePtr	getTexture (uint8 actorIdx) const
bool	hasActiveActor (const Renderable *renderable) const
bool	hasFlushPending (const Renderable *renderable) const
bool	hasPlanarReflections (const Renderable *renderable) const
void	releaseReservation (PlanarReflectionActor *actor)
	Releases a reservation made with reserve().
void	removeRenderable (Renderable *renderable)
void	reserve (uint8 activeActorSlot, PlanarReflectionActor *actor)
	Reserves a particular slot (i.e.
void	setMaxActiveActors (uint8 maxActiveActors, IdString workspaceName, bool useAccurateLighting, uint32 width, uint32 height, bool withMipmaps, PixelFormat pixelFormat, bool mipmapMethodCompute)
	Setups how many actors can be active at the same time.
void	setMaxDistance (Real maxDistance)
void	update (Camera *camera, Real aspectRatio)

Detailed Description

Planar Reflections can be used with both Unlit and PBS, but they're setup differently.

Unlit is very fast, but also very basic. It's mostly useful for perfect mirrors.

An unlit datablock is tied to a particular Actor (reflection plane). PBS on the other hand, can dynamically assign Renderables to the closest actor that aligns with the Renderable's (predominant) normal, regardless of the pbs datablock it uses. If the actor is close enough but not an exact match, PBS will attempt to project the reflection in an attempt to correct this, however it's an approximation.

If you want perfect reflections, the reflection plane of the actor must match and align exactly the surface being drawn; or rely on a fallback (Local Cubemaps, SSR, etc).

Furthermore, PBS will automatically disable reflections while rendering reflections (but Unlit won't do this, so it's your job to leave it out of rendering i.e. via visibility masks).

Actors are culled against the camera, thus if they're no longer visible Ogre will stop updating those actors, improving performance.

Member Enumeration Documentation

CustomParameterBits

enum Ogre::PlanarReflections::CustomParameterBits

Enumerator
UseActiveActor
FlushPending
InactiveActor

Constructor & Destructor Documentation

PlanarReflections()

Ogre::PlanarReflections::PlanarReflections	(	SceneManager *	sceneManager,
		CompositorManager2 *	compositorManager,
		Real	maxDistance,
		Camera *	lockCamera
	)

Parameters

sceneManager
compositorManager
maxActiveActors
maxDistance
lockCamera

~PlanarReflections()

Ogre::PlanarReflections::~PlanarReflections

(

)

Member Function Documentation

_isUpdatingRenderablesHlms()

bool Ogre::PlanarReflections::_isUpdatingRenderablesHlms

(

void

)

const

_notifyRenderableFlushedHlmsDatablock()

void Ogre::PlanarReflections::_notifyRenderableFlushedHlmsDatablock

(

Renderable *

renderable

)

addActor()

PlanarReflectionActor * Ogre::PlanarReflections::addActor

(

const PlanarReflectionActor &

actor

)

Adds an actor plane that other objects can use as source for reflections if they're close enough to it (and aligned enough to the normal).

Parameters

actor

Actor to use, with some data prefilled (see PlanarReflectionActor::PlanarReflectionActor constructor)

Returns

Pointer to the created actor for further manipulation.

addRenderable()

void Ogre::PlanarReflections::addRenderable

(

const TrackedRenderable &

trackedRenderable

)

Once you add a Renderable, we will automatically update its PBS material to use reflection if it's close to any active actor.

If no active actor is close, we'll disable the reflections for that frame.

Remarks

You must call removeRenderable before destroying the Renderable. You can use PlanarReflections::hasPlanarReflections( renderable ) to tell whether this Renderable has already been added.

Parameters

trackedRenderable

See TrackedRenderable::TrackedRenderable.

beginFrame()

void Ogre::PlanarReflections::beginFrame

(

void

)

cameraMatches()

bool Ogre::PlanarReflections::cameraMatches

(

const Camera *

camera

)

Returns true if the Camera settings (position, orientation, aspect ratio, etc) match with the reflection we have in cache.

destroyActor()

void Ogre::PlanarReflections::destroyActor

(

PlanarReflectionActor *

actor

)

destroyAllActors()

void Ogre::PlanarReflections::destroyAllActors

(

void

)

fillConstBufferData()

void Ogre::PlanarReflections::fillConstBufferData	(	RenderTarget *	renderTarget,
		Camera *	camera,
		const Matrix4 &	projectionMatrix,
		float *RESTRICT_ALIAS	passBufferPtr
	)		const

Fills 'passBufferPtr' with the necessary data for PlanarReflections.

See also

getConstBufferSize

Remarks

Assumes 'passBufferPtr' is aligned to a vec4/float4 boundary.

getConstBufferSize()

size_t Ogre::PlanarReflections::getConstBufferSize

(

void

)

const

Returns the amount of bytes that fillConstBufferData is going to fill.

getMaxActiveActors()

uint8 Ogre::PlanarReflections::getMaxActiveActors ( void  ) const

inline

getTexture()

TexturePtr Ogre::PlanarReflections::getTexture

(

uint8

actorIdx

)

const

hasActiveActor()

bool Ogre::PlanarReflections::hasActiveActor

(

const Renderable *

renderable

)

const

hasFlushPending()

bool Ogre::PlanarReflections::hasFlushPending

(

const Renderable *

renderable

)

const

hasPlanarReflections()

bool Ogre::PlanarReflections::hasPlanarReflections

(

const Renderable *

renderable

)

const

releaseReservation()

void Ogre::PlanarReflections::releaseReservation

(

PlanarReflectionActor *

actor

)

Releases a reservation made with reserve().

This is done automatically if you call destroyActor

removeRenderable()

void Ogre::PlanarReflections::removeRenderable

(

Renderable *

renderable

)

reserve()

void Ogre::PlanarReflections::reserve	(	uint8	activeActorSlot,
		PlanarReflectionActor *	actor
	)

Reserves a particular slot (i.e.

texture) to be used only with a specifc actor. A slot can only be reserved by one actor at a time. If this actor doesn't activate (i.e. it's culled by the camera), the slot won't be used and thus the contents of the texture will remain unchanged.

Remarks

Reservation is useful to have a texture be linked always with the same actor, which can be used to avoid updating it while still showing a (partially wrong) reflection (as a performance improvement) or for using actors with HlmsUnlit, which can only bind reflection textures with materials; rather than binding actors with materials.

Parameters

activeActorSlot	Slot to reserve. Must be in range [0; mMaxActiveActors)
actor	Actor to link this reservation with.

setMaxActiveActors()

void Ogre::PlanarReflections::setMaxActiveActors	(	uint8	maxActiveActors,
		IdString	workspaceName,
		bool	useAccurateLighting,
		uint32	width,
		uint32	height,
		bool	withMipmaps,
		PixelFormat	pixelFormat,
		bool	mipmapMethodCompute
	)

Setups how many actors can be active at the same time.

You may have many actors (i.e. 1000 actors), but for performance and memory reasons you may only want 1-5 actors at the same time. Actors are dynamically activated based on distance to camera.

Remarks

Note HlmsPbs hardcodes the max number of actors, so changing this value after having rendered a few frames could cause many shaders to be recompiled.

Parameters

maxActiveActors	New max active actors. Can be lower or higher than its previous value. When this value is less or equal than current value, all the next parameters are ignored. When this value is higher than its previous, value, the new active actors will use these parameters; which don't have to necessarily match previous calls.
workspaceName	Workspace to use for rendering.
useAccurateLighting	When true, overall scene CPU usage may be higher, but lighting information in the reflections will be accurate. Turning it to false is faster. This is a performance optimization that rarely has a noticeable impact on quality.
width	Width resolution of the RTT assigned to this reflection plane
height	Height resolution of the RTT assigned to this reflection plane
withMipmaps	When true, mipmaps will be created; which are useful for glossy reflections (i.e. roughness close to 1). Set this to false if you only plan on using it for a mirror (which are always a perfect reflection... unless you want to use a roughness map to add scratches & stains to it).
pixelFormat	Pixel Format of the RTT assigned to this reflection plane
mipmapMethodCompute	Set to true if the workspace assigned via PlanarReflectionActor::workspaceName will filter the RTT with a compute filter (usually for higher quality).

setMaxDistance()

void Ogre::PlanarReflections::setMaxDistance

(

Real

maxDistance

)

update()

void Ogre::PlanarReflections::update	(	Camera *	camera,
		Real	aspectRatio
	)

---

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

• OgrePlanarReflections.h