BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJMEDIA Reference

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
poolPool where the circular buffer will be allocated from.
capacityCapacity of the buffer, in samples.
p_cbPointer 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
circbufThe 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
circbufThe 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
circbufThe circular buffer.
lenThe 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
circbufThe circular buffer.
countDistance 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
circbufThe circular buffer.
countDistance 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
circbufThe circular buffer.
reg1Pointer to store the first buffer address.
reg1_lenPointer to store the length of the first buffer, in samples.
reg2Pointer to store the second buffer address.
reg2_lenPointer 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
circbufThe circular buffer.
reg1Pointer to store the first buffer address.
reg1_lenPointer to store the length of the first buffer, in samples.
reg2Pointer to store the second buffer address.
reg2_lenPointer 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
circbufThe circular buffer.
dataBuffer to store the read audio samples.
countNumber 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
circbufThe circular buffer.
dataAudio samples to be written.
countNumber 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
circbufThe circular buffer.
start_idxStarting sample index to be copied.
dataBuffer to store the read audio samples.
countNumber 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
circbufThe 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.

 


PJMEDIA small footprint Open Source media stack
Copyright (C) 2006-2008 Teluu Inc.