Struct recording_buffer_s

A memory buffer for storing captured frames, for use by VCS's recording subsystem.


Public member functions

voidinitialize(const size_t frameCapacity=10)

Data fields

const unsignedmaxHeight
const unsignedmaxWidth

Detailed description

A memory buffer for storing captured frames, for use by VCS's recording subsystem.

This buffer allocates memory using VCS's memory subsystem for a given fixed number of captured frames, and provides access to the memory via a LIFO-like (last in, first out) queue interface.

The buffer provides the queue-like commands push() and pop(), of which push() marks the next available frame slot in the buffer as being in use and returns a pointer to its memory (which is big enough to hold one captured frame). This memory is available to the caller until it's marked by a call to pop() as no longer being in use, after which it's made available to subsequent push() calls. In LIFO fashion, the slot reserved by the most recent call to push() will be the last to be unreserved by pop().


  1. Initialize the buffer by calling initialize().
  2. To add a captured frame into the buffer, call push() to obtain a pointer to the next available frame slot, then copy the frame's pixel data into this memory area. The memory area is large enough to hold the maximum frame size supported by the buffer.
  3. To retrieve and remove a frame from the buffer in LIFO fashion, call pop() and copy the frame pixel data from the memory to which the function returns a pointer.
  4. When you no longer need the buffer, release it by calling release().

Public member function documentation

bool empty(void)

Returns true if the buffer currently has no frame slots reserved; false otherwise.

bool full(void)

Returns true if the buffer is currently at maximum capacity; false otherwise.

If the buffer is full, no new frames can be queued with push() until one or more frame slots are unreserved with pop() or the buffer is reset with reset().

void initialize(const size_t frameCapacity)

Initializes the buffer, allocating memory to hold at most the number of frames given by frameCapacity.

heap_mem<u8>* pop(void)

Unreserves a frame slot in the queue and returns a pointer to its memory.

The returned pointer will remain valid until either push() or release() is called.

heap_mem<u8>* push(void)

Reserves a frame slot in the buffer and returns a pointer to its memory.

void release(void)

Releases the buffer.


This function deallocates the buffer's memory, invalidating all pointers obtained from push() or pop().

void reset(void)

Resets the buffer to an empty state.

unsigned usage(void)

Returns as a percentage (0–100) the amount of buffer capacity currently in use.

Data field documentation

const unsigned maxHeight

Specifies the maximum height of frame that the buffer can store.

const unsigned maxWidth

Specifies the maximum width of frame that the buffer can store.

std::mutex mutex

A convenience mutex for use by the recording subsystem.

Not used by the class itself.

heap_mem<u8> scratchBuffer

An extra memory buffer for any temporary frame operations the VCS video recording subsystem might need to do.

The buffer has room for one captured frame.


It's likely that this buffer will be removed in a future version of VCS, since it's a bit of a temporary kludge.


This buffer's memory won't be allocated until initialize() is called.