r.GaussianBloom.Cross

r.GaussianBloom.Cross

#Overview

name: r.GaussianBloom.Cross

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.GaussianBloom.Cross is to provide an experimental feature for modifying the bloom kernel in the post-processing pipeline of Unreal Engine’s rendering system. It allows developers to adjust the brightness of the center sample in the bloom effect, creating various visual styles such as a cross-shaped bloom or an anisomorphic lens flare look.

This setting variable is primarily used in the Renderer module of Unreal Engine, specifically in the post-processing subsystem responsible for bloom effects. The code referencing this variable is located in the PostProcessBloomSetup.cpp file, which is part of the rendering pipeline.

The value of this variable is set through a console variable (CVarBloomCross) using the TAutoConsoleVariable class. This allows for runtime modification of the bloom effect without recompiling the engine.

The associated variable CVarBloomCross interacts directly with r.GaussianBloom.Cross, as they share the same value. This console variable is used to retrieve the current value of the setting in the rendering code.

Developers must be aware of the following when using this variable:

  1. The valid range for a cross-shaped bloom is between 1 and 3, as mentioned in the comments.
  2. Negative values create an anisomorphic lens flare look (X-axis only).
  3. A value of 0 turns off the effect (default setting).
  4. Using this feature may affect the overall brightness of the bloom effect, as existing bloom is lowered to match the same brightness.

Best practices when using this variable include:

  1. Experiment with values between 1 and 3 for the cross-shaped bloom effect to avoid aliasing.
  2. Use negative values cautiously, as they create an anisomorphic lens flare look that may not be suitable for all scenes.
  3. Consider the performance impact of enabling this feature, especially on lower-end hardware.
  4. Test the visual results thoroughly across different scenes and lighting conditions to ensure consistency.

Regarding the associated variable CVarBloomCross:

The purpose of CVarBloomCross is to provide a runtime-modifiable console variable that controls the r.GaussianBloom.Cross setting. It allows for easy adjustment of the bloom effect during development and debugging.

This variable is used in the same Renderer module and post-processing subsystem as r.GaussianBloom.Cross. It’s defined and used in the PostProcessBloomSetup.cpp file.

The value of CVarBloomCross is set when the console variable is created, with a default value of 0.0f. It can be modified at runtime through console commands.

CVarBloomCross interacts directly with the r.GaussianBloom.Cross setting, as they share the same value. It’s used to retrieve the current setting value in the rendering code using the GetValueOnRenderThread() method.

Developers should be aware that changes to CVarBloomCross will immediately affect the bloom rendering, so it should be used carefully in production environments.

Best practices for using CVarBloomCross include:

  1. Use it for rapid iteration and testing of bloom effects during development.
  2. Consider exposing it as a user-adjustable setting for advanced graphics options in the final product.
  3. Document the effects of different values for other team members and end-users if exposed.
  4. Ensure that the default value (0.0f) is appropriate for the majority of use cases 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/PostProcess/PostProcessBloomSetup.cpp:16

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<float> CVarBloomCross(
	TEXT("r.GaussianBloom.Cross"),
	0.0f,
	TEXT("Experimental feature to give bloom kernel a more bright center sample (values between 1 and 3 work without causing aliasing)\n")
	TEXT("Existing bloom get lowered to match the same brightness\n")
	TEXT("<0 for a anisomorphic lens flare look (X only)\n")
	TEXT(" 0 off (default)\n")
	TEXT(">0 for a cross look (X and Y)"),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessBloomSetup.cpp:15

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

const int32 GBloomSetupComputeTileSizeY = 8;

TAutoConsoleVariable<float> CVarBloomCross(
	TEXT("r.GaussianBloom.Cross"),
	0.0f,
	TEXT("Experimental feature to give bloom kernel a more bright center sample (values between 1 and 3 work without causing aliasing)\n")
	TEXT("Existing bloom get lowered to match the same brightness\n")
	TEXT("<0 for a anisomorphic lens flare look (X only)\n")
	TEXT(" 0 off (default)\n")

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessBloomSetup.cpp:212

Scope (from outer to inner):

file
function     FScreenPassTexture AddGaussianBloomPasses

Source code excerpt:

		RDG_EVENT_SCOPE(GraphBuilder, "Bloom");

		const float CrossBloom = CVarBloomCross.GetValueOnRenderThread();

		const FVector2D CrossCenterWeight(FMath::Max(CrossBloom, 0.0f), FMath::Abs(CrossBloom));

		check(BloomQuality != EBloomQuality::Disabled);
		const uint32 BloomQualityIndex = static_cast<uint32>(BloomQuality);
		const uint32 BloomQualityCountMax = static_cast<uint32>(EBloomQuality::MAX);