A buffer for media data. More...

#include <av.h>

Inheritance diagram for MediaBuffer:

Public Member Functions
virtual bool_t	alloc (int32_t size, bool_t keepData)=0
	Allocates internal buffer storage.

virtual bool_t	append (const void *data, int32_t dataSize)=0
	Appends data to the end of the MediaBuffer data.

virtual bool_t	attach (void *buffer, int32_t size, bool_t setData)=0
	Attaches an external buffer storage.

virtual int32_t	capacity () const =0
	Returns the size of the buffer in bytes.

virtual void	clear ()=0
	Clears existing data.

virtual MediaBuffer *	clone () const =0
	Creates a deep copy of this object.

virtual uint8_t *	data () const =0
	Returns a pointer to the first byte of data.

virtual int32_t	dataOffset () const =0
	Returns the offset at which valid data starts in the buffer.

virtual int32_t	dataSize () const =0
	Returns the size of the valid data that in the buffer.

virtual uint8_t *	detach ()=0
	Detaches an external buffer storage.

virtual bool_t	external () const =0
	Returns whether the MediaBuffer uses an external data buffer.

virtual void	free ()=0
	Frees internal buffer storage.

virtual int32_t	freeLinearSpace () const =0
	Returns the free linear space that can be used to append data without normalization.

virtual int32_t	freeSpace () const =0
	Returns the free space that can be used to append data without buffer reallocation.

virtual void	normalize ()=0
	Moves the existing data to the start of the buffer amd maximizes the free linear space.

virtual void	remove (int32_t dataSize)=0
	Removes data from the beginning of the MediaBuffer data.

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.

virtual uint8_t *	start () const =0
	Returns a pointer to the start of the buffer.

Public Member Functions inherited from Reference
virtual int32_t	release () const =0
	Releases the instance.

virtual int32_t	retain () const =0
	Retains the instance.

virtual int32_t	retainCount () const =0
	Returns the current reference count.

Protected Member Functions
	~MediaBuffer ()
	This object can be destroyed only by its implementation.

Detailed Description

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.

Constructor & Destructor Documentation

◆ ~MediaBuffer()

~MediaBuffer ( )

protected

This object can be destroyed only by its implementation.

The caller must use Reference::release.

See also: Object Management

Member Function Documentation

◆ alloc()

virtual bool_t alloc	(	int32_t	size,
		bool_t	keepData
	)

pure virtual

Allocates internal buffer storage.

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).

Remarks: If an external storage is attached it is automatically detached.

◆ append()

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

pure virtual

Appends data to the end of the MediaBuffer data.

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.

Remarks: 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.

◆ attach()

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

pure virtual

Attaches an external buffer storage.

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.

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

◆ capacity()

virtual int32_t capacity ( ) const

pure virtual

Returns the size of the buffer in bytes.

Returns: Buffer capacity. Can be zero.

◆ clear()

virtual void clear ( )

pure virtual

Clears existing data.

Remarks: The operation does not change the buffer capacity.

◆ clone()

virtual MediaBuffer * clone ( ) const

pure virtual

Creates a deep copy of this object.

Returns: A new MediaBuffer object. The caller is responsible for releasing the new object when it is not needed anymore.; NULL if the object cannot be cloned because there's not enough memory.

Remarks: 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; MediaBuffer::external

◆ data()

virtual uint8_t * data ( ) const

pure virtual

Returns a pointer to the first byte of data.

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

Returns: A pointer to the data start.

◆ dataOffset()

virtual int32_t dataOffset ( ) const

pure virtual

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

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

◆ dataSize()

virtual int32_t dataSize ( ) const

pure virtual

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

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

◆ detach()

virtual uint8_t * detach ( )

pure virtual

Detaches an external buffer storage.

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

◆ external()

virtual bool_t external ( ) const

pure virtual

Returns whether the MediaBuffer uses an external data buffer.

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

◆ free()

virtual void free ( )

pure virtual

Frees internal buffer storage.

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

◆ freeLinearSpace()

virtual int32_t freeLinearSpace ( ) const

pure virtual

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

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

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

See also: freeSpace

◆ freeSpace()

virtual int32_t freeSpace ( ) const

pure virtual

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

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

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

See also: freeLinearSpace

◆ normalize()

virtual void normalize ( )

pure virtual

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

Remarks: 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.

◆ remove()

virtual void remove ( int32_t dataSize )

pure virtual

Removes data from the beginning of the MediaBuffer data.

Parameters

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

Returns: TRUE The operation is successful, FALSE otherwise.

Remarks: The operation does not change the buffer capacity.

◆ setData()

virtual bool_t setData	(	int32_t	dataOffset,
		int32_t	dataSize
	)

pure virtual

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.

◆ start()

virtual uint8_t * start ( ) const

pure virtual

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.

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~MediaBuffer()

Member Function Documentation

◆ alloc()

◆ append()

◆ attach()

◆ capacity()

◆ clear()

◆ clone()

◆ data()

◆ dataOffset()

◆ dataSize()

◆ detach()

◆ external()

◆ free()

◆ freeLinearSpace()

◆ freeSpace()

◆ normalize()

◆ remove()

◆ setData()

◆ start()