Google Git
Sign in
android / platform / external / rust / android-crates-io / 3dc9e2472f59e995d5b002c65f593ad221729a69 / . / crates / vulkano / src / image / sys.rs
blob: 1933ffeeaa1400d20d8fa3ecc411273cab640ed3 [file] [log] [blame]
// Copyright (c) 2016 The vulkano developers
// Licensed under the Apache License, Version 2.0
// <LICENSE-APACHE or
// https://www.apache.org/licenses/LICENSE-2.0> or the MIT
// license <LICENSE-MIT or https://opensource.org/licenses/MIT>,
// at your option. All files in the project carrying such
// notice may not be copied, modified, or distributed except
// according to those terms.
//! Low-level implementation of images.
//!
//! This module contains low-level wrappers around the Vulkan image types. All
//! other image types of this library, and all custom image types
//! that you create must wrap around the types in this module.
use super::{
ImageAspect, ImageAspects, ImageCreateFlags, ImageDimensions, ImageLayout,
ImageSubresourceLayers, ImageSubresourceRange, ImageTiling, ImageUsage, SampleCount,
SampleCounts, SparseImageMemoryRequirements,
};
use crate::{
buffer::subbuffer::{ReadLockError, WriteLockError},
cache::OnceCache,
device::{Device, DeviceOwned},
format::{ChromaSampling, Format, FormatFeatures, NumericType},
image::{
view::ImageViewCreationError, ImageFormatInfo, ImageFormatProperties, ImageType,
SparseImageFormatProperties,
},
macros::impl_id_counter,
memory::{
allocator::{AllocationCreationError, AllocationType, DeviceLayout, MemoryAlloc},
is_aligned, DedicatedTo, DeviceAlignment, ExternalMemoryHandleType,
ExternalMemoryHandleTypes, MemoryPropertyFlags, MemoryRequirements,
},
range_map::RangeMap,
swapchain::Swapchain,
sync::{future::AccessError, CurrentAccess, Sharing},
DeviceSize, RequirementNotMet, RequiresOneOf, Version, VulkanError, VulkanObject,
};
use ash::vk::ImageDrmFormatModifierExplicitCreateInfoEXT;
use parking_lot::{Mutex, MutexGuard};
use smallvec::{smallvec, SmallVec};
use std::{
error::Error,
fmt::{Display, Error as FmtError, Formatter},
hash::{Hash, Hasher},
iter::{FusedIterator, Peekable},
mem::{size_of_val, MaybeUninit},
num::NonZeroU64,
ops::Range,
ptr,
sync::Arc,
};
/// A raw image, with no memory backing it.
///
/// This is the basic image type, a direct translation of a `VkImage` object, but it is mostly
/// useless in this form. After creating a raw image, you must call `bind_memory` to make a
/// complete image object.
#[derive(Debug)]
pub struct RawImage {
handle: ash::vk::Image,
device: Arc<Device>,
id: NonZeroU64,
flags: ImageCreateFlags,
dimensions: ImageDimensions,
format: Option<Format>,
format_features: FormatFeatures,
initial_layout: ImageLayout,
mip_levels: u32,
samples: SampleCount,
tiling: ImageTiling,
usage: ImageUsage,
sharing: Sharing<SmallVec<[u32; 4]>>,
stencil_usage: ImageUsage,
external_memory_handle_types: ExternalMemoryHandleTypes,
memory_requirements: SmallVec<[MemoryRequirements; 3]>,
needs_destruction: bool, // `vkDestroyImage` is called only if true.
subresource_layout: OnceCache<(ImageAspect, u32, u32), SubresourceLayout>,
}
impl RawImage {
/// Creates a new `RawImage`.
///
/// # Panics
///
/// - Panics if one of the values in `create_info.dimensions` is zero.
/// - Panics if `create_info.format` is `None`.
/// - Panics if `create_info.block_texel_view_compatible` is set but not
/// `create_info.mutable_format`.
/// - Panics if `create_info.mip_levels` is `0`.
/// - Panics if `create_info.sharing` is [`Sharing::Concurrent`] with less than 2 items.
/// - Panics if `create_info.initial_layout` is something other than
/// [`ImageLayout::Undefined`] or [`ImageLayout::Preinitialized`].
/// - Panics if `create_info.usage` is empty.
/// - Panics if `create_info.usage` contains `transient_attachment`, but does not also contain
/// at least one of `color_attachment`, `depth_stencil_attachment`, `input_attachment`, or
/// if it contains values other than these.
#[inline]
pub fn new(
device: Arc<Device>,
mut create_info: ImageCreateInfo,
) -> Result<RawImage, ImageError> {
match &mut create_info.sharing {
Sharing::Exclusive => (),
Sharing::Concurrent(queue_family_indices) => {
// VUID-VkImageCreateInfo-sharingMode-01420
queue_family_indices.sort_unstable();
queue_family_indices.dedup();
}
}
Self::validate_new(&device, &create_info)?;
unsafe { Ok(RawImage::new_unchecked(device, create_info)?) }
}
fn validate_new(
device: &Device,
create_info: &ImageCreateInfo,
) -> Result<FormatFeatures, ImageError> {
let &ImageCreateInfo {
flags,
dimensions,
format,
mip_levels,
samples,
tiling,
usage,
mut stencil_usage,
ref sharing,
initial_layout,
external_memory_handle_types,
_ne: _,
image_drm_format_modifier_create_info,
} = create_info;
let physical_device = device.physical_device();
let device_properties = physical_device.properties();
let format = format.unwrap(); // Can be None for "external formats" but Vulkano doesn't support that yet
let aspects = format.aspects();
let has_separate_stencil_usage = if stencil_usage.is_empty()
|| !aspects.contains(ImageAspects::DEPTH | ImageAspects::STENCIL)
{
stencil_usage = usage;
false
} else {
stencil_usage == usage
};
// VUID-VkImageCreateInfo-flags-parameter
flags.validate_device(device)?;
// VUID-VkImageCreateInfo-format-parameter
format.validate_device(device)?;
// VUID-VkImageCreateInfo-samples-parameter
samples.validate_device(device)?;
// VUID-VkImageCreateInfo-tiling-parameter
tiling.validate_device(device)?;
// VUID-VkImageCreateInfo-usage-parameter
usage.validate_device(device)?;
// VUID-VkImageCreateInfo-usage-requiredbitmask
assert!(!usage.is_empty());
if has_separate_stencil_usage {
if !(device.api_version() >= Version::V1_2
|| device.enabled_extensions().ext_separate_stencil_usage)
{
return Err(ImageError::RequirementNotMet {
required_for: "`create_info.stencil_usage` is `Some` and `create_info.format` \
has both a depth and a stencil aspect",
requires_one_of: RequiresOneOf {
api_version: Some(Version::V1_2),
device_extensions: &["ext_separate_stencil_usage"],
..Default::default()
},
});
}
// VUID-VkImageStencilUsageCreateInfo-stencilUsage-parameter
stencil_usage.validate_device(device)?;
// VUID-VkImageStencilUsageCreateInfo-usage-requiredbitmask
assert!(!stencil_usage.is_empty());
}
// VUID-VkImageCreateInfo-initialLayout-parameter
initial_layout.validate_device(device)?;
// VUID-VkImageCreateInfo-initialLayout-00993
assert!(matches!(
initial_layout,
ImageLayout::Undefined | ImageLayout::Preinitialized
));
// VUID-VkImageCreateInfo-flags-01573
assert!(
!flags.intersects(ImageCreateFlags::BLOCK_TEXEL_VIEW_COMPATIBLE)
|| flags.intersects(ImageCreateFlags::MUTABLE_FORMAT)
);
// VUID-VkImageCreateInfo-tiling-02261
// VUID-VkImageCreateInfo-pNext-02262
if (tiling == ImageTiling::DrmFormatModifier)
!= image_drm_format_modifier_create_info.is_some()
{
return Err(ImageError::DrmFormatModifierRequiresCreateInfo);
}
// Get format features
let format_features = {
// Use unchecked, because all validation has been done above.
let format_properties = unsafe { physical_device.format_properties_unchecked(format) };
match tiling {
ImageTiling::Linear => format_properties.linear_tiling_features,
ImageTiling::Optimal => format_properties.optimal_tiling_features,
ImageTiling::DrmFormatModifier => format_properties.linear_tiling_features, // TODO: Improve
}
};
// TODO: VUID-VkImageCreateInfo-tiling-02353
// Vulkano currently has no high-level way to add or check for VkImageFormatListCreateInfo.
// Format isn't supported at all?
if format_features.is_empty() {
return Err(ImageError::FormatNotSupported);
}
// Decode the dimensions
let (image_type, extent, array_layers) = match dimensions {
ImageDimensions::Dim1d {
width,
array_layers,
} => (ImageType::Dim1d, [width, 1, 1], array_layers),
ImageDimensions::Dim2d {
width,
height,
array_layers,
} => (ImageType::Dim2d, [width, height, 1], array_layers),
ImageDimensions::Dim3d {
width,
height,
depth,
} => (ImageType::Dim3d, [width, height, depth], 1),
};
// VUID-VkImageCreateInfo-extent-00944
assert!(extent[0] != 0);
// VUID-VkImageCreateInfo-extent-00945
assert!(extent[1] != 0);
// VUID-VkImageCreateInfo-extent-00946
assert!(extent[2] != 0);
// VUID-VkImageCreateInfo-arrayLayers-00948
assert!(array_layers != 0);
// VUID-VkImageCreateInfo-mipLevels-00947
assert!(mip_levels != 0);
// Check mip levels
let max_mip_levels = dimensions.max_mip_levels();
debug_assert!(max_mip_levels >= 1);
// VUID-VkImageCreateInfo-mipLevels-00958
if mip_levels > max_mip_levels {
return Err(ImageError::MaxMipLevelsExceeded {
mip_levels,
max: max_mip_levels,
});
}
// VUID-VkImageCreateInfo-samples-02257
if samples != SampleCount::Sample1 {
if image_type != ImageType::Dim2d {
return Err(ImageError::MultisampleNot2d);
}
if flags.intersects(ImageCreateFlags::CUBE_COMPATIBLE) {
return Err(ImageError::MultisampleCubeCompatible);
}
if mip_levels != 1 {
return Err(ImageError::MultisampleMultipleMipLevels);
}
if tiling == ImageTiling::Linear {
return Err(ImageError::MultisampleLinearTiling);
}
// VUID-VkImageCreateInfo-multisampleArrayImage-04460
if device.enabled_extensions().khr_portability_subset
&& !device.enabled_features().multisample_array_image
&& array_layers != 1
{
return Err(ImageError::RequirementNotMet {
required_for: "this device is a portability subset device, \
`create_info.samples` is not `SampleCount::Sample1` and \
`create_info.dimensions.array_layers()` is greater than `1`",
requires_one_of: RequiresOneOf {
features: &["multisample_array_image"],
..Default::default()
},
});
}
}
// Check limits for YCbCr formats
if let Some(chroma_sampling) = format.ycbcr_chroma_sampling() {
// VUID-VkImageCreateInfo-format-06410
if mip_levels != 1 {
return Err(ImageError::YcbcrFormatMultipleMipLevels);
}
// VUID-VkImageCreateInfo-format-06411
if samples != SampleCount::Sample1 {
return Err(ImageError::YcbcrFormatMultisampling);
}
// VUID-VkImageCreateInfo-format-06412
if image_type != ImageType::Dim2d {
return Err(ImageError::YcbcrFormatNot2d);
}
// VUID-VkImageCreateInfo-format-06413
if array_layers > 1 && !device.enabled_features().ycbcr_image_arrays {
return Err(ImageError::RequirementNotMet {
required_for: "`create_info.format.ycbcr_chroma_sampling()` is `Some` and \
`create_info.dimensions.array_layers()` is greater than `1`",
requires_one_of: RequiresOneOf {
features: &["ycbcr_image_arrays"],
..Default::default()
},
});
}
match chroma_sampling {
ChromaSampling::Mode444 => (),
ChromaSampling::Mode422 => {
// VUID-VkImageCreateInfo-format-04712
if extent[0] % 2 != 0 {
return Err(ImageError::YcbcrFormatInvalidDimensions);
}
}
ChromaSampling::Mode420 => {
// VUID-VkImageCreateInfo-format-04712
// VUID-VkImageCreateInfo-format-04713
if !(extent[0] % 2 == 0 && extent[1] % 2 == 0) {
return Err(ImageError::YcbcrFormatInvalidDimensions);
}
}
}
}
/* Check usage requirements */
let combined_usage = usage | stencil_usage;
if combined_usage.intersects(ImageUsage::SAMPLED)
&& !format_features.intersects(FormatFeatures::SAMPLED_IMAGE)
{
return Err(ImageError::FormatUsageNotSupported { usage: "sampled" });
}
if combined_usage.intersects(ImageUsage::COLOR_ATTACHMENT)
&& !format_features.intersects(FormatFeatures::COLOR_ATTACHMENT)
{
return Err(ImageError::FormatUsageNotSupported {
usage: "color_attachment",
});
}
if combined_usage.intersects(ImageUsage::DEPTH_STENCIL_ATTACHMENT)
&& !format_features.intersects(FormatFeatures::DEPTH_STENCIL_ATTACHMENT)
{
return Err(ImageError::FormatUsageNotSupported {
usage: "depth_stencil_attachment",
});
}
if combined_usage.intersects(ImageUsage::INPUT_ATTACHMENT)
&& !format_features.intersects(
FormatFeatures::COLOR_ATTACHMENT | FormatFeatures::DEPTH_STENCIL_ATTACHMENT,
)
{
return Err(ImageError::FormatUsageNotSupported {
usage: "input_attachment",
});
}
if combined_usage.intersects(
ImageUsage::COLOR_ATTACHMENT
| ImageUsage::DEPTH_STENCIL_ATTACHMENT
| ImageUsage::INPUT_ATTACHMENT
| ImageUsage::TRANSIENT_ATTACHMENT,
) {
// VUID-VkImageCreateInfo-usage-00964
// VUID-VkImageCreateInfo-usage-00965
// VUID-VkImageCreateInfo-Format-02536
// VUID-VkImageCreateInfo-format-02537
if extent[0] > device_properties.max_framebuffer_width
|| extent[1] > device_properties.max_framebuffer_height
{
return Err(ImageError::MaxFramebufferDimensionsExceeded {
extent: [extent[0], extent[1]],
max: [
device_properties.max_framebuffer_width,
device_properties.max_framebuffer_height,
],
});
}
}
if combined_usage.intersects(ImageUsage::STORAGE) {
if !format_features.intersects(FormatFeatures::STORAGE_IMAGE) {
return Err(ImageError::FormatUsageNotSupported { usage: "storage" });
}
// VUID-VkImageCreateInfo-usage-00968
// VUID-VkImageCreateInfo-format-02538
if !device.enabled_features().shader_storage_image_multisample
&& samples != SampleCount::Sample1
{
return Err(ImageError::RequirementNotMet {
required_for: "`create_info.usage` or `create_info.stencil_usage` contains \
`ImageUsage::STORAGE`, and `create_info.samples` is not \
`SampleCount::Sample1`",
requires_one_of: RequiresOneOf {
features: &["shader_storage_image_multisample"],
..Default::default()
},
});
}
}
// These flags only exist in later versions, ignore them otherwise
if device.api_version() >= Version::V1_1 || device.enabled_extensions().khr_maintenance1 {
if combined_usage.intersects(ImageUsage::TRANSFER_SRC)
&& !format_features.intersects(FormatFeatures::TRANSFER_SRC)
{
return Err(ImageError::FormatUsageNotSupported {
usage: "transfer_src",
});
}
if combined_usage.intersects(ImageUsage::TRANSFER_DST)
&& !format_features.intersects(FormatFeatures::TRANSFER_DST)
{
return Err(ImageError::FormatUsageNotSupported {
usage: "transfer_dst",
});
}
}
if usage.intersects(ImageUsage::TRANSIENT_ATTACHMENT) {
// VUID-VkImageCreateInfo-usage-00966
assert!(usage.intersects(
ImageUsage::COLOR_ATTACHMENT
| ImageUsage::DEPTH_STENCIL_ATTACHMENT
| ImageUsage::INPUT_ATTACHMENT
));
// VUID-VkImageCreateInfo-usage-00963
assert!((usage
- (ImageUsage::TRANSIENT_ATTACHMENT
| ImageUsage::COLOR_ATTACHMENT
| ImageUsage::DEPTH_STENCIL_ATTACHMENT
| ImageUsage::INPUT_ATTACHMENT))
.is_empty())
}
if has_separate_stencil_usage {
// VUID-VkImageCreateInfo-format-02795
// VUID-VkImageCreateInfo-format-02796
if usage.intersects(ImageUsage::DEPTH_STENCIL_ATTACHMENT)
!= stencil_usage.intersects(ImageUsage::DEPTH_STENCIL_ATTACHMENT)
{
return Err(ImageError::StencilUsageMismatch {
usage,
stencil_usage,
});
}
// VUID-VkImageCreateInfo-format-02797
// VUID-VkImageCreateInfo-format-02798
if usage.intersects(ImageUsage::TRANSIENT_ATTACHMENT)
!= stencil_usage.intersects(ImageUsage::TRANSIENT_ATTACHMENT)
{
return Err(ImageError::StencilUsageMismatch {
usage,
stencil_usage,
});
}
if stencil_usage.intersects(ImageUsage::TRANSIENT_ATTACHMENT) {
// VUID-VkImageStencilUsageCreateInfo-stencilUsage-02539
assert!((stencil_usage
- (ImageUsage::TRANSIENT_ATTACHMENT
| ImageUsage::DEPTH_STENCIL_ATTACHMENT
| ImageUsage::INPUT_ATTACHMENT))
.is_empty())
}
}
/* Check flags requirements */
if flags.intersects(ImageCreateFlags::CUBE_COMPATIBLE) {
// VUID-VkImageCreateInfo-flags-00949
if image_type != ImageType::Dim2d {
return Err(ImageError::CubeCompatibleNot2d);
}
// VUID-VkImageCreateInfo-imageType-00954
if extent[0] != extent[1] {
return Err(ImageError::CubeCompatibleNotSquare);
}
// VUID-VkImageCreateInfo-imageType-00954
if array_layers < 6 {
return Err(ImageError::CubeCompatibleNotEnoughArrayLayers);
}
}
if flags.intersects(ImageCreateFlags::ARRAY_2D_COMPATIBLE) {
// VUID-VkImageCreateInfo-flags-00950
if image_type != ImageType::Dim3d {
return Err(ImageError::Array2dCompatibleNot3d);
}
// VUID-VkImageCreateInfo-imageView2DOn3DImage-04459
if device.enabled_extensions().khr_portability_subset
&& !device.enabled_features().image_view2_d_on3_d_image
{
return Err(ImageError::RequirementNotMet {
required_for: "this device is a portability subset device, and \
`create_info.flags` contains `ImageCreateFlags::ARRAY_2D_COMPATIBLE`",
requires_one_of: RequiresOneOf {
features: &["image_view2_d_on3_d_image"],
..Default::default()
},
});
}
}
if flags.intersects(ImageCreateFlags::BLOCK_TEXEL_VIEW_COMPATIBLE) {
// VUID-VkImageCreateInfo-flags-01572
if format.compression().is_none() {
return Err(ImageError::BlockTexelViewCompatibleNotCompressed);
}
}
if flags.intersects(ImageCreateFlags::DISJOINT) {
// VUID-VkImageCreateInfo-format-01577
if format.planes().len() < 2 {
return Err(ImageError::DisjointFormatNotSupported);
}
// VUID-VkImageCreateInfo-imageCreateFormatFeatures-02260
if !format_features.intersects(FormatFeatures::DISJOINT) {
return Err(ImageError::DisjointFormatNotSupported);
}
}
/* Check sharing mode and queue families */
match sharing {
Sharing::Exclusive => (),
Sharing::Concurrent(queue_family_indices) => {
// VUID-VkImageCreateInfo-sharingMode-00942
assert!(queue_family_indices.len() >= 2);
for &queue_family_index in queue_family_indices {
// VUID-VkImageCreateInfo-sharingMode-01420
if queue_family_index
>= device.physical_device().queue_family_properties().len() as u32
{
return Err(ImageError::SharingQueueFamilyIndexOutOfRange {
queue_family_index,
queue_family_count: device
.physical_device()
.queue_family_properties()
.len() as u32,
});
}
}
}
}
/* External memory handles */
if !external_memory_handle_types.is_empty() {
if !(device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_external_memory)
{
return Err(ImageError::RequirementNotMet {
required_for: "`create_info.external_memory_handle_types` is not empty",
requires_one_of: RequiresOneOf {
api_version: Some(Version::V1_1),
device_extensions: &["khr_external_memory"],
..Default::default()
},
});
}
// VUID-VkExternalMemoryImageCreateInfo-handleTypes-parameter
external_memory_handle_types.validate_device(device)?;
// VUID-VkImageCreateInfo-pNext-01443
if initial_layout != ImageLayout::Undefined {
return Err(ImageError::ExternalMemoryInvalidInitialLayout);
}
}
/*
Some device limits can be exceeded, but only for particular image configurations, which
must be queried with `image_format_properties`. See:
https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap44.html#capabilities-image
First, we check if this is the case, then query the device if so.
*/
// https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap44.html#features-extentperimagetype
let extent_must_query = || match image_type {
ImageType::Dim1d => {
let limit = device.physical_device().properties().max_image_dimension1_d;
extent[0] > limit
}
ImageType::Dim2d if flags.intersects(ImageCreateFlags::CUBE_COMPATIBLE) => {
let limit = device
.physical_device()
.properties()
.max_image_dimension_cube;
extent[0] > limit
}
ImageType::Dim2d => {
let limit = device.physical_device().properties().max_image_dimension2_d;
extent[0] > limit || extent[1] > limit
}
ImageType::Dim3d => {
let limit = device.physical_device().properties().max_image_dimension3_d;
extent[0] > limit || extent[1] > limit || extent[2] > limit
}
};
// https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageFormatProperties.html
let mip_levels_must_query = || {
if mip_levels > 1 {
// TODO: for external memory, the spec says:
// "handle type included in the handleTypes member for which mipmap image support is
// not required". But which handle types are those?
!external_memory_handle_types.is_empty()
} else {
false
}
};
// https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageFormatProperties.html
let array_layers_must_query = || {
if array_layers > device.physical_device().properties().max_image_array_layers {
true
} else if array_layers > 1 {
image_type == ImageType::Dim3d
} else {
false
}
};
// https://registry.khronos.org/vulkan/specs/1.3-extensions/html/chap44.html#features-supported-sample-counts
let samples_must_query = || {
if samples == SampleCount::Sample1 {
return false;
}
if combined_usage.intersects(ImageUsage::COLOR_ATTACHMENT)
&& !device_properties
.framebuffer_color_sample_counts
.contains_enum(samples)
{
// TODO: how to handle framebuffer_integer_color_sample_counts limit, which only
// exists >= Vulkan 1.2
return true;
}
if combined_usage.intersects(ImageUsage::DEPTH_STENCIL_ATTACHMENT) {
if aspects.intersects(ImageAspects::DEPTH)
&& !device_properties
.framebuffer_depth_sample_counts
.contains_enum(samples)
{
return true;
}
if aspects.intersects(ImageAspects::STENCIL)
&& !device_properties
.framebuffer_stencil_sample_counts
.contains_enum(samples)
{
return true;
}
}
if combined_usage.intersects(ImageUsage::SAMPLED) {
if let Some(numeric_type) = format.type_color() {
match numeric_type {
NumericType::UINT | NumericType::SINT => {
if !device_properties
.sampled_image_integer_sample_counts
.contains_enum(samples)
{
return true;
}
}
NumericType::SFLOAT
| NumericType::UFLOAT
| NumericType::SNORM
| NumericType::UNORM
| NumericType::SSCALED
| NumericType::USCALED
| NumericType::SRGB => {
if !device_properties
.sampled_image_color_sample_counts
.contains_enum(samples)
{
return true;
}
}
}
} else {
if aspects.intersects(ImageAspects::DEPTH)
&& !device_properties
.sampled_image_depth_sample_counts
.contains_enum(samples)
{
return true;
}
if aspects.intersects(ImageAspects::STENCIL)
&& device_properties
.sampled_image_stencil_sample_counts
.contains_enum(samples)
{
return true;
}
}
}
if combined_usage.intersects(ImageUsage::STORAGE)
&& !device_properties
.storage_image_sample_counts
.contains_enum(samples)
{
return true;
}
false
};
// https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VkImageCreateInfo.html#_description
let linear_must_query = || {
if tiling == ImageTiling::Linear {
!(image_type == ImageType::Dim2d
&& format.type_color().is_some()
&& mip_levels == 1
&& array_layers == 1
// VUID-VkImageCreateInfo-samples-02257 already states that multisampling+linear
// is invalid so no need to check for that here.
&& (usage - (ImageUsage::TRANSFER_SRC | ImageUsage::TRANSFER_DST)).is_empty())
} else {
false
}
};
let must_query_device = extent_must_query()
|| mip_levels_must_query()
|| array_layers_must_query()
|| samples_must_query()
|| linear_must_query();
// We determined that we must query the device in order to be sure that the image
// configuration is supported.
if must_query_device {
let external_memory_handle_types: SmallVec<[Option<ExternalMemoryHandleType>; 4]> =
if !external_memory_handle_types.is_empty() {
// If external memory handles are used, the properties need to be queried
// individually for each handle type.
external_memory_handle_types.into_iter().map(Some).collect()
} else {
smallvec![None]
};
for external_memory_handle_type in external_memory_handle_types {
// Use unchecked, because all validation has been done above.
let image_format_properties = unsafe {
device
.physical_device()
.image_format_properties_unchecked(ImageFormatInfo {
flags,
format: Some(format),
image_type,
tiling,
usage,
external_memory_handle_type,
..Default::default()
})?
};
let ImageFormatProperties {
max_extent,
max_mip_levels,
max_array_layers,
sample_counts,
max_resource_size: _,
..
} = match image_format_properties {
Some(x) => x,
None => return Err(ImageError::ImageFormatPropertiesNotSupported),
};
// VUID-VkImageCreateInfo-extent-02252
// VUID-VkImageCreateInfo-extent-02253
// VUID-VkImageCreateInfo-extent-02254
if extent[0] > max_extent[0]
|| extent[1] > max_extent[1]
|| extent[2] > max_extent[2]
{
return Err(ImageError::MaxDimensionsExceeded {
extent,
max: max_extent,
});
}
// VUID-VkImageCreateInfo-mipLevels-02255
if mip_levels > max_mip_levels {
return Err(ImageError::MaxMipLevelsExceeded {
mip_levels,
max: max_mip_levels,
});
}
// VUID-VkImageCreateInfo-arrayLayers-02256
if array_layers > max_array_layers {
return Err(ImageError::MaxArrayLayersExceeded {
array_layers,
max: max_array_layers,
});
}
// VUID-VkImageCreateInfo-samples-02258
if !sample_counts.contains_enum(samples) {
return Err(ImageError::SampleCountNotSupported {
samples,
supported: sample_counts,
});
}
// TODO: check resource size?
}
}
Ok(format_features)
}
#[cfg_attr(not(feature = "document_unchecked"), doc(hidden))]
#[inline]
pub unsafe fn new_unchecked(
device: Arc<Device>,
create_info: ImageCreateInfo,
) -> Result<Self, VulkanError> {
let &ImageCreateInfo {
flags,
dimensions,
format,
mip_levels,
samples,
tiling,
usage,
mut stencil_usage,
ref sharing,
initial_layout,
external_memory_handle_types,
_ne: _,
mut image_drm_format_modifier_create_info,
} = &create_info;
let aspects = format.map_or_else(Default::default, |format| format.aspects());
let has_separate_stencil_usage = if stencil_usage.is_empty()
|| !aspects.contains(ImageAspects::DEPTH | ImageAspects::STENCIL)
{
stencil_usage = usage;
false
} else {
stencil_usage == usage
};
let (image_type, extent, array_layers) = match dimensions {
ImageDimensions::Dim1d {
width,
array_layers,
} => (ImageType::Dim1d, [width, 1, 1], array_layers),
ImageDimensions::Dim2d {
width,
height,
array_layers,
} => (ImageType::Dim2d, [width, height, 1], array_layers),
ImageDimensions::Dim3d {
width,
height,
depth,
} => (ImageType::Dim3d, [width, height, depth], 1),
};
let (sharing_mode, queue_family_index_count, p_queue_family_indices) = match sharing {
Sharing::Exclusive => (ash::vk::SharingMode::EXCLUSIVE, 0, &[] as _),
Sharing::Concurrent(queue_family_indices) => (
ash::vk::SharingMode::CONCURRENT,
queue_family_indices.len() as u32,
queue_family_indices.as_ptr(),
),
};
let mut info_vk = ash::vk::ImageCreateInfo {
flags: flags.into(),
image_type: image_type.into(),
format: format.map(Into::into).unwrap_or_default(),
extent: ash::vk::Extent3D {
width: extent[0],
height: extent[1],
depth: extent[2],
},
mip_levels,
array_layers,
samples: samples.into(),
tiling: tiling.into(),
usage: usage.into(),
sharing_mode,
queue_family_index_count,
p_queue_family_indices,
initial_layout: initial_layout.into(),
..Default::default()
};
let mut external_memory_info_vk = None;
let mut stencil_usage_info_vk = None;
if !external_memory_handle_types.is_empty() {
let next = external_memory_info_vk.insert(ash::vk::ExternalMemoryImageCreateInfo {
handle_types: external_memory_handle_types.into(),
..Default::default()
});
next.p_next = info_vk.p_next;
info_vk.p_next = next as *const _ as *const _;
}
if has_separate_stencil_usage {
let next = stencil_usage_info_vk.insert(ash::vk::ImageStencilUsageCreateInfo {
stencil_usage: stencil_usage.into(),
..Default::default()
});
next.p_next = info_vk.p_next;
info_vk.p_next = next as *const _ as *const _;
}
if external_memory_handle_types.intersects(ExternalMemoryHandleTypes::DMA_BUF) {
let next = image_drm_format_modifier_create_info.as_mut().unwrap();
next.p_next = info_vk.p_next;
info_vk.p_next = next as *const _ as *const _;
}
let handle = {
let fns = device.fns();
let mut output = MaybeUninit::uninit();
(fns.v1_0.create_image)(device.handle(), &info_vk, ptr::null(), output.as_mut_ptr())
.result()
.map_err(VulkanError::from)?;
output.assume_init()
};
Ok(Self::from_handle(device, handle, create_info))
}
/// Creates a new `RawImage` from a raw object handle.
///
/// # Safety
///
/// - `handle` must be a valid Vulkan object handle created from `device`.
/// - `handle` must refer to an image that has not yet had memory bound to it.
/// - `create_info` must match the info used to create the object.
#[inline]
pub unsafe fn from_handle(
device: Arc<Device>,
handle: ash::vk::Image,
create_info: ImageCreateInfo,
) -> Self {
Self::from_handle_with_destruction(device, handle, create_info, true)
}
unsafe fn from_handle_with_destruction(
device: Arc<Device>,
handle: ash::vk::Image,
create_info: ImageCreateInfo,
needs_destruction: bool,
) -> Self {
let ImageCreateInfo {
flags,
dimensions,
format,
mip_levels,
samples,
tiling,
usage,
mut stencil_usage,
sharing,
initial_layout,
external_memory_handle_types,
_ne: _,
image_drm_format_modifier_create_info: _,
} = create_info;
let aspects = format.map_or_else(Default::default, |format| format.aspects());
if stencil_usage.is_empty()
|| !aspects.contains(ImageAspects::DEPTH | ImageAspects::STENCIL)
{
stencil_usage = usage;
}
// Get format features
let format_features = {
// Use unchecked, because `create_info` is assumed to match the info of the handle, and
// therefore already valid.
let format_properties = device
.physical_device()
.format_properties_unchecked(format.unwrap());
match tiling {
ImageTiling::Linear => format_properties.linear_tiling_features,
ImageTiling::Optimal => format_properties.optimal_tiling_features,
ImageTiling::DrmFormatModifier => format_properties.linear_tiling_features, // TODO: improve
}
};
let memory_requirements = if needs_destruction {
if flags.intersects(ImageCreateFlags::DISJOINT) {
(0..format.unwrap().planes().len())
.map(|plane| Self::get_memory_requirements(&device, handle, Some(plane)))
.collect()
} else {
smallvec![Self::get_memory_requirements(&device, handle, None)]
}
} else {
smallvec![]
};
RawImage {
handle,
device,
id: Self::next_id(),
flags,
dimensions,
format,
format_features,
mip_levels,
initial_layout,
samples,
tiling,
usage,
stencil_usage,
sharing,
external_memory_handle_types,
memory_requirements,
needs_destruction,
subresource_layout: OnceCache::new(),
}
}
fn get_memory_requirements(
device: &Device,
handle: ash::vk::Image,
plane: Option<usize>,
) -> MemoryRequirements {
let mut info_vk = ash::vk::ImageMemoryRequirementsInfo2 {
image: handle,
..Default::default()
};
let mut plane_info_vk = None;
if let Some(plane) = plane {
debug_assert!(
device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_get_memory_requirements2
&& device.enabled_extensions().khr_sampler_ycbcr_conversion
);
let next = plane_info_vk.insert(ash::vk::ImagePlaneMemoryRequirementsInfo {
plane_aspect: match plane {
0 => ash::vk::ImageAspectFlags::PLANE_0,
1 => ash::vk::ImageAspectFlags::PLANE_1,
2 => ash::vk::ImageAspectFlags::PLANE_2,
_ => unreachable!(),
},
..Default::default()
});
next.p_next = info_vk.p_next;
info_vk.p_next = next as *mut _ as *mut _;
}
let mut memory_requirements2_vk = ash::vk::MemoryRequirements2::default();
let mut memory_dedicated_requirements_vk = None;
if device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_dedicated_allocation
{
debug_assert!(
device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_get_memory_requirements2
);
let next = memory_dedicated_requirements_vk
.insert(ash::vk::MemoryDedicatedRequirements::default());
next.p_next = memory_requirements2_vk.p_next;
memory_requirements2_vk.p_next = next as *mut _ as *mut _;
}
unsafe {
let fns = device.fns();
if device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_get_memory_requirements2
{
if device.api_version() >= Version::V1_1 {
(fns.v1_1.get_image_memory_requirements2)(
device.handle(),
&info_vk,
&mut memory_requirements2_vk,
);
} else {
(fns.khr_get_memory_requirements2
.get_image_memory_requirements2_khr)(
device.handle(),
&info_vk,
&mut memory_requirements2_vk,
);
}
} else {
(fns.v1_0.get_image_memory_requirements)(
device.handle(),
handle,
&mut memory_requirements2_vk.memory_requirements,
);
}
}
MemoryRequirements {
layout: DeviceLayout::from_size_alignment(
memory_requirements2_vk.memory_requirements.size,
memory_requirements2_vk.memory_requirements.alignment,
)
.unwrap(),
memory_type_bits: memory_requirements2_vk.memory_requirements.memory_type_bits,
prefers_dedicated_allocation: memory_dedicated_requirements_vk
.map_or(false, |dreqs| dreqs.prefers_dedicated_allocation != 0),
requires_dedicated_allocation: memory_dedicated_requirements_vk
.map_or(false, |dreqs| dreqs.requires_dedicated_allocation != 0),
}
}
#[inline]
#[allow(dead_code)] // Remove when sparse memory is implemented
fn get_sparse_memory_requirements(&self) -> Vec<SparseImageMemoryRequirements> {
let device = &self.device;
unsafe {
let fns = self.device.fns();
if device.api_version() >= Version::V1_1
|| device.enabled_extensions().khr_get_memory_requirements2
{
let info2 = ash::vk::ImageSparseMemoryRequirementsInfo2 {
image: self.handle,
..Default::default()
};
let mut count = 0;
if device.api_version() >= Version::V1_1 {
(fns.v1_1.get_image_sparse_memory_requirements2)(
device.handle(),
&info2,
&mut count,
ptr::null_mut(),
);
} else {
(fns.khr_get_memory_requirements2
.get_image_sparse_memory_requirements2_khr)(
device.handle(),
&info2,
&mut count,
ptr::null_mut(),
);
}
let mut sparse_image_memory_requirements2 =
vec![ash::vk::SparseImageMemoryRequirements2::default(); count as usize];
if device.api_version() >= Version::V1_1 {
(fns.v1_1.get_image_sparse_memory_requirements2)(
self.device.handle(),
&info2,
&mut count,
sparse_image_memory_requirements2.as_mut_ptr(),
);
} else {
(fns.khr_get_memory_requirements2
.get_image_sparse_memory_requirements2_khr)(
self.device.handle(),
&info2,
&mut count,
sparse_image_memory_requirements2.as_mut_ptr(),
);
}
sparse_image_memory_requirements2.set_len(count as usize);
sparse_image_memory_requirements2
.into_iter()
.map(
|sparse_image_memory_requirements2| SparseImageMemoryRequirements {
format_properties: SparseImageFormatProperties {
aspects: sparse_image_memory_requirements2
.memory_requirements
.format_properties
.aspect_mask
.into(),
image_granularity: [
sparse_image_memory_requirements2
.memory_requirements
.format_properties
.image_granularity
.width,
sparse_image_memory_requirements2
.memory_requirements
.format_properties
.image_granularity
.height,
sparse_image_memory_requirements2
.memory_requirements
.format_properties
.image_granularity
.depth,
],
flags: sparse_image_memory_requirements2
.memory_requirements
.format_properties
.flags
.into(),
},
image_mip_tail_first_lod: sparse_image_memory_requirements2
.memory_requirements
.image_mip_tail_first_lod,
image_mip_tail_size: sparse_image_memory_requirements2
.memory_requirements
.image_mip_tail_size,
image_mip_tail_offset: sparse_image_memory_requirements2
.memory_requirements
.image_mip_tail_offset,
image_mip_tail_stride: (!sparse_image_memory_requirements2
.memory_requirements
.format_properties
.flags
.intersects(ash::vk::SparseImageFormatFlags::SINGLE_MIPTAIL))
.then_some(
sparse_image_memory_requirements2
.memory_requirements
.image_mip_tail_stride,
),
},
)
.collect()
} else {
let mut count = 0;
(fns.v1_0.get_image_sparse_memory_requirements)(
device.handle(),
self.handle,
&mut count,
ptr::null_mut(),
);
let mut sparse_image_memory_requirements =
vec![ash::vk::SparseImageMemoryRequirements::default(); count as usize];
(fns.v1_0.get_image_sparse_memory_requirements)(
device.handle(),
self.handle,
&mut count,
sparse_image_memory_requirements.as_mut_ptr(),
);
sparse_image_memory_requirements.set_len(count as usize);
sparse_image_memory_requirements
.into_iter()
.map(
|sparse_image_memory_requirements| SparseImageMemoryRequirements {
format_properties: SparseImageFormatProperties {
aspects: sparse_image_memory_requirements
.format_properties
.aspect_mask
.into(),
image_granularity: [
sparse_image_memory_requirements
.format_properties
.image_granularity
.width,
sparse_image_memory_requirements
.format_properties
.image_granularity
.height,
sparse_image_memory_requirements
.format_properties
.image_granularity
.depth,
],
flags: sparse_image_memory_requirements
.format_properties
.flags
.into(),
},
image_mip_tail_first_lod: sparse_image_memory_requirements
.image_mip_tail_first_lod,
image_mip_tail_size: sparse_image_memory_requirements
.image_mip_tail_size,
image_mip_tail_offset: sparse_image_memory_requirements
.image_mip_tail_offset,
image_mip_tail_stride: (!sparse_image_memory_requirements
.format_properties
.flags
.intersects(ash::vk::SparseImageFormatFlags::SINGLE_MIPTAIL))
.then_some(sparse_image_memory_requirements.image_mip_tail_stride),
},
)
.collect()
}
}
}
pub(crate) fn id(&self) -> NonZeroU64 {
self.id
}
/// Binds device memory to this image.
///
/// - If `self.flags().disjoint` is not set, then `allocations` must contain exactly one
/// element. This element may be a dedicated allocation.
/// - If `self.flags().disjoint` is set, then `allocations` must contain exactly
/// `self.format().unwrap().planes().len()` elements. These elements must not be dedicated
/// allocations.
pub fn bind_memory(
self,
allocations: impl IntoIterator<Item = MemoryAlloc>,
) -> Result<
Image,
(
ImageError,
RawImage,
impl ExactSizeIterator<Item = MemoryAlloc>,
),
> {
let allocations: SmallVec<[_; 3]> = allocations.into_iter().collect();
if let Err(err) = self.validate_bind_memory(&allocations) {
return Err((err, self, allocations.into_iter()));
}
unsafe { self.bind_memory_unchecked(allocations) }.map_err(|(err, image, allocations)| {
(
err.into(),
image,
allocations
.into_iter()
.collect::<SmallVec<[_; 3]>>()
.into_iter(),
)
})
}
fn validate_bind_memory(&self, allocations: &[MemoryAlloc]) -> Result<(), ImageError> {
if self.flags.intersects(ImageCreateFlags::DISJOINT) {
if allocations.len() != self.format.unwrap().planes().len() {
return Err(ImageError::AllocationsWrongNumberOfElements {
provided: allocations.len(),
required: self.format.unwrap().planes().len(),
});
}
} else {
if allocations.len() != 1 {
return Err(ImageError::AllocationsWrongNumberOfElements {
provided: allocations.len(),
required: 1,
});
}
}
for (allocations_index, (allocation, memory_requirements)) in (allocations.iter())
.zip(self.memory_requirements.iter())
.enumerate()
{
assert_ne!(allocation.allocation_type(), AllocationType::Linear);
let memory = allocation.device_memory();
let memory_offset = allocation.offset();
let memory_type = &self
.device
.physical_device()
.memory_properties()
.memory_types[memory.memory_type_index() as usize];
// VUID-VkBindImageMemoryInfo-commonparent
assert_eq!(self.device(), memory.device());
// VUID-VkBindImageMemoryInfo-image-07460
// Ensured by taking ownership of `RawImage`.
// VUID-VkBindImageMemoryInfo-image-01045
// Currently ensured by not having sparse binding flags, but this needs to be checked
// once those are enabled.
// VUID-VkBindImageMemoryInfo-memoryOffset-01046
// Assume that `allocation` was created correctly.
if let Some(dedicated_to) = memory.dedicated_to() {
// VUID-VkBindImageMemoryInfo-memory-02628
match dedicated_to {
DedicatedTo::Image(id) if id == self.id => {}
_ => return Err(ImageError::DedicatedAllocationMismatch),
}
debug_assert!(memory_offset == 0); // This should be ensured by the allocator
} else {
// VUID-VkBindImageMemoryInfo-image-01445
if memory_requirements.requires_dedicated_allocation {
return Err(ImageError::DedicatedAllocationRequired);
}
}
// VUID-VkBindImageMemoryInfo-None-01901
if memory_type
.property_flags
.intersects(MemoryPropertyFlags::PROTECTED)
{
return Err(ImageError::MemoryProtectedMismatch {
allocations_index,
image_protected: false,
memory_protected: true,
});
}
// VUID-VkBindImageMemoryInfo-memory-02728
if !memory.export_handle_types().is_empty()
&& !memory
.export_handle_types()
.intersects(self.external_memory_handle_types)
{
return Err(ImageError::MemoryExternalHandleTypesDisjoint {
allocations_index,
image_handle_types: self.external_memory_handle_types,
memory_export_handle_types: memory.export_handle_types(),
});
}
if let Some(handle_type) = memory.imported_handle_type() {
// VUID-VkBindImageMemoryInfo-memory-02989
if !ExternalMemoryHandleTypes::from(handle_type)
.intersects(self.external_memory_handle_types)
{
return Err(ImageError::MemoryImportedHandleTypeNotEnabled {
allocations_index,
image_handle_types: self.external_memory_handle_types,
memory_imported_handle_type: handle_type,
});
}
}
// VUID-VkBindImageMemoryInfo-pNext-01615
// VUID-VkBindImageMemoryInfo-pNext-01619
if memory_requirements.memory_type_bits & (1 << memory.memory_type_index()) == 0 {
return Err(ImageError::MemoryTypeNotAllowed {
allocations_index,
provided_memory_type_index: memory.memory_type_index(),
allowed_memory_type_bits: memory_requirements.memory_type_bits,
});
}
// VUID-VkBindImageMemoryInfo-pNext-01616
// VUID-VkBindImageMemoryInfo-pNext-01620
if !is_aligned(memory_offset, memory_requirements.layout.alignment()) {
return Err(ImageError::MemoryAllocationNotAligned {
allocations_index,
allocation_offset: memory_offset,
required_alignment: memory_requirements.layout.alignment(),
});
}
// VUID-VkBindImageMemoryInfo-pNext-01617
// VUID-VkBindImageMemoryInfo-pNext-01621
if allocation.size() < memory_requirements.layout.size() {
return Err(ImageError::MemoryAllocationTooSmall {
allocations_index,
allocation_size: allocation.size(),
required_size: memory_requirements.layout.size(),
});
}
}
Ok(())
}
/// # Safety
///
/// - If `self.flags().disjoint` is not set, then `allocations` must contain exactly one
/// element.
/// - If `self.flags().disjoint` is set, then `allocations` must contain exactly
/// `self.format().unwrap().planes().len()` elements.
#[cfg_attr(not(feature = "document_unchecked"), doc(hidden))]
pub unsafe fn bind_memory_unchecked(
self,
allocations: impl IntoIterator<Item = MemoryAlloc>,
) -> Result<
Image,
(
VulkanError,
RawImage,
impl ExactSizeIterator<Item = MemoryAlloc>,
),
> {
let allocations: SmallVec<[_; 3]> = allocations.into_iter().collect();
let fns = self.device.fns();
let result = if self.device.api_version() >= Version::V1_1
|| self.device.enabled_extensions().khr_bind_memory2
{
let mut infos_vk: SmallVec<[_; 3]> = SmallVec::with_capacity(3);
let mut plane_infos_vk: SmallVec<[_; 3]> = SmallVec::with_capacity(3);
if self.flags.intersects(ImageCreateFlags::DISJOINT) {
debug_assert_eq!(allocations.len(), self.format.unwrap().planes().len());
for (plane, allocation) in allocations.iter().enumerate() {
let memory = allocation.device_memory();
let memory_offset = allocation.offset();
infos_vk.push(ash::vk::BindImageMemoryInfo {
image: self.handle,
memory: memory.handle(),
memory_offset,
..Default::default()
});
// VUID-VkBindImageMemoryInfo-pNext-01618
plane_infos_vk.push(ash::vk::BindImagePlaneMemoryInfo {
plane_aspect: match plane {
0 => ash::vk::ImageAspectFlags::PLANE_0,
1 => ash::vk::ImageAspectFlags::PLANE_1,
2 => ash::vk::ImageAspectFlags::PLANE_2,
_ => unreachable!(),
},
..Default::default()
});
}
} else {
debug_assert_eq!(allocations.len(), 1);
let allocation = &allocations[0];
let memory = allocation.device_memory();
let memory_offset = allocation.offset();
infos_vk.push(ash::vk::BindImageMemoryInfo {
image: self.handle,
memory: memory.handle(),
memory_offset,
..Default::default()
});
};
for (info_vk, plane_info_vk) in (infos_vk.iter_mut()).zip(plane_infos_vk.iter_mut()) {
info_vk.p_next = plane_info_vk as *mut _ as *mut _;
}
if self.device.api_version() >= Version::V1_1 {
(fns.v1_1.bind_image_memory2)(
self.device.handle(),
infos_vk.len() as u32,
infos_vk.as_ptr(),
)
} else {
(fns.khr_bind_memory2.bind_image_memory2_khr)(
self.device.handle(),
infos_vk.len() as u32,
infos_vk.as_ptr(),
)
}
} else {
debug_assert_eq!(allocations.len(), 1);
let allocation = &allocations[0];
let memory = allocation.device_memory();
let memory_offset = allocation.offset();
(fns.v1_0.bind_image_memory)(
self.device.handle(),
self.handle,
memory.handle(),
memory_offset,
)
}
.result();
if let Err(err) = result {
return Err((VulkanError::from(err), self, allocations.into_iter()));
}
Ok(Image::from_raw(self, ImageMemory::Normal(allocations)))
}
/// Returns the memory requirements for this image.
///
/// - If the image is a swapchain image, this returns a slice with a length of 0.
/// - If `self.flags().disjoint` is not set, this returns a slice with a length of 1.
/// - If `self.flags().disjoint` is set, this returns a slice with a length equal to
/// `self.format().unwrap().planes().len()`.
#[inline]
pub fn memory_requirements(&self) -> &[MemoryRequirements] {
&self.memory_requirements
}
/// Returns the flags the image was created with.
#[inline]
pub fn flags(&self) -> ImageCreateFlags {
self.flags
}
/// Returns the dimensions of the image.
#[inline]
pub fn dimensions(&self) -> ImageDimensions {
self.dimensions
}
/// Returns the image's format.
#[inline]
pub fn format(&self) -> Option<Format> {
self.format
}
/// Returns the features supported by the image's format.
#[inline]
pub fn format_features(&self) -> FormatFeatures {
self.format_features
}
/// Returns the number of mipmap levels in the image.
#[inline]
pub fn mip_levels(&self) -> u32 {
self.mip_levels
}
/// Returns the initial layout of the image.
#[inline]
pub fn initial_layout(&self) -> ImageLayout {
self.initial_layout
}
/// Returns the number of samples for the image.
#[inline]
pub fn samples(&self) -> SampleCount {
self.samples
}
/// Returns the tiling of the image.
#[inline]
pub fn tiling(&self) -> ImageTiling {
self.tiling
}
/// Returns the usage the image was created with.
#[inline]
pub fn usage(&self) -> ImageUsage {
self.usage
}
/// Returns the stencil usage the image was created with.
#[inline]
pub fn stencil_usage(&self) -> ImageUsage {
self.stencil_usage
}
/// Returns the sharing the image was created with.
#[inline]
pub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>> {
&self.sharing
}
/// Returns the external memory handle types that are supported with this image.
#[inline]
pub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes {
self.external_memory_handle_types
}
/// Returns an `ImageSubresourceLayers` covering the first mip level of the image. All aspects
/// of the image are selected, or `plane0` if the image is multi-planar.
#[inline]
pub fn subresource_layers(&self) -> ImageSubresourceLayers {
ImageSubresourceLayers {
aspects: {
let aspects = self.format.unwrap().aspects();
if aspects.intersects(ImageAspects::PLANE_0) {
ImageAspects::PLANE_0
} else {
aspects
}
},
mip_level: 0,
array_layers: 0..self.dimensions.array_layers(),
}
}
/// Returns an `ImageSubresourceRange` covering the whole image. If the image is multi-planar,
/// only the `color` aspect is selected.
#[inline]
pub fn subresource_range(&self) -> ImageSubresourceRange {
ImageSubresourceRange {
aspects: self.format.unwrap().aspects()
- (ImageAspects::PLANE_0 | ImageAspects::PLANE_1 | ImageAspects::PLANE_2),
mip_levels: 0..self.mip_levels,
array_layers: 0..self.dimensions.array_layers(),
}
}
/// Queries the memory layout of a single subresource of the image.
///
/// Only images with linear tiling are supported, if they do not have a format with both a
/// depth and a stencil format. Images with optimal tiling have an opaque image layout that is
/// not suitable for direct memory accesses, and likewise for combined depth/stencil formats.
/// Multi-planar formats are supported, but you must specify one of the planes as the `aspect`,
/// not [`ImageAspect::Color`].
///
/// The results of this function are cached, so that future calls with the same arguments
/// do not need to make a call to the Vulkan API again.
pub fn subresource_layout(
&self,
aspect: ImageAspect,
mip_level: u32,
array_layer: u32,
) -> Result<SubresourceLayout, ImageError> {
self.validate_subresource_layout(aspect, mip_level, array_layer)?;
unsafe { Ok(self.subresource_layout_unchecked(aspect, mip_level, array_layer)) }
}
fn validate_subresource_layout(
&self,
aspect: ImageAspect,
mip_level: u32,
array_layer: u32,
) -> Result<(), ImageError> {
// VUID-VkImageSubresource-aspectMask-parameter
aspect.validate_device(&self.device)?;
// VUID-VkImageSubresource-aspectMask-requiredbitmask
// VUID-vkGetImageSubresourceLayout-aspectMask-00997
// Ensured by use of enum `ImageAspect`.
// VUID-vkGetImageSubresourceLayout-image-02270
if !matches!(
self.tiling,
ImageTiling::DrmFormatModifier | ImageTiling::Linear
) {
return Err(ImageError::OptimalTilingNotSupported);
}
// VUID-vkGetImageSubresourceLayout-mipLevel-01716
if mip_level >= self.mip_levels {
return Err(ImageError::MipLevelOutOfRange {
provided_mip_level: mip_level,
image_mip_levels: self.mip_levels,
});
}
// VUID-vkGetImageSubresourceLayout-arrayLayer-01717
if array_layer >= self.dimensions.array_layers() {
return Err(ImageError::ArrayLayerOutOfRange {
provided_array_layer: array_layer,
image_array_layers: self.dimensions.array_layers(),
});
}
let mut allowed_aspects = self.format.unwrap().aspects();
// Follows from the combination of these three VUIDs. See:
// https://github.com/KhronosGroup/Vulkan-Docs/issues/1942
// VUID-vkGetImageSubresourceLayout-aspectMask-00997
// VUID-vkGetImageSubresourceLayout-format-04462
// VUID-vkGetImageSubresourceLayout-format-04463
if allowed_aspects.contains(ImageAspects::DEPTH | ImageAspects::STENCIL) {
return Err(ImageError::DepthStencilFormatsNotSupported);
}
if allowed_aspects
.intersects(ImageAspects::PLANE_0 | ImageAspects::PLANE_1 | ImageAspects::PLANE_2)
{
allowed_aspects -= ImageAspects::COLOR;
}
// TODO: VUID-vkGetImageSubresourceLayout-tiling-02271
//if self.tiling == ImageTiling::DrmFormatModifier {
// Only one-plane image importing is possible for now.
//}
// VUID-vkGetImageSubresourceLayout-format-04461
// VUID-vkGetImageSubresourceLayout-format-04462
// VUID-vkGetImageSubresourceLayout-format-04463
// VUID-vkGetImageSubresourceLayout-format-04464
// VUID-vkGetImageSubresourceLayout-format-01581
// VUID-vkGetImageSubresourceLayout-format-01582
if !allowed_aspects.contains(aspect.into()) {
return Err(ImageError::AspectNotAllowed {
provided_aspect: aspect,
allowed_aspects,
});
}
Ok(())
}
#[cfg_attr(not(feature = "document_unchecked"), doc(hidden))]
pub unsafe fn subresource_layout_unchecked(
&self,
aspect: ImageAspect,
mip_level: u32,
array_layer: u32,
) -> SubresourceLayout {
self.subresource_layout.get_or_insert(
(aspect, mip_level, array_layer),
|&(aspect, mip_level, array_layer)| {
let fns = self.device.fns();
let subresource = ash::vk::ImageSubresource {
aspect_mask: aspect.into(),
mip_level,
array_layer,
};
let mut output = MaybeUninit::uninit();
(fns.v1_0.get_image_subresource_layout)(
self.device.handle(),
self.handle,
&subresource,
output.as_mut_ptr(),
);
let output = output.assume_init();
SubresourceLayout {
offset: output.offset,
size: output.size,
row_pitch: output.row_pitch,
array_pitch: (self.dimensions.array_layers() > 1).then_some(output.array_pitch),
depth_pitch: matches!(self.dimensions, ImageDimensions::Dim3d { .. })
.then_some(output.depth_pitch),
}
},
)
}
}
impl Drop for RawImage {
#[inline]
fn drop(&mut self) {
if !self.needs_destruction {
return;
}
unsafe {
let fns = self.device.fns();
(fns.v1_0.destroy_image)(self.device.handle(), self.handle, ptr::null());
}
}
}
unsafe impl VulkanObject for RawImage {
type Handle = ash::vk::Image;
#[inline]
fn handle(&self) -> Self::Handle {
self.handle
}
}
unsafe impl DeviceOwned for RawImage {
#[inline]
fn device(&self) -> &Arc<Device> {
&self.device
}
}
impl_id_counter!(RawImage);
/// Parameters to create a new `Image`.
#[derive(Clone, Debug)]
pub struct ImageCreateInfo {
/// Flags to enable.
///
/// The default value is [`ImageCreateFlags::empty()`].
pub flags: ImageCreateFlags,
/// The type, extent and number of array layers to create the image with.
///
/// On [portability subset](crate::instance#portability-subset-devices-and-the-enumerate_portability-flag)
/// devices, if `samples` is not [`SampleCount::Sample1`] and `dimensions.array_layers()` is
/// not 1, the [`multisample_array_image`](crate::device::Features::multisample_array_image)
/// feature must be enabled on the device.
///
/// The default value is `ImageDimensions::Dim2d { width: 0, height: 0, array_layers: 1 }`,
/// which must be overridden.
pub dimensions: ImageDimensions,
/// The format used to store the image data.
///
/// The default value is `None`, which must be overridden.
pub format: Option<Format>,
/// The number of mip levels to create the image with.
///
/// The default value is `1`.
pub mip_levels: u32,
/// The number of samples per texel that the image should use.
///
/// On [portability subset](crate::instance#portability-subset-devices-and-the-enumerate_portability-flag)
/// devices, if `samples` is not [`SampleCount::Sample1`] and `dimensions.array_layers()` is
/// not 1, the [`multisample_array_image`](crate::device::Features::multisample_array_image)
/// feature must be enabled on the device.
///
/// The default value is [`SampleCount::Sample1`].
pub samples: SampleCount,
/// The memory arrangement of the texel blocks.
///
/// The default value is [`ImageTiling::Optimal`].
pub tiling: ImageTiling,
/// How the image is going to be used.
///
/// The default value is [`ImageUsage::empty()`], which must be overridden.
pub usage: ImageUsage,
/// How the stencil aspect of the image is going to be used, if any.
///
/// 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 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 enabled on the device.
///
/// The default value is [`ImageUsage::empty()`].
pub stencil_usage: ImageUsage,
/// Whether the image can be shared across multiple queues, or is limited to a single queue.
///
/// The default value is [`Sharing::Exclusive`].
pub sharing: Sharing<SmallVec<[u32; 4]>>,
/// The image layout that the image will have when it is created.
///
/// The default value is [`ImageLayout::Undefined`].
pub initial_layout: ImageLayout,
/// The external memory handle types that are going to be used with the image.
///
/// If any of the fields in this value are set, the device must either support API version 1.1
/// or the [`khr_external_memory`](crate::device::DeviceExtensions::khr_external_memory)
/// extension must be enabled, and `initial_layout` must be set to
/// [`ImageLayout::Undefined`].
///
/// The default value is [`ExternalMemoryHandleTypes::empty()`].
pub external_memory_handle_types: ExternalMemoryHandleTypes,
/// Specify that an image be created with the provided DRM format modifier and explicit memory layout
pub image_drm_format_modifier_create_info: Option<ImageDrmFormatModifierExplicitCreateInfoEXT>,
pub _ne: crate::NonExhaustive,
}
impl Default for ImageCreateInfo {
#[inline]
fn default() -> Self {
Self {
flags: ImageCreateFlags::empty(),
dimensions: ImageDimensions::Dim2d {
width: 0,
height: 0,
array_layers: 1,
},
format: None,
mip_levels: 1,
samples: SampleCount::Sample1,
tiling: ImageTiling::Optimal,
usage: ImageUsage::empty(),
stencil_usage: ImageUsage::empty(),
sharing: Sharing::Exclusive,
initial_layout: ImageLayout::Undefined,
external_memory_handle_types: ExternalMemoryHandleTypes::empty(),
image_drm_format_modifier_create_info: None,
_ne: crate::NonExhaustive(()),
}
}
}
/// A multi-dimensioned storage for texel data.
///
/// Unlike [`RawImage`], an `Image` has memory backing it, and can be used normally.
#[derive(Debug)]
pub struct Image {
inner: RawImage,
memory: ImageMemory,
aspect_list: SmallVec<[ImageAspect; 4]>,
aspect_size: DeviceSize,
mip_level_size: DeviceSize,
range_size: DeviceSize,
state: Mutex<ImageState>,
}
/// The type of backing memory that an image can have.
#[derive(Debug)]
pub enum ImageMemory {
/// The image is backed by normal memory, bound with [`bind_memory`].
///
/// [`bind_memory`]: RawImage::bind_memory
Normal(SmallVec<[MemoryAlloc; 3]>),
/// The image is backed by sparse memory, bound with [`bind_sparse`].
///
/// [`bind_sparse`]: crate::device::QueueGuard::bind_sparse
Sparse(Vec<SparseImageMemoryRequirements>),
/// The image is backed by memory owned by a [`Swapchain`].
Swapchain {
swapchain: Arc<Swapchain>,
image_index: u32,
},
}
impl Image {
fn from_raw(inner: RawImage, memory: ImageMemory) -> Self {
let aspects = inner.format.unwrap().aspects();
let aspect_list: SmallVec<[ImageAspect; 4]> = aspects.into_iter().collect();
let mip_level_size = inner.dimensions.array_layers() as DeviceSize;
let aspect_size = mip_level_size * inner.mip_levels as DeviceSize;
let range_size = aspect_list.len() as DeviceSize * aspect_size;
let state = Mutex::new(ImageState::new(range_size, inner.initial_layout));
Image {
inner,
memory,
aspect_list,
aspect_size,
mip_level_size,
range_size,
state,
}
}
pub(crate) unsafe fn from_swapchain(
handle: ash::vk::Image,
swapchain: Arc<Swapchain>,
image_index: u32,
) -> Self {
let create_info = ImageCreateInfo {
flags: ImageCreateFlags::empty(),
dimensions: ImageDimensions::Dim2d {
width: swapchain.image_extent()[0],
height: swapchain.image_extent()[1],
array_layers: swapchain.image_array_layers(),
},
format: Some(swapchain.image_format()),
initial_layout: ImageLayout::Undefined,
mip_levels: 1,
samples: SampleCount::Sample1,
tiling: ImageTiling::Optimal,
usage: swapchain.image_usage(),
stencil_usage: swapchain.image_usage(),
sharing: swapchain.image_sharing().clone(),
..Default::default()
};
Self::from_raw(
RawImage::from_handle_with_destruction(
swapchain.device().clone(),
handle,
create_info,
false,
),
ImageMemory::Swapchain {
swapchain,
image_index,
},
)
}
/// Returns the type of memory that is backing this image.
#[inline]
pub fn memory(&self) -> &ImageMemory {
&self.memory
}
/// Returns the memory requirements for this image.
///
/// - If the image is a swapchain image, this returns a slice with a length of 0.
/// - If `self.flags().disjoint` is not set, this returns a slice with a length of 1.
/// - If `self.flags().disjoint` is set, this returns a slice with a length equal to
/// `self.format().unwrap().planes().len()`.
#[inline]
pub fn memory_requirements(&self) -> &[MemoryRequirements] {
&self.inner.memory_requirements
}
/// Returns the flags the image was created with.
#[inline]
pub fn flags(&self) -> ImageCreateFlags {
self.inner.flags
}
/// Returns the dimensions of the image.
#[inline]
pub fn dimensions(&self) -> ImageDimensions {
self.inner.dimensions
}
/// Returns the image's format.
#[inline]
pub fn format(&self) -> Option<Format> {
self.inner.format
}
/// Returns the features supported by the image's format.
#[inline]
pub fn format_features(&self) -> FormatFeatures {
self.inner.format_features
}
/// Returns the number of mipmap levels in the image.
#[inline]
pub fn mip_levels(&self) -> u32 {
self.inner.mip_levels
}
/// Returns the initial layout of the image.
#[inline]
pub fn initial_layout(&self) -> ImageLayout {
self.inner.initial_layout
}
/// Returns the number of samples for the image.
#[inline]
pub fn samples(&self) -> SampleCount {
self.inner.samples
}
/// Returns the tiling of the image.
#[inline]
pub fn tiling(&self) -> ImageTiling {
self.inner.tiling
}
/// Returns the usage the image was created with.
#[inline]
pub fn usage(&self) -> ImageUsage {
self.inner.usage
}
/// Returns the stencil usage the image was created with.
#[inline]
pub fn stencil_usage(&self) -> ImageUsage {
self.inner.stencil_usage
}
/// Returns the sharing the image was created with.
#[inline]
pub fn sharing(&self) -> &Sharing<SmallVec<[u32; 4]>> {
&self.inner.sharing
}
/// Returns the external memory handle types that are supported with this image.
#[inline]
pub fn external_memory_handle_types(&self) -> ExternalMemoryHandleTypes {
self.inner.external_memory_handle_types
}
/// Returns an `ImageSubresourceLayers` covering the first mip level of the image. All aspects
/// of the image are selected, or `plane0` if the image is multi-planar.
#[inline]
pub fn subresource_layers(&self) -> ImageSubresourceLayers {
self.inner.subresource_layers()
}
/// Returns an `ImageSubresourceRange` covering the whole image. If the image is multi-planar,
/// only the `color` aspect is selected.
#[inline]
pub fn subresource_range(&self) -> ImageSubresourceRange {
self.inner.subresource_range()
}
/// Queries the memory layout of a single subresource of the image.
///
/// Only images with linear tiling are supported, if they do not have a format with both a
/// depth and a stencil format. Images with optimal tiling have an opaque image layout that is
/// not suitable for direct memory accesses, and likewise for combined depth/stencil formats.
/// Multi-planar formats are supported, but you must specify one of the planes as the `aspect`,
/// not [`ImageAspect::Color`].
///
/// The layout is invariant for each image. However it is not cached, as this would waste
/// memory in the case of non-linear-tiling images. You are encouraged to store the layout
/// somewhere in order to avoid calling this semi-expensive function at every single memory
/// access.
#[inline]
pub fn subresource_layout(
&self,
aspect: ImageAspect,
mip_level: u32,
array_layer: u32,
) -> Result<SubresourceLayout, ImageError> {
self.inner
.subresource_layout(aspect, mip_level, array_layer)
}
#[cfg_attr(not(feature = "document_unchecked"), doc(hidden))]
#[inline]
pub unsafe fn subresource_layout_unchecked(
&self,
aspect: ImageAspect,
mip_level: u32,
array_layer: u32,
) -> SubresourceLayout {
self.inner
.subresource_layout_unchecked(aspect, mip_level, array_layer)
}
pub(crate) fn range_size(&self) -> DeviceSize {
self.range_size
}
/// Returns an iterator over subresource ranges.
///
/// In ranges, the subresources are "flattened" to `DeviceSize`, where each index in the range
/// is a single array layer. The layers are arranged hierarchically: aspects at the top level,
/// with the mip levels in that aspect, and the array layers in that mip level.
pub(crate) fn iter_ranges(
&self,
subresource_range: ImageSubresourceRange,
) -> SubresourceRangeIterator {
assert!(self
.format()
.unwrap()
.aspects()
.contains(subresource_range.aspects));
assert!(subresource_range.mip_levels.end <= self.inner.mip_levels);
assert!(subresource_range.array_layers.end <= self.inner.dimensions.array_layers());
SubresourceRangeIterator::new(
subresource_range,
&self.aspect_list,
self.aspect_size,
self.inner.mip_levels,
self.mip_level_size,
self.inner.dimensions.array_layers(),
)
}
pub(crate) fn range_to_subresources(
&self,
mut range: Range<DeviceSize>,
) -> ImageSubresourceRange {
debug_assert!(!range.is_empty());
debug_assert!(range.end <= self.range_size);
if range.end - range.start > self.aspect_size {
debug_assert!(range.start % self.aspect_size == 0);
debug_assert!(range.end % self.aspect_size == 0);
let start_aspect_num = (range.start / self.aspect_size) as usize;
let end_aspect_num = (range.end / self.aspect_size) as usize;
ImageSubresourceRange {
aspects: self.aspect_list[start_aspect_num..end_aspect_num]
.iter()
.copied()
.collect(),
mip_levels: 0..self.inner.mip_levels,
array_layers: 0..self.inner.dimensions.array_layers(),
}
} else {
let aspect_num = (range.start / self.aspect_size) as usize;
range.start %= self.aspect_size;
range.end %= self.aspect_size;
// Wraparound
if range.end == 0 {
range.end = self.aspect_size;
}
if range.end - range.start > self.mip_level_size {
debug_assert!(range.start % self.mip_level_size == 0);
debug_assert!(range.end % self.mip_level_size == 0);
let start_mip_level = (range.start / self.mip_level_size) as u32;
let end_mip_level = (range.end / self.mip_level_size) as u32;
ImageSubresourceRange {
aspects: self.aspect_list[aspect_num].into(),
mip_levels: start_mip_level..end_mip_level,
array_layers: 0..self.inner.dimensions.array_layers(),
}
} else {
let mip_level = (range.start / self.mip_level_size) as u32;
range.start %= self.mip_level_size;
range.end %= self.mip_level_size;
// Wraparound
if range.end == 0 {
range.end = self.mip_level_size;
}
let start_array_layer = range.start as u32;
let end_array_layer = range.end as u32;
ImageSubresourceRange {
aspects: self.aspect_list[aspect_num].into(),
mip_levels: mip_level..mip_level + 1,
array_layers: start_array_layer..end_array_layer,
}
}
}
}
pub(crate) fn state(&self) -> MutexGuard<'_, ImageState> {
self.state.lock()
}
}
unsafe impl VulkanObject for Image {
type Handle = ash::vk::Image;
#[inline]
fn handle(&self) -> Self::Handle {
self.inner.handle
}
}
unsafe impl DeviceOwned for Image {
#[inline]
fn device(&self) -> &Arc<Device> {
&self.inner.device
}
}
impl PartialEq for Image {
#[inline]
fn eq(&self, other: &Self) -> bool {
self.inner == other.inner
}
}
impl Eq for Image {}
impl Hash for Image {
fn hash<H: Hasher>(&self, state: &mut H) {
self.inner.hash(state);
}
}
/// The current state of an image.
#[derive(Debug)]
pub(crate) struct ImageState {
ranges: RangeMap<DeviceSize, ImageRangeState>,
}
impl ImageState {
fn new(size: DeviceSize, initial_layout: ImageLayout) -> Self {
ImageState {
ranges: [(
0..size,
ImageRangeState {
current_access: CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads: 0,
},
layout: initial_layout,
},
)]
.into_iter()
.collect(),
}
}
#[allow(dead_code)]
pub(crate) fn check_cpu_read(&self, range: Range<DeviceSize>) -> Result<(), ReadLockError> {
for (_range, state) in self.ranges.range(&range) {
match &state.current_access {
CurrentAccess::CpuExclusive { .. } => return Err(ReadLockError::CpuWriteLocked),
CurrentAccess::GpuExclusive { .. } => return Err(ReadLockError::GpuWriteLocked),
CurrentAccess::Shared { .. } => (),
}
}
Ok(())
}
#[allow(dead_code)]
pub(crate) unsafe fn cpu_read_lock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::Shared { cpu_reads, .. } => {
*cpu_reads += 1;
}
_ => unreachable!("Image is being written by the CPU or GPU"),
}
}
}
#[allow(dead_code)]
pub(crate) unsafe fn cpu_read_unlock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::Shared { cpu_reads, .. } => *cpu_reads -= 1,
_ => unreachable!("Image was not locked for CPU read"),
}
}
}
#[allow(dead_code)]
pub(crate) fn check_cpu_write(&self, range: Range<DeviceSize>) -> Result<(), WriteLockError> {
for (_range, state) in self.ranges.range(&range) {
match &state.current_access {
CurrentAccess::CpuExclusive => return Err(WriteLockError::CpuLocked),
CurrentAccess::GpuExclusive { .. } => return Err(WriteLockError::GpuLocked),
CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads: 0,
} => (),
CurrentAccess::Shared { cpu_reads, .. } if *cpu_reads > 0 => {
return Err(WriteLockError::CpuLocked)
}
CurrentAccess::Shared { .. } => return Err(WriteLockError::GpuLocked),
}
}
Ok(())
}
#[allow(dead_code)]
pub(crate) unsafe fn cpu_write_lock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
state.current_access = CurrentAccess::CpuExclusive;
}
}
#[allow(dead_code)]
pub(crate) unsafe fn cpu_write_unlock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::CpuExclusive => {
state.current_access = CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads: 0,
}
}
_ => unreachable!("Image was not locked for CPU write"),
}
}
}
pub(crate) fn check_gpu_read(
&self,
range: Range<DeviceSize>,
expected_layout: ImageLayout,
) -> Result<(), AccessError> {
for (_range, state) in self.ranges.range(&range) {
match &state.current_access {
CurrentAccess::Shared { .. } => (),
_ => return Err(AccessError::AlreadyInUse),
}
if expected_layout != ImageLayout::Undefined && state.layout != expected_layout {
return Err(AccessError::UnexpectedImageLayout {
allowed: state.layout,
requested: expected_layout,
});
}
}
Ok(())
}
pub(crate) unsafe fn gpu_read_lock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::GpuExclusive { gpu_reads, .. }
| CurrentAccess::Shared { gpu_reads, .. } => *gpu_reads += 1,
_ => unreachable!("Image is being written by the CPU"),
}
}
}
pub(crate) unsafe fn gpu_read_unlock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::GpuExclusive { gpu_reads, .. } => *gpu_reads -= 1,
CurrentAccess::Shared { gpu_reads, .. } => *gpu_reads -= 1,
_ => unreachable!("Buffer was not locked for GPU read"),
}
}
}
pub(crate) fn check_gpu_write(
&self,
range: Range<DeviceSize>,
expected_layout: ImageLayout,
) -> Result<(), AccessError> {
for (_range, state) in self.ranges.range(&range) {
match &state.current_access {
CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads: 0,
} => (),
_ => return Err(AccessError::AlreadyInUse),
}
if expected_layout != ImageLayout::Undefined && state.layout != expected_layout {
return Err(AccessError::UnexpectedImageLayout {
allowed: state.layout,
requested: expected_layout,
});
}
}
Ok(())
}
pub(crate) unsafe fn gpu_write_lock(
&mut self,
range: Range<DeviceSize>,
destination_layout: ImageLayout,
) {
debug_assert!(!matches!(
destination_layout,
ImageLayout::Undefined | ImageLayout::Preinitialized
));
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
CurrentAccess::GpuExclusive { gpu_writes, .. } => *gpu_writes += 1,
&mut CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads,
} => {
state.current_access = CurrentAccess::GpuExclusive {
gpu_reads,
gpu_writes: 1,
}
}
_ => unreachable!("Image is being accessed by the CPU"),
}
state.layout = destination_layout;
}
}
pub(crate) unsafe fn gpu_write_unlock(&mut self, range: Range<DeviceSize>) {
self.ranges.split_at(&range.start);
self.ranges.split_at(&range.end);
for (_range, state) in self.ranges.range_mut(&range) {
match &mut state.current_access {
&mut CurrentAccess::GpuExclusive {
gpu_reads,
gpu_writes: 1,
} => {
state.current_access = CurrentAccess::Shared {
cpu_reads: 0,
gpu_reads,
}
}
CurrentAccess::GpuExclusive { gpu_writes, .. } => *gpu_writes -= 1,
_ => unreachable!("Image was not locked for GPU write"),
}
}
}
}
/// The current state of a specific subresource range in an image.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct ImageRangeState {
current_access: CurrentAccess,
layout: ImageLayout,
}
#[derive(Clone)]
pub(crate) struct SubresourceRangeIterator {
next_fn: fn(&mut Self) -> Option<Range<DeviceSize>>,
image_aspect_size: DeviceSize,
image_mip_level_size: DeviceSize,
mip_levels: Range<u32>,
array_layers: Range<u32>,
aspect_nums: Peekable<smallvec::IntoIter<[usize; 4]>>,
current_aspect_num: Option<usize>,
current_mip_level: u32,
}
impl SubresourceRangeIterator {
fn new(
subresource_range: ImageSubresourceRange,
image_aspect_list: &[ImageAspect],
image_aspect_size: DeviceSize,
image_mip_levels: u32,
image_mip_level_size: DeviceSize,
image_array_layers: u32,
) -> Self {
assert!(!subresource_range.mip_levels.is_empty());
assert!(!subresource_range.array_layers.is_empty());
let next_fn = if subresource_range.array_layers.start != 0
|| subresource_range.array_layers.end != image_array_layers
{
Self::next_some_layers
} else if subresource_range.mip_levels.start != 0
|| subresource_range.mip_levels.end != image_mip_levels
{
Self::next_some_levels_all_layers
} else {
Self::next_all_levels_all_layers
};
let mut aspect_nums = subresource_range
.aspects
.into_iter()
.map(|aspect| image_aspect_list.iter().position(|&a| a == aspect).unwrap())
.collect::<SmallVec<[usize; 4]>>()
.into_iter()
.peekable();
assert!(aspect_nums.len() != 0);
let current_aspect_num = aspect_nums.next();
let current_mip_level = subresource_range.mip_levels.start;
Self {
next_fn,
image_aspect_size,
image_mip_level_size,
mip_levels: subresource_range.mip_levels,
array_layers: subresource_range.array_layers,
aspect_nums,
current_aspect_num,
current_mip_level,
}
}
/// Used when the requested range contains only a subset of the array layers in the image.
/// The iterator returns one range for each mip level and aspect, each covering the range of
/// array layers of that mip level and aspect.
fn next_some_layers(&mut self) -> Option<Range<DeviceSize>> {
self.current_aspect_num.map(|aspect_num| {
let mip_level_offset = aspect_num as DeviceSize * self.image_aspect_size
+ self.current_mip_level as DeviceSize * self.image_mip_level_size;
self.current_mip_level += 1;
if self.current_mip_level >= self.mip_levels.end {
self.current_mip_level = self.mip_levels.start;
self.current_aspect_num = self.aspect_nums.next();
}
let start = mip_level_offset + self.array_layers.start as DeviceSize;
let end = mip_level_offset + self.array_layers.end as DeviceSize;
start..end
})
}
/// Used when the requested range contains all array layers in the image, but not all mip
/// levels. The iterator returns one range for each aspect, each covering all layers of the
/// range of mip levels of that aspect.
fn next_some_levels_all_layers(&mut self) -> Option<Range<DeviceSize>> {
self.current_aspect_num.map(|aspect_num| {
let aspect_offset = aspect_num as DeviceSize * self.image_aspect_size;
self.current_aspect_num = self.aspect_nums.next();
let start =
aspect_offset + self.mip_levels.start as DeviceSize * self.image_mip_level_size;
let end = aspect_offset + self.mip_levels.end as DeviceSize * self.image_mip_level_size;
start..end
})
}
/// Used when the requested range contains all array layers and mip levels in the image.
/// The iterator returns one range for each series of adjacent aspect numbers, each covering
/// all mip levels and all layers of those aspects. If the range contains the whole image, then
/// exactly one range is returned since all aspect numbers will be adjacent.
fn next_all_levels_all_layers(&mut self) -> Option<Range<DeviceSize>> {
self.current_aspect_num.map(|aspect_num_start| {
self.current_aspect_num = self.aspect_nums.next();
let mut aspect_num_end = aspect_num_start + 1;
while self.current_aspect_num == Some(aspect_num_end) {
self.current_aspect_num = self.aspect_nums.next();
aspect_num_end += 1;
}
let start = aspect_num_start as DeviceSize * self.image_aspect_size;
let end = aspect_num_end as DeviceSize * self.image_aspect_size;
start..end
})
}
}
impl Iterator for SubresourceRangeIterator {
type Item = Range<DeviceSize>;
fn next(&mut self) -> Option<Self::Item> {
(self.next_fn)(self)
}
}
impl FusedIterator for SubresourceRangeIterator {}
/// Describes the memory layout of a single subresource of an image.
///
/// The address of a texel at `(x, y, z, layer)` is `layer * array_pitch + z * depth_pitch +
/// y * row_pitch + x * size_of_each_texel + offset`. `size_of_each_texel` must be determined
/// depending on the format. The same formula applies for compressed formats, except that the
/// coordinates must be in number of blocks.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct SubresourceLayout {
/// The number of bytes from the start of the memory to the start of the queried subresource.
pub offset: DeviceSize,
/// The total number of bytes for the queried subresource.
pub size: DeviceSize,
/// The number of bytes between two texels or two blocks in adjacent rows.
pub row_pitch: DeviceSize,
/// For images with more than one array layer, the number of bytes between two texels or two
/// blocks in adjacent array layers.
pub array_pitch: Option<DeviceSize>,
/// For 3D images, the number of bytes between two texels or two blocks in adjacent depth
/// layers.
pub depth_pitch: Option<DeviceSize>,
}
/// Error that can happen in image functions.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum ImageError {
VulkanError(VulkanError),
/// Allocating memory failed.
AllocError(AllocationCreationError),
RequirementNotMet {
required_for: &'static str,
requires_one_of: RequiresOneOf,
},
/// The provided number of elements in `allocations` is not what is required for `image`.
AllocationsWrongNumberOfElements {
provided: usize,
required: usize,
},
/// The `array_2d_compatible` flag was enabled, but the image type was not 3D.
Array2dCompatibleNot3d,
/// The provided array layer is not less than the number of array layers in the image.
ArrayLayerOutOfRange {
provided_array_layer: u32,
image_array_layers: u32,
},
/// The provided aspect is not present in the image, or is not allowed.
AspectNotAllowed {
provided_aspect: ImageAspect,
allowed_aspects: ImageAspects,
},
/// The `block_texel_view_compatible` flag was enabled, but the given format was not compressed.
BlockTexelViewCompatibleNotCompressed,
/// The `cube_compatible` flag was enabled, but the image type was not 2D.
CubeCompatibleNot2d,
/// The `cube_compatible` flag was enabled, but the number of array layers was less than 6.
CubeCompatibleNotEnoughArrayLayers,
/// The `cube_compatible` flag was enabled, but the image dimensions were not square.
CubeCompatibleNotSquare,
/// The `cube_compatible` flag was enabled together with multisampling.
CubeCompatibleMultisampling,
/// The memory was created dedicated to a resource, but not to this image.
DedicatedAllocationMismatch,
/// A dedicated allocation is required for this image, but one was not provided.
DedicatedAllocationRequired,
/// The image has a format with both a depth and a stencil aspect, which is not supported for
/// this operation.
DepthStencilFormatsNotSupported,
/// The `disjoint` flag was enabled, but the given format is either not multi-planar, or does
/// not support disjoint images.
DisjointFormatNotSupported,
/// One or more external memory handle types were provided, but the initial layout was not
/// `Undefined`.
ExternalMemoryInvalidInitialLayout,
/// The given format was not supported by the device.
FormatNotSupported,
/// A requested usage flag was not supported by the given format.
FormatUsageNotSupported {
usage: &'static str,
},
/// The image configuration as queried through the `image_format_properties` function was not
/// supported by the device.
ImageFormatPropertiesNotSupported,
/// The number of array layers exceeds the maximum supported by the device for this image
/// configuration.
MaxArrayLayersExceeded {
array_layers: u32,
max: u32,
},
/// The specified dimensions exceed the maximum supported by the device for this image
/// configuration.
MaxDimensionsExceeded {
extent: [u32; 3],
max: [u32; 3],
},
/// The usage included one of the attachment types, and the specified width and height exceeded
/// the `max_framebuffer_width` or `max_framebuffer_height` limits.
MaxFramebufferDimensionsExceeded {
extent: [u32; 2],
max: [u32; 2],
},
/// The maximum number of mip levels for the given dimensions has been exceeded.
MaxMipLevelsExceeded {
mip_levels: u32,
max: u32,
},
/// In an `allocations` element, the offset of the allocation does not have the required
/// alignment.
MemoryAllocationNotAligned {
allocations_index: usize,
allocation_offset: DeviceSize,
required_alignment: DeviceAlignment,
},
/// In an `allocations` element, the size of the allocation is smaller than what is required.
MemoryAllocationTooSmall {
allocations_index: usize,
allocation_size: DeviceSize,
required_size: DeviceSize,
},
/// In an `allocations` element, the memory was created with export handle types, but none of
/// these handle types were enabled on the image.
MemoryExternalHandleTypesDisjoint {
allocations_index: usize,
image_handle_types: ExternalMemoryHandleTypes,
memory_export_handle_types: ExternalMemoryHandleTypes,
},
/// In an `allocations` element, the memory was created with an import, but the import's handle
/// type was not enabled on the image.
MemoryImportedHandleTypeNotEnabled {
allocations_index: usize,
image_handle_types: ExternalMemoryHandleTypes,
memory_imported_handle_type: ExternalMemoryHandleType,
},
/// In an `allocations` element, the protection of image and memory are not equal.
MemoryProtectedMismatch {
allocations_index: usize,
image_protected: bool,
memory_protected: bool,
},
/// In an `allocations` element, the provided memory type is not one of the allowed memory
/// types that can be bound to this image or image plane.
MemoryTypeNotAllowed {
allocations_index: usize,
provided_memory_type_index: u32,
allowed_memory_type_bits: u32,
},
/// The provided mip level is not less than the number of mip levels in the image.
MipLevelOutOfRange {
provided_mip_level: u32,
image_mip_levels: u32,
},
/// Multisampling was enabled, and the `cube_compatible` flag was set.
MultisampleCubeCompatible,
/// Multisampling was enabled, and tiling was `Linear`.
MultisampleLinearTiling,
/// Multisampling was enabled, and multiple mip levels were specified.
MultisampleMultipleMipLevels,
/// Multisampling was enabled, but the image type was not 2D.
MultisampleNot2d,
/// The image has optimal tiling, which is not supported for this operation.
OptimalTilingNotSupported,
/// The sample count is not supported by the device for this image configuration.
SampleCountNotSupported {
samples: SampleCount,
supported: SampleCounts,
},
/// The sharing mode was set to `Concurrent`, but one of the specified queue family indices was
/// out of range.
SharingQueueFamilyIndexOutOfRange {
queue_family_index: u32,
queue_family_count: u32,
},
/// The provided `usage` and `stencil_usage` have different values for
/// `depth_stencil_attachment` or `transient_attachment`.
StencilUsageMismatch {
usage: ImageUsage,
stencil_usage: ImageUsage,
},
/// A YCbCr format was given, but the specified width and/or height was not a multiple of 2
/// as required by the format's chroma subsampling.
YcbcrFormatInvalidDimensions,
/// A YCbCr format was given, and multiple mip levels were specified.
YcbcrFormatMultipleMipLevels,
/// A YCbCr format was given, and multisampling was enabled.
YcbcrFormatMultisampling,
/// A YCbCr format was given, but the image type was not 2D.
YcbcrFormatNot2d,
DirectImageViewCreationFailed(ImageViewCreationError),
/// If and only if tiling is `DRMFormatModifier`, then `image_drm_format_modifier_create_info` must not be `None`.
DrmFormatModifierRequiresCreateInfo,
}
impl Error for ImageError {
fn source(&self) -> Option<&(dyn Error + 'static)> {
match self {
ImageError::AllocError(err) => Some(err),
_ => None,
}
}
}
impl Display for ImageError {
fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
match self {
Self::VulkanError(_) => write!(f, "a runtime error occurred"),
Self::AllocError(_) => write!(f, "allocating memory failed"),
Self::RequirementNotMet {
required_for,
requires_one_of,
} => write!(
f,
"a requirement was not met for: {}; requires one of: {}",
required_for, requires_one_of,
),
Self::AllocationsWrongNumberOfElements { provided, required } => write!(
f,
"the provided number of elements in `allocations` ({}) is not what is required for \
`image` ({})",
provided, required,
),
Self::Array2dCompatibleNot3d => write!(
f,
"the `array_2d_compatible` flag was enabled, but the image type was not 3D",
),
Self::ArrayLayerOutOfRange {
provided_array_layer,
image_array_layers,
} => write!(
f,
"the provided array layer ({}) is not less than the number of array layers in the image ({})",
provided_array_layer, image_array_layers,
),
Self::AspectNotAllowed {
provided_aspect,
allowed_aspects,
} => write!(
f,
"the provided aspect ({:?}) is not present in the image, or is not allowed ({:?})",
provided_aspect, allowed_aspects,
),
Self::BlockTexelViewCompatibleNotCompressed => write!(
f,
"the `block_texel_view_compatible` flag was enabled, but the given format was not \
compressed",
),
Self::CubeCompatibleNot2d => write!(
f,
"the `cube_compatible` flag was enabled, but the image type was not 2D",
),
Self::CubeCompatibleNotEnoughArrayLayers => write!(
f,
"the `cube_compatible` flag was enabled, but the number of array layers was less \
than 6",
),
Self::CubeCompatibleNotSquare => write!(
f,
"the `cube_compatible` flag was enabled, but the image dimensions were not square",
),
Self::CubeCompatibleMultisampling => write!(
f,
"the `cube_compatible` flag was enabled together with multisampling",
),
Self::DedicatedAllocationMismatch => write!(
f,
"the memory was created dedicated to a resource, but not to this image",
),
Self::DedicatedAllocationRequired => write!(
f,
"a dedicated allocation is required for this image, but one was not provided"
),
Self::DepthStencilFormatsNotSupported => write!(
f,
"the image has a format with both a depth and a stencil aspect, which is not \
supported for this operation",
),
Self::DisjointFormatNotSupported => write!(
f,
"the `disjoint` flag was enabled, but the given format is either not multi-planar, \
or does not support disjoint images",
),
Self::ExternalMemoryInvalidInitialLayout => write!(
f,
"one or more external memory handle types were provided, but the initial layout \
was not `Undefined`",
),
Self::FormatNotSupported => {
write!(f, "the given format was not supported by the device")
}
Self::FormatUsageNotSupported { .. } => write!(
f,
"a requested usage flag was not supported by the given format",
),
Self::ImageFormatPropertiesNotSupported => write!(
f,
"the image configuration as queried through the `image_format_properties` function \
was not supported by the device",
),
Self::MaxArrayLayersExceeded { .. } => write!(
f,
"the number of array layers exceeds the maximum supported by the device for this \
image configuration",
),
Self::MaxDimensionsExceeded { .. } => write!(
f,
"the specified dimensions exceed the maximum supported by the device for this \
image configuration",
),
Self::MaxFramebufferDimensionsExceeded { .. } => write!(
f,
"the usage included one of the attachment types, and the specified width and \
height exceeded the `max_framebuffer_width` or `max_framebuffer_height` limits",
),
Self::MaxMipLevelsExceeded { .. } => write!(
f,
"the maximum number of mip levels for the given dimensions has been exceeded",
),
Self::MemoryAllocationNotAligned {
allocations_index,
allocation_offset,
required_alignment,
} => write!(
f,
"in `allocations` element {}, the offset of the allocation ({}) does not have the \
required alignment ({:?})",
allocations_index, allocation_offset, required_alignment,
),
Self::MemoryAllocationTooSmall {
allocations_index,
allocation_size,
required_size,
} => write!(
f,
"in `allocations` element {}, the size of the allocation ({}) is smaller than what \
is required ({})",
allocations_index, allocation_size, required_size,
),
Self::MemoryExternalHandleTypesDisjoint {
allocations_index, ..
} => write!(
f,
"in `allocations` element {}, the memory was created with export handle types, but \
none of these handle types were enabled on the image",
allocations_index,
),
Self::MemoryImportedHandleTypeNotEnabled {
allocations_index, ..
} => write!(
f,
"in `allocations` element {}, the memory was created with an import, but the \
import's handle type was not enabled on the image",
allocations_index,
),
Self::MemoryProtectedMismatch {
allocations_index,
image_protected,
memory_protected,
} => write!(
f,
"in `allocations` element {}, the protection of image ({}) and memory ({}) are not \
equal",
allocations_index, image_protected, memory_protected,
),
Self::MemoryTypeNotAllowed {
allocations_index,
provided_memory_type_index,
allowed_memory_type_bits,
} => write!(
f,
"in `allocations` element {}, the provided memory type ({}) is not one of the \
allowed memory types (",
allocations_index, provided_memory_type_index,
)
.and_then(|_| {
let mut first = true;
for i in (0..size_of_val(allowed_memory_type_bits))
.filter(|i| allowed_memory_type_bits & (1 << i) != 0)
{
if first {
write!(f, "{}", i)?;
first = false;
} else {
write!(f, ", {}", i)?;
}
}
Ok(())
})
.and_then(|_| write!(f, ") that can be bound to this buffer")),
Self::MipLevelOutOfRange {
provided_mip_level,
image_mip_levels,
} => write!(
f,
"the provided mip level ({}) is not less than the number of mip levels in the image ({})",
provided_mip_level, image_mip_levels,
),
Self::MultisampleCubeCompatible => write!(
f,
"multisampling was enabled, and the `cube_compatible` flag was set",
),
Self::MultisampleLinearTiling => {
write!(f, "multisampling was enabled, and tiling was `Linear`")
}
Self::MultisampleMultipleMipLevels => write!(
f,
"multisampling was enabled, and multiple mip levels were specified",
),
Self::MultisampleNot2d => write!(
f,
"multisampling was enabled, but the image type was not 2D",
),
Self::OptimalTilingNotSupported => write!(
f,
"the image has optimal tiling, which is not supported for this operation",
),
Self::SampleCountNotSupported { .. } => write!(
f,
"the sample count is not supported by the device for this image configuration",
),
Self::SharingQueueFamilyIndexOutOfRange { .. } => write!(
f,
"the sharing mode was set to `Concurrent`, but one of the specified queue family \
indices was out of range",
),
Self::StencilUsageMismatch {
usage: _,
stencil_usage: _,
} => write!(
f,
"the provided `usage` and `stencil_usage` have different values for \
`depth_stencil_attachment` or `transient_attachment`",
),
Self::YcbcrFormatInvalidDimensions => write!(
f,
"a YCbCr format was given, but the specified width and/or height was not a \
multiple of 2 as required by the format's chroma subsampling",
),
Self::YcbcrFormatMultipleMipLevels => write!(
f,
"a YCbCr format was given, and multiple mip levels were specified",
),
Self::YcbcrFormatMultisampling => {
write!(f, "a YCbCr format was given, and multisampling was enabled")
}
Self::YcbcrFormatNot2d => {
write!(f, "a YCbCr format was given, but the image type was not 2D")
}
Self::DirectImageViewCreationFailed(e) => write!(f, "Image view creation failed {}", e),
Self::DrmFormatModifierRequiresCreateInfo => write!(f, "If and only if tiling is `DRMFormatModifier`, then `image_drm_format_modifier_create_info` must be `Some`"),
}
}
}
impl From<VulkanError> for ImageError {
fn from(err: VulkanError) -> Self {
Self::VulkanError(err)
}
}
impl From<AllocationCreationError> for ImageError {
fn from(err: AllocationCreationError) -> Self {
Self::AllocError(err)
}
}
impl From<RequirementNotMet> for ImageError {
fn from(err: RequirementNotMet) -> Self {
Self::RequirementNotMet {
required_for: err.required_for,
requires_one_of: err.requires_one_of,
}
}
}
#[cfg(test)]
mod tests {
use super::{ImageCreateInfo, ImageError, ImageUsage, RawImage};
use crate::{
format::Format,
image::{
sys::SubresourceRangeIterator, ImageAspect, ImageAspects, ImageCreateFlags,
ImageDimensions, ImageSubresourceRange, SampleCount,
},
DeviceSize, RequiresOneOf,
};
use smallvec::SmallVec;
#[test]
fn create_sampled() {
let (device, _) = gfx_dev_and_queue!();
let _ = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
usage: ImageUsage::SAMPLED,
..Default::default()
},
)
.unwrap();
}
#[test]
fn create_transient() {
let (device, _) = gfx_dev_and_queue!();
let _ = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
usage: ImageUsage::TRANSIENT_ATTACHMENT | ImageUsage::COLOR_ATTACHMENT,
..Default::default()
},
)
.unwrap();
}
#[test]
fn zero_mipmap() {
let (device, _) = gfx_dev_and_queue!();
assert_should_panic!({
let _ = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
mip_levels: 0,
usage: ImageUsage::SAMPLED,
..Default::default()
},
);
});
}
#[test]
fn mipmaps_too_high() {
let (device, _) = gfx_dev_and_queue!();
let res = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
mip_levels: u32::MAX,
usage: ImageUsage::SAMPLED,
..Default::default()
},
);
match res {
Err(ImageError::MaxMipLevelsExceeded { .. }) => (),
_ => panic!(),
};
}
#[test]
fn shader_storage_image_multisample() {
let (device, _) = gfx_dev_and_queue!();
let res = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
samples: SampleCount::Sample2,
usage: ImageUsage::STORAGE,
..Default::default()
},
);
match res {
Err(ImageError::RequirementNotMet {
requires_one_of: RequiresOneOf { features, .. },
..
}) if features.contains(&"shader_storage_image_multisample") => (),
Err(ImageError::SampleCountNotSupported { .. }) => (), // unlikely but possible
_ => panic!(),
};
}
#[test]
fn compressed_not_color_attachment() {
let (device, _) = gfx_dev_and_queue!();
let res = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::ASTC_5x4_UNORM_BLOCK),
usage: ImageUsage::COLOR_ATTACHMENT,
..Default::default()
},
);
match res {
Err(ImageError::FormatNotSupported) => (),
Err(ImageError::FormatUsageNotSupported {
usage: "color_attachment",
}) => (),
_ => panic!(),
};
}
#[test]
fn transient_forbidden_with_some_usages() {
let (device, _) = gfx_dev_and_queue!();
assert_should_panic!({
let _ = RawImage::new(
device,
ImageCreateInfo {
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 32,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
usage: ImageUsage::TRANSIENT_ATTACHMENT | ImageUsage::SAMPLED,
..Default::default()
},
);
})
}
#[test]
fn cubecompatible_dims_mismatch() {
let (device, _) = gfx_dev_and_queue!();
let res = RawImage::new(
device,
ImageCreateInfo {
flags: ImageCreateFlags::CUBE_COMPATIBLE,
dimensions: ImageDimensions::Dim2d {
width: 32,
height: 64,
array_layers: 1,
},
format: Some(Format::R8G8B8A8_UNORM),
usage: ImageUsage::SAMPLED,
..Default::default()
},
);
match res {
Err(ImageError::CubeCompatibleNotEnoughArrayLayers) => (),
Err(ImageError::CubeCompatibleNotSquare) => (),
_ => panic!(),
};
}
#[test]
#[allow(clippy::erasing_op, clippy::identity_op)]
fn subresource_range_iterator() {
// A fictitious set of aspects that no real image would actually ever have.
let image_aspect_list: SmallVec<[ImageAspect; 4]> = (ImageAspects::COLOR
| ImageAspects::DEPTH
| ImageAspects::STENCIL
| ImageAspects::PLANE_0)
.into_iter()
.collect();
let image_mip_levels = 6;
let image_array_layers = 8;
let mip = image_array_layers as DeviceSize;
let asp = mip * image_mip_levels as DeviceSize;
// Whole image
let mut iter = SubresourceRangeIterator::new(
ImageSubresourceRange {
aspects: ImageAspects::COLOR
| ImageAspects::DEPTH
| ImageAspects::STENCIL
| ImageAspects::PLANE_0,
mip_levels: 0..6,
array_layers: 0..8,
},
&image_aspect_list,
asp,
image_mip_levels,
mip,
image_array_layers,
);
assert_eq!(iter.next(), Some(0 * asp..4 * asp));
assert_eq!(iter.next(), None);
// Only some aspects
let mut iter = SubresourceRangeIterator::new(
ImageSubresourceRange {
aspects: ImageAspects::COLOR | ImageAspects::DEPTH | ImageAspects::PLANE_0,
mip_levels: 0..6,
array_layers: 0..8,
},
&image_aspect_list,
asp,
image_mip_levels,
mip,
image_array_layers,
);
assert_eq!(iter.next(), Some(0 * asp..2 * asp));
assert_eq!(iter.next(), Some(3 * asp..4 * asp));
assert_eq!(iter.next(), None);
// Two aspects, and only some of the mip levels
let mut iter = SubresourceRangeIterator::new(
ImageSubresourceRange {
aspects: ImageAspects::DEPTH | ImageAspects::STENCIL,
mip_levels: 2..4,
array_layers: 0..8,
},
&image_aspect_list,
asp,
image_mip_levels,
mip,
image_array_layers,
);
assert_eq!(iter.next(), Some(1 * asp + 2 * mip..1 * asp + 4 * mip));
assert_eq!(iter.next(), Some(2 * asp + 2 * mip..2 * asp + 4 * mip));
assert_eq!(iter.next(), None);
// One aspect, one mip level, only some of the array layers
let mut iter = SubresourceRangeIterator::new(
ImageSubresourceRange {
aspects: ImageAspects::COLOR,
mip_levels: 0..1,
array_layers: 2..4,
},
&image_aspect_list,
asp,
image_mip_levels,
mip,
image_array_layers,
);
assert_eq!(
iter.next(),
Some(0 * asp + 0 * mip + 2..0 * asp + 0 * mip + 4)
);
assert_eq!(iter.next(), None);
// Two aspects, two mip levels, only some of the array layers
let mut iter = SubresourceRangeIterator::new(
ImageSubresourceRange {
aspects: ImageAspects::DEPTH | ImageAspects::STENCIL,
mip_levels: 2..4,
array_layers: 6..8,
},
&image_aspect_list,
asp,
image_mip_levels,
mip,
image_array_layers,
);
assert_eq!(
iter.next(),
Some(1 * asp + 2 * mip + 6..1 * asp + 2 * mip + 8)
);
assert_eq!(
iter.next(),
Some(1 * asp + 3 * mip + 6..1 * asp + 3 * mip + 8)
);
assert_eq!(
iter.next(),
Some(2 * asp + 2 * mip + 6..2 * asp + 2 * mip + 8)
);
assert_eq!(
iter.next(),
Some(2 * asp + 3 * mip + 6..2 * asp + 3 * mip + 8)
);
assert_eq!(iter.next(), None);
}
}