Руководство по разработке проецируемых декалей

using LCCCore;
using UnityEngine;

/// <summary>
/// Проекция декали — минимальный пример использования для разработчика.
///
/// Этот скрипт имитирует «скрипт интегратора»: он вызывает только публичные API LCCManager и не затрагивает внутренности 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). Вызовы на mobile/VR игнорируются SDK и записываются как предупреждения.
/// </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("При включении задние грани/окклюдированные точки за передней геометрией больше не окрашиваются декалью (эффект слайд-проектора); при выключении — эффект рентгена")]
    public bool m_occlusion = false;
    [Range(0f, 1f)][Tooltip("Порог непрозрачности: только сплаты с непрозрачностью >= этого значения участвуют в карте глубины, отфильтровывая плавающие/туманные точки. 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, степень двойки 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)

        // -- Отсечение окклюзией: 2 API -- должны вызываться после ApplyProjection (карте глубины нужна валидная VP проектора)
        m_manager.SetDecalOcclusionSettings(BuildOcclusionSettings());
        m_manager.SetDecalOcclusion(m_occlusion);
        CacheOcclusionState();

        m_loaded = true;
    }

    /// <summary>
    /// Только для демонстрации. В реальных проектах для лучшей производительности не нужно вызывать
    /// SetDecalProjection / SetDecalOpacity / SetDecalEdgeFade каждый кадр в Update();
    /// вызывайте соответствующий 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("Включить декаль")]  private void DecalOn()  { m_manager?.SetDecalEnabled(true); }
    [ContextMenu("Выключить декаль")] private void DecalOff() { m_manager?.SetDecalEnabled(false); }
    [ContextMenu("Включить окклюзию")]  private void OcclusionOn()  { m_occlusion = true;  m_manager?.SetDecalOcclusion(true);  m_lastOcclusion = true; }
    [ContextMenu("Выключить окклюзию")] 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] минимальная непрозрачность для участия сплата в карте глубины, по умолчанию 0 (участвуют все)
    public float depthBias;       // относительный коэффициент допуска глубины, по умолчанию 0.05
    public int   footprintMaxPx;  // ограничение квадратного радиуса следа (px), 0~16, по умолчанию 2
    public int   resolution;      // разрешение карты глубины (px, степень двойки, 256~4096), по умолчанию 1024

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