Adding some new functionality and documentation to DummyReader

include/DummyReader.h

@@ -46,14 +46,58 @@
 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 added using the WriteFrame() method.
 	 *
 	 * 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 a reader (Fraction fps, int width, int height, int sample_rate, int channels, float duration)
+	 * openshot::DummyReader r(openshot::Fraction(30, 1), 1920, 1080, 44100, 2, 30.0);
+	 * r.Open(); // Open the reader
+	 *
+	 * // Get a frame (which will be blank, since we haven't added any frames yet)
+	 * std::shared_ptr<openshot::Frame> f = r.GetFrame(1);
+	 *
+	 * // 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
+	 *
+	 *   // Write test frame to dummy reader
+	 *   r.WriteFrame(f);
+	 * }
+	 *
+	 * // 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
+	 *
+	 * // Close the reader
+	 * r.Close();
+	 * @endcode
 	 */
 	class DummyReader : public ReaderBase
 	{
 	private:
+		CacheMemory dummy_cache;
 		std::shared_ptr<openshot::Frame> image_frame;
 		bool is_open;
 
@@ -94,6 +138,10 @@ namespace openshot
 
 		/// Open File - which is called by the constructor automatically
 		void Open() override;
+
+		/// @brief Add a frame to the dummy reader. This is useful when constructing unit tests that require custom frames.
+		/// @param frame The openshot::Frame object to write to this image
+		void WriteFrame(std::shared_ptr<openshot::Frame> frame);
 	};
 
 }

src/DummyReader.cpp

@@ -99,24 +99,49 @@ void DummyReader::Close()
 	{
 		// Mark as "closed"
 		is_open = false;
+
+		// Clear cache
+		dummy_cache.Clear();
+	}
+}
+
+// Add Frame objects to DummyReader
+void DummyReader::WriteFrame(std::shared_ptr<openshot::Frame> frame)
+{
+	if (frame) {
+		dummy_cache.Add(frame);
 	}
 }
 
-// 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 the WriteFrame() method.
 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)
-	{
+	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 added with WriteFrame().", "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,102 @@
+/**
+ * @file
+ * @brief Unit tests for openshot::DummyReader
+ * @author Jonathan Thomas <jonathan@openshot.org>
+ *
+ * @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_Constructor) {
+	// 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
+
+	// 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(30.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 added any frames using WriteFrame() yet)
+	// 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 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
+
+	// 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
+
+		// Write test frame to dummy reader
+		r.WriteFrame(f);
+	}
+
+	// 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);
+}