jiao 0.4.1

// Copyright (c) 2023 Xu Shaohua <shaohua@biofan.org>. All rights reserved.
// Use of this source is governed by Lesser General Public License that can be found
// in the LICENSE file.

use crate::base::math::MAX_S32;
use crate::core::alpha_type::AlphaType;
use crate::core::color_space::ColorSpace;
use crate::core::color_type::{self, ColorType};
use crate::core::irect::IRect;
use crate::core::size::ISize;

/// `YuvColorSpace` describes color range of YUV pixels.
///
/// The color mapping from YUV to RGB varies depending on the source.
/// YUV pixels may be generated by JPEG images, standard video streams,
/// or high definition video streams. Each has its own mapping from YUV to RGB.
///
/// JPEG YUV values encode the full range of 0 to 255 for all three components.
/// Video YUV values often range from 16 to 235 for Y and from 16 to 240 for U and V (limited).
/// Details of encoding and conversion to RGB are described in `YCbCr` color space.
///
/// The identity colorspace exists to provide a utility mapping from Y to R, U to G and V to B.
/// It can be used to visualize the YUV planes or to explicitly post process the YUV channels.

//#[repr(u32)]
#[derive(Debug, Clone, Copy, Eq, PartialEq)]
pub enum YuvColorSpace {
    /// describes full range
    JpegFull,

    /// describes SDTV range
    Rec601Limited,

    /// describes HDTV range
    Rec709Full,

    Rec709Limited,

    /// describes UHDTV range, non-constant-luminance
    Bt2020_8bitFull,

    Bt2020_8bitLimited,

    Bt2020_10bitFull,

    Bt2020_10bitLimited,

    Bt2020_12bitFull,

    Bt2020_12bitLimited,

    /// maps Y->R, U->G, V->B
    Identity,
}

/// `ColorInfo` describes pixel and encoding.
///
/// `ImageInfo` can be created from `ColorInfo` by providing dimensions.
///
/// It encodes how pixel bits describe alpha, transparency; color components red, blue,
/// and green; and `ColorSpace`, the range and linearity of colors.
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct ColorInfo {
    color_space: Option<ColorSpace>,
    color_type: ColorType,
    alpha_type: AlphaType,
}

impl Default for ColorInfo {
    fn default() -> Self {
        Self::new()
    }
}

impl ColorInfo {
    #[must_use]
    pub const fn new() -> Self {
        Self {
            color_space: None,
            color_type: ColorType::Unknown,
            alpha_type: AlphaType::Unknown,
        }
    }

    /// Creates `ColorInfo` from `ColorType`, `AlphaType` and `ColorSpace`.
    /// `ColorSpace` defaults to `sRGB`.
    #[must_use]
    pub const fn from(
        color_type: ColorType,
        alpha_type: AlphaType,
        color_space: Option<ColorSpace>,
    ) -> Self {
        Self {
            color_space,
            color_type,
            alpha_type,
        }
    }

    /// Creates `ColorInfo` with same `ColorType`, `ColorSpace` as self, with `AlphaType` changed.
    ///
    /// Created `ColorInfo` contains `new_alpha_type` even if it is incompatible with
    /// `ColorType`, in which case `AlphaType` in `ColorInfo` is ignored.
    #[must_use]
    pub fn from_alpha_type(&self, new_alpha_type: AlphaType) -> Self {
        Self {
            color_space: self.color_space.clone(),
            color_type: self.color_type,
            alpha_type: new_alpha_type,
        }
    }

    /// Creates new `ColorInfo` with same `AlphaType`, `ColorSpace` as self, with `ColorType`
    /// changed.
    #[must_use]
    pub fn from_color_type(&self, new_color_type: ColorType) -> Self {
        Self {
            color_space: self.color_space.clone(),
            color_type: new_color_type,
            alpha_type: self.alpha_type,
        }
    }

    /// Creates `ColorInfo` with same `AlphaType`, `ColorType` as self, with `ColorSpace` changed.
    #[must_use]
    pub const fn from_color_space(&self, new_color_space: Option<ColorSpace>) -> Self {
        Self {
            color_space: new_color_space,
            color_type: self.color_type,
            alpha_type: self.alpha_type,
        }
    }

    #[must_use]
    pub const fn color_space(&self) -> &Option<ColorSpace> {
        &self.color_space
    }

    #[must_use]
    pub const fn color_type(&self) -> ColorType {
        self.color_type
    }

    #[must_use]
    pub const fn alpha_type(&self) -> AlphaType {
        self.alpha_type
    }

    #[must_use]
    pub fn is_opaque(&self) -> bool {
        self.alpha_type.is_opaque() || self.color_type.is_always_opaque()
    }

    #[must_use]
    pub const fn gamma_close_to_srgb(&self) -> bool {
        if let Some(color_space) = &self.color_space {
            color_space.gamma_close_to_srgb()
        } else {
            false
        }
    }

    /// Returns number of bytes per pixel required by `ColorType`.
    ///
    /// Returns zero if `color_type()` is `ColorType::Unknown`.
    #[must_use]
    pub const fn bytes_per_pixel(&self) -> i32 {
        self.color_type.bytes_per_pixel()
    }

    /// Returns bit shift converting row bytes to row pixels.
    ///
    /// Returns zero for `ColorType::Unknown`.
    ///
    /// One of: 0, 1, 2, 3, 4; left shift to convert pixels to bytes
    #[must_use]
    pub const fn shift_per_pixel(&self) -> i32 {
        self.color_type.shift_per_pixel()
    }

    /// Returns true if contains a valid `color_type` and `alpha_type`.
    pub(crate) fn is_valid(&self) -> bool {
        self.color_type != ColorType::Unknown && self.alpha_type != AlphaType::Unknown
    }
}

/// `ImageInfo` describes pixel dimensions and encoding.
///
/// `Bitmap`, `Image`, `PixMap`, and `Surface` can be created from `ImageInfo`.
///
/// `ImageInfo` can be retrieved from `Bitmap` and `Pixmap`, but not from `Image` and
/// `Surface`.
/// For example, `Image` and `Surface` implementations may defer pixel depth,
/// so may not completely specify `ImageInfo`.
///
/// `ImageInfo` contains dimensions, the pixel integral width and height.
/// It encodes how pixel bits describe alpha, transparency; color components red, blue,
/// and green; and `ColorSpace`, the range and linearity of colors.
#[derive(Debug, Clone, Eq, PartialEq)]
pub struct ImageInfo {
    color_info: ColorInfo,
    dimensions: ISize,
}

impl Default for ImageInfo {
    fn default() -> Self {
        Self::new()
    }
}

impl ImageInfo {
    /// Creates an empty `ImageInfo` with `ColorType::Unknown`, `AlphaType::Unknown`,
    /// a width and height of zero, and no `ColorSpace`.
    #[must_use]
    pub const fn new() -> Self {
        Self {
            color_info: ColorInfo::new(),
            dimensions: ISize::new(),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType`,
    /// `AlphaType`, and optionally `ColorSpace`.
    ///
    /// If `ColorSpace` is None and `ImageInfo` is part of drawing source: `ColorSpace`
    /// defaults to `sRGB`, mapping into `Surface` `ColorSpace`.
    ///
    /// # Parameters
    /// Parameters are not validated to see if their values are legal, or that the
    /// combination is supported.
    ///
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` - pixel row count; must be zero or greater
    /// - `cs` - range of colors; may be None
    #[must_use]
    pub const fn from(
        width: i32,
        height: i32,
        ct: ColorType,
        at: AlphaType,
        cs: Option<ColorSpace>,
    ) -> Self {
        Self {
            color_info: ColorInfo::from(ct, at, cs),
            dimensions: ISize::from_wh(width, height),
        }
    }

    #[must_use]
    pub const fn new_dimensions(
        dimensions: ISize,
        ct: ColorType,
        at: AlphaType,
        cs: Option<ColorSpace>,
    ) -> Self {
        Self {
            color_info: ColorInfo::from(ct, at, cs),
            dimensions,
        }
    }

    /// Creates `ImageInfo` from integral dimensions and `ColorInfo`.
    ///
    /// # Parameters
    /// Parameters are not validated to see if their values are legal, or that the
    /// combination is supported.
    ///
    /// - `dimensions` - pixel column and row count; must be zeros or greater
    /// - `color_info` - the pixel encoding consisting of `ColorType`, `AlphaType`, and
    ///                  `ColorSpace` (which may be nullptr)
    #[must_use]
    pub const fn from_color_info(dimensions: ISize, color_info: ColorInfo) -> Self {
        Self {
            color_info,
            dimensions,
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType` N32,
    /// `AlphaType`, and optionally `ColorSpace`.
    ///
    /// `ColorType` N32 will equal either `ColorType::Bgra8888` or `ColorType::Rgba8888`,
    /// whichever is optimal.
    ///
    /// If `ColorSpace` is None and `ImageInfo` is part of drawing source: `ColorSpace`
    /// defaults to `sRGB`, mapping into `Surface` `ColorSpace`.
    ///
    /// # Parameters
    /// Parameters are not validated to see if their values are legal, or that the
    /// combination is supported.
    ///
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` -  pixel row count; must be zero or greater
    /// - `cs` - range of colors; may be None
    #[must_use]
    pub const fn new_n32(width: i32, height: i32, at: AlphaType, cs: Option<ColorSpace>) -> Self {
        Self {
            color_info: ColorInfo::from(color_type::N32, at, cs),
            dimensions: ISize::from_wh(width, height),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType` N32,
    /// `AlphaType`, with `sRGB` `ColorSpace`.
    ///
    /// # Parameters
    /// Parameters are not validated to see if their values are legal, or that the
    /// combination is supported.
    ///
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` - pixel column count; must be zero or greater
    #[must_use]
    pub const fn new_s32(width: i32, height: i32, at: AlphaType) -> Self {
        Self {
            // TODO(Shaohua): Set color space.
            color_info: ColorInfo::from(color_type::N32, at, None),
            dimensions: ISize::from_wh(width, height),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType` N32,
    /// `AlphaType::Premul`, with optional `ColorSpace`.
    ///
    /// If `ColorSpace` is None and `ImageInfo` is part of drawing source: `ColorSpace`
    /// defaults to `sRGB`, mapping into `Surface` `ColorSpace`.
    ///
    /// # Parameters
    /// Parameters are not validated to see if their values are legal, or that the
    /// combination is supported.
    ///
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` -  pixel row count; must be zero or greater
    /// - `cs` - range of colors; may be None
    #[must_use]
    pub const fn new_n32_premul(width: i32, height: i32, cs: Option<ColorSpace>) -> Self {
        Self {
            color_info: ColorInfo::from(ColorType::Alpha8, AlphaType::Premul, cs),
            dimensions: ISize::from_wh(width, height),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType::Alpha8`,
    /// `AlphaType::Premul`, with `ColorSpace` set to None.
    ///
    /// # Parameters
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` - pixel row count; must be zero or greater
    #[must_use]
    pub const fn new_a8(width: i32, height: i32) -> Self {
        Self {
            color_info: ColorInfo::from(ColorType::Alpha8, AlphaType::Premul, None),
            dimensions: ISize::from_wh(width, height),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height, `ColorType::Unknown`,
    /// `AlphaType::Unknown`, with `ColorSpace` set to None.
    ///
    /// Returned `ImageInfo` as part of source does not draw, and as part of destination
    /// can not be drawn to.
    ///
    /// # Parameters
    /// - `width` - pixel column count; must be zero or greater
    /// - `height` - pixel row count; must be zero or greater
    #[must_use]
    pub const fn new_unknown(width: i32, height: i32) -> Self {
        Self {
            color_info: ColorInfo::from(ColorType::Unknown, AlphaType::Unknown, None),
            dimensions: ISize::from_wh(width, height),
        }
    }

    /// Creates `ImageInfo` from integral dimensions width and height set to zero,
    /// `ColorType::Unknown`, `AlphaType::Unknown`, with `ColorSpace` set to None.
    #[must_use]
    pub const fn new_unknown_empty() -> Self {
        Self::new_unknown(0, 0)
    }

    /// Creates `ImageInfo` with the same `ColorType`, `ColorSpace`, and `AlphaType`,
    /// with dimensions set to width and height.
    ///
    /// # Parameters
    /// - `new_width` - pixel column count; must be zero or greater
    /// - `new_height` - pixel row count; must be zero or greater
    #[must_use]
    pub fn from_wh(&self, new_width: i32, new_height: i32) -> Self {
        Self::from_color_info(
            ISize::from_wh(new_width, new_height),
            self.color_info.clone(),
        )
    }

    /// Creates `ImageInfo` with the same `ColorType`, `ColorSpace`, and `AlphaType`,
    /// with dimensions set to `new_dimensions`.
    #[must_use]
    pub fn from_dimensions(&self, new_size: ISize) -> Self {
        Self::from_color_info(new_size, self.color_info.clone())
    }

    /// Creates `ImageInfo` with same `ColorType`, `ColorSpace`, width, and height,
    /// with `AlphaType` set to `new_alpha_type`.
    ///
    /// Created `ImageInfo` contains `new_alpha_type` even if it is incompatible with
    /// `ColorType`, in which case `AlphaType` in `ImageInfo` is ignored.
    #[must_use]
    pub fn from_alpha_type(&self, new_alpha_type: AlphaType) -> Self {
        Self::from_color_info(
            self.dimensions,
            self.color_info.from_alpha_type(new_alpha_type),
        )
    }

    /// Creates `ImageInfo` with same `AlphaType`, `ColorSpace`, width, and height,
    /// with `ColorType` set to `new_color_type`.
    #[must_use]
    pub fn from_color_type(&self, new_color_type: ColorType) -> Self {
        Self::from_color_info(
            self.dimensions,
            self.color_info.from_color_type(new_color_type),
        )
    }

    /// Creates `ImageInfo` with same `AlphaType`, `ColorType`, width, and height,
    /// with `ColorSpace` set to `new_color_space`.
    #[must_use]
    pub const fn from_color_space(&self, new_color_space: Option<ColorSpace>) -> Self {
        Self::from_color_info(
            self.dimensions,
            self.color_info.from_color_space(new_color_space),
        )
    }

    /// Returns pixel count in each row.
    #[must_use]
    pub const fn width(&self) -> i32 {
        self.dimensions.width()
    }

    /// Returns pixel row count.
    #[must_use]
    pub const fn height(&self) -> i32 {
        self.dimensions.height()
    }

    #[must_use]
    pub const fn color_type(&self) -> ColorType {
        self.color_info.color_type()
    }

    #[must_use]
    pub const fn alpha_type(&self) -> AlphaType {
        self.color_info.alpha_type()
    }

    /// Returns `ColorSpace`, the range of colors.
    #[must_use]
    pub const fn color_space(&self) -> &Option<ColorSpace> {
        self.color_info.color_space()
    }

    /// Returns if `ImageInfo` describes an empty area of pixels by checking if either
    /// width or height is zero or smaller.
    #[must_use]
    pub const fn is_empty(&self) -> bool {
        self.dimensions.is_empty()
    }

    /// Returns the dimensionless `ColorInfo` that represents the same color type,
    /// alpha type, and color space as this `ImageInfo`.
    #[must_use]
    pub const fn color_info(&self) -> &ColorInfo {
        &self.color_info
    }

    /// Returns true if `AlphaType` is set to hint that all pixels are opaque; their
    /// alpha value is implicitly or explicitly 1.0.
    ///
    /// Return true if `AlphaType` is `AlphaType::Opaque`.
    /// If true, and all pixels are not opaque, may draw incorrectly.
    ///
    /// Does not check if `ColorType` allows alpha, or if any pixel value has
    /// transparency.
    #[must_use]
    pub fn is_opaque(&self) -> bool {
        self.color_info.is_opaque()
    }

    /// Returns `ISize { width(), height() }`.
    #[must_use]
    pub const fn dimensions(&self) -> ISize {
        self.dimensions
    }

    /// Returns true if contains a valid combination of width, height and `color_info`.
    #[must_use]
    pub(crate) fn is_valid(&self) -> bool {
        const MAX_DIMENSION: i32 = MAX_S32 >> 2;

        if self.width() <= 0 || self.height() <= 0 {
            return false;
        }

        if self.width() > MAX_DIMENSION || self.height() > MAX_DIMENSION {
            return false;
        }

        self.color_info.is_valid()
    }

    /// Returns true if it has defined a pixel conversion from the `src` to the `self`.
    /// Returns false otherwise.
    #[must_use]
    pub fn valid_conversion(&self, src: &Self) -> bool {
        self.is_valid() && src.is_valid()
    }

    /// Returns bounding rect.
    ///
    /// Returns integral rectangle from origin to `width()` and `height()`
    #[must_use]
    pub const fn bounds(&self) -> IRect {
        IRect::from_size(self.dimensions)
    }

    /// Returns true if associated `ColorSpace` is not None, and `ColorSpace` gamma
    /// is approximately the same as `sRGB`.
    #[must_use]
    pub const fn gamma_close_to_srgb(&self) -> bool {
        self.color_info.gamma_close_to_srgb()
    }

    /// Returns number of bytes per pixel required by `ColorType`.
    ///
    /// Returns zero if `color_type` is `ColorType::Unknown`.
    #[must_use]
    pub const fn bytes_per_pixel(&self) -> i32 {
        self.color_info.bytes_per_pixel()
    }

    /// Returns bit shift converting row bytes to row pixels.
    ///
    /// Returns zero for `ColorType::Unknown`.
    /// Returns one of: 0, 1, 2, 3; left shift to convert pixels to bytes
    #[must_use]
    pub const fn shift_per_pixel(&self) -> i32 {
        self.color_info.shift_per_pixel()
    }

    /// Returns minimum bytes per row, computed from pixel `width()` and `ColorType`,
    /// which specifies `bytes_per_pixel()`.
    ///
    /// `Bitmap` maximum value for row bytes must fit in 31 bits.
    ///
    /// Return `width()` times `bytes_per_pixel()` as unsigned 64-bit integer
    #[must_use]
    #[allow(clippy::cast_sign_loss)]
    pub const fn min_row_bytes64(&self) -> u64 {
        (self.width() as u64) * (self.bytes_per_pixel() as u64)
    }

    /// Returns minimum bytes per row, computed from pixel `width()` and `ColorType`,
    /// which specifies `bytes_per_pixel()`.
    ///
    /// `Bitmap` maximum value for row bytes must fit in 31 bits.
    #[must_use]
    #[allow(clippy::cast_possible_truncation)]
    pub const fn min_row_bytes(&self) -> usize {
        let min_row_bytes = self.min_row_bytes64();
        // TODO(Shaohua): Check range
        //if (!TFitsIn<int32_t>(minRowBytes)) {
        //    return 0;
        //}
        min_row_bytes as usize
    }

    /// Returns byte offset of pixel from pixel base address.
    ///
    /// Asserts in debug build if x or y is outside of bounds.
    /// Does not assert if `row_bytes` is smaller than `min_row_bytes()`,
    /// even though result may be incorrect.
    ///
    /// # Parameters
    /// - `x` - column index, zero or greater, and less than `width()`
    /// - `y` - row index, zero or greater, and less than `height()`
    /// - `row_bytes` - size of pixel row or larger
    #[must_use]
    pub const fn compute_offset(&self, _x: i32, _y: i32, _row_bytes: usize) -> usize {
        unimplemented!()
    }

    /// Returns storage required by pixel array, given `ImageInfo` dimensions,
    /// `ColorType`, and `row_bytes`.
    ///
    /// `row_bytes` is assumed to be at least as large as `min_row_bytes()`.
    ///
    /// Returns zero if height is zero.
    /// Returns `usize::MAX` if answer exceeds the range of usize.
    #[must_use]
    pub const fn compute_byte_size(&self, _row_bytes: usize) -> usize {
        unimplemented!()
    }

    /// Returns storage required by pixel array, given `ImageInfo` dimensions,
    /// and `ColorType`.
    ///
    /// Uses `min_row_bytes()` to compute bytes for pixel row.
    ///
    /// Returns zero if height is zero.
    ///
    /// Returns `usize::MAX` if answer exceeds the range of usize.
    ///
    /// Returns least memory required by pixel buffer
    #[must_use]
    pub const fn compute_min_byte_size(&self) -> usize {
        self.compute_byte_size(self.min_row_bytes())
    }

    /// Returns true if `byte_size` equals `usize::MAX`.
    ///
    /// `compute_byte_size()` and `compute_min_byte_size()` return `usize::MAX`
    /// if usize can not hold buffer size.
    ///
    /// # Parameters
    /// `byte_size` - result of `compute_byte_size()` or `compute_min_byte_size()`
    #[must_use]
    pub(crate) const fn byte_size_overflowed(byte_size: usize) -> bool {
        byte_size == usize::MAX
    }

    /// Returns true if `row_bytes` is valid for this `ImageInfo`.
    ///
    /// Returns true if `row_bytes` is large enough to contain pixel row
    /// and is properly aligned.
    ///
    /// # Parameters
    /// - `row_bytes` - size of pixel row including padding
    #[must_use]
    pub const fn valid_row_bytes(&self, row_bytes: usize) -> bool {
        if (row_bytes as u64) < self.min_row_bytes64() {
            return false;
        }

        let shift = self.shift_per_pixel();
        let aligned_row_bytes = row_bytes >> shift << shift;
        aligned_row_bytes == row_bytes
    }

    /// Creates an empty `ImageInfo` with `ColorType::Unknown`, `AlphaType::Unknown`,
    /// a width and height of zero, and no `ColorSpace`.
    pub fn reset(&mut self) {
        *self = Self::new();
    }

    // Asserts if internal values are illegal or inconsistent. Only available in debug mode at compile time.
    //validate() const;
}