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

doc: un-exempt librashader-runtime and add docs to show when they should be used.

Browse source
This commit is contained in:
chyyran 2023-01-19 01:23:51 -05:00
parent 261710d639
commit 8dd60e2a5c
2 changed files with 17 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

17
README.md
View file

@ -27,16 +27,14 @@ of DirectX and OpenGL, as well as Metal, are not supported (but pull-requests ar
✔ = Render API is supported — 🚧 = Support is in progress — ❌ Render API is not supported ✔ = Render API is supported — 🚧 = Support is in progress — ❌ Render API is not supported
## Usage ## Usage
librashader provides both a Rust API under the `librashader` crate, and a C API. Both APIs are first-class, fully supported. librashader provides both a Rust API under the `librashader` crate, and a C API. Both APIs are first-class and fully supported.
The C API is geared more towards integration with existing projects. The Rust `librashader` crate exposes more
of the internals if you wish to use parts of librashader piecemeal.
The librashader C API is best used by linking statically with `librashader_ld`, which implements a loader that dynamically The librashader C API is best used by linking statically with `librashader_ld`, which implements a loader that dynamically
loads the librashader (`librashader.so` or `librashader.dll`) implementation in the search path. You may also link against loads the librashader (`librashader.so` or `librashader.dll`) implementation in the search path. You may also link against
`librashader_capi` directly at compile time with [`librashader.h`](https://github.com/SnowflakePowered/librashader/blob/master/include/librashader.h). `librashader_capi` directly at compile time with [`librashader.h`](https://github.com/SnowflakePowered/librashader/blob/master/include/librashader.h).
The C API currently does not expose the [shader reflection API](https://docs.rs/librashader/latest/librashader/reflect/index.html). Work
is in progress to expose this to C. In the meanwhile, if you wish to implement a custom runtime for librashader, it will have to be done
in Rust.
### Building ### Building
For Rust projects, simply add the crate to your `Cargo.toml` For Rust projects, simply add the crate to your `Cargo.toml`
@ -114,6 +112,15 @@ if it does end up that this results in actual rendering differences I may change
with RetroArch's copy implementation. However, since the Vulkan runtime already uses `vkCmdCopyImage` it is likely that it will with RetroArch's copy implementation. However, since the Vulkan runtime already uses `vkCmdCopyImage` it is likely that it will
not cause issues. not cause issues.
### 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 in your publish API to the end user, and should be kept internal to the implementation of
the runtime.
## License ## License
The core parts of librashader such as the preprocessor, the preset parser, The core parts of librashader such as the preprocessor, the preset parser,
the reflection library, and the runtimes, are all licensed under the Mozilla Public License version 2.0. the reflection library, and the runtimes, are all licensed under the Mozilla Public License version 2.0.

8
librashader-runtime/src/lib.rs
View file

@ -1,9 +1,11 @@
//! Helpers and shared logic for librashader runtime implementations. //! Helpers and shared logic for librashader runtime implementations.
//! //!
//! Most of this is code internal to librashader runtime implementations and is not //! Most of this is only useful when _writing_ a librashader runtime implementations,
//! intended for general use unless writing a librashader runtime. //! not _using_ a librashader runtime. Types useful for _using_ the runtime implementations
//! will be re-exported in [`librashader::runtime`](https://docs.rs/librashader/latest/librashader/runtime/index.html).
//! //!
//! This crate is exempt from semantic versioning of the librashader API. //! If you are _writing_ a librashader runtime implementation, using these traits and helpers will
//! help in maintaining consistent behaviour in binding semantics and image handling.
#![feature(array_chunks)] #![feature(array_chunks)]
/// Scaling helpers. /// Scaling helpers.