alex/librashader
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

doc: update docs for stable build instructions

Browse source
This commit is contained in:
chyyran 2024-09-15 03:00:59 -04:00 committed by Ronny Chan
parent 927740433c
commit 05d48841ad
2 changed files with 87 additions and 45 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

52
README.md
View file

@ -8,7 +8,7 @@ librashader (*/ˈli:brəʃeɪdɚ/*) is a preprocessor, compiler, and runtime for
[![Latest Version](https://img.shields.io/crates/v/librashader.svg)](https://crates.io/crates/librashader) [![Docs](https://docs.rs/librashader/badge.svg)](https://docs.rs/librashader) [![build result](https://build.opensuse.org/projects/home:chyyran:librashader/packages/librashader/badge.svg)](https://software.opensuse.org//download.html?project=home%3Achyyran%3Alibrashader&package=librashader)
![License](https://img.shields.io/crates/l/librashader)
![Nightly rust](https://img.shields.io/badge/rust-nightly-orange.svg)
![Nightly rust](https://img.shields.io/badge/rust-nightly-orange.svg) ![Stable rust](https://img.shields.io/badge/rust-1.77-blue.svg)
## Installation
For end-users, librashader is available from the [Open Build Service](https://software.opensuse.org//download.html?project=home%3Achyyran%3Alibrashader&package=librashader) for a variety of Linux distributions and platforms.
@ -92,7 +92,17 @@ static DEFAULT_MVP: &[f32; 16] = &[
As with RetroArch, a rotation on this MVP will be applied only on the final pass for these runtimes. This is the only way to
pass orientation information to shaders.
### Building
### Writing a librashader Runtime
If you wish to contribute a runtime implementation not already available, see the [librashader-runtime](https://docs.rs/librashader-runtime/latest/librashader_runtime/)
crate for helpers and shared logic used across all librashader runtime implementations. Using these helpers and traits will
ensure that your runtime has consistent behaviour for uniform and texture semantics bindings with the existing librashader runtimes.
These types should not be exposed to the end user in the runtime's public API, and should be kept internal to the implementation of
the runtime.
## Building
For Rust projects, simply add the crate to your `Cargo.toml`.
@ -112,14 +122,28 @@ This will output a `librashader.dll` or `librashader.so` in the target folder. P
While librashader has no build-time dependencies, using `librashader_ld.h` may require headers from
the relevant runtime graphics API.
### Writing a librashader Runtime
If you wish to contribute a runtime implementation not already available, see the [librashader-runtime](https://docs.rs/librashader-runtime/latest/librashader_runtime/)
crate for helpers and shared logic used across all librashader runtime implementations. Using these helpers and traits will
ensure that your runtime has consistent behaviour for uniform and texture semantics bindings with the existing librashader runtimes.
### Building against stable Rust
While librashader is intended to be used with nightly Rust until [required features](https://github.com/SnowflakePowered/librashader/issues/55) are stabilized, it supports being
built with stable Rust with the `stable` feature.
These types should not be exposed to the end user in the runtime's public API, and should be kept internal to the implementation of
the runtime.
```toml
librashader = { features = "stable" }
```
If building the C API, the `--stable` flag in the build script will enable the `stable` feature.
```
cargo +stable run -p librashader-build-script -- --profile optimized --stable
```
There are some caveats when building against stable Rust, such that building librashader against nightly Rust is still highly encouraged.
* C headers will not be regenerated when building with the `stable` feature.
* There is a minor performance hit in initial shader compilation when building against stable Rust. This is due to boxed trait objects being used instead of `impl Trait`.
* A higher MSRV is required when building against stable Rust.
When the `trait_alias_impl_trait` feature is stabilized, the `stable` feature will be removed.
## Examples
@ -225,12 +249,18 @@ in both the Rust and C API without an increase to either `LIBRASHADER_CURRENT_VE
### MSRV Policy
While librashader requires nightly Rust, the following MSRV policy is enforced for unstable library features.
When building against nightly Rust, the following MSRV policy is enforced for unstable library features.
* Windows and macOS: **latest** nightly
* Linux: **1.76**
* Linux: **1.74**
A CI job runs weekly to ensure librashader continues to build on nightly. Note that the MSRV is only intended to ease distribution on Linux and is allowed to change any time. It generally tracks the latest version of Rust available in the latest version of Ubuntu, but this may change with no warning in a patch release.
A CI job runs weekly to ensure librashader continues to build on nightly.
Building against stable Rust requires a higher MSRV.
* All platforms: **1.77**
Note that the MSRV is only intended to ease distribution on Linux when building against nightly Rust or with `RUSTC_BOOTSTRAP=1`, and is allowed to change any time.
It generally tracks the latest version of Rust available in the latest version of Ubuntu, but this may change with no warning in a patch release.
## License
The core parts of librashader such as the preprocessor, the preset parser,

60
librashader/src/lib.rs
View file

@ -104,33 +104,26 @@ pub mod preprocess {
#[cfg_attr(feature = "docsrs", doc(cfg(feature = "reflect")))]
/// Shader reflection and cross-compilation.
///
/// The `type_alias_impl_trait` nightly feature is required. You should choose your
/// target shading language, and a compilation type.
/// Without the `stable` crate feature, the `type_alias_impl_trait` nightly feature is required.
///
/// You should choose your target shading language, and a compilation type.
///
/// ```rust
/// #![feature(type_alias_impl_trait)]
///
/// mod compile {
/// use std::error::Error;
/// use librashader::preprocess::ShaderSource;
/// use librashader::presets::ShaderPreset;
/// use librashader::reflect::{CompileReflectShader, FromCompilation, CompilePresetTarget, ShaderPassArtifact};
/// use librashader::reflect::targets::SPIRV;
/// use librashader::reflect::semantics::ShaderSemantics;
/// use librashader_reflect::front::{ShaderInputCompiler, SpirvCompilation};
/// use librashader_preprocess::ShaderSource;
/// use librashader_presets::ShaderPreset;
/// use librashader_reflect::back::{CompileReflectShader, FromCompilation};
/// use librashader_reflect::back::targets::SPIRV;
/// use librashader_reflect::front::SpirvCompilation;
/// use librashader_reflect::reflect::cross::SpirvCross;
/// use librashader_reflect::reflect::presets::{CompilePresetTarget, ShaderPassArtifact};
/// use librashader_reflect::reflect::semantics::ShaderSemantics;
///
/// type Artifact = impl CompileReflectShader<SPIRV, SpirvCompilation, SpirvCross>;
/// type ShaderPassMeta = ShaderPassArtifact<Artifact>;
///
/// // Compile single shader
/// pub fn compile_spirv(
/// source: &ShaderSource,
/// ) -> Result<Artifact, Box<dyn Error>>
/// {
/// let compilation = SpirvCompilation::compile(&source)?;
/// let spirv = SPIRV::from_compilation(compilation)?;
/// Ok(spirv)
/// }
///
/// // Compile preset
/// pub fn compile_preset(preset: ShaderPreset) -> Result<(Vec<ShaderPassMeta>, ShaderSemantics), Box<dyn Error>>
/// {
@ -138,15 +131,34 @@ pub mod preprocess {
/// preset.shaders, &preset.textures)?;
/// Ok((passes, semantics))
/// }
/// }
/// ```
///
/// With the `stable` crate feature, a trait object can be used instead. Note the `Send` bound
/// on `Artifact` is required.
///
/// ```
/// use librashader_reflect::back::CompileReflectShader;
/// use librashader_reflect::back::targets::SPIRV;
/// use librashader_reflect::front::SpirvCompilation;
/// use librashader_reflect::reflect::cross::SpirvCross;
/// use librashader_reflect::reflect::presets::ShaderPassArtifact;
///
/// type Artifact = Box<dyn CompileReflectShader<SPIRV, SpirvCompilation, SpirvCross> + Send>;
/// type ShaderPassMeta = ShaderPassArtifact<Artifact>;
/// ```
///
/// ## What's with all the traits?
/// librashader-reflect is designed to be compiler-agnostic. In the future, we will allow usage of
/// [naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler, when it has
/// matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012).
/// librashader-reflect is designed to be frontend and backend agnostic.
///
/// In the meanwhile, the only supported input compiler is [SpirvCompilation](crate::reflect::SpirvCompilation),
/// which does compilation of GLSL to SPIR-V via [glslang](https://github.com/KhronosGroup/glslang/).
/// Currently [SpirvCompilation](crate::reflect::SpirvCompilation),
/// which does compilation of GLSL to SPIR-V via [glslang](https://github.com/KhronosGroup/glslang/ is the only
/// supported frontend.
///
/// In the future, we will allow [Naga](https://docs.rs/naga/latest/naga/index.html), a pure-Rust shader compiler,
/// as a frontend, when it has matured enough to support [the features librashader needs](https://github.com/gfx-rs/naga/issues/1012).
///
/// Both naga and SPIRV-Cross are supported as backends depending on the target.
pub mod reflect {
/// Supported shader compiler targets.
pub mod targets {