AVBlocks for .NET  2.3
Audio and Video Software Development Kit
UnmanagedMediaBuffer Class Reference

Unmanaged buffer for media data. More...

Inheritance diagram for UnmanagedMediaBuffer:

Public Member Functions

 UnmanagedMediaBuffer (int bufferSize=0)
 Creates a MediaBuffer and optionally allocates a buffer storage More...
 
bool Alloc (int size, bool keepData)
 Allocates internal buffer storage More...
 
bool Append (IntPtr data, int dataSize)
 Appends data to the end of the MediaBuffer data. More...
 
bool Attach (IntPtr bufptr, int size, bool setData)
 Attaches an external buffer storage More...
 
void Clear ()
 Clears existing data. More...
 
virtual object Clone ()
 Creates a deep copy this object. More...
 
IntPtr Detach ()
 Detaches an external buffer storage More...
 
void Dispose ()
 Disposes the UnmanagedMediaBuffer and reclaims the resources used by the object. More...
 
void Free ()
 Frees internal buffer storage More...
 
void Normalize ()
 Moves the existing data to the start of the buffer and maximizes the free linear space. More...
 
void Release ()
 Releases the unmanaged buffer. More...
 
void Remove (int dataSize)
 Removes data from the beginning of the MediaBuffer data. More...
 
bool SetData (int dataOffset, int dataSize)
 Sets the offset at which valid data starts in the buffer and the data size in bytes. More...
 

Properties

IntPtr BufPtr [get]
 Returns a pointer to the start of the buffer. More...
 
int Capacity [get]
 Returns the size of the buffer in bytes. More...
 
int DataOffset [get]
 The offset at which valid data starts in the buffer. More...
 
IntPtr DataPtr [get]
 Returns a pointer to the first byte of data. More...
 
int DataSize [get]
 The size of the valid data in the buffer. More...
 
bool External [get]
 Returns whether the MediaBuffer keeps and uses an external storage. More...
 
int FreeLinearSpace [get]
 Returns the free linear space that can be used to append data without normalization. More...
 
int FreeSpace [get]
 Returns the free space that can be used to append data without buffer reallocation. More...
 

Detailed Description

Unmanaged 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

UnmanagedMediaBuffer ( int  bufferSize = 0)

Creates a MediaBuffer and optionally allocates a buffer storage

Parameters
bufferSizeSpecifies the requested buffer size. If 0 the buffer is created without storage. Buffer storage can be attached (Attach), explicitly allocated (Alloc or automatically allocated when data is appended to the buffer (Append).

Member Function Documentation

bool Alloc ( int  size,
bool  keepData 
)

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
The allocation request succeeded. FALSE The allocation failed (out of memory).

If an external storaged is attached it is automatically detached.

bool Append ( IntPtr  data,
int  dataSize 
)

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.

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.

bool Attach ( IntPtr  bufptr,
int  size,
bool  setData 
)

Attaches an external buffer storage

Parameters
bufptrA pointer to the buffer storage.
sizeThe buffer storage size.
setDataSpecifies whether to autoset data with a size equal to the buffer size. If true the DataSize is equal to Capacity. If false DataSize is 0.
Returns
If true the buffer is attached succefully, false otherwise.

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

void Clear ( )

Clears existing data.

The operation does not change the buffer capacity.

Referenced by MediaInfo.PushUnmanaged().

virtual object Clone ( )
virtual

Creates a deep copy this object.

If MediaBuffer owns its internal buffer the internal buffer is copied into the cloned object.

If MediaBuffer uses an external / attached buffer only the reference to the external buffer is copied into the cloned object.

Returns
A new UnmanagedMediaBuffer instance which is a copy of the current object.
Exceptions
OutOfMemoryExceptionOutOfMemoryException if the object cannot be cloned because there's not enough memory.
See also
UnmanagedMediaBuffer.External

Referenced by MediaSample.Clone().

IntPtr Detach ( )

Detaches an external buffer storage

Returns
A pointer to the detached buffer storage. null if no external storage has been attached.
void Dispose ( )

Disposes the UnmanagedMediaBuffer and reclaims the resources used by the object.

void Free ( )

Frees internal buffer storage

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

void Normalize ( )

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

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.

void Release ( )

Releases the unmanaged buffer.

Equivalent to Dispose().

Referenced by Transcoder.Pull().

void Remove ( int  dataSize)

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.

The operation does not change the buffer capacity.

bool SetData ( int  dataOffset,
int  dataSize 
)

Sets the offset at which valid data starts in the buffer 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.

Property Documentation

IntPtr BufPtr
get

Returns a pointer to the start of the buffer.

It is guaranteed that the pointer is valid only when Capacity is greater than 0.

int Capacity
get

Returns the size of the buffer in bytes.

Can be zero.

int DataOffset
get

The offset at which valid data starts in the buffer.

Ranges from 0 to Capacity-1.

IntPtr DataPtr
get

Returns a pointer to the first byte of data.

This is effectively the same as BufPtr + DataOffset.

int DataSize
get

The size of the valid data in the buffer.

Ranges from 0 to Capacity.

Referenced by Transcoder.Push(), and MediaInfo.PushUnmanaged().

bool External
get

Returns whether the MediaBuffer keeps and uses an external storage.

Returns
true if an external buffer storage is attached, false otherwise.
int FreeLinearSpace
get

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

The free linear space starts at DataOffset + DataSize. Its size is equal to Capacity - DataSize - DataOffset. It is less than or equal to FreeSpace.

int FreeSpace
get

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

The free space starts at DataOffset + DataSize. Its size is Capacity - DataSize. It is greater than or equal to FreeLinearSpace.