Implement TextureFormat::Stencil8 + add stencil example (#3343)

* Implement TextureFormat::Stencil8 * Add stencil-triangles demo to test Stencil8 and show how to use stencil testing * Added changelog for Stencil8
gfx-rs · Jan 2, 2023 · 186a29c · 186a29c
1 parent aa46e82
commit 186a29c
Show file tree

Hide file tree

Showing 21 changed files with 380 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -143,6 +143,7 @@ Additionally `Surface::get_default_config` now returns an Option and returns Non
 - Native adapters can now use MSAA x2 and x8 if it's supported , previously only x1 and x4 were supported . By @39ali in [3140](https://github.com/gfx-rs/wgpu/pull/3140)
 - Implemented correleation between user timestamps and platform specific presentation timestamps via [`Adapter::get_presentation_timestamp`]. By @cwfitzgerald in [#3240](https://github.com/gfx-rs/wgpu/pull/3240)
 - Added support for `Features::SHADER_PRIMITIVE_INDEX` on all backends. By @cwfitzgerald in [#3272](https://github.com/gfx-rs/wgpu/pull/3272)
+- Implemented `TextureFormat::Stencil8`, allowing for stencil testing without depth components. By @Dinnerbone in [#3343](https://github.com/gfx-rs/wgpu/pull/3343)
 
 #### GLES
 
@@ -205,6 +206,7 @@ Additionally `Surface::get_default_config` now returns an Option and returns Non
 ### Examples
 
 - Log adapter info in hello example on wasm target by @JolifantoBambla in [#2858](https://github.com/gfx-rs/wgpu/pull/2858)
+- Added new example `stencil-triangles` to show basic use of stencil testing. By @Dinnerbone in [#3343](https://github.com/gfx-rs/wgpu/pull/3343)
 
 ### Testing/Internal
 

diff --git a/wgpu-core/src/command/transfer.rs b/wgpu-core/src/command/transfer.rs
@@ -331,8 +331,8 @@ pub(crate) fn validate_texture_copy_range(
     let extent = extent_virtual.physical_size(desc.format);
 
     match desc.format {
-        //wgt::TextureFormat::Stencil8 |
-        wgt::TextureFormat::Depth16Unorm
+        wgt::TextureFormat::Stencil8
+        | wgt::TextureFormat::Depth16Unorm
         | wgt::TextureFormat::Depth32Float
         | wgt::TextureFormat::Depth32FloatStencil8
         | wgt::TextureFormat::Depth24Plus

diff --git a/wgpu-core/src/validation.rs b/wgpu-core/src/validation.rs
@@ -705,8 +705,8 @@ impl NumericType {
                 (NumericDimension::Vector(Vs::Quad), Sk::Sint)
             }
             Tf::Rg11b10Float => (NumericDimension::Vector(Vs::Tri), Sk::Float),
-            //Tf::Stencil8 |
-            Tf::Depth16Unorm
+            Tf::Stencil8
+            | Tf::Depth16Unorm
             | Tf::Depth32Float
             | Tf::Depth32FloatStencil8
             | Tf::Depth24Plus

diff --git a/wgpu-hal/src/auxil/dxgi/conv.rs b/wgpu-hal/src/auxil/dxgi/conv.rs
@@ -47,7 +47,7 @@ pub fn map_texture_format_failable(format: wgt::TextureFormat) -> Option<dxgifor
         Tf::Rgba32Uint => DXGI_FORMAT_R32G32B32A32_UINT,
         Tf::Rgba32Sint => DXGI_FORMAT_R32G32B32A32_SINT,
         Tf::Rgba32Float => DXGI_FORMAT_R32G32B32A32_FLOAT,
-        // Tf::Stencil8 => DXGI_FORMAT_D24_UNORM_S8_UINT,
+        Tf::Stencil8 => DXGI_FORMAT_D24_UNORM_S8_UINT,
         Tf::Depth16Unorm => DXGI_FORMAT_D16_UNORM,
         Tf::Depth24Plus => DXGI_FORMAT_D24_UNORM_S8_UINT,
         Tf::Depth24PlusStencil8 => DXGI_FORMAT_D24_UNORM_S8_UINT,
@@ -109,9 +109,9 @@ pub fn map_texture_format_nodepth(format: wgt::TextureFormat) -> dxgiformat::DXG
         wgt::TextureFormat::Depth32FloatStencil8 => {
             dxgiformat::DXGI_FORMAT_R32_FLOAT_X8X24_TYPELESS
         }
-        wgt::TextureFormat::Depth24Plus | wgt::TextureFormat::Depth24PlusStencil8 => {
-            dxgiformat::DXGI_FORMAT_R24_UNORM_X8_TYPELESS
-        }
+        wgt::TextureFormat::Stencil8
+        | wgt::TextureFormat::Depth24Plus
+        | wgt::TextureFormat::Depth24PlusStencil8 => dxgiformat::DXGI_FORMAT_R24_UNORM_X8_TYPELESS,
         _ => {
             assert_eq!(
                 crate::FormatAspects::from(format),
@@ -127,6 +127,7 @@ pub fn map_texture_format_depth_typeless(format: wgt::TextureFormat) -> dxgiform
         wgt::TextureFormat::Depth16Unorm => dxgiformat::DXGI_FORMAT_R16_TYPELESS,
         wgt::TextureFormat::Depth32Float => dxgiformat::DXGI_FORMAT_R32_TYPELESS,
         wgt::TextureFormat::Depth32FloatStencil8 => dxgiformat::DXGI_FORMAT_R32G8X24_TYPELESS,
+        wgt::TextureFormat::Stencil8 => dxgiformat::DXGI_FORMAT_R24G8_TYPELESS,
         wgt::TextureFormat::Depth24Plus | wgt::TextureFormat::Depth24PlusStencil8 => {
             dxgiformat::DXGI_FORMAT_R24G8_TYPELESS
         }

diff --git a/wgpu-hal/src/gles/adapter.rs b/wgpu-hal/src/gles/adapter.rs
@@ -786,8 +786,8 @@ impl crate::Adapter<super::Api> for super::Adapter {
             Tf::Rgba32Uint => renderable | storage,
             Tf::Rgba32Sint => renderable | storage,
             Tf::Rgba32Float => unfilterable | storage | float_renderable | texture_float_linear,
-            //Tf::Stencil8 |
-            Tf::Depth16Unorm
+            Tf::Stencil8
+            | Tf::Depth16Unorm
             | Tf::Depth32Float
             | Tf::Depth32FloatStencil8
             | Tf::Depth24Plus

diff --git a/wgpu-hal/src/gles/conv.rs b/wgpu-hal/src/gles/conv.rs
@@ -56,7 +56,11 @@ impl super::AdapterShared {
             Tf::Rgba32Uint => (glow::RGBA32UI, glow::RGBA_INTEGER, glow::UNSIGNED_INT),
             Tf::Rgba32Sint => (glow::RGBA32I, glow::RGBA_INTEGER, glow::INT),
             Tf::Rgba32Float => (glow::RGBA32F, glow::RGBA, glow::FLOAT),
-            //Tf::Stencil8 => (glow::R8UI, glow::STENCIL_COMPONENTS, glow::UNSIGNED_BYTE),
+            Tf::Stencil8 => (
+                glow::STENCIL_INDEX8,
+                glow::STENCIL_COMPONENTS,
+                glow::UNSIGNED_BYTE,
+            ),
             Tf::Depth16Unorm => (
                 glow::DEPTH_COMPONENT16,
                 glow::DEPTH_COMPONENT,

diff --git a/wgpu-hal/src/lib.rs b/wgpu-hal/src/lib.rs
@@ -636,7 +636,7 @@ impl From<wgt::TextureAspect> for FormatAspects {
 impl From<wgt::TextureFormat> for FormatAspects {
     fn from(format: wgt::TextureFormat) -> Self {
         match format {
-            //wgt::TextureFormat::Stencil8 => Self::STENCIL,
+            wgt::TextureFormat::Stencil8 => Self::STENCIL,
             wgt::TextureFormat::Depth16Unorm => Self::DEPTH,
             wgt::TextureFormat::Depth32Float | wgt::TextureFormat::Depth24Plus => Self::DEPTH,
             wgt::TextureFormat::Depth32FloatStencil8 | wgt::TextureFormat::Depth24PlusStencil8 => {

diff --git a/wgpu-hal/src/metal/adapter.rs b/wgpu-hal/src/metal/adapter.rs
@@ -166,13 +166,9 @@ impl crate::Adapter<super::Api> for super::Adapter {
                 };
                 flags
             }
-            /*Tf::Stencil8 => {
-                let mut flags = all_caps
-                    | Tfc::DEPTH_STENCIL_ATTACHMENT
-                    | Tfc::MULTISAMPLE
-                    | msaa_resolve_apple3x_if;
-                flags
-            }*/
+            Tf::Stencil8 => {
+                all_caps | Tfc::DEPTH_STENCIL_ATTACHMENT | msaa_count | msaa_resolve_apple3x_if
+            }
             Tf::Depth16Unorm => {
                 let mut flags =
                     Tfc::DEPTH_STENCIL_ATTACHMENT | msaa_count | msaa_resolve_apple3x_if;
@@ -909,7 +905,7 @@ impl super::PrivateCapabilities {
             Tf::Rgba32Uint => RGBA32Uint,
             Tf::Rgba32Sint => RGBA32Sint,
             Tf::Rgba32Float => RGBA32Float,
-            //Tf::Stencil8 => R8Unorm,
+            Tf::Stencil8 => Stencil8,
             Tf::Depth16Unorm => Depth16Unorm,
             Tf::Depth32Float => Depth32Float,
             Tf::Depth32FloatStencil8 => Depth32Float_Stencil8,

diff --git a/wgpu-hal/src/vulkan/adapter.rs b/wgpu-hal/src/vulkan/adapter.rs
@@ -1016,6 +1016,13 @@ impl super::Instance {
                     .optimal_tiling_features
                     .contains(vk::FormatFeatureFlags::DEPTH_STENCIL_ATTACHMENT)
             },
+            texture_s8: unsafe {
+                self.shared
+                    .raw
+                    .get_physical_device_format_properties(phd, vk::Format::S8_UINT)
+                    .optimal_tiling_features
+                    .contains(vk::FormatFeatureFlags::DEPTH_STENCIL_ATTACHMENT)
+            },
             non_coherent_map_mask: phd_capabilities.properties.limits.non_coherent_atom_size - 1,
             can_present: true,
             //TODO: make configurable

diff --git a/wgpu-hal/src/vulkan/conv.rs b/wgpu-hal/src/vulkan/conv.rs
@@ -64,7 +64,15 @@ impl super::PrivateCapabilities {
                     F::D32_SFLOAT_S8_UINT
                 }
             }
-            //Tf::Stencil8 => F::R8_UNORM,
+            Tf::Stencil8 => {
+                if self.texture_s8 {
+                    F::S8_UINT
+                } else if self.texture_d24_s8 {
+                    F::D24_UNORM_S8_UINT
+                } else {
+                    F::D32_SFLOAT_S8_UINT
+                }
+            }
             Tf::Depth16Unorm => F::D16_UNORM,
             Tf::Rgb9e5Ufloat => F::E5B9G9R9_UFLOAT_PACK32,
             Tf::Bc1RgbaUnorm => F::BC1_RGBA_UNORM_BLOCK,

diff --git a/wgpu-hal/src/vulkan/mod.rs b/wgpu-hal/src/vulkan/mod.rs
@@ -160,6 +160,7 @@ struct PrivateCapabilities {
     timeline_semaphores: bool,
     texture_d24: bool,
     texture_d24_s8: bool,
+    texture_s8: bool,
     /// Ability to present contents to any screen. Only needed to work around broken platform configurations.
     can_present: bool,
     non_coherent_map_mask: wgt::BufferAddress,

diff --git a/wgpu-info/src/main.rs b/wgpu-info/src/main.rs
@@ -8,7 +8,7 @@ mod inner {
 
     // Lets keep these on one line
     #[rustfmt::skip]
-    const TEXTURE_FORMAT_LIST: [wgpu::TextureFormat; 113] = [
+    const TEXTURE_FORMAT_LIST: [wgpu::TextureFormat; 114] = [
         wgpu::TextureFormat::R8Unorm,
         wgpu::TextureFormat::R8Snorm,
         wgpu::TextureFormat::R8Uint,
@@ -50,7 +50,7 @@ mod inner {
         wgpu::TextureFormat::Rgba32Uint,
         wgpu::TextureFormat::Rgba32Sint,
         wgpu::TextureFormat::Rgba32Float,
-        //wgpu::TextureFormat::Stencil8,
+        wgpu::TextureFormat::Stencil8,
         wgpu::TextureFormat::Depth16Unorm,
         wgpu::TextureFormat::Depth32Float,
         wgpu::TextureFormat::Depth32FloatStencil8,

diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
@@ -1929,7 +1929,7 @@ pub enum TextureFormat {
 
     // Depth and stencil formats
     /// Stencil format with 8 bit integer stencil.
-    //Stencil8,
+    Stencil8,
     /// Special depth format with 16 bit integer depth.
     Depth16Unorm,
     /// Special depth format with at least 24 bit integer depth.
@@ -2163,6 +2163,7 @@ impl<'de> Deserialize<'de> for TextureFormat {
                     "rgba32uint" => TextureFormat::Rgba32Uint,
                     "rgba32sint" => TextureFormat::Rgba32Sint,
                     "rgba32float" => TextureFormat::Rgba32Float,
+                    "stencil8" => TextureFormat::Stencil8,
                     "depth32float" => TextureFormat::Depth32Float,
                     "depth32float-stencil8" => TextureFormat::Depth32FloatStencil8,
                     "depth16unorm" => TextureFormat::Depth16Unorm,
@@ -2288,6 +2289,7 @@ impl Serialize for TextureFormat {
             TextureFormat::Rgba32Uint => "rgba32uint",
             TextureFormat::Rgba32Sint => "rgba32sint",
             TextureFormat::Rgba32Float => "rgba32float",
+            TextureFormat::Stencil8 => "stencil8",
             TextureFormat::Depth32Float => "depth32float",
             TextureFormat::Depth16Unorm => "depth16unorm",
             TextureFormat::Depth32FloatStencil8 => "depth32float-stencil8",
@@ -2443,6 +2445,7 @@ impl TextureFormat {
             Self::Rgba32Sint =>          (   native,    sint,    linear,         noaa, (1, 1), 16,  all_flags, 4),
             Self::Rgba32Float =>         (   native, nearest,    linear,         noaa, (1, 1), 16,  all_flags, 4),
             // Depth-stencil textures
+            Self::Stencil8 =>            (   native,   depth,    linear,         msaa, (1, 1),  2, attachment, 1),
             Self::Depth16Unorm =>        (   native,   depth,    linear,         msaa, (1, 1),  2, attachment, 1),
             Self::Depth24Plus =>         (   native,   depth,    linear,         msaa, (1, 1),  4, attachment, 1),
             Self::Depth24PlusStencil8 => (   native,   depth,    linear,         msaa, (1, 1),  4, attachment, 2),
@@ -2702,6 +2705,10 @@ fn texture_format_serialize() {
         serde_json::to_string(&TextureFormat::Rgba32Float).unwrap(),
         "\"rgba32float\"".to_string()
     );
+    assert_eq!(
+        serde_json::to_string(&TextureFormat::Stencil8).unwrap(),
+        "\"stencil8\"".to_string()
+    );
     assert_eq!(
         serde_json::to_string(&TextureFormat::Depth32Float).unwrap(),
         "\"depth32float\"".to_string()
@@ -2990,6 +2997,10 @@ fn texture_format_deserialize() {
         serde_json::from_str::<TextureFormat>("\"rgba32float\"").unwrap(),
         TextureFormat::Rgba32Float
     );
+    assert_eq!(
+        serde_json::from_str::<TextureFormat>("\"stencil8\"").unwrap(),
+        TextureFormat::Stencil8
+    );
     assert_eq!(
         serde_json::from_str::<TextureFormat>("\"depth32float\"").unwrap(),
         TextureFormat::Depth32Float

diff --git a/wgpu/Cargo.toml b/wgpu/Cargo.toml
@@ -75,6 +75,10 @@ test = true
 name = "water"
 test = true
 
+[[example]]
+name = "stencil-triangles"
+test = true
+
 [features]
 default = ["wgsl", "expose-ids"]
 # Apply run-time checks, even in release builds. These are in addition