From: Kostya Shishkov Date: Tue, 18 Feb 2020 15:06:36 +0000 (+0100) Subject: core/test: document module X-Git-Url: https://git.nihav.org/?a=commitdiff_plain;h=fb8e31774f738353e3ada384a0751cea63936c15;p=nihav.git core/test: document module --- diff --git a/nihav-core/src/test/dec_video.rs b/nihav-core/src/test/dec_video.rs index 9c219a0..1dc2bed 100644 --- a/nihav-core/src/test/dec_video.rs +++ b/nihav-core/src/test/dec_video.rs @@ -1,3 +1,4 @@ +//! Routines for testing decoders. use std::fs::File; use std::io::prelude::*; use crate::frame::*; @@ -197,6 +198,17 @@ fn write_ppm(pfx: &str, strno: usize, num: u64, frm: NAFrameRef) { WavWriter::new(&mut wr) }*/ +/// Tests decoding of provided file and optionally outputs video frames as PNM (PPM for RGB video, PGM for YUV). +/// +/// This function expects the following arguments: +/// * `demuxer` - container format name (used to find proper demuxer for it) +/// * `name` - input file name +/// * `limit` - optional PTS value after which decoding is stopped +/// * `decode_video`/`decode_audio` - flags for enabling video/audio decoding +/// * `video_pfx` - prefix for video frames written as pictures (if enabled then output picture names should look like `/assets/test_out/PFXout00_000000.ppm` +/// * `dmx_reg` and `dec_reg` - registered demuxers and decoders that should contain demuxer and decoder(s) needed to decode the provided file. +/// +/// Since the function is intended for tests, it will panic instead of returning an error. pub fn test_file_decoding(demuxer: &str, name: &str, limit: Option, decode_video: bool, decode_audio: bool, video_pfx: Option<&str>, @@ -257,6 +269,13 @@ panic!(" unknown format"); } } +/// Tests audio decoder with the content in the provided file and optionally outputs decoded audio. +/// +/// The syntax is very similar to [`test_file_decoding`] except that it is intended for testing audio codecs. +/// +/// Since the function is intended for tests, it will panic instead of returning an error. +/// +/// [`test_file_decoding`]: ./fn.test_file_decoding.html pub fn test_decode_audio(demuxer: &str, name: &str, limit: Option, audio_pfx: Option<&str>, dmx_reg: &RegisteredDemuxers, dec_reg: &RegisteredDecoders) { let dmx_f = dmx_reg.find_demuxer(demuxer).unwrap(); @@ -406,6 +425,26 @@ fn frame_checksum(md5: &mut MD5, frm: NAFrameRef) { }; } +/// Tests decoder for requested codec in provided file. +/// +/// This functions tries to decode a stream corresponding to `dec_name` codec in input file and validate the results against expected ones. +/// +/// Since the function is intended for tests, it will panic instead of returning an error. +/// +/// # Examples +/// +/// Test RealVideo 4 decoder in test stream: +/// ```no_run +/// use nihav_core::test::ExpectedTestResult; +/// use nihav_core::test::dec_video::test_decoding; +/// use nihav_core::codecs::RegisteredDecoders; +/// use nihav_core::demuxers::RegisteredDemuxers; +/// +/// let mut dmx_reg = RegisteredDemuxers::new(); +/// let mut dec_reg = RegisteredDecoders::new(); +/// // ... register RealMedia demuxers and RealVideo decoders ... +/// test_decoding("realmedia", "rv40", "assets/test_file.rmvb", None, &dmx_reg, &dec_reg, ExpectedTestResult::MD5([0x00010203, 0x04050607, 0x08090a0b, 0x0c0d0e0f])); +/// ``` pub fn test_decoding(demuxer: &str, dec_name: &str, filename: &str, limit: Option, dmx_reg: &RegisteredDemuxers, dec_reg: &RegisteredDecoders, test: ExpectedTestResult) { diff --git a/nihav-core/src/test/mod.rs b/nihav-core/src/test/mod.rs index 15f13eb..367be24 100644 --- a/nihav-core/src/test/mod.rs +++ b/nihav-core/src/test/mod.rs @@ -1,11 +1,21 @@ +//! Decoder testing functionality. +//! +//! This module provides functions that may be used in internal test to check that decoders produce output and that they produce expected output. pub mod dec_video; pub mod wavwriter; mod md5; // for internal checksums only +/// Decoder testing modes. +/// +/// NihAV has its own MD5 hasher that calculates hash for input frame in a deterministic way (i.e. no endianness issues) and it outputs hash as `[u32; 4]`. During testing the resulting hash will be printed out so when the test fails you can find what was the calculated hash (and use it as a reference if you are implementing a new test). pub enum ExpectedTestResult { + /// Decoding runs without errors. Decodes, + /// Full decoded output is expected to be equal to this MD5 hash. MD5([u32; 4]), + /// Each decoded frame hash should be equal to the corresponding MD5 hash. MD5Frames(Vec<[u32; 4]>), + /// Test function should report decoded frame hashes to be used as the reference later. GenerateMD5Frames, } diff --git a/nihav-core/src/test/wavwriter.rs b/nihav-core/src/test/wavwriter.rs index 0c32430..50b1949 100644 --- a/nihav-core/src/test/wavwriter.rs +++ b/nihav-core/src/test/wavwriter.rs @@ -1,7 +1,9 @@ +//! Audio output in WAV format. use crate::io::byteio::*; use crate::frame::*; use std::io::SeekFrom; +/// WAVE output writer. pub struct WavWriter<'a> { io: &'a mut ByteWriter<'a>, data_pos: u64, @@ -46,9 +48,13 @@ macro_rules! write_data { } impl<'a> WavWriter<'a> { + /// Constructs a new `WavWriter` instance. pub fn new(io: &'a mut ByteWriter<'a>) -> Self { WavWriter { io, data_pos: 0 } } + /// Writes audio format information to the file header. + /// + /// This function should be called exactly once before writing actual audio data. pub fn write_header(&mut self, ainfo: NAAudioInfo) -> ByteIOResult<()> { let bits = ainfo.get_format().get_bits() as usize; @@ -78,6 +84,7 @@ impl<'a> WavWriter<'a> { self.data_pos = self.io.tell(); Ok(()) } + /// Writes audio data. pub fn write_frame(&mut self, abuf: NABufferType) -> ByteIOResult<()> { match abuf { NABufferType::AudioU8(ref buf) => {