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

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

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

UnmanagedMediaBuffer

(

int

bufferSize = 0

)

Creates a MediaBuffer and optionally allocates a buffer storage.

Parameters

bufferSize

Specifies 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

Alloc()

bool Alloc	(	int	size,
		bool	keepData
	)

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

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

If an external storaged is attached it is automatically detached.

Append()

bool Append	(	IntPtr	data,
		int	dataSize
	)

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.

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

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

Attaches an external buffer storage.

Parameters

bufptr	A pointer to the buffer storage.
size	The buffer storage size.
setData	Specifies 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.

Clear()

void Clear

(

)

Clears existing data.

The operation does not change the buffer capacity.

Referenced by MediaInfo.PushUnmanaged().

Clone()

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

OutOfMemoryException

OutOfMemoryException if the object cannot be cloned because there's not enough memory.

See also

UnmanagedMediaBuffer.External

Referenced by MediaSample.Clone().

Detach()

IntPtr Detach

(

)

Detaches an external buffer storage.

Returns

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

Free()

void Free

(

)

Frees internal buffer storage.

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

Normalize()

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.

Release()

void Release

(

)

Releases the unmanaged buffer.

Equivalent to Dispose().

Referenced by Transcoder.PullUnmanaged().

Remove()

void Remove

(

int

dataSize

)

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.

The operation does not change the buffer capacity.

SetData()

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

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.

Property Documentation

BufPtr

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.

Capacity

int Capacity

get

Returns the size of the buffer in bytes.

Can be zero.

DataOffset

int DataOffset

get

The offset at which valid data starts in the buffer.

Ranges from 0 to Capacity-1.

DataPtr

IntPtr DataPtr

get

Returns a pointer to the first byte of data.

This is effectively the same as BufPtr + DataOffset.

DataSize

int DataSize

get

The size of the valid data in the buffer.

Ranges from 0 to Capacity.

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

External

bool External

get

Returns whether the MediaBuffer keeps and uses an external storage.

Returns

true if an external buffer storage is attached, false otherwise.

FreeLinearSpace

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.

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.