Merge pull request #527 from OpenShot/dummy_reader_improvements

Adding some new functionality and documentation to DummyReader

Author: jonoomph

include/DummyReader.h

@@ -46,17 +46,65 @@
 namespace openshot
 {
 	/**
-	 * @brief This class is used as a simple, dummy reader, which always returns a blank frame.
+	 * @brief This class is used as a simple, dummy reader, which can be very useful when writing
+	 * unit tests. It can return a single blank frame or it can return custom frame objects
+	 * which were passed into the constructor with a Cache object.
 	 *
 	 * A dummy reader can be created with any framerate or samplerate. This is useful in unit
 	 * tests that need to test different framerates or samplerates.
+	 *
+	 * @code
+	 * 	// Create cache object to store fake Frame objects
+	 * 	CacheMemory cache;
+	 *
+	 * // Now let's create some test frames
+	 * for (int64_t frame_number = 1; frame_number <= 30; frame_number++)
+	 * {
+	 *   // Create blank frame (with specific frame #, samples, and channels)
+	 *   // Sample count should be 44100 / 30 fps = 1470 samples per frame
+	 *   int sample_count = 1470;
+	 *   std::shared_ptr<openshot::Frame> f(new openshot::Frame(frame_number, sample_count, 2));
+	 *
+	 *   // Create test samples with incrementing value
+	 *   float *audio_buffer = new float[sample_count];
+	 *   for (int64_t sample_number = 0; sample_number < sample_count; sample_number++)
+	 *   {
+	 *     // Generate an incrementing audio sample value (just as an example)
+	 *     audio_buffer[sample_number] = float(frame_number) + (float(sample_number) / float(sample_count));
+	 *   }
+	 *
+	 *   // Add custom audio samples to Frame (bool replaceSamples, int destChannel, int destStartSample, const float* source,
+	 *   //                                    int numSamples, float gainToApplyToSource = 1.0f)
+	 *   f->AddAudio(true, 0, 0, audio_buffer, sample_count, 1.0); // add channel 1
+	 *   f->AddAudio(true, 1, 0, audio_buffer, sample_count, 1.0); // add channel 2
+	 *
+	 *   // Add test frame to cache
+	 *   cache.Add(f);
+	 * }
+	 *
+	 * // Create a reader (Fraction fps, int width, int height, int sample_rate, int channels, float duration, CacheBase* cache)
+	 * openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 30.0, &cache);
+	 * r.Open(); // Open the reader
+	 *
+	 * // Now let's verify our DummyReader works
+	 * std::shared_ptr<openshot::Frame> f = r.GetFrame(1);
+	 * // r.GetFrame(1)->GetAudioSamples(0)[1] should equal 1.00068033 based on our above calculations
+	 *
+	 * // Clean up
+	 * r.Close();
+	 * cache.Clear()
+	 * @endcode
 	 */
 	class DummyReader : public ReaderBase
 	{
 	private:
+		CacheBase* dummy_cache;
 		std::shared_ptr<openshot::Frame> image_frame;
 		bool is_open;
 
+		/// Initialize variables used by constructor
+		void init(Fraction fps, int width, int height, int sample_rate, int channels, float duration);
+
 	public:
 
 		/// Blank constructor for DummyReader, with default settings.
@@ -65,6 +113,9 @@ namespace openshot
 		/// Constructor for DummyReader.
 		DummyReader(openshot::Fraction fps, int width, int height, int sample_rate, int channels, float duration);
 
+		/// Constructor for DummyReader which takes a frame cache object.
+		DummyReader(openshot::Fraction fps, int width, int height, int sample_rate, int channels, float duration, CacheBase* cache);
+
 		virtual ~DummyReader();
 
 		/// Close File

src/DummyReader.cpp

@@ -32,16 +32,8 @@
 
 using namespace openshot;
 
-// Blank constructor for DummyReader, with default settings.
-DummyReader::DummyReader() {
-
-	// Call actual constructor with default values
-	DummyReader(Fraction(24,1), 1280, 768, 44100, 2, 30.0);
-}
-
-// Constructor for DummyReader.  Pass a framerate and samplerate.
-DummyReader::DummyReader(Fraction fps, int width, int height, int sample_rate, int channels, float duration) {
-
+// Initialize variables used by constructor
+void DummyReader::init(Fraction fps, int width, int height, int sample_rate, int channels, float duration) {
 	// Set key info settings
 	info.has_audio = false;
 	info.has_video = true;
@@ -68,10 +60,30 @@ DummyReader::DummyReader(Fraction fps, int width, int height, int sample_rate, i
 	// Set the ratio based on the reduced fraction
 	info.display_ratio.num = size.num;
 	info.display_ratio.den = size.den;
+}
+
+// Blank constructor for DummyReader, with default settings.
+DummyReader::DummyReader() : dummy_cache(NULL), is_open(false) {
+
+	// Initialize important variables
+	init(Fraction(24,1), 1280, 768, 44100, 2, 30.0);
+}
+
+// Constructor for DummyReader.  Pass a framerate and samplerate.
+DummyReader::DummyReader(Fraction fps, int width, int height, int sample_rate, int channels, float duration) : dummy_cache(NULL), is_open(false) {
+
+	// Initialize important variables
+	init(fps, width, height, sample_rate, channels, duration);
+}
 
-	// Open and Close the reader, to populate its attributes (such as height, width, etc...)
-	Open();
-	Close();
+// Constructor which also takes a cache object
+DummyReader::DummyReader(Fraction fps, int width, int height, int sample_rate, int channels, float duration, CacheBase* cache) : is_open(false) {
+
+	// Initialize important variables
+	init(fps, width, height, sample_rate, channels, duration);
+
+	// Set cache object
+	dummy_cache = (CacheBase*) cache;
 }
 
 DummyReader::~DummyReader() {
@@ -102,21 +114,40 @@ void DummyReader::Close()
 	}
 }
 
-// Get an openshot::Frame object for a specific frame number of this reader.
+// Get an openshot::Frame object for a specific frame number of this reader. It is either a blank frame
+// or a custom frame added with passing a Cache object to the constructor.
 std::shared_ptr<Frame> DummyReader::GetFrame(int64_t requested_frame)
 {
 	// Check for open reader (or throw exception)
 	if (!is_open)
 		throw ReaderClosed("The ImageReader is closed.  Call Open() before calling this method.", "dummy");
 
-	if (image_frame)
-	{
+	int dummy_cache_count = 0;
+	if (dummy_cache) {
+		dummy_cache_count = dummy_cache->Count();
+	}
+
+	if (dummy_cache_count == 0 && image_frame) {
 		// Create a scoped lock, allowing only a single thread to run the following code at one time
 		const GenericScopedLock<CriticalSection> lock(getFrameCriticalSection);
 
 		// Always return same frame (regardless of which frame number was requested)
 		image_frame->number = requested_frame;
 		return image_frame;
+
+	} else if (dummy_cache_count > 0) {
+		// Create a scoped lock, allowing only a single thread to run the following code at one time
+		const GenericScopedLock<CriticalSection> lock(getFrameCriticalSection);
+
+		// Get a frame from the dummy cache
+		std::shared_ptr<openshot::Frame> f = dummy_cache->GetFrame(requested_frame);
+		if (f) {
+			// return frame from cache (if found)
+			return f;
+		} else {
+			// No cached frame found
+			throw InvalidFile("Requested frame not found. You can only access Frame numbers that exist in the Cache object.", "dummy");
+		}
 	}
 	else
 		// no frame loaded

src/Frame.cpp

@@ -480,6 +480,11 @@ const unsigned char* Frame::GetPixels()
 // Get pixel data (for only a single scan-line)
 const unsigned char* Frame::GetPixels(int row)
 {
+	// Check for blank image
+	if (!image)
+		// Fill with black
+		AddColor(width, height, color);
+
 	// Return array of pixel packets
 	return image->constScanLine(row);
 }

tests/CMakeLists.txt

@@ -109,6 +109,7 @@ set(OPENSHOT_TEST_FILES
   Clip_Tests.cpp
   Color_Tests.cpp
   Coordinate_Tests.cpp
+  DummyReader_Tests.cpp
   ReaderBase_Tests.cpp
   ImageWriter_Tests.cpp
   FFmpegReader_Tests.cpp

tests/DummyReader_Tests.cpp

@@ -0,0 +1,149 @@
+/**
+ * @file
+ * @brief Unit tests for openshot::DummyReader
+ * @author Jonathan Thomas <[email protected]>
+ *
+ * @ref License
+ */
+
+/* LICENSE
+ *
+ * Copyright (c) 2008-2019 OpenShot Studios, LLC
+ * <http://www.openshotstudios.com/>. This file is part of
+ * OpenShot Library (libopenshot), an open-source project dedicated to
+ * delivering high quality video editing and animation solutions to the
+ * world. For more information visit <http://www.openshot.org/>.
+ *
+ * OpenShot Library (libopenshot) is free software: you can redistribute it
+ * and/or modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation, either version 3 of the
+ * License, or (at your option) any later version.
+ *
+ * OpenShot Library (libopenshot) is distributed in the hope that it will be
+ * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with OpenShot Library. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include "UnitTest++.h"
+// Prevent name clashes with juce::UnitTest
+#define DONT_SET_USING_JUCE_NAMESPACE 1
+
+#include "../include/OpenShot.h"
+
+using namespace std;
+using namespace openshot;
+
+TEST (DummyReader_Basic_Constructor) {
+	// Create a default fraction (should be 1/1)
+	openshot::DummyReader r;
+	r.Open(); // Open the reader
+
+	// Check values
+			CHECK_EQUAL(1280, r.info.width);
+			CHECK_EQUAL(768, r.info.height);
+			CHECK_EQUAL(24, r.info.fps.num);
+			CHECK_EQUAL(1, r.info.fps.den);
+			CHECK_EQUAL(44100, r.info.sample_rate);
+			CHECK_EQUAL(2, r.info.channels);
+			CHECK_EQUAL(30.0, r.info.duration);
+}
+
+TEST (DummyReader_Constructor) {
+	// Create a default fraction (should be 1/1)
+	openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 60.0);
+	r.Open(); // Open the reader
+
+	// Check values
+	CHECK_EQUAL(1920, r.info.width);
+	CHECK_EQUAL(1080, r.info.height);
+	CHECK_EQUAL(30, r.info.fps.num);
+	CHECK_EQUAL(1, r.info.fps.den);
+	CHECK_EQUAL(44100, r.info.sample_rate);
+	CHECK_EQUAL(2, r.info.channels);
+	CHECK_EQUAL(60.0, r.info.duration);
+}
+
+TEST (DummyReader_Blank_Frame) {
+	// Create a default fraction (should be 1/1)
+	openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 30.0);
+	r.Open(); // Open the reader
+
+	// Get a blank frame (because we have not passed a Cache object (full of Frame objects) to the constructor
+	// Check values
+	CHECK_EQUAL(1, r.GetFrame(1)->number);
+	CHECK_EQUAL(1, r.GetFrame(1)->GetPixels(700)[700] == 0); // black pixel
+	CHECK_EQUAL(1, r.GetFrame(1)->GetPixels(701)[701] == 0); // black pixel
+}
+
+TEST (DummyReader_Fake_Frame) {
+
+	// Create cache object to hold test frames
+	CacheMemory cache;
+
+	// Let's create some test frames
+	for (int64_t frame_number = 1; frame_number <= 30; frame_number++) {
+		// Create blank frame (with specific frame #, samples, and channels)
+		// Sample count should be 44100 / 30 fps = 1470 samples per frame
+		int sample_count = 1470;
+		std::shared_ptr<openshot::Frame> f(new openshot::Frame(frame_number, sample_count, 2));
+
+		// Create test samples with incrementing value
+		float *audio_buffer = new float[sample_count];
+		for (int64_t sample_number = 0; sample_number < sample_count; sample_number++) {
+			// Generate an incrementing audio sample value (just as an example)
+			audio_buffer[sample_number] = float(frame_number) + (float(sample_number) / float(sample_count));
+		}
+
+		// Add custom audio samples to Frame (bool replaceSamples, int destChannel, int destStartSample, const float* source,
+		f->AddAudio(true, 0, 0, audio_buffer, sample_count, 1.0); // add channel 1
+		f->AddAudio(true, 1, 0, audio_buffer, sample_count, 1.0); // add channel 2
+
+		// Add test frame to dummy reader
+		cache.Add(f);
+	}
+
+	// Create a default fraction (should be 1/1)
+	openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 30.0, &cache);
+	r.Open(); // Open the reader
+
+	// Verify our artificial audio sample data is correct
+	CHECK_EQUAL(1, r.GetFrame(1)->number);
+	CHECK_EQUAL(1, r.GetFrame(1)->GetAudioSamples(0)[0]);
+	CHECK_CLOSE(1.00068033, r.GetFrame(1)->GetAudioSamples(0)[1], 0.00001);
+	CHECK_CLOSE(1.00136054, r.GetFrame(1)->GetAudioSamples(0)[2], 0.00001);
+	CHECK_EQUAL(2, r.GetFrame(2)->GetAudioSamples(0)[0]);
+	CHECK_CLOSE(2.00068033, r.GetFrame(2)->GetAudioSamples(0)[1], 0.00001);
+	CHECK_CLOSE(2.00136054, r.GetFrame(2)->GetAudioSamples(0)[2], 0.00001);
+
+	// Clean up
+	cache.Clear();
+	r.Close();
+}
+
+TEST (DummyReader_Invalid_Fake_Frame) {
+	// Create fake frames (with specific frame #, samples, and channels)
+	std::shared_ptr<openshot::Frame> f1(new openshot::Frame(1, 1470, 2));
+	std::shared_ptr<openshot::Frame> f2(new openshot::Frame(2, 1470, 2));
+
+	// Add test frames to cache object
+	CacheMemory cache;
+	cache.Add(f1);
+	cache.Add(f2);
+
+	// Create a default fraction (should be 1/1)
+	openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 30.0, &cache);
+	r.Open();
+
+	// Verify exception
+	CHECK_EQUAL(1, r.GetFrame(1)->number);
+	CHECK_EQUAL(2, r.GetFrame(2)->number);
+	CHECK_THROW(r.GetFrame(3)->number, InvalidFile);
+
+	// Clean up
+	cache.Clear();
+	r.Close();
+}