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

doc(d3d12): clean up docs for d3d12

Browse source
This commit is contained in:
chyyran 2023-02-06 01:25:06 -05:00
parent ec619ec5e2
commit 3cdf3aa105
12 changed files with 87 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
Cargo.lock generated
View file

@ -802,6 +802,7 @@ dependencies = [
"librashader-reflect",
"librashader-runtime",
"librashader-runtime-d3d11",
"librashader-runtime-d3d12",
"librashader-runtime-gl",
"librashader-runtime-vk",
"librashader-spirv-cross",
@ -907,7 +908,7 @@ dependencies = [
[[package]]
name = "librashader-runtime-d3d12"
version = "0.1.0-beta.8"
version = "0.1.0-beta.10"
dependencies = [
"array-concat",
"array-init",

34
README.md
View file

@ -10,20 +10,22 @@ librashader (*/ˈli:brəʃeɪdɚ/*) is a preprocessor, compiler, and runtime for
![Nightly rust](https://img.shields.io/badge/rust-nightly-orange.svg)
## Supported Render APIs
librashader supports OpenGL 3, OpenGL 4.6, Vulkan, DirectX 11, and DirectX 12. Older versions
of DirectX and OpenGL, as well as Metal, are not supported (but pull-requests are welcome).
librashader supports OpenGL 3, OpenGL 4.6, Vulkan, Direct3D 11, and Direct3D 12. Older versions
of Direct3D and OpenGL, as well as Metal, are not supported (but pull-requests are welcome).
| **API** | **Status** | **`librashader` feature** |
|-------------|------------|---------------------------|
| OpenGL 3.3+ | ✔ | `gl` |
| OpenGL 4.6 | ✔ | `gl` |
| Vulkan 1.3+ | ✔ | `vk` |
| Direct3D11 | ✔ | `d3d11` |
| Direct3D12 | 🚧 | `d3d12` |
| Vulkan | ✔ | `vk` |
| Direct3D 11 | ✔ | `d3d11` |
| Direct3D 12 | ✔ | `d3d12` |
| OpenGL 2 | ❌ | |
| DirectX 9 | ❌ | |
| Direct3D 9 | ❌ | |
| Direct3D 10 | ❌ | |
| Metal | ❌ | |
✔ = Render API is supported — 🚧 = Support is in progress — ❌ Render API is not supported
## Usage
@ -73,18 +75,17 @@ CMake package is highly recommended.
### Examples
The following Rust examples show how to use each librashader runtime.
* [Vulkan](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-vk/src/lib.rs#L40)
* [OpenGL](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-gl/src/lib.rs#L34)
* [Direct3D 11](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-d3d11/src/lib.rs#L33)
* [Vulkan](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-vk/src/lib.rs)
* [OpenGL](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-gl/src/lib.rs)
* [Direct3D 11](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-d3d11/src/lib.rs)
* [Direct3D 12](https://github.com/SnowflakePowered/librashader/blob/master/librashader-runtime-d3d12/src/lib.rs)
Some basic examples on using the C API are also provided in the [librashader-capi-tests](https://github.com/SnowflakePowered/librashader/tree/master/test/capi-tests/librashader-capi-tests)
directory.
## Compatibility
librashader implements the entire RetroArch shader pipeline and is highly compatible with existing shaders,
but there are some deliberate differences in design choices that may potentially cause incompatiblities with certain
shaders.
librashader implements the entire RetroArch shader pipeline and is highly compatible with existing shaders.
Please report an issue if you run into a shader that works in RetroArch, but not under librashader.
@ -92,6 +93,8 @@ Please report an issue if you run into a shader that works in RetroArch, but not
* Unlike RetroArch, librashader does not have full knowledge of the entire rendering state and is designed to be pluggable
at any point in your render pipeline. Instead, filter chains terminate at a caller-provided output surface and viewport.
It is the caller's responsibility to blit the surface back to the backbuffer.
* Shaders are compiled in parallel where possible. This should noticeably decrease preset compile times. Note that parallel compilation
is not available to OpenGL.
* Runtime-specific differences
* OpenGL
* Copying of in-flight framebuffer contents to history is done via `glBlitFramebuffer` rather than drawing a quad into an intermediate FBO.
@ -119,11 +122,6 @@ Please report an issue if you run into a shader that works in RetroArch, but not
Most, if not all shader presets should work fine on librashader. The runtime specific differences should not affect the output,
and are more a heads-up for integrating librashader into your project.
Compatibility issues may arise with framebuffer copies for original history, but I have not found any yet;
if it does end up that this results in actual rendering differences I may change the implementation to be more in line
with RetroArch's copy implementation. However, since the Vulkan runtime already uses `vkCmdCopyImage` it is likely that it will
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/)
@ -137,7 +135,7 @@ the runtime.
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 librashader C API, i.e. its headers and definitions, *not its implementation in `librashader_capi`*,
The librashader C API, i.e. its headers and definitions, *not its implementation in `librashader-capi`*,
are more permissively licensed, and may allow you to use librashader in your permissively
licensed or proprietary project.

2
librashader-reflect/Cargo.toml
View file

@ -30,7 +30,7 @@ bytemuck = "1.13.0"
rspirv = { version = "0.11.0+1.5.4", optional = true }
[features]
default = ["dxil", "unstable-naga"]
default = ["dxil"]
unstable-naga = [ "naga", "rspirv" ]
standalone = ["shaderc/build-from-source"]
dxil = ["spirv-to-dxil"]

4
librashader-runtime-d3d11/src/error.rs
View file

@ -1,4 +1,4 @@
//! Direct3D11 shader runtime errors.
//! Direct3D 11 shader runtime errors.
//!
use librashader_preprocess::PreprocessError;
use librashader_presets::ParsePresetError;
@ -43,5 +43,5 @@ macro_rules! assume_d3d11_init {
/// Macro for unwrapping result of a D3D function.
pub(crate) use assume_d3d11_init;
/// Result type for Direct3D11 filter chains.
/// Result type for Direct3D 11 filter chains.
pub type Result<T> = std::result::Result<T, FilterChainError>;

2
librashader-runtime-d3d12/Cargo.toml
View file

@ -3,7 +3,7 @@ name = "librashader-runtime-d3d12"
edition = "2021"
license = "MPL-2.0 OR GPL-3.0-only"
version = "0.1.0-beta.8"
version = "0.1.0-beta.10"
authors = ["Ronny Chan <ronny@ronnychan.ca>"]
repository = "https://github.com/SnowflakePowered/librashader"
readme = "../README.md"

3
librashader-runtime-d3d12/src/error.rs
View file

@ -1,3 +1,5 @@
//! Direct3D 12 shader runtime errors.
//!
use thiserror::Error;
/// Cumulative error type for Direct3D12 filter chains.
@ -23,6 +25,7 @@ pub enum FilterChainError {
DescriptorHeapOverflow,
}
/// Result type for Direct3D 12 filter chains.
pub type Result<T> = std::result::Result<T, FilterChainError>;
macro_rules! assume_d3d12_init {

10
librashader-runtime-d3d12/src/filter_chain.rs
View file

@ -61,6 +61,7 @@ pub struct FilterMutable {
pub(crate) parameters: FxHashMap<String, f32>,
}
/// A Direct3D 12 filter chain.
pub struct FilterChainD3D12 {
pub(crate) common: FilterCommon,
pub(crate) passes: Vec<FilterPass>,
@ -513,7 +514,14 @@ impl FilterChainD3D12 {
Ok(())
}
/// Process a frame with the input image.
/// Records shader rendering commands to the provided command list.
///
/// * The input image must be in the `D3D12_RESOURCE_STATE_PIXEL_SHADER_RESOURCE` resource state.
/// * The output image must be in `D3D12_RESOURCE_STATE_RENDER_TARGET` resource state.
///
/// librashader **will not** create a resource barrier for the final pass. The output image will
/// remain in `D3D12_RESOURCE_STATE_RENDER_TARGET` after all shader passes. The caller must transition
/// the output image to the final resource state.
pub fn frame(
&mut self,
cmd: &ID3D12GraphicsCommandList,

5
librashader-runtime-d3d12/src/lib.rs
View file

@ -3,7 +3,7 @@
#![feature(type_alias_impl_trait)]
mod buffer;
mod descriptor_heap;
mod error;
pub mod error;
mod filter_chain;
mod filter_pass;
mod framebuffer;
@ -11,7 +11,7 @@ mod graphics_pipeline;
mod hello_triangle;
mod luts;
mod mipmap;
mod options;
pub mod options;
mod parameters;
mod quad_render;
mod render_target;
@ -19,6 +19,7 @@ mod samplers;
mod texture;
mod util;
pub use filter_chain::FilterChainD3D12;
pub use texture::D3D12InputImage;
pub use texture::D3D12OutputView;

5
librashader-runtime-d3d12/src/texture.rs
View file

@ -4,6 +4,7 @@ use std::ops::Deref;
use windows::Win32::Graphics::Direct3D12::{ID3D12Resource, D3D12_CPU_DESCRIPTOR_HANDLE};
use windows::Win32::Graphics::Dxgi::Common::DXGI_FORMAT;
/// An image for use as shader resource view.
pub struct D3D12InputImage {
pub resource: ID3D12Resource,
pub descriptor: D3D12_CPU_DESCRIPTOR_HANDLE,
@ -41,6 +42,10 @@ impl AsRef<D3D12_CPU_DESCRIPTOR_HANDLE> for OutputDescriptor {
}
}
/// An image view for use as a render target.
///
/// Can be created from a CPU descriptor handle, and a size.
#[derive(Clone)]
pub struct D3D12OutputView {
pub(crate) descriptor: OutputDescriptor,

4
librashader-runtime-vk/src/filter_chain.rs
View file

@ -523,8 +523,8 @@ impl FilterChainVulkan {
}
/// Records shader rendering commands to the provided command buffer.
///
/// * The input image must be in the `VK_SHADER_READ_ONLY_OPTIMAL`.
/// * The output image must be in `VK_COLOR_ATTACHMENT_OPTIMAL`.
/// * The input image must be in the `VK_SHADER_READ_ONLY_OPTIMAL` layout.
/// * The output image must be in `VK_COLOR_ATTACHMENT_OPTIMAL` layout.
///
/// librashader **will not** create a pipeline barrier for the final pass. The output image will
/// remain in `VK_COLOR_ATTACHMENT_OPTIMAL` after all shader passes. The caller must transition

12
librashader/Cargo.toml
View file

@ -19,23 +19,23 @@ librashader-preprocess = { path = "../librashader-preprocess", version = "0.1.0-
librashader-reflect = { path = "../librashader-reflect", version = "0.1.0-beta.10", features = ["standalone"] }
librashader-runtime = { path = "../librashader-runtime", version = "0.1.0-beta.10" }
librashader-runtime-d3d11 = { path = "../librashader-runtime-d3d11", version = "0.1.0-beta.10", optional = true }
librashader-runtime-d3d12 = { path = "../librashader-runtime-d3d12", version = "0.1.0-beta.10", optional = true }
librashader-runtime-gl = { path = "../librashader-runtime-gl", version = "0.1.0-beta.10", optional = true }
librashader-runtime-vk = { path = "../librashader-runtime-vk", version = "0.1.0-beta.10", optional = true }
ash = { version = "0.37.1+1.3.235", optional = true }
spirv_cross = { package = "librashader-spirv-cross", version = "0.23", features = ["glsl"], optional = true }
spirv_cross = { package = "librashader-spirv-cross", version = "0.23", features = ["glsl", "hlsl"], optional = true }
[target.'cfg(windows)'.dependencies.windows]
version = "0.44.0"
features = [
"Win32_Graphics_Direct3D11",
]
optional = true
[features]
default = ["gl", "d3d11", "vk", "reflect", "preprocess", "presets" ]
default = ["gl", "d3d11", "d3d12", "vk", "reflect", "preprocess", "presets" ]
gl = [ "runtime", "librashader-common/opengl", "librashader-runtime-gl", "spirv_cross" ]
d3d11 = [ "runtime", "librashader-common/d3d11", "librashader-runtime-d3d11", "windows" ]
d3d11 = [ "runtime", "librashader-common/d3d11", "librashader-runtime-d3d11", "windows/Win32_Graphics_Direct3D11" ]
d3d12 = [ "runtime", "librashader-common/d3d11", "librashader-runtime-d3d12", "windows/Win32_Graphics_Direct3D12" ]
vk = ["runtime", "librashader-common/vulkan", "librashader-runtime-vk", "ash" ]
runtime = []
reflect = []

43
librashader/src/lib.rs
View file

@ -15,10 +15,14 @@
//! called with appropriate input and output parameters to draw a frame with the shader effect applied.
//!
//! ## Runtimes
//! Currently available runtimes are Vulkan 1.3+, OpenGL 3.3+ and 4.6 (with DSA), and Direct3D 11.
//! Work on the Direct3D 12 runtime is in progress. The Vulkan runtime requires [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html)
//! Currently available runtimes are Vulkan, OpenGL 3.3+ and 4.6 (with DSA), Direct3D 11, and Direct3D 12.
//!
//! The Vulkan runtime requires [`VK_KHR_dynamic_rendering`](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_KHR_dynamic_rendering.html)
//! by default, unless [`FilterChainOptions::render_pass_format`](crate::runtime::vk::FilterChainOptions) is explicitly set. Note that dynamic rendering
//! will being the best performance.
//! will bring the best performance.
//!
//! The Direct3D 12 runtime requires support for [render passes](https://learn.microsoft.com/en-us/windows/win32/direct3d12/direct3d-12-render-passes), which
//! have been available since Windows 10, version 1809.
//!
//! | **API** | **Status** | **`librashader` feature** |
//! |-------------|------------|---------------------------|
@ -26,9 +30,10 @@
//! | OpenGL 4.6 | ✔ | `gl` |
//! | Vulkan | ✔ | `vk` |
//! | Direct3D 11 | ✔ | `d3d11` |
//! | Direct3D 12 | 🚧 | `d3d12` |
//! | Direct3D 12 | ✔ | `d3d12` |
//! | OpenGL 2 | ❌ | |
//! | DirectX 9 | ❌ | |
//! | Direct3D 9 | ❌ | |
//! | Direct3D 10 | ❌ | |
//! | Metal | ❌ | |
//!
//! ## C API
@ -126,6 +131,7 @@ pub mod reflect {
pub mod targets {
pub use librashader_reflect::back::targets::GLSL;
pub use librashader_reflect::back::targets::HLSL;
pub use librashader_reflect::back::targets::DXIL;
pub use librashader_reflect::back::targets::SPIRV;
}
@ -142,9 +148,12 @@ pub mod reflect {
pub mod cross {
pub use librashader_reflect::front::GlslangCompilation;
/// The version of GLSL to compile to.
/// The version of GLSL to target.
pub use spirv_cross::glsl::Version as GlslVersion;
/// The HLSL Shader Model to target.
pub use spirv_cross::hlsl::ShaderModel as HlslVersion;
pub use librashader_reflect::back::cross::CrossGlslContext;
pub use librashader_reflect::back::cross::CrossHlslContext;
@ -232,6 +241,28 @@ pub mod runtime {
}
}
#[cfg(all(target_os = "windows", feature = "d3d12"))]
#[doc(cfg(all(target_os = "windows", feature = "d3d12")))]
/// Shader runtime for Direct3D 12.
pub mod d3d12 {
pub use librashader_runtime_d3d12::{
error,
options::{
FilterChainOptionsD3D12 as FilterChainOptions, FrameOptionsD3D12 as FrameOptions,
},
D3D12InputImage, D3D12OutputView, FilterChainD3D12 as FilterChain,
};
#[doc(hidden)]
#[cfg(feature = "internal")]
/// Re-exports names to deal with C API conflicts.
///
/// This is internal to librashader-capi and is exempt from semantic versioning.
pub mod capi {
pub use librashader_runtime_d3d12::*;
}
}
#[cfg(feature = "vk")]
#[doc(cfg(feature = "vk"))]
/// Shader runtime for Vulkan 1.3+.