DirectXTex Usage 是一项使用指南,用于说明如何在 C++ 项目中集成并使用 DirectXTex 纹理处理库。DirectXTex 面向 Direct3D 11 和 Direct3D 12 应用,支持 DDS 文件读写,并能对纹理内容执行调整尺寸、格式转换、生成 mipmap、块压缩和生成法线贴图等处理。
用途
当需要将 DirectXTex 作为依赖加入新项目或现有项目,编写处理纹理数据的代码(例如缩放、格式转换、生成 mipmap、进行 DirectX 块压缩),或了解典型的 DirectXTex 处理管线时,可以使用本指南。
集成方式
通过 vcpkg 的 manifest 模式(推荐):在 vcpkg.json 的 dependencies 中加入 directxtex。通过 vcpkg 的经典模式:运行 vcpkg install directxtex。可用特性包括 dx12(DirectX 12 API 支持)、openexr(OpenEXR 支持)、tools(命令行工具);triplet 包括 x64-windows、x64-linux、arm64-windows 等。如果使用 DLL,需要在消费项目中定义 DIRECTX_TEX_IMPORT;如果使用静态库,则使用 -static-md 系列 triplet。CMake 中使用 find_package(directxtex CONFIG REQUIRED) 与 target_link_libraries(${PROJECT_NAME} PRIVATE Microsoft::DirectXTex)。
也可以通过 NuGet 集成:Win32 桌面应用使用 directxtex_desktop_win10,UWP 应用使用 directxtex_uwp。还可以采用项目引用:把 DirectXTex/ 下对应的 .vcxproj 加入解决方案,并添加项目引用,同时把 DirectXTex 目录加入 Additional Include Directories。
头文件包含时,需要先包含 d3d12.h 或 d3d11_1.h,再包含 DirectXTex.h,并使用 using namespace DirectX。辅助特性需要额外头文件:DirectXTexEXR.h 用于 OpenEXR,DirectXTexJPEG.h 和 DirectXTexPNG.h 使用 libjpeg/libpng(非 WIC,通常在 Linux 使用),DirectXTexXbox.h 用于 Xbox 平铺扩展。
关键概念
ScratchImage 是主要的图像容器,拥有像素内存,可访问各个 mip 级别、数组切片和体积深度切片。TexMetadata 描述纹理尺寸、格式、mip 数量、数组大小和类型(1D、2D、3D、立方体贴图)。Blob 是用于序列化输出的内存缓冲。所有处理函数返回 HRESULT,需用 FAILED/SUCCEEDED 检查。
主要能力与示例
加载:LoadFromDDSFile、LoadFromWICFile(PNG/BMP/JPEG/TIFF,仅 Windows)、LoadFromTGAFile、LoadFromHDRFile、LoadFromDDSMemory。
保存:SaveToDDSFile、SaveToWICFile(单张图像,Windows)、SaveToDDSMemory。
处理:Convert 格式转换、Resize 缩放、GenerateMipMaps 生成 mip 链(0 表示完整链)、Compress 块压缩(支持 BC7,也可通过 Direct3D 11 设备进行 GPU 加速的 BC6H/BC7 压缩)、Decompress 解压、ComputeNormalMap 生成法线贴图、PremultiplyAlpha 预乘 Alpha。
资源创建:CreateTexture 与 CreateShaderResourceView 创建 D3D11 资源;D3D12 下使用 CreateTexture 创建提交资源,并用 PrepareUpload 准备 CopyTextureRegion 所需子资源数据。
典型离线纹理管线:加载源图 → 按需缩放到 1024×1024 → 生成 mipmap → 压缩为 BC7 → 保存为 DDS。
格式工具函数:IsCompressed、BitsPerPixel、IsSRGB、MakeSRGB、MakeLinear、ComputePitch 等,可用于查询 DXGI 格式属性。
命令行工具
DirectXTex 附带三个 CLI 工具:texconv(转换图像为 DDS,支持压缩、mipmap、缩放)、texassemble(由单张图像创建立方体贴图、纹理数组和体积贴图)、texdiag(检查与验证 DDS 文件)。示例:texconv -f BC7_UNORM -m 0 -y diffuse.png。
适用场景与限制
适用于 Windows 桌面、UWP、Xbox (GDK) 和 Linux。平台支持矩阵显示:Windows 桌面与 UWP 支持 DDS、HDR、TGA、WIC、Direct3D 11/12;Xbox (GDK) 支持 DDS、HDR、TGA、Direct3D 11/12,但不支持 WIC;Linux 仅支持 DDS、HDR、TGA,不支持 WIC 与 Direct3D。WIC 相关加载/保存以及 D3D 资源创建因此主要面向 Windows 环境。