AVBlocks for C++  2.1
Audio and Video Software Development Kit
MediaBuffer Class Referenceabstract

A buffer for media data. More...

Inheritance diagram for MediaBuffer:
Reference

Public Member Functions

virtual bool_t alloc (int32_t size, bool_t keepData)=0
 Allocates internal buffer storage. More...
 
virtual bool_t append (const void *data, int32_t dataSize)=0
 Appends data to the end of the MediaBuffer data. More...
 
virtual bool_t attach (void *buffer, int32_t size, bool_t setData)=0
 Attaches an external buffer storage. More...
 
virtual int32_t capacity () const =0
 Returns the size of the buffer in bytes. More...
 
virtual void clear ()=0
 Clears existing data. More...
 
virtual MediaBufferclone () const =0
 Creates a deep copy of this object. More...
 
virtual uint8_t * data () const =0
 Returns a pointer to the first byte of data. More...
 
virtual int32_t dataOffset () const =0
 Returns the offset at which valid data starts in the buffer. More...
 
virtual int32_t dataSize () const =0
 Returns the size of the valid data that in the buffer. More...
 
virtual uint8_t * detach ()=0
 Detaches an external buffer storage. More...
 
virtual bool_t external () const =0
 Returns whether the MediaBuffer uses an external data buffer. More...
 
virtual void free ()=0
 Frees internal buffer storage. More...
 
virtual int32_t freeLinearSpace () const =0
 Returns the free linear space that can be used to append data without normalization. More...
 
virtual int32_t freeSpace () const =0
 Returns the free space that can be used to append data without buffer reallocation. More...
 
virtual void normalize ()=0
 Moves the existing data to the start of the buffer amd maximizes the free linear space. More...
 
virtual void remove (int32_t dataSize)=0
 Removes data from the beginning of the MediaBuffer data. More...
 
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. More...
 
virtual uint8_t * start () const =0
 Returns a pointer to the start of the buffer. More...
 
- Public Member Functions inherited from Reference
virtual int32_t release () const =0
 Releases the instance. More...
 
virtual int32_t retain () const =0
 Retains the instance. More...
 
virtual int32_t retainCount () const =0
 Returns the current reference count. More...
 

Protected Member Functions

 ~MediaBuffer ()
 This object can be destroyed only by its implementation. More...
 

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 ( )
protected

This object can be destroyed only by its implementation.

The caller must use Reference::release.

See Also
Object Management

Member Function Documentation

virtual bool_t alloc ( int32_t  size,
bool_t  keepData 
)
pure virtual

Allocates internal buffer storage.

Parameters
sizeRequested 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.
keepDataSpecifies 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.
virtual bool_t append ( const void *  data,
int32_t  dataSize 
)
pure virtual

Appends data to the end of the MediaBuffer data.

Parameters
dataA pointer to the data that should be appended.
dataSizeThe 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.
virtual bool_t attach ( void *  buffer,
int32_t  size,
bool_t  setData 
)
pure virtual

Attaches an external buffer storage.

Parameters
bufferA pointer to the buffer storage.
sizeThe buffer size.
setDataSpecifies 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.
virtual int32_t capacity ( ) const
pure virtual

Returns the size of the buffer in bytes.

Returns
Buffer capacity. Can be zero.
virtual void clear ( )
pure virtual

Clears existing data.

Remarks
The operation does not change the buffer capacity.
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
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.
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.
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().
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.
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.
virtual void free ( )
pure virtual

Frees internal buffer storage.

Remarks
The function does nothing if an external storage is attached to the buffer.
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
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
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.
virtual void remove ( int32_t  dataSize)
pure virtual

Removes data from the beginning of the MediaBuffer data.

Parameters
dataSizeThe 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.
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
dataOffsetThe offset at which valid data starts in the buffer. Allowed values range from 0 to capacity()-1.
dataSizeThe 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 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.