In simple terms, circular buffering is like having a loop that stores and retrieves data from a fixed memory location. This can be useful for real-time audio processing because it allows us to continuously read and write data without worrying about buffer overflows or underflows.

Here’s how it works: let’s say we have a ring buffer with a capacity of 1024 bytes (which is common in many audio applications). When new data comes in, we add it to the end of the buffer and then move the “read pointer” back to the beginning. This way, when we read from the buffer, we always get the most recent data first.

To implement this in code, we can use a circular queue or deque (depending on whether we want to support insertion at both ends). Here’s an example implementation using a ringbuffer_chunk struct:

“`c++
// This script implements a ringbuffer data structure, which is a type of circular queue or deque that allows for efficient insertion and retrieval of data. It is commonly used in systems where data is constantly being added and removed, such as in network communication or real-time data processing.

// The ringbuffer struct holds information about the buffer, including a pointer to the start of the memory region, the maximum capacity, and indices for reading and writing data.
struct ringbuffer {
char *data; // pointer to the start of the memory region for our buffer
size_t capacity; // maximum number of bytes that can be stored in this buffer
int read_index, write_index; // indices for reading and writing data
};

// This function creates a new ringbuffer with the given capacity and returns a pointer to it.
ringbuffer *new_ringbuffer(size_t cap) {
ringbuffer *buf = malloc(sizeof(ringbuffer)); // allocate memory for the buffer struct
buf->data = malloc(cap); // allocate memory for the buffer data
buf->capacity = cap;
buf->read_index = 0; // start at the beginning of our buffer
buf->write_index = 0; // also start at the beginning (since we haven’t written anything yet)
return buf;
}

// This function adds a new chunk of data to the end of the ringbuffer.
void push(ringbuffer *buf, const void *data, size_t len) {
if ((buf->write_index + len) > buf->capacity) { // check for buffer overflow
printf(“Error: Buffer is full\n”);
return;
}
memcpy(&buf->data[buf->write_index], data, len); // copy the new chunk of data to our buffer
buf->write_index = (buf->write_index + len) % buf->capacity; // update our write pointer to wrap around if necessary
}

// This function reads a chunk of data from the ringbuffer and returns it as a void* pointer.
void *pop(ringbuffer *buf, size_t *len) {
if (buf->read_index == buf->write_index) { // check for buffer underflow
printf(“Error: Buffer is empty\n”);
return NULL;
}
void *data = &buf->data[buf->read_index]; // get a pointer to the current chunk of data
size_t chunk_len = buf->write_index – buf->read_index; // calculate how much data we can read without overflowing our buffer
if (*len > chunk_len) { // check for buffer underflow and adjust the length accordingly
*len = chunk_len;
}
buf->read_index = (buf->read_index + *len) % buf->capacity; // update our read pointer to wrap around if necessary
return data; // return a pointer to the current chunk of data
}
“`

In this example, we’re using a simple circular buffer with a fixed capacity. When we add new data to the end of the buffer (using `push()`), we copy it into the next available memory location and update our write pointer accordingly. Similarly, when we read from the buffer (using `pop()`), we get a pointer to the current chunk of data and adjust our read pointer as needed.

This implementation is simple but not very efficient for large buffers or high-speed applications because it involves copying data between memory locations every time we add or remove something from the ringbuffer. However, it’s still useful for demonstrating how circular buffering works in real-time audio processing and can be a good starting point for more advanced implementations that use optimized algorithms to minimize overhead.

In our main I/O loop, we first get the free buffer region where we write new audio samples. When the buffer is full, we start the stream for the first time and wait until our callback function is called. Once the data has been processed by the callback function, we can read it back from the ringbuffer using `pop()`.

To drain the buffer, we just wait until our ring buffer is empty. When it is, I stop the stream with AudioDeviceStop(). Remember that in case the input data was less than the size of our buffer, our stream isn’t yet started. We start it with AudioDeviceStart() if it’s the case.