r.FilmGrain.SequenceLength

r.FilmGrain.SequenceLength

#Overview

name: r.FilmGrain.SequenceLength

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.FilmGrain.SequenceLength is to control the length of the random sequence used for film grain effects in Unreal Engine’s rendering system. This setting is part of the post-processing pipeline, specifically the tonemapping and film grain application process.

This setting variable is primarily used in the Renderer module of Unreal Engine, particularly in the post-processing subsystem. It’s referenced in the PostProcessTonemap.cpp file, which handles tonemapping and related post-processing effects.

The value of this variable is set as a console variable (CVar) with a default value of 97. It’s defined using the TAutoConsoleVariable template, which allows it to be changed at runtime through console commands or configuration files.

The variable interacts closely with the View state and is used to calculate a random sequence index for film grain application. It’s used in conjunction with other film grain-related variables and the Halton sequence to generate pseudo-random offsets for the film grain texture.

Developers should be aware that:

  1. The value should preferably be a prime number, as mentioned in the variable’s description.
  2. Changing this value will affect the periodicity of the film grain effect.
  3. This variable is marked as ECVF_RenderThreadSafe, meaning it can be safely accessed from the render thread.

Best practices when using this variable include:

  1. Keeping the value as a prime number to ensure a good distribution of random values.
  2. Adjusting it if you notice repetitive patterns in the film grain effect over time.
  3. Being cautious about setting extremely large values, as it might impact performance.

Regarding the associated variable CVarFilmGrainSequenceLength:

This is the actual console variable object that holds the value of r.FilmGrain.SequenceLength. It’s used to retrieve the current value of the setting at runtime, specifically on the render thread (as seen in the GetValueOnRenderThread() call).

The purpose and usage of CVarFilmGrainSequenceLength align directly with r.FilmGrain.SequenceLength. It’s the programmatic interface for accessing and modifying the film grain sequence length setting.

Developers should be aware that:

  1. This variable can be accessed and modified through console commands.
  2. Changes to this variable will take effect on the next frame.

Best practices for using CVarFilmGrainSequenceLength include:

  1. Using GetValueOnRenderThread() when accessing the value from render thread code.
  2. Considering caching the value if it’s accessed frequently, to avoid potential performance overhead from repeated CVar lookups.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:57

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:


TAutoConsoleVariable<int32> CVarFilmGrainSequenceLength(
	TEXT("r.FilmGrain.SequenceLength"), 97,
	TEXT("Length of the random sequence for film grain (preferably a prime number, default=97)."),
	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarFilmGrainCacheTextureConstants(
	TEXT("r.FilmGrain.CacheTextureConstants"), 1,
	TEXT("Wether the constants related to the film grain should be cached."),

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:56

Scope (from outer to inner):

file
namespace    anonymous

Source code excerpt:

	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarFilmGrainSequenceLength(
	TEXT("r.FilmGrain.SequenceLength"), 97,
	TEXT("Length of the random sequence for film grain (preferably a prime number, default=97)."),
	ECVF_RenderThreadSafe);

TAutoConsoleVariable<int32> CVarFilmGrainCacheTextureConstants(
	TEXT("r.FilmGrain.CacheTextureConstants"), 1,

#Loc: <Workspace>/Engine/Source/Runtime/Renderer/Private/PostProcess/PostProcessTonemap.cpp:749

Scope (from outer to inner):

file
function     FScreenPassTexture AddTonemapPass

Source code excerpt:

		CommonParameters.FilmGrain.FilmGrainSampler = TStaticSamplerState<SF_Bilinear, AM_Wrap, AM_Wrap>::GetRHI();

		int32 RandomSequenceLength = CVarFilmGrainSequenceLength.GetValueOnRenderThread();
		int32 RandomSequenceIndex = (View.ViewState ? View.ViewState->FrameIndex : 0) % RandomSequenceLength;

		FVector2f RandomGrainTextureUVOffset;
		RandomGrainTextureUVOffset.X = Halton(RandomSequenceIndex + 1, 2);
		RandomGrainTextureUVOffset.Y = Halton(RandomSequenceIndex + 1, 3);