r.DefaultFeature.LightUnits

r.DefaultFeature.LightUnits

#Overview

name: r.DefaultFeature.LightUnits

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.DefaultFeature.LightUnits is to set the default units for point, spot, and rect lights in Unreal Engine 5. It determines how light intensity is measured and interpreted within the engine’s rendering system.

This setting variable is primarily used by the rendering system, specifically for lighting components. It is utilized by various Unreal Engine subsystems and modules, including:

  1. The Engine module (SceneView.cpp)
  2. The DetailCustomizations module (LightComponentDetails.cpp)
  3. The UnrealEd module (ActorFactoryPointLight.cpp, ActorFactoryRectLight.cpp, ActorFactorySpotLight.cpp)

The value of this variable is set as a console variable (CVar) in the engine’s initialization process. It can be modified through the console or configuration files.

This variable interacts with the IntensityUnits property of light components (UPointLightComponent, URectLightComponent, USpotLightComponent). When new light actors are spawned or when light units are reset to default, the value of r.DefaultFeature.LightUnits is used to determine the appropriate intensity units.

Developers must be aware that changing this variable will affect the default behavior of newly created light actors and can impact the visual appearance of the scene. It’s important to understand the implications of each unit type:

0: Unitless 1: Candelas (default) 2: Lumens

Best practices when using this variable include:

  1. Consistently using the same light units across a project to maintain visual coherence.
  2. Documenting any changes to the default value in project settings or team guidelines.
  3. Being cautious when changing this value in existing projects, as it may require adjusting the intensity values of existing lights to maintain their appearance.
  4. Consider the scale and requirements of your scene when choosing between candelas and lumens, as they are better suited for different scenarios (e.g., candelas for smaller, more precise lighting, lumens for larger area lighting).

#References in C++ code

#Callsites

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

#Loc: <Workspace>/Engine/Source/Runtime/Engine/Private/SceneView.cpp:223

Scope: file

Source code excerpt:

// see ELightUnits
static TAutoConsoleVariable<int32> CVarDefaultPointLightUnits(
	TEXT("r.DefaultFeature.LightUnits"),
	1,
	TEXT("Default units to use for point, spot and rect lights\n")
	TEXT(" 0: unitless \n")
	TEXT(" 1: candelas (default)\n")
	TEXT(" 2: lumens"));

#Loc: <Workspace>/Engine/Source/Editor/DetailCustomizations/Private/LightComponentDetails.cpp:333

Scope (from outer to inner):

file
function     void FLightComponentDetails::ResetIntensityUnitsToDefault

Source code excerpt:

	if (Component && Component->GetArchetype() && !Component->GetArchetype()->IsInBlueprint())
	{
		static const auto CVarDefaultLightUnits = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DefaultFeature.LightUnits"));
		const ELightUnits DefaultUnits = (ELightUnits)CVarDefaultLightUnits->GetValueOnGameThread();

		if (DefaultUnits != Component->IntensityUnits)
		{
			SetComponentIntensityUnits(Component, DefaultUnits);
		}

#Loc: <Workspace>/Engine/Source/Editor/DetailCustomizations/Private/LightComponentDetails.cpp:353

Scope (from outer to inner):

file
function     bool FLightComponentDetails::IsIntensityUnitsResetToDefaultVisible

Source code excerpt:

	if (Component && Component->GetArchetype() && !Component->GetArchetype()->IsInBlueprint())
	{
		static const auto CVarDefaultLightUnits = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DefaultFeature.LightUnits"));
		const ELightUnits DefaultUnits = (ELightUnits)CVarDefaultLightUnits->GetValueOnGameThread();
		return DefaultUnits != Component->IntensityUnits;
	}
	else
	{
		// Fall back to default handler

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Factories/ActorFactoryPointLight.cpp:18

Scope (from outer to inner):

file
function     void UActorFactoryPointLight::PostSpawnActor

Source code excerpt:

		if (Component && Component->CreationMethod == EComponentCreationMethod::Native)
		{
			static const auto CVarDefaultLightUnits = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DefaultFeature.LightUnits"));
			ELightUnits DefaultUnits = (ELightUnits)CVarDefaultLightUnits->GetValueOnAnyThread();

			Component->Intensity *= UPointLightComponent::GetUnitsConversionFactor(Component->IntensityUnits, DefaultUnits, -1.f);
			Component->IntensityUnits = DefaultUnits;
		}
	}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Factories/ActorFactoryRectLight.cpp:17

Scope (from outer to inner):

file
function     void UActorFactoryRectLight::PostSpawnActor

Source code excerpt:

		if (Component && Component->CreationMethod == EComponentCreationMethod::Native)
		{
			static const auto CVarDefaultLightUnits = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DefaultFeature.LightUnits"));
			ELightUnits DefaultUnits = (ELightUnits)CVarDefaultLightUnits->GetValueOnAnyThread();

			// Passing .5 as CosHalfConeAngle  since URectLightComponent::SetLightBrightness() lumens conversion use only PI
			Component->Intensity *= URectLightComponent::GetUnitsConversionFactor(Component->IntensityUnits, DefaultUnits, .5f);
			Component->IntensityUnits = DefaultUnits;
		}

#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Factories/ActorFactorySpotLight.cpp:18

Scope (from outer to inner):

file
function     void UActorFactorySpotLight::PostSpawnActor

Source code excerpt:

		if (Component && Component->CreationMethod == EComponentCreationMethod::Native)
		{
			static const auto CVarDefaultLightUnits = IConsoleManager::Get().FindTConsoleVariableDataInt(TEXT("r.DefaultFeature.LightUnits"));
			ELightUnits DefaultUnits = (ELightUnits)CVarDefaultLightUnits->GetValueOnAnyThread();

			Component->Intensity *= UPointLightComponent::GetUnitsConversionFactor(Component->IntensityUnits, DefaultUnits, Component->GetCosHalfConeAngle());
			Component->IntensityUnits = DefaultUnits;
		}
	}