Circular Buffer
[Audio Manipulation Algorithms]

---

Detailed Description

This section describes PJMEDIA's implementation of circular buffer.

Data Structures
struct	pjmedia_circ_buf
Defines
#define	PJMEDIA_CIRC_BUF_CHECK(x)
Functions
pj_status_t	pjmedia_circ_buf_create (pj_pool_t *pool, unsigned capacity, pjmedia_circ_buf **p_cb)
pj_status_t	pjmedia_circ_buf_reset (pjmedia_circ_buf *circbuf)
unsigned	pjmedia_circ_buf_get_len (pjmedia_circ_buf *circbuf)
void	pjmedia_circ_buf_set_len (pjmedia_circ_buf *circbuf, unsigned len)
pj_status_t	pjmedia_circ_buf_adv_read_ptr (pjmedia_circ_buf *circbuf, unsigned count)
pj_status_t	pjmedia_circ_buf_adv_write_ptr (pjmedia_circ_buf *circbuf, unsigned count)
void	pjmedia_circ_buf_get_read_regions (pjmedia_circ_buf *circbuf, pj_int16_t **reg1, unsigned *reg1_len, pj_int16_t **reg2, unsigned *reg2_len)
void	pjmedia_circ_buf_get_write_regions (pjmedia_circ_buf *circbuf, pj_int16_t **reg1, unsigned *reg1_len, pj_int16_t **reg2, unsigned *reg2_len)
pj_status_t	pjmedia_circ_buf_read (pjmedia_circ_buf *circbuf, pj_int16_t *data, unsigned count)
pj_status_t	pjmedia_circ_buf_write (pjmedia_circ_buf *circbuf, pj_int16_t *data, unsigned count)
pj_status_t	pjmedia_circ_buf_copy (pjmedia_circ_buf *circbuf, unsigned start_idx, pj_int16_t *data, unsigned count)
pj_status_t	pjmedia_circ_buf_pack_buffer (pjmedia_circ_buf *circbuf)

---

Function Documentation

pj_status_t pjmedia_circ_buf_create	(	pj_pool_t *	pool,
		unsigned	capacity,
		pjmedia_circ_buf **	p_cb
	)

Create the circular buffer.

Parameters:

	pool	Pool where the circular buffer will be allocated from.
	capacity	Capacity of the buffer, in samples.
	p_cb	Pointer to receive the circular buffer instance.

Returns:

PJ_SUCCESS if the circular buffer has been created successfully, otherwise the appropriate error will be returned.

References pjmedia_circ_buf::buf, pjmedia_circ_buf::capacity, pjmedia_circ_buf::len, PJ_INLINE, pj_pool_calloc(), PJ_POOL_ZALLOC_T, PJ_SUCCESS, and pjmedia_circ_buf::start.

pj_status_t pjmedia_circ_buf_reset

(

pjmedia_circ_buf *

circbuf

)

Reset the circular buffer.

Parameters:

circbuf

The circular buffer.

Returns:

PJ_SUCCESS when successful.

References PJ_INLINE, and PJ_SUCCESS.

Referenced by pjmedia_circ_buf_adv_read_ptr().

unsigned pjmedia_circ_buf_get_len

(

pjmedia_circ_buf *

circbuf

)

Get the circular buffer length, it is number of samples buffered in the circular buffer.

Parameters:

circbuf

The circular buffer.

Returns:

The buffer length.

References PJ_INLINE.

Referenced by pjmedia_circ_buf_pack_buffer().

void pjmedia_circ_buf_set_len	(	pjmedia_circ_buf *	circbuf,
		unsigned	len
	)

Set circular buffer length. This is useful when audio buffer is manually manipulated by the user, e.g: shrinked, expanded.

Parameters:

	circbuf	The circular buffer.
	len	The new buffer length.

References PJ_INLINE.

pj_status_t pjmedia_circ_buf_adv_read_ptr	(	pjmedia_circ_buf *	circbuf,
		unsigned	count
	)

Advance the read pointer of circular buffer. This function will discard the skipped samples while advancing the read pointer, thus reducing the buffer length.

Parameters:

	circbuf	The circular buffer.
	count	Distance from current read pointer, can only be possitive number, in samples.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_INLINE, PJ_SUCCESS, and pjmedia_circ_buf_reset().

Referenced by pjmedia_circ_buf_read().

pj_status_t pjmedia_circ_buf_adv_write_ptr	(	pjmedia_circ_buf *	circbuf,
		unsigned	count
	)

Advance the write pointer of circular buffer. Since write pointer is always pointing to a sample after the end of sample, so this function also means increasing the buffer length.

Parameters:

	circbuf	The circular buffer.
	count	Distance from current write pointer, can only be possitive number, in samples.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_ETOOBIG, PJ_INLINE, and PJ_SUCCESS.

Referenced by pjmedia_circ_buf_write().

void pjmedia_circ_buf_get_read_regions	(	pjmedia_circ_buf *	circbuf,
		pj_int16_t **	reg1,
		unsigned *	reg1_len,
		pj_int16_t **	reg2,
		unsigned *	reg2_len
	)

Get the real buffer addresses containing the audio samples.

Parameters:

	circbuf	The circular buffer.
	reg1	Pointer to store the first buffer address.
	reg1_len	Pointer to store the length of the first buffer, in samples.
	reg2	Pointer to store the second buffer address.
	reg2_len	Pointer to store the length of the second buffer, in samples.

References PJ_INLINE.

Referenced by pjmedia_circ_buf_copy(), pjmedia_circ_buf_pack_buffer(), and pjmedia_circ_buf_read().

void pjmedia_circ_buf_get_write_regions	(	pjmedia_circ_buf *	circbuf,
		pj_int16_t **	reg1,
		unsigned *	reg1_len,
		pj_int16_t **	reg2,
		unsigned *	reg2_len
	)

Get the real buffer addresses that is empty or writeable.

Parameters:

	circbuf	The circular buffer.
	reg1	Pointer to store the first buffer address.
	reg1_len	Pointer to store the length of the first buffer, in samples.
	reg2	Pointer to store the second buffer address.
	reg2_len	Pointer to store the length of the second buffer, in samples.

References PJ_INLINE.

Referenced by pjmedia_circ_buf_write().

pj_status_t pjmedia_circ_buf_read	(	pjmedia_circ_buf *	circbuf,
		pj_int16_t *	data,
		unsigned	count
	)

Read audio samples from the circular buffer.

Parameters:

	circbuf	The circular buffer.
	data	Buffer to store the read audio samples.
	count	Number of samples being read.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_ETOOBIG, PJ_INLINE, pjmedia_circ_buf_adv_read_ptr(), pjmedia_circ_buf_get_read_regions(), and pjmedia_copy_samples().

pj_status_t pjmedia_circ_buf_write	(	pjmedia_circ_buf *	circbuf,
		pj_int16_t *	data,
		unsigned	count
	)

Write audio samples to the circular buffer.

Parameters:

	circbuf	The circular buffer.
	data	Audio samples to be written.
	count	Number of samples being written.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_ETOOBIG, PJ_INLINE, pjmedia_circ_buf_adv_write_ptr(), pjmedia_circ_buf_get_write_regions(), and pjmedia_copy_samples().

pj_status_t pjmedia_circ_buf_copy	(	pjmedia_circ_buf *	circbuf,
		unsigned	start_idx,
		pj_int16_t *	data,
		unsigned	count
	)

Copy audio samples from the circular buffer without changing its state.

Parameters:

	circbuf	The circular buffer.
	start_idx	Starting sample index to be copied.
	data	Buffer to store the read audio samples.
	count	Number of samples being read.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_ETOOBIG, PJ_INLINE, PJ_SUCCESS, pjmedia_circ_buf_get_read_regions(), and pjmedia_copy_samples().

pj_status_t pjmedia_circ_buf_pack_buffer

(

pjmedia_circ_buf *

circbuf

)

Pack the buffer so the first sample will be in the beginning of the buffer. This will also make the buffer contiguous.

Parameters:

circbuf

The circular buffer.

Returns:

PJ_SUCCESS when successful, otherwise the appropriate error will be returned.

References PJ_ETOOBIG, PJ_INLINE, PJ_SUCCESS, pjmedia_circ_buf_get_len(), pjmedia_circ_buf_get_read_regions(), pjmedia_copy_samples(), and pjmedia_move_samples().