From 3cdf3aa105c8dbbd5d94ae0097d6d92b5450f3ed Mon Sep 17 00:00:00 2001 From: chyyran Date: Mon, 6 Feb 2023 01:25:06 -0500 Subject: [PATCH] doc(d3d12): clean up docs for d3d12 --- Cargo.lock | 3 +- README.md | 34 +++++++-------- librashader-reflect/Cargo.toml | 2 +- librashader-runtime-d3d11/src/error.rs | 4 +- librashader-runtime-d3d12/Cargo.toml | 2 +- librashader-runtime-d3d12/src/error.rs | 3 ++ librashader-runtime-d3d12/src/filter_chain.rs | 10 ++++- librashader-runtime-d3d12/src/lib.rs | 5 ++- librashader-runtime-d3d12/src/texture.rs | 5 +++ librashader-runtime-vk/src/filter_chain.rs | 4 +- librashader/Cargo.toml | 12 +++--- librashader/src/lib.rs | 43 ++++++++++++++++--- 12 files changed, 87 insertions(+), 40 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 00cf850..dd30f7c 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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", diff --git a/README.md b/README.md index 8091a77..8e64e6d 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/librashader-reflect/Cargo.toml b/librashader-reflect/Cargo.toml index 2e57f15..f750aca 100644 --- a/librashader-reflect/Cargo.toml +++ b/librashader-reflect/Cargo.toml @@ -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"] diff --git a/librashader-runtime-d3d11/src/error.rs b/librashader-runtime-d3d11/src/error.rs index 2e4d1d1..f5c99bf 100644 --- a/librashader-runtime-d3d11/src/error.rs +++ b/librashader-runtime-d3d11/src/error.rs @@ -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 = std::result::Result; diff --git a/librashader-runtime-d3d12/Cargo.toml b/librashader-runtime-d3d12/Cargo.toml index 9ed79c1..1d32dbd 100644 --- a/librashader-runtime-d3d12/Cargo.toml +++ b/librashader-runtime-d3d12/Cargo.toml @@ -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 "] repository = "https://github.com/SnowflakePowered/librashader" readme = "../README.md" diff --git a/librashader-runtime-d3d12/src/error.rs b/librashader-runtime-d3d12/src/error.rs index 5fd4b6f..6020244 100644 --- a/librashader-runtime-d3d12/src/error.rs +++ b/librashader-runtime-d3d12/src/error.rs @@ -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 = std::result::Result; macro_rules! assume_d3d12_init { diff --git a/librashader-runtime-d3d12/src/filter_chain.rs b/librashader-runtime-d3d12/src/filter_chain.rs index 10a6854..9106a34 100644 --- a/librashader-runtime-d3d12/src/filter_chain.rs +++ b/librashader-runtime-d3d12/src/filter_chain.rs @@ -61,6 +61,7 @@ pub struct FilterMutable { pub(crate) parameters: FxHashMap, } +/// A Direct3D 12 filter chain. pub struct FilterChainD3D12 { pub(crate) common: FilterCommon, pub(crate) passes: Vec, @@ -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, diff --git a/librashader-runtime-d3d12/src/lib.rs b/librashader-runtime-d3d12/src/lib.rs index ac97de7..24040aa 100644 --- a/librashader-runtime-d3d12/src/lib.rs +++ b/librashader-runtime-d3d12/src/lib.rs @@ -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; diff --git a/librashader-runtime-d3d12/src/texture.rs b/librashader-runtime-d3d12/src/texture.rs index 3b6ed4e..733a36b 100644 --- a/librashader-runtime-d3d12/src/texture.rs +++ b/librashader-runtime-d3d12/src/texture.rs @@ -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 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, diff --git a/librashader-runtime-vk/src/filter_chain.rs b/librashader-runtime-vk/src/filter_chain.rs index a5905e1..edb3d2f 100644 --- a/librashader-runtime-vk/src/filter_chain.rs +++ b/librashader-runtime-vk/src/filter_chain.rs @@ -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 diff --git a/librashader/Cargo.toml b/librashader/Cargo.toml index 8d757a8..af45716 100644 --- a/librashader/Cargo.toml +++ b/librashader/Cargo.toml @@ -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 = [] diff --git a/librashader/src/lib.rs b/librashader/src/lib.rs index 85aca86..2958d3b 100644 --- a/librashader/src/lib.rs +++ b/librashader/src/lib.rs @@ -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+.