投影貼花開發指南

using LCCCore;
using UnityEngine;

/// <summary>
/// Decal 貼花投影 —— 開發者最小使用示例。
///
/// 本腳本模擬"接入方腳本",只調用 LCCManager 的 public API,不觸碰 SDK 內部。
/// 覆蓋全部 7 個貼花 API:
///   基礎投影(5)  SetDecalEnabled / SetDecalTexture / SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade
///   遮擋剔除(2)  SetDecalOcclusion / SetDecalOcclusionSettings
///
/// 使用步驟:
///   1) 新建空 GameObject,掛上本腳本;
///   2) Inspector 裡把場景中的 LCCManager 拖到 m_manager;
///   3) m_filePath 填一個有效 LCC 場景路徑;
///   4) m_decalTexture 拖入要投影的圖片(建議在導入設置裡勾 Read/Write);
///   5) m_projector 拖入一個空物體當投影儀(留空則用本物體),它的 +Z 朝向即投影方向;
///   6) Play。場景加載完成後貼花自動開啟,拖動投影儀即可實時看到貼花打在點雲上。
///
/// 平台說明:貼花與遮擋剔除僅在 PC/Mac(URP)生效,移動端/VR 調用會被 SDK 忽略並打印 LogWarning。
/// </summary>
public class Decal : MonoBehaviour
{
    [Header("必填")]
    [Tooltip("場景中的 LCCManager 實例")]
    public LCCManager m_manager;
    [Tooltip("有效的 LCC 場景路徑")]
    public string m_filePath;
    [Tooltip("要投影的貼花圖片。RGB=顏色, A=貼花自身遮罩")]
    public Texture2D m_decalTexture;

    [Header("投影儀 (沿 +Z 方向投影)")]
    [Tooltip("投影儀位姿。留空則用本物體 transform")]
    public Transform m_projector;
    [Range(1f, 179f)] public float m_fov = 60f;
    [Tooltip("投影寬高比; <=0 時按貼花圖片寬高比自動計算")]
    public float m_aspect = 0f;
    public float m_near = 0.1f;
    public float m_far = 100f;

    [Header("貼花外觀")]
    [Range(0f, 1f)] public float m_opacity = 1.0f;
    [Range(0f, 0.5f)][Tooltip("邊緣羽化寬度(UV 比例)。0 = 硬邊")]
    public float m_edgeFade = 0.1f;
    [Tooltip("每幀刷新投影,便於運行時拖動投影儀 / 改參數看效果")]
    public bool m_updateEveryFrame = true;

    [Header("遮擋剔除 (僅 PC/Mac)")]
    [Tooltip("開啟後被前方遮擋的背面/被擋點雲不再被貼花染色(幻燈機效果),關閉則 X 光穿透")]
    public bool m_occlusion = false;
    [Range(0f, 1f)][Tooltip("opacity 閾值: 僅 opacity ≥ 此值的 splat 參與深度圖,濾浮點/霧狀點。0=全部參與")]
    public float m_occlusionCutoff = 0f;
    [Range(0f, 0.5f)][Tooltip("相對深度容差。過小→近面自遮擋; 過大→漏擋穿透。默認 0.05")]
    public float m_occlusionBias = 0.05f;
    [Range(0, 16)][Tooltip("方形足跡半徑上限(px),去穿透漏染主旋鈕。0=單紋素,默認 2")]
    public int m_occlusionFootprint = 2;
    [Tooltip("深度圖分辨率(px, 2 的冪 256~4096)。調低補掠射面空洞,默認 1024")]
    public int m_occlusionResolution = 1024;

    // ── 運行時狀態 ──
    private bool m_loaded;
    private bool m_lastOcclusion;
    private float m_lastCutoff = float.NaN;
    private float m_lastBias = float.NaN;
    private int m_lastFootprint = -1;
    private int m_lastResolution = -1;

    void Start()
    {
        if (m_manager == null || string.IsNullOrEmpty(m_filePath))
        {
            Debug.LogError("[DecalDemo] m_manager 或 m_filePath 未賦值。");
            enabled = false;
            return;
        }

        // 1) 初始化渲染管線為 PC 單場景編輯模式
        m_manager.SetPlatformType(PlatformType.PC);
        m_manager.SwitchRenderPass(ActiveRenderMode.SingleRender);
        m_manager.SetEditorMode(true);

        // 2) 加載點雲場景,完成後再開啟貼花(貼花是全局狀態,場景就緒後設置最穩妥)
        var renderer = m_manager.GetRender(this.transform);
        Debug.Log($"[DecalDemo] 開始加載: {m_filePath}");
        renderer.Load(m_filePath,
            _ => { /* 進度回調,示例不使用 */ },
            OnSceneLoaded);
    }

    private void OnSceneLoaded()
    {
        Debug.Log("[DecalDemo] 加載完成,開啟貼花投影。");

        // ── 基礎投影:5 個 API ──
        m_manager.SetDecalTexture(m_decalTexture);   // 貼花內容
        m_manager.SetDecalOpacity(m_opacity);        // 整體不透明度
        m_manager.SetDecalEdgeFade(m_edgeFade);      // 邊緣羽化
        ApplyProjection();                           // 投影儀位姿(內部 SetDecalProjection)
        m_manager.SetDecalEnabled(true);             // 開啟貼花 (_DECAL keyword)

        // ── 遮擋剔除:2 個 API ── 必須在 ApplyProjection 之後(深度圖需有效投影儀 VP)
        m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
        m_manager.SetDecalOcclusion(m_occlusion);
        CacheOcclusionState();

        m_loaded = true;
    }

    /// <summary>
    /// 僅演示使用，實際項目中，為提高性能，不需要在 Update() 方法中每幀調用
    /// SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade 等，僅在參數變化時調用相應 API 即可。
    /// </summary>
    void Update()
    {
        if (!m_loaded) return;

        // 遮擋開關運行時切換
        if (m_occlusion != m_lastOcclusion)
        {
            m_manager.SetDecalOcclusion(m_occlusion);
            m_lastOcclusion = m_occlusion;
        }

        // 遮擋質量參數任一變化 → 一次性下發結構體
        if (!Mathf.Approximately(m_occlusionCutoff, m_lastCutoff) ||
            !Mathf.Approximately(m_occlusionBias, m_lastBias) ||
            m_occlusionFootprint != m_lastFootprint ||
            m_occlusionResolution != m_lastResolution)
        {
            m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
            CacheOcclusionState();
        }

        // 每幀刷新投影儀 / 外觀,方便實時調試
        if (!m_updateEveryFrame) return;
        m_manager.SetDecalOpacity(m_opacity);
        m_manager.SetDecalEdgeFade(m_edgeFade);
        ApplyProjection();
    }

    /// <summary>用當前投影儀位姿與透視參數構建投影矩陣。</summary>
    private void ApplyProjection()
    {
        Transform p = m_projector != null ? m_projector : this.transform;
        float aspect = m_aspect > 0f
            ? m_aspect
            : (m_decalTexture != null ? (float)m_decalTexture.width / m_decalTexture.height : 1f);
        m_manager.SetDecalProjection(p.position, p.rotation, m_fov, aspect, m_near, m_far);
    }

    /// <summary>把 4 項遮擋參數彙集為結構體。</summary>
    private DecalOcclusionSettings BuildOcclusionSettings()
    {
        return new DecalOcclusionSettings
        {
            opacityCutoff  = m_occlusionCutoff,
            depthBias      = m_occlusionBias,
            footprintMaxPx = m_occlusionFootprint,
            resolution     = m_occlusionResolution,
        };
    }

    private void CacheOcclusionState()
    {
        m_lastOcclusion  = m_occlusion;
        m_lastCutoff     = m_occlusionCutoff;
        m_lastBias       = m_occlusionBias;
        m_lastFootprint  = m_occlusionFootprint;
        m_lastResolution = m_occlusionResolution;
    }

    // ── 便捷調試入口 (Inspector 右鍵) ──
    [ContextMenu("Decal On")]  private void DecalOn()  { m_manager?.SetDecalEnabled(true); }
    [ContextMenu("Decal Off")] private void DecalOff() { m_manager?.SetDecalEnabled(false); }
    [ContextMenu("Occlusion On")]  private void OcclusionOn()  { m_occlusion = true;  m_manager?.SetDecalOcclusion(true);  m_lastOcclusion = true; }
    [ContextMenu("Occlusion Off")] private void OcclusionOff() { m_occlusion = false; m_manager?.SetDecalOcclusion(false); m_lastOcclusion = false; }
}

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

m_manager.SetDecalEnabled(true);
m_manager.SetDecalTexture(decalTex);
m_manager.SetDecalProjection(projectorPos, projectorRot, 60f, 1.778f, 0.1f, 20f);

// 返回值：void
public void SetDecalTexture(Texture2D tex)

m_manager.SetDecalTexture(logoTex);

// 返回值：void
public void SetDecalProjection(Vector3 pos, Quaternion rot, float fov, float aspect, float near, float far)

m_manager.SetDecalProjection(new Vector3(0, 10, 0), Quaternion.Euler(90, 0, 0), 60f, 1.778f, 0.1f, 20f);

// 返回值：void
public void SetDecalOpacity(float opacity)

m_manager.SetDecalOpacity(0.8f);

// 返回值：void
public void SetDecalEdgeFade(float edgeFade)

m_manager.SetDecalEdgeFade(0.1f);

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

m_manager.SetDecalOcclusion(true);

// 返回值：void
public void SetDecalOcclusionSettings(DecalOcclusionSettings settings)

m_manager.SetDecalOcclusionSettings(DecalOcclusionSettings.Default);
m_manager.SetDecalOcclusionSettings(new DecalOcclusionSettings {
    opacityCutoff = 0.1f,
    depthBias = 0.05f,
    footprintMaxPx = 2,
    resolution = 1024
});

public struct DecalOcclusionSettings {
    public float opacityCutoff;   // [0,1] splat 參與深度圖的最低 opacity，默認 0（全部參與）
    public float depthBias;       // 相對深度容差比例，默認 0.05
    public int   footprintMaxPx;  // 方形足跡半徑上限(px)，0~16，默認 2
    public int   resolution;      // 深度圖分辨率(px，2 的冪，256~4096)，默認 1024

    public static DecalOcclusionSettings Default { get; } // cutoff=0, bias=0.05, footprint=2, resolution=1024
}