The PCM buffer

This page is part of an attempt to document the software codec playback code.

General

The PCM buffer contains raw PCM data to be (or being) sent to the audio output. The codecs allocate space in the buffer and puts the decoded audio in the allocated space. It has two auxiliary buffers, the crossfade and voice buffers, used for mixing.

Regular PCM playback

You can allocate space in the buffer for later playback by calling the pcmbuf_request_buffer() function. It will reserve space in the buffer which will later be queued for playback when you call the pcmbuf_write_complete() function.

Step 1 - allocate buffer space

When you want to add a chunk of audio to the PCM buffer, you must first reserve the buffer space. Here's how the buffer may look before you begin. digraph G { graph[label="PCM buffer before pcmbuf_request_buffer()"]; node[fontname="Courier" shape=record width=5 height=.1 fontsize=10];

buf[label="Queued| \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ Free space\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "]; }

You then reserve some space:

char *ptr;   /* Pointer to the requested buffer */
size_t size; /* How many bytes I managed to reserve */

ptr = pcmbuf_request_buffer(0x2000, &size);

/* The 'size' variable now holds the number of bytes reserved */

Step 2 - Fill with data and queue it

You have now reserved buffer space for your audio data, but the buffer is not yet added to the PCM queue for playback. It is now time to fill the buffer with PCM data.

digraph G { graph[label="PCM buffer after pcmbuf_request_buffer()"]; node[fontname="Courier" shape=record width=5 height=.1 fontsize=10];

buf[label="Queued|Reserved|\ \ \ \ \ \ \ Free space\ \ \ \ \ \ \ \ \ "]; }

You now fill the buffer with audio data and call pcmbuf_write_complete() to add the audio data to the PCM queue. In this example, I fill it with zeroes.

memset(ptr, 0, size);

pcmbuf_write_complete(size);

/* After this, the 'ptr' pointer is no longer valid */

digraph G { graph[label="PCM buffer after pcmbuf_write_complete()"]; node[fontname="Courier" shape=record width=5 height=.1 fontsize=10];

buf[label="Queued|Queued|\ \ \ \ \ \ \ Free space\ \ \ \ \ \ \ \ \ "]; }

Special case 1 - crossfade

coming

Special case 2 - voice

coming