#include <OgreVctLighting.h>

Inheritance diagram for Ogre::VctLighting:

Public Types
enum	Reason { Unknown , FromStorageToSysRam , FromSysRamToStorage , GainedResidency , LostResidency , PoolTextureSlotChanged , ResidentToSysRamSync , MetadataCacheOutOfDate , ExceptionThrown , FsaaSettingAlteredByApi , ReadyForRendering , Deleted }

Public Member Functions
	VctLighting (IdType id, VctVoxelizerSourceBase *voxelizer, bool bAnisotropic)

virtual	~VctLighting ()

void	addCascade (VctLighting *cascade)
	Used by VctCascadedVoxelizer. More...

void	fillConstBufferData (const Matrix4 &viewMatrix, float *RESTRICT_ALIAS passBufferPtr) const

bool	getAllowMultipleBounces () const

float	getBakingMultiplier () const

const HlmsSamplerblock *	getBindTrilinearSamplerblock ()

size_t	getConstBufferSize () const

float	getCurrentBakingMultiplier () const
	If you've set setBakingMultiplier but haven't yet called VctLighting::update with autoMultiplier = false, this function returns the baking multiplier that is currently in use (beware of floating point accuracy differences) More...

bool	getDebugVisualizationMode () const

IdType	getId () const
	Get the unique id of this object. More...

TextureGpu **	getLightVoxelTextures ()

TextureGpu **	getLightVoxelTextures (const size_t cascadeIdx)

size_t	getNumCascades () const

uint32	getNumVoxelTextures () const

const VctVoxelizerSourceBase *	getVoxelizer () const

bool	isAnisotropic () const

bool	needsAmbientHemisphere () const

virtual void	notifyTextureChanged (TextureGpu texture, TextureGpuListener::Reason reason, void extraData)
	Called when a TextureGpu changed in a way that affects how it is displayed: More...

bool	operator() (const IdObject &left, const IdObject &right)

bool	operator() (const IdObject left, const IdObject right)

void	reserveExtraCascades (size_t numExtraCascades)
	Used by VctCascadedVoxelizer. More...

void	resetTexturesFromBuildRelative ()
	When VctImageVoxelizer::buildRelative is called; voxelizer's textures (albedo, normal, emissive) may be swapped for a copy. More...

void	setAllowMultipleBounces (bool bAllowMultipleBounces)
	This function allows VctLighting::update to pass numBounces > 0 as argument. More...

void	setAmbient (const ColourValue &upperHemisphere, const ColourValue &lowerHemisphere)
	Extremely similar version of SceneManager::setAmbientLight In fact the hemisphereDir parameter is shared and set in SceneManager::setAmbientLight. More...

void	setAnisotropic (bool bAnisotropic)
	Toggles anisotropic mips. More...

void	setBakingMultiplier (float bakingMult)
	Sets baking multiplier for HDR rendering. More...

void	setDebugVisualization (bool bShow, SceneManager *sceneManager)

bool	shouldEnableSpecularSdfQuality () const

virtual bool	shouldStayLoaded (TextureGpu *texture)
	Return true if this TextureGpu should likely stay loaded or else graphical changes could occur. More...

void	update (SceneManager *sceneManager, uint32 numBounces, float thinWallCounter=1.0f, bool autoMultiplier=true, float rayMarchStepScale=1.0f, uint32 lightMask=0xffffffff)

Public Attributes
float	mMultiplier
	Sets the intensity/brightness of the GI. More...

float	mSpecularSdfQuality
	When roughness is close to 0.02, specular cone tracing becomes path tracing. More...

Static Public Attributes
static const uint16	msDistanceThresholdCustomParam

Member Enumeration Documentation

◆ Reason

enum Ogre::TextureGpuListener::Reason

inherited

Enumerator
Unknown
FromStorageToSysRam	OnStorage -> OnSystemRam.
FromSysRamToStorage	OnSystemRam -> OnStorage.
GainedResidency	OnStorage -> Resident OnSystemRam -> Resident See ReadyForRendering.
LostResidency	Resident -> OnStorage Resident -> OnSystemRam.
PoolTextureSlotChanged
ResidentToSysRamSync	Only called while TextureGpu is still Resident, and strategy is AlwaysKeepSystemRamCopy. This listener happens when something was done to the TextureGpu that modifies its contents in the GPU, and were thus forced to sync those values back to SystemRam. This listener calls tells that sync is over.
MetadataCacheOutOfDate	The Metadata cache was out of date and we had to do a ping-pong. Expect this to be followed by at least LostResidency and GainedResidency calls This is very important, because if you were expecting certain sequence of calls (e.g. you were expecting a LostResidency soon to arrive), expect that to be changed. See TextureGpuManager for details about the metadata cache.
ExceptionThrown	Called when the worker thread caught an exception. This exception has already been logged, and the texture resumed loading normally with a white 2x2 RGBA8 fallback. This listener will get called from the main thread. The texture may still have pending residency transitions (e.g. it may still be loading the 2x2 fallback) Cast Exception e = reinterpret_cast<Exception>( extraData ); to know more info
FsaaSettingAlteredByApi	Requested FSAA (MSAA / CSAA / EQAA / etc) is not supported by the API, and thus the setting had to be downgraded. Note this may happen on device lost, and a new GPU became in use; thus it's possible for a TextureGpu to initially support certain FSAA but later change.
ReadyForRendering	This Reason is called when TextureGpu::notifyDataIsReady is called. This normally means worker thread is done loading texture from file and uploading it to GPU; and can now be used for rendering. It does NOT mean that Ogre has finished issueing rendering commands to a RenderTexture and is now ready to be presented to the monitor.
Deleted

Constructor & Destructor Documentation

◆ VctLighting()

Ogre::VctLighting::VctLighting	(	IdType	id,
		VctVoxelizerSourceBase *	voxelizer,
		bool	bAnisotropic
	)

◆ ~VctLighting()

virtual Ogre::VctLighting::~VctLighting ( )

virtual

Member Function Documentation

◆ addCascade()

void Ogre::VctLighting::addCascade ( VctLighting * cascade )

Used by VctCascadedVoxelizer.

By having extra cascade info, we can calculate multiple bounces with extra info

◆ fillConstBufferData()

void Ogre::VctLighting::fillConstBufferData	(	const Matrix4 &	viewMatrix,
		float *RESTRICT_ALIAS	passBufferPtr
	)		const

◆ getAllowMultipleBounces()

bool Ogre::VctLighting::getAllowMultipleBounces ( ) const

◆ getBakingMultiplier()

float Ogre::VctLighting::getBakingMultiplier ( ) const

inline

◆ getBindTrilinearSamplerblock()

const HlmsSamplerblock* Ogre::VctLighting::getBindTrilinearSamplerblock ( )

inline

◆ getConstBufferSize()

size_t Ogre::VctLighting::getConstBufferSize ( ) const

◆ getCurrentBakingMultiplier()

float Ogre::VctLighting::getCurrentBakingMultiplier ( ) const

inline

If you've set setBakingMultiplier but haven't yet called VctLighting::update with autoMultiplier = false, this function returns the baking multiplier that is currently in use (beware of floating point accuracy differences)

◆ getDebugVisualizationMode()

bool Ogre::VctLighting::getDebugVisualizationMode ( ) const

◆ getId()

IdType Ogre::IdObject::getId ( ) const

inlineinherited

Get the unique id of this object.

◆ getLightVoxelTextures() [1/2]

TextureGpu** Ogre::VctLighting::getLightVoxelTextures ( )

inline

◆ getLightVoxelTextures() [2/2]

TextureGpu** Ogre::VctLighting::getLightVoxelTextures ( const size_t cascadeIdx )

◆ getNumCascades()

size_t Ogre::VctLighting::getNumCascades ( ) const

inline

References Ogre::FastArray< T >::size().

◆ getNumVoxelTextures()

uint32 Ogre::VctLighting::getNumVoxelTextures ( ) const

inline

◆ getVoxelizer()

const VctVoxelizerSourceBase* Ogre::VctLighting::getVoxelizer ( ) const

inline

◆ isAnisotropic()

bool Ogre::VctLighting::isAnisotropic ( ) const

inline

◆ needsAmbientHemisphere()

bool Ogre::VctLighting::needsAmbientHemisphere ( ) const

◆ notifyTextureChanged()

virtual void Ogre::VctLighting::notifyTextureChanged	(	TextureGpu *	texture,
		TextureGpuListener::Reason	reason,
		void *	extraData
	)

virtual

Called when a TextureGpu changed in a way that affects how it is displayed:

TextureGpu::notifyDataIsReady got called (texture is ready to be displayed)
Texture changed residency status.
Texture is being deleted. It won't be a valid pointer after this call.

Implements Ogre::TextureGpuListener.

◆ operator()() [1/2]

bool Ogre::IdObject::operator()	(	const IdObject &	left,
		const IdObject &	right
	)

inlineinherited

◆ operator()() [2/2]

bool Ogre::IdObject::operator()	(	const IdObject *	left,
		const IdObject *	right
	)

inlineinherited

◆ reserveExtraCascades()

void Ogre::VctLighting::reserveExtraCascades ( size_t numExtraCascades )

Used by VctCascadedVoxelizer.

By having extra cascade info, we can calculate multiple bounces with extra info

This function calls mExtraCascades.reserve

◆ resetTexturesFromBuildRelative()

void Ogre::VctLighting::resetTexturesFromBuildRelative ( )

When VctImageVoxelizer::buildRelative is called; voxelizer's textures (albedo, normal, emissive) may be swapped for a copy.

This function notifies us that buildRelative to update some of our references

◆ setAllowMultipleBounces()

void Ogre::VctLighting::setAllowMultipleBounces ( bool bAllowMultipleBounces )

This function allows VctLighting::update to pass numBounces > 0 as argument.

Note however, that multiple bounces requires creating another RGBA32_UNORM texture of the same resolution as the voxel texture.

This can cause increase memory consumption.

Remarks: It is valid to call setAllowMultipleBounces( false ) right after calling update( sceneManager, numBounces > 0 ) in order to release the extra memory.

However remember to call setAllowMultipleBounces( true ) before calling update() again with numBounces > 0.

Parameters

bAllowMultipleBounces True to allow multiple bounces, and consume more memory. False to no longer allow multiple bounces, and release memory.

◆ setAmbient()

void Ogre::VctLighting::setAmbient	(	const ColourValue &	upperHemisphere,
		const ColourValue &	lowerHemisphere
	)

Extremely similar version of SceneManager::setAmbientLight In fact the hemisphereDir parameter is shared and set in SceneManager::setAmbientLight.

Setting upperHemisphere = lowerHemisphere can cause shader recompilations.

These values are used when cone tracing reaches the end of the probe without hitting anything, which usually means the sky must be visible.

Parameters

upperHemisphere	upperHemisphere should be set to the sky colour, which is usually set to a value much brighter than the ambient light (i.e. use the clear colour instead of the ambient colour)
lowerHemisphere	lowerHemisphere should be set to the ground colour

◆ setAnisotropic()

void Ogre::VctLighting::setAnisotropic ( bool bAnisotropic )

Toggles anisotropic mips.

Anisotropic mips provide much higher quality and generally lower light leaking. However it costs a bit more performance, and increases memory consumption.

Normally regular mipmaps of 3D textures increase memory consumption by 1/7 Anisotropic mipmaps of 3D textures increase memory consumption by 6/7

Isotropic 256x256x256 RGBA8_UNORM = 256x256x256x4 * (1+1/7) = 64 MB * 1.143 = 73.14MB Anisotrop 256x256x256 RGBA8_UNORM = 256x256x256x4 * (1+6/7) = 64 MB * 1.857 = 118.85MB

Remarks: After changing this setting, VctLighting::update must* be called again to repopulate the light data.

◆ setBakingMultiplier()

void Ogre::VctLighting::setBakingMultiplier ( float bakingMult )

Sets baking multiplier for HDR rendering.

Internally the lighting data is stored in RGBA8_UNORM_sRGB, which is not enough for HDR. More precise formats would allow for native HDR, however it's memory cost and bandwidth could be prohibtive.

Hence bakingMult is used to bring down the lighting data to usable levels without saturation (however beware areas with very low lighting conditions may round to 0).

During rendering, we use 1.0 / bakingMult to bring back the values its original range.

For LDR rendering, you probably would want to set this value to 1.0.

Remarks: This value will be ignored if VctLighting::update is not called after setting this value or if VctLighting::update gets called again but autoMultiplier = true

This function is different from VctLighting::mMultiplier. That variable controls the GI strength/brightness. This function only controls precision and accuracy.

Parameters

bakingMult Value to multiply against GI lighting during baking. Use values >= 1 when all your lights are too dim, but could saturate quickly if that's not the case

Values <= 1 make when your lights are very bright, but can cause low light to become 0 (too dark)

Changes to this value take effect after calling VctLighting::update and autoMultiplier must be set to false

◆ setDebugVisualization()

void Ogre::VctLighting::setDebugVisualization	(	bool	bShow,
		SceneManager *	sceneManager
	)

◆ shouldEnableSpecularSdfQuality()

bool Ogre::VctLighting::shouldEnableSpecularSdfQuality ( ) const

◆ shouldStayLoaded()

virtual bool Ogre::VctLighting::shouldStayLoaded ( TextureGpu * texture )

inlinevirtual

Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

Return false if it is certainly safe to unload.

Reimplemented from Ogre::TextureGpuListener.

◆ update()

void Ogre::VctLighting::update	(	SceneManager *	sceneManager,
		uint32	numBounces,
		float	thinWallCounter = `1.0f`,
		bool	autoMultiplier = `true`,
		float	rayMarchStepScale = `1.0f`,
		uint32	lightMask = `0xffffffff`
	)

Parameters

sceneManager
numBounces	Number of GI bounces. This value must be 0 if getAllowMultipleBounces() == false
thinWallCounter	Shadows are calculated by raymarching towards the light source. However sometimes the ray 'may go through' a wall due to how bilinear interpolation works.

Bilinear interpolation can produce nicer soft shaddows, but it can also cause this light leaking from behind a wall.

Increase this value (e.g. to 2.0f) to fight light leaking. This should generally (over-)darken the scene

Lower values will lighten the scene and allow more light leaking

Note that thinWallCounter can not fight all sources of light leaking, thus increasing it to ridiculous high values may not yield any benefit.

Parameters

autoMultiplier	Whether we should calculate the ideal multiplier based on lights on scene. See VctLighting::setMultiplier
rayMarchStepScale	Scale for the ray march step size. A value < 1.0f makes little sense and will trigger an assert.

Bigger values means the shadow raymarching during light injection pass is faster, but may cause glitches if too high (areas that are supposed to be shadowed won't be shadowed)

Parameters

lightMask

Member Data Documentation

◆ mMultiplier

float Ogre::VctLighting::mMultiplier

Sets the intensity/brightness of the GI.

e.g. to make the GI 2x brighter, set it to 2.0 To make the GI darker, set it to 0.5

Default value is 1.0

Valid range is (0; inf)

Remarks: PUBLIC VARIABLE. This variable can be altered directly. Changes are reflected immediately.

◆ msDistanceThresholdCustomParam

const uint16 Ogre::VctLighting::msDistanceThresholdCustomParam

static

◆ mSpecularSdfQuality

float Ogre::VctLighting::mSpecularSdfQuality

When roughness is close to 0.02, specular cone tracing becomes path tracing.

This is very slow. However we can greatly speed it up by skipping gaps of empty voxels.

We use the alpha (opacity) component of the higher mips to approximate the SDF (Signed Distance Field) and thus know how much to skip. This is theoretically wrong, but not very wrong because the mips are very close to its true SDF representation thus in it works practice.

Some of these formulas have been empirically tuned to match a good performance/quality ratio

Once the roughness is higher, this formula starts hurting quality (produces noticeable artifacts) and thus we disable it.

This formula has tweakable parameters to leverage performance vs quality

Recommended range is [0; 1] where 1 is high quality and 0 is high performance (artifacts may appear).

However you can go outside that range.

Remarks: When resolution is <= 32; we completely disable this hack as it only hurts performance (fetching the opacity is more expensive than skipping pixels)

PUBLIC VARIABLE. This variable can be altered directly. Changes are reflected immediately.

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

OgreVctLighting.h

Public Types

Public Member Functions

Public Attributes

Static Public Attributes

Member Enumeration Documentation

◆ Reason

Constructor & Destructor Documentation

◆ VctLighting()

◆ ~VctLighting()

Member Function Documentation

◆ addCascade()

◆ fillConstBufferData()

◆ getAllowMultipleBounces()

◆ getBakingMultiplier()

◆ getBindTrilinearSamplerblock()

◆ getConstBufferSize()

◆ getCurrentBakingMultiplier()

◆ getDebugVisualizationMode()

◆ getId()

◆ getLightVoxelTextures() [1/2]

◆ getLightVoxelTextures() [2/2]

◆ getNumCascades()

◆ getNumVoxelTextures()

◆ getVoxelizer()

◆ isAnisotropic()

◆ needsAmbientHemisphere()

◆ notifyTextureChanged()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ reserveExtraCascades()

◆ resetTexturesFromBuildRelative()

◆ setAllowMultipleBounces()

◆ setAmbient()

◆ setAnisotropic()

◆ setBakingMultiplier()

◆ setDebugVisualization()

◆ shouldEnableSpecularSdfQuality()

◆ shouldStayLoaded()

◆ update()

Member Data Documentation

◆ mMultiplier

◆ msDistanceThresholdCustomParam

◆ mSpecularSdfQuality