OGRE-Next: Ogre::PlanarReflections Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Classes | Public Types | Public Member Functions | List of all members
Ogre::PlanarReflections Class Reference
Component » Material

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)
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 ()
bool | cameraMatches (const Camera *camera)
| Returns true if the Camera settings (position, orientation, aspect ratio, etc) match with the reflection we have in cache.
uint8 | countActiveActors () const
void | destroyActor (PlanarReflectionActor *actor)
void | destroyAllActors ()
void | fillConstBufferData (TextureGpu *renderTarget, const Camera *camera, float *RESTRICT_ALIAS passBufferPtr) const
| Fills 'passBufferPtr' with the necessary data for PlanarReflections.
size_t | getConstBufferSize () const
| Returns the amount of bytes that fillConstBufferData is going to fill.
uint8 | getMaxActiveActors () const
uint8 | getMaxNumMipmaps () const
TextureGpu * | 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, PixelFormatGpu 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 | ( |  | ) | 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 | ( |  | ) |

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

## ◆ countActiveActors()

uint8 Ogre::PlanarReflections::countActiveActors | ( |  | ) | const

## ◆ destroyActor()

void Ogre::PlanarReflections::destroyActor | ( | PlanarReflectionActor * | actor | ) |

## ◆ destroyAllActors()

void Ogre::PlanarReflections::destroyAllActors | ( |  | ) |

## ◆ fillConstBufferData()

void Ogre::PlanarReflections::fillConstBufferData | ( | TextureGpu * | renderTarget,
|  | const Camera * | camera,
|  | 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.

References RESTRICT_ALIAS.

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

  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,
|  | 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

  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 (not recommended since we assume the number of mipmaps is the same for all actors. This affects surfaces with roughness > 0).
  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