src/sampler/ycbcr.rs

// Copyright (c) 2022 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.

//! Conversion from sampled YCbCr image data to RGB shader data.
//!
//! A sampler YCbCr conversion is an object that assists a sampler when converting from YCbCr
//! formats and/or YCbCr texel input data. It is used to read frames of video data within a shader,
//! possibly to apply it as texture on a rendered primitive. Sampler YCbCr conversion can only be
//! used with certain formats, and conversely, some formats require the use of a sampler YCbCr
//! conversion to be sampled at all.
//!
//! A sampler YCbCr conversion can only be used with a combined image sampler descriptor in a
//! descriptor set. The conversion must be attached on both the image view and sampler in the
//! descriptor, and the sampler must be included in the descriptor set layout as an immutable
//! sampler.
//!
//! # Examples
//!
//! ```
//! # let device: std::sync::Arc<vulkano::device::Device> = return;
//! # let image_data: Vec<u8> = return;
//! # let queue: std::sync::Arc<vulkano::device::Queue> = return;
//! # let memory_allocator: vulkano::memory::allocator::StandardMemoryAllocator = return;
//! # let descriptor_set_allocator: vulkano::descriptor_set::allocator::StandardDescriptorSetAllocator = return;
//! # let mut command_buffer_builder: vulkano::command_buffer::AutoCommandBufferBuilder<vulkano::command_buffer::PrimaryAutoCommandBuffer> = return;
//! use vulkano::descriptor_set::{PersistentDescriptorSet, WriteDescriptorSet};
//! use vulkano::descriptor_set::layout::{DescriptorSetLayout, DescriptorSetLayoutBinding, DescriptorSetLayoutCreateInfo, DescriptorType};
//! use vulkano::format::Format;
//! use vulkano::image::{ImmutableImage, ImageCreateFlags, ImageDimensions, ImageUsage, MipmapsCount};
//! use vulkano::image::view::{ImageView, ImageViewCreateInfo};
//! use vulkano::sampler::{Sampler, SamplerCreateInfo};
//! use vulkano::sampler::ycbcr::{SamplerYcbcrConversion, SamplerYcbcrConversionCreateInfo, SamplerYcbcrModelConversion};
//! use vulkano::shader::ShaderStage;
//!
//! let conversion = SamplerYcbcrConversion::new(device.clone(), SamplerYcbcrConversionCreateInfo {
//!     format: Some(Format::G8_B8_R8_3PLANE_420_UNORM),
//!     ycbcr_model: SamplerYcbcrModelConversion::YcbcrIdentity,
//!     ..Default::default()
//! })
//! .unwrap();
//!
//! let sampler = Sampler::new(device.clone(), SamplerCreateInfo {
//!     sampler_ycbcr_conversion: Some(conversion.clone()),
//!     ..Default::default()
//! })
//! .unwrap();
//!
//! let descriptor_set_layout = DescriptorSetLayout::new(
//!     device.clone(),
//!         DescriptorSetLayoutCreateInfo {
//!         bindings: [(
//!             0,
//!             DescriptorSetLayoutBinding {
//!                 stages: ShaderStage::Fragment.into(),
//!                 immutable_samplers: vec![sampler],
//!                 ..DescriptorSetLayoutBinding::descriptor_type(DescriptorType::CombinedImageSampler)
//!             },
//!         )]
//!         .into(),
//!         ..Default::default()
//!     },
//! ).unwrap();
//!
//! let image = ImmutableImage::from_iter(
//!     &memory_allocator,
//!     image_data,
//!     ImageDimensions::Dim2d { width: 1920, height: 1080, array_layers: 1 },
//!     MipmapsCount::One,
//!     Format::G8_B8_R8_3PLANE_420_UNORM,
//!     &mut command_buffer_builder,
//! ).unwrap();
//!
//! let create_info = ImageViewCreateInfo {
//!     sampler_ycbcr_conversion: Some(conversion.clone()),
//!     ..ImageViewCreateInfo::from_image(&image)
//! };
//! let image_view = ImageView::new(image, create_info).unwrap();
//!
//! let descriptor_set = PersistentDescriptorSet::new(
//!     &descriptor_set_allocator,
//!     descriptor_set_layout.clone(),
//!     [WriteDescriptorSet::image_view(0, image_view)],
//! ).unwrap();
//! ```

use crate::{
    device::{Device, DeviceOwned},
    format::{ChromaSampling, Format, FormatFeatures, NumericType},
    macros::{impl_id_counter, vulkan_enum},
    sampler::{ComponentMapping, ComponentSwizzle, Filter},
    OomError, RequirementNotMet, RequiresOneOf, Version, VulkanError, VulkanObject,
};
use std::{
    error::Error,
    fmt::{Display, Error as FmtError, Formatter},
    mem::MaybeUninit,
    num::NonZeroU64,
    ptr,
    sync::Arc,
};

/// Describes how sampled image data should converted from a YCbCr representation to an RGB one.
#[derive(Debug)]
pub struct SamplerYcbcrConversion {
    handle: ash::vk::SamplerYcbcrConversion,
    device: Arc<Device>,
    id: NonZeroU64,

    format: Option<Format>,
    ycbcr_model: SamplerYcbcrModelConversion,
    ycbcr_range: SamplerYcbcrRange,
    component_mapping: ComponentMapping,
    chroma_offset: [ChromaLocation; 2],
    chroma_filter: Filter,
    force_explicit_reconstruction: bool,
}

impl SamplerYcbcrConversion {
    /// Creates a new `SamplerYcbcrConversion`.
    ///
    /// The [`sampler_ycbcr_conversion`](crate::device::Features::sampler_ycbcr_conversion)
    /// feature must be enabled on the device.
    pub fn new(
        device: Arc<Device>,
        create_info: SamplerYcbcrConversionCreateInfo,
    ) -> Result<Arc<SamplerYcbcrConversion>, SamplerYcbcrConversionCreationError> {
        let SamplerYcbcrConversionCreateInfo {
            format,
            ycbcr_model,
            ycbcr_range,
            component_mapping,
            chroma_offset,
            chroma_filter,
            force_explicit_reconstruction,
            _ne: _,
        } = create_info;

        if !device.enabled_features().sampler_ycbcr_conversion {
            return Err(SamplerYcbcrConversionCreationError::RequirementNotMet {
                required_for: "`SamplerYcbcrConversion::new`",
                requires_one_of: RequiresOneOf {
                    features: &["sampler_ycbcr_conversion"],
                    ..Default::default()
                },
            });
        }

        let format = match format {
            Some(f) => f,
            None => {
                return Err(SamplerYcbcrConversionCreationError::FormatMissing);
            }
        };

        // VUID-VkSamplerYcbcrConversionCreateInfo-format-parameter
        format.validate_device(&device)?;

        // VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-parameter
        ycbcr_model.validate_device(&device)?;

        // VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-parameter
        ycbcr_range.validate_device(&device)?;

        // VUID-VkComponentMapping-r-parameter
        component_mapping.r.validate_device(&device)?;

        // VUID-VkComponentMapping-g-parameter
        component_mapping.g.validate_device(&device)?;

        // VUID-VkComponentMapping-b-parameter
        component_mapping.b.validate_device(&device)?;

        // VUID-VkComponentMapping-a-parameter
        component_mapping.a.validate_device(&device)?;

        for offset in chroma_offset {
            // VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-parameter
            // VUID-VkSamplerYcbcrConversionCreateInfo-yChromaOffset-parameter
            offset.validate_device(&device)?;
        }

        // VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-parameter
        chroma_filter.validate_device(&device)?;

        // VUID-VkSamplerYcbcrConversionCreateInfo-format-04061
        if !format
            .type_color()
            .map_or(false, |ty| ty == NumericType::UNORM)
        {
            return Err(SamplerYcbcrConversionCreationError::FormatNotUnorm);
        }

        // Use unchecked, because all validation has been done above.
        let potential_format_features = unsafe {
            device
                .physical_device()
                .format_properties_unchecked(format)
                .potential_format_features()
        };

        // VUID-VkSamplerYcbcrConversionCreateInfo-format-01650
        if !potential_format_features.intersects(
            FormatFeatures::MIDPOINT_CHROMA_SAMPLES | FormatFeatures::COSITED_CHROMA_SAMPLES,
        ) {
            return Err(SamplerYcbcrConversionCreationError::FormatNotSupported);
        }

        if let Some(chroma_sampling @ (ChromaSampling::Mode422 | ChromaSampling::Mode420)) =
            format.ycbcr_chroma_sampling()
        {
            let chroma_offsets_to_check = match chroma_sampling {
                ChromaSampling::Mode420 => &chroma_offset[0..2],
                ChromaSampling::Mode422 => &chroma_offset[0..1],
                _ => unreachable!(),
            };

            for offset in chroma_offsets_to_check {
                match offset {
                    ChromaLocation::CositedEven => {
                        // VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01651
                        if !potential_format_features
                            .intersects(FormatFeatures::COSITED_CHROMA_SAMPLES)
                        {
                            return Err(
                                SamplerYcbcrConversionCreationError::FormatChromaOffsetNotSupported,
                            );
                        }
                    }
                    ChromaLocation::Midpoint => {
                        // VUID-VkSamplerYcbcrConversionCreateInfo-xChromaOffset-01652
                        if !potential_format_features
                            .intersects(FormatFeatures::MIDPOINT_CHROMA_SAMPLES)
                        {
                            return Err(
                                SamplerYcbcrConversionCreationError::FormatChromaOffsetNotSupported,
                            );
                        }
                    }
                }
            }

            // VUID-VkSamplerYcbcrConversionCreateInfo-components-02581
            let g_ok = component_mapping.g_is_identity();

            // VUID-VkSamplerYcbcrConversionCreateInfo-components-02582
            let a_ok = component_mapping.a_is_identity()
                || matches!(
                    component_mapping.a,
                    ComponentSwizzle::One | ComponentSwizzle::Zero
                );

            // VUID-VkSamplerYcbcrConversionCreateInfo-components-02583
            // VUID-VkSamplerYcbcrConversionCreateInfo-components-02584
            // VUID-VkSamplerYcbcrConversionCreateInfo-components-02585
            let rb_ok1 = component_mapping.r_is_identity() && component_mapping.b_is_identity();
            let rb_ok2 = matches!(component_mapping.r, ComponentSwizzle::Blue)
                && matches!(component_mapping.b, ComponentSwizzle::Red);

            if !(g_ok && a_ok && (rb_ok1 || rb_ok2)) {
                return Err(SamplerYcbcrConversionCreationError::FormatInvalidComponentMapping);
            }
        }

        let components_bits = {
            let bits = format.components();
            component_mapping
                .component_map()
                .map(move |i| i.map(|i| bits[i]))
        };

        // VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrModel-01655
        if ycbcr_model != SamplerYcbcrModelConversion::RgbIdentity
            && !components_bits[0..3]
                .iter()
                .all(|b| b.map_or(false, |b| b != 0))
        {
            return Err(SamplerYcbcrConversionCreationError::YcbcrModelInvalidComponentMapping);
        }

        // VUID-VkSamplerYcbcrConversionCreateInfo-ycbcrRange-02748
        if ycbcr_range == SamplerYcbcrRange::ItuNarrow {
            // TODO: Spec doesn't say how many bits `Zero` and `One` are considered to have, so
            // just skip them for now.
            for &bits in components_bits[0..3].iter().flatten() {
                if bits < 8 {
                    return Err(SamplerYcbcrConversionCreationError::YcbcrRangeFormatNotEnoughBits);
                }
            }
        }

        // VUID-VkSamplerYcbcrConversionCreateInfo-forceExplicitReconstruction-01656
        if force_explicit_reconstruction
            && !potential_format_features.intersects(FormatFeatures::
                SAMPLED_IMAGE_YCBCR_CONVERSION_CHROMA_RECONSTRUCTION_EXPLICIT_FORCEABLE)
        {
            return Err(
                SamplerYcbcrConversionCreationError::FormatForceExplicitReconstructionNotSupported,
            );
        }

        match chroma_filter {
            Filter::Nearest => (),
            Filter::Linear => {
                // VUID-VkSamplerYcbcrConversionCreateInfo-chromaFilter-01657
                if !potential_format_features
                    .intersects(FormatFeatures::SAMPLED_IMAGE_YCBCR_CONVERSION_LINEAR_FILTER)
                {
                    return Err(
                        SamplerYcbcrConversionCreationError::FormatLinearFilterNotSupported,
                    );
                }
            }
            Filter::Cubic => {
                return Err(SamplerYcbcrConversionCreationError::CubicFilterNotSupported);
            }
        }

        let create_info = ash::vk::SamplerYcbcrConversionCreateInfo {
            format: format.into(),
            ycbcr_model: ycbcr_model.into(),
            ycbcr_range: ycbcr_range.into(),
            components: component_mapping.into(),
            x_chroma_offset: chroma_offset[0].into(),
            y_chroma_offset: chroma_offset[1].into(),
            chroma_filter: chroma_filter.into(),
            force_explicit_reconstruction: force_explicit_reconstruction as ash::vk::Bool32,
            ..Default::default()
        };

        let handle = unsafe {
            let fns = device.fns();
            let create_sampler_ycbcr_conversion = if device.api_version() >= Version::V1_1 {
                fns.v1_1.create_sampler_ycbcr_conversion
            } else {
                fns.khr_sampler_ycbcr_conversion
                    .create_sampler_ycbcr_conversion_khr
            };

            let mut output = MaybeUninit::uninit();
            create_sampler_ycbcr_conversion(
                device.handle(),
                &create_info,
                ptr::null(),
                output.as_mut_ptr(),
            )
            .result()
            .map_err(VulkanError::from)?;
            output.assume_init()
        };

        Ok(Arc::new(SamplerYcbcrConversion {
            handle,
            device,
            id: Self::next_id(),
            format: Some(format),
            ycbcr_model,
            ycbcr_range,
            component_mapping,
            chroma_offset,
            chroma_filter,
            force_explicit_reconstruction,
        }))
    }

    /// Creates a new `SamplerYcbcrConversion` from a raw object handle.
    ///
    /// # Safety
    ///
    /// - `handle` must be a valid Vulkan object handle created from `device`.
    /// - `create_info` must match the info used to create the object.
    /// - `create_info.format` must be `Some`.
    #[inline]
    pub unsafe fn from_handle(
        device: Arc<Device>,
        handle: ash::vk::SamplerYcbcrConversion,
        create_info: SamplerYcbcrConversionCreateInfo,
    ) -> Arc<SamplerYcbcrConversion> {
        let SamplerYcbcrConversionCreateInfo {
            format,
            ycbcr_model,
            ycbcr_range,
            component_mapping,
            chroma_offset,
            chroma_filter,
            force_explicit_reconstruction,
            _ne: _,
        } = create_info;

        Arc::new(SamplerYcbcrConversion {
            handle,
            device,
            id: Self::next_id(),
            format,
            ycbcr_model,
            ycbcr_range,
            component_mapping,
            chroma_offset,
            chroma_filter,
            force_explicit_reconstruction,
        })
    }

    /// Returns the chroma filter used by the conversion.
    #[inline]
    pub fn chroma_filter(&self) -> Filter {
        self.chroma_filter
    }

    /// Returns the chroma offsets used by the conversion.
    #[inline]
    pub fn chroma_offset(&self) -> [ChromaLocation; 2] {
        self.chroma_offset
    }

    /// Returns the component mapping of the conversion.
    #[inline]
    pub fn component_mapping(&self) -> ComponentMapping {
        self.component_mapping
    }

    /// Returns whether the conversion has forced explicit reconstruction to be enabled.
    #[inline]
    pub fn force_explicit_reconstruction(&self) -> bool {
        self.force_explicit_reconstruction
    }

    /// Returns the format that the conversion was created for.
    #[inline]
    pub fn format(&self) -> Option<Format> {
        self.format
    }

    /// Returns the YCbCr model of the conversion.
    #[inline]
    pub fn ycbcr_model(&self) -> SamplerYcbcrModelConversion {
        self.ycbcr_model
    }

    /// Returns the YCbCr range of the conversion.
    #[inline]
    pub fn ycbcr_range(&self) -> SamplerYcbcrRange {
        self.ycbcr_range
    }

    /// Returns whether `self` is equal or identically defined to `other`.
    #[inline]
    pub fn is_identical(&self, other: &SamplerYcbcrConversion) -> bool {
        self.handle == other.handle || {
            let &Self {
                handle: _,
                device: _,
                id: _,
                format,
                ycbcr_model,
                ycbcr_range,
                component_mapping,
                chroma_offset,
                chroma_filter,
                force_explicit_reconstruction,
            } = self;

            format == other.format
                && ycbcr_model == other.ycbcr_model
                && ycbcr_range == other.ycbcr_range
                && component_mapping == other.component_mapping
                && chroma_offset == other.chroma_offset
                && chroma_filter == other.chroma_filter
                && force_explicit_reconstruction == other.force_explicit_reconstruction
        }
    }
}

impl Drop for SamplerYcbcrConversion {
    #[inline]
    fn drop(&mut self) {
        unsafe {
            let fns = self.device.fns();
            let destroy_sampler_ycbcr_conversion = if self.device.api_version() >= Version::V1_1 {
                fns.v1_1.destroy_sampler_ycbcr_conversion
            } else {
                fns.khr_sampler_ycbcr_conversion
                    .destroy_sampler_ycbcr_conversion_khr
            };

            destroy_sampler_ycbcr_conversion(self.device.handle(), self.handle, ptr::null());
        }
    }
}

unsafe impl VulkanObject for SamplerYcbcrConversion {
    type Handle = ash::vk::SamplerYcbcrConversion;

    #[inline]
    fn handle(&self) -> Self::Handle {
        self.handle
    }
}

unsafe impl DeviceOwned for SamplerYcbcrConversion {
    #[inline]
    fn device(&self) -> &Arc<Device> {
        &self.device
    }
}

impl_id_counter!(SamplerYcbcrConversion);

/// Error that can happen when creating a `SamplerYcbcrConversion`.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum SamplerYcbcrConversionCreationError {
    /// Not enough memory.
    OomError(OomError),

    RequirementNotMet {
        required_for: &'static str,
        requires_one_of: RequiresOneOf,
    },

    /// The `Cubic` filter was specified.
    CubicFilterNotSupported,

    /// No format was specified when one was required.
    FormatMissing,

    /// The format has a color type other than `UNORM`.
    FormatNotUnorm,

    /// The format does not support sampler YCbCr conversion.
    FormatNotSupported,

    /// The format does not support the chosen chroma offsets.
    FormatChromaOffsetNotSupported,

    /// The component mapping was not valid for use with the chosen format.
    FormatInvalidComponentMapping,

    /// The format does not support `force_explicit_reconstruction`.
    FormatForceExplicitReconstructionNotSupported,

    /// The format does not support the `Linear` filter.
    FormatLinearFilterNotSupported,

    /// The component mapping was not valid for use with the chosen YCbCr model.
    YcbcrModelInvalidComponentMapping,

    /// For the chosen `ycbcr_range`, the R, G or B components being read from the `format` do not
    /// have the minimum number of required bits.
    YcbcrRangeFormatNotEnoughBits,
}

impl Error for SamplerYcbcrConversionCreationError {
    fn source(&self) -> Option<&(dyn Error + 'static)> {
        match self {
            SamplerYcbcrConversionCreationError::OomError(err) => Some(err),
            _ => None,
        }
    }
}

impl Display for SamplerYcbcrConversionCreationError {
    fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), FmtError> {
        match self {
            Self::OomError(_) => write!(f, "not enough memory available"),
            Self::RequirementNotMet {
                required_for,
                requires_one_of,
            } => write!(
                f,
                "a requirement was not met for: {}; requires one of: {}",
                required_for, requires_one_of,
            ),
            Self::CubicFilterNotSupported => {
                write!(f, "the `Cubic` filter was specified")
            }
            Self::FormatMissing => {
                write!(f, "no format was specified when one was required")
            }
            Self::FormatNotUnorm => {
                write!(f, "the format has a color type other than `UNORM`")
            }
            Self::FormatNotSupported => {
                write!(f, "the format does not support sampler YCbCr conversion")
            }
            Self::FormatChromaOffsetNotSupported => {
                write!(f, "the format does not support the chosen chroma offsets")
            }
            Self::FormatInvalidComponentMapping => write!(
                f,
                "the component mapping was not valid for use with the chosen format",
            ),
            Self::FormatForceExplicitReconstructionNotSupported => write!(
                f,
                "the format does not support `force_explicit_reconstruction`",
            ),
            Self::FormatLinearFilterNotSupported => {
                write!(f, "the format does not support the `Linear` filter")
            }
            Self::YcbcrModelInvalidComponentMapping => write!(
                f,
                "the component mapping was not valid for use with the chosen YCbCr model",
            ),
            Self::YcbcrRangeFormatNotEnoughBits => write!(
                f,
                "for the chosen `ycbcr_range`, the R, G or B components being read from the \
                `format` do not have the minimum number of required bits",
            ),
        }
    }
}

impl From<OomError> for SamplerYcbcrConversionCreationError {
    fn from(err: OomError) -> SamplerYcbcrConversionCreationError {
        SamplerYcbcrConversionCreationError::OomError(err)
    }
}

impl From<VulkanError> for SamplerYcbcrConversionCreationError {
    fn from(err: VulkanError) -> SamplerYcbcrConversionCreationError {
        match err {
            err @ VulkanError::OutOfHostMemory => {
                SamplerYcbcrConversionCreationError::OomError(OomError::from(err))
            }
            err @ VulkanError::OutOfDeviceMemory => {
                SamplerYcbcrConversionCreationError::OomError(OomError::from(err))
            }
            _ => panic!("unexpected error: {:?}", err),
        }
    }
}

impl From<RequirementNotMet> for SamplerYcbcrConversionCreationError {
    fn from(err: RequirementNotMet) -> Self {
        Self::RequirementNotMet {
            required_for: err.required_for,
            requires_one_of: err.requires_one_of,
        }
    }
}

/// Parameters to create a new `SamplerYcbcrConversion`.
#[derive(Clone, Debug)]
pub struct SamplerYcbcrConversionCreateInfo {
    /// The image view format that this conversion will read data from. The conversion cannot be
    /// used with image views of any other format.
    ///
    /// The format must support YCbCr conversions, meaning that its `FormatFeatures` must support
    /// at least one of `cosited_chroma_samples` or `midpoint_chroma_samples`.
    ///
    /// If this is set to a format that has chroma subsampling (contains `422` or `420` in the name)
    /// then `component_mapping` is restricted as follows:
    /// - `g` must be identity swizzled.
    /// - `a` must be identity swizzled or `Zero` or `One`.
    /// - `r` and `b` must be identity swizzled or mapped to each other.
    ///
    /// Compatibility notice: currently, this value must be `Some`, but future additions may allow
    /// `None` as a valid value as well.
    ///
    /// The default value is `None`.
    pub format: Option<Format>,

    /// The conversion between the input color model and the output RGB color model.
    ///
    /// If this is not set to `RgbIdentity`, then the `r`, `g` and `b` components of
    /// `component_mapping` must not be `Zero` or `One`, and the component being read must exist in
    /// `format` (must be represented as a nonzero number of bits).
    ///
    /// The default value is [`RgbIdentity`](SamplerYcbcrModelConversion::RgbIdentity).
    pub ycbcr_model: SamplerYcbcrModelConversion,

    /// If `ycbcr_model` is not `RgbIdentity`, specifies the range expansion of the input values
    /// that should be used.
    ///
    /// If this is set to `ItuNarrow`, then the `r`, `g` and `b` components of `component_mapping`
    /// must each map to a component of `format` that is represented with at least 8 bits.
    ///
    /// The default value is [`ItuFull`](SamplerYcbcrRange::ItuFull).
    pub ycbcr_range: SamplerYcbcrRange,

    /// The mapping to apply to the components of the input format, before color model conversion
    /// and range expansion.
    ///
    /// The default value is [`ComponentMapping::identity()`].
    pub component_mapping: ComponentMapping,

    /// For formats with chroma subsampling and a `Linear` filter, specifies the sampled location
    /// for the subsampled components, in the x and y direction.
    ///
    /// The value is ignored if the filter is `Nearest` or the corresponding axis is not chroma
    /// subsampled. If the value is not ignored, the format must support the chosen mode.
    ///
    /// The default value is [`CositedEven`](ChromaLocation::CositedEven) for both axes.
    pub chroma_offset: [ChromaLocation; 2],

    /// For formats with chroma subsampling, specifies the filter used for reconstructing the chroma
    /// components to full resolution.
    ///
    /// The `Cubic` filter is not supported. If `Linear` is used, the format must support it.
    ///
    /// The default value is [`Nearest`](Filter::Nearest).
    pub chroma_filter: Filter,

    /// Forces explicit reconstruction if the implementation does not use it by default. The format
    /// must support it. See
    /// [the spec](https://registry.khronos.org/vulkan/specs/1.2-extensions/html/chap16.html#textures-chroma-reconstruction)
    /// for more information.
    ///
    /// The default value is `false`.
    pub force_explicit_reconstruction: bool,

    pub _ne: crate::NonExhaustive,
}

impl Default for SamplerYcbcrConversionCreateInfo {
    #[inline]
    fn default() -> Self {
        Self {
            format: None,
            ycbcr_model: SamplerYcbcrModelConversion::RgbIdentity,
            ycbcr_range: SamplerYcbcrRange::ItuFull,
            component_mapping: ComponentMapping::identity(),
            chroma_offset: [ChromaLocation::CositedEven; 2],
            chroma_filter: Filter::Nearest,
            force_explicit_reconstruction: false,
            _ne: crate::NonExhaustive(()),
        }
    }
}

vulkan_enum! {
    #[non_exhaustive]

    /// The conversion between the color model of the source image and the color model of the shader.
    SamplerYcbcrModelConversion = SamplerYcbcrModelConversion(i32);

    /// The input values are already in the shader's model, and are passed through unmodified.
    RgbIdentity = RGB_IDENTITY,

    /// The input values are only range expanded, no other modifications are done.
    YcbcrIdentity = YCBCR_IDENTITY,

    /// The input values are converted according to the
    /// [ITU-R BT.709](https://en.wikipedia.org/wiki/Rec._709) standard.
    Ycbcr709 = YCBCR_709,

    /// The input values are converted according to the
    /// [ITU-R BT.601](https://en.wikipedia.org/wiki/Rec._601) standard.
    Ycbcr601 = YCBCR_601,

    /// The input values are converted according to the
    /// [ITU-R BT.2020](https://en.wikipedia.org/wiki/Rec._2020) standard.
    Ycbcr2020 = YCBCR_2020,
}

vulkan_enum! {
    #[non_exhaustive]

    /// How the numeric range of the input data is converted.
    SamplerYcbcrRange = SamplerYcbcrRange(i32);

    /// The input values cover the full numeric range, and are interpreted according to the ITU
    /// "full range" rules.
    ItuFull = ITU_FULL,

    /// The input values cover only a subset of the numeric range, with the remainder reserved as
    /// headroom/footroom. The values are interpreted according to the ITU "narrow range" rules.
    ItuNarrow = ITU_NARROW,
}

vulkan_enum! {
    #[non_exhaustive]

    /// For formats with chroma subsampling, the location where the chroma components are sampled,
    /// relative to the luma component.
    ChromaLocation = ChromaLocation(i32);

    /// The chroma components are sampled at the even luma coordinate.
    CositedEven = COSITED_EVEN,

    /// The chroma components are sampled at the midpoint between the even luma coordinate and
    /// the next higher odd luma coordinate.
    Midpoint = MIDPOINT,
}

#[cfg(test)]
mod tests {
    use super::{SamplerYcbcrConversion, SamplerYcbcrConversionCreationError};
    use crate::RequiresOneOf;

    #[test]
    fn feature_not_enabled() {
        let (device, _queue) = gfx_dev_and_queue!();

        let r = SamplerYcbcrConversion::new(device, Default::default());

        match r {
            Err(SamplerYcbcrConversionCreationError::RequirementNotMet {
                requires_one_of: RequiresOneOf { features, .. },
                ..
            }) if features.contains(&"sampler_ycbcr_conversion") => (),
            _ => panic!(),
        }
    }
}