RTXNTC 是 NVIDIA 开源的神经纹理压缩（Neural Texture Compression，NTC）SDK，其核心库 LibNTC 让你用十几行 C++ 代码即可完成「PBR 纹理组压缩 → 保存 NTC 文件 → 解压还原」的完整流程，把一套材质纹理的磁盘占用和显存占用压缩到传统 BCn 格式的 1/8 左右。本文将带你走通 LibNTC API 实战全流程：从项目集成、初始化 Context，到纹理压缩与三种解压模式，每一步都给出关键代码与实用建议。

神经纹理压缩能省多少？先看一个真实例子 🧱

NTC 的思路是把一个材质的全部 PBR 纹理（反照率、法线、粗糙度、金属度、环境光遮蔽等，最多 16 个通道）打包成一组一起压缩：压缩时把像素数据转化为「小型 MLP 解码器权重 + 潜特征张量（latents）」，渲染时由着色器采样 latents 并跑一遍解码器还原颜色。

仓库自带的金属板材质（assets/materials/MetalPlates013/）包含 9 个通道，按 8 位最优打包约 64 bits/texel；传统流水线需要 3 张 BCn 纹理（约 24 bits/texel）；而 NTC 以约5 bits/texel就能达到相近质量（PSNR 40–50 dB）：

压缩过程分为 5 步：构建特征金字塔 → 模拟量化（scoring）→ 采样与拼接 → 双层 64 通道隐层网络推理 → 预测各 mip 级别，最终得到可随机访问的 NTC 文件：

第 1 步：把 LibNTC 集成进你的工程（3 步完成）

按照 docs/integration/Installation.md，CMake 工程只需三步：

add_subdirectory(path/to/RTXNTC-Library) target_link_libraries(<your_target> PRIVATE libntc)

然后包含头文件#include <libntc/ntc.h>即可。非 CMake 工程则需手动添加RTXNTC-Library/include到搜索路径、链接libntc.lib，并在部署目录复制libntc.dll与cudart64_12.dll。

第 2 步：初始化 LibNTC Context

所有 LibNTC 操作都依赖一个ntc::IContext（见 docs/integration/Context.md）。纯压缩场景只需 CUDA；若要 GPU 解压，还需把图形设备对象传入：

ntc::IContext* context = nullptr; ntc::ContextParameters contextParams; // 可指定 graphicsApi: Vulkan / D3D12 ntc::Status ntcStatus = ntc::CreateContext(&context, contextParams); // 释放：ntc::DestroyContext(context)

两个容易踩的坑：

• 错误排查：任何返回ntc::Status的函数都会写入错误信息，失败后请立即在同一线程调用ntc::GetLastErrorMessage()获取详情；
• 没有 CUDA 设备时可能返回Status::CudaUnavailable，此时 Context 仍可用于图形 API 解压，但不能压缩。

第 3 步：纹理压缩全流程（5 个子步骤）

压缩 API 围绕ntc::ITextureSet接口展开（完整示例见 docs/integration/Compression.md）：

② 和 ④ 是最核心的两步，代码非常简洁：

// ② 目标 5 bits/pixel，自动匹配最接近的 latent shape float actualBpp; ntc::LatentShape shape; ntc::PickLatentShape(5.0f, actualBpp, shape); textureSet->SetLatentShape(shape); // ④ 压缩是异步分步的，循环执行直到完成 ntc::CompressionSettings settings; // 默认值即可 textureSet->BeginCompression(settings); ntc::CompressionStats stats; ntc::Status s = textureSet->RunCompressionSteps(&stats); while (s == ntc::Status::Incomplete) s = textureSet->RunCompressionSteps(&stats); // 可在循环中上报进度 textureSet->FinalizeCompression();

💡进阶技巧：不想手动指定 BPP？LibNTC 提供了自适应压缩（IAdaptiveCompressionSession），你只需给出目标 PSNR 和最大 BPP，库会自动搜索最优压缩率——原理是先按当前预设压缩、记录 PSNR，再把结果喂回 session 决定下一步，直到收敛。详见 Compression.md#L139-L206。

第 4 步：纹理解压全流程（3 种模式任选）

NTC 文件解压有三种官方模式，对应不同的渲染场景：

模式 A：CUDA 整体解压 —— 集成最快，5 行核心代码

把 NTC 文件在 CPU/CUDA 侧整体还原为原始像素，适合离线转码或工具链：

ntc::FileStreamWrapper in(context); context->OpenFile("material.ntc", false, in.ptr()); ntc::TextureSetWrapper set(context); context->CreateCompressedTextureSetFromStream(in, features, set.ptr()); set->Decompress(&stats, false); // GPU 一次性解压 // 之后用 GetTextureCount()/ReadChannels() 逐张读回像素

ReadChannels支持写入带更多通道的目标缓冲区（多余通道自动填充默认值），读回后你可以直接存图或进入 BCn 编码。完整枚举纹理 + 读数据的流程见 Compression.md#L242-L290。

模式 B：Inference on Load —— GPU 解压 + 转码 BCn 🚀

这是低/中端硬件的主流方案：加载时把 NTC 直接转码为 BCn 纹理。LibNTC 本身不提交任何 GPU 命令，它只负责生成 compute pass 的描述（着色器字节码、常量缓冲、dispatch 维度），由你的引擎负责建管线（参考实现 GraphicsDecompressionPass.cpp）：

ntc::MakeDecompressionComputePassParameters params; params.textureSetMetadata = metadata; params.weightType = metadata->GetBestSupportedWeightType(); ntc::ComputePassDesc pass; context->MakeDecompressionComputePass(params, &pass);

数据流向如下：解析ITextureSetMetadata→ 上传 latent 纹理数组与推理权重 → 执行 NTC 解码（FP8/CoopVec 或 DP4a 回退）→ 送入 BC1–BC7 编码 pass：

• BCn 转码：解码输出可直连MakeBlockCompressionComputePass，输出是 UINT 打包纹理，通过 reinterpret copy 即可变回原生 BCn 资源。LibNTC 还内置了BC7 加速——压缩阶段预先分析每个 4×4 块的最优 mode/partition 并存入 mode buffer，加载时转码提速约20–30 倍（BlockCompression.md）。
• GDeflate 无损再压缩：NTC 文件内部可对 latents 使用 GDeflate 无损压缩进一步瘦身，加载时用 CPU（DecompressBuffer）、Vulkan GPU（DecompressGDeflateOnVulkanGPU）或 DirectStorage 三种路径解回，参考实现见 BufferLoading.cpp：

💡 通过ITextureSet::ConfigureLosslessCompression(...)可关闭 GDeflate，简化加载逻辑。

模式 C：Inference on Sample —— 着色器内逐 texel 推理

高端硬件（支持 Cooperative Vector 的 Ada/Blackwell 显卡）可以直接在像素/光追着色器里对单个 texel 做推理，只解压当前视角真正用到的纹理，显存占用降至 NTC 文件原始大小（上表中 2.5 MB 那一档）。集成分三阶段：解析文件 → 上传 latents/权重 → 着色器中调用 LibNTC 提供的NtcSampleTextureSet函数（HLSL 实现位于libntc/shaders/Inference.hlsl），完整示例见 samples/renderer/NtcForwardShadingPass.hlsl 与 InferenceOnSample.md。

⚠️ 该模式建议搭配 Stochastic Texture Filtering（STF）使用，因为 NTC 只输出单个未滤波 texel。

三种模式怎么选？

实用技巧与常见问题 🔧

• 质量与体积的平衡：latent shape 决定比特率，先用PickLatentShape按目标 BPP 自动匹配，再用自适应压缩精调；更多参数讲解见 docs/SettingsAndQuality.md。
• NTC 文件结构：容器类似 GLB（NTEX签名 + JSON 描述 + 二进制数据块），支持快速索引与版本向后兼容，规格见 docs/TextureSetFile.md。
• 不想写 C++？仓库提供了 libraries/ntc.py 模块，它是ntc-cli的 Python 封装，几行脚本即可完成压缩、解压与 PSNR 校验，非常适合内容管线自动化。
• 调试建议：先跑--no-coopVec的 DP4a 回退路径验证功能正确性，再在目标 GPU 上开启 CoopVec 追求性能。

参考资料汇总

• 安装与集成：docs/integration/Installation.md
• Context 初始化：docs/integration/Context.md
• 压缩与 CUDA 解压：docs/integration/Compression.md
• Inference on Load：docs/integration/InferenceOnLoad.md
• BCn 转码：docs/integration/BlockCompression.md
• Inference on Sample：docs/integration/InferenceOnSample.md
• 图形 API 参考实现：libraries/ntc-utils/src/
• 渲染器完整示例：samples/renderer/NtcMaterialLoader.cpp
• 示例材质与模型：assets/materials/、assets/models/FlightHelmet/

按照「集成 → 初始化 → 压缩 → 解压」四步走，你就已经把 LibNTC API 的完整工作流跑通了。建议从模式 A 开始验证管线，再按目标硬件逐步迁移到 Inference on Load / Sample，即可在项目中稳定落地神经纹理压缩。