+//! 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 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;
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
}
}
+/// 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,
_ => false,
}
}
+ /// Reports whether this is some left channel.
pub fn is_left(self) -> bool {
match self {
NAChannelType::L => true, NAChannelType::Ls => true,
_ => false,
}
}
+ /// Reports whether this is some right channel.
pub fn is_right(self) -> bool {
match self {
NAChannelType::R => true, NAChannelType::Rs => true,
}
}
+/// Generic channel configuration parsing error.
#[derive(Clone,Copy,Debug,PartialEq)]
pub struct ChannelParseError {}
}
}
+/// Channel map.
+///
+/// This is essentially an ordered sequence of channels.
#[derive(Clone,Default)]
pub struct NAChannelMap {
ids: Vec<NAChannelType>,
];
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<u8> {
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() {
}
}
+/// A list of RGB colour model variants.
#[derive(Debug,Clone,Copy,PartialEq)]
pub enum RGBSubmodel {
RGB,
}
}
+/// 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,
}
}
}
+/// A list of known colour models.
#[derive(Debug, Clone,Copy,PartialEq)]
pub enum ColorModel {
RGB(RGBSubmodel),
}
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",
}
}
+/// 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<NAPixelChromaton>; 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,
}
});
}
+/// 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),
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),
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),
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),
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),
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),
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 {
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
}
impl NAPixelFormaton {
+ /// Constructs a new instance of `NAPixelFormaton`.
pub fn new(model: ColorModel,
comp1: Option<NAPixelChromaton>,
comp2: Option<NAPixelChromaton>,
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<NAPixelChromaton> {
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() {
}
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() {
}
mdepth
}
+ /// Returns the maximum component subsampling.
pub fn get_max_subsampling(&self) -> u8 {
let mut ssamp = 0;
for chr in self.comp_info.iter() {
projects / nihav.git / commitdiff