doc(d3d12): clean up docs for d3d12

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",

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
+librashader supports OpenGL 3, OpenGL 4.6, Vulkan, Direct3D 11, and Direct3D 12.  Older versions
-of DirectX and OpenGL, as well as Metal, are not supported (but pull-requests are welcome).
+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`                      |
+| Vulkan      | ✔          | `vk`                      |
 | Direct3D 11 | ✔          | `d3d11`                   |
-| Direct3D12  | 🚧         | `d3d12`                   |
+| 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)
+* [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#L34)
+* [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#L33)
+* [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,
+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.
 
 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.
 

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"]

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 <ronny@ronnychan.ca>"]
 repository = "https://github.com/SnowflakePowered/librashader"
 readme = "../README.md"

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<T> = std::result::Result<T, FilterChainError>;
 
 macro_rules! assume_d3d12_init {

librashader-runtime-d3d12/src/filter_chain.rs

@@ -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,

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;
 

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<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,

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 input image must be in the `VK_SHADER_READ_ONLY_OPTIMAL` layout.
-    /// * The output image must be in `VK_COLOR_ATTACHMENT_OPTIMAL`.
+    /// * 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

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 = []

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.
+//! Currently available runtimes are Vulkan, OpenGL 3.3+ and 4.6 (with DSA), Direct3D 11, and Direct3D 12.
-//! 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)
+//!
+//! 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+.