Circular Buffer

Circular buffer manages read and write contiguous audio samples in a non-contiguous buffer as if the buffer were contiguous. This should give better performance than keeping contiguous samples in a contiguous buffer, since read/write operations will only update the pointers, instead of shifting audio samples. More...

Data Structures
struct	pjmedia_circ_buf

Macros
#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)

Detailed Description

This section describes PJMEDIA's implementation of circular buffer.

Function Documentation

pjmedia_circ_buf_create()

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.

pjmedia_circ_buf_reset()

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 pjmedia_circ_buf::buf, pjmedia_circ_buf::len, PJ_INLINE, PJ_SUCCESS, and pjmedia_circ_buf::start.

Referenced by pjmedia_circ_buf_adv_read_ptr().

pjmedia_circ_buf_get_len()

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 pjmedia_circ_buf::len, and PJ_INLINE.

Referenced by pjmedia_circ_buf_pack_buffer().

pjmedia_circ_buf_set_len()

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.

pjmedia_circ_buf_adv_read_ptr()

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 pjmedia_circ_buf::len, PJ_INLINE, and pjmedia_circ_buf_reset().

Referenced by pjmedia_circ_buf_read().

pjmedia_circ_buf_adv_write_ptr()

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 pjmedia_circ_buf::capacity, pjmedia_circ_buf::len, PJ_ETOOBIG, PJ_INLINE, and PJ_SUCCESS.

Referenced by pjmedia_circ_buf_write().

pjmedia_circ_buf_get_read_regions()

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 pjmedia_circ_buf::buf, pjmedia_circ_buf::capacity, pjmedia_circ_buf::len, PJ_INLINE, and pjmedia_circ_buf::start.

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

pjmedia_circ_buf_get_write_regions()

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 pjmedia_circ_buf::buf, pjmedia_circ_buf::capacity, pjmedia_circ_buf::len, PJ_INLINE, and pjmedia_circ_buf::start.

Referenced by pjmedia_circ_buf_write().

pjmedia_circ_buf_read()

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 pjmedia_circ_buf::len, PJ_ETOOBIG, PJ_INLINE, pjmedia_circ_buf_adv_read_ptr(), pjmedia_circ_buf_get_read_regions(), and pjmedia_copy_samples().

pjmedia_circ_buf_write()

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 pjmedia_circ_buf::capacity, pjmedia_circ_buf::len, PJ_ETOOBIG, PJ_INLINE, pjmedia_circ_buf_adv_write_ptr(), pjmedia_circ_buf_get_write_regions(), and pjmedia_copy_samples().

pjmedia_circ_buf_copy()

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 pjmedia_circ_buf::len, PJ_ETOOBIG, PJ_INLINE, PJ_SUCCESS, pjmedia_circ_buf_get_read_regions(), and pjmedia_copy_samples().

pjmedia_circ_buf_pack_buffer()

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 pjmedia_circ_buf::buf, pjmedia_circ_buf::capacity, PJ_ETOOBIG, PJ_INLINE, PJ_SUCCESS, pjmedia_circ_buf_get_len(), pjmedia_circ_buf_get_read_regions(), pjmedia_copy_samples(), pjmedia_move_samples(), and pjmedia_circ_buf::start.