X-Git-Url: https://git.nihav.org/?a=blobdiff_plain;f=nihav-core%2Fsrc%2Fformats.rs;h=2c2e717d93e3cd6bf35bf2fe2f5dafb3d0ede950;hb=8b746bf7d611f6910d656b312b4f6269fd63883c;hp=f7ef8d881caedeb4a8f7062293cb089d49fea814;hpb=c7d8d94809fd5cdebc191c2ff86aa9c0c2d77dbf;p=nihav.git diff --git a/nihav-core/src/formats.rs b/nihav-core/src/formats.rs index f7ef8d8..2c2e717 100644 --- a/nihav-core/src/formats.rs +++ b/nihav-core/src/formats.rs @@ -1,50 +1,98 @@ +//! 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; let is_pl = (flags & SONITON_FLAG_PLANAR) != 0; let is_fl = (flags & SONITON_FLAG_FLOAT) != 0; let is_sg = (flags & SONITON_FLAG_SIGNED) != 0; - NASoniton { bits: bits, be: is_be, packed: is_pk, planar: is_pl, float: is_fl, signed: is_sg } - } - - pub fn get_bits(&self) -> u8 { self.bits } - pub fn is_be(&self) -> bool { self.be } - pub fn is_packed(&self) -> bool { self.packed } - pub fn is_planar(&self) -> bool { self.planar } - pub fn is_float(&self) -> bool { self.float } - pub fn is_signed(&self) -> bool { self.signed } - - pub fn get_audio_size(&self, length: u64) -> usize { + 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 * (self.bits as u64) + 7) >> 3) as usize + ((length * u64::from(self.bits) + 7) >> 3) as usize } else { - (length * (((self.bits + 7) >> 3) as u64)) as usize + (length * u64::from((self.bits + 7) >> 3)) as usize } } } @@ -57,14 +105,16 @@ impl fmt::Display for NASoniton { } } +/// 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 { - pub fn is_center(&self) -> bool { - match *self { + /// Reports whether this is some center channel. + pub fn is_center(self) -> bool { + match self { NAChannelType::C => true, NAChannelType::Ch => true, NAChannelType::Cl => true, NAChannelType::Ov => true, NAChannelType::LFE => true, NAChannelType::LFE2 => true, @@ -72,8 +122,9 @@ impl NAChannelType { _ => false, } } - pub fn is_left(&self) -> bool { - match *self { + /// Reports whether this is some left channel. + pub fn is_left(self) -> bool { + match self { NAChannelType::L => true, NAChannelType::Ls => true, NAChannelType::Lss => true, NAChannelType::Lc => true, NAChannelType::Lh => true, NAChannelType::Lw => true, @@ -82,8 +133,9 @@ impl NAChannelType { _ => false, } } - pub fn is_right(&self) -> bool { - match *self { + /// Reports whether this is some right channel. + pub fn is_right(self) -> bool { + match self { NAChannelType::R => true, NAChannelType::Rs => true, NAChannelType::Rss => true, NAChannelType::Rc => true, NAChannelType::Rh => true, NAChannelType::Rw => true, @@ -94,6 +146,7 @@ impl NAChannelType { } } +/// Generic channel configuration parsing error. #[derive(Clone,Copy,Debug,PartialEq)] pub struct ChannelParseError {} @@ -171,7 +224,10 @@ impl fmt::Display for NAChannelType { } } -#[derive(Clone)] +/// Channel map. +/// +/// This is essentially an ordered sequence of channels. +#[derive(Clone,Default)] pub struct NAChannelMap { ids: Vec, } @@ -191,32 +247,39 @@ 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 i in 0..chs.len() { - self.ids.push(chs[i]); + 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 in 0..MS_CHANNEL_MAP.len() { + for (i, ch) in MS_CHANNEL_MAP.iter().enumerate() { if ((chmap >> i) & 1) != 0 { - cm.add_channel(MS_CHANNEL_MAP[i]); + cm.add_channel(*ch); } } cm @@ -227,7 +290,7 @@ impl fmt::Display for NAChannelMap { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { let mut map = String::new(); for el in self.ids.iter() { - if map.len() > 0 { map.push(','); } + if !map.is_empty() { map.push(','); } map.push_str(&*el.to_string()); } write!(f, "{}", map) @@ -246,6 +309,7 @@ impl FromStr for NAChannelMap { } } +/// A list of RGB colour model variants. #[derive(Debug,Clone,Copy,PartialEq)] pub enum RGBSubmodel { RGB, @@ -262,10 +326,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 +347,7 @@ impl fmt::Display for YUVSubmodel { } } +/// A list of known colour models. #[derive(Debug, Clone,Copy,PartialEq)] pub enum ColorModel { RGB(RGBSubmodel), @@ -291,26 +359,32 @@ pub enum ColorModel { } impl ColorModel { - pub fn get_default_components(&self) -> usize { - match *self { + /// 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, } } - pub fn is_rgb(&self) -> bool { - match *self { + /// Reports whether the current colour model is RGB. + pub fn is_rgb(self) -> bool { + match self { ColorModel::RGB(_) => true, _ => false, } } - pub fn is_yuv(&self) -> bool { - match *self { + /// Reports whether the current colour model is YUV. + pub fn is_yuv(self) -> bool { + match self { ColorModel::YUV(_) => true, _ => false, } } - pub fn get_short_name(&self) -> &'static str { - match *self { + /// Returns short name for the current colour mode. + pub fn get_short_name(self) -> &'static str { + match self { ColorModel::RGB(_) => "rgb", ColorModel::YUV(_) => "yuv", ColorModel::CMYK => "cmyk", @@ -335,31 +409,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 +488,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 +497,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 +505,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 +515,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 +524,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 +533,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,23 +543,33 @@ 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 } } - pub fn get_subsampling(&self) -> (u8, u8) { (self.h_ss, self.v_ss) } - pub fn is_packed(&self) -> bool { self.packed } - pub fn get_depth(&self) -> u8 { self.depth } - pub fn get_shift(&self) -> u8 { self.shift } - pub fn get_offset(&self) -> u8 { self.comp_offs } - pub fn get_step(&self) -> u8 { self.next_elem } - - pub fn get_width(&self, width: usize) -> usize { + /// 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 } - pub fn get_height(&self, height: usize) -> usize { + /// 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 } - pub fn get_linesize(&self, width: usize) -> usize { + /// 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 { (self.get_width(width) * d + d - 1) >> 3 @@ -451,7 +577,8 @@ impl NAPixelChromaton { self.get_width(width) } } - pub fn get_data_size(&self, width: usize, height: usize) -> usize { + /// 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 +597,7 @@ impl fmt::Display for NAPixelChromaton { } impl NAPixelFormaton { + /// Constructs a new instance of `NAPixelFormaton`. pub fn new(model: ColorModel, comp1: Option, comp2: Option, @@ -487,23 +615,31 @@ impl NAPixelFormaton { if let Some(c) = comp3 { chromatons[2] = Some(c); ncomp += 1; } if let Some(c) = comp4 { chromatons[3] = Some(c); ncomp += 1; } if let Some(c) = comp5 { chromatons[4] = Some(c); ncomp += 1; } - NAPixelFormaton { model: model, + NAPixelFormaton { model, components: ncomp, comp_info: chromatons, - elem_size: elem_size, - be: be, alpha: alpha, palette: palette } + elem_size, + 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 } - pub fn is_be(&self) -> bool { self.be } - pub fn has_alpha(&self) -> bool { self.alpha } - pub fn is_paletted(&self) -> bool { self.palette } - pub fn get_elem_size(&self) -> u8 { self.elem_size } + /// 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 +649,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 +659,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() {