Frames

Frames of binary data. More...

Collaboration diagram for Frames:

Modules
	Frame chain
	Block FIFO
	Thread-safe block queue functions.

Files
file	vlc_frame.h
	Frames definition and functions.

Data Structures
struct	vlc_frame_callbacks
struct	vlc_frame_t

Macros
#define	VLC_FRAME_FLAG_DISCONTINUITY   0x0001
	The content doesn't follow the last frame, possible some frames in between have been lost.
#define	VLC_FRAME_FLAG_TYPE_I   0x0002
	Intra frame.
#define	VLC_FRAME_FLAG_TYPE_P   0x0004
	Inter frame with backward reference only.
#define	VLC_FRAME_FLAG_TYPE_B   0x0008
	Inter frame with backward and forward reference.
#define	VLC_FRAME_FLAG_TYPE_PB   0x0010
	For inter frame when you don't know the real type.
#define	VLC_FRAME_FLAG_HEADER   0x0020
	Warn that this frame is a header one.
#define	VLC_FRAME_FLAG_END_OF_SEQUENCE   0x0040
	This frame contains the last part of a sequence
#define	VLC_FRAME_FLAG_SCRAMBLED   0x0100
	This frame is scrambled.
#define	VLC_FRAME_FLAG_PREROLL   0x0200
	This frame has to be decoded but not be displayed.
#define	VLC_FRAME_FLAG_CORRUPTED   0x0400
	This frame is corrupted and/or there is data loss
#define	VLC_FRAME_FLAG_AU_END   0x0800
	This frame is last of its access unit.
#define	VLC_FRAME_FLAG_TOP_FIELD_FIRST   0x1000
	This frame contains an interlaced picture with top field stored first.
#define	VLC_FRAME_FLAG_BOTTOM_FIELD_FIRST   0x2000
	This frame contains an interlaced picture with bottom field stored first.
#define	VLC_FRAME_FLAG_SINGLE_FIELD   0x4000
	This frame contains a single field from interlaced picture.
#define	VLC_FRAME_FLAG_INTERLACED_MASK    (VLC_FRAME_FLAG_TOP_FIELD_FIRST|VLC_FRAME_FLAG_BOTTOM_FIELD_FIRST|VLC_FRAME_FLAG_SINGLE_FIELD)
	This frame contains an interlaced picture.
#define	VLC_FRAME_FLAG_TYPE_MASK    (VLC_FRAME_FLAG_TYPE_I|VLC_FRAME_FLAG_TYPE_P|VLC_FRAME_FLAG_TYPE_B|VLC_FRAME_FLAG_TYPE_PB)
#define	VLC_FRAME_FLAG_CORE_PRIVATE_MASK   0x00ff0000
#define	VLC_FRAME_FLAG_CORE_PRIVATE_SHIFT   16
#define	VLC_FRAME_FLAG_PRIVATE_MASK   0xff000000
#define	VLC_FRAME_FLAG_PRIVATE_SHIFT   24
#define	vlc_frame_cleanup_push(frame)   vlc_cleanup_push (vlc_frame_Cleanup, frame)

Typedefs
typedef struct vlc_frame_t	vlc_frame_t

Functions
vlc_frame_t *	vlc_frame_Init (vlc_frame_t *frame, const struct vlc_frame_callbacks *cbs, void *base, size_t length)
	Initializes a custom frame.
vlc_frame_t *	vlc_frame_New (const struct vlc_frame_callbacks *cbs, void *base, size_t length)
	Creates a custom frame.
vlc_frame_t *	vlc_frame_Alloc (size_t size)
	Allocates a frame.
vlc_frame_t *	vlc_frame_TryRealloc (vlc_frame_t *, ssize_t pre, size_t body)
vlc_frame_t *	vlc_frame_Realloc (vlc_frame_t *frame, ssize_t pre, size_t body)
	Reallocates a frame.
void	vlc_frame_Release (vlc_frame_t *frame)
	Releases a frame.
int	vlc_frame_AttachAncillary (vlc_frame_t *frame, struct vlc_ancillary *ancillary)
	Attach an ancillary to the frame.
struct vlc_ancillary *	vlc_frame_GetAncillary (vlc_frame_t *frame, vlc_ancillary_id id)
	Return the ancillary identified by an ID.
void	vlc_frame_CopyProperties (vlc_frame_t *dst, const vlc_frame_t *src)
	Copy frame properties from src to dst.
static vlc_frame_t *	vlc_frame_Duplicate (const vlc_frame_t *frame)
	Duplicates a frame.
vlc_frame_t *	vlc_frame_heap_Alloc (void *addr, size_t length)
	Wraps heap in a frame.
vlc_frame_t *	vlc_frame_mmap_Alloc (void *addr, size_t length)
	Wraps a memory mapping in a frame.
vlc_frame_t *	vlc_frame_shm_Alloc (void *addr, size_t length)
	Wraps a System V memory segment in a frame.
vlc_frame_t *	vlc_frame_File (int fd, bool write)
	Maps a file handle in memory.
vlc_frame_t *	vlc_frame_FilePath (const char *path, bool write)
	Maps a file in memory.
static void	vlc_frame_Cleanup (void *frame)

Detailed Description

Frames of binary data.

vlc_frame_t is a generic structure to represent a binary blob within VLC. The primary goal of the structure is to avoid memory copying as data is passed around. It is notably used between the Demultiplexer, the packetizer (if present) and the Decoder, and for audio, between the Decoder, the audio filters, and the Audio output.

Macro Definition Documentation

vlc_frame_cleanup_push

#define vlc_frame_cleanup_push

(

frame

)

vlc_cleanup_push (vlc_frame_Cleanup, frame)

VLC_FRAME_FLAG_AU_END

#define VLC_FRAME_FLAG_AU_END   0x0800

This frame is last of its access unit.

VLC_FRAME_FLAG_BOTTOM_FIELD_FIRST

#define VLC_FRAME_FLAG_BOTTOM_FIELD_FIRST   0x2000

This frame contains an interlaced picture with bottom field stored first.

VLC_FRAME_FLAG_CORE_PRIVATE_MASK

#define VLC_FRAME_FLAG_CORE_PRIVATE_MASK   0x00ff0000

VLC_FRAME_FLAG_CORE_PRIVATE_SHIFT

#define VLC_FRAME_FLAG_CORE_PRIVATE_SHIFT   16

VLC_FRAME_FLAG_CORRUPTED

#define VLC_FRAME_FLAG_CORRUPTED   0x0400

This frame is corrupted and/or there is data loss

VLC_FRAME_FLAG_DISCONTINUITY

#define VLC_FRAME_FLAG_DISCONTINUITY   0x0001

The content doesn't follow the last frame, possible some frames in between have been lost.

VLC_FRAME_FLAG_END_OF_SEQUENCE

#define VLC_FRAME_FLAG_END_OF_SEQUENCE   0x0040

This frame contains the last part of a sequence

VLC_FRAME_FLAG_HEADER

#define VLC_FRAME_FLAG_HEADER   0x0020

Warn that this frame is a header one.

VLC_FRAME_FLAG_INTERLACED_MASK

#define VLC_FRAME_FLAG_INTERLACED_MASK    (VLC_FRAME_FLAG_TOP_FIELD_FIRST|VLC_FRAME_FLAG_BOTTOM_FIELD_FIRST|VLC_FRAME_FLAG_SINGLE_FIELD)

This frame contains an interlaced picture.

VLC_FRAME_FLAG_PREROLL

#define VLC_FRAME_FLAG_PREROLL   0x0200

This frame has to be decoded but not be displayed.

VLC_FRAME_FLAG_PRIVATE_MASK

#define VLC_FRAME_FLAG_PRIVATE_MASK   0xff000000

VLC_FRAME_FLAG_PRIVATE_SHIFT

#define VLC_FRAME_FLAG_PRIVATE_SHIFT   24

VLC_FRAME_FLAG_SCRAMBLED

#define VLC_FRAME_FLAG_SCRAMBLED   0x0100

This frame is scrambled.

VLC_FRAME_FLAG_SINGLE_FIELD

#define VLC_FRAME_FLAG_SINGLE_FIELD   0x4000

This frame contains a single field from interlaced picture.

VLC_FRAME_FLAG_TOP_FIELD_FIRST

#define VLC_FRAME_FLAG_TOP_FIELD_FIRST   0x1000

This frame contains an interlaced picture with top field stored first.

VLC_FRAME_FLAG_TYPE_B

#define VLC_FRAME_FLAG_TYPE_B   0x0008

Inter frame with backward and forward reference.

VLC_FRAME_FLAG_TYPE_I

#define VLC_FRAME_FLAG_TYPE_I   0x0002

Intra frame.

VLC_FRAME_FLAG_TYPE_MASK

#define VLC_FRAME_FLAG_TYPE_MASK    (VLC_FRAME_FLAG_TYPE_I|VLC_FRAME_FLAG_TYPE_P|VLC_FRAME_FLAG_TYPE_B|VLC_FRAME_FLAG_TYPE_PB)

VLC_FRAME_FLAG_TYPE_P

#define VLC_FRAME_FLAG_TYPE_P   0x0004

Inter frame with backward reference only.

VLC_FRAME_FLAG_TYPE_PB

#define VLC_FRAME_FLAG_TYPE_PB   0x0010

For inter frame when you don't know the real type.

Typedef Documentation

vlc_frame_t

typedef struct vlc_frame_t vlc_frame_t

Function Documentation

vlc_frame_Alloc()

vlc_frame_t * vlc_frame_Alloc

(

size_t

size

)

Allocates a frame.

Creates a new frame with the requested size. The frame must be released with vlc_frame_Release().

Parameters

size	size in bytes (possibly zero)

Returns

the created frame, or NULL on memory error.

References aligned_alloc(), vlc_frame_t::i_buffer, likely, vlc_frame_t::p_buffer, unlikely, VLC_FRAME_ALIGN, vlc_frame_heap_Alloc(), and VLC_FRAME_PADDING.

Referenced by vlc_frame_ChainGather(), vlc_frame_Duplicate(), vlc_frame_File(), and vlc_frame_ReallocDup().

vlc_frame_AttachAncillary()

int vlc_frame_AttachAncillary	(	vlc_frame_t *	frame,
		struct vlc_ancillary *	ancillary
	)

Attach an ancillary to the frame.

Warning

the ancillary will be released only if the frame is allocated from a vlc_frame Alloc function (vlc_frame_Alloc(), vlc_frame_mmap_Alloc()...).

Note

Several ancillaries can be attached to a frame, but if two ancillaries are identified by the same ID, only the last one take precedence.

Parameters

frame	the frame to attach an ancillary
ancillary	ancillary that will be held by the frame, can't be NULL

Returns

VLC_SUCCESS in case of success, VLC_ENOMEM in case of alloc error

References vlc_frame_t::priv_ancillaries, and vlc_ancillary_array_Insert().

vlc_frame_Cleanup()

static void vlc_frame_Cleanup ( void *  frame )

inlinestatic

References vlc_frame_Release().

vlc_frame_CopyProperties()

void vlc_frame_CopyProperties	(	vlc_frame_t *	dst,
		const vlc_frame_t *	src
	)

Copy frame properties from src to dst.

Copy i_flags, i_nb_samples, i_dts, i_pts, and i_length.

Note

if src has an ancillary, the ancillary will be copied and refcounted to dst.

Parameters

dst	the frame to copy properties into
src	the frame to copy properties from

Referenced by vlc_frame_Duplicate().

vlc_frame_Duplicate()

static vlc_frame_t * vlc_frame_Duplicate ( const vlc_frame_t *  frame )

inlinestatic

Duplicates a frame.

Creates a writeable duplicate of a frame.

Returns

the duplicate on success, NULL on error.

References vlc_frame_t::i_buffer, vlc_frame_t::p_buffer, vlc_frame_Alloc(), and vlc_frame_CopyProperties().

vlc_frame_File()

vlc_frame_t * vlc_frame_File	(	int	fd,
		bool	write
	)

Maps a file handle in memory.

Loads a file into a frame of memory through a file descriptor. If possible a private file mapping is created. Otherwise, the file is read normally. This function is a cancellation point.

Note

On 32-bits platforms, this function will not work for very large files, due to memory space constraints.

Parameters

fd	file descriptor to load from
write	If true, request a read/write private mapping. If false, request a read-only potentially shared mapping.

Returns

a new frame with the file content at p_buffer, and file length at i_buffer (release it with vlc_frame_Release()), or NULL upon error (see errno).

References vlc_frame_t::p_buffer, S_TYPEISSHM, unlikely, vlc_cleanup_pop, vlc_cleanup_push, vlc_frame_Alloc(), vlc_frame_cleanup_push, vlc_frame_mmap_Alloc(), vlc_frame_Release(), and vlc_testcancel().

Referenced by vlc_frame_FilePath().

vlc_frame_FilePath()

vlc_frame_t * vlc_frame_FilePath	(	const char *	path,
		bool	write
	)

Maps a file in memory.

Loads a file into a frame of memory from a path to the file. See also vlc_frame_File().

Parameters

path	the file path to load the memory block from
write	If true, request a read/write private mapping. If false, request a read-only potentially shared mapping.

References vlc_close(), vlc_frame_File(), and vlc_open().

vlc_frame_GetAncillary()

struct vlc_ancillary * vlc_frame_GetAncillary	(	vlc_frame_t *	frame,
		vlc_ancillary_id	id
	)

Return the ancillary identified by an ID.

Parameters

frame	the frame to read the ancillary from
id	id of ancillary to request

Returns

the ancillary or NULL if the ancillary for that particular id is not present

References vlc_frame_t::priv_ancillaries, and vlc_ancillary_array_Get().

vlc_frame_heap_Alloc()

vlc_frame_t * vlc_frame_heap_Alloc	(	void *	addr,
		size_t	length
	)

Wraps heap in a frame.

Creates a vlc_frame_t out of an existing heap allocation. This is provided by LibVLC so that manually heap-allocated frames can safely be deallocated even after the origin plugin has been unloaded from memory.

When vlc_frame_Release() is called, VLC will free() the specified pointer.

Parameters

addr	base address of the heap allocation (will be free()'d)
length	bytes length of the heap allocation

Returns

NULL in case of error (ptr free()'d in that case), or a valid vlc_frame_t pointer.

References vlc_frame_callbacks::free, unlikely, vlc_frame_heap_cbs, and vlc_frame_New().

Referenced by vlc_frame_Alloc().

vlc_frame_Init()

vlc_frame_t * vlc_frame_Init	(	vlc_frame_t *	frame,
		const struct vlc_frame_callbacks *	cbs,
		void *	base,
		size_t	length
	)

Initializes a custom frame.

This function initialize a frame of timed data allocated by custom means. This allows passing data without copying even if the data has been allocated with unusual means or outside of LibVLC.

Normally, frames are allocated and initialized by vlc_frame_Alloc() instead.

Parameters

frame	allocated frame structure to initialize
cbs	structure of custom callbacks to handle the frame [IN]
base	start address of the frame data
length	byte length of the frame data

Returns

frame (this function cannot fail)

vlc_frame_mmap_Alloc()

vlc_frame_t * vlc_frame_mmap_Alloc	(	void *	addr,
		size_t	length
	)

Wraps a memory mapping in a frame.

Creates a vlc_frame_t from a virtual address memory mapping (mmap). This is provided by LibVLC so that mmap frames can safely be deallocated even after the allocating plugin has been unloaded from memory.

Parameters

addr	base address of the mapping (as returned by mmap)
length	length (bytes) of the mapping (as passed to mmap)

Returns

NULL if addr is MAP_FAILED, or an error occurred (in the later case, munmap(addr, length) is invoked before returning).

Referenced by vlc_frame_File().

vlc_frame_New()

vlc_frame_t * vlc_frame_New	(	const struct vlc_frame_callbacks *	cbs,
		void *	base,
		size_t	length
	)

Creates a custom frame.

This function initialize a frame of timed data allocated by custom means. This allows passing data without copying even if the data has been allocated with unusual means or outside of LibVLC.

Normally, frames are allocated and initialized by vlc_frame_Alloc() instead.

Parameters

cbs	structure of custom callbacks to handle the frame [IN]
base	start address of the frame data
length	byte length of the frame data

Returns

the created frame, or NULL on memory error.

References unlikely, and vlc_frame_Init().

Referenced by vlc_frame_heap_Alloc().

vlc_frame_Realloc()

vlc_frame_t * vlc_frame_Realloc	(	vlc_frame_t *	frame,
		ssize_t	pre,
		size_t	body
	)

Reallocates a frame.

This function expands, shrinks or moves a data frame. In many cases, this function can return without any memory allocation by reusing spare buffer space. Otherwise, a new frame is created and data is copied.

Parameters

frame	the frame to realloc, which will be freed after the call to this function
pre	count of bytes to prepend if positive, count of leading bytes to discard if negative
body	new bytes size of the frame

Returns

the reallocated frame on success, NULL on error.

Note

Skipping leading bytes can be achieved directly by subtracting from vlc_frame_t.i_buffer and adding vlc_frame_t.p_buffer.

Discard trailing bytes can be achieved directly by subtracting from vlc_frame_t.i_buffer.

On error, the frame is discarded. To avoid that, use vlc_frame_TryRealloc() instead.

References vlc_frame_Release(), and vlc_frame_TryRealloc().

vlc_frame_Release()

void vlc_frame_Release

(

vlc_frame_t *

frame

)

Releases a frame.

This function works for any vlc_frame_t frame, regardless of the way it was allocated.

Note

If the frame is in a chain, this function does not release any subsequent frame in the chain. Use vlc_frame_ChainRelease() for that purpose.

Parameters

frame

frame to release (cannot be NULL)

References vlc_frame_t::cbs, vlc_frame_callbacks::free, vlc_frame_t::p_next, vlc_frame_t::priv_ancillaries, vlc_ancillary_array_Clear(), and vlc_frame_Check().

Referenced by DecoderPlayCcLocked(), vlc_frame_ChainRelease(), vlc_frame_Cleanup(), vlc_frame_File(), vlc_frame_Realloc(), and vlc_frame_ReallocDup().

vlc_frame_shm_Alloc()

vlc_frame_t * vlc_frame_shm_Alloc	(	void *	addr,
		size_t	length
	)

Wraps a System V memory segment in a frame.

Creates a vlc_frame_t from a System V shared memory segment (shmget()). This is provided by LibVLC so that segments can safely be deallocated even after the allocating plugin has been unloaded from memory.

Parameters

addr	base address of the segment (as returned by shmat())
length	length (bytes) of the segment (as passed to shmget())

Returns

NULL if an error occurred (in that case, shmdt(addr) is invoked before returning NULL).

vlc_frame_TryRealloc()

vlc_frame_t * vlc_frame_TryRealloc	(	vlc_frame_t *	frame,
		ssize_t	pre,
		size_t	body
	)

References vlc_frame_t::i_buffer, vlc_frame_t::i_size, vlc_frame_t::p_buffer, vlc_frame_t::p_start, vlc_frame_Check(), and vlc_frame_ReallocDup().

Referenced by vlc_frame_Realloc().