r.ForceRetileTextures

r.ForceRetileTextures

#Overview

name: r.ForceRetileTextures

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

It is referenced in 6 C++ source files.

#Summary

#Usage in the C++ source code

The purpose of r.ForceRetileTextures is to force the rebuilding of the tiling step for textures when Shared Linear Texture Encoding is enabled in project settings. This setting is primarily used in the texture processing and rendering system of Unreal Engine 5.

This setting variable is relied upon by the Engine module, specifically within the texture derived data task system. It’s used to control the behavior of texture tiling and caching.

The value of this variable is set through a console variable (CVarForceRetileTextures) with a default value of 0. It can be changed at runtime through console commands or programmatically.

The associated variable CVarForceRetileTextures directly interacts with r.ForceRetileTextures. They share the same value and purpose.

Developers must be aware that:

  1. This variable only takes effect when Shared Linear Texture Encoding is enabled in project settings.
  2. Enabling this forces the tiling build step to rebuild, which can impact performance and build times.
  3. Even when enabled, the linear texture is still allowed to fetch from cache.

Best practices when using this variable include:

  1. Use it sparingly, primarily for debugging or when you need to force a rebuild of tiled textures.
  2. Be aware of the performance implications, especially in larger projects with many textures.
  3. Remember to disable it after use to avoid unnecessary rebuilds.

Regarding the associated variable CVarForceRetileTextures:

Developers should use CVarForceRetileTextures.GetValueOnAnyThread() to check the current state of this setting in their code if they need to implement custom behavior based on whether texture retiling is forced or not.

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:51

Scope: file

Source code excerpt:


static TAutoConsoleVariable<int32> CVarForceRetileTextures(
	TEXT("r.ForceRetileTextures"),
	0,
	TEXT("If Shared Linear Texture Encoding is enabled in project settings, this will force the tiling build step to rebuild,")
	TEXT("however the linear texture is allowed to fetch from cache.")
);

#Associated Variable and Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:50

Scope: file

Source code excerpt:

);

static TAutoConsoleVariable<int32> CVarForceRetileTextures(
	TEXT("r.ForceRetileTextures"),
	0,
	TEXT("If Shared Linear Texture Encoding is enabled in project settings, this will force the tiling build step to rebuild,")
	TEXT("however the linear texture is allowed to fetch from cache.")
);

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:2037

Scope (from outer to inner):

file
function     void FTextureCacheDerivedDataWorker::DoWork

Source code excerpt:

	if (BuildSettingsPerLayerFetchOrBuild[0].Tiler && !bForVirtualTextureStreamingBuild)
	{
		if (CVarForceRetileTextures.GetValueOnAnyThread())
		{
			// We do this after the fetch so it can fill out the metadata and key suffix that gets used.
			bSucceeded = false;
			bLoadedFromDDC = false;

			DerivedData->Mips.Empty();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:2720

Scope (from outer to inner):

file
class        class FTextureBuildTask final : public FTextureAsyncCacheDerivedDataTask
function     FTextureBuildTask

Source code excerpt:


				// Must be done after the policy is copied in to the child input resolver
				if (CVarForceRetileTextures.GetValueOnAnyThread())
				{
					FetchOrBuildPolicy = EBuildPolicy::Build;
				}

				FBuildInfo FetchOrBuildInfo(FetchOrBuild_ChildBuildSession.GetValue(), FetchOrBuild_TilingDefinition, FetchOrBuildPolicy, FetchOrBuildResultMetadata);
				FetchOrBuildInfo.TilingInputResolver = FetchOrBuild_ChildInputResolver.GetPtrOrNull();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:2739

Scope (from outer to inner):

file
class        class FTextureBuildTask final : public FTextureAsyncCacheDerivedDataTask
function     FTextureBuildTask

Source code excerpt:

					FetchFirst_ChildBuildSession = Build.CreateSession(TexturePath, FetchFirst_ChildInputResolver.GetPtrOrNull());
					// Must be done after the policy is copied in to the child input resolver
					if (CVarForceRetileTextures.GetValueOnAnyThread())
					{
						FetchFirstBuildPolicy = EBuildPolicy::Build;
					}

					FBuildInfo FetchFirstInfo(FetchFirst_ChildBuildSession.GetValue(), FetchFirst_TilingDefinition, FetchFirstBuildPolicy, FetchFirstResultMetadata);
					FetchFirstInfo.TilingInputResolver = FetchFirst_ChildInputResolver.GetPtrOrNull();

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/TextureDerivedDataTask.cpp:2783

Scope (from outer to inner):

file
class        class FTextureBuildTask final : public FTextureAsyncCacheDerivedDataTask
function     FTextureBuildTask

Source code excerpt:

				FetchOrBuild_ChildInputResolver.Emplace(BuildSession.Get(), FetchOrBuild_ParentDefinition, FetchOrBuildPolicy);
				// Must be done after the policy is copied in to the child input resolver
				if (CVarForceRetileTextures.GetValueOnAnyThread())
				{
					FetchOrBuildPolicy = EBuildPolicy::Build;
				}

				FetchOrBuild_ChildBuildSession = Build.CreateSession(TexturePath, FetchOrBuild_ChildInputResolver.GetPtrOrNull());