贡献

欢迎贡献！此存储库欢迎以下类型的示例

  • Vulkan API 使用

  • Vulkan 扩展使用

  • Vulkan 最佳实践和/或性能指导

  • 独特的 Vulkan 用例或项目

如果您有像以上任何一点那样演示 Vulkan 的示例，请考虑为 Vulkan 示例存储库做出贡献。

在开始之前，请查看以下要求和指南。遵循这些指南可以帮助确保您的贡献最终获得审阅者的批准，最重要的是成为 Vulkan 示例存储库的宝贵补充。

质量检查

Vulkan 示例有一系列质量检查，以确保我们在所有示例中保持一致的质量和风格。其中包括格式化、代码检查和版权检查。

为了使贡献者的过程尽可能轻松，我们使用 pre-commit。要安装 pre-commit 和此存储库的钩子，请运行以下命令

pip install pre-commit
pre-commit install

如果您不想使用 pre-commit，可以使用以下命令手动运行检查

# Run clang-format
./scripts/clang_format.py main
# Run copyright checks
./scripts/copyright.py main --fix

未来可能会添加其他工具。如果您有任何建议或反馈，请在存储库上打开一个 issue。

存储库结构

文件夹 描述

/samples/api/

包含演示 API 使用的示例的文件夹

/samples/extensions/

包含演示 API 扩展使用的示例的文件夹

/samples/performance/

包含演示性能最佳实践的示例的文件夹

/shaders/

包含示例使用的着色器的文件夹

/assets/

带有模型、场景和字体的 GIT 子模块

/third_party/

包含常用外部库的文件夹

创建示例

按照本指南自动创建虚拟示例和关联的构建文件。这个新示例将基于包装器类的框架，该框架提供了一个优化且方便的系统来管理 Vulkan 对象。

通用要求

  • 示例文件夹和描述

    • 每个示例必须放置在 /samples/api/、/samples/performance/ 或 /samples/extensions/ 中的单独子文件夹中。

    • 每个示例都应使用简短的文件夹名称，使用 snake_case，以最能描述该示例。

    • 每个示例都必须有良好的文档，包括 README.adoc 文件，理想情况下，在示例文件夹的根目录中包含一个教程文件，其中包含对示例的详细说明，并在适用时提供“最佳实践”摘要。教程中使用的任何图像都应存储在示例文件夹的 images/ 子文件夹中。

  • 供应商示例

    • 默认情况下，假定每个示例都在所有支持的平台上运行。否则，请在示例的文档中注明任何平台限制。

    • 如果示例是特定于供应商的（即，仅在某些硬件上运行），请在示例的 CMakeLists.txt 中添加带有供应商名称的 TAG。

  • 框架

    • 尽可能利用可用的框架。

    • 不要引入任何新的包装器代码。如果所需内容尚不是框架的一部分，请扩展它而不是引入任何新内容。

    • 或者，您可以使用原始 Vulkan API 调用。

  • 代码和资源

    • 鼓励使用构建复杂度最低的单源文件示例，以简化移植到不同平台的过程。

    • 强烈建议使用最高警告级别和将警告视为错误 (-Wall -Wextra -Werror 或 /Wall /WX) 编译示例。

    • 着色器保存在 /shaders/ 文件夹中，在 /samples/api/、/samples/performance/ 或 /samples/extensions/ 中与示例子文件夹同名的单独子文件夹中。

    • 资源应保存在 vulkan-samples-assets 中。

  • 许可证

    • 示例的许可协议在根目录下的 LICENSE 文件中。

    • 当前的贡献者许可协议（CLA）只允许示例以 Apache 2.0 许可协议发布。

    • 每个源代码文件都必须在文件顶部包含版权声明和许可协议，如下所述。

    • 资源必须有其自己的许可协议。

  • 第三方库

    • 示例不得依赖于第三方库的单独安装。

    • 任何使用的第三方库都必须在兼容的开源许可下可用，例如 MIT 或 Apache 2.0。

    • 任何使用的第三方库都必须作为子模块包含在 /third_party/ 文件夹中。

版权声明和许可模板

要将 Apache 2.0 许可应用于您的工作，请附加以下样板声明，并将方括号“[]”括起来的字段替换为您自己的版权年份或年份的标识信息。请勿包含方括号！文本应包含在文件格式的适当注释语法中。我们还建议在与版权声明相同的“打印页面”上包含文件名或类名以及目的描述，以便在第三方存档中更容易识别。当为现有文件贡献代码时，您可以在现有版权年份行下添加新的版权年份行。

Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

代码风格

建议使用通用的代码风格，例如 Google C++ 风格指南 中描述的代码风格。示例必须一致地应用单一代码风格。

此存储库中包含一个 .clang-format 文件，请使用 clang-format -style=file 来验证代码风格。建议使用 clang-format-15，它与我们 .clang-format 文件中的风格兼容。

贡献流程

  1. Fork KhronosGroup/Vulkan-Samples 存储库。

  2. 将贡献添加到新的 Fork 中（请参阅 创建示例）。

  3. 确保满足上述要求。

  4. 确保示例符合 Vulkan 规范。

  5. 确保示例代码可以在 Windows、Linux、macOS 和 Android 上构建和运行。如果您无法在所有这些目标平台上进行验证，请在示例的 README 中注明平台限制。

  6. 使用从源代码构建或从最新可用 Vulkan SDK 获取的最新版本的 Vulkan 验证层验证示例。

  7. 通过 github 提交贡献的拉取请求，包括使用 CLA-Assistant 电子签署存储库的 Khronos 贡献者许可协议（CLA）。

代码审查

所有提交，包括项目成员的提交，都须经过 Khronos 成员的代码审查。GitHub 拉取请求用于促进审查过程，请提交准备好审查的贡献的拉取请求。有关审查过程的更多信息，请访问此链接。

维护

一旦新的示例被合并，作者应尽可能维护它。否则，他们应确定一位已同意承担责任的新维护者。