陰影接收開發指南

LCC Unity SDK 支持 Mesh 物體動態投射陰影到 3DGS 表面，實現更好的光影效果。下面介紹實現動態陰影的完整步驟。

步驟 1：創建場景與遊戲對象

在 Unity 中創建一個全新的場景，Unity 默認會創建 Main Camera 和 Directional Light。

設置 Main Camera

在 Hierarchy 窗口中選擇 Main Camera，在 Inspector 窗口中按下圖設置其屬性。

設置 Main Camera 的屬性

創建 LCCManager

在 Hierarchy 窗口空白處單擊鼠標右鍵，在彈出的菜單中選擇 Create Empty，創建一個空遊戲對象，命名為 LCCManager，將其 Transform 歸一，並通過 Add Component 為其添加 LCCManager 腳本。

創建 LCCManager 遊戲對象並添加 LCCManager 腳本

創建 LCCRenderer

在 Hierarchy 窗口空白處單擊鼠標右鍵，選擇 Create Empty，創建一個空遊戲對象，命名為 LCCRenderer，將其 Transform 設置為 Rotation.x = -90、Scale.x = -1。

創建 LCCRenderer 並設置 Transform（Rotation.x = -90、Scale.x = -1）

注意：

LCCRenderer 遊戲對象的 Transform 設置（Rotation.x = -90、Scale.x = -1）是與 LCC 數據座標系的對齊。關於座標系對齊的詳細說明，參見 Unity SDK 簡介 中的「LCC 數據座標系」。

開啟 Directional Light 陰影

在 Hierarchy 窗口中選擇 Directional Light 遊戲對象，在 Inspector 窗口中確保已開啟陰影功能。

確保 Directional Light 已開啟陰影功能

步驟 2：添加 Render Feature

1. 在 Unity 菜單欄中選擇 File → Project Settings，在左側選擇 Graphics，確認當前使用的 Default Render Pipeline Asset。本示例為 URP（Universal Render Pipeline Asset）。

在 Graphics 設置中確認 Default Render Pipeline Asset

2. 點擊該 Asset，在 Project 窗口中定位到對應的資源文件，找到與之關聯的 Renderer（本示例為 URP_Renderer.asset）。

3. 選中該 Renderer 資源文件，在 Inspector 窗口中點擊 Add Renderer Feature，添加 Splat Shadow Mask Feature。

在 URP Renderer 中添加 Splat Shadow Mask Feature

步驟 3：編寫腳本開啟陰影接收

新建一個 C# 腳本，命名為 LCCShadow.cs，代碼如下：

using LCCCore;
using UnityEngine;

public class LCCShadow : MonoBehaviour
{
    public LCCManager m_manager;
    public string m_FilePath;
    private LCCCore.Renderer m_renderer;

    void Start()
    {
        m_manager.SetPlatformType(PlatformType.PC);
        m_manager.SwitchRenderPass(ActiveRenderMode.SingleRender);

        Debug.Log("Started ");
        m_renderer = m_manager.GetRender(this.transform);
        m_renderer.Load(m_FilePath, onProgress, onComplete);
    }

    private void onProgress(float _progress)
    {
        Debug.Log($"[LCCRenderer] file load progress: {_progress:P1}");
    }

    private void onComplete()
    {
        Debug.Log($"[LCCRenderer] file  loaded");
        m_manager.SetShadowReceive(true);
        //m_manager.SetShadowColor(new Color(0, 0, 0, 1.0f));
        //m_manager.SetShadowStrength(0.5f);
    }
}

注意：

陰影接收功能需要在 LCC 場景加載完成後開啟，因此 SetShadowReceive(true) 在 onComplete 回調中調用。

步驟 4：掛載腳本並設置數據路徑

1. 將 LCCShadow.cs 腳本掛載到 Hierarchy 窗口中的 LCCRenderer 遊戲對象上。
2. 在 Inspector 窗口中，將 LCCManager 遊戲對象拖動到腳本的 Manager 屬性上。
3. 在腳本的 File Path 屬性中填寫 LCC 文件的路徑地址。

步驟 5：創建投射陰影的 Mesh 物體

1. 在場景中創建一個 Cube 對象，並確保其 Cast Shadows = On。
2. 調整 Cube 到合適的位置，以便觀察它投射到 3DGS 表面上的陰影。

步驟 6：運行

在 Game 窗口中點擊 Play 按鈕，實時改變 Cube 的位置，即可觀察它投射的動態陰影。

運行後 Cube 向 3DGS 表面投射動態陰影

常見問題：關閉兼容模式

如果 Unity Console 窗口報錯且沒有出現陰影，請關閉兼容模式：通過 Edit → Project Settings → Graphics 打開設置面板，選擇 URP 選項卡，不要勾選 Render Graph → Compatibility Mode (Render Graph Disabled) 後的多選框。

不要勾選 Render Graph 兼容模式（Render Graph Disabled）

關鍵步驟

Mesh 物體對象向 3DGS 表面投射陰影的關鍵步驟：

1. 確保場景中有 Directional Light 光源，並已開啟陰影功能。
2. 確保場景中有投射陰影的 Mesh 物體對象，並已開啟陰影投射（Cast Shadows = On）。
3. 確保在 URP Renderer 中添加了 Splat Shadow Mask Feature 渲染特性。
4. 確保在 LCC 場景加載完成後通過代碼開啟陰影接收功能（SetShadowReceive(true)）。

陰影相關 API

LCC Unity SDK 通過 LCCManager 提供了以下三個陰影相關 API。它們都需要在 LCC 場景加載完成後調用（即在 onComplete 回調中），且 SetShadowColor()、SetShadowStrength() 需要先開啟 SetShadowReceive(true) 才會生效。

SetShadowReceive

// 返回值：void
public void SetShadowReceive(bool enable)

開關點雲陰影接收功能。開啟後，場景中 Mesh 物體的陰影可以投射到 3DGS 點雲表面上。

調用示例：

m_manager.SetShadowReceive(true);

說明：

• 默認關閉。
• 需要場景中有投射陰影的 Mesh 物體和 Directional Light 光源。
• 開啟後會啟用 _SPLAT_SHADOW_ON shader keyword。

SetShadowColor

// 返回值：void
public void SetShadowColor(Color color)

設置陰影區域的顏色。

調用示例：

m_manager.SetShadowColor(new Color(0.3f, 0.3f, 0.3f, 1f));

說明：

• 默認值為 (0.3, 0.3, 0.3, 1)。
• 需先開啟 SetShadowReceive(true)。

SetShadowStrength

// 返回值：void
public void SetShadowStrength(float strength)

設置陰影強度。0 為無陰影，1 為最強陰影。

調用示例：

m_manager.SetShadowStrength(0.8f);

說明：

• 默認值為 1.0。
• 取值範圍 [0, 1]，超出範圍會自動鉗制。
• 需先開啟 SetShadowReceive(true)。