r.HeterogeneousVolumes.SparseVoxel.Refinement

r.HeterogeneousVolumes.SparseVoxel.Refinement

#Overview

name: r.HeterogeneousVolumes.SparseVoxel.Refinement

This variable is created as a Console Variable (cvar).

It is referenced in 3 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.HeterogeneousVolumes.SparseVoxel.Refinement is to control the hierarchical refinement process for coalescing neighboring sparse voxels in heterogeneous volume rendering. This setting is primarily used in the rendering system, specifically for handling heterogeneous volumes.

This setting variable is relied upon by the Renderer module of Unreal Engine, particularly within the HeterogeneousVolumes subsystem. It’s defined and used in the HeterogeneousVolumes.cpp file, which is part of the Renderer’s private implementation.

The value of this variable is set as a console variable with a default value of 1. It can be modified at runtime through the console or configuration files.

The associated variable CVarHeterogeneousVolumesSparseVoxelRefinement directly interacts with this setting. It’s used to retrieve the current value of the setting in the engine’s code.

Developers must be aware that this variable affects the performance and quality of heterogeneous volume rendering. Enabling refinement (value != 0) may improve visual quality but could potentially impact performance, especially in scenes with complex volumetric effects.

Best practices when using this variable include:

  1. Testing different values to find the optimal balance between visual quality and performance for your specific use case.
  2. Considering disabling refinement (setting to 0) if performance is a critical concern and the visual difference is negligible.
  3. Being cautious when modifying this value at runtime, as it may cause sudden changes in rendering quality or performance.

Regarding the associated variable CVarHeterogeneousVolumesSparseVoxelRefinement:

This is an internal representation of the r.HeterogeneousVolumes.SparseVoxel.Refinement setting. It’s implemented as a TAutoConsoleVariable, which allows for easy integration with Unreal Engine’s console variable system.

The purpose of this variable is to provide a programmatic way to access and modify the refinement setting within the engine’s C++ code. It’s used in the ShouldRefineSparseVoxels() function to determine whether sparse voxel refinement should be applied.

This variable is set up in the Renderer module and is primarily used within the HeterogeneousVolumes namespace. Its value can be safely retrieved on the render thread using the GetValueOnRenderThread() method.

Developers should be aware that changes to this variable will directly affect the behavior of the heterogeneous volume rendering system. It’s important to ensure that any code modifying or reading this variable does so in a thread-safe manner, respecting the ECVF_RenderThreadSafe flag it’s created with.

Best practices for using CVarHeterogeneousVolumesSparseVoxelRefinement include:

  1. Always access its value using GetValueOnRenderThread() when in render thread code.
  2. Avoid frequently changing its value, as this could lead to inconsistent rendering or performance issues.
  3. Consider exposing this setting through appropriate user interfaces if it’s something that needs to be adjusted frequently in your game or application.

#References in C++ code

#Callsites

This variable is referenced in the following C++ source code:

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:169

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesSparseVoxelRefinement(
	TEXT("r.HeterogeneousVolumes.SparseVoxel.Refinement"),
	1,
	TEXT("Uses hierarchical refinement to coalesce neighboring sparse-voxels (Default = 1)"),
	ECVF_RenderThreadSafe
);

static TAutoConsoleVariable<float> CVarHeterogeneousVolumesStepSize(

#Associated Variable and Callsites

This variable is associated with another variable named CVarHeterogeneousVolumesSparseVoxelRefinement. They share the same value. See the following C++ source code.

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:168

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarHeterogeneousVolumesSparseVoxelRefinement(
	TEXT("r.HeterogeneousVolumes.SparseVoxel.Refinement"),
	1,
	TEXT("Uses hierarchical refinement to coalesce neighboring sparse-voxels (Default = 1)"),
	ECVF_RenderThreadSafe
);

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/HeterogeneousVolumes/HeterogeneousVolumes.cpp:440

Scope (from outer to inner):

file
namespace    HeterogeneousVolumes
function     bool ShouldRefineSparseVoxels

Source code excerpt:

	bool ShouldRefineSparseVoxels()
	{
		return CVarHeterogeneousVolumesSparseVoxelRefinement.GetValueOnRenderThread() != 0;
	}

	bool UseSparseVoxelPerTileCulling()
	{
		return CVarHeterogeneousVolumesSparseVoxelPerTileCulling.GetValueOnRenderThread() != 0;
	}