OGRE-Next  2.3
Object-Oriented Graphics Rendering Engine
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 () const
 
void _notifyRenderableFlushedHlmsDatablock (Renderable *renderable)
 
PlanarReflectionActoraddActor (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). More...
 
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. More...
 
void beginFrame ()
 
bool cameraMatches (const Camera *camera)
 Returns true if the Camera settings (position, orientation, aspect ratio, etc) match with the reflection we have in cache. More...
 
void destroyActor (PlanarReflectionActor *actor)
 
void destroyAllActors ()
 
void fillConstBufferData (TextureGpu *renderTarget, const Camera *camera, const Matrix4 &projectionMatrix, float *RESTRICT_ALIAS passBufferPtr) const
 Fills 'passBufferPtr' with the necessary data for PlanarReflections. More...
 
size_t getConstBufferSize () const
 Returns the amount of bytes that fillConstBufferData is going to fill. More...
 
uint8 getMaxActiveActors () const
 
uint8 getMaxNumMipmaps () const
 
TextureGpugetTexture (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(). More...
 
void removeRenderable (Renderable *renderable)
 
void reserve (uint8 activeActorSlot, PlanarReflectionActor *actor)
 Reserves a particular slot (i.e. More...
 
void setMaxActiveActors (uint8 maxActiveActors, IdString workspaceName, bool useAccurateLighting, uint32 width, uint32 height, bool withMipmaps, PixelFormatGpu pixelFormat, bool mipmapMethodCompute)
 Setups how many actors can be active at the same time. More...
 
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

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 ( ) 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
actorActor 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
trackedRenderableSee TrackedRenderable::TrackedRenderable.

◆ beginFrame()

void Ogre::PlanarReflections::beginFrame ( )

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

◆ fillConstBufferData()

void Ogre::PlanarReflections::fillConstBufferData ( TextureGpu renderTarget,
const 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 ( ) const

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

◆ getMaxActiveActors()

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

◆ getMaxNumMipmaps()

uint8 Ogre::PlanarReflections::getMaxNumMipmaps ( ) const
inline

◆ getTexture()

TextureGpu* 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
activeActorSlotSlot to reserve. Must be in range [0; mMaxActiveActors)
actorActor to link this reservation with.

◆ setMaxActiveActors()

void Ogre::PlanarReflections::setMaxActiveActors ( uint8  maxActiveActors,
IdString  workspaceName,
bool  useAccurateLighting,
uint32  width,
uint32  height,
bool  withMipmaps,
PixelFormatGpu  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
maxActiveActorsNew 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 (not recommended since we assume the number of mipmaps is the same for all actors. This affects surfaces with roughness > 0).
workspaceNameWorkspace to use for rendering.
useAccurateLightingWhen 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.
widthWidth resolution of the RTT assigned to this reflection plane
heightHeight resolution of the RTT assigned to this reflection plane
withMipmapsWhen 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).
pixelFormatPixel Format of the RTT assigned to this reflection plane
mipmapMethodComputeSet 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: