Renderer: Rendering-Instanz

Eine LCC-Rendering-Instanz, verantwortlich für das Laden der Daten und die Rendering-Steuerung einer einzelnen 3DGS-Szene. Sie wird über LCCManager.GetRender() erstellt und kann nicht direkt instanziiert werden.

Eigenschaften

Methoden

Die Methoden sind nach Zweck gruppiert:

• Datenladen und Lebenszyklus
• Laufzeitsteuerung und Abfragen

Datenladen und Lebenszyklus

Load

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

Lädt eine 3DGS-Datendatei. Unterstützt .lcc2 (lokale Datei oder HTTP-remote) und die nativen Formate .ply / .sog / .spz / .splat / .ksplat (nur lokale Dateien).

Hinweise:

• Der Callback _onComplete wird ausgelöst, nachdem die Daten tatsächlich auf der GPU angekommen sind.
• Operationen wie Schattenempfang und Effektauslösung müssen innerhalb des Callbacks _onComplete aufgerufen werden.
• Native Formate verwenden immer den SingleRender-Voll-Load-Pfad (kein LOD-Chunking); der Fortschritt wird über _onProgress und Fehler über _onError gemeldet.
• Der Modus MultiRender erlaubt keine HTTP-Datenquellen oder nativen Formate.
• HTTP unterstützt nur .lcc2; native Formate sind nur lokale Pfade und nur im SingleRender-Modus.
• SetPlatformType() / SwitchRenderPass() / SetMainCamera() und andere Voraussetzungen müssen zuerst abgeschlossen sein.
• Sie müssen Unload() oder Dispose() aufrufen, bevor Sie Load() erneut aufrufen; ein Aufruf von Load() während eines laufenden Ladevorgangs wird abgelehnt und löst _onError aus.

Beispiel:

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

Unload

public void Unload()

Gibt die aktuell geladenen Daten frei und kehrt in den Zustand „erstellt, aber nicht geladen“ zurück, wobei die Manager-Registrierung der Instanz erhalten bleibt. Dieselbe Renderer-Instanz kann durch wiederholtes Durchlaufen von Load → Unload → Load wiederverwendet werden.

Hinweise:

• Unterschied zu Dispose(): Die Manager-Registrierung wird nicht entfernt und die Instanz kann wiederverwendet werden.
• Nach Unload() ist IsEnable false; ein erneuter Aufruf von Load() setzt den gesamten Datenzustand zurück.
• Wird nur ausgeführt, wenn die Daten das Laden abgeschlossen haben; kehrt sofort zurück, wenn nicht geladen oder bereits Dispose() ausgeführt wurde.

Beispiel:

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

Dispose

public void Dispose()

Zerstört die Rendering-Instanz und gibt alle GPU-Ressourcen und den Speicher frei. Die Instanz kann nach der Zerstörung nicht mehr verwendet werden, und alle öffentlichen Methoden werden automatisch wirkungslos.

Hinweise:

• Benachrichtigt den LCCManager nach dem Aufruf automatisch, die Referenz zu entfernen.

Beispiel:

renderer.Dispose();
renderer = null;

Laufzeitsteuerung und Abfragen

SetEnable

public void SetEnable(bool _enable)

Legt den Aktivierungszustand der Rendering-Instanz fest. Wenn deaktiviert, nimmt sie nicht am Rendering oder an der LOD-Auswahl teil.

Hinweise:

• Gibt keine Ressourcen frei und kann jederzeit reaktiviert werden.

Beispiel:

renderer.SetEnable(false); // Ausblenden
renderer.SetEnable(true);  // Einblenden

SetAlpha

public void SetAlpha(float alpha)

Legt die unabhängige Deckkraft des aktuellen Renderer fest. Anders als das prozessweite globale Alpha von LCCManager.SetAlpha() wirkt diese API nur auf den aktuellen Renderer. Endgültiges Alpha = Splat-Abdeckung × globales Alpha des LCCManager × Alpha dieses Renderer.

Hinweise:

• Wirkt nur auf dem MultiRender- / RenderCore-Pfad (PC / Mac); auf diesem Pfad trägt jeder Splat eine renderID, und der Shader indiziert das Alpha-Array pro Renderer über die renderID.
• Der FullRender- / Mobil-Pfad hat keine renderID, daher ist diese API dort wirkungslos (der Wert wird zwischengespeichert und automatisch angewendet, wenn später zum RenderCore-Pfad gewechselt wird).

Beispiel:

renderer.SetAlpha(0.5f);

SetRenderAll

public void SetRenderAll(bool _renderAll)

Legt fest, ob der Vollrendering-Modus verwendet werden soll (LOD0-Daten vollständig rendern). Er wird beim nächsten Load()-Aufruf wirksam und wirkt sich nicht auf den aktuell geladenen Datensatz aus.

Hinweise:

• Nur auf PC-/Mac-Plattformen unterstützt; keine Wirkung auf Mobil/VR.
• Den aktuellen Zustand mit der Eigenschaft IsRenderAll abfragen.

Beispiel:

renderer.SetRenderAll(true);
renderer.Load(filePath, null, () => Debug.Log("Vollständig geladen"));

SetColliderEnable

// Rückgabewert: bool, true=erfolgreich gesetzt, false=die Daten haben keinen Collider oder die Instanz ist inaktiv
public bool SetColliderEnable(bool _enable)

Schaltet die Collider-Funktion um. Nach dem Aktivieren werden IntersectsSphere() / IntersectsCapsule() und RaycastMesh() verfügbar.

Hinweise:

• Die Daten müssen einen Collider-Knoten enthalten, andernfalls wird false zurückgegeben.
• Der Renderer muss aktiv sein.

Beispiel:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Daten enthalten keinen Collider");

SetEnvironment

public void SetEnvironment(bool _env)

Schaltet das Rendering von Umgebungsdaten um. Umgebungsdaten sind eine niederpräzise Hintergrund-Punktwolke, die zum Auffüllen entfernter Ansichten verwendet wird.

Hinweise:

• Die Daten müssen Umgebungsknoten enthalten.
• Umgebungsdaten sind unabhängig vom LOD-System der Hauptdaten.

Beispiel:

renderer.SetEnvironment(true);

GetBounds

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

Ruft die achsenausgerichtete Bounding Box (Weltkoordinaten) der gerenderten Daten ab.

Hinweise:

• Gibt Vector3.zero zurück, wenn die Daten nicht vollständig geladen sind.
• Kann für die Kamerapositionierung und die Berechnung des Blickwinkels verwendet werden.

Beispiel:

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

GetSourceType

// Rückgabewert: SourceType
public SourceType GetSourceType()

Ruft den Quellentyp der geladenen Daten ab; siehe SourceType.

Hinweise:

• Gibt SourceType.None zurück, wenn die Daten nicht geladen sind.

GetDataType

// Rückgabewert: DataType
public DataType GetDataType()

Ruft den Formattyp der geladenen Daten ab; siehe DataType.

Hinweise:

• Gibt DataType.None zurück, wenn die Daten nicht geladen sind.

GetMeta (Aus Dateipfad)

// Rückgabewert: bool, true=erfolgreich gelesen
public bool GetMeta(string _filePath, out SplatMeta _metaData)

Liest die Metadaten der 3DGS-Daten aus dem angegebenen Dateipfad, ohne die Daten vollständig zu laden.

Hinweise:

• Unterstützt lokale Pfade und HTTP-URLs.
• Liest nur die Metadaten des Datei-Headers und lädt keine Punktwolkendaten.
• Gibt false zurück, wenn der Pfad leer ist oder die Datei nicht existiert.

Beispiel:

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

GetMeta (Aus geladenen Daten)

// Rückgabewert: bool, true=erfolgreich gelesen
public bool GetMeta(out SplatMeta _metaData)

Ruft die Metadaten der aktuell geladenen Daten ab. Wenn die Daten das Laden noch nicht abgeschlossen haben, wird versucht, aus dem Dateipfad zu lesen.

Beispiel:

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

GetMeshBlockInfos

// Rückgabewert: List<LCCMeshBlockInfo>, Metadaten der Kollisions-Mesh-Blöcke; null, wenn kein Mesh vorhanden oder nicht verfügbar
public List<LCCMeshBlockInfo> GetMeshBlockInfos()

Gibt die Metadaten aller Kollisions-Mesh-Blöcke zurück (id, Welt- / Lokal-Bounding-Box, Vertexanzahl, Flächenanzahl). Zero I/O, Zero-Analyse — liest nur die bereits im Speicher befindlichen Metadaten. Siehe LCCMeshBlockInfo.

Hinweise:

• Nur PC-/Mac-Plattform + lokale Datenquelle; muss im Hauptthread aufgerufen werden.
• Typische Verwendung: Zuerst damit die Welt-Bounding-Box jedes Blocks abrufen, die benötigten IDs heraussuchen und dann GetMeshes(ids) aufrufen, um nur diese Blöcke zu lesen.
• Native Formate (PLY / SOG / SPZ / splat / ksplat) haben kein Mesh und geben null zurück (normal, keine Protokollierung).

Beispiel:

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

GetMeshes

// Rückgabewert: List<LCCMeshBlock>, Geometriedaten aller Kollisions-Mesh-Blöcke; null, wenn nicht verfügbar
public List<LCCMeshBlock> GetMeshes()

Gibt synchron die Geometriedaten aller Kollisions-Mesh-Blöcke zurück (Vertices + Dreiecksindizes, in lokalen Koordinaten). Dies ist eine schwere Operation (synchrones Festplattenlesen + Analyse + Zuweisung), daher rufen Sie sie einmal auf und cachen Sie sie selbst — niemals in jedem Frame. Siehe LCCMeshBlock.

Hinweise:

• Nur PC-/Mac-Plattform + lokale Datenquelle; muss im Hauptthread aufgerufen werden.
• Verwenden Sie für große Szenen GetMeshBlockInfos() zum Auswählen der IDs + GetMeshes(ids), um die einmalige Zuweisung großer Mengen verwalteten Speichers zu vermeiden.
• Ein einzelner Block kann mehr als 65535 Vertices haben, daher muss mesh.indexFormat = IndexFormat.UInt32 vor dem Aufbau des Mesh gesetzt werden.

Beispiel:

var meshes = renderer.GetMeshes();
foreach (var block in meshes)
{
    // block.vertices / block.triangles liegen im lokalen Koordinatensystem des Objekts vor
}

GetMeshes (Nach ID)

// Rückgabewert: List<LCCMeshBlock>, Kollisions-Mesh-Geometriedaten der angegebenen IDs; null, wenn kein Treffer
public List<LCCMeshBlock> GetMeshes(IEnumerable<string> _ids)

Gibt synchron die Kollisions-Mesh-Block-Geometriedaten (in lokalen Koordinaten) der angegebenen IDs zurück. Die IDs werden von GetMeshBlockInfos() bereitgestellt.

Hinweise:

• Unbekannte IDs werden mit einer Warnung übersprungen; doppelte IDs werden dedupliziert (keine wiederholten Festplattenlesevorgänge); die Rückgabereihenfolge ist die Traversierungsreihenfolge der IDs (nach Deduplizierung).
• Gibt null mit einer Warnung zurück, wenn die Eingabe null, leer oder ohne Treffer ist.
• Weitere Einschränkungen sind dieselben wie bei GetMeshes().

Beispiel:

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