XGRIDS文档

LCC 与 LCC2 数据格式兼容开发指南

LCC2 数据格式提供了更好的数据压缩及 LOD 机制，原 LCC 格式后续会逐步被 LCC2 取代，原 LCC SDK（v1.x）也会逐步停止维护。由于新旧数据格式差异巨大，新版 LCC SDK（v2.x）不会向下兼容 LCC 格式。后续可通过以下两种方式实现数据兼容：

  1. 使用官方提供的转换器（LccConverter）exe/dll，将 LCC 数据格式转换为 LCC2，再进入 SDK 使用；
  2. 在应用层进行 LCC 和 LCC2 数据格式的兼容。

本文主要说明在应用层进行数据格式兼容的流程及步骤，即在同一 Unity 工程中同时导入两个版本的 SDK，根据数据格式自动选择对应版本进行渲染和相应的处理。

步骤 1：Unity 版本与工程设置

Unity 版本与工程设置与独立使用 SDK 时一致，无需额外配置。具体可参考 PC 快速开发入门指南 和 工程设置优化指南

步骤 2：导入两个版本的 SDK

通过 Unity UPM 分别导入 SDK v1.4.8 及以上版本 （ 建议使用 v1.4.32 ）和 SDK v2.0.1 及以上版本。导入后，v1.x 版本会显示为 Legacy。两个版本的 SDK 可以共存，互不影响。

说明：

步骤 3：配置场景

在场景中新建一个空对象，命名为 LCCController，将 LCCManager_Legacy 和 LCCManager 两个组件都挂载到该对象上。

在 LCCController 对象上挂载 LCCManager_Legacy 和 LCCManager 组件

在 LCCController 对象上同时挂载 LCCManager_Legacy 和 LCCManager 组件

注意：

LCCController 游戏对象的 Transform 设置（Rotation.x = -90、Scale.x = -1）是与 LCC 数据坐标系的对齐。关于坐标系对齐的详细说明，参见 Unity SDK 简介 中的「LCC 数据坐标系」。

步骤 4：编写 MultiSDKController 脚本

新建一个 C# 脚本，命名为 MultiSDKController.cs，代码如下：

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

public class MultiSDKController : MonoBehaviour
{
    public LCCManager_Legacy m_managerLegacy;          // 用于 LCC SDK v1.4.8 及以下版本
    public LCCManager m_manager;                       // 用于 LCC SDK v2.0.0 及以上版本
    public string m_FilePath;                          // LCC 文件路径
    private LCCCore_Legacy.Renderer m_rendererLegacy;  // 用于 LCC SDK v1.4.8 及以下版本
    private LCCCore.Renderer m_renderer;               // 用于 LCC SDK v2.0.0 及以上版本
    private DataType m_dataType;                       // 数据类型，用于判断使用哪个 SDK

    void Start()
    {
        string extension = Path.GetExtension(m_FilePath);
        if (extension == ".lcc")
        {
            m_manager.Enable = false; // 禁用 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; // 禁用 v1.4.8 及以下版本的管理器
            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("data loaded !!!");
    }

    // 方法调用示例：通过数据类型判断使用哪个 SDK 的渲染器进行操作
    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 }
}

注意：

  • 脚本文件名必须与类名一致（MultiSDKController.cs 对应 class MultiSDKController），否则无法挂载到游戏对象上。
  • 两个版本的命名空间不同（LCCCore 与 LCCCore_Legacy），使用 Renderer、PlatformType、RenderMode 等同名类型时需带上命名空间前缀以区分。
  • 示例通过文件后缀（.lcc / .lcc2）判断数据格式并选择对应 SDK 版本。

步骤 5：挂载脚本并设置属性

  1. 将 MultiSDKController.cs 脚本也挂载到场景中的 LCCController 对象上。
  2. 在 Inspector 窗口中，将 LCCManager 和 LCCManager_Legacy 组件分别拖动到脚本对应的属性上。
  3. 在脚本的 File Path 属性中填写 LCC / LCC2 文件的路径地址。
挂载 MultiSDKController 脚本并设置属性

挂载 MultiSDKController 脚本并在 Inspector 中设置属性

此时运行代码，即可根据 LCC 数据格式自动使用对应的 SDK 版本进行渲染，实现数据格式兼容。

关键步骤

在应用层实现 LCC 与 LCC2 数据格式兼容的关键步骤：

  1. 通过 UPM 同时导入 v1.x（Legacy）与 v2.x 两个版本的 SDK，二者可共存。
  2. 在同一对象上挂载 LCCManager_Legacy 与 LCCManager 两个管理器组件。
  3. 根据数据格式（文件后缀 .lcc / .lcc2）选择对应版本的管理器创建渲染器并加载数据。
  4. 确定使用某一版本后，禁用另一版本的管理器（Manager.Enable = false）。
  5. 切换数据或销毁时，通过 Renderer.Dispose() 卸载当前渲染的数据。

数据格式兼容注意事项

  • 不支持同时渲染 LCC 和 LCC2。 因此切换所用数据时，需要先将当前正在渲染的数据卸载（调用 Renderer.Dispose()），否则可能导致内存和显存泄露。

  • 禁用未使用的 Manager。 在确定使用某一个 SDK 版本后，最好将另一个 SDK 版本的 Manager 对象取消使能（Manager.Enable = false），否则可能导致一些无效的性能损耗。

  • API 接口一致，但需调用正确的 Render。 两个 SDK 版本的 API 接口完全一致（v2.x 版本很多API已迁移到Manager类，请参阅API手册），但使用时需确保调用正确版本的 Renderer（m_rendererLegacy 或 m_renderer）。另外，v2.0.0 及以上版本不再支持调色和裁剪数据保存功能，其他部分 API 也已失效，请查阅对应版本的开发者文档。

相关 API

本方案主要涉及两个版本 SDK 的管理器与渲染器 API。以下以 v2.x（LCCCore）为例说明，v1.x（LCCCore_Legacy）接口一致，仅命名空间不同。

LCCManager.Enable

// 属性
public bool Enable { get; set; }

管理器的使能开关。设为 false 可禁用该版本 SDK 的管理器，避免与另一版本同时工作产生无效性能损耗。

调用示例：

// 使用 LCC2 数据时，禁用 Legacy 管理器
m_managerLegacy.Enable = false;

说明：

  • 在确定使用某一版本后，建议禁用另一版本的管理器。

GetRender

// 返回值：Renderer → 渲染实例，失败返回 null
public Renderer GetRender(Transform _transform)

创建一个渲染实例并绑定到指定的 Transform。

参数类型说明
_transformTransform渲染实例挂载的 Transform

调用示例：

m_renderer = m_manager.GetRender(this.transform);

说明：

  • 需通过对应版本的管理器创建，确保渲染器与数据格式匹配。

Renderer.Dispose

// 返回值：void
public void Dispose()

销毁渲染实例，释放所有 GPU 资源和内存。销毁后实例不可再使用。

调用示例：

m_renderer?.Dispose();

说明：

  • 切换数据前必须先卸载当前数据，否则可能导致内存和显存泄露。
  • 调用后自动通知 Manager 移除引用。
  • 建议在对象销毁（OnDestroy）时调用。