UE3 Lightmass 技术指南
文档变更记录: 由 [Daniel Wright] 创建。
- 运行本地构建的 UnrealLightmass
- 通用调试
- BaseLightmass.ini
- 高级选项
- 确定性
- 调试
- 贴图像素调试
- 其它有用的调试选项
运行本地构建的 UnrealLightmass
Lightmass 程序在目录 Development/Tools/UnrealLightmass/UnrealLightmass.sln 中。
从版本QA_APPROVED_BUILD_SEPT_2009起，在运行本地构建的 Lightmass 前您必须编译 SwarmAgent。这是作为一个安全防范来实施的。编译 SwarmAgent 可以通过打开 Development/Tools/UnrealSwarm/UnrealSwarm.sln ，然后请确认配置为 Release(发布版本)、平台为Mixed(混合的)，最后重新编译程序。
注意，有 32 位和 64 位版本的 Lightmass。当测试本地的改变时，请确定您编译的版本是实际运行的版本。在 Epic 公司中我们运行的都是 Vista 64 位，所有一般使用 64 位版本的 Lightmass，除非 BaseLightmass.ini 文件中的 bAllow64bitProcess=False。
通用调试
为了通过调试器运行 Lightmass，首先在编辑器控制台中输入 'lightmassdebug' 并启动一个光照构建。Swarm 在这时将会处于等待状态直到您手动地运行了 Lightmass。无论是在调试或者发布模式下，这里都是您在调试器中启动 Lightmass 的地方，并且您可以一步步的跟踪代码。
Lightmass 中的大多数代码是通过许多线程同时执行的，所以近放置一个断点便起作用的情况是很少的，因为您永远不知道当前正在处理哪个 贴图像素/地图。下面所描述的 Texel Debugging（贴图像素调试）可以帮助解决这个问题。
Debug Lightmass（调试模式下的 Lightmass）要比 Release（发布）模式下慢大约 4 倍，如果您必须单线程地运行（设置BaseLightmass.ini 文件中的 bAllowMultiThreadedStaticLighting=false ），那么它将会慢很多倍（在运行分布式渲染的发布版本和单线程的调试版本间有 1000 倍的速度差异）。因此，一般在梗概测试关卡（或者细分原始关卡）中再现您正在调查的 bug 直到它在切换到调试模式之前在发布模式下编译了数十秒，这是一个好主意。
BaseLightmass.ini
这里是保存用于调试的所有 Lightmass 解决方案的设置及幻方常数地方。在这个文件中的几乎所有的设置都会在您每次进行光照构建时重新载入一次，所以您不必重新启动引擎。该设置会在 Lightmass 解决方案的 SceneExport.h 的代码注释中进行说明。
高级选项
在文件 BaseLightmass.ini 中设置 bAllowAdvancedOptions=True 可以在构建光照对话框中获得一个按钮来编辑光照的调试选项。这些大多数都在 Lightmass 外部，可以控制导入/导出选项，间距等等。领会到这些功能的最好的方法是查看代码。
确定性
通过细心地开发，Lightmass 已经是一个非常确定的系统。这意味着无论使用多少个线程、光照的编译是如何进行分布式处理的或者什么机器在执行编译，它将总是能够给出一个精确地相同的结果。其中有一个例外是不同机器之间的浮点精确度的差异，但是差异通常非常的小。Determinism（确定性）是非常重要的，因为这意味着我们总是能够再现在本地运行、或调试、或以单线程运行 (bAllowMultiThreadedStaticLighting=False) 时进行大量的分布式编译期间所发生的 bug。
有一个不会改变 Lightmass 的任何计算的附加设置，即在 BaseLightmass.ini 中的最终贴图像素颜色： ViewSingleBounceNumber 。在 BaseLightmass.ini 文件中的其它的所有的设置几乎都一定会该改变 Lightmass 的内部计算并可能会中断您再现 bug 的过程。
调试
贴图像素调试
为了使用贴图像素调试，您需要：
- 启用在 UE3 和 Lightmass 中定义的
ALLOW_LIGHTMAP_SAMPLE_DEBUGGING。 - 在文件 BaseLightmass.ini 中，禁用
bAllowLightmapCompression 和 bUseBilinearFilterLightmaps。这将会导致光照贴图被存储为 ARGB8 而不是需要选择颜色的 DXT1。禁用双线性过滤将会是您更容易地查看贴图像素的颜色。 - 再次构建光照（最好在预览级别下）。
现在您准备好了使用贴图像素调试。注意贴图像素调试仅在 BSP 或静态网格物体的贴图光照贴图上有效。它在静态网格物体的顶点光照贴图上部分地有效，在其它组合物上无效。 一旦您已经选择了一个贴图像素，请注意不要改变任何影响光照贴图分辨率或打包的东西。
为了选择一个贴图像素，在编辑器中按下 T 键并左击一个光照贴图的贴图像素。它应该会变为红色来暗示您所选中的贴图像素。注意按键 T 也可以切换地形，所以请确保在您尝试进行此操作之前已经隐藏了所有的地形 actor。
贴图像素选择最好的应用是或者在 Lightmass 中从头到尾逐步执行那个贴图像素的所有光照，或者渲染调试线来在编辑器中展现不同的东西。为了逐步跟踪选中的贴图像素的光照，在 'lightmassdebug' 模式的调试器中运行 Lightmass，并在 Lightmass 找到您想调查的代码的区域。在 Lightmass 中迭代所有贴图像素的几乎任何地方，您会找到像以下显示的片段代码。您必须在 bDebugThisTexel = TRUE; 处放置一个断点来开始调试选中的贴图像素。
UBOOL bDebugThisTexel = FALSE;
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisMapping
&& LowResY == Scene.DebugInput.LocalY
&& LowResX == Scene.DebugInput.LocalX)
{
bDebugThisTexel = TRUE;
}
#endif
这里是在选中一个贴图像素情况下进行光照构建后应该显示的样子：
红色的方块是被选中的贴图像素。四个青绿色的点是点阵化过程中所决定的那个贴图像素的四个角。在中心的青蓝色的圆点是真正的进行光照的点，从那个圆点出来的线是光照的法线，并且它周围的球体显示了由 Lightmass 决定的贴图像素的大小。这些可视化的帮助对于验证 Lightmass 是否使用了正确的光照位置及法线是有用。在选中的贴图像素周围的黄色的线显示了在同一个映射中选中的贴图像素附近的所有其它贴图像素中心的位置及法线。长的绿线显示了缓存在选中贴图像素中的最近的发光光子，从贴图像素到光子的绿线显示用于阻止漏光的可见性检测。
调试时出现的线对 BaseLightmass.ini 中的设置是敏感的，如果您处在某个视图模式中，可能会显示很多线。
ViewSingleBounceNumber-1= 仅显示上面列出的线，它不会针对任何反射光线。ViewSingleBounceNumber=0导致 Lightmass 仅显示在光照贴图中的直接光照。它现在将为选中的贴图像素的直接阴影所完成的光线追踪来描画线。绿色的光线意味着光源是可见的，红色的意味着光线是带阴影的。ViewSingleBounceNumber=1使 Lightmass 仅显示在光照贴图中第一次反射的间接光照。它现在将为发光缓冲入口描画绿色的点，同时伴随着一个文本标签显示了TLightingCache::FRecord::Id的值，这个值在逐步通过在TLightingCache::InterpolateLighting()中发光缓存的插值时是有用的。每一个发光缓存入口周围也有一个球体和一个显示法线的长线。如果发光缓存入口确实是用于对选中的贴图像素的间接光照进行插值，它将会被描画为绿色，否者将会被描画为灰色。
如果您确实选择了一个创建了发光缓存入口的贴图像素，您会获得一些更多不同类型的线来帮助您调试实际的 Final Gathering with Photon Mapping。首先，在选中的贴图像素周围的红色的线显示了所发现的并用于引导 Final Gather 的第一次反射的光子。从在屏幕截图中的黄色的选中的贴图像素发出的光线是用于粗略地跟踪第一次反射光子的入射方向的 Final Gather 光线。如果它们没有获得正光将显示为灰色。在每个最终收集的碰撞点附近有绿色的线，它们是最终收集光线所发现的缓存发光量子。
其它有用的调试选项
- 选中一个贴图像素，除了设置
ViewSingleBounceNumber=0, bUsePhotonsForDirectLighting=True, bVisualizePhotonPaths=True, bUseIrradiancePhotons=False外，其它都为默认设置。这将仅显示直接光子。
- 选中贴图像素，除了设置
bUseIrradiancePhotons=True外，其它设置和上面一样。这将仅显示直接发光光子。
- 选中贴图像素，除了
bUsePhotonsForDirectLighting=True, bVisualizePhotonPaths=True, bUseIrradiancePhotons=False外，所有其它的设置都为默认值。这将显示所有光子，包括直接光子和间接光子。白色的显示间接光子的路径，这些路径是由 Lightmass 决定的，它们将导致光照反射。红色的线是到处反射的间接光子。
这个图片显示了在一个角落周围进行反射的间接光子。
- 除了
bUsePhotonsForDirectLighting=True外，所有的其它值都为默认设置并且没有选中贴图像素。这将显示在表面缓存的发光量子。这是 Final Gather 光线看到的世界上的光照的展现，除了间接光照仍然使用 Final Gathering 进行计算。设置bUseFinalGathering=False也可以显示间接光子。
- 除了设置
ShowMaterialAttribute=Diffuse外，其它设置都为默认值。当 Lightmass 看到材质的漫反射项时，将会显示它们，材质的漫反射项可以用于交互漫反射。您也可以查看 Emissive（自发光）, Transmission（传输）和 Specular（高光）。
- 除了设置
bVisualizeMeshAreaLightPrimitives=True外，其它所有的项都为默认设置并选中一个贴图像素。这将会显示简化的网格物体区域光照图元的几何体。网格物体区域光源作为许多独立的长方形自发光贴图像素发出，并且通过简化来降低多边形数量来实现优化。
- 除了
bVisualizeVolumeLightSamples=True外，其它所有项都为默认值，并选中一个贴图像素。这个方式描画了用于插值间接光照到光照环境中作为带颜色的点的体积光照样本。
文档变更记录: 由 [Daniel Wright] 创建。
- 运行本地构建的 UnrealLightmass
- 通用调试
- BaseLightmass.ini
- 高级选项
- 确定性
- 调试
- 贴图像素调试
- 其它有用的调试选项
运行本地构建的 UnrealLightmass
Lightmass 程序在目录 Development/Tools/UnrealLightmass/UnrealLightmass.sln 中。
从版本QA_APPROVED_BUILD_SEPT_2009起，在运行本地构建的 Lightmass 前您必须编译 SwarmAgent。这是作为一个安全防范来实施的。编译 SwarmAgent 可以通过打开 Development/Tools/UnrealSwarm/UnrealSwarm.sln ，然后请确认配置为 Release(发布版本)、平台为Mixed(混合的)，最后重新编译程序。
注意，有 32 位和 64 位版本的 Lightmass。当测试本地的改变时，请确定您编译的版本是实际运行的版本。在 Epic 公司中我们运行的都是 Vista 64 位，所有一般使用 64 位版本的 Lightmass，除非 BaseLightmass.ini 文件中的 bAllow64bitProcess=False。
通用调试
为了通过调试器运行 Lightmass，首先在编辑器控制台中输入 'lightmassdebug' 并启动一个光照构建。Swarm 在这时将会处于等待状态直到您手动地运行了 Lightmass。无论是在调试或者发布模式下，这里都是您在调试器中启动 Lightmass 的地方，并且您可以一步步的跟踪代码。
Lightmass 中的大多数代码是通过许多线程同时执行的，所以近放置一个断点便起作用的情况是很少的，因为您永远不知道当前正在处理哪个 贴图像素/地图。下面所描述的 Texel Debugging（贴图像素调试）可以帮助解决这个问题。
Debug Lightmass（调试模式下的 Lightmass）要比 Release（发布）模式下慢大约 4 倍，如果您必须单线程地运行（设置BaseLightmass.ini 文件中的 bAllowMultiThreadedStaticLighting=false ），那么它将会慢很多倍（在运行分布式渲染的发布版本和单线程的调试版本间有 1000 倍的速度差异）。因此，一般在梗概测试关卡（或者细分原始关卡）中再现您正在调查的 bug 直到它在切换到调试模式之前在发布模式下编译了数十秒，这是一个好主意。
BaseLightmass.ini
这里是保存用于调试的所有 Lightmass 解决方案的设置及幻方常数地方。在这个文件中的几乎所有的设置都会在您每次进行光照构建时重新载入一次，所以您不必重新启动引擎。该设置会在 Lightmass 解决方案的 SceneExport.h 的代码注释中进行说明。
高级选项
在文件 BaseLightmass.ini 中设置 bAllowAdvancedOptions=True 可以在构建光照对话框中获得一个按钮来编辑光照的调试选项。这些大多数都在 Lightmass 外部，可以控制导入/导出选项，间距等等。领会到这些功能的最好的方法是查看代码。
确定性
通过细心地开发，Lightmass 已经是一个非常确定的系统。这意味着无论使用多少个线程、光照的编译是如何进行分布式处理的或者什么机器在执行编译，它将总是能够给出一个精确地相同的结果。其中有一个例外是不同机器之间的浮点精确度的差异，但是差异通常非常的小。Determinism（确定性）是非常重要的，因为这意味着我们总是能够再现在本地运行、或调试、或以单线程运行 (bAllowMultiThreadedStaticLighting=False) 时进行大量的分布式编译期间所发生的 bug。
有一个不会改变 Lightmass 的任何计算的附加设置，即在 BaseLightmass.ini 中的最终贴图像素颜色： ViewSingleBounceNumber 。在 BaseLightmass.ini 文件中的其它的所有的设置几乎都一定会该改变 Lightmass 的内部计算并可能会中断您再现 bug 的过程。
调试
贴图像素调试
为了使用贴图像素调试，您需要：
- 启用在 UE3 和 Lightmass 中定义的
ALLOW_LIGHTMAP_SAMPLE_DEBUGGING。 - 在文件 BaseLightmass.ini 中，禁用
bAllowLightmapCompression 和 bUseBilinearFilterLightmaps。这将会导致光照贴图被存储为 ARGB8 而不是需要选择颜色的 DXT1。禁用双线性过滤将会是您更容易地查看贴图像素的颜色。 - 再次构建光照（最好在预览级别下）。
现在您准备好了使用贴图像素调试。注意贴图像素调试仅在 BSP 或静态网格物体的贴图光照贴图上有效。它在静态网格物体的顶点光照贴图上部分地有效，在其它组合物上无效。 一旦您已经选择了一个贴图像素，请注意不要改变任何影响光照贴图分辨率或打包的东西。
为了选择一个贴图像素，在编辑器中按下 T 键并左击一个光照贴图的贴图像素。它应该会变为红色来暗示您所选中的贴图像素。注意按键 T 也可以切换地形，所以请确保在您尝试进行此操作之前已经隐藏了所有的地形 actor。
贴图像素选择最好的应用是或者在 Lightmass 中从头到尾逐步执行那个贴图像素的所有光照，或者渲染调试线来在编辑器中展现不同的东西。为了逐步跟踪选中的贴图像素的光照，在 'lightmassdebug' 模式的调试器中运行 Lightmass，并在 Lightmass 找到您想调查的代码的区域。在 Lightmass 中迭代所有贴图像素的几乎任何地方，您会找到像以下显示的片段代码。您必须在 bDebugThisTexel = TRUE; 处放置一个断点来开始调试选中的贴图像素。
UBOOL bDebugThisTexel = FALSE;
#if ALLOW_LIGHTMAP_SAMPLE_DEBUGGING
if (bDebugThisMapping
&& LowResY == Scene.DebugInput.LocalY
&& LowResX == Scene.DebugInput.LocalX)
{
bDebugThisTexel = TRUE;
}
#endif
这里是在选中一个贴图像素情况下进行光照构建后应该显示的样子：
红色的方块是被选中的贴图像素。四个青绿色的点是点阵化过程中所决定的那个贴图像素的四个角。在中心的青蓝色的圆点是真正的进行光照的点，从那个圆点出来的线是光照的法线，并且它周围的球体显示了由 Lightmass 决定的贴图像素的大小。这些可视化的帮助对于验证 Lightmass 是否使用了正确的光照位置及法线是有用。在选中的贴图像素周围的黄色的线显示了在同一个映射中选中的贴图像素附近的所有其它贴图像素中心的位置及法线。长的绿线显示了缓存在选中贴图像素中的最近的发光光子，从贴图像素到光子的绿线显示用于阻止漏光的可见性检测。
调试时出现的线对 BaseLightmass.ini 中的设置是敏感的，如果您处在某个视图模式中，可能会显示很多线。
ViewSingleBounceNumber-1= 仅显示上面列出的线，它不会针对任何反射光线。ViewSingleBounceNumber=0导致 Lightmass 仅显示在光照贴图中的直接光照。它现在将为选中的贴图像素的直接阴影所完成的光线追踪来描画线。绿色的光线意味着光源是可见的，红色的意味着光线是带阴影的。ViewSingleBounceNumber=1使 Lightmass 仅显示在光照贴图中第一次反射的间接光照。它现在将为发光缓冲入口描画绿色的点，同时伴随着一个文本标签显示了TLightingCache::FRecord::Id的值，这个值在逐步通过在TLightingCache::InterpolateLighting()中发光缓存的插值时是有用的。每一个发光缓存入口周围也有一个球体和一个显示法线的长线。如果发光缓存入口确实是用于对选中的贴图像素的间接光照进行插值，它将会被描画为绿色，否者将会被描画为灰色。
如果您确实选择了一个创建了发光缓存入口的贴图像素，您会获得一些更多不同类型的线来帮助您调试实际的 Final Gathering with Photon Mapping。首先，在选中的贴图像素周围的红色的线显示了所发现的并用于引导 Final Gather 的第一次反射的光子。从在屏幕截图中的黄色的选中的贴图像素发出的光线是用于粗略地跟踪第一次反射光子的入射方向的 Final Gather 光线。如果它们没有获得正光将显示为灰色。在每个最终收集的碰撞点附近有绿色的线，它们是最终收集光线所发现的缓存发光量子。
其它有用的调试选项
- 选中一个贴图像素，除了设置
ViewSingleBounceNumber=0, bUsePhotonsForDirectLighting=True, bVisualizePhotonPaths=True, bUseIrradiancePhotons=False外，其它都为默认设置。这将仅显示直接光子。
- 选中贴图像素，除了设置
bUseIrradiancePhotons=True外，其它设置和上面一样。这将仅显示直接发光光子。
- 选中贴图像素，除了
bUsePhotonsForDirectLighting=True, bVisualizePhotonPaths=True, bUseIrradiancePhotons=False外，所有其它的设置都为默认值。这将显示所有光子，包括直接光子和间接光子。白色的显示间接光子的路径，这些路径是由 Lightmass 决定的，它们将导致光照反射。红色的线是到处反射的间接光子。
这个图片显示了在一个角落周围进行反射的间接光子。
- 除了
bUsePhotonsForDirectLighting=True外，所有的其它值都为默认设置并且没有选中贴图像素。这将显示在表面缓存的发光量子。这是 Final Gather 光线看到的世界上的光照的展现，除了间接光照仍然使用 Final Gathering 进行计算。设置bUseFinalGathering=False也可以显示间接光子。
- 除了设置
ShowMaterialAttribute=Diffuse外，其它设置都为默认值。当 Lightmass 看到材质的漫反射项时，将会显示它们，材质的漫反射项可以用于交互漫反射。您也可以查看 Emissive（自发光）, Transmission（传输）和 Specular（高光）。
- 除了设置
bVisualizeMeshAreaLightPrimitives=True外，其它所有的项都为默认设置并选中一个贴图像素。这将会显示简化的网格物体区域光照图元的几何体。网格物体区域光源作为许多独立的长方形自发光贴图像素发出，并且通过简化来降低多边形数量来实现优化。
- 除了
bVisualizeVolumeLightSamples=True外，其它所有项都为默认值，并选中一个贴图像素。这个方式描画了用于插值间接光照到光照环境中作为带颜色的点的体积光照样本。