AudioSource v2 API

plugins/soundsourcem4a/soundsourcem4a.cpp

@@ -444,7 +444,7 @@ ReadableSampleFrames SoundSourceM4A::readSampleFramesClamped(
         if (!m_sampleBuffer.empty()) {
             // Consume previously decoded sample data
             const SampleBuffer::ReadableSlice readableSlice(
-                    m_sampleBuffer.readLifo(numberOfSamplesRemaining));
+                    m_sampleBuffer.readFromHead(numberOfSamplesRemaining));
             if (writableSampleFrames.writableData()) {
                 SampleUtil::copy(
                         writableSampleFrames.writableData(outputSampleOffset),
@@ -506,7 +506,7 @@ ReadableSampleFrames SoundSourceM4A::readSampleFramesClamped(
             const SINT writeToTailCount = math_max(
                     numberOfSamplesRemaining, decodeBufferCapacityMin);
             const SampleBuffer::WritableSlice writableSlice(
-                    m_sampleBuffer.write(writeToTailCount));
+                    m_sampleBuffer.writeToTail(writeToTailCount));
             pDecodeBuffer = writableSlice.data();
             decodeBufferCapacity = writableSlice.size();
         }
@@ -562,14 +562,14 @@ ReadableSampleFrames SoundSourceM4A::readSampleFramesClamped(
         } else {
             // Decoded into temporary buffer
             DEBUG_ASSERT(numberOfSamplesDecoded <= decodeBufferCapacity);
-            // Adjust the size of the buffer to the samples that
+            // Shrink the size of the buffer to the samples that
             // have actually been decoded
-            m_sampleBuffer.readFifo(decodeBufferCapacity - numberOfSamplesDecoded);
+            m_sampleBuffer.readFromTail(decodeBufferCapacity - numberOfSamplesDecoded);
             // Read from the buffer's head
             numberOfSamplesRead =
                     std::min(numberOfSamplesDecoded, numberOfSamplesRemaining);
             const SampleBuffer::ReadableSlice readableSlice(
-                    m_sampleBuffer.readLifo(numberOfSamplesRead));
+                    m_sampleBuffer.readFromHead(numberOfSamplesRead));
             DEBUG_ASSERT(readableSlice.size() == numberOfSamplesRead);
             if (writableSampleFrames.writableData()) {
                 SampleUtil::copy(

plugins/soundsourcemediafoundation/soundsourcemediafoundation.cpp

@@ -267,7 +267,7 @@ ReadableSampleFrames SoundSourceMediaFoundation::readSampleFramesClamped(
     SINT numberOfFramesRemaining = numberOfFramesTotal;
     while (numberOfFramesRemaining > 0) {
         SampleBuffer::ReadableSlice readableSlice(
-                m_sampleBuffer.readLifo(
+                m_sampleBuffer.readFromHead(
                         frames2samples(numberOfFramesRemaining)));
         DEBUG_ASSERT(readableSlice.size()
                 <= frames2samples(numberOfFramesRemaining));
@@ -431,7 +431,7 @@ ReadableSampleFrames SoundSourceMediaFoundation::readSampleFramesClamped(
             }
             // Buffer the remaining samples
             SampleBuffer::WritableSlice writableSlice(
-                    m_sampleBuffer.write(lockedSampleBufferCount));
+                    m_sampleBuffer.writeToTail(lockedSampleBufferCount));
             // The required capacity has been calculated in advance (see above)
             DEBUG_ASSERT(writableSlice.size() == lockedSampleBufferCount);
             SampleUtil::copy(

src/sources/soundsourceflac.cpp

@@ -264,7 +264,7 @@ ReadableSampleFrames SoundSourceFLAC::readSampleFramesClamped(
         const SINT numberOfSamplesRead =
                 std::min(m_sampleBuffer.readableLength(), numberOfSamplesRemaining);
         const SampleBuffer::ReadableSlice readableSlice(
-                m_sampleBuffer.readLifo(numberOfSamplesRead));
+                m_sampleBuffer.readFromHead(numberOfSamplesRead));
         DEBUG_ASSERT(readableSlice.size() == numberOfSamplesRead);
         if (writableSampleFrames.writableData()) {
             SampleUtil::copy(
@@ -376,7 +376,7 @@ FLAC__StreamDecoderWriteStatus SoundSourceFLAC::flacWrite(
     // Decode buffer should be empty before decoding the next frame
     DEBUG_ASSERT(m_sampleBuffer.empty());
     const SampleBuffer::WritableSlice writableSlice(
-            m_sampleBuffer.write(frames2samples(numReadableFrames)));
+            m_sampleBuffer.writeToTail(frames2samples(numReadableFrames)));
 
     const SINT numWritableFrames = samples2frames(writableSlice.size());
     DEBUG_ASSERT(numWritableFrames <= numReadableFrames);

src/test/samplebuffertest.cpp

@@ -5,6 +5,7 @@
 #include "test/mixxxtest.h"
 #include "util/readaheadsamplebuffer.h"
 
+
 class ReadAheadSampleBufferTest: public MixxxTest {
 public:
     ReadAheadSampleBufferTest()
@@ -15,29 +16,29 @@ class ReadAheadSampleBufferTest: public MixxxTest {
 protected:
     static const SINT kCapacity;
 
-    SINT write(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
+    SINT writeToTail(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
         const mixxx::SampleBuffer::WritableSlice writableSlice(
-                pSampleBuffer->write(size));
+                pSampleBuffer->writeToTail(size));
         for (SINT i = 0; i < writableSlice.size(); ++i) {
             writableSlice[i] = m_writeValue;
             m_writeValue += CSAMPLE_ONE;
         }
         return writableSlice.size();
     }
 
-    SINT readFifoAndVerify(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
+    SINT readFromHeadAndVerify(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
         const mixxx::SampleBuffer::ReadableSlice readableSlice(
-                pSampleBuffer->readFifo(size));
+                pSampleBuffer->readFromHead(size));
         for (SINT i = 0; i < readableSlice.size(); ++i) {
             EXPECT_EQ(readableSlice[i], m_readValue);
             m_readValue += CSAMPLE_ONE;
         }
         return readableSlice.size();
     }
 
-    SINT readLifoAndVerify(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
+    SINT readFromTailAndVerify(mixxx::ReadAheadSampleBuffer* pSampleBuffer, SINT size) {
         const mixxx::SampleBuffer::ReadableSlice readableSlice(
-                pSampleBuffer->readLifo(size));
+                pSampleBuffer->readFromTail(size));
         for (SINT i = readableSlice.size(); i-- > 0; ) {
             m_writeValue -= CSAMPLE_ONE;
             EXPECT_EQ(readableSlice[i], m_writeValue);
@@ -66,13 +67,13 @@ TEST_F(ReadAheadSampleBufferTest, emptyWithoutCapacity) {
     EXPECT_TRUE(sampleBuffer.empty());
 
     const mixxx::SampleBuffer::WritableSlice writableSlice(
-            sampleBuffer.write(10));
+            sampleBuffer.writeToTail(10));
     EXPECT_EQ(writableSlice.data(), static_cast<CSAMPLE*>(NULL));
     EXPECT_EQ(writableSlice.size(), 0);
     EXPECT_TRUE(sampleBuffer.empty());
 
     const mixxx::SampleBuffer::ReadableSlice readableSlice(
-            sampleBuffer.readLifo(10));
+            sampleBuffer.readFromTail(10));
     EXPECT_EQ(readableSlice.data(), static_cast<const CSAMPLE*>(NULL));
     EXPECT_EQ(readableSlice.size(), 0);
     EXPECT_TRUE(sampleBuffer.empty());
@@ -89,79 +90,103 @@ TEST_F(ReadAheadSampleBufferTest, emptyWithCapacity) {
 TEST_F(ReadAheadSampleBufferTest, readWriteTrim) {
     mixxx::ReadAheadSampleBuffer sampleBuffer(kCapacity);
 
-    SINT writeCount1 = write(&sampleBuffer, kCapacity + 10);
-    EXPECT_EQ(writeCount1, kCapacity); // buffer is full
+    SINT writeCount1 = writeToTail(&sampleBuffer, kCapacity + 10);
+    // Buffer is completely filled with samples
+    EXPECT_EQ(writeCount1, kCapacity);
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity);
     EXPECT_EQ(sampleBuffer.writableLength(), 0);
 
-    SINT readCount1 = readFifoAndVerify(&sampleBuffer, kCapacity - 10);
+    SINT readCount1 = readFromHeadAndVerify(&sampleBuffer, kCapacity - 10);
+    // Buffer contains the remaining 10 samples, but is still full
     EXPECT_EQ(readCount1, kCapacity - 10);
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity - readCount1);
     EXPECT_EQ(sampleBuffer.writableLength(), 0);
 
-    SINT writeCount2 = write(&sampleBuffer, kCapacity);
-    EXPECT_EQ(writeCount2, 0); // no tail capacity left
+    SINT writeCount2 = writeToTail(&sampleBuffer, kCapacity);
+    // Impossible to write more samples
+    EXPECT_EQ(writeCount2, 0);
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity - readCount1);
+    EXPECT_EQ(sampleBuffer.writableLength(), 0);
 
     // Trim buffer contents by reallocation
     mixxx::ReadAheadSampleBuffer(sampleBuffer).swap(sampleBuffer);
-
-    SINT writeCount3 = write(&sampleBuffer, kCapacity);
-    EXPECT_EQ(writeCount3, readCount1); // buffer has been refilled
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity - readCount1);
+    EXPECT_EQ(sampleBuffer.writableLength(), readCount1);
 
-    SINT readCount2 = readFifoAndVerify(&sampleBuffer, kCapacity - 10);
-    EXPECT_EQ(readCount2, kCapacity - 10);
+    // Refill Buffer with samples
+    SINT writeCount3 = writeToTail(&sampleBuffer, kCapacity);
+    EXPECT_EQ(writeCount3, readCount1);
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity);
     EXPECT_EQ(sampleBuffer.writableLength(), 0);
 
-    // Trim buffer contents by reallocation
+    // Read from the end
+    SINT readCount2 = readFromTailAndVerify(&sampleBuffer, readCount1);
+    EXPECT_EQ(readCount2, readCount1);
+    EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity - readCount1);
+    EXPECT_EQ(sampleBuffer.writableLength(), readCount1);
+
+    // Trim buffer contents by reallocation has no effect
     mixxx::ReadAheadSampleBuffer(sampleBuffer).swap(sampleBuffer);
+    EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity - readCount1);
+    EXPECT_EQ(sampleBuffer.writableLength(), readCount1);
 
-    SINT writeCount4 = write(&sampleBuffer, kCapacity);
+    // Refill Buffer with samples
+    SINT writeCount4 = writeToTail(&sampleBuffer, kCapacity);
     EXPECT_EQ(writeCount4, readCount2); // buffer has been refilled
     EXPECT_FALSE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), kCapacity);
+    EXPECT_EQ(sampleBuffer.writableLength(), 0);
 
-    SINT readCount3 = readFifoAndVerify(&sampleBuffer, kCapacity + 10);
-    EXPECT_EQ(readCount3, kCapacity); // whole buffer has been read
+    // Read whole buffer
+    SINT readCount3 = readFromTailAndVerify(&sampleBuffer, kCapacity + 10);
+    EXPECT_EQ(readCount3, kCapacity);
     EXPECT_TRUE(sampleBuffer.empty());
+    EXPECT_EQ(sampleBuffer.readableLength(), 0);
+    EXPECT_EQ(sampleBuffer.writableLength(), kCapacity);
 }
 
 TEST_F(ReadAheadSampleBufferTest, shrink) {
     mixxx::ReadAheadSampleBuffer sampleBuffer(kCapacity);
 
-    SINT writeCount1 = write(&sampleBuffer, kCapacity - 10);
+    SINT writeCount1 = writeToTail(&sampleBuffer, kCapacity - 10);
     EXPECT_EQ(writeCount1, kCapacity - 10);
     EXPECT_FALSE(sampleBuffer.empty());
-    SINT shrinkCount1 = readLifoAndVerify(&sampleBuffer, 10);
+    SINT shrinkCount1 = readFromHeadAndVerify(&sampleBuffer, 10);
     EXPECT_EQ(shrinkCount1, 10);
-    SINT readCount1 = readFifoAndVerify(&sampleBuffer, 10);
+    SINT readCount1 = readFromTailAndVerify(&sampleBuffer, 10);
     EXPECT_EQ(readCount1, 10);
     EXPECT_FALSE(sampleBuffer.empty());
-    SINT readCount2 = readFifoAndVerify(&sampleBuffer, kCapacity - 40);
+    SINT readCount2 = readFromTailAndVerify(&sampleBuffer, kCapacity - 40);
     EXPECT_EQ(readCount2, kCapacity - 40);
     EXPECT_FALSE(sampleBuffer.empty());
-    SINT readCount3 = readFifoAndVerify(&sampleBuffer, 20);
+    SINT readCount3 = readFromTailAndVerify(&sampleBuffer, 20);
     EXPECT_EQ(readCount3, 10);
     EXPECT_TRUE(sampleBuffer.empty());
 
-    SINT writeCount2 = write(&sampleBuffer, 20);
+    SINT writeCount2 = writeToTail(&sampleBuffer, 20);
     EXPECT_EQ(writeCount2, 20);
     EXPECT_FALSE(sampleBuffer.empty());
-    SINT shrinkCount2 = readLifoAndVerify(&sampleBuffer, 21);
+    SINT shrinkCount2 = readFromHeadAndVerify(&sampleBuffer, 21);
     EXPECT_EQ(shrinkCount2, 20);
     EXPECT_TRUE(sampleBuffer.empty());
 }
 
 TEST_F(ReadAheadSampleBufferTest, clear) {
     mixxx::ReadAheadSampleBuffer sampleBuffer(kCapacity);
 
-    SINT writeCount = write(&sampleBuffer, 10);
+    SINT writeCount = writeToTail(&sampleBuffer, 10);
     EXPECT_EQ(writeCount, 10);
     EXPECT_FALSE(sampleBuffer.empty());
     clear(&sampleBuffer);
     EXPECT_TRUE(sampleBuffer.empty());
-    SINT readCount = readFifoAndVerify(&sampleBuffer, 10);
+    SINT readCount = readFromTailAndVerify(&sampleBuffer, 10);
     EXPECT_EQ(readCount, 0);
     EXPECT_TRUE(sampleBuffer.empty());
 }

src/util/readaheadsamplebuffer.cpp

@@ -53,16 +53,16 @@ void ReadAheadSampleBuffer::clear() {
 void ReadAheadSampleBuffer::adjustCapacity(SINT capacity) {
     DEBUG_ASSERT_CLASS_INVARIANT_ReadAheadSampleBuffer;
 
-    SINT newCapacity = std::min(readableLength(), capacity);
-    if (newCapacity != capacity) {
+    SINT newCapacity = math_max(readableLength(), capacity);
+    if (newCapacity != this->capacity()) {
         ReadAheadSampleBuffer tmp(*this, newCapacity);
         swap(tmp);
     }
 
     DEBUG_ASSERT_CLASS_INVARIANT_ReadAheadSampleBuffer;
 }
 
-SampleBuffer::WritableSlice ReadAheadSampleBuffer::write(SINT writeLength) {
+SampleBuffer::WritableSlice ReadAheadSampleBuffer::writeToTail(SINT writeLength) {
     DEBUG_ASSERT_CLASS_INVARIANT_ReadAheadSampleBuffer;
 
     const SINT tailLength = math_min(writeLength, writableLength());
@@ -74,7 +74,7 @@ SampleBuffer::WritableSlice ReadAheadSampleBuffer::write(SINT writeLength) {
     return tailSlice;
 }
 
-SampleBuffer::ReadableSlice ReadAheadSampleBuffer::readFifo(SINT readLength) {
+SampleBuffer::ReadableSlice ReadAheadSampleBuffer::readFromTail(SINT readLength) {
     DEBUG_ASSERT_CLASS_INVARIANT_ReadAheadSampleBuffer;
 
     const SINT tailLength = math_min(readLength, readableLength());
@@ -91,7 +91,7 @@ SampleBuffer::ReadableSlice ReadAheadSampleBuffer::readFifo(SINT readLength) {
     return tailSlice;
 }
 
-SampleBuffer::ReadableSlice ReadAheadSampleBuffer::readLifo(SINT readLength) {
+SampleBuffer::ReadableSlice ReadAheadSampleBuffer::readFromHead(SINT readLength) {
     DEBUG_ASSERT_CLASS_INVARIANT_ReadAheadSampleBuffer;
 
     const SINT headLength = math_min(readLength, readableLength());

src/util/readaheadsamplebuffer.h

@@ -8,8 +8,10 @@
 namespace mixxx {
 
 // A FIFO/LIFO sample buffer with fixed capacity and range checking.
-// It works best when consuming all buffered samples before writing
-// any new samples.
+//
+// Samples are written at the tail and read from the head (FIFO) or
+// from the tail (LIFO). It is intended to consume all buffered samples
+// before writing any new samples.
 //
 // This class is not thread-safe and is not intended to be used from
 // multiple threads!
@@ -63,37 +65,37 @@ class ReadAheadSampleBuffer final {
         return capacity() - m_readableRange.end();
     }
 
-    // Reserves space at the buffer's back end for writing samples.
+    // Reserves space at the buffer's tail for writing samples.
     //
     // Returns a pointer to the continuous memory region and the
     // actual number of samples that have been reserved. The maximum
     // length is limited by writableLength().
     //
-    // The returned pointer is valid until the next write() operation.
-    SampleBuffer::WritableSlice write(SINT writeLength);
+    // The returned pointer is valid until the next writeToTail() operation.
+    SampleBuffer::WritableSlice writeToTail(SINT writeLength);
 
     // The number of readable samples.
     SINT readableLength() const {
         return m_readableRange.length();
     }
 
-    // Consumes buffered samples in FIFO order.
+    // Consumes buffered samples from the head of the buffer.
     //
     // Returns a pointer to the continuous memory region and the actual
     // number of readable samples. The maximum length is limited by
     // readableLength().
     //
-    // The returned pointer is valid until the next write() operation.
-    SampleBuffer::ReadableSlice readFifo(SINT readLength);
+    // The returned pointer is valid until the next writeToTail() operation.
+    SampleBuffer::ReadableSlice readFromHead(SINT readLength);
 
-    // Consumes buffered samples in LIFO order.
+    // Consumes buffered samples from the tail of the buffer
     //
     // Returns a pointer to the continuous memory region and the actual
     // number of readable samples. The maximum length is limited by
     // readableLength().
     //
-    // The returned pointer is valid until the next write() operation.
-    SampleBuffer::ReadableSlice readLifo(SINT readLength);
+    // The returned pointer is valid until the next writeToTail() operation.
+    SampleBuffer::ReadableSlice readFromTail(SINT readLength);
 
   private:
     ReadAheadSampleBuffer(