Renderer: istanza di rendering

Un'istanza di rendering LCC, responsabile del caricamento dei dati e del controllo del rendering di una singola scena 3DGS. Viene creata tramite LCCManager.GetRender() e non può essere istanziata direttamente.

Proprietà

Metodi

I metodi sono raggruppati per scopo:

• Caricamento dei dati e ciclo di vita
• Controllo a runtime e query

Caricamento dei dati e ciclo di vita

Load

public void Load(string _filePath, Action<float> _onProgress, Action _onComplete, Action<string> _onError = null)

Carica un file di dati 3DGS. Supporta .lcc2 (file locale o HTTP remoto) e i formati nativi .ply / .sog / .spz / .splat / .ksplat (solo file locali).

Note:

• La callback _onComplete viene attivata dopo che i dati sono effettivamente arrivati sulla GPU.
• Operazioni come la ricezione delle ombre e l'attivazione degli effetti devono essere chiamate all'interno della callback _onComplete.
• I formati nativi usano sempre il percorso di caricamento completo SingleRender (senza suddivisione LOD); l'avanzamento viene segnalato tramite _onProgress e gli errori tramite _onError.
• La modalità MultiRender non consente origini dati HTTP né formati nativi.
• HTTP supporta solo .lcc2; i formati nativi sono solo percorsi locali e solo in modalità SingleRender.
• Prima devono essere completati SetPlatformType() / SwitchRenderPass() / SetMainCamera() e gli altri prerequisiti.
• Devi chiamare Unload() o Dispose() prima di chiamare di nuovo Load(); chiamare Load() mentre il caricamento è in corso viene rifiutato e attiva _onError.

Esempio:

renderer.Load("D:/data/scene.lcc2",
    p => Debug.Log($"Caricamento {p:P0}"),
    () => {
        Debug.Log("Caricamento completato");
        lccManager.SetShadowReceive(true);
    });

Unload

public void Unload()

Rilascia i dati attualmente caricati e torna allo stato "creato ma non caricato", mantenendo la registrazione dell'istanza presso il manager. La stessa istanza Renderer può essere riutilizzata ripetendo il ciclo Load → Unload → Load.

Note:

• Differenza rispetto a Dispose(): la registrazione presso il manager non viene rimossa e l'istanza può essere riutilizzata.
• Dopo Unload(), IsEnable è false; chiamare di nuovo Load() reimposta tutto lo stato dei dati.
• Viene eseguita solo quando il caricamento dei dati è terminato; ritorna immediatamente quando non è caricata o è già stata chiamata Dispose().

Esempio:

renderer.Unload();
renderer.Load(newFilePath, null, () => Debug.Log("Ricaricato"));

Dispose

public void Dispose()

Distrugge l'istanza di rendering e rilascia tutte le risorse GPU e la memoria. L'istanza non può essere usata dopo la distruzione e tutti i metodi pubblici diventano automaticamente inefficaci.

Note:

• Notifica automaticamente LCCManager per rimuovere il riferimento dopo la chiamata.

Esempio:

renderer.Dispose();
renderer = null;

Controllo a runtime e query

SetEnable

public void SetEnable(bool _enable)

Imposta lo stato di attivazione dell'istanza di rendering. Quando è disattivata, non partecipa al rendering né alla selezione LOD.

Note:

• Non rilascia le risorse e può essere riattivata in qualsiasi momento.

Esempio:

renderer.SetEnable(false); // Nascondi
renderer.SetEnable(true);  // Mostra

SetAlpha

public void SetAlpha(float alpha)

Imposta l'opacità indipendente del Renderer corrente. A differenza dell'alpha globale a livello di processo di LCCManager.SetAlpha(), questa API influisce solo sul Renderer corrente. Alpha finale = copertura dello splat × alpha globale di LCCManager × alpha di questo Renderer.

Note:

• Ha effetto solo sul percorso MultiRender / RenderCore (PC / Mac); su quel percorso ogni splat porta un renderID e lo shader indicizza l'array alpha per Renderer tramite renderID.
• Il percorso FullRender / Mobile non ha renderID, quindi questa API è un no-op (il valore viene memorizzato e applicato automaticamente quando in seguito si passa al percorso RenderCore).

Esempio:

renderer.SetAlpha(0.5f);

SetRenderAll

public void SetRenderAll(bool _renderAll)

Imposta se usare la modalità di rendering completo (renderizzare completamente i dati LOD0). Ha effetto alla successiva chiamata Load() e non influisce sul dataset attualmente caricato.

Note:

• Supportata solo sulle piattaforme PC / Mac; nessun effetto su mobile / VR.
• Per interrogare lo stato corrente usa la proprietà IsRenderAll.

Esempio:

renderer.SetRenderAll(true);
renderer.Load(filePath, null, () => Debug.Log("Caricamento completo"));

SetColliderEnable

// Valore di ritorno: bool, true=impostato correttamente, false=i dati non hanno collider o l'istanza è inattiva
public bool SetColliderEnable(bool _enable)

Attiva/disattiva la funzionalità collider. Una volta attivata, IntersectsSphere() / IntersectsCapsule() e RaycastMesh() diventano disponibili.

Note:

• I dati devono contenere un nodo Collider, altrimenti viene restituito false.
• Il Renderer deve essere attivo.

Esempio:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("I dati non contengono un collider");

SetEnvironment

public void SetEnvironment(bool _env)

Attiva/disattiva il rendering dei dati ambiente. I dati ambiente sono una nuvola di punti di sfondo a bassa precisione usata per riempire le viste distanti.

Note:

• I dati devono contenere nodi ambiente.
• I dati ambiente sono indipendenti dal sistema LOD dei dati principali.

Esempio:

renderer.SetEnvironment(true);

GetBounds

public void GetBounds(out Vector3 max, out Vector3 min)

Ottiene il box di delimitazione allineato agli assi (coordinate mondo) dei dati renderizzati.

Note:

• Restituisce Vector3.zero quando i dati non sono completamente caricati.
• Può essere usato per il posizionamento della camera e il calcolo dell'angolo di vista.

Esempio:

renderer.GetBounds(out Vector3 max, out Vector3 min);
Vector3 center = (max + min) / 2f;
Vector3 size = max - min;

GetSourceType

// Valore di ritorno: SourceType
public SourceType GetSourceType()

Ottiene il tipo di origine dei dati caricati; vedi SourceType.

Note:

• Restituisce SourceType.None quando i dati non sono caricati.

GetDataType

// Valore di ritorno: DataType
public DataType GetDataType()

Ottiene il tipo di formato dei dati caricati; vedi DataType.

Note:

• Restituisce DataType.None quando i dati non sono caricati.

GetMeta (da percorso file)

// Valore di ritorno: bool, true=letto correttamente
public bool GetMeta(string _filePath, out SplatMeta _metaData)

Legge i metadati dei dati 3DGS dal percorso file specificato senza caricare completamente i dati.

Note:

• Supporta percorsi locali e URL HTTP.
• Legge solo i metadati dell'intestazione del file e non carica i dati della nuvola di punti.
• Restituisce false quando il percorso è vuoto o il file non esiste.

Esempio:

if (renderer.GetMeta(filePath, out SplatMeta meta))
{
    Debug.Log(meta.source);
    Debug.Log(meta.dataType);
}

GetMeta (da dati caricati)

// Valore di ritorno: bool, true=letto correttamente
public bool GetMeta(out SplatMeta _metaData)

Ottiene i metadati dei dati attualmente caricati. Se il caricamento dei dati non è terminato, prova a leggere dal percorso file.

Esempio:

if (renderer.GetMeta(out SplatMeta meta))
{
    Debug.Log(meta.source);
}

GetMeshBlockInfos

// Valore di ritorno: List<LCCMeshBlockInfo>, metadati dei blocchi Mesh di collisione; null quando non c'è Mesh o non è disponibile
public List<LCCMeshBlockInfo> GetMeshBlockInfos()

Restituisce i metadati di tutti i blocchi Mesh di collisione (id, box di delimitazione mondo / locale, numero di vertici, numero di facce). Zero I/O, zero parsing: legge solo i metadati già in memoria. Vedi LCCMeshBlockInfo.

Note:

• Solo piattaforma PC / Mac + origine dati locale; deve essere chiamata sul thread principale.
• Uso tipico: prima usala per ottenere il box di delimitazione mondo di ogni blocco, scegli gli id necessari, poi chiama GetMeshes(ids) per leggere solo quei blocchi.
• I formati nativi (PLY / SOG / SPZ / splat / ksplat) non hanno Mesh e restituiscono null (normale, senza log).

Esempio:

var infos = renderer.GetMeshBlockInfos();
foreach (var info in infos)
{
    Debug.Log($"{info.id}: verts={info.vertexCount}, faces={info.faceCount}");
}

GetMeshes

// Valore di ritorno: List<LCCMeshBlock>, tutti i dati geometrici delle Mesh di collisione; null quando non disponibile
public List<LCCMeshBlock> GetMeshes()

Restituisce in modo sincrono i dati geometrici di tutti i blocchi Mesh di collisione (vertici + indici dei triangoli, in coordinate locali). È un'operazione pesante (lettura disco sincrona + parsing + allocazione), quindi chiamala una volta e memorizzala tu stesso: non chiamarla mai a ogni frame. Vedi LCCMeshBlock.

Note:

• Solo piattaforma PC / Mac + origine dati locale; deve essere chiamata sul thread principale.
• Per scene grandi, usa GetMeshBlockInfos() per scegliere gli id + GetMeshes(ids) per evitare di allocare una quantità enorme di memoria gestita in una sola volta.
• Un singolo blocco può avere più di 65535 vertici, quindi bisogna impostare mesh.indexFormat = IndexFormat.UInt32 prima di costruire la Mesh.

Esempio:

var meshes = renderer.GetMeshes();
foreach (var block in meshes)
{
    // block.vertices / block.triangles sono nel sistema di coordinate locale dell'oggetto
}

GetMeshes (per id)

// Valore di ritorno: List<LCCMeshBlock>, dati geometrici delle Mesh di collisione degli id specificati; null quando non ci sono corrispondenze
public List<LCCMeshBlock> GetMeshes(IEnumerable<string> _ids)

Restituisce in modo sincrono i dati geometrici dei blocchi Mesh di collisione (in coordinate locali) degli id specificati. Gli id sono forniti da GetMeshBlockInfos().

Note:

• Gli id sconosciuti vengono saltati con un avviso; gli id duplicati vengono deduplicati (nessuna lettura disco ripetuta); l'ordine di ritorno è l'ordine di attraversamento degli id (dopo la deduplicazione).
• Restituisce null con un avviso quando l'input è null, vuoto o senza corrispondenze.
• Gli altri vincoli sono gli stessi di GetMeshes().

Esempio:

var ids = new List<string> { "block-0", "block-3" };
var meshes = renderer.GetMeshes(ids);