VisibilityTangentOffsetSampleRadiusScale
VisibilityTangentOffsetSampleRadiusScale
#Overview
name: VisibilityTangentOffsetSampleRadiusScale
The value of this variable can be defined or overridden in .ini config files. 1
.ini config file referencing this setting variable.
It is referenced in 7
C++ source files.
#Summary
#Usage in the C++ source code
The purpose of VisibilityTangentOffsetSampleRadiusScale is to adjust the offset of visibility ray samples in the tangent plane of a surface. This setting is used in the static lighting and global illumination system of Unreal Engine, particularly for lightmass calculations.
This variable is primarily used in the Lightmass subsystem, which is responsible for precalculating static lighting in Unreal Engine. It’s referenced in the UnrealLightmass program and the Lightmass exporter in the UnrealEd module.
The value of this variable is set in the Lightmass configuration file (GLightmassIni). It’s read from the “DevOptions.StaticLightingSceneConstants” section of the config file.
VisibilityTangentOffsetSampleRadiusScale interacts with other variables related to visibility sampling, such as VisibilityNormalOffsetSampleRadiusScale and VisibilityRayOffsetDistance. It’s often used in calculations alongside SampleRadius and various tangent vectors.
Developers should be aware that this variable affects the precision and quality of shadow calculations, particularly for large texels with high variance in incoming radiance. Adjusting this value can impact the appearance of shadows and indirect lighting in the scene.
Best practices when using this variable include:
- Only modify it if you understand its impact on lighting calculations.
- Test any changes thoroughly, as it can affect the overall lighting quality of your scene.
- Consider the relationship between this variable and other visibility-related settings.
- Be cautious when increasing this value, as it may lead to increased computation time.
#Setting Variables
#References In INI files
Location: <Workspace>/Engine/Config/BaseLightmass.ini:44, section: [DevOptions.StaticLightingSceneConstants]
- INI Section:
DevOptions.StaticLightingSceneConstants
- Raw value:
.8
- Is Array:
False
#References in C++ code
#Callsites
This variable is referenced in the following C++ source code:
#Loc: <Workspace>/Engine/Source/Editor/UnrealEd/Private/Lightmass/Lightmass.cpp:2184
Scope (from outer to inner):
file
function void FLightmassExporter::WriteSceneSettings
Source code excerpt:
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("VisibilityNormalOffsetDistance"), Scene.SceneConstants.VisibilityNormalOffsetDistance, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("VisibilityNormalOffsetSampleRadiusScale"), Scene.SceneConstants.VisibilityNormalOffsetSampleRadiusScale, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("VisibilityTangentOffsetSampleRadiusScale"), Scene.SceneConstants.VisibilityTangentOffsetSampleRadiusScale, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetFloat(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("SmallestTexelRadius"), Scene.SceneConstants.SmallestTexelRadius, GLightmassIni));
VERIFYLIGHTMASSINI(GConfig->GetInt(TEXT("DevOptions.StaticLightingSceneConstants"), TEXT("LightGridSize"), Scene.SceneConstants.LightGridSize, GLightmassIni));
}
{
VERIFYLIGHTMASSINI(GConfig->GetBool(TEXT("DevOptions.StaticLightingMaterial"), TEXT("bUseDebugMaterial"), bConfigBool, GLightmassIni));
Scene.MaterialSettings.bUseDebugMaterial = bConfigBool;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:326
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::IntersectLightRays
Source code excerpt:
// Offset the sample's starting point in the tangent XY plane based on the sample's area of influence.
// This is particularly effective for large texels with high variance in the incoming radiance over the area of the texel.
SampleOffset = Vertex.WorldTangentX * TangentPathDirection.X * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale
+ Vertex.WorldTangentY * TangentPathDirection.Y * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;
// Experiment to distribute the starting position over the area of the texel to anti-alias, causes incorrect shadowing at intersections though
//@todo - use consistent sample set between irradiance cache samples
//const FVector2f DiskPosition = GetUniformUnitDiskPosition(RandomStream);
//SampleOffset = Vertex.WorldTangentX * DiskPosition.X * SampleRadius * .5f + Vertex.WorldTangentY * DiskPosition.Y * SampleRadius * .5f;
}
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:337
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::IntersectLightRays
Source code excerpt:
const float RayStartNormalBiasScale = RayBiasMode == RBM_ConstantNormalOffset
? SceneConstants.VisibilityNormalOffsetSampleRadiusScale
: (SceneConstants.VisibilityTangentOffsetSampleRadiusScale * TangentPathDirection.Z);
// Apply various offsets to the start of the ray.
// The offset along the ray direction is to avoid incorrect self-intersection due to floating point precision.
// The offset along the normal is to push self-intersection patterns (like triangle shape) on highly curved surfaces onto the backfaces.
FVector3f RayStart = Vertex.WorldPosition
+ WorldPathDirection * SceneConstants.VisibilityRayOffsetDistance
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/FinalGather.cpp:1639
Scope: file
Source code excerpt:
// Vector from the center to one of the corners of the texel
// The FMath::Sqrt(.5f) is to normalize (Vertex.TriangleTangentX + Vertex.TriangleTangentY), which are orthogonal unit vectors.
const FVector4f CornerOffset = FMath::Sqrt(.5f) * (Vertex.TriangleTangentX + Vertex.TriangleTangentY) * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;
const FLightRay TexelRay(
TexelCenterOffset + CornerOffset,
TexelCenterOffset - CornerOffset,
NULL,
NULL
);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/LightingSystem.cpp:2479
Scope (from outer to inner):
file
namespace Lightmass
function FVector2f FStaticLightingSystem::CalculatePointAreaShadowing
Source code excerpt:
//@todo - the rays cross over on the way to the light and mess up penumbra shapes.
//@todo - need to use more than texel size, otherwise BSP generates lots of texels that become half shadowed at corners
SampleOffset = Vertex.WorldTangentX * LightPositionSamples(RayIndex).DiskPosition.X * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale
+ Vertex.WorldTangentY * LightPositionSamples(RayIndex).DiskPosition.Y * SampleRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;
*/
}
float DistSqr = LightVector.SizeSquared3() + KINDA_SMALL_NUMBER;
float SamplePDF = CurrentSample.PDF * -Dot3( CurrentSample.Normal, LightVector ) / ( DistSqr * FMath::Sqrt( DistSqr ) );
if( SamplePDF <= 0.0f )
{
continue;
}
FVector4f NormalForOffset = Vertex.WorldTangentZ;
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Private/Lighting/TextureMapping.cpp:1052
Scope (from outer to inner):
file
namespace Lightmass
function void FStaticLightingSystem::TraceToTexelCorner
Source code excerpt:
// Vector from the center to one of the corners of the texel
// The FMath::Sqrt(.5f) is to normalize (Vertex.TriangleTangentX + Vertex.TriangleTangentY), which are orthogonal unit vectors.
const FVector4f CornerOffset = FMath::Sqrt(.5f) * (CornerSigns.X * FullVertex.TriangleTangentX + CornerSigns.Y * FullVertex.TriangleTangentY) * TexelRadius * SceneConstants.VisibilityTangentOffsetSampleRadiusScale;
const FLightRay TexelRay(
TexelCenterOffset,
TexelCenterOffset + CornerOffset,
NULL,
NULL
);
#Loc: <Workspace>/Engine/Source/Programs/UnrealLightmass/Public/SceneExport.h:163
Scope (from outer to inner):
file
namespace Lightmass
class class FStaticLightingSceneConstants
Source code excerpt:
* This is only used when bAccountForTexelSize is true.
*/
float VisibilityTangentOffsetSampleRadiusScale;
/**
* Smallest texel radius allowed, useful for clamping edge cases where some texels have a radius of 0.
* This should be smaller than the smallest valid texel radius in the scene.
*/
float SmallestTexelRadius;