mirror of
https://github.com/Rust-GPU/rust-gpu.git
synced 2026-06-04 16:49:51 +09:00
Initial changes for the handoff from Embark to the community. (#1)
* Change URLs * Switch away from paid runners. * Drop copyright from MIT license. Similar to the Rust project. See the git history of https://github.com/rust-lang/rust/blob/master/LICENSE-MIT
This commit is contained in:
Christian Legnitto
committed by
GitHub
GitHub
parent
54f6978c25
commit
e54dd75fb7
4
.github/CODEOWNERS
vendored
4
.github/CODEOWNERS
vendored
@@ -1,3 +1 @@
|
||||
* @eddyb
|
||||
|
||||
/examples/ @fu5ha @VZout
|
||||
* @eddyb @LegNeato @fornwall
|
||||
|
||||
9
.github/ISSUE_TEMPLATE/enhancement.md
vendored
9
.github/ISSUE_TEMPLATE/enhancement.md
vendored
@@ -6,14 +6,13 @@ labels: "t: enhancement"
|
||||
---
|
||||
|
||||
<!--
|
||||
Thank you for your interest in the `rust-gpu` project! This template is for
|
||||
proposing a minor improvement, such as addig a new method, or improving
|
||||
documentation. Please try to provide a short high level overview of what you would
|
||||
Thank you for your interest in the `rust-gpu` project!
|
||||
Please try to provide a short high level overview of what you would
|
||||
like you to add. Also be sure to check the existing and `wontfix` issues to see
|
||||
if it's already been proposed before posting.
|
||||
|
||||
Existing Issues: https://github.com/EmbarkStudios/rust-gpu/issues?q=is%3Aopen+is%3Aissue+label%3A%22t%3A+enhancement%22
|
||||
Closed Issues: https://github.com/EmbarkStudios/rust-gpu/labels/s%3A%20wontfix
|
||||
Existing Issues: https://github.com/rust-gpu/rust-gpu/issues?q=is%3Aopen+is%3Aissue+label%3A%22t%3A+enhancement%22
|
||||
Closed Issues: https://github.com/rust-gpu/rust-gpu/labels/s%3A%20wontfix
|
||||
|
||||
-->
|
||||
|
||||
|
||||
20
.github/ISSUE_TEMPLATE/mcp.md
vendored
20
.github/ISSUE_TEMPLATE/mcp.md
vendored
@@ -1,20 +0,0 @@
|
||||
---
|
||||
name: Major change proposal (MCP)
|
||||
about: Propose a major change or feature to the project.
|
||||
title: "(My major change proposal)"
|
||||
labels: "mcp: proposed"
|
||||
---
|
||||
|
||||
<!--
|
||||
Thank you for your interest in proposing a new feature for the `rust-gpu`
|
||||
project. Please try to provide a short high level overview of what you would
|
||||
like you to add. Also be sure to check the existing and closed MCPs to see
|
||||
if it's already been proposed before posting.
|
||||
|
||||
Existing Proposals: https://github.com/EmbarkStudios/rust-gpu/issues?q=is%3Aopen+is%3Aissue+label%3A%22mcp%3A+proposed%22
|
||||
Closed Proposals: https://github.com/EmbarkStudios/rust-gpu/issues?q=is%3Aclosed+is%3Aissue+label%3A%22mcp%3A+proposed%22
|
||||
|
||||
-->
|
||||
|
||||
# Proposal
|
||||
|
||||
17
.github/ISSUE_TEMPLATE/meeting.md
vendored
17
.github/ISSUE_TEMPLATE/meeting.md
vendored
@@ -1,17 +0,0 @@
|
||||
---
|
||||
name: Meeting
|
||||
about: An issue thread for a meeting
|
||||
title: "Meeting YYYY-MM-DD"
|
||||
labels: "t: meeting"
|
||||
---
|
||||
### Where & When
|
||||
- `#rust-gpu` on the [Embark Discord](https://discord.gg/8TW9nfF).
|
||||
- Time: 17:00 CET
|
||||
- [Previous Meeting](link_to_previous_meeting)
|
||||
|
||||
### Agenda
|
||||
|
||||
- Project updates
|
||||
- [Review & discuss any open MCPs](https://github.com/EmbarkStudios/rust-gpu/labels/mcp%3A%20proposed)
|
||||
|
||||
Feel free to propose additional items in this thread.
|
||||
8
.github/workflows/ci.yaml
vendored
8
.github/workflows/ci.yaml
vendored
@@ -17,13 +17,13 @@ jobs:
|
||||
strategy:
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-20.04-16core
|
||||
- os: ubuntu-20.04
|
||||
target: x86_64-unknown-linux-gnu
|
||||
- os: windows-2022-16core
|
||||
- os: windows-2022
|
||||
target: x86_64-pc-windows-msvc
|
||||
- os: macOS-latest-xl
|
||||
- os: macOS-latest
|
||||
target: x86_64-apple-darwin
|
||||
- os: ubuntu-20.04-16core
|
||||
- os: ubuntu-20.04
|
||||
target: aarch64-linux-android
|
||||
host: x86_64-unknown-linux-gnu
|
||||
runs-on: ${{ matrix.os }}
|
||||
|
||||
@@ -130,7 +130,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- [PR#998](https://github.com/EmbarkStudios/rust-gpu/pull/998) added `extra_arg()` SpirvBuilder API to be able to set codegen args otherwise not supported by the API (for example, to set `--spirv-passes`)
|
||||
|
||||
### Changed 🛠
|
||||
- [PR#999](https://github.com/EmbarkStudios/rust-gpu/pull/999) made the [`SPIR-🇹` shader IR framework](https://github.com/EmbarkStudios/spirt) the default (you can opt out via `RUSTGPU_CODEGEN_ARGS=--no-spirt`)
|
||||
- [PR#999](https://github.com/EmbarkStudios/rust-gpu/pull/999) made the [`SPIR-🇹` shader IR framework](https://github.com/rust-gpu/spirt) the default (you can opt out via `RUSTGPU_CODEGEN_ARGS=--no-spirt`)
|
||||
- [PR#992](https://github.com/EmbarkStudios/rust-gpu/pull/992) renamed `rust-toolchain` to `rust-toolchain.toml`
|
||||
- [PR#991](https://github.com/EmbarkStudios/rust-gpu/pull/991) updated toolchain to `nightly-2023-01-21`
|
||||
- [PR#990](https://github.com/EmbarkStudios/rust-gpu/pull/990) removed return type inference from `Image` API and made `glam` usage mandatory
|
||||
@@ -153,7 +153,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
||||
- `RUSTGPU_RUSTFLAGS="..."` for shader `RUSTFLAGS="..."`
|
||||
- `RUSTGPU_CODEGEN_ARGS="..."` for shader "codegen args" (i.e. `RUSTFLAGS=-Cllvm-args="..."`)
|
||||
(check out [the "codegen args" docs](docs/src/codegen-args.md), or run with `RUSTGPU_CODEGEN_ARGS=--help` to see the full list of options)
|
||||
- [PR#940](https://github.com/EmbarkStudios/rust-gpu/pull/940) integrated the experimental [`SPIR-🇹` shader IR framework](https://github.com/EmbarkStudios/spirt) into the linker
|
||||
- [PR#940](https://github.com/EmbarkStudios/rust-gpu/pull/940) integrated the experimental [`SPIR-🇹` shader IR framework](https://github.com/rust-gpu/spirt) into the linker
|
||||
(opt-in via `RUSTGPU_CODEGEN_ARGS=--spirt`, see also [the `--spirt` docs](docs/src/codegen-args.md#--spirt), for more details)
|
||||
|
||||
### Changed 🛠️
|
||||
|
||||
@@ -6,8 +6,8 @@ We as members, contributors, and leaders pledge to make participation in our
|
||||
community a harassment-free experience for everyone, regardless of age, body
|
||||
size, visible or invisible disability, ethnicity, sex characteristics, gender
|
||||
identity and expression, level of experience, education, socio-economic status,
|
||||
nationality, personal appearance, race, religion, or sexual identity
|
||||
and orientation.
|
||||
nationality, personal appearance, race, caste, color, religion, or sexual
|
||||
identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming,
|
||||
diverse, inclusive, and healthy community.
|
||||
@@ -22,17 +22,17 @@ community include:
|
||||
* Giving and gracefully accepting constructive feedback
|
||||
* Accepting responsibility and apologizing to those affected by our mistakes,
|
||||
and learning from the experience
|
||||
* Focusing on what is best not just for us as individuals, but for the
|
||||
overall community
|
||||
* Focusing on what is best not just for us as individuals, but for the overall
|
||||
community
|
||||
|
||||
Examples of unacceptable behavior include:
|
||||
|
||||
* The use of sexualized language or imagery, and sexual attention or
|
||||
advances of any kind
|
||||
* The use of sexualized language or imagery, and sexual attention or advances of
|
||||
any kind
|
||||
* Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
* Public or private harassment
|
||||
* Publishing others' private information, such as a physical or email
|
||||
address, without their explicit permission
|
||||
* Publishing others' private information, such as a physical or email address,
|
||||
without their explicit permission
|
||||
* Other conduct which could reasonably be considered inappropriate in a
|
||||
professional setting
|
||||
|
||||
@@ -52,15 +52,14 @@ decisions when appropriate.
|
||||
|
||||
This Code of Conduct applies within all community spaces, and also applies when
|
||||
an individual is officially representing the community in public spaces.
|
||||
Examples of representing our community include using an official e-mail address,
|
||||
Examples of representing our community include using an official email address,
|
||||
posting via an official social media account, or acting as an appointed
|
||||
representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement at
|
||||
opensource@embark-studios.com.
|
||||
reported to the community leaders.
|
||||
All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
@@ -82,15 +81,15 @@ behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community Impact**: A violation through a single incident or series
|
||||
of actions.
|
||||
**Community Impact**: A violation through a single incident or series of
|
||||
actions.
|
||||
|
||||
**Consequence**: A warning with consequences for continued behavior. No
|
||||
interaction with the people involved, including unsolicited interaction with
|
||||
those enforcing the Code of Conduct, for a specified period of time. This
|
||||
includes avoiding interactions in community spaces as well as external channels
|
||||
like social media. Violating these terms may lead to a temporary or
|
||||
permanent ban.
|
||||
like social media. Violating these terms may lead to a temporary or permanent
|
||||
ban.
|
||||
|
||||
### 3. Temporary Ban
|
||||
|
||||
@@ -106,27 +105,27 @@ Violating these terms may lead to a permanent ban.
|
||||
### 4. Permanent Ban
|
||||
|
||||
**Community Impact**: Demonstrating a pattern of violation of community
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
standards, including sustained inappropriate behavior, harassment of an
|
||||
individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence**: A permanent ban from any sort of public interaction within
|
||||
the community.
|
||||
**Consequence**: A permanent ban from any sort of public interaction within the
|
||||
community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
|
||||
version 2.0, available at
|
||||
[https://www.contributor-covenant.org/version/2/0/code_of_conduct.html][v2.0].
|
||||
version 2.1, available at
|
||||
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
|
||||
|
||||
Community Impact Guidelines were inspired by
|
||||
Community Impact Guidelines were inspired by
|
||||
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at
|
||||
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available
|
||||
at [https://www.contributor-covenant.org/translations][translations].
|
||||
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
|
||||
[https://www.contributor-covenant.org/translations][translations].
|
||||
|
||||
[homepage]: https://www.contributor-covenant.org
|
||||
[v2.0]: https://www.contributor-covenant.org/version/2/0/code_of_conduct.html
|
||||
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
|
||||
[Mozilla CoC]: https://github.com/mozilla/diversity
|
||||
[FAQ]: https://www.contributor-covenant.org/faq
|
||||
[translations]: https://www.contributor-covenant.org/translations
|
||||
|
||||
@@ -1,12 +1,13 @@
|
||||
# Embark Contributor Guidelines
|
||||
# Contributor Guidelines
|
||||
|
||||
Welcome! This project is created by the team at [Embark Studios](https://embark.games). We're glad you're interested in contributing! We welcome contributions from people of all backgrounds who are interested in making great software with us.
|
||||
Welcome! We're glad you're interested in contributing! We welcome contributions from people of all backgrounds who are interested in making great software with us.
|
||||
|
||||
At Embark, we aspire to empower everyone to create interactive experiences. To do this, we're exploring and pushing the boundaries of new technologies, and sharing our learnings with the open source community.
|
||||
## How to get help
|
||||
|
||||
If you have ideas for collaboration, email us at opensource@embark-studios.com.
|
||||
For questions, clarifications, and general help please first search [Github
|
||||
discussions](discussions) and then ask your question if you can't find the answer.
|
||||
|
||||
We're also hiring full-time engineers to work with us in Stockholm! Check out our current job postings [here](https://www.embark-studios.com/jobs).
|
||||
[discussions]: https://github.com/rust-gpu/rust-gpu/discussions
|
||||
|
||||
## Issues
|
||||
|
||||
@@ -20,21 +21,10 @@ Feature requests will be tagged as `enhancement` and their status will be update
|
||||
|
||||
When reporting a bug or unexpected behaviour in a project, make sure your issue describes steps to reproduce the behaviour, including the platform you were using, what steps you took, and any error messages.
|
||||
|
||||
Reproducible bugs will be tagged as `bug` and their status will be updated in the comments of the issue.
|
||||
|
||||
### Wontfix
|
||||
|
||||
Issues will be closed and tagged as `wontfix` if we decide that we do not wish to implement it, usually due to being misaligned with the project vision or out of scope. We will comment on the issue with more detailed reasoning.
|
||||
|
||||
### Labels
|
||||
The labels for this repository are divided into the following categories;
|
||||
|
||||
- **`c:` Crate** Issues specific a single crate in the repository.
|
||||
- **`g:` GPU** Issues specific a GPU vendor.
|
||||
- **`p:` Platform** Issues specific a single operating system or platform.
|
||||
- **`s:` Status** The current status of a PR or issue.
|
||||
- **`t:` Type** The general type of the issue. (E.g. `t: bug` for bugs.)
|
||||
|
||||
## Contribution Workflow
|
||||
|
||||
### Open Issues
|
||||
@@ -43,51 +33,7 @@ If you're ready to contribute, start by looking at our open issues tagged as [`h
|
||||
|
||||
You can comment on the issue to let others know you're interested in working on it or to ask questions.
|
||||
|
||||
### Major Change Process
|
||||
Most bug fixes can be implemented directly by opening a PR, however for larger design decisions and major changes to the compiler's architecture, this repository uses a two stage "Major Change Proposal" and "Request For Comments" process. If you're unsure about what's required for a specific change you should always start with [**opening an issue**][open-issue] or asking the team over on the `#rust-gpu` channel in the [Embark Discord][dis].
|
||||
|
||||
[dis]: https://discord.gg/8TW9nfF
|
||||
[open-issue]: https://github.com/EmbarkStudios/rust-gpu/issues/new
|
||||
|
||||
#### Definitions
|
||||
|
||||
##### **Major Change Proposal (MCP)**
|
||||
A proposal to make a significant internal changes or small public facing changes to the compiler. An MCP is opened as an issue on `rust-gpu` the repository. An MCP typically only requires one member's approval. Though if the change is significantly big enough it may require the full team's sign off or require an RFC.
|
||||
|
||||
An MCP should generally be a short (1-2 paragraphs) high level overview of the change you would want to make, the motivation behind the change, and potential solutions. There is a [major change issue template][mcp-template] you can use for convenience.
|
||||
|
||||
[mcp-template]: https://github.com/rust-lang/rust/issues/new?labels=mcp%3A%20proposed&template=mcp.md
|
||||
|
||||
Examples of what would require an MCP:
|
||||
|
||||
- Changing the compiler architecture.
|
||||
- Adding support for an existing Rust language or feature.
|
||||
- Small additions (e.g. new methods) to `spirv-std` types.
|
||||
- Proposing an RFC.
|
||||
|
||||
Examples of what would **not** require an MCP:
|
||||
|
||||
- Updating documentation
|
||||
- Fixing existing bugs
|
||||
- Performance improvements
|
||||
|
||||
##### **Request For Comments (RFC)**
|
||||
A proposal to make significant public facing changes to the compiler or standard library. RFCs are opened as pull requests to the `rust-gpu` repository. RFCs require full sign off by the team, before being approved or implemented. Check out the [RFC `000-template.md` document][rfc-template] for details on the structure.
|
||||
|
||||
[rfc-template]: https://github.com/EmbarkStudios/rust-gpu/blob/main/rfcs/000-template.md
|
||||
|
||||
Examples of what would require an RFC:
|
||||
|
||||
- Major additions to `spirv-std`, such as new APIs, or breaking changes to existing ones.
|
||||
|
||||
#### Life-cycle
|
||||
|
||||
1. You file a [major change proposal][mcp-template] outlining the changes and the motivation for it.
|
||||
2. A member of the team will review the proposal and tag it with the appropriate label.
|
||||
2.1. `mcp: accepted` means that the MCP has been accepted and is ready for a pull request implementing it.
|
||||
2.2. `mcp: rfc needed` means that the MCP has been accepted as something the team would like but needs a full RFC before the implementation.
|
||||
2.3 Closing an issue means that the MCP has rejected.
|
||||
3. If the proposal has been accepted then the implementation can begin.
|
||||
[open-issue]: https://github.com/rust-gpu/rust-gpu/issues/new
|
||||
|
||||
### Pull Request Process
|
||||
|
||||
@@ -97,16 +43,12 @@ Examples of what would require an RFC:
|
||||
4. Open a pull request with a name and description of what you did. You can read more about working with pull requests on GitHub [here](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork).
|
||||
5. A maintainer will review your pull request and may ask you to make changes.
|
||||
|
||||
## Code Guidelines
|
||||
|
||||
### Rust
|
||||
|
||||
You can read about our standards and recommendations for working with Rust [here](https://github.com/EmbarkStudios/rust-ecosystem/blob/master/guidelines.md).
|
||||
|
||||
## Licensing
|
||||
|
||||
Unless otherwise specified, all Embark open source projects are licensed under a dual MIT OR Apache-2.0 license, allowing licensees to chose either at their option. You can read more in each project's respective README.
|
||||
This project is licensed under a dual MIT OR Apache-2.0 license, allowing licensees to chose either at their option.
|
||||
|
||||
## Code of Conduct
|
||||
|
||||
Please note that our projects are released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md) to ensure that they are welcoming places for everyone to contribute. By participating in any Embark open source project, you agree to abide by these terms.
|
||||
Please note that our project has a [Contributor Code of Conduct](CODE_OF_CONDUCT.md) to
|
||||
ensure it is a welcoming place for everyone to contribute. By participating in this
|
||||
project, you agree to abide by these terms.
|
||||
|
||||
@@ -25,10 +25,10 @@ members = [
|
||||
|
||||
[workspace.package]
|
||||
version = "0.9.0"
|
||||
authors = ["Embark <opensource@embark-studios.com>"]
|
||||
authors = ["rust-gpu developers", "Embark <opensource@embark-studios.com>"]
|
||||
edition = "2021"
|
||||
license = "MIT OR Apache-2.0"
|
||||
repository = "https://github.com/EmbarkStudios/rust-gpu"
|
||||
repository = "https://github.com/rust-gpu/rust-gpu"
|
||||
|
||||
[workspace.dependencies]
|
||||
spirv-builder = { path = "./crates/spirv-builder", version = "=0.9.0", default-features = false }
|
||||
|
||||
@@ -1,5 +1,3 @@
|
||||
Copyright (c) 2019 Embark Studios
|
||||
|
||||
Permission is hereby granted, free of charge, to any
|
||||
person obtaining a copy of this software and associated
|
||||
documentation files (the "Software"), to deal in the
|
||||
|
||||
48
README.md
48
README.md
@@ -12,11 +12,9 @@
|
||||
|
||||
**Rust as a first-class language and ecosystem for GPU graphics & compute shaders**
|
||||
|
||||
[](https://embark.dev)
|
||||
[](https://discord.gg/dAuKfZS)
|
||||
[](https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv)
|
||||
[](https://deps.rs/repo/github/EmbarkStudios/rust-gpu)
|
||||
[](https://github.com/EmbarkStudios/rust-gpu/actions/workflows/ci.yaml)
|
||||
[](https://github.com/rust-gpu/rust-gpu/actions/workflows/ci.yaml)
|
||||
[](https://rust-gpu.github.io/rust-gpu/api/rustc_codegen_spirv)
|
||||
|
||||
</div>
|
||||
|
||||
## Current Status 🚧
|
||||
@@ -25,10 +23,8 @@ Note: This project is still heavily in development and is at an early stage.
|
||||
|
||||
Compiling and running simple shaders works, and a significant portion of [the core library](https://doc.rust-lang.org/core/index.html) also compiles.
|
||||
|
||||
However, many things aren't implemented yet. That means that while being technically usable, this project is far from being production-ready. Support for specific features in [Rust][rust-support] and [SPIR-V][spirv-support] are tracked on GitHub.
|
||||
|
||||
[rust-support]: https://github.com/EmbarkStudios/rust-gpu/issues/78
|
||||
[spirv-support]: https://github.com/EmbarkStudios/rust-gpu/issues/383
|
||||
However, many things aren't implemented yet. That means that while being technically
|
||||
usable, this project is not yet production-ready.
|
||||
|
||||
## Example
|
||||
|
||||
@@ -61,36 +57,33 @@ pub fn main(
|
||||
|
||||
See [source](examples/shaders/sky-shader/src/lib.rs) for full details.
|
||||
|
||||
## Our Vision & Community Contributions
|
||||
|
||||
`rust-gpu` is a project that we at Embark think has the potential to change the way GPU programming works in multiple ways. One of the primary things we think it can change is opening the door to leverage the open source culture of sharing and improving each others' code, and our end goal and vision for `rust-gpu` is to develop it very much in tandem with the community. However, the project is still in quite early stages and has a very small team working on it, so in order to be productive and guide the project to where we ultimately want it to go, as of right now, we need to focus on our own primary use cases for our projects at Embark.
|
||||
|
||||
What this means practically is that it is unlikely that we'll be able to accept major changes from community members at this time. If you have a large change you would like to make, please file an issue and/or ask on our Discord in the `#rust-gpu` channel to see if it is something we'll be able to accept *before* working on it, as it is not great to have to turn down stuff that community members have poured their time and effort into. As the project matures, we'll in theory be able to accept more input from the community and move closer and closer to the goals outlined above. Thank you so much for your understanding!
|
||||
|
||||
## Getting started
|
||||
|
||||
Check out [The `rust-gpu` Dev Guide][gpu-guide] for information on how to get started with using it in your projects.
|
||||
|
||||
Experiment with rust-gpu shaders in-browser at [SHADERed][shadered].
|
||||
|
||||
[gpu-guide]: https://embarkstudios.github.io/rust-gpu/book/
|
||||
[gpu-guide]: https://rust-gpu.github.io/rust-gpu/book/
|
||||
[shadered]: https://shadered.org/shaders?language=rust&sort=hot
|
||||
|
||||
## Background
|
||||
|
||||
Historically in games GPU programming has been done through writing either HLSL, or to a lesser extent GLSL. These are simple programming languages that have evolved along with rendering APIs over the years. However, as game engines have evolved, these languages have failed to provide mechanisms for dealing with large codebases, and have generally stayed behind the curve compared to other programming languages.
|
||||
Historically in games GPU programming has been done through writing either HLSL, or to a lesser extent GLSL and WGSL. These are simple programming languages that have evolved along with rendering APIs over the years. However, these languages have failed to provide mechanisms for dealing with large codebases, and have generally stayed behind the curve compared to other programming languages.
|
||||
|
||||
In part this is because it's a niche language for a niche market, and in part this has been because the industry as a whole has sunk quite a lot of time and effort into the status quo. While over-all better alternatives to both languages exist, none of them are in a place to replace HLSL or GLSL. Either because they are vendor locked, or because they don't support the traditional graphics pipeline. Examples of this include CUDA and OpenCL. And while attempts have been made to create language in this space, none of them have gained any notable traction in the gamedev community.
|
||||
In part this is because it's a niche language for a niche market, and in part this has been because the industry as a whole has sunk quite a lot of time and effort into the status quo. While over-all better alternatives to both languages exist, none of them are in a place to replace HLSL or GLSL. Either because they are vendor locked, or because they don't support the traditional graphics pipeline. Examples of this include CUDA and OpenCL. And while attempts have been made to create language in this space, none of them have gained any notable traction.
|
||||
|
||||
Our hope with this project is that we push the industry forward by bringing an existing, low-level, safe, and high performance language to the GPU; namely [Rust](https://rust-lang.org). And with it come some additional benefits that can't be overlooked: a package/module system that's one of the industry's best, built in safety against race-conditions or out of bounds memory access, a wide range of tools and utilities to improve programmer workflows, and many others!
|
||||
|
||||
### Why Embark?
|
||||
### Embark
|
||||
|
||||
At Embark, we've been building our own new game engine from the ground up in Rust. We have previous experience in-house developing the [RLSL](https://github.com/MaikKlein/rlsl) prototype, and we have a team of excellent rendering engineers that are familiar with the problems in current shading languages both from games, game engines and other industries. So, we believe we are uniquely positioned to attempt solving this problem.
|
||||
This project was originally created and supported by the folks at
|
||||
[Embark](https://www.embark-studios.com/). We thank them for their foresight and
|
||||
contributions.
|
||||
|
||||
We want to streamline our own internal development with a single great language, build an open source graphics ecosystem and community, facilitate code-sharing between GPU and CPU, and most importantly: to enable our (future) users, and fellow developers, to more rapidly build great looking and engaging experiences.
|
||||
|
||||
If we do this project right, one wouldn't necessarily need an entire team of rendering engineers to build a good looking game, instead one would simply use a few of the existing open-source crates that provide the graphical effects needed to create the experience you're after. Instead of sharing and copy'n'pasting snippets of TAA code on forum posts, one could simply find and use the right crates from [crates.io](https://crates.io).
|
||||
Embark wanted to streamline their internal development with a single great language,
|
||||
build an open source graphics ecosystem and community, facilitate code-sharing between
|
||||
GPU and CPU, and most importantly: to enable their (future) users, and fellow
|
||||
developers, to more rapidly build great looking and engaging experiences.
|
||||
|
||||
## Project scope
|
||||
|
||||
@@ -98,20 +91,14 @@ The scope of this overall project is quite broad, but is in multiple stages
|
||||
|
||||
- `rustc` compiler backend to generate [SPIR-V], plugging in via `-Z codegen-backend`.
|
||||
- This is the same mechanism that [rustc_codegen_cranelift](https://github.com/bjorn3/rustc_codegen_cranelift) and [rustc_codegen_gcc](https://github.com/antoyo/rustc_codegen_gcc) use.
|
||||
- Currently only [SPIR-V] support is planned, [Vulkan](https://en.wikipedia.org/wiki/Vulkan_(API))'s open compiler target
|
||||
- Currently only [SPIR-V] support is planned, [Vulkan](<https://en.wikipedia.org/wiki/Vulkan_(API)>)'s open compiler target
|
||||
- Possible a future version could support [DXIL](https://github.com/microsoft/DirectXShaderCompiler/blob/master/docs/DXIL.rst) (the target for DirectX) or [WGSL](https://github.com/gpuweb/gpuweb/tree/main/wgsl) (the WebGPU shading language that's bijective with SPIR-V)
|
||||
- Focus on Vulkan graphics shaders first, then after Vulkan compute shaders
|
||||
- [Cargo](https://github.com/rust-lang/cargo/) and [crates.io](https://crates.io) support to develop and publish SPIR-V crates
|
||||
- High-level render graph to take advantage of this, make it easy for users to develop and use rendering effects.
|
||||
|
||||
## Process
|
||||
|
||||
We use this repo as a monorepo for everything related to the project: crates, tools, shaders, examples, tests, and design documents. This way, we can use issues and PRs covering everything in the same place, cross-reference stuff within the repo, as well as with other GitHub repos such as [rspirv](https://github.com/gfx-rs/rspirv) and [Rust](https://github.com/rust-lang/rust) itself.
|
||||
|
||||
We meet weekly over a Discord call to discuss design and triage issues. Each meeting has an [issue](https://github.com/EmbarkStudios/rust-gpu/labels/t%3A%20meeting) with agenda, links and minutes.
|
||||
|
||||
We have a [#rust-gpu Discord channel](https://discord.gg/dAuKfZS) for fast discussion and collaboration.
|
||||
|
||||
## Backwards compatibility, breaking changes and deprecation
|
||||
|
||||
Right now because the project is in an early state of development, we might introduce temporary changes as stop-gap measures, or implement features or APIs that might not work exactly in a way we end up liking. Therefore it is expected that some (if not most) of the user facing code will change and evolve over time. At the moment this means that we make no guarantees about backwards compatibility and have no formal deprecation model in place. Effectively meaning that currently we only support building from source with the latest `main` branch in our repository. We appreciate our early adopters and would ask them to evolve their code along with ours.
|
||||
@@ -135,6 +122,7 @@ Historical and other related projects for compiling Rust code to GPUs.
|
||||
- 2020: [accel](https://github.com/termoshtt/accel) GPGPU library for Rust.
|
||||
- 2020: [rlsl](https://github.com/MaikKlein/rlsl) Predeccesor to rust_gpu, Rust to SPIR-V compiler.
|
||||
- 2021: [Rust CUDA](https://github.com/Rust-GPU/Rust-CUDA) Rust to PTX compiler, similar mechanism to rustc_codegen_spirv.
|
||||
- 2024 Embark transitions maintenance of `rust-gpu` to the open source community.
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
[package]
|
||||
name = "rustc_codegen_spirv"
|
||||
description = "SPIR-V code generator backend for rustc"
|
||||
documentation = "https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv/index.html"
|
||||
documentation = "https://rust-gpu.github.io/rust-gpu/api/rustc_codegen_spirv/index.html"
|
||||
version.workspace = true
|
||||
authors.workspace = true
|
||||
edition.workspace = true
|
||||
|
||||
@@ -4,4 +4,4 @@ Compiler backend for the `SPIR-V` target architecture. This crate is not intende
|
||||
|
||||
## Documentation
|
||||
|
||||
Because of its nature, this crate can only be built using a very specific nightly version of the Rust toolchain. As such, the `docs.rs` build of the API documentation will likely fail. Please refer to the [documentation in the `rust-gpu` github repo](https://embarkstudios.github.io/rust-gpu/api/rustc_codegen_spirv/index.html) for properly built docs.
|
||||
Because of its nature, this crate can only be built using a very specific nightly version of the Rust toolchain. As such, the `docs.rs` build of the API documentation will likely fail. Please refer to the [documentation in the `rust-gpu` github repo](https://rust-gpu.github.io/rust-gpu/api/rustc_codegen_spirv/index.html) for properly built docs.
|
||||
|
||||
@@ -10,11 +10,11 @@
|
||||
//! - [`spirv-tools`]
|
||||
//! - [`spirv-tools-sys`]
|
||||
//!
|
||||
//! [gpu-dev-guide]: https://embarkstudios.github.io/rust-gpu/book
|
||||
//! [`spirv-builder`]: https://embarkstudios.github.io/rust-gpu/api/spirv_builder
|
||||
//! [`spirv-std`]: https://embarkstudios.github.io/rust-gpu/api/spirv_std
|
||||
//! [`spirv-tools`]: https://embarkstudios.github.io/rust-gpu/api/spirv_tools
|
||||
//! [`spirv-tools-sys`]: https://embarkstudios.github.io/rust-gpu/api/spirv_tools_sys
|
||||
//! [gpu-dev-guide]: https://rust-gpu.github.io/rust-gpu/book
|
||||
//! [`spirv-builder`]: https://rust-gpu.github.io/rust-gpu/api/spirv_builder
|
||||
//! [`spirv-std`]: https://rust-gpu.github.io/rust-gpu/api/spirv_std
|
||||
//! [`spirv-tools`]: https://rust-gpu.github.io/rust-gpu/api/spirv_tools
|
||||
//! [`spirv-tools-sys`]: https://rust-gpu.github.io/rust-gpu/api/spirv_tools_sys
|
||||
#![feature(rustc_private)]
|
||||
#![feature(array_methods)]
|
||||
#![feature(assert_matches)]
|
||||
@@ -498,7 +498,7 @@ impl Drop for DumpModuleOnPanic<'_, '_, '_> {
|
||||
pub fn __rustc_codegen_backend() -> Box<dyn CodegenBackend> {
|
||||
// Tweak rustc's default ICE panic hook, to direct people to `rust-gpu`.
|
||||
rustc_driver::install_ice_hook(
|
||||
"https://github.com/EmbarkStudios/rust-gpu/issues/new",
|
||||
"https://github.com/rust-gpu/rust-gpu/issues/new",
|
||||
|handler| {
|
||||
handler.note_without_error(concat!(
|
||||
"`rust-gpu` version `",
|
||||
|
||||
@@ -33,7 +33,7 @@ As `spirv-builder` relies on `rustc_codegen_spirv` being built for it (by Cargo,
|
||||
|
||||
**The current Rust toolchain version is: `nightly-2023-05-27`.**
|
||||
|
||||
Rust toolchain version history across [rust-gpu releases](https://github.com/EmbarkStudios/rust-gpu/releases) (since `0.4`):
|
||||
Rust toolchain version history across [rust-gpu releases](https://github.com/rust-gpu/rust-gpu/releases) (since `0.4`):
|
||||
|
||||
|`spirv-builder`<br>version|Rust toolchain<br>version|
|
||||
|:-:|:-:|
|
||||
@@ -52,4 +52,4 @@ Notably, the error will also show what the `rust-toolchain.toml` file *should* c
|
||||
|
||||
If you want to experiment with _different, **unsupported**_, Rust toolchain versions, this check can be omitted by defining the environment variable `RUSTGPU_SKIP_TOOLCHAIN_CHECK`. Keep in mind that, as `rustc_codegen_spirv` is *heavily* dependent on `rustc`'s internal APIs, diverging too much from the supported toolchain version will quickly result in compile errors (or worse, e.g. spurious errors and/or incorrect behavior, when compiling shaders with it).
|
||||
|
||||
[rustgpu]: https://github.com/EmbarkStudios/rust-gpu/
|
||||
[rustgpu]: https://github.com/rust-gpu/rust-gpu/
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# `spirv-std`
|
||||
|
||||
Core functions, traits, and more that make up a “standard library” for SPIR-V for use in [rust-gpu](https://github.com/EmbarkStudios/rust-gpu#readme).
|
||||
Core functions, traits, and more that make up a “standard library” for SPIR-V for use in [rust-gpu](https://github.com/rust-gpu/rust-gpu#readme).
|
||||
|
||||
This crate gives a `rust-gpu` shader access to the required `#![spirv(..)]` attribute, as well as povide all kinds of APIs that allows a shader to access GPU resources such as textures and buffers. Optionally, through the use of the `"glam"` feature, it includes some boilerplate trait implementations to make `glam` vector types compatible with these APIs.
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
|
||||
|
||||
Here is a small excerpt to see what a shader would look like. See [source][source] for full details of the shader that generates above image.
|
||||
|
||||
@@ -42,7 +42,7 @@ Check out [The `rust-gpu` Dev Guide][gpu-guide] for information on how to get st
|
||||
|
||||
Experiment with rust-gpu shaders in-browser at [SHADERed][shadered].
|
||||
|
||||
[migration]: https://github.com/EmbarkStudios/rust-gpu/blob/097ba40bedd74eeaa296e719ef7e41f2d3d76c23/docs/src/migration-to-register-tool.md
|
||||
[source]: https://github.com/EmbarkStudios/rust-gpu/blob/69cb69d28f1e64420ee31ade5e7dffb7c5621e89/examples/shaders/sky-shader/src/lib.rs
|
||||
[gpu-guide]: https://embarkstudios.github.io/rust-gpu/book/
|
||||
[migration]: https://github.com/rust-gpu/rust-gpu/blob/097ba40bedd74eeaa296e719ef7e41f2d3d76c23/docs/src/migration-to-register-tool.md
|
||||
[source]: https://github.com/rust-gpu/rust-gpu/blob/69cb69d28f1e64420ee31ade5e7dffb7c5621e89/examples/shaders/sky-shader/src/lib.rs
|
||||
[gpu-guide]: https://rust-gpu.github.io/rust-gpu/book/
|
||||
[shadered]: https://shadered.org/shaders?language=rust&sort=hot
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
1. Clone the repository.
|
||||
|
||||
```shell
|
||||
git clone --recurse-submodules https://github.com/EmbarkStudios/rust-gpu
|
||||
git clone --recurse-submodules https://github.com/rust-gpu/rust-gpu
|
||||
```
|
||||
|
||||
1. **optional** Install [SPIRV-Tools](https://github.com/KhronosGroup/SPIRV-Tools#downloads) and add it to your `PATH`. You can skip this step if you just want to run examples with the defaults. See [Using installed SPIRV-Tools](#using-installed-spirv-tools) if you decide to go with this option.
|
||||
@@ -39,10 +39,10 @@ cargo run \
|
||||
|
||||
You should see `warning: use-installed-tools feature on, skipping compilation of C++ code` during the compilation, but otherwise the build will function just the same as if you compiled the C++ code, with the exception that it will fail if you don't have SPIRV-Tools installed correctly.
|
||||
|
||||
[spirv-builder]: https://embarkstudios.github.io/rust-gpu/api/spirv_builder/index.html
|
||||
[examples]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples
|
||||
[examples/runners]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples/runners
|
||||
[examples/runners/ash]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples/runners/ash
|
||||
[examples/runners/cpu]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples/runners/cpu
|
||||
[examples/runners/wgpu]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples/runners/wgpu
|
||||
[examples/shaders]: https://github.com/EmbarkStudios/rust-gpu/tree/main/examples/shaders
|
||||
[spirv-builder]: https://rust-gpu.github.io/rust-gpu/api/spirv_builder/index.html
|
||||
[examples]: https://github.com/rust-gpu/rust-gpu/tree/main/examples
|
||||
[examples/runners]: https://github.com/rust-gpu/rust-gpu/tree/main/examples/runners
|
||||
[examples/runners/ash]: https://github.com/rust-gpu/rust-gpu/tree/main/examples/runners/ash
|
||||
[examples/runners/cpu]: https://github.com/rust-gpu/rust-gpu/tree/main/examples/runners/cpu
|
||||
[examples/runners/wgpu]: https://github.com/rust-gpu/rust-gpu/tree/main/examples/runners/wgpu
|
||||
[examples/shaders]: https://github.com/rust-gpu/rust-gpu/tree/main/examples/shaders
|
||||
|
||||
@@ -160,13 +160,13 @@ Disables CFG structurization. Probably results in invalid modules.
|
||||
Note: as of `rust-gpu 0.8.0`, `SPIR-🇹` is always being used and cannot be disabled
|
||||
(to reduce the cost of maintenance, testing and further feature development).
|
||||
|
||||
Enables using the experimental [`SPIR-🇹` shader IR framework](https://github.com/EmbarkStudios/spirt) in the linker - more specifically, this:
|
||||
Enables using the experimental [`SPIR-🇹` shader IR framework](https://github.com/rust-gpu/spirt) in the linker - more specifically, this:
|
||||
- adds a `SPIR-V -> SPIR-🇹 -> SPIR-V` roundtrip
|
||||
(future `SPIR-🇹` passes would go in the middle of this, and eventually codegen might not produce `SPIR-V` at all)
|
||||
- replaces the existing structurizer with `SPIR-🇹` structurization (which is more robust and can e.g. handle `OpPhi`s)
|
||||
- runs some existing `SPIR-V` legalization/optimization passes (`mem2reg`) *before* inlining, instead of *only after* (as the `OpPhi`s they would produce are no longer an issue for structurization)
|
||||
|
||||
For more information, also see [the `SPIR-🇹` repository](https://github.com/EmbarkStudios/spirt).
|
||||
For more information, also see [the `SPIR-🇹` repository](https://github.com/rust-gpu/spirt).
|
||||
|
||||
### `--no-spirt` <sub>_(0.6.0 and 0.7.0)_</sup>
|
||||
|
||||
@@ -178,7 +178,7 @@ Note: if you were using `--no-spirt` to work around [`naga` issue #1977](https:/
|
||||
you may be able to `cargo update -p naga` to update to a fixed `naga` version
|
||||
(`0.11.1` for `wgpu 0.15`, `0.12.1` for `wgpu 0.16`, and any later versions).
|
||||
|
||||
Disables the [`SPIR-🇹` shader IR framework](https://github.com/EmbarkStudios/spirt) in the linker.
|
||||
Disables the [`SPIR-🇹` shader IR framework](https://github.com/rust-gpu/spirt) in the linker.
|
||||
|
||||
### `--spirt-passes PASSES`
|
||||
|
||||
|
||||
@@ -6,10 +6,10 @@ type is incredibly tedious, so a wrapper macro, `spirv_std::Image!` can be used
|
||||
instead.
|
||||
|
||||
The specific syntax and meaning of the arguments to the `Image!` macro can be found in
|
||||
[rustdoc](https://embarkstudios.github.io/rust-gpu/api/spirv_std/macro.Image.html).
|
||||
[rustdoc](https://rust-gpu.github.io/rust-gpu/api/spirv_std/macro.Image.html).
|
||||
|
||||
Some type aliases for common image formats can be found in the
|
||||
[`spirv_std::image`](https://embarkstudios.github.io/rust-gpu/api/spirv_std/image/index.html)
|
||||
[`spirv_std::image`](https://rust-gpu.github.io/rust-gpu/api/spirv_std/image/index.html)
|
||||
module. For example, `Image2d` is a very commonly used type, corresponding to `texture2D` in GLSL,
|
||||
and is likely what you want if you want a regular old sampled texture.
|
||||
|
||||
|
||||
@@ -1,9 +1,10 @@
|
||||
# Publishing rust-gpu on crates.io
|
||||
|
||||
This is a task list for the maintainers of rust-gpu to remember to do when publishing a new version
|
||||
of rust-gpu (probably not useful for contributors without access to embark's crates.io account 😋)
|
||||
of rust-gpu (probably not useful for contributors without access to our crates.io account 😋)
|
||||
|
||||
The published crates and their relative locations are:
|
||||
|
||||
1. `spirv-std-types` (`crates/spirv-std/shared`)
|
||||
2. `spirv-std-macros` (`crates/spirv-std/macros`)
|
||||
3. `spirv-std` (`crates/spirv-std`)
|
||||
@@ -16,7 +17,7 @@ These are the steps:
|
||||
|
||||
1. Bump all the versions to the next one in the workspace's `Cargo.toml`. This project uses workspace
|
||||
inheritance, so this is the only place you'll find these actual versions. Make sure to pin the
|
||||
rust-gpu dependencies to their *exact* versions using the `=`-notation, such as: `=0.4.0`. All crates
|
||||
rust-gpu dependencies to their _exact_ versions using the `=`-notation, such as: `=0.4.0`. All crates
|
||||
are built and published in tandem so you're not expected to be able to mix and match between versions.
|
||||
2. Add this new version to the table in `crates/spirv-builder/README.md` and make sure the correct
|
||||
nightly version is listed there as well.
|
||||
@@ -24,7 +25,7 @@ These are the steps:
|
||||
4. Pull the merged `main` branch.
|
||||
5. Tag `main` with the version: `git tag v0.4.0`
|
||||
6. Push the tag: `git push origin v0.4.0`
|
||||
7. Publish the crates: `cd [crate] && cargo publish` in the order of the list above (make sure
|
||||
`.cargo/credentials` is set to embark's token). The crates.io index might take some seconds to update
|
||||
7. Publish the crates: `cd [crate] && cargo publish` in the order of the list above.
|
||||
The crates.io index might take some seconds to update
|
||||
causing an error if the crates are published in quick succession. Wait a couple of seconds and try
|
||||
again 🙂.
|
||||
|
||||
@@ -4,7 +4,7 @@ This is section is going to walk you through writing a shader in Rust and
|
||||
setting up your shader crate.
|
||||
|
||||
Be aware that this project is in a very early phase, please [file an
|
||||
issue](https://github.com/EmbarkStudios/rust-gpu/issues) if there's something
|
||||
issue](https://github.com/rust-gpu/rust-gpu/issues) if there's something
|
||||
not working or unclear.
|
||||
|
||||
## Online
|
||||
@@ -65,7 +65,7 @@ Substituting `shader_crate` with a relative path to your shader crate. The value
|
||||
`"spirv-unknown-vulkan1.1"`.
|
||||
|
||||
The `SpirvBuilder` struct has numerous configuration options available, see
|
||||
[documentation](https://embarkstudios.github.io/rust-gpu/api/spirv_builder/struct.SpirvBuilder.html).
|
||||
[documentation](https://rust-gpu.github.io/rust-gpu/api/spirv_builder/struct.SpirvBuilder.html).
|
||||
|
||||
#### `main.rs`
|
||||
The following will directly include the shader module binary into your application.
|
||||
@@ -142,7 +142,7 @@ cargo build
|
||||
Now you should have `<project_name>.spv` SPIR-V file in `target/debug` that you
|
||||
can give to a renderer.
|
||||
|
||||
[`rust-toolchain.toml`]: https://github.com/EmbarkStudios/rust-gpu/blob/main/rust-toolchain.toml
|
||||
[`rust-toolchain.toml`]: https://github.com/rust-gpu/rust-gpu/blob/main/rust-toolchain.toml
|
||||
|
||||
## Writing your first shader
|
||||
|
||||
|
||||
Reference in New Issue
Block a user