Castle Game Engine: CastleGLShadowVolumes: Class TGLShadowVolumeRenderer

# Class TGLShadowVolumeRenderer
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleGLShadowVolumes ## Declaration `type TGLShadowVolumeRenderer = class(TBaseShadowVolumeRenderer)` ## Description Shadow volume rendering in OpenGL. This class provides various utilities related to shadow volume rendering. It provides everything, except it doesn't actually render the 3D models or their shadow volumes (actual rendering is provided by T3D descendants, like TCastleScene.Render and TCastleScene.RenderShadowVolume). For general usage tutorial of this class, see [http://castle-engine.sourceforge.net/vrml_engine_doc/output/xsl/html/chapter.shadows.html] ## Hierarchy TObject TBaseShadowVolumeRenderer TGLShadowVolumeRenderer ## Overview ### Methods
| `constructor Create;`
| `procedure GLContextOpen;`
| `procedure InitFrustumAndLight( const Frustum: TFrustum; const ALightPosition: TVector4Single);`
| `procedure InitScene(const SceneBox: TBox3D);`
| `procedure InitSceneDontSetupStencil(const SceneBox: TBox3D);`
| `procedure InitSceneOnlySetupStencil;`
| `procedure InitSceneAlwaysVisible;`
| `procedure Render( const Params: TRenderParams; const Render3D: TSVRenderParamsProc; const RenderShadowVolumes: TSVRenderProc; const DrawShadowVolumes: boolean);`
### Properties
| `property WrapAvailable: boolean read FWrapAvailable;`
| `property LightPosition: TVector4Single read FLightPosition;`
| `property LightPositionDouble: TVector4Double read FLightPositionDouble;`
| `property SceneShadowPossiblyVisible: boolean read FSceneShadowPossiblyVisible;`
| `property ZFail: boolean read FZFail;`
| `property ZFailAndLightCap: boolean read FZFailAndLightCap;`
| `property StencilTwoSided: boolean read FStencilTwoSided;`
| `property StencilSetupKind: TStencilSetupKind read FStencilSetupKind write FStencilSetupKind default ssFrontAndBack;`
| `property Count: boolean read FCount write FCount default true;`
| `property CountScenes: Cardinal read FCountScenes;`
| `property CountShadowsNotVisible: Cardinal read FCountShadowsNotVisible;`
| `property CountZPass: Cardinal read FCountZPass;`
| `property CountZFailNoLightCap: Cardinal read FCountZFailNoLightCap;`
| `property CountZFailAndLightCap: Cardinal read FCountZFailAndLightCap;`
## Description ### Methods
| `constructor Create;`
| `procedure GLContextOpen;`
Call this when OpenGL context is initialized, this will set some things. For now, this sets StencilOpIncrWrap, StencilOpDecrWrap.
| `procedure InitFrustumAndLight( const Frustum: TFrustum; const ALightPosition: TVector4Single);`
Call this when camera frustum is known and light position (of the shadow casting light) is known, typically at the beginning of your drawing routine. You have to call this before InitScene. This prepares some things (so that each InitScene call doesn't have to) and all subsequent InitScene calls assume that Frustum and LightPosition are the same. It also resets CountScenes etc. counters for debug purposes.
| `procedure InitScene(const SceneBox: TBox3D);`
Call this when the bounding box of shadow caster is known. This calculates various things related to shadow volumes rendering of this scene. 1. checks whether you need to render shadow of the object inside SceneBox, settting SceneShadowPossiblyVisible. 2. checks whether ZFail method is needed, setting ZFail. This assumes that Frustum and LightPosition values given in InitFrustumAndLight are OK. Also note that after InitFrustumAndLight, all `InitScene` will assume that they have complete control over glStencilOp states for the time of rendering shadow volumes. In other words: `InitScene` will setup some stencil configuration, depending on ZFail state and StencilSetupKind. For the sake of speed, we try to avoid setting the same state twice, so we optimize it: first `InitScene` after InitFrustumAndLight does always setup stencil confguration. Following `InitScene` will only change stencil configuration if ZFail value will actually change. This means that if e.g. all objects will be detected to be in z-pass method, then stencil configuration will be done only once. The above optimization works OK if you do not change StencilOp configuration yourself during SV rendering.
| `procedure InitSceneDontSetupStencil(const SceneBox: TBox3D);`
You can split InitScene call into these two calls, first `InitSceneDontSetupStencil` and then InitSceneOnlySetupStencil. This is useful only in very special cases, in particular: if you only have one shadow caster object in your scene. Then you can call `InitSceneDontSetupStencil` only once, before any drawing, and later you can call InitSceneOnlySetupStencil multiple times to set stencil configuration for this object.
| `procedure InitSceneOnlySetupStencil;`
| `procedure InitSceneAlwaysVisible;`
Initialize scene, assuming shadow caster is always visible. This is an alternative version of InitScene that initializes the same variables as InitScene, but assumes that the scene, along with it's shadow, will always be visible. This means that for example SceneShadowPossiblyVisible, ZFail, ZFailAndLightCap will always be `True`. Use this only if you have a scene that will really be always visible and z-fail will be needed. For example, level scene in FPS games will usually be always visible, so making optimizations in InitScene may be useless. Also, this is useful if for any reason you don't know bounding box of the scene.
| `procedure Render( const Params: TRenderParams; const Render3D: TSVRenderParamsProc; const RenderShadowVolumes: TSVRenderProc; const DrawShadowVolumes: boolean);`
Do actual rendering with shadow volumes. You have to provide the appropriate callbacks that render given scene parts. Params.Transparent and Params.ShadowVolumesReceivers and Params.InShadow are changed here (their previous values are ignored). They cannot be modified by our callbacks. Render3D renders part of the scene. With Params.ShadowVolumesReceivers = `True`, renders only things that may be in the shadow. You should use Params.InShadow to either display the version of the scene in the shadows (so probably darker, probably with some lights off) or the version that is currently lighted (probably brighter, with normal scene lights on). With Params.ShadowVolumesReceivers = `False`, renders only things that must never be considered in shadow (are not shadow receivers). Params.InShadow is always `False` when Params.ShadowVolumesReceivers = `False`. Render3D must also honour Params.Transparent, rendering only opaque or only transparent parts. For Transparent = `True`, always Params.InShadow = `False`. Shadow volumes simply don't allow transparent object to function properly as shadow receivers. Reading [http://developer.nvidia.com/object/fast_shadow_volumes.html] notes: they also just do separate rendering pass to render the partially-transparent parts, IOW they also note that transparent parts simply don't work at all with shadow volumes. RenderShadowVolumes renders shadow volumes from shadow casters. If DrawShadowVolumes then shadow volumes will be also actually drawn to color buffer (as yellow blended polygons), this is useful for debugging shadow volumes.
### Properties
| `property WrapAvailable: boolean read FWrapAvailable;`
| `property LightPosition: TVector4Single read FLightPosition;`
Light casting shadows position, initialized by InitFrustumAndLight.
| `property LightPositionDouble: TVector4Double read FLightPositionDouble;`
| `property SceneShadowPossiblyVisible: boolean read FSceneShadowPossiblyVisible;`
Does the shadow need to be rendered, set by InitScene.
| `property ZFail: boolean read FZFail;`
Is the `ZFail` method needed, set by InitScene.
| `property ZFailAndLightCap: boolean read FZFailAndLightCap;`
Is the ZFail with light caps method needed, set by InitScene.
| `property StencilTwoSided: boolean read FStencilTwoSided;`
Is two-sided stencil test (that allows you to make SV in a single pass) available. This is initialized by GLContextOpen, and is true if OpenGL provides one of: glStencilOpSeparate (in OpenGL >= 2.0) GL_ATI_separate_stencil extension, glStencilOpSeparateATI We could also handle GL_EXT_stencil_two_side extension, glActiveStencilFaceEXT. But, since OpenGL >= 2.0 is now common, don't try.
| `property StencilSetupKind: TStencilSetupKind read FStencilSetupKind write FStencilSetupKind default ssFrontAndBack;`
What kind of stencil settings should be set by InitScene. Set ssFrontAndBack only if StencilTwoSided is `True`. Otherwise, you have to use 2-pass method (render everything 2 times, culling front one time, culling back second time) — in this case use ssFront or ssBack as appropriate.
| `property Count: boolean read FCount write FCount default true;`
Statistics of shadow volumes. They are enabled by default, as calculating them takes practically no time.
| `property CountScenes: Cardinal read FCountScenes;`
| `property CountShadowsNotVisible: Cardinal read FCountShadowsNotVisible;`
| `property CountZPass: Cardinal read FCountZPass;`
| `property CountZFailNoLightCap: Cardinal read FCountZFailNoLightCap;`
| `property CountZFailAndLightCap: Cardinal read FCountZFailAndLightCap;`
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:12