Guida allo sviluppo dell'illuminazione in tempo reale

L'LCC Unity SDK supporta l'illuminazione in tempo reale da luci puntiformi e spotlight dinamici. Di seguito viene usato un esempio di una luce puntiforme che si muove lungo un percorso circolare per descrivere i passaggi completi per implementare l'illuminazione in tempo reale.

Passaggio 1: crea la scena e i GameObject

Crea una scena completamente nuova in Unity. Unity crea Camera principale e Luce direzionale per impostazione predefinita.

Configura la Camera principale

Seleziona Camera principale nella finestra Gerarchia e imposta le sue proprietà nella finestra Inspector come mostrato di seguito.

Imposta le proprietà della Camera principale

Crea LCCManager

Fai clic con il pulsante destro su un'area vuota nella finestra Gerarchia, seleziona Crea vuoto dal menu a comparsa per creare un GameObject vuoto, assegna il nome LCCManager, normalizza il suo Transform e aggiungi lo script LCCManager tramite Aggiungi componente.

Crea il GameObject LCCManager e aggiungi lo script LCCManager

Crea LCCRenderer

Fai clic con il pulsante destro su un'area vuota nella finestra Gerarchia, seleziona Crea vuoto per creare un GameObject vuoto, assegna il nome LCCRenderer e imposta il suo Transform su Rotation.x = -90 e Scale.x = -1.

Crea LCCRenderer e imposta il suo Transform (Rotation.x = -90, Scale.x = -1)

Nota:

Le impostazioni Transform del GameObject LCCRenderer (Rotation.x = -90, Scale.x = -1) lo allineano al sistema di coordinate dei dati LCC. Per i dettagli sull'allineamento del sistema di coordinate, vedi "Sistema di coordinate dei dati LCC" in Introduzione all'Unity SDK.

Passaggio 2: scrivi uno script per inviare le luci

Crea un nuovo script C# denominato Relighting.cs con il seguente codice:

using System.Collections.Generic;
using LCCCore;
using Unity.Mathematics;
using UnityEngine;

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

    [Header("Impostazioni luce puntiforme")]
    public Vector3 pointLightPosition = new Vector3(0, 2, 0);
    public Color pointLightColor = Color.red;
    public float pointLightIntensity = 2.0f;
    public float pointLightRange = 3.0f;

    [Header("Impostazioni spotlight")]
    public Vector3 spotLightPosition = new Vector3(0, 2, -2);
    public Vector3 spotLightDirection = new Vector3(0, -1, 0);
    public Color spotLightColor = new Color(0.1f, 0.9f, 0.7f);
    public float spotLightIntensity = 3.0f;
    public float spotLightRange = 20.0f;
    public float spotLightAngle = 45.0f;

    [Header("Animazione")]
    public bool animateLights = true;
    public float rotateSpeed = 30.0f;

    private List<PointLightData> m_lights = new List<PointLightData>();
    private float m_angle;

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

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

    private void onProgress(float _progress)
    {
        Debug.Log($"[Relighting] avanzamento caricamento: {_progress:P1}");
    }

    private void onComplete()
    {
        Debug.Log("[Relighting] caricamento completato, configurazione delle luci");
        //m_manager.SetLightIntensity(0.5f);
        ApplyLights();
    }

    void Update()
    {
        if (!animateLights) return;

        m_angle += rotateSpeed * Time.deltaTime;
        ApplyLights();
    }

    private void ApplyLights()
    {
        m_lights.Clear();

        float rad = m_angle * Mathf.Deg2Rad;
        float px = pointLightPosition.x + Mathf.Cos(rad) * 3f;
        float pz = pointLightPosition.z + Mathf.Sin(rad) * 3f;

        // lightType 0 = luce puntiforme
        m_lights.Add(new PointLightData
        {
            position = new float3(px, pointLightPosition.y, pz),
            lightType = 0,
            color = new float3(pointLightColor.r, pointLightColor.g, pointLightColor.b),
            intensity = pointLightIntensity,
            direction = float3.zero,
            range = pointLightRange,
            spotAngle = 0f,
            pad = float3.zero
        });

        // lightType 1 = spotlight
        Vector3 dir = spotLightDirection.normalized;
        m_lights.Add(new PointLightData
        {
            position = new float3(spotLightPosition.x, spotLightPosition.y, spotLightPosition.z),
            lightType = 1,
            color = new float3(spotLightColor.r, spotLightColor.g, spotLightColor.b),
            intensity = spotLightIntensity,
            direction = new float3(dir.x, dir.y, dir.z),
            range = spotLightRange,
            spotAngle = spotLightAngle,
            pad = float3.zero
        });

        int result = m_manager.SetLights(m_lights);
        if (result != 0)
            Debug.LogWarning($"[Relighting] SetLights non riuscito: {result}");
    }

    void OnDisable()
    {
        // Passa null per disabilitare l'illuminazione personalizzata
        m_manager.SetLights(null);
    }
}

Nota:

• L'illuminazione in tempo reale deve essere inviata dopo il completamento del caricamento della scena LCC, quindi il primo ApplyLights() viene chiamato nel callback onComplete.
• Questo esempio aggiorna la posizione della luce a ogni frame in Update per animare la luce puntiforme che si muove lungo un percorso circolare.
• Il tipo del campo luce è Unity.Mathematics.float3, che richiede using Unity.Mathematics;. color ha solo tre componenti RGB e nessun alpha.

Passaggio 3: associa lo script e imposta il percorso dati

1. Associa lo script Relighting.cs al GameObject LCCManager nella finestra Gerarchia.
2. Nella finestra Inspector, trascina il GameObject LCCManager sulla proprietà Manager dello script.
3. Inserisci il percorso del file LCC nella proprietà File Path dello script.
4. Le restanti proprietà di luce puntiforme, spotlight e animazione possono essere configurate liberamente.

Associa lo script Relighting e imposta le sue proprietà nell'Inspector

In questo esempio vengono create una luce puntiforme e uno spotlight, e la luce puntiforme si muove lungo un percorso circolare per dimostrare l'effetto di illuminazione in tempo reale.

Passaggio 4: esegui

Fai clic sul pulsante Play nella finestra Game per vedere l'effetto di illuminazione in tempo reale nella scena.

Effetto di illuminazione in tempo reale nella scena 3DGS dopo l'esecuzione

Peculiarità dell'illuminazione 3DGS

L'illuminazione nella 3DGS differisce notevolmente dall'illuminazione tradizionale dei modelli Mesh. L'effetto di illuminazione nella 3DGS viene scritto direttamente nel colore RGB, il che significa che l'illuminazione è incorporata nei componenti di colore renderizzati. Pertanto, se un modello 3DGS è stato acquisito in una giornata di sole con ombre molto forti e marcate, la re-illuminazione non può rimuovere quelle ombre già incorporate.

Inoltre, l'intervallo di colore durante il rendering è [0, 1]. Se rafforzi direttamente l'illuminazione senza alcuna elaborazione, si verificherà una sovraesposizione. Per evitare la sovraesposizione, di solito si scurisce prima la scena 3DGS e poi la si re-illumina.

Nell'SDK, l'intensità dell'illuminazione può essere regolata tramite LCCManager.SetLightIntensity(float _intensity):

• Il parametro di input _intensity va da [0, 1].
• Questa funzione influisce sull'effetto di illuminazione complessivo: maggiore è l'intensità della luce configurata, più la scena 3DGS viene spinta verso il buio.
• Il valore predefinito è 0.5.

Suggerimento:

Il calcolo dell'illuminazione è un'operazione relativamente costosa. L'SDK supporta un massimo di 50 luci dinamiche (luci puntiformi e spotlight combinati). Quando il limite viene superato, SetLights restituisce -1 e non ha alcun effetto.

Passaggi chiave

I passaggi chiave per aggiungere l'illuminazione in tempo reale a una scena 3DGS:

1. Completa la pre-configurazione di SetPlatformType / SwitchRenderPass / SetMainCamera e carica la scena LCC tramite GetRender + Load.
2. Dopo il completamento del caricamento della scena (nel callback onComplete), costruisci l'elenco PointLightData e chiama SetLights per inviare le luci.
3. Quando è necessaria un'animazione, aggiorna i parametri della luce in Update e chiama nuovamente SetLights.
4. Se si verifica una sovraesposizione, usa SetLightIntensity per scurire la scena prima della re-illuminazione.
5. Per disabilitare l'illuminazione in tempo reale, passa null o un elenco vuoto a SetLights.

API per l'illuminazione in tempo reale

L'LCC Unity SDK fornisce le seguenti due API per l'illuminazione in tempo reale tramite LCCManager. Devono essere entrambe chiamate dopo il completamento del caricamento della scena LCC (ovvero nel callback onComplete).

SetLights

// Valore restituito: int → 0 = successo, -1 = superato il limite massimo di conteggio
public int SetLights(List<PointLightData> lights)

Imposta l'elenco personalizzato delle luci puntiformi. Passare null o un elenco vuoto disabilita l'illuminazione personalizzata.

Esempio di utilizzo:

using Unity.Mathematics; // float3

var lights = new List<PointLightData>();
lights.Add(new PointLightData {
    position = new float3(0, 5, 0),
    lightType = 0,              // 0=luce puntiforme, 1=spotlight
    color = new float3(1, 1, 1),
    intensity = 2f,
    range = 10f
});
m_manager.SetLights(lights);

Note:

• Il tipo del campo è Unity.Mathematics.float3, non Vector4; color non ha il componente alpha.
• lightType: 0 = luce puntiforme (ignora direction / spotAngle), 1 = spotlight (richiede direction / spotAngle).
• Il conteggio massimo è 50 (luci puntiformi e spotlight combinati); restituisce -1 quando viene superato.
• Passare null o un elenco vuoto disabilita l'illuminazione personalizzata.
• Quando è abilitata, viene abilitata la parola chiave shader _USERLIGHT.
• La struttura dati si chiama PointLightData perché UnityEngine definisce già LightData, per evitare ambiguità.

SetLightIntensity

// Valore restituito: void
public void SetLightIntensity(float intensity)

Imposta l'intensità globale dell'illuminazione, usata per scurire la scena 3DGS prima della re-illuminazione per evitare la sovraesposizione.

Esempio di utilizzo:

m_manager.SetLightIntensity(0.5f);

Note:

• Il valore predefinito è 0.5.
• Intervallo [0, 1]; i valori fuori dall'intervallo vengono limitati automaticamente.
• Maggiore è il valore, più la scena 3DGS complessiva viene spinta verso il buio.

Struttura dati PointLightData

public struct PointLightData {
    public float3 position;    // posizione nel mondo
    public int lightType;      // 0=luce puntiforme, 1=spotlight
    public float3 color;       // colore rgb (nessun componente alpha)
    public float intensity;    // intensità della luce
    public float3 direction;   // direzione dello spotlight (ignorata per le luci puntiformi)
    public float range;        // raggio della luce
    public float spotAngle;    // angolo del cono dello spotlight (gradi, ignorato per le luci puntiformi)
    public float3 pad;         // padding di allineamento, nessuna assegnazione necessaria
}