Renderer: instancja renderowania

Instancja renderowania LCC, odpowiedzialna za ładowanie danych i sterowanie renderowaniem pojedynczej sceny 3DGS. Jest tworzona przez LCCManager.GetRender() i nie może być tworzona bezpośrednio.

Właściwości

Metody

Metody są pogrupowane według celu:

• Ładowanie danych i cykl życia
• Sterowanie i zapytania w czasie działania

Ładowanie danych i cykl życia

Load

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

Ładuje plik danych 3DGS. Obsługuje .lcc2 (plik lokalny lub zdalny HTTP) oraz formaty natywne .ply / .sog / .spz / .splat / .ksplat (tylko pliki lokalne).

Uwagi:

• Wywołanie zwrotne _onComplete uruchamia się po faktycznym umieszczeniu danych na GPU.
• Operacje takie jak odbieranie cieni i wywoływanie efektów muszą być wywoływane wewnątrz wywołania zwrotnego _onComplete.
• Formaty natywne zawsze używają ścieżki pełnego ładowania SingleRender (bez fragmentowania LOD); postęp jest raportowany przez _onProgress, a niepowodzenia przez _onError.
• Tryb MultiRender nie pozwala na źródła danych HTTP ani formaty natywne.
• HTTP obsługuje tylko .lcc2; formaty natywne to tylko ścieżki lokalne i tylko tryb SingleRender.
• Najpierw należy ukończyć SetPlatformType() / SwitchRenderPass() / SetMainCamera() i inne wymagania wstępne.
• Musisz wywołać Unload() lub Dispose() przed ponownym wywołaniem Load(); wywołanie Load() podczas trwającego ładowania jest odrzucane i wyzwala _onError.

Przykład:

renderer.Load("D:/data/scene.lcc2",
    p => Debug.Log($"Ładowanie {p:P0}"),
    () => {
        Debug.Log("Ładowanie zakończone");
        lccManager.SetShadowReceive(true);
    });

Unload

public void Unload()

Zwalnia aktualnie załadowane dane i wraca do stanu „utworzony, ale niezaładowany", zachowując rejestrację instancji w menedżerze. Ta sama instancja Renderer może być ponownie używana przez wielokrotne cykle Load → Unload → Load.

Uwagi:

• Różnica w stosunku do Dispose(): rejestracja w menedżerze nie jest usuwana, a instancja może być ponownie używana.
• Po Unload() IsEnable jest false; ponowne wywołanie Load() resetuje cały stan danych.
• Wykonuje się tylko wtedy, gdy dane zakończyły ładowanie; zwraca natychmiast, gdy niezaładowane lub już Dispose().

Przykład:

renderer.Unload();
renderer.Load(newFilePath, null, () => Debug.Log("Ponownie załadowane"));

Dispose

public void Dispose()

Niszczy instancję renderowania i zwalnia wszystkie zasoby GPU oraz pamięć. Instancja nie może być używana po zniszczeniu, a wszystkie publiczne metody automatycznie stają się nieskuteczne.

Uwagi:

• Po wywołaniu automatycznie powiadamia LCCManager o usunięciu odniesienia.

Przykład:

renderer.Dispose();
renderer = null;

Sterowanie i zapytania w czasie działania

SetEnable

public void SetEnable(bool _enable)

Ustawia stan aktywacji instancji renderowania. Gdy wyłączona, nie uczestniczy w renderowaniu ani wyborze LOD.

Uwagi:

• Nie zwalnia zasobów i może być ponownie aktywowana w dowolnym momencie.

Przykład:

renderer.SetEnable(false); // Ukryj
renderer.SetEnable(true);  // Pokaż

SetAlpha

public void SetAlpha(float alpha)

Ustawia niezależną nieprzezroczystość bieżącego Renderera. W przeciwieństwie do globalnej alfa na poziomie procesu w LCCManager.SetAlpha(), to API wpływa tylko na bieżący Renderer. Ostateczna alfa = pokrycie splata × globalna alfa LCCManager × alfa tego Renderera.

Uwagi:

• Działa tylko na ścieżce MultiRender / RenderCore (PC / Mac); na tej ścieżce każdy splat przenosi renderID, a shader indeksuje tablicę alfa per-Renderer według renderID.
• Ścieżka FullRender / Mobile nie ma renderID, więc to API jest tam no-op (wartość jest buforowana i automatycznie stosowana przy późniejszym przełączeniu na ścieżkę RenderCore).

Przykład:

renderer.SetAlpha(0.5f);

SetRenderAll

public void SetRenderAll(bool _renderAll)

Ustawia, czy używać trybu pełnego renderowania (pełne renderowanie danych LOD0). Działa przy następnym wywołaniu Load() i nie wpływa na aktualnie załadowany zestaw danych.

Uwagi:

• Obsługiwane tylko na platformach PC / Mac; brak efektu na mobilnych / VR.
• Zapytaj o bieżący stan właściwością IsRenderAll.

Przykład:

renderer.SetRenderAll(true);
renderer.Load(filePath, null, () => Debug.Log("Pełne załadowane"));

SetColliderEnable

// Wartość zwracana: bool, true=ustawiono pomyślnie, false=dane nie mają kolidera lub instancja jest nieaktywna
public bool SetColliderEnable(bool _enable)

Przełącza funkcję kolidera. Po włączeniu IntersectsSphere() / IntersectsCapsule() i RaycastMesh() stają się dostępne.

Uwagi:

• Dane muszą zawierać węzeł Collidera, w przeciwnym razie zwracane jest false.
• Renderer musi być aktywny.

Przykład:

bool ok = renderer.SetColliderEnable(true);
if (!ok) Debug.LogWarning("Dane nie zawierają kolidera");

SetEnvironment

public void SetEnvironment(bool _env)

Przełącza renderowanie danych środowiskowych. Dane środowiskowe to niskoprecyzyjna chmura punktów tła używana do wypełniania odległych widoków.

Uwagi:

• Dane muszą zawierać węzły środowiskowe.
• Dane środowiskowe są niezależne od systemu LOD danych głównych.

Przykład:

renderer.SetEnvironment(true);

GetBounds

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

Pobiera prostokąt ograniczający wyrównany do osi (współrzędne świata) renderowanych danych.

Uwagi:

• Zwraca Vector3.zero, gdy dane nie są w pełni załadowane.
• Może być używane do pozycjonowania kamery i obliczania kąta widoku.

Przykład:

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

GetSourceType

// Wartość zwracana: SourceType
public SourceType GetSourceType()

Pobiera typ źródła załadowanych danych; zobacz SourceType.

Uwagi:

• Zwraca SourceType.None, gdy dane nie są załadowane.

GetDataType

// Wartość zwracana: DataType
public DataType GetDataType()

Pobiera typ formatu załadowanych danych; zobacz DataType.

Uwagi:

• Zwraca DataType.None, gdy dane nie są załadowane.

GetMeta (ze ścieżki pliku)

// Wartość zwracana: bool, true=odczytano pomyślnie
public bool GetMeta(string _filePath, out SplatMeta _metaData)

Odczytuje metadane danych 3DGS z określonej ścieżki pliku bez pełnego ładowania danych.

Uwagi:

• Obsługuje ścieżki lokalne i adresy URL HTTP.
• Odczytuje tylko metadane nagłówka pliku i nie ładuje danych chmury punktów.
• Zwraca false, gdy ścieżka jest pusta lub plik nie istnieje.

Przykład:

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

GetMeta (z załadowanych danych)

// Wartość zwracana: bool, true=odczytano pomyślnie
public bool GetMeta(out SplatMeta _metaData)

Pobiera metadane aktualnie załadowanych danych. Jeśli dane nie zakończyły ładowania, próbuje odczytać ze ścieżki pliku.

Przykład:

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

GetMeshBlockInfos

// Wartość zwracana: List<LCCMeshBlockInfo>, metadane bloków siatki kolizji; null, gdy nie ma siatki lub jest niedostępna
public List<LCCMeshBlockInfo> GetMeshBlockInfos()

Zwraca metadane wszystkich bloków siatki kolizji (id, prostokąt ograniczający świata / lokalny, liczba wierzchołków, liczba ścian). Zero I/O, zero analizy — odczytuje tylko metadane już w pamięci. Zobacz LCCMeshBlockInfo.

Uwagi:

• Tylko platforma PC / Mac + lokalne źródło danych; musi być wywoływane na wątku głównym.
• Typowe użycie: najpierw użyj jej, aby uzyskać prostokąt ograniczający świata każdego bloku, wybierz potrzebne id, a następnie wywołaj GetMeshes(ids), aby odczytać tylko te bloki.
• Format natywny (PLY / SOG / SPZ / splat / ksplat) nie ma siatki i zwraca null (normalne, bez dziennika).

Przykład:

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

GetMeshes

// Wartość zwracana: List<LCCMeshBlock>, wszystkie dane geometrii siatki kolizji; null, gdy niedostępna
public List<LCCMeshBlock> GetMeshes()

Synchronicznie zwraca dane geometrii wszystkich bloków siatki kolizji (wierzchołki + indeksy trójkątów, w lokalnych współrzędnych). To ciężka operacja (synchroniczny odczyt z dysku + analiza + alokacja), więc wywołaj ją raz i sam buforuj — nigdy nie wywołuj co klatkę. Zobacz LCCMeshBlock.

Uwagi:

• Tylko platforma PC / Mac + lokalne źródło danych; musi być wywoływane na wątku głównym.
• Dla dużych scen użyj GetMeshBlockInfos() do wyboru id + GetMeshes(ids), aby uniknąć alokacji ogromnej ilości pamięci zarządzanej naraz.
• Pojedynczy blok może mieć ponad 65535 wierzchołków, więc przed zbudowaniem Mesh należy ustawić mesh.indexFormat = IndexFormat.UInt32.

Przykład:

var meshes = renderer.GetMeshes();
foreach (var block in meshes)
{
    // block.vertices / block.triangles są w lokalnym układzie współrzędnych obiektu
}

GetMeshes (według id)

// Wartość zwracana: List<LCCMeshBlock>, dane geometrii siatki kolizji określonych id; null, gdy brak trafienia
public List<LCCMeshBlock> GetMeshes(IEnumerable<string> _ids)

Synchronicznie zwraca dane geometrii bloków siatki kolizji (w lokalnych współrzędnych) o określonych id. Id są dostarczane przez GetMeshBlockInfos().

Uwagi:

• Nieznane id są pomijane z ostrzeżeniem; zduplikowane id są deduplikowane (bez powtarzanych odczytów z dysku); kolejność zwracania to kolejność przechodzenia id (po deduplikacji).
• Zwraca null z ostrzeżeniem, gdy wejście jest null, puste lub nie ma trafień.
• Pozostałe ograniczenia są takie same jak w GetMeshes().

Przykład:

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