X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Fformats.rs;h=4c577cf2f3803d747d7ef6c951cc1539de98e520;hb=81b94329a275bb92066404bd3bb2822c5bb3f424;hp=9a1d4e8cf1d712fee53a6632b6d2956bb3c6b9d3;hpb=e243ceb4d694cc08767ad70027bb6963f4cefea3;p=nihav.git diff --git a/nihav-core/src/formats.rs b/nihav-core/src/formats.rs index 9a1d4e8..4c577cf 100644 --- a/nihav-core/src/formats.rs +++ b/nihav-core/src/formats.rs @@ -1,29 +1,70 @@ +//! Audio and image sample format definitions. +//! +//! NihAV does not have a fixed list of supported formats but rather accepts format definitions both for audio and video. +//! In result exotic formats like YUV410+alpha plane that is used by Indeo 4 are supported without any additional case handing. +//! Some common format definitions are provided as constants for convenience. use std::str::FromStr; use std::string::*; use std::fmt; +/// Audio format definition. +/// +/// The structure describes how audio samples are stored and what characteristics they have. #[derive(Debug,Copy,Clone,PartialEq)] pub struct NASoniton { - bits: u8, - be: bool, - packed: bool, - planar: bool, - float: bool, - signed: bool, + /// Bits per sample. + pub bits: u8, + /// Audio format is big-endian. + pub be: bool, + /// Audio samples are packed (e.g. 20-bit audio samples). + pub packed: bool, + /// Audio data is stored in planar format instead of interleaving samples for different channels. + pub planar: bool, + /// Audio data is in floating point format. + pub float: bool, + /// Audio data is signed (usually only 8-bit audio is unsigned). + pub signed: bool, } +/// Flag for specifying that audio format is big-endian in `NASoniton::`[`new`]`()`. Related to [`be`] field of `NASoniton`. +/// +/// [`new`]: ./struct.NASoniton.html#method.new +/// [`be`]: ./struct.NASoniton.html#structfield.be pub const SONITON_FLAG_BE :u32 = 0x01; +/// Flag for specifying that audio format has packed samples in `NASoniton::`[`new`]`()`. Related to [`packed`] field of `NASoniton`. +/// +/// [`new`]: ./struct.NASoniton.html#method.new +/// [`packed`]: ./struct.NASoniton.html#structfield.packed pub const SONITON_FLAG_PACKED :u32 = 0x02; +/// Flag for specifying that audio data is stored as planar in `NASoniton::`[`new`]`()`. Related to [`planar`] field of `NASoniton`. +/// +/// [`new`]: ./struct.NASoniton.html#method.new +/// [`planar`]: ./struct.NASoniton.html#structfield.planar pub const SONITON_FLAG_PLANAR :u32 = 0x04; +/// Flag for specifying that audio samples are in floating point format in `NASoniton::`[`new`]`()`. Related to [`float`] field of `NASoniton`. +/// +/// [`new`]: ./struct.NASoniton.html#method.new +/// [`float`]: ./struct.NASoniton.html#structfield.float pub const SONITON_FLAG_FLOAT :u32 = 0x08; +/// Flag for specifying that audio format is signed in `NASoniton::`[`new`]`()`. Related to [`signed`] field of `NASoniton`. +/// +/// [`new`]: ./struct.NASoniton.html#method.new +/// [`signed`]: ./struct.NASoniton.html#structfield.signed pub const SONITON_FLAG_SIGNED :u32 = 0x10; +/// Predefined format for interleaved 8-bit unsigned audio. pub const SND_U8_FORMAT: NASoniton = NASoniton { bits: 8, be: false, packed: false, planar: false, float: false, signed: false }; +/// Predefined format for interleaved 16-bit signed audio. pub const SND_S16_FORMAT: NASoniton = NASoniton { bits: 16, be: false, packed: false, planar: false, float: false, signed: true }; +/// Predefined format for planar 16-bit signed audio. pub const SND_S16P_FORMAT: NASoniton = NASoniton { bits: 16, be: false, packed: false, planar: true, float: false, signed: true }; +/// Predefined format for planar 32-bit floating point audio. pub const SND_F32P_FORMAT: NASoniton = NASoniton { bits: 32, be: false, packed: false, planar: true, float: true, signed: true }; impl NASoniton { + /// Constructs a new audio format definition using flags like [`SONITON_FLAG_BE`]. + /// + /// [`SONITON_FLAG_BE`]: ./constant.SONITON_FLAG_BE.html pub fn new(bits: u8, flags: u32) -> Self { let is_be = (flags & SONITON_FLAG_BE) != 0; let is_pk = (flags & SONITON_FLAG_PACKED) != 0; @@ -33,13 +74,20 @@ impl NASoniton { NASoniton { bits, be: is_be, packed: is_pk, planar: is_pl, float: is_fl, signed: is_sg } } + /// Returns the number of bits per sample. pub fn get_bits(self) -> u8 { self.bits } + /// Reports whether the format is big-endian. pub fn is_be(self) -> bool { self.be } + /// Reports whether the format has packed samples. pub fn is_packed(self) -> bool { self.packed } + /// Reports whether audio data is planar instead of interleaved. pub fn is_planar(self) -> bool { self.planar } + /// Reports whether audio samples are in floating point format. pub fn is_float(self) -> bool { self.float } + /// Reports whether audio samples are signed. pub fn is_signed(self) -> bool { self.signed } + /// Returns the amount of bytes needed to store the audio of requested length (in samples). pub fn get_audio_size(self, length: u64) -> usize { if self.packed { ((length * u64::from(self.bits) + 7) >> 3) as usize @@ -47,6 +95,15 @@ impl NASoniton { (length * u64::from((self.bits + 7) >> 3)) as usize } } + + /// Returns soniton description as a short string. + pub fn to_short_string(&self) -> String { + let ltype = if self.float { 'f' } else if self.signed { 's' } else { 'u' }; + let endianness = if self.bits == 8 { "" } else if self.be { "be" } else { "le" }; + let planar = if self.planar { "p" } else { "" }; + let packed = if self.packed { "x" } else { "" }; + format!("{}{}{}{}{}", ltype, self.bits, endianness, planar, packed) + } } impl fmt::Display for NASoniton { @@ -57,12 +114,37 @@ impl fmt::Display for NASoniton { } } +/// Generic soniton parsing error. +#[derive(Clone,Copy,Debug,PartialEq)] +pub struct SonitonParseError {} + +impl FromStr for NASoniton { + type Err = SonitonParseError; + + fn from_str(s: &str) -> Result { + match s { + "u8" => Ok(NASoniton { bits: 8, be: true, packed: false, planar: false, float: false, signed: false }), + "s16be" => Ok(NASoniton { bits: 16, be: true, packed: false, planar: false, float: false, signed: true }), + "s16le" => Ok(NASoniton { bits: 16, be: false, packed: false, planar: false, float: false, signed: true }), + "s24be" => Ok(NASoniton { bits: 24, be: true, packed: false, planar: false, float: false, signed: true }), + "s24le" => Ok(NASoniton { bits: 24, be: false, packed: false, planar: false, float: false, signed: true }), + "s32be" => Ok(NASoniton { bits: 32, be: true, packed: false, planar: false, float: false, signed: true }), + "s32le" => Ok(NASoniton { bits: 32, be: false, packed: false, planar: false, float: false, signed: true }), + "f32be" => Ok(NASoniton { bits: 32, be: true, packed: false, planar: false, float: true, signed: true }), + "f32le" => Ok(NASoniton { bits: 32, be: false, packed: false, planar: false, float: true, signed: true }), + _ => Err(SonitonParseError{}), + } + } +} + +/// Known channel types. #[derive(Debug,Clone,Copy,PartialEq)] pub enum NAChannelType { 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 } impl NAChannelType { + /// Reports whether this is some center channel. pub fn is_center(self) -> bool { match self { NAChannelType::C => true, NAChannelType::Ch => true, @@ -72,6 +154,7 @@ impl NAChannelType { _ => false, } } + /// Reports whether this is some left channel. pub fn is_left(self) -> bool { match self { NAChannelType::L => true, NAChannelType::Ls => true, @@ -82,6 +165,7 @@ impl NAChannelType { _ => false, } } + /// Reports whether this is some right channel. pub fn is_right(self) -> bool { match self { NAChannelType::R => true, NAChannelType::Rs => true, @@ -94,6 +178,7 @@ impl NAChannelType { } } +/// Generic channel configuration parsing error. #[derive(Clone,Copy,Debug,PartialEq)] pub struct ChannelParseError {} @@ -135,9 +220,9 @@ impl FromStr for NAChannelType { } } -impl fmt::Display for NAChannelType { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - let name = match *self { +impl ToString for NAChannelType { + fn to_string(&self) -> String { + match *self { NAChannelType::C => "C".to_string(), NAChannelType::L => "L".to_string(), NAChannelType::R => "R".to_string(), @@ -166,11 +251,13 @@ impl fmt::Display for NAChannelType { NAChannelType::Rt => "Rt".to_string(), NAChannelType::Lo => "Lo".to_string(), NAChannelType::Ro => "Ro".to_string(), - }; - write!(f, "{}", name) + } } } +/// Channel map. +/// +/// This is essentially an ordered sequence of channels. #[derive(Clone,Default)] pub struct NAChannelMap { ids: Vec, @@ -191,27 +278,34 @@ const MS_CHANNEL_MAP: [NAChannelType; 11] = [ ]; impl NAChannelMap { + /// Constructs a new `NAChannelMap` instance. pub fn new() -> Self { NAChannelMap { ids: Vec::new() } } + /// Adds a new channel to the map. pub fn add_channel(&mut self, ch: NAChannelType) { self.ids.push(ch); } + /// Adds several channels to the map at once. pub fn add_channels(&mut self, chs: &[NAChannelType]) { for e in chs.iter() { self.ids.push(*e); } } + /// Returns the total number of channels. pub fn num_channels(&self) -> usize { self.ids.len() } + /// Reports channel type for a requested index. pub fn get_channel(&self, idx: usize) -> NAChannelType { self.ids[idx] } + /// Tries to find position of the channel with requested type. pub fn find_channel_id(&self, t: NAChannelType) -> Option { for i in 0..self.ids.len() { if self.ids[i] as i32 == t as i32 { return Some(i as u8); } } None } + /// Creates a new `NAChannelMap` using the channel mapping flags from WAVE format. pub fn from_ms_mapping(chmap: u32) -> Self { let mut cm = NAChannelMap::new(); for (i, ch) in MS_CHANNEL_MAP.iter().enumerate() { @@ -246,6 +340,7 @@ impl FromStr for NAChannelMap { } } +/// A list of RGB colour model variants. #[derive(Debug,Clone,Copy,PartialEq)] pub enum RGBSubmodel { RGB, @@ -262,10 +357,13 @@ impl fmt::Display for RGBSubmodel { } } +/// A list of YUV colour model variants. #[derive(Debug,Clone,Copy,PartialEq)] pub enum YUVSubmodel { YCbCr, + /// NTSC variant. YIQ, + /// The YUV variant used by JPEG. YUVJ, } @@ -280,6 +378,7 @@ impl fmt::Display for YUVSubmodel { } } +/// A list of known colour models. #[derive(Debug, Clone,Copy,PartialEq)] pub enum ColorModel { RGB(RGBSubmodel), @@ -291,24 +390,30 @@ pub enum ColorModel { } impl ColorModel { + /// Returns the number of colour model components. + /// + /// The actual image may have more components e.g. alpha component. pub fn get_default_components(self) -> usize { match self { ColorModel::CMYK => 4, _ => 3, } } + /// Reports whether the current colour model is RGB. pub fn is_rgb(self) -> bool { match self { ColorModel::RGB(_) => true, _ => false, } } + /// Reports whether the current colour model is YUV. pub fn is_yuv(self) -> bool { match self { ColorModel::YUV(_) => true, _ => false, } } + /// Returns short name for the current colour mode. pub fn get_short_name(self) -> &'static str { match self { ColorModel::RGB(_) => "rgb", @@ -335,31 +440,67 @@ impl fmt::Display for ColorModel { } } +/// Single colourspace component definition. +/// +/// This structure defines how components of a colourspace are subsampled and where and how they are stored. #[derive(Clone,Copy,PartialEq)] pub struct NAPixelChromaton { + /// Horizontal subsampling in power of two (e.g. `0` = no subsampling, `1` = only every second value is stored). pub h_ss: u8, + /// Vertial subsampling in power of two (e.g. `0` = no subsampling, `1` = only every second value is stored). pub v_ss: u8, + /// A flag to signal that component is packed. pub packed: bool, + /// Bit depth of current component. pub depth: u8, + /// Shift for packed components. pub shift: u8, + /// Component offset for byte-packed components. pub comp_offs: u8, + /// The distance to the next packed element in bytes. pub next_elem: u8, } +/// Flag for specifying that image data is stored big-endian in `NAPixelFormaton::`[`new`]`()`. Related to its [`be`] field. +/// +/// [`new`]: ./struct.NAPixelFormaton.html#method.new +/// [`be`]: ./struct.NAPixelFormaton.html#structfield.new pub const FORMATON_FLAG_BE :u32 = 0x01; +/// Flag for specifying that image data has alpha plane in `NAPixelFormaton::`[`new`]`()`. Related to its [`alpha`] field. +/// +/// [`new`]: ./struct.NAPixelFormaton.html#method.new +/// [`alpha`]: ./struct.NAPixelFormaton.html#structfield.alpha pub const FORMATON_FLAG_ALPHA :u32 = 0x02; +/// Flag for specifying that image data is stored in paletted form for `NAPixelFormaton::`[`new`]`()`. Related to its [`palette`] field. +/// +/// [`new`]: ./struct.NAPixelFormaton.html#method.new +/// [`palette`]: ./struct.NAPixelFormaton.html#structfield.palette pub const FORMATON_FLAG_PALETTE :u32 = 0x04; +/// The current limit on number of components in image colourspace model (including alpha component). pub const MAX_CHROMATONS: usize = 5; +/// Image colourspace representation. +/// +/// This structure includes both definitions for each component and some common definitions. +/// For example the format can be paletted and then components describe the palette storage format while actual data is 8-bit palette indices. #[derive(Clone,Copy,PartialEq)] pub struct NAPixelFormaton { + /// Image colour model. pub model: ColorModel, + /// Actual number of components present. pub components: u8, + /// Format definition for each component. pub comp_info: [Option; MAX_CHROMATONS], + /// Single pixel size for packed formats. pub elem_size: u8, + /// A flag signalling that data is stored as big-endian. pub be: bool, + /// A flag signalling that image has alpha component. pub alpha: bool, + /// A flag signalling that data is paletted. + /// + /// 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. pub palette: bool, } @@ -378,6 +519,7 @@ macro_rules! chromaton { }); } +/// Predefined format for planar 8-bit YUV with 4:2:0 subsampling. pub const YUV420_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 3, comp_info: [ chromaton!(0, 0, false, 8, 0, 0, 1), @@ -386,6 +528,7 @@ pub const YUV420_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel:: None, None], elem_size: 0, be: false, alpha: false, palette: false }; +/// Predefined format for planar 8-bit YUV with 4:1:0 subsampling. pub const YUV410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 3, comp_info: [ chromaton!(0, 0, false, 8, 0, 0, 1), @@ -393,6 +536,7 @@ pub const YUV410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel:: chromaton!(yuv8; 2, 2, 2), None, None], elem_size: 0, be: false, alpha: false, palette: false }; +/// Predefined format for planar 8-bit YUV with 4:1:0 subsampling and alpha component. pub const YUVA410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::YUV(YUVSubmodel::YUVJ), components: 4, comp_info: [ chromaton!(0, 0, false, 8, 0, 0, 1), @@ -402,6 +546,7 @@ pub const YUVA410_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel: None], elem_size: 0, be: false, alpha: true, palette: false }; +/// Predefined format with RGB24 palette. pub const PAL8_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3, comp_info: [ chromaton!(pal8; 0), @@ -410,6 +555,7 @@ pub const PAL8_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RG None, None], elem_size: 3, be: false, alpha: false, palette: true }; +/// Predefined format for RGB565 packed video. pub const RGB565_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3, comp_info: [ chromaton!(packrgb; 5, 11, 0, 2), @@ -418,6 +564,7 @@ pub const RGB565_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel:: None, None], elem_size: 2, be: false, alpha: false, palette: false }; +/// Predefined format for RGB24. pub const RGB24_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::RGB(RGBSubmodel::RGB), components: 3, comp_info: [ chromaton!(packrgb; 8, 0, 0, 3), @@ -427,22 +574,32 @@ pub const RGB24_FORMAT: NAPixelFormaton = NAPixelFormaton { model: ColorModel::R elem_size: 3, be: false, alpha: false, palette: false }; impl NAPixelChromaton { + /// Constructs a new `NAPixelChromaton` instance. pub fn new(h_ss: u8, v_ss: u8, packed: bool, depth: u8, shift: u8, comp_offs: u8, next_elem: u8) -> Self { Self { h_ss, v_ss, packed, depth, shift, comp_offs, next_elem } } + /// Returns subsampling for the current component. pub fn get_subsampling(self) -> (u8, u8) { (self.h_ss, self.v_ss) } + /// Reports whether current component is packed. pub fn is_packed(self) -> bool { self.packed } + /// Returns bit depth of current component. pub fn get_depth(self) -> u8 { self.depth } + /// Returns bit shift for packed component. pub fn get_shift(self) -> u8 { self.shift } + /// Returns byte offset for packed component. pub fn get_offset(self) -> u8 { self.comp_offs } + /// Returns byte offset to the next element of current packed component. pub fn get_step(self) -> u8 { self.next_elem } + /// Calculates the width for current component from general image width. pub fn get_width(self, width: usize) -> usize { (width + ((1 << self.h_ss) - 1)) >> self.h_ss } + /// Calculates the height for current component from general image height. pub fn get_height(self, height: usize) -> usize { (height + ((1 << self.v_ss) - 1)) >> self.v_ss } + /// Calculates the minimal stride for current component from general image width. pub fn get_linesize(self, width: usize) -> usize { let d = self.depth as usize; if self.packed { @@ -451,6 +608,7 @@ impl NAPixelChromaton { self.get_width(width) } } + /// Calculates the required image size in pixels for current component from general image width. pub fn get_data_size(self, width: usize, height: usize) -> usize { let nh = (height + ((1 << self.v_ss) - 1)) >> self.v_ss; self.get_linesize(width) * nh @@ -470,6 +628,7 @@ impl fmt::Display for NAPixelChromaton { } impl NAPixelFormaton { + /// Constructs a new instance of `NAPixelFormaton`. pub fn new(model: ColorModel, comp1: Option, comp2: Option, @@ -494,16 +653,24 @@ impl NAPixelFormaton { be, alpha, palette } } + /// Returns current colour model. pub fn get_model(&self) -> ColorModel { self.model } + /// Returns the number of components. pub fn get_num_comp(&self) -> usize { self.components as usize } + /// Returns selected component information. pub fn get_chromaton(&self, idx: usize) -> Option { if idx < self.comp_info.len() { return self.comp_info[idx]; } None } + /// Reports whether the packing format is big-endian. pub fn is_be(self) -> bool { self.be } + /// Reports whether colourspace has alpha component. pub fn has_alpha(self) -> bool { self.alpha } + /// Reports whether this is paletted format. pub fn is_paletted(self) -> bool { self.palette } + /// Returns single packed pixel size. pub fn get_elem_size(self) -> u8 { self.elem_size } + /// Reports whether the format is not packed. pub fn is_unpacked(&self) -> bool { if self.palette { return false; } for chr in self.comp_info.iter() { @@ -513,6 +680,7 @@ impl NAPixelFormaton { } true } + /// Returns the maximum component bit depth. pub fn get_max_depth(&self) -> u8 { let mut mdepth = 0; for chr in self.comp_info.iter() { @@ -522,6 +690,17 @@ impl NAPixelFormaton { } mdepth } + /// Returns the total amount of bits needed for components. + pub fn get_total_depth(&self) -> u8 { + let mut depth = 0; + for chr in self.comp_info.iter() { + if let Some(ref chromaton) = chr { + depth += chromaton.depth; + } + } + depth + } + /// Returns the maximum component subsampling. pub fn get_max_subsampling(&self) -> u8 { let mut ssamp = 0; for chr in self.comp_info.iter() { @@ -558,6 +737,10 @@ mod test { println!("{}", SND_S16_FORMAT); println!("{}", SND_U8_FORMAT); println!("{}", SND_F32P_FORMAT); + assert_eq!(SND_U8_FORMAT.to_short_string(), "u8"); + assert_eq!(SND_F32P_FORMAT.to_short_string(), "f32lep"); + let s16fmt = SND_S16_FORMAT.to_short_string(); + assert_eq!(NASoniton::from_str(s16fmt.as_str()).unwrap(), SND_S16_FORMAT); println!("formaton yuv- {}", YUV420_FORMAT); println!("formaton pal- {}", PAL8_FORMAT); println!("formaton rgb565- {}", RGB565_FORMAT);