nihav-core/src/formats.rs

   1 //! Audio and image sample format definitions.
   2 //!
   3 //! NihAV does not have a fixed list of supported formats but rather accepts format definitions both for audio and video.
   4 //! In result exotic formats like YUV410+alpha plane that is used by Indeo 4 are supported without any additional case handing.
   5 //! Some common format definitions are provided as constants for convenience.
   6 use std::str::FromStr;
   7 use std::string::*;
   8 use std::fmt;
   9
  10 /// Generic format parsing error.
  11 #[derive(Clone,Copy,Debug,PartialEq)]
  12 pub struct FormatParseError {}
  13
  14 /// Audio format definition.
  15 ///
  16 /// The structure describes how audio samples are stored and what characteristics they have.
  17 #[derive(Debug,Copy,Clone,PartialEq)]
  18 pub struct NASoniton {
  19     /// Bits per sample.
  20     pub bits:       u8,
  21     /// Audio format is big-endian.
  22     pub be:         bool,
  23     /// Audio samples are packed (e.g. 20-bit audio samples).
  24     pub packed:     bool,
  25     /// Audio data is stored in planar format instead of interleaving samples for different channels.
  26     pub planar:     bool,
  27     /// Audio data is in floating point format.
  28     pub float:      bool,
  29     /// Audio data is signed (usually only 8-bit audio is unsigned).
  30     pub signed:     bool,
  31 }
  32
  33 /// Flag for specifying that audio format is big-endian in `NASoniton::`[`new`]`()`. Related to [`be`] field of `NASoniton`.
  34 ///
  35 /// [`new`]: ./struct.NASoniton.html#method.new
  36 /// [`be`]: ./struct.NASoniton.html#structfield.be
  37 pub const SONITON_FLAG_BE     :u32 = 0x01;
  38 /// Flag for specifying that audio format has packed samples in `NASoniton::`[`new`]`()`. Related to [`packed`] field of `NASoniton`.
  39 ///
  40 /// [`new`]: ./struct.NASoniton.html#method.new
  41 /// [`packed`]: ./struct.NASoniton.html#structfield.packed
  42 pub const SONITON_FLAG_PACKED :u32 = 0x02;
  43 /// Flag for specifying that audio data is stored as planar in `NASoniton::`[`new`]`()`. Related to [`planar`] field of `NASoniton`.
  44 ///
  45 /// [`new`]: ./struct.NASoniton.html#method.new
  46 /// [`planar`]: ./struct.NASoniton.html#structfield.planar
  47 pub const SONITON_FLAG_PLANAR :u32 = 0x04;
  48 /// Flag for specifying that audio samples are in floating point format in `NASoniton::`[`new`]`()`. Related to [`float`] field of `NASoniton`.
  49 ///
  50 /// [`new`]: ./struct.NASoniton.html#method.new
  51 /// [`float`]: ./struct.NASoniton.html#structfield.float
  52 pub const SONITON_FLAG_FLOAT  :u32 = 0x08;
  53 /// Flag for specifying that audio format is signed in `NASoniton::`[`new`]`()`. Related to [`signed`] field of `NASoniton`.
  54 ///
  55 /// [`new`]: ./struct.NASoniton.html#method.new
  56 /// [`signed`]: ./struct.NASoniton.html#structfield.signed
  57 pub const SONITON_FLAG_SIGNED :u32 = 0x10;
  58
  59 /// Predefined format for interleaved 8-bit unsigned audio.
  60 pub const SND_U8_FORMAT: NASoniton = NASoniton { bits: 8, be: false, packed: false, planar: false, float: false, signed: false };
  61 /// Predefined format for interleaved 16-bit signed audio.
  62 pub const SND_S16_FORMAT: NASoniton = NASoniton { bits: 16, be: false, packed: false, planar: false, float: false, signed: true };
  63 /// Predefined format for planar 16-bit signed audio.
  64 pub const SND_S16P_FORMAT: NASoniton = NASoniton { bits: 16, be: false, packed: false, planar: true, float: false, signed: true };
  65 /// Predefined format for planar 32-bit floating point audio.
  66 pub const SND_F32P_FORMAT: NASoniton = NASoniton { bits: 32, be: false, packed: false, planar: true, float: true, signed: true };
  67
  68 impl NASoniton {
  69     /// Constructs a new audio format definition using flags like [`SONITON_FLAG_BE`].
  70     ///
  71     /// [`SONITON_FLAG_BE`]: ./constant.SONITON_FLAG_BE.html
  72     pub fn new(bits: u8, flags: u32) -> Self {
  73         let is_be = (flags & SONITON_FLAG_BE) != 0;
  74         let is_pk = (flags & SONITON_FLAG_PACKED) != 0;
  75         let is_pl = (flags & SONITON_FLAG_PLANAR) != 0;
  76         let is_fl = (flags & SONITON_FLAG_FLOAT) != 0;
  77         let is_sg = (flags & SONITON_FLAG_SIGNED) != 0;
  78         NASoniton { bits, be: is_be, packed: is_pk, planar: is_pl, float: is_fl, signed: is_sg }
  79     }
  80
  81     /// Returns the number of bits per sample.
  82     pub fn get_bits(self)   -> u8   { self.bits }
  83     /// Reports whether the format is big-endian.
  84     pub fn is_be(self)      -> bool { self.be }
  85     /// Reports whether the format has packed samples.
  86     pub fn is_packed(self)  -> bool { self.packed }
  87     /// Reports whether audio data is planar instead of interleaved.
  88     pub fn is_planar(self)  -> bool { self.planar }
  89     /// Reports whether audio samples are in floating point format.
  90     pub fn is_float(self)   -> bool { self.float }
  91     /// Reports whether audio samples are signed.
  92     pub fn is_signed(self)  -> bool { self.signed }
  93
  94     /// Returns the amount of bytes needed to store the audio of requested length (in samples).
  95     pub fn get_audio_size(self, length: u64) -> usize {
  96         if self.packed {
  97             ((length * u64::from(self.bits) + 7) >> 3) as usize
  98         } else {
  99             (length * u64::from((self.bits + 7) >> 3)) as usize
 100         }
 101     }
 102
 103     /// Returns soniton description as a short string.
 104     pub fn to_short_string(&self) -> String {
 105         let ltype = if self.float { 'f' } else if self.signed { 's' } else { 'u' };
 106         let endianness = if self.bits == 8 { "" } else if self.be { "be" } else { "le" };
 107         let planar = if self.planar { "p" } else { "" };
 108         let packed = if self.packed { "x" } else { "" };
 109         format!("{}{}{}{}{}", ltype, self.bits, endianness, planar, packed)
 110     }
 111 }
 112
 113 impl fmt::Display for NASoniton {
 114     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 115         let fmt = if self.float { "float" } else if self.signed { "int" } else { "uint" };
 116         let end = if self.be { "BE" } else { "LE" };
 117         write!(f, "({} bps, {} planar: {} packed: {} {})", self.bits, end, self.packed, self.planar, fmt)
 118     }
 119 }
 120
 121 impl FromStr for NASoniton {
 122     type Err = FormatParseError;
 123
 124     fn from_str(s: &str) -> Result<Self, Self::Err> {
 125         match s {
 126             "u8" => Ok(NASoniton { bits: 8, be: true, packed: false, planar: false, float: false, signed: false }),
 127             "s16be" => Ok(NASoniton { bits: 16, be:  true, packed: false, planar: false, float: false, signed: true }),
 128             "s16le" => Ok(NASoniton { bits: 16, be: false, packed: false, planar: false, float: false, signed: true }),
 129             "s24be" => Ok(NASoniton { bits: 24, be:  true, packed: false, planar: false, float: false, signed: true }),
 130             "s24le" => Ok(NASoniton { bits: 24, be: false, packed: false, planar: false, float: false, signed: true }),
 131             "s32be" => Ok(NASoniton { bits: 32, be:  true, packed: false, planar: false, float: false, signed: true }),
 132             "s32le" => Ok(NASoniton { bits: 32, be: false, packed: false, planar: false, float: false, signed: true }),
 133             "f32be" => Ok(NASoniton { bits: 32, be:  true, packed: false, planar: false, float: true, signed: true }),
 134             "f32le" => Ok(NASoniton { bits: 32, be: false, packed: false, planar: false, float: true, signed: true }),
 135             _ => Err(FormatParseError{}),
 136         }
 137     }
 138 }
 139
 140 /// Known channel types.
 141 #[derive(Debug,Clone,Copy,PartialEq)]
 142 pub enum NAChannelType {
 143     C, L, R, Cs, Ls, Rs, Lss, Rss, LFE, Lc, Rc, Lh, Rh, Ch, LFE2, Lw, Rw, Ov, Lhs, Rhs, Chs, Ll, Rl, Cl, Lt, Rt, Lo, Ro
 144 }
 145
 146 impl NAChannelType {
 147     /// Reports whether this is some center channel.
 148     pub fn is_center(self) -> bool {
 149         match self {
 150             NAChannelType::C => true,   NAChannelType::Ch => true,
 151             NAChannelType::Cl => true,  NAChannelType::Ov => true,
 152             NAChannelType::LFE => true, NAChannelType::LFE2 => true,
 153             NAChannelType::Cs => true,  NAChannelType::Chs => true,
 154             _ => false,
 155         }
 156     }
 157     /// Reports whether this is some left channel.
 158     pub fn is_left(self) -> bool {
 159         match self {
 160             NAChannelType::L   => true, NAChannelType::Ls => true,
 161             NAChannelType::Lss => true, NAChannelType::Lc => true,
 162             NAChannelType::Lh  => true, NAChannelType::Lw => true,
 163             NAChannelType::Lhs => true, NAChannelType::Ll => true,
 164             NAChannelType::Lt  => true, NAChannelType::Lo => true,
 165             _ => false,
 166         }
 167     }
 168     /// Reports whether this is some right channel.
 169     pub fn is_right(self) -> bool {
 170         match self {
 171             NAChannelType::R   => true, NAChannelType::Rs => true,
 172             NAChannelType::Rss => true, NAChannelType::Rc => true,
 173             NAChannelType::Rh  => true, NAChannelType::Rw => true,
 174             NAChannelType::Rhs => true, NAChannelType::Rl => true,
 175             NAChannelType::Rt  => true, NAChannelType::Ro => true,
 176             _ => false,
 177         }
 178     }
 179 }
 180
 181 impl FromStr for NAChannelType {
 182     type Err = FormatParseError;
 183
 184     fn from_str(s: &str) -> Result<Self, Self::Err> {
 185         match s {
 186             "C"     => Ok(NAChannelType::C),
 187             "L"     => Ok(NAChannelType::L),
 188             "R"     => Ok(NAChannelType::R),
 189             "Cs"    => Ok(NAChannelType::Cs),
 190             "Ls"    => Ok(NAChannelType::Ls),
 191             "Rs"    => Ok(NAChannelType::Rs),
 192             "Lss"   => Ok(NAChannelType::Lss),
 193             "Rss"   => Ok(NAChannelType::Rss),
 194             "LFE"   => Ok(NAChannelType::LFE),
 195             "Lc"    => Ok(NAChannelType::Lc),
 196             "Rc"    => Ok(NAChannelType::Rc),
 197             "Lh"    => Ok(NAChannelType::Lh),
 198             "Rh"    => Ok(NAChannelType::Rh),
 199             "Ch"    => Ok(NAChannelType::Ch),
 200             "LFE2"  => Ok(NAChannelType::LFE2),
 201             "Lw"    => Ok(NAChannelType::Lw),
 202             "Rw"    => Ok(NAChannelType::Rw),
 203             "Ov"    => Ok(NAChannelType::Ov),
 204             "Lhs"   => Ok(NAChannelType::Lhs),
 205             "Rhs"   => Ok(NAChannelType::Rhs),
 206             "Chs"   => Ok(NAChannelType::Chs),
 207             "Ll"    => Ok(NAChannelType::Ll),
 208             "Rl"    => Ok(NAChannelType::Rl),
 209             "Cl"    => Ok(NAChannelType::Cl),
 210             "Lt"    => Ok(NAChannelType::Lt),
 211             "Rt"    => Ok(NAChannelType::Rt),
 212             "Lo"    => Ok(NAChannelType::Lo),
 213             "Ro"    => Ok(NAChannelType::Ro),
 214             _   => Err(FormatParseError{}),
 215         }
 216     }
 217 }
 218
 219 impl ToString for NAChannelType {
 220     fn to_string(&self) -> String {
 221         match *self {
 222             NAChannelType::C    => "C".to_string(),
 223             NAChannelType::L    => "L".to_string(),
 224             NAChannelType::R    => "R".to_string(),
 225             NAChannelType::Cs   => "Cs".to_string(),
 226             NAChannelType::Ls   => "Ls".to_string(),
 227             NAChannelType::Rs   => "Rs".to_string(),
 228             NAChannelType::Lss  => "Lss".to_string(),
 229             NAChannelType::Rss  => "Rss".to_string(),
 230             NAChannelType::LFE  => "LFE".to_string(),
 231             NAChannelType::Lc   => "Lc".to_string(),
 232             NAChannelType::Rc   => "Rc".to_string(),
 233             NAChannelType::Lh   => "Lh".to_string(),
 234             NAChannelType::Rh   => "Rh".to_string(),
 235             NAChannelType::Ch   => "Ch".to_string(),
 236             NAChannelType::LFE2 => "LFE2".to_string(),
 237             NAChannelType::Lw   => "Lw".to_string(),
 238             NAChannelType::Rw   => "Rw".to_string(),
 239             NAChannelType::Ov   => "Ov".to_string(),
 240             NAChannelType::Lhs  => "Lhs".to_string(),
 241             NAChannelType::Rhs  => "Rhs".to_string(),
 242             NAChannelType::Chs  => "Chs".to_string(),
 243             NAChannelType::Ll   => "Ll".to_string(),
 244             NAChannelType::Rl   => "Rl".to_string(),
 245             NAChannelType::Cl   => "Cl".to_string(),
 246             NAChannelType::Lt   => "Lt".to_string(),
 247             NAChannelType::Rt   => "Rt".to_string(),
 248             NAChannelType::Lo   => "Lo".to_string(),
 249             NAChannelType::Ro   => "Ro".to_string(),
 250         }
 251     }
 252 }
 253
 254 /// Channel map.
 255 ///
 256 /// This is essentially an ordered sequence of channels.
 257 #[derive(Clone,Default)]
 258 pub struct NAChannelMap {
 259     ids: Vec<NAChannelType>,
 260 }
 261
 262 const MS_CHANNEL_MAP: [NAChannelType; 11] = [
 263     NAChannelType::L,
 264     NAChannelType::R,
 265     NAChannelType::C,
 266     NAChannelType::LFE,
 267     NAChannelType::Ls,
 268     NAChannelType::Rs,
 269     NAChannelType::Lss,
 270     NAChannelType::Rss,
 271     NAChannelType::Cs,
 272     NAChannelType::Lc,
 273     NAChannelType::Rc,
 274 ];
 275
 276 impl NAChannelMap {
 277     /// Constructs a new `NAChannelMap` instance.
 278     pub fn new() -> Self { NAChannelMap { ids: Vec::new() } }
 279     /// Adds a new channel to the map.
 280     pub fn add_channel(&mut self, ch: NAChannelType) {
 281         self.ids.push(ch);
 282     }
 283     /// Adds several channels to the map at once.
 284     pub fn add_channels(&mut self, chs: &[NAChannelType]) {
 285         for e in chs.iter() {
 286             self.ids.push(*e);
 287         }
 288     }
 289     /// Returns the total number of channels.
 290     pub fn num_channels(&self) -> usize {
 291         self.ids.len()
 292     }
 293     /// Reports channel type for a requested index.
 294     pub fn get_channel(&self, idx: usize) -> NAChannelType {
 295         self.ids[idx]
 296     }
 297     /// Tries to find position of the channel with requested type.
 298     pub fn find_channel_id(&self, t: NAChannelType) -> Option<u8> {
 299         for i in 0..self.ids.len() {
 300             if self.ids[i] as i32 == t as i32 { return Some(i as u8); }
 301         }
 302         None
 303     }
 304     /// Creates a new `NAChannelMap` using the channel mapping flags from WAVE format.
 305     pub fn from_ms_mapping(chmap: u32) -> Self {
 306         let mut cm = NAChannelMap::new();
 307         for (i, ch) in MS_CHANNEL_MAP.iter().enumerate() {
 308             if ((chmap >> i) & 1) != 0 {
 309                 cm.add_channel(*ch);
 310             }
 311         }
 312         cm
 313     }
 314 }
 315
 316 impl fmt::Display for NAChannelMap {
 317     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 318         let mut map = String::new();
 319         for el in self.ids.iter() {
 320             if !map.is_empty() { map.push(','); }
 321             map.push_str(&*el.to_string());
 322         }
 323         write!(f, "{}", map)
 324     }
 325 }
 326
 327 impl FromStr for NAChannelMap {
 328     type Err = FormatParseError;
 329
 330     fn from_str(s: &str) -> Result<Self, Self::Err> {
 331         let mut chm = NAChannelMap::new();
 332         for tok in s.split(',') {
 333             chm.add_channel(NAChannelType::from_str(tok)?);
 334         }
 335         Ok(chm)
 336     }
 337 }
 338
 339 /// A list of RGB colour model variants.
 340 #[derive(Debug,Clone,Copy,PartialEq)]
 341 pub enum RGBSubmodel {
 342     RGB,
 343     SRGB,
 344 }
 345
 346 impl fmt::Display for RGBSubmodel {
 347     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 348         let name = match *self {
 349             RGBSubmodel::RGB  => "RGB".to_string(),
 350             RGBSubmodel::SRGB => "sRGB".to_string(),
 351         };
 352         write!(f, "{}", name)
 353     }
 354 }
 355
 356 /// A list of YUV colour model variants.
 357 #[derive(Debug,Clone,Copy,PartialEq)]
 358 pub enum YUVSubmodel {
 359     YCbCr,
 360     /// NTSC variant.
 361     YIQ,
 362     /// The YUV variant used by JPEG.
 363     YUVJ,
 364 }
 365
 366 impl fmt::Display for YUVSubmodel {
 367     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 368         let name = match *self {
 369             YUVSubmodel::YCbCr => "YCbCr".to_string(),
 370             YUVSubmodel::YIQ   => "YIQ".to_string(),
 371             YUVSubmodel::YUVJ  => "YUVJ".to_string(),
 372         };
 373         write!(f, "{}", name)
 374     }
 375 }
 376
 377 /// A list of known colour models.
 378 #[derive(Debug, Clone,Copy,PartialEq)]
 379 pub enum ColorModel {
 380     RGB(RGBSubmodel),
 381     YUV(YUVSubmodel),
 382     CMYK,
 383     HSV,
 384     LAB,
 385     XYZ,
 386 }
 387
 388 impl ColorModel {
 389     /// Returns the number of colour model components.
 390     ///
 391     /// The actual image may have more components e.g. alpha component.
 392     pub fn get_default_components(self) -> usize {
 393         match self {
 394             ColorModel::CMYK => 4,
 395             _                => 3,
 396         }
 397     }
 398     /// Reports whether the current colour model is RGB.
 399     pub fn is_rgb(self) -> bool {
 400         match self {
 401             ColorModel::RGB(_) => true,
 402             _ => false,
 403         }
 404     }
 405     /// Reports whether the current colour model is YUV.
 406     pub fn is_yuv(self) -> bool {
 407         match self {
 408             ColorModel::YUV(_) => true,
 409             _ => false,
 410         }
 411     }
 412     /// Returns short name for the current colour mode.
 413     pub fn get_short_name(self) -> &'static str {
 414         match self {
 415             ColorModel::RGB(_)   => "rgb",
 416             ColorModel::YUV(_)   => "yuv",
 417             ColorModel::CMYK     => "cmyk",
 418             ColorModel::HSV      => "hsv",
 419             ColorModel::LAB      => "lab",
 420             ColorModel::XYZ      => "xyz",
 421         }
 422     }
 423 }
 424
 425 impl fmt::Display for ColorModel {
 426     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 427         let name = match *self {
 428             ColorModel::RGB(fmt) => format!("RGB({})", fmt).to_string(),
 429             ColorModel::YUV(fmt) => format!("YUV({})", fmt).to_string(),
 430             ColorModel::CMYK     => "CMYK".to_string(),
 431             ColorModel::HSV      => "HSV".to_string(),
 432             ColorModel::LAB      => "LAB".to_string(),
 433             ColorModel::XYZ      => "XYZ".to_string(),
 434         };
 435         write!(f, "{}", name)
 436     }
 437 }
 438
 439 /// Single colourspace component definition.
 440 ///
 441 /// This structure defines how components of a colourspace are subsampled and where and how they are stored.
 442 #[derive(Clone,Copy,PartialEq)]
 443 pub struct NAPixelChromaton {
 444     /// Horizontal subsampling in power of two (e.g. `0` = no subsampling, `1` = only every second value is stored).
 445     pub h_ss:           u8,
 446     /// Vertial subsampling in power of two (e.g. `0` = no subsampling, `1` = only every second value is stored).
 447     pub v_ss:           u8,
 448     /// A flag to signal that component is packed.
 449     pub packed:         bool,
 450     /// Bit depth of current component.
 451     pub depth:          u8,
 452     /// Shift for packed components.
 453     pub shift:          u8,
 454     /// Component offset for byte-packed components.
 455     pub comp_offs:      u8,
 456     /// The distance to the next packed element in bytes.
 457     pub next_elem:      u8,
 458 }
 459
 460 /// Flag for specifying that image data is stored big-endian in `NAPixelFormaton::`[`new`]`()`. Related to its [`be`] field.
 461 ///
 462 /// [`new`]: ./struct.NAPixelFormaton.html#method.new
 463 /// [`be`]: ./struct.NAPixelFormaton.html#structfield.new
 464 pub const FORMATON_FLAG_BE      :u32 = 0x01;
 465 /// Flag for specifying that image data has alpha plane in `NAPixelFormaton::`[`new`]`()`. Related to its [`alpha`] field.
 466 ///
 467 /// [`new`]: ./struct.NAPixelFormaton.html#method.new
 468 /// [`alpha`]: ./struct.NAPixelFormaton.html#structfield.alpha
 469 pub const FORMATON_FLAG_ALPHA   :u32 = 0x02;
 470 /// Flag for specifying that image data is stored in paletted form for `NAPixelFormaton::`[`new`]`()`. Related to its [`palette`] field.
 471 ///
 472 /// [`new`]: ./struct.NAPixelFormaton.html#method.new
 473 /// [`palette`]: ./struct.NAPixelFormaton.html#structfield.palette
 474 pub const FORMATON_FLAG_PALETTE :u32 = 0x04;
 475
 476 /// The current limit on number of components in image colourspace model (including alpha component).
 477 pub const MAX_CHROMATONS: usize = 5;
 478
 479 /// Image colourspace representation.
 480 ///
 481 /// This structure includes both definitions for each component and some common definitions.
 482 /// For example the format can be paletted and then components describe the palette storage format while actual data is 8-bit palette indices.
 483 #[derive(Clone,Copy,PartialEq)]
 484 pub struct NAPixelFormaton {
 485     /// Image colour model.
 486     pub model:      ColorModel,
 487     /// Actual number of components present.
 488     pub components: u8,
 489     /// Format definition for each component.
 490     pub comp_info:  [Option<NAPixelChromaton>; MAX_CHROMATONS],
 491     /// Single pixel size for packed formats.
 492     pub elem_size:  u8,
 493     /// A flag signalling that data is stored as big-endian.
 494     pub be:         bool,
 495     /// A flag signalling that image has alpha component.
 496     pub alpha:      bool,
 497     /// A flag signalling that data is paletted.
 498     ///
 499     /// This means that image data is stored as 8-bit indices (in the first image component) for the palette stored as second component of the image and actual palette format is described in this structure.
 500     pub palette:    bool,
 501 }
 502
 503 macro_rules! chromaton {
 504     ($hs: expr, $vs: expr, $pck: expr, $d: expr, $sh: expr, $co: expr, $ne: expr) => ({
 505         Some(NAPixelChromaton{ h_ss: $hs, v_ss: $vs, packed: $pck, depth: $d, shift: $sh, comp_offs: $co, next_elem: $ne })
 506     });
 507     (yuv8; $hs: expr, $vs: expr, $co: expr) => ({
 508         Some(NAPixelChromaton{ h_ss: $hs, v_ss: $vs, packed: false, depth: 8, shift: 0, comp_offs: $co, next_elem: 1 })
 509     });
 510     (packrgb; $d: expr, $s: expr, $co: expr, $ne: expr) => ({
 511         Some(NAPixelChromaton{ h_ss: 0, v_ss: 0, packed: true, depth: $d, shift: $s, comp_offs: $co, next_elem: $ne })
 512     });
 513     (pal8; $co: expr) => ({
 514         Some(NAPixelChromaton{ h_ss: 0, v_ss: 0, packed: true, depth: 8, shift: 0, comp_offs: $co, next_elem: 3 })
 515     });
 516 }
 517
 518 /// Predefined format for planar 8-bit YUV with 4:2:0 subsampling.
 519 pub const YUV420_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 3,
 520                                         comp_info: [
 521                                             chromaton!(0, 0, false, 8, 0, 0, 1),
 522                                             chromaton!(yuv8; 1, 1, 1),
 523                                             chromaton!(yuv8; 1, 1, 2),
 524                                             None, None],
 525                                         elem_size: 0, be: false, alpha: false, palette: false };
 526
 527 /// Predefined format for planar 8-bit YUV with 4:1:0 subsampling.
 528 pub const YUV410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 3,
 529                                         comp_info: [
 530                                             chromaton!(0, 0, false, 8, 0, 0, 1),
 531                                             chromaton!(yuv8; 2, 2, 1),
 532                                             chromaton!(yuv8; 2, 2, 2),
 533                                             None, None],
 534                                         elem_size: 0, be: false, alpha: false, palette: false };
 535 /// Predefined format for planar 8-bit YUV with 4:1:0 subsampling and alpha component.
 536 pub const YUVA410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 4,
 537                                         comp_info: [
 538                                             chromaton!(0, 0, false, 8, 0, 0, 1),
 539                                             chromaton!(yuv8; 2, 2, 1),
 540                                             chromaton!(yuv8; 2, 2, 2),
 541                                             chromaton!(0, 0, false, 8, 0, 3, 1),
 542                                             None],
 543                                         elem_size: 0, be: false, alpha: true, palette: false };
 544
 545 /// Predefined format with RGB24 palette.
 546 pub const PAL8_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3,
 547                                         comp_info: [
 548                                             chromaton!(pal8; 0),
 549                                             chromaton!(pal8; 1),
 550                                             chromaton!(pal8; 2),
 551                                             None, None],
 552                                         elem_size: 3, be: false, alpha: false, palette: true };
 553
 554 /// Predefined format for RGB565 packed video.
 555 pub const RGB565_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3,
 556                                         comp_info: [
 557                                             chromaton!(packrgb; 5, 11, 0, 2),
 558                                             chromaton!(packrgb; 6,  5, 0, 2),
 559                                             chromaton!(packrgb; 5,  0, 0, 2),
 560                                             None, None],
 561                                         elem_size: 2, be: false, alpha: false, palette: false };
 562
 563 /// Predefined format for RGB24.
 564 pub const RGB24_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3,
 565                                         comp_info: [
 566                                             chromaton!(packrgb; 8, 0, 0, 3),
 567                                             chromaton!(packrgb; 8, 0, 1, 3),
 568                                             chromaton!(packrgb; 8, 0, 2, 3),
 569                                             None, None],
 570                                         elem_size: 3, be: false, alpha: false, palette: false };
 571
 572 impl NAPixelChromaton {
 573     /// Constructs a new `NAPixelChromaton` instance.
 574     pub fn new(h_ss: u8, v_ss: u8, packed: bool, depth: u8, shift: u8, comp_offs: u8, next_elem: u8) -> Self {
 575         Self { h_ss, v_ss, packed, depth, shift, comp_offs, next_elem }
 576     }
 577     /// Returns subsampling for the current component.
 578     pub fn get_subsampling(self) -> (u8, u8) { (self.h_ss, self.v_ss) }
 579     /// Reports whether current component is packed.
 580     pub fn is_packed(self) -> bool { self.packed }
 581     /// Returns bit depth of current component.
 582     pub fn get_depth(self) -> u8   { self.depth }
 583     /// Returns bit shift for packed component.
 584     pub fn get_shift(self) -> u8   { self.shift }
 585     /// Returns byte offset for packed component.
 586     pub fn get_offset(self) -> u8  { self.comp_offs }
 587     /// Returns byte offset to the next element of current packed component.
 588     pub fn get_step(self)  -> u8   { self.next_elem }
 589
 590     /// Calculates the width for current component from general image width.
 591     pub fn get_width(self, width: usize) -> usize {
 592         (width  + ((1 << self.h_ss) - 1)) >> self.h_ss
 593     }
 594     /// Calculates the height for current component from general image height.
 595     pub fn get_height(self, height: usize) -> usize {
 596         (height + ((1 << self.v_ss) - 1)) >> self.v_ss
 597     }
 598     /// Calculates the minimal stride for current component from general image width.
 599     pub fn get_linesize(self, width: usize) -> usize {
 600         let d = self.depth as usize;
 601         if self.packed {
 602             (self.get_width(width) * d + d - 1) >> 3
 603         } else {
 604             self.get_width(width)
 605         }
 606     }
 607     /// Calculates the required image size in pixels for current component from general image width.
 608     pub fn get_data_size(self, width: usize, height: usize) -> usize {
 609         let nh = (height + ((1 << self.v_ss) - 1)) >> self.v_ss;
 610         self.get_linesize(width) * nh
 611     }
 612 }
 613
 614 impl fmt::Display for NAPixelChromaton {
 615     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 616         let pfmt = if self.packed {
 617             let mask = ((1 << self.depth) - 1) << self.shift;
 618             format!("packed(+{},{:X}, step {})", self.comp_offs, mask, self.next_elem)
 619         } else {
 620             format!("planar({},{})", self.comp_offs, self.next_elem)
 621         };
 622         write!(f, "({}x{}, {})", self.h_ss, self.v_ss, pfmt)
 623     }
 624 }
 625
 626 impl NAPixelFormaton {
 627     /// Constructs a new instance of `NAPixelFormaton`.
 628     pub fn new(model: ColorModel,
 629                comp1: Option<NAPixelChromaton>,
 630                comp2: Option<NAPixelChromaton>,
 631                comp3: Option<NAPixelChromaton>,
 632                comp4: Option<NAPixelChromaton>,
 633                comp5: Option<NAPixelChromaton>,
 634                flags: u32, elem_size: u8) -> Self {
 635         let mut chromatons: [Option<NAPixelChromaton>; MAX_CHROMATONS] = [None; MAX_CHROMATONS];
 636         let mut ncomp = 0;
 637         let be      = (flags & FORMATON_FLAG_BE)      != 0;
 638         let alpha   = (flags & FORMATON_FLAG_ALPHA)   != 0;
 639         let palette = (flags & FORMATON_FLAG_PALETTE) != 0;
 640         if let Some(c) = comp1 { chromatons[0] = Some(c); ncomp += 1; }
 641         if let Some(c) = comp2 { chromatons[1] = Some(c); ncomp += 1; }
 642         if let Some(c) = comp3 { chromatons[2] = Some(c); ncomp += 1; }
 643         if let Some(c) = comp4 { chromatons[3] = Some(c); ncomp += 1; }
 644         if let Some(c) = comp5 { chromatons[4] = Some(c); ncomp += 1; }
 645         NAPixelFormaton { model,
 646                           components: ncomp,
 647                           comp_info: chromatons,
 648                           elem_size,
 649                           be, alpha, palette }
 650     }
 651
 652     /// Returns current colour model.
 653     pub fn get_model(&self) -> ColorModel { self.model }
 654     /// Returns the number of components.
 655     pub fn get_num_comp(&self) -> usize { self.components as usize }
 656     /// Returns selected component information.
 657     pub fn get_chromaton(&self, idx: usize) -> Option<NAPixelChromaton> {
 658         if idx < self.comp_info.len() { return self.comp_info[idx]; }
 659         None
 660     }
 661     /// Reports whether the packing format is big-endian.
 662     pub fn is_be(self) -> bool { self.be }
 663     /// Reports whether colourspace has alpha component.
 664     pub fn has_alpha(self) -> bool { self.alpha }
 665     /// Reports whether this is paletted format.
 666     pub fn is_paletted(self) -> bool { self.palette }
 667     /// Returns single packed pixel size.
 668     pub fn get_elem_size(self) -> u8 { self.elem_size }
 669     /// Reports whether the format is not packed.
 670     pub fn is_unpacked(&self) -> bool {
 671         if self.palette { return false; }
 672         for chr in self.comp_info.iter() {
 673             if let Some(ref chromaton) = chr {
 674                 if chromaton.is_packed() { return false; }
 675             }
 676         }
 677         true
 678     }
 679     /// Returns the maximum component bit depth.
 680     pub fn get_max_depth(&self) -> u8 {
 681         let mut mdepth = 0;
 682         for chr in self.comp_info.iter() {
 683             if let Some(ref chromaton) = chr {
 684                 mdepth = mdepth.max(chromaton.depth);
 685             }
 686         }
 687         mdepth
 688     }
 689     /// Returns the total amount of bits needed for components.
 690     pub fn get_total_depth(&self) -> u8 {
 691         let mut depth = 0;
 692         for chr in self.comp_info.iter() {
 693             if let Some(ref chromaton) = chr {
 694                 depth += chromaton.depth;
 695             }
 696         }
 697         depth
 698     }
 699     /// Returns the maximum component subsampling.
 700     pub fn get_max_subsampling(&self) -> u8 {
 701         let mut ssamp = 0;
 702         for chr in self.comp_info.iter() {
 703             if let Some(ref chromaton) = chr {
 704                 let (ss_v, ss_h) = chromaton.get_subsampling();
 705                 ssamp = ssamp.max(ss_v).max(ss_h);
 706             }
 707         }
 708         ssamp
 709     }
 710 }
 711
 712 impl fmt::Display for NAPixelFormaton {
 713     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 714         let end = if self.be { "BE" } else { "LE" };
 715         let palstr = if self.palette { "palette " } else { "" };
 716         let astr = if self.alpha { "alpha " } else { "" };
 717         let mut str = format!("Formaton for {} ({}{}elem {} size {}): ", self.model, palstr, astr,end, self.elem_size);
 718         for i in 0..self.comp_info.len() {
 719             if let Some(chr) = self.comp_info[i] {
 720                 str = format!("{} {}", str, chr);
 721             }
 722         }
 723         write!(f, "[{}]", str)
 724     }
 725 }
 726
 727 #[cfg(test)]
 728 mod test {
 729     use super::*;
 730
 731     #[test]
 732     fn test_fmt() {
 733         println!("{}", SND_S16_FORMAT);
 734         println!("{}", SND_U8_FORMAT);
 735         println!("{}", SND_F32P_FORMAT);
 736         assert_eq!(SND_U8_FORMAT.to_short_string(), "u8");
 737         assert_eq!(SND_F32P_FORMAT.to_short_string(), "f32lep");
 738         let s16fmt = SND_S16_FORMAT.to_short_string();
 739         assert_eq!(NASoniton::from_str(s16fmt.as_str()).unwrap(), SND_S16_FORMAT);
 740         println!("formaton yuv- {}", YUV420_FORMAT);
 741         println!("formaton pal- {}", PAL8_FORMAT);
 742         println!("formaton rgb565- {}", RGB565_FORMAT);
 743     }
 744 }