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

Public Members

pj_int16_t *buf

The buffer

unsigned capacity

Buffer capacity, in samples

pj_int16_t *start

Pointer to the first sample

unsigned len

Audio samples length, in samples