MediaBuffer

primo::codecs::MediaBuffer

class MediaBuffer : public primo::Reference

A buffer for media data.

MediaBuffer has a capacity which is the size of the buffer and data size which is the size of the actual data in the buffer. The buffer is a continuous block of memory. The valid data is also a continuous block. The data can start at any offset in the buffer.

Public Functions

virtual bool_t setData(int32_t dataOffset, int32_t dataSize) = 0

Sets the offset at which valid data starts in the buffer block and the data size in bytes.

The data offset and size are validated so that they are always within the buffer.

Parameters:

  • dataOffset – The offset at which valid data starts in the buffer. Allowed values range from 0 to capacity()-1.

  • dataSize – The size of the valid data in the buffer. Allowed values range from 0 to capacity().

Returns:

TRUE The data offset and size are successfully changed. FALSE The supplied data offset and size are not valid.

virtual int32_t dataOffset() const = 0

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

Returns:

An offset that can range from 0 to capacity()-1.

virtual int32_t dataSize() const = 0

Returns the size of the valid data that in the buffer.

Returns:

The data size in bytes. It ranges from 0 to capacity().

virtual uint8_t *data() const = 0

Returns a pointer to the first byte of data.

This is effectively the same as start() + dataOffset().

Returns:

A pointer to the data start.

virtual uint8_t *start() const = 0

Returns a pointer to the start of the buffer.

Returns:

A pointer to the buffer start. It is guaranteed that the pointer is valid only when capacity() is greater than 0.

virtual int32_t capacity() const = 0

Returns the size of the buffer in bytes.

Returns:

Buffer capacity. Can be zero.

virtual bool_t alloc(int32_t size, bool_t keepData) = 0

Allocates internal buffer storage.

Remark

If an external storage is attached it is automatically detached.

Parameters:

  • size – Requested buffer size. A buffer storage is allocated only if the requested size exceeds the current buffer size (capacity). The actual allocated buffer may be larger than the requested size.

  • keepData – Specifies whether to keep the existing data when the existing buffer is resized.

Returns:

TRUE The allocation request succeeded. FALSE The allocation failed (out of memory).

virtual bool_t alignedAlloc(int32_t alignment, int32_t size, bool_t keepData) = 0

Allocates internal buffer storage with specified memory alignment.

Remark

If an external storage is attached it is automatically detached. The aligned allocation is tracked internally and the buffer is freed using the appropriate method. The minimum alignment of 8 bytes is required for compatibility with platform memory alignment functions.

Version

3.4

Parameters:

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

  • size – Requested buffer size. A buffer storage is allocated only if the requested size exceeds the current buffer size (capacity).

  • keepData – Specifies whether to keep the existing data when the existing buffer is resized.

Returns:

TRUE The allocation request succeeded. FALSE The allocation failed (out of memory or invalid alignment).

virtual void free() = 0

Frees internal buffer storage.

Remark

The function does nothing if an external storage is attached to the buffer.

virtual bool_t attach(void *buffer, int32_t size, bool_t setData) = 0

Attaches an external buffer storage.

Remark

If an internal storage is already allocated it is automatically freed.

Parameters:

  • buffer – A pointer to the buffer storage.

  • size – The buffer size.

  • setData – Specifies whether to auto set data with a size equal to the buffer size. If TRUE the data size is set to the buffer size. If FALSE data size is 0.

Returns:

TRUE The buffer is attached succefully, FALSE otherwise.

virtual uint8_t *detach() = 0

Detaches an external buffer storage.

Returns:

A pointer to the detached buffer storage. NULL if no external storage has been attached.

virtual bool_t external() const = 0

Returns whether the MediaBuffer uses an external data buffer.

Returns:

TRUE An external data buffer is attached to this MediaBuffer, FALSE otherwise.

virtual void clear() = 0

Clears existing data.

Remark

The operation does not change the buffer capacity.

virtual bool_t append(const void *data, int32_t dataSize) = 0

Appends data to the end of the MediaBuffer data.

Remark

If MediaBuffer has internal storage it will be increased if needed to fit the data. If MediaBuffer has external storage and the provided data cannot fit the operation will fail.

Parameters:

  • data – A pointer to the data that should be appended.

  • dataSize – The number of bytes that should be appended.

Returns:

TRUE The operation is successful, FALSE otherwise.

virtual void remove(int32_t dataSize) = 0

Removes data from the beginning of the MediaBuffer data.

Remark

The operation does not change the buffer capacity.

Parameters:

dataSize – The number of bytes that should be removed from the valid data.

Returns:

TRUE The operation is successful, FALSE otherwise.

virtual void normalize() = 0

Moves the existing data to the start of the buffer amd maximizes the free linear space.

Remark

This may be useful when new data is added through direct copying after the existing data and then setData is used to extend/modify the data range. The operation does not change the buffer capacity.

virtual int32_t freeLinearSpace() const = 0

Returns the free linear space that can be used to append data without normalization.

Remark

The free linear space starts at data() + dataSize(). It is less than or equal to freeSpace().

See also

freeSpace

Returns:

The size in bytes of the free linear space in the buffer. This is equal to capacity() - dataSize() - dataOffset().

virtual int32_t freeSpace() const = 0

Returns the free space that can be used to append data without buffer reallocation.

Remark

The free space starts at data() + dataSize(). It is greater than or equal to freeLinearSpace().

See also

freeLinearSpace

Returns:

The size in bytes of the free space in the buffer. This is equal to capacity() - dataSize().

virtual MediaBuffer *clone() const = 0

Creates a deep copy of this object.

Remark

Only the pointer to the external buffer is copied when MediaBuffer does not own its data buffer, i.e. uses external / attached data. On the contrary, when MediaBuffer owns its data, a new copy of the data is created.

See also

Object Management

See also

MediaBuffer::external

Returns:

A new MediaBuffer object. The caller is responsible for releasing the new object when it is not needed anymore.

Returns:

NULL if the object cannot be cloned because there’s not enough memory.