OpenUSD 灯光入门深入解析 usdLux DiskLight 圆盘灯 Schema 与实战【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD导读DiskLight圆盘灯是 OpenUSD 中 usdLux 核心库提供的一种内建intrinsic光源类型它从位于 XY 平面中心的一个圆形盘片沿 -Z 轴单向发光用于模拟摄影软箱soft box、线性灯、荧光灯与灯板等现实照明设备。本文以 OpenUSD 仓库中 DiskLight.md 文档为骨架结合 schema.usda 的 Schema 定义、diskLight.h 的 C API 以及 testUsdLuxLight.py 的测试用例完整讲解 DiskLight 的属性体系、USD 场景编写方法、继承自 LightAPI 的灯光参数以及 extent 包围盒计算的底层实现读完即可在 USD 场景中正确配置并使用 DiskLight。一、DiskLight 是什么核心定义与适用场景根据 Schema 文档的定义DiskLight 是一种内建光源intrinsic lightLight emitted from one side of a circular disk. The disk is centered in the XY plane and emits light along the -Z axis.即发光面是一个位于XY 平面中心的圆盘光线只从圆盘的一侧沿-Z 轴方向向外发射。这与 RectLight矩形灯类似但发光区域为圆形因此非常适合模拟摄影用的柔光箱soft boxes——圆形柔光箱在真实摄影中非常常见线性灯 / 荧光灯管linear lights, fluorescent lights——通过长条状的圆盘排列或组合实现灯板light panels——大面积均匀发光的影视/摄影灯板。由于它是「有边界、可求范围」的光源DiskLight 在 usdLux 的类型体系中归属于可包围盒光源BoundableLightBase这一点会在后文源码部分详细展开。二、快速上手完整的 USD 场景示例原文档给出了一个可直接使用的完整 USD 场景场景中放置了一个radius 0.8、intensity 20的 DiskLight并配有 Sphere 与 Cube 作为被照明物体。完整代码如下#usda 1.0 ( upAxis Y ) def Scope Lights { def DiskLight Light1 { float inputs:radius 0.8 color3f inputs:color (1, 1, 1) float inputs:intensity 20.0 double3 xformOp:translate (4, 0, 1) uniform token[] xformOpOrder [xformOp:translate] } } def Xform TestGeom { def Sphere Sphere1 { token purpose render color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double3 xformOp:translate (0, 0, -2) uniform token[] xformOpOrder [xformOp:translate] } def Cube Cube { token purpose render color3f[] primvars:displayColor [(1, 1, 1)] ( interpolation constant ) double size 8 double3 xformOp:translate (0, 0, -8) uniform token[] xformOpOrder [xformOp:translate] } }逐行拆解这个示例的关键点元素说明def DiskLight Light1在LightsScope 下定义一个 DiskLight 类型的 primprim 类型名与 Schema 类型名完全一致float inputs:radius 0.8设置圆盘发光面半径。注意原文档特意省略了该属性的默认值行注释因为 0.8 是显式覆盖了 Schema 默认值 0.5见下文属性详解color3f inputs:color (1, 1, 1)发光颜色此处为纯白继承自 LightAPIfloat inputs:intensity 20.0光强缩放系数继承自 LightAPI此处覆盖默认值 1.0 以增强照明效果double3 xformOp:translate (4, 0, 1)将灯放置在 (4, 0, 1)灯默认发光方向为自身局部坐标的 -Z 轴uniform token[] xformOpOrder声明变换操作顺序USD 的标准变换约定def Sphere/def Cube被照明几何体均设置purpose renderSphere 置于 (0,0,-2) 正对灯光 -Z 发射方向Cube 置于 (0,0,-8)整个场景的upAxis Y表示 Y 轴向上。灯光位于 X4 处斜向照射几何体Sphere 与 Cube 依次排列在灯光的 -Z 发射方向上从而在渲染中形成由近及远的受光层次。三、DiskLight 专属属性详解DiskLight 自身在 Schema 层面只声明了一个专属属性另一个是继承自 LightAPI 的light:shaderId重写。3.1 inputs:radiusUSD 类型float默认值Fallback value0.5含义圆盘发光面的半径。半径越大灯光整体的覆盖范围reach越大但单位面积上的发光强度分布也随之变化。从 schema.usda 可以看到该属性的完整声明float inputs:radius 0.5 ( displayGroup Geometry displayName Radius doc Radius of the disk. customData { token apiName radius } )值得注意的是displayGroup Geometry与displayName Radius这两个元数据用于在 DCC 工具如 Maya、Katana、Houdini 的 USD 插件的 UI 中归类与显示该属性——它属于「几何/形状」分组而非「基础」分组。这与 LightAPI 中的intensity、color等被标记为displayGroup Basic的属性形成对比。半径与渲染效果的关系半径不仅决定发光面的物理大小还直接影响阴影的软硬程度——在其他条件不变时更大的发光面意味着更柔和的阴影边缘类似摄影中更大的柔光箱因为从盘面上不同点发出的光线以不同的角度到达被照物体表面。该属性在 C 层的访问 API 为GetRadiusAttr()/CreateRadiusAttr()详见 diskLight.h。3.2 light:shaderIdUSD 类型token默认值DiskLight含义DiskLight 对应的着色器标识符shader ID。在 schema.usda 中其声明为uniform token light:shaderId DiskLight ( customData { bool apiSchemaOverride true } )两个关键细节该属性带uniform修饰符表示在整个场景中它是一个均匀uniform值不会被时间采样或分块求值。apiSchemaOverride true表明这是对 LightAPI 中同名属性LightAPI 中light:shaderId默认值为空字符串的子类覆盖——DiskLight 将自己的默认 shaderId 固定为类型名DiskLight。原文档特别指出USD 会同时注册一个标识符为DiskLight、源类型source type为USD的 Sdr shader 节点用来对应灯光的各 inputs。这意味着 DiskLight 的inputs:*属性会被 SdrShader Definition Registry着色器定义注册表识别为着色器输入渲染器可以通过 Sdr 机制查询到该光源的定义从而在渲染器侧完成材质/光源的映射。四、继承自 LightAPI 的灯光参数Intensity / Color / Exposure 等DiskLight 通过继承链DiskLight → BoundableLightBase → Boundable并prepend apiSchemas [LightAPI]见 schema.usda获得了完整的灯光通用属性。从源码结构看所有内建光源RectLight、SphereLight、DistantLight、PortalLight 等共享这套 LightAPI 参数体系掌握它们即可通用于所有 usdLux 灯光。以下参数均定义于 LightAPIschema.usdaDiskLight 可直接使用属性USD 类型默认值含义inputs:intensityfloat1线性缩放灯光亮度。规范上intensity1、exposure0的白光在 RGB 渲染器中于传感器平面正入射时产生 [1,1,1] 像素值即亮度 1 nitcd/m²intensity2则为 2 nitinputs:exposurefloat0以 2 的幂次指数缩放亮度类似 F-stop 曝光控制L L · 2^exposure与 intensity 相乘生效inputs:colorcolor3f(1, 1, 1)发光颜色在渲染色彩空间中定义L_color L_scalar · colorinputs:diffusefloat1.0灯光对材质漫反射响应的倍率非物理控制用于精细调光inputs:specularfloat1.0灯光对材质高光响应的倍率非物理控制inputs:normalizebool0是否将光强按发光面积归一化使不同尺寸盘片的单位亮度一致displayGroup Refineinputs:enableColorTemperatureboolfalse是否启用色温控制inputs:colorTemperaturefloat6500色温开尔文有效范围 1000~10000默认 6500 对应 D65 白点值越低越暖、越高越冷仅当enableColorTemperature为 true 时生效light:shaderIdtoken灯光的着色器 IDDiskLight 覆盖为DiskLightinputs:materialSyncModetoken见源码材质同步模式允许值包括materialGlowTintsLight、independent、noMaterialResponse4.1 亮度单位的规范性说明在 schema.usda 的 LightAPI 文档中对亮度单位有明确的规范性定义当前绝大多数消费 OpenUSD 的渲染器是 RGB 渲染器而非光谱渲染器RGB 渲染器中传输的每个通道R/G/B代表「光谱曝光分布 × 传感器响应函数」的卷积如 CIE Illuminant D65 × CIE 1931。因此默认灯光的发射intensity1, color[1,1,1]被定义为发光色度与渲染色彩空间白点一致的 Illuminant D 光谱分布其亮度恰为1 nit (cd/m²)。这也是为什么示例中 DiskLight 需要intensity 20才能获得明显照明——默认 1 nit 是「直接被看到」的基准亮度。4.2 灯光链接LinkingLightAPI 还预置了collection:lightLink:includeRoot 1与collection:shadowLink:includeRoot 1两个属性schema.usda对应GetLightLinkCollection()与GetShadowLinkCollection()两个集合接口。Linking 用于控制一盏灯照亮哪些几何体、以及哪些几何体对该灯投射阴影。默认includeRoot为 true即灯光默认照亮全部物体若只想照亮特定集合可显式排除其余物体或将 includeRoot 设为 false 后显式包含目标物体。五、继承属性Boundable / Xformable / Imageable原文档在「Inherited Properties」小节列出了 DiskLight 从三个基类继承的属性完整清单如下5.1 继承自 BoundableextentUSD 类型float3[]含义包围盒范围extent用于空间加速与剔除。DiskLight 的 Schema 声明了implementsComputeExtent 1见 schema.usda表示其拥有可计算 extent 的实现。关于 extent 的数值测试用例 testUsdLuxLight.py 验证了它的计算规则——当使用默认半径 0.5 时extent 为[(-0.5, -0.5, 0.0), (0.5, 0.5, 0.0)]当通过diskLight.CreateRadiusAttr(5.0)将半径改为 5.0 后extent 变为[(-5.0, -5.0, 0.0), (5.0, 5.0, 0.0)]。可见DiskLight 的 extent 与半径严格成正比且在 Z 轴上厚度为零发光面为 XY 平面内的薄盘。这一点与 RectLight 完全一致同测试中 RectLight 的 extent 由宽高决定Z 轴同样为 0而与 SphereLight、CylinderLight 的 Z 轴有厚度的 extent 不同。5.2 继承自 XformablexformOpOrderUSD 类型token[]含义Xform 变换操作顺序。与所有可变换 prim 相同DiskLight 的朝向与位置由xformOp:*系列操作及其顺序决定。特别注意发光方向是局部坐标 -Z因此要通过旋转如xformOp:rotateXYZ调整灯光照射方向。5.3 继承自 Imageable属性USD 类型默认值含义proxyPrimrel关系—代理 prim 关系用于在交互视口中以轻量几何替代渲染几何purposetokendefaultprim 的用途default/render/proxy/guide决定其在各阶段的可见性。在 usdview 中purpose render的物体只参与渲染而不参与视口选择等交互visibilitytokeninherited可见性可取inherited/invisibleinvisible时该灯不参与照明计算六、源码级原理Schema 定义与 C API6.1 Schema 声明schema.usdaDiskLight 的完整 Schema 声明位于 schema.usdaclass DiskLight DiskLight ( customData { dictionary extraPlugInfo { bool implementsComputeExtent 1 } } inherits /BoundableLightBase doc Light emitted from one side of a circular disk. The disk is centered in the XY plane and emits light along the -Z axis. ) { uniform token light:shaderId DiskLight ( customData { bool apiSchemaOverride true } ) float inputs:radius 0.5 ( displayGroup Geometry displayName Radius doc Radius of the disk. customData { token apiName radius } ) }要点inherits /BoundableLightBase直接继承可包围盒灯光基类因此具备 extent 计算能力implementsComputeExtent 1提示系统该类型有自定义的 extent 计算实现而非使用通用遍历全篇唯一的新增属性只有inputs:radius其余能力全部来自继承链。6.2 C 类型体系diskLight.h在 C 侧DiskLight 对应UsdLuxDiskLight类定义于 diskLight.hclass UsdLuxDiskLight : public UsdLuxBoundableLightBase关键信息schemaKind UsdSchemaKind::ConcreteTypeddiskLight.h这是一个具体类型化concrete typedSchema可以直接用def DiskLight在 USD 文件中实例化提供工厂方法UsdLuxDiskLight::Get(stage, path)与UsdLuxDiskLight::Define(stage, path)diskLight.hGet用于获取已存在的符合该 Schema 的 primDefine用于在指定路径上创建/确保存在符合该 Schema 的 prim属性访问 APIGetRadiusAttr()获取 radius 属性句柄CreateRadiusAttr(defaultValue, writeSparsely)创建并可选地稀疏写入默认值diskLight.h。6.3 Python 绑定Python 侧通过 wrapDiskLight.cpp 导出UsdLux.DiskLight模块典型用法即测试用例所示import UsdLux diskLight UsdLux.DiskLight.Define(stage, /DiskLight) diskLight.CreateRadiusAttr(5.0)七、测试验证extent 与包围盒计算testUsdLuxLight.py 是 usdLux 灯光体系的综合测试其中与 DiskLight 直接相关的验证包括类型可定义性第 352 行UsdLux.DiskLight.Define(stage, /DiskLight)返回有效的 Schema 对象验证 DiskLight 是注册在 usdLux 插件中的可实例化灯光类型extent 与包围盒计算第 364、375-376 行默认半径 0.5 → extent[(-0.5, -0.5, 0.0), (0.5, 0.5, 0.0)]CreateRadiusAttr(5.0)→ extent[(-5.0, -5.0, 0.0), (5.0, 5.0, 0.0)]验证函数_VerifyExtentAndBBox同时检查ComputeLocalBound(time, default)返回的Gf.BBox3d是否与 extent 一致尺寸属性注册表第 441 行DiskLight : [radius]表明 radius 是 DiskLight 唯一影响包围盒的尺寸属性灯光类型枚举第 452-464 行DiskLight出现在所有 BoundableLightBase/NonboundableLightBase 派生类型列表中由插件注册表Plug.Registry().GetPluginWithName(usdLux).DeclaresType验证。这些测试从侧面印证了第 5.1 节的结论DiskLight 的 extent 完全由 radius 决定且为 XY 平面内的薄盘Z 轴厚度为 0这对渲染器的包围盒剔除与交互选择具有重要意义。八、渲染集成与扩展从 Sdr 到各渲染器DiskLight 作为内建光源其渲染路径的核心是light:shaderIdSdr 注册USD 会为 DiskLight 注册源类型source type为USD、标识符为DiskLight的 Sdr shader 节点其输入对应灯光的inputs:*属性含继承自 LightAPI 的全部参数。渲染器可通过 Sdr 查询该节点定义从而在渲染时实例化对应的光源 shaderRenderMan 输出原文档展示的lux_disk_light.png即为该 USD layer 在 RenderMan 中的渲染结果Sphere 与 Cube 被 DiskLight 照亮的效果usdview 验证可直接用usdview打开包含 DiskLight 的 USD 文件通过交互视口调整 radius、intensity 等参数并实时观察照明变化插件扩展DiskLight 与 RectLight、SphereLight、CylinderLight、DistantLight、DomeLight、PortalLight 等共同构成 usdLux 的内建灯光家族见 testUsdLuxLight.py 的完整类型清单各渲染器插件如 third_party/renderman会针对这些 shaderId 提供对应的转换与实现。如需自定义灯光行为可参考PluginLight与 LightDefParser 的解析机制。九、实践要点小结默认发光方向DiskLight 在自身局部坐标中沿-Z 轴单向发光布置场景时需通过xformOp旋转/平移将盘面对准被照物体半径即覆盖范围inputs:radius默认 0.5增大半径扩大照明范围并柔化阴影同时 extent 随之线性增大亮度控制优先使用intensity线性与exposure2 的幂次组合调光示例中intensity 20属于较强的补光设置实际取值需结合渲染器与场景尺度调整颜色与色温color直接与亮度相乘需要物理色温时可启用enableColorTemperature并设置colorTemperature1000~10000K薄盘包围盒DiskLight 的 extent 在 Z 轴为 0交互拾取与剔除行为与 RectLight 一致与 SphereLight 等有厚度的光源不同继承体系DiskLight 的全部通用属性来自LightAPI掌握 LightAPI 参数即可一通百通地使用 usdLux 内建灯光。通过本文的文档解读与源码对照读者可以在 OpenUSD 项目中准确地以手写 USD 或程序化 APIC/Python方式创建、配置 DiskLight并理解其渲染集成与包围盒计算的底层机制。【免费下载链接】OpenUSDUniversal Scene Description项目地址: https://gitcode.com/GitHub_Trending/ope/OpenUSD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考