XGRIDSDocumentazione

Guida allo sviluppo della compatibilità dei formati dati LCC e LCC2

Il formato dati LCC2 offre una migliore compressione dei dati e meccanismi LOD. Il formato LCC originale verrà gradualmente sostituito da LCC2, e l'LCC SDK originale (v1.x) cesserà gradualmente di essere mantenuto. Poiché i formati dati vecchio e nuovo differiscono notevolmente, il nuovo LCC SDK (v2.x) non è retrocompatibile con il formato LCC. La compatibilità dei dati può essere ottenuta nei due modi seguenti:

  1. Usa il convertitore ufficiale (LccConverter) exe/dll per convertire il formato dati LCC in LCC2 e poi usalo nell'SDK;
  2. Implementa la compatibilità dei formati dati LCC e LCC2 a livello di applicazione.

Questa guida descrive principalmente il flusso e i passaggi per implementare la compatibilità dei formati dati a livello di applicazione, ovvero importare due versioni dell'SDK nello stesso progetto Unity contemporaneamente e selezionare automaticamente la versione corrispondente per il rendering e l'elaborazione in base al formato dati.

Passaggio 1: versione Unity e impostazioni del progetto

La versione Unity e le impostazioni del progetto sono le stesse di quando si usa l'SDK in modo indipendente; non è richiesta alcuna configurazione aggiuntiva. Vedi Guida rapida per PC e Guida all'ottimizzazione delle impostazioni di progetto.

Passaggio 2: importa le due versioni dell'SDK

Importa SDK v1.4.8 o successivo (si consiglia v1.4.32) e SDK v2.0.1 o successivo tramite Unity UPM. Dopo l'importazione, la versione v1.x verrà visualizzata come Legacy. Le due versioni dell'SDK possono coesistere senza influenzarsi a vicenda.

Nota:

  • L'SDK v1.4.32 può essere scaricato da GitHub: https://github.com/xgrids/LCC-Unity-SDK/releases
  • Il namespace dell'SDK v1.4.32 è LCCCore_Legacy e il suo componente manager è LCCManager_Legacy; il namespace di v2.x è LCCCore e il suo componente manager è LCCManager.

Passaggio 3: configura la scena

Crea un oggetto vuoto nella scena denominato LCCController e associa sia il componente LCCManager_Legacy sia il componente LCCManager a tale oggetto.

Associa i componenti LCCManager_Legacy e LCCManager all'oggetto LCCController

Associa sia il componente LCCManager_Legacy sia il componente LCCManager all'oggetto LCCController

Nota:

Le impostazioni Transform del GameObject LCCController (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 4: scrivi lo script MultiSDKController

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

using LCCCore;
using LCCCore_Legacy;
using System.IO;
using UnityEngine;

public class MultiSDKController : MonoBehaviour
{
    public LCCManager_Legacy m_managerLegacy;          // per l'LCC SDK v1.4.8 e precedenti
    public LCCManager m_manager;                       // per l'LCC SDK v2.0.0 e successivi
    public string m_FilePath;                          // percorso del file LCC
    private LCCCore_Legacy.Renderer m_rendererLegacy;  // per l'LCC SDK v1.4.8 e precedenti
    private LCCCore.Renderer m_renderer;               // per l'LCC SDK v2.0.0 e successivi
    private DataType m_dataType;                       // tipo di dati, usato per determinare quale SDK usare

    void Start()
    {
        string extension = Path.GetExtension(m_FilePath);
        if (extension == ".lcc")
        {
            m_manager.Enable = false; // disabilita il manager v2.0.0+
            m_dataType = DataType.LCC;
            m_rendererLegacy = m_managerLegacy.GetRender(this.transform);
            m_rendererLegacy.Load(m_FilePath, LCCCore_Legacy.PlatformType.PC, onLoadCallback);
        }
        else if (extension == ".lcc2")
        {
            m_managerLegacy.Enable = false; // disabilita il manager v1.4.8 e precedenti
            m_dataType = DataType.LCC2;
            m_renderer = m_manager.GetRender(this.transform);
            m_renderer.Load(m_FilePath, LCCCore.PlatformType.PC, onLoadCallback);
        }
    }

    private void onLoadCallback()
    {
        Debug.Log("dati caricati !!!");
    }

    // Esempio di chiamata di metodo: determina su quale renderer dell'SDK operare in base al tipo di dati
    public void onRenderPointClick()
    {
        if (m_dataType == DataType.LCC)
            m_rendererLegacy.SwitchRenderMode(LCCCore_Legacy.RenderMode.PointCloud);
        else if (m_dataType == DataType.LCC2)
            m_renderer.SwitchRenderMode(LCCCore.RenderMode.PointCloud);
    }

    void OnDestroy()
    {
        if (m_dataType == DataType.LCC)
            m_rendererLegacy?.Dispose();
        else if (m_dataType == DataType.LCC2)
            m_renderer?.Dispose();
    }

    public enum DataType { LCC, LCC2 }
}

Nota:

  • Il nome del file dello script deve corrispondere al nome della classe (MultiSDKController.cs corrisponde a class MultiSDKController), altrimenti non può essere associato a un GameObject.
  • Le due versioni hanno namespace diversi (LCCCore e LCCCore_Legacy). Quando usi tipi con lo stesso nome come Renderer, PlatformType e RenderMode, devi anteporre il namespace per distinguerli.
  • L'esempio determina il formato dati in base all'estensione del file (.lcc / .lcc2) e seleziona la versione dell'SDK corrispondente.

Passaggio 5: associa lo script e imposta le proprietà

  1. Associa anche lo script MultiSDKController.cs all'oggetto LCCController nella scena.
  2. Nella finestra Inspector, trascina i componenti LCCManager e LCCManager_Legacy sulle proprietà corrispondenti dello script.
  3. Inserisci il percorso del file LCC / LCC2 nella proprietà File Path dello script.
Associa lo script MultiSDKController e imposta le sue proprietà

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

Ora, quando esegui il codice, la versione dell'SDK corrispondente viene usata automaticamente per il rendering in base al formato dati LCC, ottenendo la compatibilità dei formati dati.

Punti chiave

I passaggi chiave per implementare la compatibilità dei formati dati LCC e LCC2 a livello di applicazione:

  1. Importa entrambe le versioni dell'SDK v1.x (Legacy) e v2.x tramite UPM; le due possono coesistere.
  2. Associa entrambi i componenti manager LCCManager_Legacy e LCCManager allo stesso oggetto.
  3. Seleziona il manager della versione corrispondente per creare un renderer e caricare i dati in base al formato dati (estensione del file .lcc / .lcc2).
  4. Dopo aver determinato quale versione usare, disabilita il manager dell'altra versione (Manager.Enable = false).
  5. Quando cambi i dati o distruggi, scarica i dati attualmente renderizzati tramite Renderer.Dispose().

Note sulla compatibilità dei formati dati

  • Il rendering simultaneo di LCC e LCC2 non è supportato. Pertanto, quando cambi i dati, devi prima scaricare i dati attualmente renderizzati (chiama Renderer.Dispose()), altrimenti potrebbero verificarsi perdite di memoria e memoria video.

  • Disabilita il Manager inutilizzato. Dopo aver determinato quale versione dell'SDK usare, è meglio disabilitare l'oggetto Manager dell'altra versione dell'SDK (Manager.Enable = false), altrimenti potrebbe causare un overhead di prestazioni inefficace.

  • Le interfacce API sono coerenti, ma devi chiamare il Renderer corretto. Le interfacce API delle due versioni dell'SDK sono esattamente le stesse (in v2.x molte API sono state spostate nella classe Manager; vedi il manuale API), ma devi assicurarti di chiamare il Renderer della versione corretta (m_rendererLegacy o m_renderer). Inoltre, v2.0.0 e successivi non supportano più il salvataggio dei dati di regolazione del colore e di ritaglio, e anche alcune altre API sono deprecate; consulta la documentazione per sviluppatori della versione corrispondente.

API correlate

Questa soluzione coinvolge principalmente le API del manager e del renderer delle due versioni dell'SDK. Di seguito viene usata come esempio v2.x (LCCCore); v1.x (LCCCore_Legacy) ha la stessa interfaccia con solo un namespace diverso.

LCCManager.Enable

// Proprietà
public bool Enable { get; set; }

Interruttore di abilitazione del manager. Impostandolo su false si disabilita il manager di quella versione dell'SDK, evitando l'overhead di prestazioni inefficace derivante dal funzionamento simultaneo con l'altra versione.

Esempio di utilizzo:

// Quando usi dati LCC2, disabilita il manager Legacy
m_managerLegacy.Enable = false;

Note:

  • Dopo aver determinato quale versione usare, si consiglia di disabilitare il manager dell'altra versione.

GetRender

// Valore restituito: Renderer → istanza di rendering, null in caso di errore
public Renderer GetRender(Transform _transform)

Crea un'istanza di rendering e la associa al Transform specificato.

ParametroTipoDescrizione
_transformTransformIl Transform a cui è collegata l'istanza di rendering

Esempio di utilizzo:

m_renderer = m_manager.GetRender(this.transform);

Note:

  • Deve essere creata tramite il manager della versione corrispondente per garantire che il renderer corrisponda al formato dati.

Renderer.Dispose

// Valore restituito: void
public void Dispose()

Distrugge l'istanza di rendering e libera tutte le risorse GPU e la memoria. L'istanza non può essere usata nuovamente dopo la distruzione.

Esempio di utilizzo:

m_renderer?.Dispose();

Note:

  • Prima di cambiare i dati, devi prima scaricare i dati attuali, altrimenti potrebbero verificarsi perdite di memoria e memoria video.
  • Dopo la chiamata, notifica automaticamente al Manager di rimuovere il riferimento.
  • Si consiglia di chiamarlo quando l'oggetto viene distrutto (OnDestroy).