Lib.rs

› 多媒体 › 图像
#图像处理 #dds #图像 #directx #api-bindings #编码

directxtex

微软 DirectXTex 库的非官方 Rust 绑定

作者：Ryan-rsm-McKenzie

1 个稳定版本

1.0.0 2024 年 1 月 23 日

#407 in 图像


用于 ba2

MIT 许可证

1.5MB
31K SLoC

C++ 28K SLoC // 0.1% comments Rust 2.5K SLoC // 0.0% comments

DirectXTex Rust 绑定

这些是非官方的 DirectXTex 纹理处理库的 Rust 绑定。构建此库需要 C++17 兼容的编译器。此库已在 Windows、Linux 和 MacOS 上验证通过。库文档中包含一个迁移表，描述了原始 C++ API 和其 Rust 绑定之间的等效关系。以下是对底层 DirectXTex 库的说明

DirectX Logo

DirectXTex 纹理处理库

http://go.microsoft.com/fwlink/?LinkId=248926

版权所有 © 微软公司。

2023 年 12 月 31 日

本包包含 DirectXTex，这是一个用于读取和写入 .DDS 文件的共享源库，并执行各种纹理内容处理操作，包括调整大小、格式转换、生成米柏、为 Direct3D 运行时纹理资源进行块压缩以及高度图到法线图的转换。此库使用 Windows 图像组件 (WIC) API。它还包括 .TGA 和 .HDR 读取器和写入器，因为这些图像文件格式常用于纹理内容处理管道，但当前不支持内置的 WIC 编解码器。

此代码设计用于与 Visual Studio 2019 (16.11)、Visual Studio 2022、Windows v12 或更高版本的 clang 或 MinGW 12.2 一起构建。对于 Visual Studio，需要使用 Windows 10 2020 年 5 月更新 SDK（19041）或更高版本。它也可以使用 GCC 11 或更高版本为 Windows 子系统 for Linux 构建。

这些组件设计为无需依赖旧 DirectX SDK 中的任何内容即可工作。有关详细信息，请参阅 DirectX SDK 在哪里？。

目录结构

  • DirectXTex\

    • 此目录包含 DirectXTex 库。它包括功能齐全的 DDS 读取器和写入器，包括旧格式转换、TGA 读取器和写入器、HDR 读取器和写入器、基于 WIC 的位图读取器和写入器（BMP、JPEG、PNG、TIFF 和 HD Photo），以及各种纹理处理函数。主要针对工具使用。

这里的大多数头文件仅用于库的内部实现（如BC.h、BCDirectCompute.h、DDS.h、DirectXTexP.h等）。只有DirectXTex.h和DirectXTex.inl被视为库的“公共”头文件。

  • 辅助\

    • 包含DirectXTex库的可选源文件，例如使用OpenEXR库的适配器加载函数、Xbox纹理平铺扩展等。

  • Texconv\

    • 这个DirectXTex示例是实现DirectX SDK中的texconv命令行纹理工具，它使用DirectXTex而不是D3DX。

      它支持与Texture Conversion Tool Extended（texconvex.exe）旧版DirectX SDK实用程序相同的参数。主要区别是-10和-11参数不适用，并且过滤器名称（POINT、LINEAR、CUBIC、FANT或BOX、TRIANGLE、*_DITHER、*_DITHER_DIFFUSION）。这还包括对JPEG XR（HD Photo）位图格式的支持。

  • Texassemble\

    • 这个DirectXTex示例是一个命令行实用程序，用于从一组单个输入图像文件创建立方图、体积图或纹理数组。

  • Texdiag\

    • 这个DirectXTex示例是一个命令行实用程序，用于分析图像内容，主要用于调试目的。

  • DDSView\

    • 这个DirectXTex示例是一个简单的基于Direct3D 11的DDS文件查看器。对于数组纹理或体积图，使用键盘上的"<"和">"键可以显示DDS中包含的不同图像。使用"1"到"0"键也可以跳转到特定的图像索引。

  • DDSTextureLoader\

    • 这包含了一个简化的旧版DirectX SDK示例DDSWithoutD3DX11纹理加载代码，用于简单的轻量级运行时DDS加载器。有Direct3D 9、Direct3D 11和Direct3D 12版本。这不会执行运行时像素数据转换。这对于运行时使用非常理想，并支持Direct3D纹理资源的完整集合（1D、2D、体积图、立方图、Mipmap级别、纹理数组、BC格式等）。

  • ScreenGrab\

    • 这包含Direct3D 9、Direct3D 11和Direct3D 12的纹理编写模块，主要用于创建屏幕截图。图像以DDS或使用WIC的图像文件格式写入。

  • WICTextureLoader\

    • 这包含一个Direct3D 9、Direct3D 11和Direct3D 12的2D纹理加载器，它使用WIC加载位图（BMP、JPEG、PNG、HD Photo或其他WIC支持的文件容器），根据当前功能级别（或显式参数）进行必要的调整大小，根据需要转换为DXGI_FORMAT，然后创建2D纹理。请注意，这不支持1D纹理、体积纹理、立方图或纹理数组。建议使用DDSTextureLoader来创建最大性能和图像质量的“预先烹饪”纹理，但此加载器可以用于在运行时从标准图像文件创建简单的2D纹理。

DDSTextureLoader11、ScreenGrab11和WICTextureLoader11是DirectX Tool Kit for DX11中提供的相同模块的“独立”版本。

DDSTextureLoader12、ScreenGrab12 和 WICTextureLoader12 是与 DirectX Tool Kit for DX12 中提供的相同模块的“独立”版本。

  • build\

    • 包含构建管道的 YAML 文件，以及一些杂项构建文件和脚本。

文档

文档可在 GitHub wiki 上找到。

注意事项

本包的所有内容和源代码均受 MIT 许可证 的约束。

有关 DirectXTex 的最新版本、错误报告等，请访问 GitHub 上的项目网站。

版本说明

  • 从 2022 年 7 月版本开始，CreateTextureEx 和 CreateShaderResourceViewEx 函数的 bool forceSRGB 参数现在是一个 CREATETEX_FLAGS 类型枚举位掩码标志参数。这可能会对客户端代码产生 破坏性变化 的影响。将 true 替换为 CREATETEX_FORCE_SRGB，将 false 替换为 CREATETEX_DEFAULT。

  • 从 2020 年 6 月版本开始，该库根据 C++ 标准第 17.5.2.1.3 位掩码类型 部分的建议使用类型枚举位掩码标志。这与 Direct3D 12 使用 DEFINE_ENUM_FLAG_OPERATORS 宏的做法一致。这可能会对客户端代码产生 破坏性变化 的影响。

    • 您不能将 0 文本作为标志值传递。相反，您必须使用适当的默认枚举值：CP_FLAGS_NONE、DDS_FLAGS_NONE、WIC_FLAGS_NONE、TEX_FR_ROTATE0、TEX_FILTER_DEFAULT、TEX_FILTER_DEFAULT、TEX_FILTER_DEFAULT、CNMAP_DEFAULT 或 CNMAP_DEFAULT。

    • 如果要在本地使用位掩码操作构建标志值，请使用枚举类型而不是 DWORD。例如，DDS_FLAGS flags = DDS_FLAGS_NONE; if (...) flags |= DDS_FLAGS_EXPAND_LUMINANCE;

    • 在某些标志重叠的情况下，您可以使用 | 来组合相关类型：TEX_FILTER_FLAGS 过滤模式与 WIC_FLAGS 结合，TEX_FILTER_FLAGS sRGB 标志与 TEX_PMALPHA_FLAGS 或 TEX_COMPRESS_FLAGS 结合。没有定义其他位运算符。例如，WIC_FLAGS wicFlags = WIC_FLAGS_NONE | TEX_FILTER_CUBIC;

  • 除非系统已安装第三方 WIC 编解码器，否则 WICTextureLoader 无法加载 .TGA 或 .HDR 文件。您必须使用 DirectXTex 库来支持 TGA/HDR 文件格式，而无需依赖附加的 WIC 编解码器。

  • UWP 项目和 Win10 经典桌面项目包括 ARM64 平台的配置。构建这些项目需要安装 ARM64 工具集。

  • 在为ARM64平台使用clang/LLVM时，需要Windows 11 SDK（22000）或更高版本。

  • 脚本CompileShaders.cmd必须使用Windows风格的（CRLF）行结束符。如果将其更改为Linux风格的（LF）行结束符，则可能导致无法构建所有必需的着色器。

支持

如有疑问，请考虑使用带有directxtk标签的Stack Overflow，或dx12-developers或dx9-dx11-developers频道的DirectX Discord服务器。

对于错误报告和功能请求，请使用GitHub上此项目的问题。

贡献

此项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权并且实际上确实授予我们使用您贡献的权利。有关详细信息，请访问https://cla.opensource.microsoft.com。

提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并适当装饰PR（例如，状态检查，注释）。只需遵循机器人提供的说明即可。您只需要在所有使用我们的CLA的仓库中这样做一次。

行为准则

此项目采用了Microsoft开源代码行为准则。有关更多信息，请参阅行为准则常见问题解答或通过[email protected]与任何额外的问题或评论联系。

商标

此项目可能包含项目、产品或服务的商标或徽标。Microsoft商标或徽标的授权使用必须遵循并遵循Microsoft的商标和品牌指南。在此项目的修改版本中使用Microsoft商标或徽标不得引起混淆或暗示Microsoft的赞助。任何使用第三方商标或徽标的行为均受这些第三方政策的约束。

鸣谢

DirectXTex库是Chuck Walbourn的作品，由Matt Lee、Xin Huang、Craig Peeper以及多年来开发D3DX实用库的众多其他Microsoft工程师做出贡献。

感谢Paul Penson在实现MemoryStreamOnBlob方面的帮助。

感谢Andrew Farrier和Scott Matloff在代码审查方面的持续帮助。

感谢Park DongHa贡献JPEG/PNG辅助函数。

依赖项