TMediaBuffer

primo::avblocks::modern::TMediaBuffer

class TMediaBuffer

Fluent wrapper for primo::codecs::MediaBuffer, a buffer for media data.

A buffer has a capacity, which is the size of its memory block, and a data range, the part of the block that holds valid data. The valid data is contiguous and can start at any offset in the block.

Owns the raw object through a primo::ref. Not copyable, movable.

Unnamed Group

TMediaBuffer(TMediaBuffer&&) = default
TMediaBuffer &operator=(TMediaBuffer&&) = default

Move construction/assignment transfers ownership of the underlying object. The moved-from object no longer wraps anything.

Unnamed Group

inline TMediaBuffer &&attach(const uint8_t *data, size_t size, bool copy = true) &&
inline TMediaBuffer &attach(const uint8_t *data, size_t size, bool copy = true) &

Attaches an external memory block as the buffer storage.

Any internal storage is freed. The block is not copied and must stay valid for as long as it is attached.

Parameters:

  • data – Pointer to the memory block.

  • size – Size of the block in bytes.

  • copy – When true (default) the whole block is marked as valid data, i.e. dataSize() equals size. When false the data size is 0.

Returns:

This object, for chaining.

Public Functions

inline TMediaBuffer()

Creates an empty buffer with zero capacity.

inline explicit TMediaBuffer(int32_t capacity)

Creates a buffer with internal storage.

Parameters:

capacity – Buffer capacity in bytes.

inline explicit TMediaBuffer(primo::ref<primo::codecs::MediaBuffer> buffer)

Takes ownership of an existing MediaBuffer reference.

inline explicit TMediaBuffer(primo::codecs::MediaBuffer *buffer)

Wraps a non-owned MediaBuffer pointer, retaining it.

TMediaBuffer(const TMediaBuffer&) = delete
TMediaBuffer &operator=(const TMediaBuffer&) = delete
inline uint8_t *start() const

Returns a pointer to the start of the buffer block.

It is valid only when capacity() is greater than 0.

inline int32_t capacity() const

Returns the size of the buffer block in bytes. Can be zero.

inline bool external() const

Returns true if the buffer uses an external memory block attached with attach().

inline const uint8_t *data() const

Returns a pointer to the first byte of valid data.

Same as start() + dataOffset().

inline int32_t dataSize() const

Returns the size of the valid data in bytes, from 0 to capacity().

inline int32_t dataOffset() const

Returns the offset in bytes at which the valid data starts in the buffer block.

inline int32_t freeSpace() const

Returns the free space in bytes that can be used to append data without reallocation: capacity() - dataSize().

inline int32_t freeLinearSpace() const

Returns the contiguous free space in bytes after the valid data, which can be used to append data without normalize(): capacity() - dataSize() - dataOffset().

It is at most freeSpace().

inline TMediaBuffer &setData(int32_t offset, int32_t size)

Sets the range of valid data.

Both values are validated so that the range is always inside the buffer.

Parameters:

  • offset – Offset at which valid data starts, from 0 to capacity() - 1.

  • size – Size of the valid data, from 0 to capacity().

Returns:

This object, for chaining.

inline bool alloc(int32_t size, bool keepData)

Allocates internal storage.

Storage is allocated only if size exceeds the current capacity; the actual capacity may be larger than requested.

Parameters:

  • size – Requested size in bytes.

  • keepData – Whether to keep the existing data when the storage is reallocated.

Returns:

true on success.

inline bool alignedAlloc(int32_t alignment, int32_t size, bool keepData)

Allocates internal storage with the specified memory alignment.

Storage is allocated only if size exceeds the current capacity.

Parameters:

  • alignment – Alignment in bytes. Must be a power of 2 and at least 8.

  • size – Requested size in bytes.

  • keepData – Whether to keep the existing data when the storage is reallocated.

Returns:

true on success.

inline TMediaBuffer &free()

Frees the internal storage. Does nothing if an external memory block is attached. Returns this object, for chaining.

inline TMediaBuffer &clear()

Clears the data. The capacity does not change. Returns this object, for chaining.

inline TMediaBuffer &normalize()

Moves the valid data to the start of the buffer, which maximizes the free linear space.

Useful after data is added by copying it directly after the existing data and then extended with setData(). The capacity does not change. Returns this object, for chaining.

inline bool append(const void *data, int32_t dataSize)

Appends data to the end of the valid data.

Internal storage grows when needed; external storage does not.

Parameters:

  • data – Pointer to the data to append.

  • dataSize – Number of bytes to append.

Returns:

true on success.

inline TMediaBuffer &remove(int32_t dataSize)

Removes data from the beginning of the valid data.

The capacity does not change.

Parameters:

dataSize – Number of bytes to remove.

Returns:

This object, for chaining.

inline uint8_t *detach()

Detaches the external memory block.

Returns a pointer to it, or nullptr if none was attached.

inline TMediaBuffer clone() const

Creates a deep copy. If the buffer uses an external memory block only the pointer to it is copied.

inline primo::codecs::MediaBuffer *get() const

Returns the raw underlying pointer. For interop with the core API only.