Gltfpack.Net 1.0.0

Gltfpack.Net 使用说明

C# 直接调用 gltfpack 的托管封装，用于优化 glTF/GLB/OBJ 文件。

⚠️ 仅支持 Windows x64：此库使用 C++/CLI 技术，不支持 Linux、macOS 或其他平台。

安装

dotnet add package Gltfpack.Net

快速开始

using Gltf;

// 简单用法：高压缩
int result = GltfPack.compress("input.glb", "output.glb");

// 自定义配置
using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;
    settings.simplify_ratio = 0.5f;

    result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

API

返回值

GltfSettings 参数详解

压缩选项

网格简化

顶点量化

纹理处理

按纹理类型配置

// GltfTextureKind: Generic, Color, Normal, Attrib
// GltfTextureMode: Raw, ETC1S, UASTC, WebP

settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.ETC1S);
settings.SetTextureQuality(GltfTextureKind.Color, 8);      // 1-10
settings.SetTextureScale(GltfTextureKind.Normal, 0.5f);    // 0-1
settings.SetTextureLimit(GltfTextureKind.Attrib, 1024);    // 最大像素

场景选项

动画选项

使用示例

基础压缩

// 等同于: gltfpack -i input.glb -o output.glb -cc
int result = GltfPack.compress("input.glb", "output.glb");

网格简化

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;
    settings.simplify_ratio = 0.5f;        // 简化到50%
    settings.simplify_lock_borders = true;

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

KTX2 纹理压缩（高质量）

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;

    settings.texture_ktx2 = true;
    settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.UASTC);
    settings.SetTextureMode(GltfTextureKind.Normal, GltfTextureMode.UASTC);
    settings.SetTextureQuality(GltfTextureKind.Color, 10);
    settings.SetTextureQuality(GltfTextureKind.Normal, 10);

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

KTX2 纹理压缩（高压缩率）

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;

    settings.texture_ktx2 = true;
    settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.ETC1S);
    settings.SetTextureMode(GltfTextureKind.Normal, GltfTextureMode.ETC1S);
    settings.SetTextureQuality(GltfTextureKind.Color, 6);
    settings.SetTextureQuality(GltfTextureKind.Normal, 8);
    settings.SetTextureLimit(GltfTextureKind.Color, 1024);

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

WebP 纹理压缩

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;

    settings.texture_webp = true;
    settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.WebP);
    settings.SetTextureMode(GltfTextureKind.Normal, GltfTextureMode.WebP);
    settings.SetTextureQuality(GltfTextureKind.Color, 8);

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

混合纹理压缩

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;
    settings.texture_ktx2 = true;

    // 颜色: ETC1S (高压缩)
    settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.ETC1S);
    settings.SetTextureQuality(GltfTextureKind.Color, 6);

    // 法线: UASTC (高质量)
    settings.SetTextureMode(GltfTextureKind.Normal, GltfTextureMode.UASTC);
    settings.SetTextureQuality(GltfTextureKind.Normal, 10);

    // 属性: UASTC
    settings.SetTextureMode(GltfTextureKind.Attrib, GltfTextureMode.UASTC);
    settings.SetTextureQuality(GltfTextureKind.Attrib, 8);

    settings.texture_jobs = Environment.ProcessorCount;

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

完整优化流程

using (GltfSettings settings = GltfSettings.defaults())
{
    // 压缩
    settings.compress = true;
    settings.compressmore = true;

    // 简化
    settings.simplify_ratio = 0.5f;
    settings.simplify_error = 0.01f;
    settings.simplify_lock_borders = true;

    // 量化
    settings.pos_bits = 14;
    settings.tex_bits = 12;
    settings.nrm_bits = 8;

    // 纹理
    settings.texture_ktx2 = true;
    settings.SetTextureMode(GltfTextureKind.Color, GltfTextureMode.ETC1S);
    settings.SetTextureMode(GltfTextureKind.Normal, GltfTextureMode.UASTC);
    settings.SetTextureQuality(GltfTextureKind.Color, 7);
    settings.SetTextureQuality(GltfTextureKind.Normal, 9);
    settings.texture_jobs = Environment.ProcessorCount;

    // 场景
    settings.mesh_merge = true;
    settings.mesh_instancing = true;

    int result = GltfPack.gltfpack("input.glb", "output.glb", "report.json", settings);
    Console.WriteLine(result == 0 ? "成功" : $"失败: {result}");
}

保留节点数据

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;
    settings.keep_nodes = true;
    settings.keep_extras = true;
    settings.pos_float = true;

    int result = GltfPack.gltfpack("input.glb", "output.glb", null, settings);
}

纹理格式选择

功能支持

日志回调

使用 GltfLogCallback 委托可以捕获 gltfpack 处理过程中的详细输出（需配合 verbose 属性使用）。

GltfLogCallback 委托

public delegate void GltfLogCallback(string message);

使用示例

using Gltf;

// 定义日志回调
void OnLog(string message)
{
    Console.WriteLine($"[gltfpack] {message}");
}

// 使用回调捕获详细输出
using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.compressmore = true;
    settings.verbose = 1;  // 启用详细输出

    int result = GltfPack.gltfpack(
        "input.glb",
        "output.glb",
        null,
        settings,
        OnLog  // 日志回调
    );

    Console.WriteLine(result == 0 ? "成功" : $"失败: {result}");
}

使用 Lambda 表达式

using (GltfSettings settings = GltfSettings.defaults())
{
    settings.compress = true;
    settings.verbose = 1;

    StringBuilder log = new StringBuilder();

    int result = GltfPack.gltfpack(
        "input.glb",
        "output.glb",
        null,
        settings,
        msg => log.AppendLine(msg)  // Lambda 回调
    );

    // 处理完成后查看日志
    Console.WriteLine(log.ToString());
}

verbose 级别

注意事项

• 如果不需要捕获输出，使用不带 logCallback 参数的重载方法
• 回调会在处理完成后一次性返回所有输出
• 输出内容与命令行工具使用 -v 参数时相同