Make stencil_usage an Option (#2276)

* Make stencil_usage an Option

* Small doc fixes

vulkano/src/command_buffer/commands/clear.rs

@@ -969,7 +969,10 @@ impl ClearDepthStencilImageInfo {
  }
 
  if subresource_range.aspects.intersects(ImageAspects::STENCIL)
- && !image.stencil_usage().intersects(ImageUsage::TRANSFER_DST)
+ && !image
+ .stencil_usage()
+ .unwrap_or(image.usage())
+ .intersects(ImageUsage::TRANSFER_DST)
  {
  return Err(Box::new(ValidationError {
  problem: format!(

vulkano/src/command_buffer/commands/copy.rs

@@ -3012,6 +3012,7 @@ impl CopyImageInfo {
  if src_subresource.aspects.intersects(ImageAspects::STENCIL)
  && !src_image
  .stencil_usage()
+ .unwrap_or(src_image.usage())
  .intersects(ImageUsage::TRANSFER_SRC)
  {
  return Err(Box::new(ValidationError {
@@ -3379,6 +3380,7 @@ impl CopyImageInfo {
  if dst_subresource.aspects.intersects(ImageAspects::STENCIL)
  && !dst_image
  .stencil_usage()
+ .unwrap_or(dst_image.usage())
  .intersects(ImageUsage::TRANSFER_DST)
  {
  return Err(Box::new(ValidationError {

vulkano/src/device/physical.rs

@@ -14,8 +14,8 @@ use crate::{
  device::{properties::Properties, DeviceExtensions, Features, FeaturesFfi, PropertiesFfi},
  format::{DrmFormatModifierProperties, Format, FormatProperties},
  image::{
- ImageAspects, ImageDrmFormatModifierInfo, ImageFormatInfo, ImageFormatProperties,
- ImageUsage, SparseImageFormatInfo, SparseImageFormatProperties,
+ ImageDrmFormatModifierInfo, ImageFormatInfo, ImageFormatProperties, ImageUsage,
+ SparseImageFormatInfo, SparseImageFormatProperties,
  },
  instance::{Instance, InstanceOwned},
  macros::{impl_id_counter, vulkan_bitflags, vulkan_enum},
@@ -1017,25 +1017,8 @@ impl PhysicalDevice {
  #[inline]
  pub unsafe fn image_format_properties_unchecked(
  &self,
- mut image_format_info: ImageFormatInfo,
+ image_format_info: ImageFormatInfo,
  ) -> Result<Option<ImageFormatProperties>, VulkanError> {
- {
- let ImageFormatInfo {
- format,
- usage,
- stencil_usage,
- ..
- } = &mut image_format_info;
-
- let aspects = format.aspects();
-
- if stencil_usage.is_empty()
- || !aspects.contains(ImageAspects::DEPTH | ImageAspects::STENCIL)
- {
- *stencil_usage = *usage;
- }
- }
-
  self.image_format_properties
  .get_or_try_insert(image_format_info, |image_format_info| {
  /* Input */
@@ -1052,8 +1035,6 @@ impl PhysicalDevice {
  _ne: _,
  } = image_format_info;
 
- let has_separate_stencil_usage = stencil_usage != usage;
-
  let mut info2_vk = ash::vk::PhysicalDeviceImageFormatInfo2 {
  format: format.into(),
  ty: image_type.into(),
@@ -1121,7 +1102,7 @@ impl PhysicalDevice {
  info2_vk.p_next = next as *const _ as *const _;
  }
 
- if has_separate_stencil_usage {
+ if let Some(stencil_usage) = stencil_usage {
  let next = stencil_usage_info_vk.insert(ash::vk::ImageStencilUsageCreateInfo {
  stencil_usage: stencil_usage.into(),
  ..Default::default()

vulkano/src/image/mod.rs

@@ -217,7 +217,7 @@ impl Image {
  samples: SampleCount::Sample1,
  tiling: ImageTiling::Optimal,
  usage: swapchain.image_usage(),
- stencil_usage: swapchain.image_usage(),
+ stencil_usage: None,
  sharing: swapchain.image_sharing().clone(),
  initial_layout: ImageLayout::Undefined,
  ..Default::default()
@@ -323,7 +323,7 @@ impl Image {
 
  /// Returns the stencil usage the image was created with.
  #[inline]
- pub fn stencil_usage(&self) -> ImageUsage {
+ pub fn stencil_usage(&self) -> Option<ImageUsage> {
  self.inner.stencil_usage()
  }
 
@@ -1668,18 +1668,14 @@ pub struct ImageFormatInfo {
  /// The default value is [`ImageUsage::empty()`], which must be overridden.
  pub usage: ImageUsage,
 
- /// The `stencil_usage` that the image will have.
+ /// The `stencil_usage` that the image will have, if different from the regular `usage`.
  ///
- /// If `stencil_usage` is empty or if `format` does not have both a depth and a stencil aspect,
- /// then it is automatically set to equal `usage`.
- ///
- /// If after this, `stencil_usage` does not equal `usage`,
- /// then the physical device API version must be at least 1.2, or the
+ /// If this is `Some`, then the physical device API version must be at least 1.2, or the
  /// [`ext_separate_stencil_usage`](crate::device::DeviceExtensions::ext_separate_stencil_usage)
  /// extension must be supported by the physical device.
  ///
- /// The default value is [`ImageUsage::empty()`].
- pub stencil_usage: ImageUsage,
+ /// The default value is `None`.
+ pub stencil_usage: Option<ImageUsage>,
 
  /// An external memory handle type that will be imported to or exported from the image.
  ///
@@ -1724,7 +1720,7 @@ impl Default for ImageFormatInfo {
  image_type: ImageType::Dim2d,
  tiling: ImageTiling::Optimal,
  usage: ImageUsage::empty(),
- stencil_usage: ImageUsage::empty(),
+ stencil_usage: None,
  external_memory_handle_type: None,
  image_view_type: None,
  drm_format_modifier_info: None,
@@ -1744,7 +1740,7 @@ impl ImageFormatInfo {
  image_type,
  tiling,
  usage,
- mut stencil_usage,
+ stencil_usage,
  external_memory_handle_type,
  image_view_type,
  ref drm_format_modifier_info,
@@ -1800,28 +1796,15 @@ impl ImageFormatInfo {
  }));
  }
 
- let aspects = format.aspects();
-
- let has_separate_stencil_usage = if aspects
- .contains(ImageAspects::DEPTH | ImageAspects::STENCIL)
- && !stencil_usage.is_empty()
- {
- stencil_usage == usage
- } else {
- stencil_usage = usage;
- false
- };
-
- if has_separate_stencil_usage {
+ if let Some(stencil_usage) = stencil_usage {
  if !(physical_device.api_version() >= Version::V1_2
  || physical_device
  .supported_extensions()
  .ext_separate_stencil_usage)
  {
  return Err(Box::new(ValidationError {
- problem: "`stencil_usage` is `Some`, and `format` has both a depth and a \
- stencil aspect"
- .into(),
+ context: "stencil_usage".into(),
+ problem: "is `Some`".into(),
  requires_one_of: RequiresOneOf(&[
  RequiresAllOf(&[Requires::APIVersion(Version::V1_2)]),
  RequiresAllOf(&[Requires::DeviceExtension("ext_separate_stencil_usage")]),
@@ -1846,6 +1829,24 @@ impl ImageFormatInfo {
  ..Default::default()
  }));
  }
+
+ if stencil_usage.intersects(ImageUsage::TRANSIENT_ATTACHMENT)
+ && !(stencil_usage
+ - (ImageUsage::TRANSIENT_ATTACHMENT
+ | ImageUsage::DEPTH_STENCIL_ATTACHMENT
+ | ImageUsage::INPUT_ATTACHMENT))
+ .is_empty()
+ {
+ return Err(Box::new(ValidationError {
+ context: "stencil_usage".into(),
+ problem: "contains `ImageUsage::TRANSIENT_ATTACHMENT`, but also contains \
+ usages other than `ImageUsage::DEPTH_STENCIL_ATTACHMENT` or \
+ `ImageUsage::INPUT_ATTACHMENT`"
+ .into(),
+ vuids: &["VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539"],
+ ..Default::default()
+ }));
+ }
  }
 
  if let Some(handle_type) = external_memory_handle_type {