Group PJMED_CIRCBUF¶
-
group
PJMED_CIRCBUF
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.
This section describes PJMEDIA’s implementation of circular buffer.
Defines
-
PJMEDIA_CIRC_BUF_CHECK
(x)¶
Functions
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
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.
-
struct
pjmedia_circ_buf
¶ - #include <circbuf.h>
Circular buffer structure
-