Ontwikkelgids voor realtime belichting

De LCC Unity SDK ondersteunt realtime belichting van dynamische puntlichten en spotlights. Hieronder wordt aan de hand van een voorbeeld van een puntlicht dat langs een cirkelvormig pad beweegt, beschreven hoe je realtime belichting volledig implementeert.

Stap 1: De scène en GameObjects aanmaken

Maak een gloednieuwe scène aan in Unity. Unity maakt standaard Main Camera en Directional Light aan.

Main Camera instellen

Selecteer Main Camera in het Hiërarchie-venster en stel de eigenschappen in het Inspector-venster in zoals hieronder wordt weergegeven.

Stel de eigenschappen van Main Camera in

LCCManager aanmaken

Klik met de rechtermuisknop op een leeg gebied in het Hiërarchie-venster, selecteer Create Empty in het pop-upmenu om een leeg GameObject aan te maken, geef het de naam LCCManager, normaliseer de Transform en voeg het LCCManager-script eraan toe via Component toevoegen.

Maak het LCCManager-GameObject aan en voeg het LCCManager-script toe

LCCRenderer aanmaken

Klik met de rechtermuisknop op een leeg gebied in het Hiërarchie-venster, selecteer Create Empty om een leeg GameObject aan te maken, geef het de naam LCCRenderer en stel de Transform in op Rotation.x = -90 en Scale.x = -1.

Maak LCCRenderer aan en stel de Transform in (Rotation.x = -90, Scale.x = -1)

Opmerking:

De Transform-instellingen van het LCCRenderer-GameObject (Rotation.x = -90, Scale.x = -1) lijnen het uit met het coördinatensysteem van de LCC-gegevens. Zie "Coördinatensysteem van LCC-gegevens" in LCC Unity SDK Introductie voor meer informatie over de uitlijning van het coördinatensysteem.

Stap 2: Een script schrijven om de lichten door te sturen

Maak een nieuw C#-script aan met de naam Relighting.cs met de volgende code:

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("Instellingen voor puntlicht")]
    public Vector3 pointLightPosition = new Vector3(0, 2, 0);
    public Color pointLightColor = Color.red;
    public float pointLightIntensity = 2.0f;
    public float pointLightRange = 3.0f;

    [Header("Instellingen voor 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("Animatie")]
    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] laadvoortgang: {_progress:P1}");
    }

    private void onComplete()
    {
        Debug.Log("[Relighting] laden voltooid, lichten worden ingesteld");
        //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 = puntlicht
        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 mislukt: {result}");
    }

    void OnDisable()
    {
        // Geef null door om aangepaste belichting uit te schakelen
        m_manager.SetLights(null);
    }
}

Opmerking:

• Realtime belichting moet worden doorgestuurd nadat de LCC-scène is geladen, dus de eerste ApplyLights() wordt aangeroepen in de onComplete-callback.
• Dit voorbeeld werkt de lichtpositie elke frame bij in Update om het puntlicht langs een cirkelvormig pad te laten bewegen.
• Het veldtype van het licht is Unity.Mathematics.float3, waarvoor using Unity.Mathematics; vereist is. color heeft slechts drie RGB-componenten en geen alfa.

Stap 3: Het script toevoegen en het gegevenspad instellen

1. Voeg het Relighting.cs-script toe aan het LCCManager-GameObject in het Hiërarchie-venster.
2. Sleep in het Inspector-venster het LCCManager-GameObject naar de eigenschap Manager van het script.
3. Vul het LCC-bestandspad in bij de eigenschap File Path van het script.
4. De overige eigenschappen voor puntlicht, spotlight en animatie kunnen vrij worden geconfigureerd.

Voeg het Relighting-script toe en stel de eigenschappen in de Inspector in

In dit voorbeeld worden één puntlicht en één spotlight aangemaakt en beweegt het puntlicht langs een cirkelvormig pad om het realtime belichtingseffect te demonstreren.

Stap 4: Uitvoeren

Klik op de knop Play in het Game-venster om het realtime belichtingseffect in de scène te zien.

Realtime belichtingseffect in de 3DGS-scène na het uitvoeren

Bijzonderheden van 3DGS-belichting

Belichting in 3DGS verschilt sterk van traditionele Mesh-modelbelichting. Het belichtingseffect in 3DGS wordt rechtstreeks in de RGB-kleur geschreven, wat betekent dat de belichting in de gerenderde kleurcomponenten wordt gebakken. Daarom kan opnieuw belichten de al ingebakken schaduwen niet verwijderen als een 3DGS-model op een zonnige dag met zeer sterke harde schaduwen is vastgelegd.

Bovendien is het kleurbereik tijdens het renderen [0, 1]. Als je de belichting zonder enige bewerking rechtstreeks versterkt, treedt overbelichting op. Om overbelichting te voorkomen, maak je de 3DGS-scène doorgaans eerst donkerder voordat je deze opnieuw belicht.

In de SDK kan de lichtintensiteit worden aangepast via LCCManager.SetLightIntensity(float _intensity):

• De invoerparameter _intensity varieert van [0, 1].
• Deze functie beïnvloedt het algehele belichtingseffect: hoe sterker de geconfigureerde lichtintensiteit, hoe donkerder de 3DGS-scène wordt gemaakt.
• De standaardwaarde is 0.5.

Tip:

Belichtingsberekening is een relatief dure bewerking. De SDK ondersteunt maximaal 50 dynamische lichten (puntlichten en spotlights samen). Wanneer de limiet wordt overschreden, retourneert SetLights -1 en heeft deze geen effect.

Belangrijkste stappen

De belangrijkste stappen voor het toevoegen van realtime belichting aan een 3DGS-scène:

1. Voltooi de pre-configuratie van SetPlatformType / SwitchRenderPass / SetMainCamera en laad de LCC-scène via GetRender + Load.
2. Bouw nadat de scène is geladen (in de onComplete-callback) de PointLightData-lijst op en roep SetLights aan om de lichten door te sturen.
3. Werk wanneer animatie nodig is de lichtparameters bij in Update en roep SetLights opnieuw aan.
4. Gebruik bij overbelichting SetLightIntensity om de scène eerst donkerder te maken voordat je deze opnieuw belicht.
5. Geef null of een lege lijst door aan SetLights om realtime belichting uit te schakelen.

Realtime belichtings-API's

De LCC Unity SDK biedt via LCCManager de volgende twee realtime belichtings-API's. Ze moeten beide worden aangeroepen nadat de LCC-scène is geladen (dat wil zeggen in de onComplete-callback).

SetLights

// Retourwaarde: int → 0 = succes, -1 = de maximale limiet overschreden
public int SetLights(List<PointLightData> lights)

Stelt de aangepaste lijst met puntlichten in. Het doorgeven van null of een lege lijst schakelt aangepaste belichting uit.

Gebruiksvoorbeeld:

using Unity.Mathematics; // float3

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

Opmerkingen:

• Het veldtype is Unity.Mathematics.float3, niet Vector4; color heeft geen alfacomponent.
• lightType: 0 = puntlicht (negeert direction / spotAngle), 1 = spotlight (vereist direction / spotAngle).
• Het maximumaantal is 50 (puntlichten en spotlights samen); retourneert -1 wanneer dit wordt overschreden.
• Het doorgeven van null of een lege lijst schakelt aangepaste belichting uit.
• Wanneer ingeschakeld, wordt het shader-keyword _USERLIGHT ingeschakeld.
• De gegevensstructuur heet PointLightData omdat UnityEngine al LightData definieert, om dubbelzinnigheid te voorkomen.

SetLightIntensity

// Retourwaarde: void
public void SetLightIntensity(float intensity)

Stelt de globale lichtintensiteit in, gebruikt om de 3DGS-scène donkerder te maken voordat deze opnieuw wordt belicht, om overbelichting te voorkomen.

Gebruiksvoorbeeld:

m_manager.SetLightIntensity(0.5f);

Opmerkingen:

• De standaardwaarde is 0.5.
• Bereik [0, 1]; waarden buiten het bereik worden automatisch afgekapt.
• Hoe groter de waarde, hoe donkerder de algehele 3DGS-scène wordt gemaakt.

PointLightData-gegevensstructuur

public struct PointLightData {
    public float3 position;    // wereldpositie
    public int lightType;      // 0=puntlicht, 1=spotlight
    public float3 color;       // rgb-kleur (geen alfacomponent)
    public float intensity;    // lichtintensiteit
    public float3 direction;   // spotlightrichting (genegeerd voor puntlichten)
    public float range;        // lichtbereik
    public float spotAngle;    // kegelhoek van de spotlight (graden, genegeerd voor puntlichten)
    public float3 pad;         // uitlijnpadding, geen toewijzing nodig
}