r.Water.WaterMesh.OcclusionCulling.MaxQueries

r.Water.WaterMesh.OcclusionCulling.MaxQueries

#Overview

name: r.Water.WaterMesh.OcclusionCulling.MaxQueries

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.Water.WaterMesh.OcclusionCulling.MaxQueries is to control the maximum number of occlusion queries for CPU water quadtree nodes in the water rendering system of Unreal Engine 5.

This setting variable is primarily used in the Water plugin, specifically in the water rendering subsystem. It’s part of the occlusion culling mechanism for water meshes, which helps optimize rendering performance by determining which parts of the water surface are visible and need to be rendered.

The value of this variable is set through a console variable (CVar) system, which allows it to be adjusted at runtime. It’s defined with a default value of 256, but can be changed through console commands or configuration files.

This variable interacts closely with another variable, CVarWaterMeshOcclusionCullingIncludeFarMesh, which determines whether occlusion queries should always be performed for the water far mesh, regardless of the MaxQueries setting.

Developers should be aware that using fewer queries than the number of nodes in the water quadtree will result in coarser culling. This means that while it might improve performance, it could potentially lead to less accurate visibility determination for water surfaces.

Best practices when using this variable include:

  1. Adjusting it based on the complexity of your water surfaces and performance requirements.
  2. Testing different values to find the optimal balance between performance and visual accuracy.
  3. Considering the relationship with other water rendering settings, particularly those related to the far mesh and quadtree structure.

The associated variable, CVarWaterMeshOcclusionCullingMaxQueries, is effectively the same as r.Water.WaterMesh.OcclusionCulling.MaxQueries. It’s the C++ implementation of the console variable. This variable is used directly in the code to retrieve the current value of the setting, particularly in the FWaterMeshSceneProxy constructor.

When working with CVarWaterMeshOcclusionCullingMaxQueries, developers should:

  1. Use GetValueOnGameThread() to safely retrieve its current value.
  2. Be aware that changes to this value can affect the performance and visual quality of water rendering.
  3. Consider how it interacts with other water rendering parameters, such as the far mesh inclusion setting.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:75

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarWaterMeshOcclusionCullingMaxQueries(
	TEXT("r.Water.WaterMesh.OcclusionCulling.MaxQueries"), 256,
	TEXT("Maximum number of occlusion queries for the CPU water quadtree nodes. Using fewer queries than nodes will result in coarser culling."),
	ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarWaterMeshOcclusionCullingIncludeFarMesh(
	TEXT("r.Water.WaterMesh.OcclusionCulling.IncludeFarMesh"), 1,
	TEXT("When occlusion culling is enabled, always do occlusion queries for the water far mesh, independent of r.Water.WaterMesh.OcclusionCulling.MaxQueries."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:74

Scope: file

Source code excerpt:

	ECVF_RenderThreadSafe);

static TAutoConsoleVariable<int32> CVarWaterMeshOcclusionCullingMaxQueries(
	TEXT("r.Water.WaterMesh.OcclusionCulling.MaxQueries"), 256,
	TEXT("Maximum number of occlusion queries for the CPU water quadtree nodes. Using fewer queries than nodes will result in coarser culling."),
	ECVF_Scalability);

static TAutoConsoleVariable<int32> CVarWaterMeshOcclusionCullingIncludeFarMesh(
	TEXT("r.Water.WaterMesh.OcclusionCulling.IncludeFarMesh"), 1,

#Loc: <Workspace>/Engine/Plugins/Experimental/Water/Source/Runtime/Private/WaterMeshSceneProxy.cpp:264

Scope (from outer to inner):

file
function     FWaterMeshSceneProxy::FWaterMeshSceneProxy

Source code excerpt:


	// Always do CPU occlusion queries, even if this is a GPU quadtree. The GPU quadtree still potentially uses the far mesh which is CPU driven.
	const int32 MaxQueries = CVarWaterMeshOcclusionCullingMaxQueries.GetValueOnGameThread();
	const bool bIncludeFarMeshOcclusionQueries = CVarWaterMeshOcclusionCullingIncludeFarMesh.GetValueOnGameThread() != 0;
	OcclusionCullingBounds = WaterQuadTree.ComputeNodeBounds(MaxQueries, CVarWaterMeshOcclusionCullExpandBoundsAmountXY.GetValueOnGameThread(), bIncludeFarMeshOcclusionQueries, &OcclusionResultsFarMeshOffset);
	EmptyOcclusionCullingBounds.Add(WaterQuadTree.GetBoundsIncludingFarMesh());
	// If this is a GPU quadtree, the CPU root node will have an invalid bounding box, so derive conservative bounds now
	if (bIsGPUQuadTree && !OcclusionCullingBounds.IsEmpty())
	{