init
This commit is contained in:
@@ -0,0 +1,170 @@
|
||||
////
|
||||
- Copyright (c) 2019-2024, Arm Limited and Contributors
|
||||
-
|
||||
- SPDX-License-Identifier: Apache-2.0
|
||||
-
|
||||
- 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
|
||||
-
|
||||
- http://www.apache.org/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.
|
||||
-
|
||||
////
|
||||
= Contributing
|
||||
:pp: {plus}{plus}
|
||||
|
||||
Contributions are encouraged!
|
||||
This repository welcomes samples of the following types:
|
||||
|
||||
* Vulkan API Usage
|
||||
* Vulkan Extension Usage
|
||||
* Vulkan Best Practices and/or Performance Guidance
|
||||
* Unique Vulkan use case or project
|
||||
|
||||
If you have a sample that demonstrates Vulkan like any of the above points, then consider contributing to the Vulkan samples repository.
|
||||
|
||||
Before you start, check out the requirements and guidelines below.
|
||||
Following these guidelines can help ensure that your contribution ends up being approved by reviewers and most importantly becomes a valuable addition to the Vulkan Samples repository.
|
||||
|
||||
== Quality Checks
|
||||
|
||||
Vulkan Samples has a range of quality checks to ensure that we maintain a consistent quality and style across all samples. These include formatting, linting and copyright checks.
|
||||
|
||||
To make this process as painless for contributors as possible we use xref:https://pre-commit.com/[pre-commit]. To install pre-commit and the hooks for this repository, run the following commands:
|
||||
|
||||
----
|
||||
pip install pre-commit
|
||||
pre-commit install
|
||||
----
|
||||
|
||||
If you prefer not to use pre-commit, you can run the checks manually using the following commands:
|
||||
|
||||
----
|
||||
# Run clang-format
|
||||
./scripts/clang_format.py main
|
||||
# Run copyright checks
|
||||
./scripts/copyright.py main --fix
|
||||
----
|
||||
|
||||
Future tooling may be added in the future. If you have any suggestions or feedback, please open an issue on the repository.
|
||||
|
||||
== Repository Structure
|
||||
|
||||
|===
|
||||
| folder | description
|
||||
|
||||
| `/samples/api/`
|
||||
| folder containing samples that demonstrate API usage
|
||||
|
||||
| `/samples/extensions/`
|
||||
| folder containing samples that demonstrate API Extensions usage
|
||||
|
||||
| `/samples/performance/`
|
||||
| folder containing samples that demonstrate performance best-practices
|
||||
|
||||
| `/shaders/`
|
||||
| folder containing shaders used by the samples
|
||||
|
||||
| `/assets/`
|
||||
| GIT sub-module with models, scenes and fonts
|
||||
|
||||
| `/third_party/`
|
||||
| folder with commonly used external libraries
|
||||
|===
|
||||
|
||||
== Creating a sample
|
||||
|
||||
Follow xref:scripts/README.adoc[this guide] to create a dummy sample and associated build files automatically.
|
||||
This new sample will be based on the framework of wrapper classes that provide an optimized and convenient system to manage Vulkan objects.
|
||||
|
||||
== General Requirements
|
||||
|
||||
* Sample folder and description:
|
||||
** Each sample must be placed in a separate sub-folder within `/samples/api/`, `/samples/performance/` or `/samples/extensions/`.
|
||||
** Each sample should use a short folder name, using snake_case, that best describes the sample.
|
||||
** Each sample must be well-documented, include a README.adoc file and ideally include a tutorial file in the root of the sample's folder with a detailed explanation of the sample and a 'best-practice' summary if applicable.
|
||||
Any images used in the tutorial should be stored in an images/ sub-folder in the sample folder.
|
||||
* Vendor samples:
|
||||
** By default each sample is assumed to run on all supported platforms.
|
||||
Otherwise note any platform restrictions in the sample's documentation.
|
||||
** If a sample is vendor-specific (i.e.
|
||||
only runs on certain hardware) please add a `TAG` with the vendor's name in the sample's `CMakeLists.txt`.
|
||||
* Framework:
|
||||
** Make use of the available framework whenever possible.
|
||||
** Do not introduce any new wrapper code.
|
||||
If what you need is not already a part of the framework, please extend it rather than introduce anything new.
|
||||
** Alternatively you may use raw Vulkan API calls.
|
||||
* Code and assets:
|
||||
** Single source file samples with minimal build complexity are encouraged to make porting to different platforms easier.
|
||||
** Compiling the sample with the highest warning level and warnings-as-errors (-Wall -Wextra -Werror, or /Wall /WX) is highly recommended.
|
||||
** Shaders are saved in the `/shaders/` folder, in a separate sub-folder with the same name as the sample sub-folder in `/samples/api/`, `/samples/performance/` or `/samples/extensions/`.
|
||||
** Assets should be saved in https://github.com/KhronosGroup/Vulkan-Samples-Assets[vulkan-samples-assets].
|
||||
* License:
|
||||
** Samples are licensed under the link:LICENSE[LICENSE] file in the root folder.
|
||||
** The current Contributor License Agreement (CLA) only allows samples to be licensed under the Apache 2.0 license.
|
||||
** Every source code file must have a Copyright notice and license at the top of the file as described below.
|
||||
** Assets must have their own license.
|
||||
* Third party libraries:
|
||||
** A sample may not depend on a separate installation of a third party library.
|
||||
** Any third party library that is used needs to be available under a compatible open source license i.e.
|
||||
MIT or Apache 2.0.
|
||||
** Any third party library that is used must be included as a sub-module in the `/third_party/` folder.
|
||||
|
||||
== Copyright Notice and License Template
|
||||
|
||||
To apply the Apache 2.0 License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information for the copyright year or years.
|
||||
_Don't include the brackets!_ The text should be enclosed in the appropriate comment syntax for the file format.
|
||||
We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
|
||||
When contributing to an existing file you may add a new copyright year line under the existing ones.
|
||||
|
||||
....
|
||||
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
|
||||
|
||||
http://www.apache.org/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.
|
||||
....
|
||||
|
||||
== Code Style
|
||||
|
||||
A common code style like, for instance, the one described by the https://google.github.io/styleguide/cppguide.html[Google C{pp} Style Guide] is recommended.
|
||||
A sample must consistently apply a single code style.
|
||||
|
||||
A `.clang-format` file is included with this repository, please use `clang-format -style=file` to verify the code style.
|
||||
It is recommended to use `clang-format-15`, which is compatible with the styles in our `.clang-format` file.
|
||||
|
||||
== Procedure for Contributing
|
||||
|
||||
. Fork the KhronosGroup/Vulkan-Samples repository.
|
||||
. Add the contribution to the new fork (see <<creating-a-sample,Creating a sample>>).
|
||||
. Make sure the above requirements are met.
|
||||
. Make sure the sample is in compliance with the Vulkan specification.
|
||||
. Make sure the sample code builds and runs on Windows, Linux, macOS and Android.
|
||||
If you cannot verify on all these target platforms, please note platform restrictions in the sample's README.
|
||||
. Verify the sample against a recent version of the Vulkan validation layers, either built from source or from the most recent available Vulkan SDK.
|
||||
. Submit a pull request via github for the contribution, including electronically signing the Khronos Contributor License Agreement (CLA) for the repository using CLA-Assistant.
|
||||
|
||||
== Code Reviews
|
||||
|
||||
All submissions, including those by project members, are subject to a code review by the Khronos Membership.
|
||||
GitHub pull requests are used to facilitate the review process, please submit a pull request with your contribution ready for review.
|
||||
For more information on the review process visit this https://github.com/KhronosGroup/Vulkan-Samples/wiki/Review-Process[link].
|
||||
|
||||
== Maintenance
|
||||
|
||||
Once a new sample is merged the author is expected to maintain it whenever possible.
|
||||
Otherwise they should identify a new maintainer that has agreed to take on the responsibility.
|
||||
Reference in New Issue
Block a user