OGRE-Next: Ogre::CompositorShadowNode Class Reference

| OGRE-Next 3.0.0 Object-Oriented Graphics Rendering Engine

Loading...
Searching...
No Matches
Ogre::CompositorShadowNode Class Reference
Core » Effects

Shadow Nodes are special nodes (not to be confused with CompositorNode) that are only used for rendering shadow maps. More...

`#include <OgreCompositorShadowNode.h>`

Inheritance diagram for Ogre::CompositorShadowNode:
[legend]

## Public Types
typedef vector< bool >::type | LightsBitSet

## Public Member Functions
| CompositorShadowNode (IdType id, const CompositorShadowNodeDef *definition, CompositorWorkspace *workspace, RenderSystem *renderSys, TextureGpu *finalTarget)
| ~CompositorShadowNode () override
bool | _shouldUpdateShadowMapIdx (uint32 shadowMapIdx) const
void | _update (Camera *camera, const Camera *lodCamera, SceneManager *sceneManager)
| Renders into the shadow map, executes passes.
void | finalTargetResized01 (const TextureGpu *finalTarget) override
| Called by CompositorManager2 when (i.e.) the RenderWindow was resized, thus our RTs that depend on their resolution need to be recreated.
const LightsBitSet & | getAffectedLightsBitSet () const
const AxisAlignedBox & | getCastersBox () const
const TextureGpuVec & | getContiguousShadowMapTex () const
const CompositorShadowNodeDef * | getDefinition () const
uint32 | getIndexToContiguousShadowMapTex (size_t shadowMapIdx) const
const Light * | getLightAssociatedWith (size_t shadowMapIdx) const
| Note: May return null if there is no such shadowMapIdx, or if there is no light that could be linked with that shadow map index.
void | getMinMaxDepthRange (const Frustum *shadowMapCamera, Real &outMin, Real &outMax) const
| Outputs the min & max depth range for the given camera.
void | getMinMaxDepthRange (size_t shadowMapIdx, Real &outMin, Real &outMax) const
float | getNormalOffsetBias (const size_t shadowMapIdx) const
size_t | getNumActiveShadowCastingLights () const
| The return value may change in the future, which happens when the number of lights changes to or from a value lower than the supported shadow casting lights by the definition.
const vector< Real >::type * | getPssmBlends (size_t shadowMapIdx) const
| Returns a list of points with the blend band boundaries of the closest N-1 PSSM split in projection space for the given shadow map index.
const Real * | getPssmFade (size_t shadowMapIdx) const
| Returns the fade point of the last PSSM split in projection space for the given shadow map index.
const vector< Real >::type * | getPssmSplits (size_t shadowMapIdx) const
| Returns a list of points with the limits of each PSSM split in projection space for the given shadow map index.
const LightClosestArray & | getShadowCastingLights () const
uint8 | getShadowMapLightTypeMask (uint32 shadowMapIdx) const
| Do not call this if isShadowMapIdxActive == false or isShadowMapIdxInValidRange == false.
const Matrix4 & | getViewMatrix (size_t shadowMapIdx) const
| Returns the texture view matrix for the given shadow map index.
Matrix4 | getViewProjectionMatrix (size_t shadowMapIdx) const
| Returns the texture view projection matrix for the given shadow map index.
bool | isShadowMapIdxActive (size_t shadowMapIdx) const
| Returns true if the shadow map index is not active.
bool | isShadowMapIdxInValidRange (uint32 shadowMapIdx) const
void | postInitializePass (CompositorPass *pass) override
| We derive so we can override the camera with ours.
void | setLightFixedToShadowMap (size_t shadowMapIdx, Light *light)
| Marks a shadow map as statically updated, and ties the given light to always use that shadow map.
void | setStaticShadowMapDirty (size_t shadowMapIdx, bool includeLinked=true)
| Tags a static shadow map as dirty, causing Ogre to update it on the next time this Shadow node gets executed.
Public Member Functions inherited from Ogre::CompositorNode
| CompositorNode (IdType id, IdString name, const CompositorNodeDef *definition, CompositorWorkspace *workspace, RenderSystem *renderSys, TextureGpu *finalTarget)
| The Id must be unique across all engine so we can create unique named textures.
virtual | ~CompositorNode ()
const CompositorPassVec & | _getPasses () const
void | _notifyCleared ()
| Internal Use.
void | _update (const Camera *lodCamera, SceneManager *sceneManager)
| Calling this function every frame will cause us to execute all our passes (ie.
bool | areAllInputsConnected () const
void | connectBufferTo (size_t outChannelA, CompositorNode *nodeB, size_t inChannelB)
| Connects this node (let's call it node 'A') to node 'B', mapping the output channel from A into the input channel from B (buffer version).
void | connectExternalBuffer (UavBufferPacked *buffer, size_t inChannelA)
| Connects (injects) an external buffer into the given channel.
void | connectExternalRT (TextureGpu *externalTexture, size_t inChannelA)
| Connects (injects) an external RT into the given channel.
void | connectTo (size_t outChannelA, CompositorNode *nodeB, size_t inChannelB)
| Connects this node (let's call it node 'A') to node 'B', mapping the output channel from A into the input channel from B (texture version).
void | createPasses ()
| Creates all passes based on our definition.
void | destroyAllPasses ()
virtual void | finalTargetResized02 (const TextureGpu *finalTarget)
UavBufferPacked * | getDefinedBuffer (IdString bufferName) const
| Returns the buffer pointer of a buffer based on it's name.
UavBufferPacked * | getDefinedBufferNoThrow (IdString bufferName) const
TextureGpu * | getDefinedTexture (IdString textureName) const
| Returns the texture pointer of a texture based on it's name & mrt index.
const CompositorNodeDef * | getDefinition () const
bool | getEnabled () const
| Returns if this instance is enabled.
const CompositorChannelVec & | getInputChannel () const
const CompositorChannelVec & | getLocalTextures () const
IdString | getName () const
size_t | getPassNumber (CompositorPass *pass) const
| See CompositorNodeDef::getPassNumber.
RenderSystem * | getRenderSystem () const
CompositorWorkspace * | getWorkspace ()
| Returns our parent workspace.
const CompositorWorkspace * | getWorkspace () const
| Returns our parent workspace.
void | notifyDestroyed (const UavBufferPacked *buffer)
void | notifyDestroyed (TextureGpu *channel)
| Call this function when caller has destroyed a RenderTarget in which the callee may have a reference to that pointer, so that we can clean it up.
void | notifyRecreated (const UavBufferPacked *oldBuffer, UavBufferPacked *newBuffer)
void | notifyRecreated (TextureGpu *channel)
| Call this function when you're replacing the textures from oldChannel with the ones in newChannel.
void | resetAllNumPassesLeft ()
| Resets the number of passes left for every pass (see CompositorPassDef::mNumInitialPasses) Useful when you have a few starting 'initialization' passes and you want to reset them.
void | setEnabled (bool bEnabled)
| Enables or disables all instances of this node.
Public Member Functions inherited from Ogre::IdObject
| IdObject (IdType id)
| We don't call generateNewId() here, to prevent objects in the stack (i.e.
IdType | getId () const
| Get the unique id of this object.
bool | operator() (const IdObject &left, const IdObject &right)
bool | operator() (const IdObject *left, const IdObject *right)

## Detailed Description

Shadow Nodes are special nodes (not to be confused with CompositorNode) that are only used for rendering shadow maps.

Normal Compositor Nodes can share or own a ShadowNode. The ShadowNode will render the scene enough times to fill all shadow maps so the main scene pass can use them.

  ShadowNode are very flexible compared to Ogre 1.x; as they allow mixing multiple shadow camera setups for different lights.

  Shadow Nodes derive from nodes so that they can be used as regular nodes

  During a render with shadow mapping enabled, we render first the Shadow Node's pass, then render the regular scene. In the past there used to be an AABB enclosing all visible objects that receive shadows that was used for calculating the shadow maps. This forced Ogre 2.x to split rendering into two stages: _cullPhase01 & _renderPhase02. This is not needed anymore.

To summarize: a normal rendering flow with shadow map looks like this: shadowNode->setupShadowCamera( normal->getVisibleBoundsInfo() ); shadowNode->_cullPhase01(); shadowNode->_renderPhase02(); normal->_cullPhase01(); normal->_renderPhase02();

  On forward lighting passes, shadow mapping is handled in the following way: 1) Build a list of all lights visible by all cameras (SceneManager does this) 2) Traverse the list to get the closest lights to the current camera. These lights will cast shadows. 3) Build a list of the closest lights for each object (SceneManager does this) 4) Traverse this list and find those that are actually casting a shadow 5) Send to the GPU & engine the list in step 4, but shadow casting lights are put first, then sorted by proximity. See the comments inside the function setShadowMapsToPass for more information.

Author
  Matias N. Goldberg

Version
  1.0

## Member Typedef Documentation

## ◆ LightsBitSet

typedef vector<bool>::type Ogre::CompositorShadowNode::LightsBitSet

## Constructor & Destructor Documentation

## ◆ CompositorShadowNode()

Ogre::CompositorShadowNode::CompositorShadowNode | ( | IdType | id,
|  | const CompositorShadowNodeDef * | definition,
|  | CompositorWorkspace * | workspace,
|  | RenderSystem * | renderSys,
|  | TextureGpu * | finalTarget )

## ◆ ~CompositorShadowNode()

Ogre::CompositorShadowNode::~CompositorShadowNode | ( |  | ) |
| override

## Member Function Documentation

## ◆ _shouldUpdateShadowMapIdx()

bool Ogre::CompositorShadowNode::_shouldUpdateShadowMapIdx | ( | uint32 | shadowMapIdx | ) | const

## ◆ _update()

void Ogre::CompositorShadowNode::_update | ( | Camera * | camera,
|  | const Camera * | lodCamera,
|  | SceneManager * | sceneManager )

Renders into the shadow map, executes passes.

Parameters

  camera | Camera used to calculate our shadow camera (in case of directional lights).

## ◆ finalTargetResized01()

void Ogre::CompositorShadowNode::finalTargetResized01 | ( | const TextureGpu * | finalTarget | ) |
| overridevirtual

Called by CompositorManager2 when (i.e.) the RenderWindow was resized, thus our RTs that depend on their resolution need to be recreated.

Remarks
  We inform all connected nodes and passes related to us of RenderTargets/Textures that may have been recreated (pointers could become danlging otherwise).

  This is divided in two steps: recreateResizableTextures01 & recreateResizableTextures02 since in some cases in RenderPassDescriptor, setting up MRT and depth textures requires all textures to be up to date, otherwise validation errors would occur since we'll have partial data (e.g. MRT 0 is 1024x768 while MRT 1 is 800x600)

Parameters

  finalTarget | The Final Target (i.e. RenderWindow) from which we'll base our local textures' resolution.

Reimplemented from Ogre::CompositorNode.

## ◆ getAffectedLightsBitSet()

const LightsBitSet & Ogre::CompositorShadowNode::getAffectedLightsBitSet | ( |  | ) | const
| inline

## ◆ getCastersBox()

const AxisAlignedBox & Ogre::CompositorShadowNode::getCastersBox | ( |  | ) | const
| inline

See also
  mCastersBox

## ◆ getContiguousShadowMapTex()

const TextureGpuVec & Ogre::CompositorShadowNode::getContiguousShadowMapTex | ( |  | ) | const
| inline

## ◆ getDefinition()

const CompositorShadowNodeDef * Ogre::CompositorShadowNode::getDefinition | ( |  | ) | const
| inline

## ◆ getIndexToContiguousShadowMapTex()

uint32 Ogre::CompositorShadowNode::getIndexToContiguousShadowMapTex | ( | size_t | shadowMapIdx | ) | const

## ◆ getLightAssociatedWith()

const Light * Ogre::CompositorShadowNode::getLightAssociatedWith | ( | size_t | shadowMapIdx | ) | const

Note: May return null if there is no such shadowMapIdx, or if there is no light that could be linked with that shadow map index.

i.e. if isShadowMapIdxActive( shadowMapIdx ) is true, then we'll return a valid pointer.

## ◆ getMinMaxDepthRange() [1/2]

void Ogre::CompositorShadowNode::getMinMaxDepthRange | ( | const Frustum * | shadowMapCamera,
|  | Real & | outMin,
|  | Real & | outMax ) const

Outputs the min & max depth range for the given camera.

0 & 100000 if camera not found

Remarks
  Performs linear search O(N), except the overload that provides a shadowMapIdx

## ◆ getMinMaxDepthRange() [2/2]

void Ogre::CompositorShadowNode::getMinMaxDepthRange | ( | size_t | shadowMapIdx,
|  | Real & | outMin,
|  | Real & | outMax ) const

## ◆ getNormalOffsetBias()

float Ogre::CompositorShadowNode::getNormalOffsetBias | ( | const size_t | shadowMapIdx | ) | const

## ◆ getNumActiveShadowCastingLights()

size_t Ogre::CompositorShadowNode::getNumActiveShadowCastingLights | ( |  | ) | const
| inline

The return value may change in the future, which happens when the number of lights changes to or from a value lower than the supported shadow casting lights by the definition.

## ◆ getPssmBlends()

const vector< Real >::type * Ogre::CompositorShadowNode::getPssmBlends | ( | size_t | shadowMapIdx | ) | const

Returns a list of points with the blend band boundaries of the closest N-1 PSSM split in projection space for the given shadow map index.

Remarks

See also
  getPssmSplits

Returns
  An array with the blend points. The number of elements is N-1 where N is the number of splits for that shadow map. Returns null if shadowMapIdx is out of bounds, or is not a PSSM technique.

## ◆ getPssmFade()

const Real * Ogre::CompositorShadowNode::getPssmFade | ( | size_t | shadowMapIdx | ) | const

Returns the fade point of the last PSSM split in projection space for the given shadow map index.

Remarks

See also
  getPssmSplits

Returns
  The fade point. Returns null if shadowMapIdx is out of bounds, or is not a PSSM technique.

## ◆ getPssmSplits()

const vector< Real >::type * Ogre::CompositorShadowNode::getPssmSplits | ( | size_t | shadowMapIdx | ) | const

Returns a list of points with the limits of each PSSM split in projection space for the given shadow map index.

Remarks
  If shadow map 0, 1 & 2 use light 0 with different splits, the return value should be the same for all of them.

Returns
  An array with the split points. The number of elements is N+1 where N is the number of splits for that shadow map. Returns null if shadowMapIdx is out of bounds, or is not a PSSM technique.

## ◆ getShadowCastingLights()

const LightClosestArray & Ogre::CompositorShadowNode::getShadowCastingLights | ( |  | ) | const
| inline

## ◆ getShadowMapLightTypeMask()

uint8 Ogre::CompositorShadowNode::getShadowMapLightTypeMask | ( | uint32 | shadowMapIdx | ) | const

Do not call this if isShadowMapIdxActive == false or isShadowMapIdxInValidRange == false.

## ◆ getViewMatrix()

const Matrix4 & Ogre::CompositorShadowNode::getViewMatrix | ( | size_t | shadowMapIdx | ) | const

Returns the texture view matrix for the given shadow map index.

## ◆ getViewProjectionMatrix()

Matrix4 Ogre::CompositorShadowNode::getViewProjectionMatrix | ( | size_t | shadowMapIdx | ) | const

Returns the texture view projection matrix for the given shadow map index.

## ◆ isShadowMapIdxActive()

bool Ogre::CompositorShadowNode::isShadowMapIdxActive | ( | size_t | shadowMapIdx | ) | const

Returns true if the shadow map index is not active.

For example:

- There are 3 shadow maps, but only 2 shadow casting lights
- There are 3 directional maps for directional PSSM, but no directional light.

## ◆ isShadowMapIdxInValidRange()

bool Ogre::CompositorShadowNode::isShadowMapIdxInValidRange | ( | uint32 | shadowMapIdx | ) | const

## ◆ postInitializePass()

void Ogre::CompositorShadowNode::postInitializePass | ( | CompositorPass * | pass | ) |
| overridevirtual

We derive so we can override the camera with ours.

Reimplemented from Ogre::CompositorNode.

## ◆ setLightFixedToShadowMap()

void Ogre::CompositorShadowNode::setLightFixedToShadowMap | ( | size_t | shadowMapIdx,
|  | Light * | light )

Marks a shadow map as statically updated, and ties the given light to always use that shadow map.

Remarks
  By default Ogre recalculates the shadow maps every single frame (even if nothing has changed). However if you know that whatever a light is illuminating is not changing at all (or barely changing), with static shadow maps you are the one who tells Ogre when to update it (e.g. you may only need to update it three times during the whole level); hence the framerate goes up. Perceived quality may also go up because by default Ogre applies shadow mapping on the closest lights; so shadows flip on and off as you move the camera (because lights that had no shadows get closer while lights that were using shadows get farther away). While often this is desirable, there are cases where the artist may want a particular light to always have shadows (regardless of distance); with static shadow maps you can force that; hence the perceived quality may go up (but that's up to the talent of the artist and the scene in particular).

  Note that for point & spot lights, you have to consider if the light changed (e.g. moved, rotated) or if anything that is or could be lit by the light has moved Directional lights are harder because they depend on the camera placement as well.

  Use setStaticShadowMapDirty to tell Ogre to update the shadow map in the next render.

  Ogre may call light->setCastShadows( true ); on the light.

  IMPORTANT: Do not put static and dynamic shadow maps in the same UV atlas. It's asking for trouble and will probably not work. Keep the atlas separate.

  VERY IMPORTANT: You must respect lights are set in the following order:
  1. Directional
  2. Point
  3. Spot If you have shadow maps defined that support both point & spotlight, and you want to mix both static lights with dynamic ones; set fixed point lights in the first shadow map indices and spotlight in the last indices, to avoid Ogre automatically (e.g.) placing a point light after your static spot light.

Parameters

  shadowMapIdx | Shadow map index to tie this light to. If this shadow map index is part of a PSSM split, all PSSM splits will be affected (thus you only need to call it once for any of the split that belong to the same set)
  light | Light to tie to the given shadow map. Null pointer disables it.

## ◆ setStaticShadowMapDirty()

void Ogre::CompositorShadowNode::setStaticShadowMapDirty | ( | size_t | shadowMapIdx,
|  | bool | includeLinked = true )

Tags a static shadow map as dirty, causing Ogre to update it on the next time this Shadow node gets executed.

If drawing to a texture atlas, multiple shadow maps may be sharing the same texture, thus if you're doing a clear on the whole atlas, you will need to update all of the shadow maps, not just this one. Use includeLinked=true to mark as dirty all static shadow maps that share the same atlas. Set it to false if that's explicitly what you want, or if you're already going to call it for every shadow map (otherwise you will trigger a O(N^2) behavior).

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

- OgreCompositorShadowNode.h