Data blocks

Blocks of binary data. More...

Collaboration diagram for Data blocks:

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

Files
file	vlc_block.h
	Data block definition and functions.

Data Structures
struct	vlc_block_callbacks
struct	block_t

Macros
#define	BLOCK_FLAG_DISCONTINUITY   0x0001
	The content doesn't follow the last block, possible some blocks in between have been lost. More...
#define	BLOCK_FLAG_TYPE_I   0x0002
	Intra frame. More...
#define	BLOCK_FLAG_TYPE_P   0x0004
	Inter frame with backward reference only. More...
#define	BLOCK_FLAG_TYPE_B   0x0008
	Inter frame with backward and forward reference. More...
#define	BLOCK_FLAG_TYPE_PB   0x0010
	For inter frame when you don't know the real type. More...
#define	BLOCK_FLAG_HEADER   0x0020
	Warn that this block is a header one. More...
#define	BLOCK_FLAG_END_OF_SEQUENCE   0x0040
	This block contains the last part of a sequence. More...
#define	BLOCK_FLAG_CLOCK   0x0080
	This block contains a clock reference. More...
#define	BLOCK_FLAG_SCRAMBLED   0x0100
	This block is scrambled. More...
#define	BLOCK_FLAG_PREROLL   0x0200
	This block has to be decoded but not be displayed. More...
#define	BLOCK_FLAG_CORRUPTED   0x0400
	This block is corrupted and/or there is data loss. More...
#define	BLOCK_FLAG_AU_END   0x0800
	This block is last of its access unit. More...
#define	BLOCK_FLAG_TOP_FIELD_FIRST   0x1000
	This block contains an interlaced picture with top field stored first. More...
#define	BLOCK_FLAG_BOTTOM_FIELD_FIRST   0x2000
	This block contains an interlaced picture with bottom field stored first. More...
#define	BLOCK_FLAG_SINGLE_FIELD   0x4000
	This block contains a single field from interlaced picture. More...
#define	BLOCK_FLAG_INTERLACED_MASK   (BLOCK_FLAG_TOP_FIELD_FIRST|BLOCK_FLAG_BOTTOM_FIELD_FIRST|BLOCK_FLAG_SINGLE_FIELD)
	This block contains an interlaced picture. More...
#define	BLOCK_FLAG_TYPE_MASK   (BLOCK_FLAG_TYPE_I|BLOCK_FLAG_TYPE_P|BLOCK_FLAG_TYPE_B|BLOCK_FLAG_TYPE_PB)
#define	BLOCK_FLAG_CORE_PRIVATE_MASK   0x00ff0000
#define	BLOCK_FLAG_CORE_PRIVATE_SHIFT   16
#define	BLOCK_FLAG_PRIVATE_MASK   0xff000000
#define	BLOCK_FLAG_PRIVATE_SHIFT   24
#define	block_cleanup_push(block)   vlc_cleanup_push (block_Cleanup, block)

Functions
block_t *	block_Init (block_t *block, const struct vlc_block_callbacks *cbs, void *base, size_t length)
	Initializes a custom block. More...
block_t *	block_Alloc (size_t size)
	Allocates a block. More...
block_t *	block_TryRealloc (block_t *, ssize_t pre, size_t body)
block_t *	block_Realloc (block_t *, ssize_t pre, size_t body)
	Reallocates a block. More...
void	block_Release (block_t *block)
	Releases a block. More...
static void	block_CopyProperties (block_t *dst, const block_t *src)
static block_t *	block_Duplicate (const block_t *p_block)
	Duplicates a block. More...
block_t *	block_heap_Alloc (void *, size_t)
	Wraps heap in a block. More...
block_t *	block_mmap_Alloc (void *addr, size_t length)
	Wraps a memory mapping in a block. More...
block_t *	block_shm_Alloc (void *addr, size_t length)
	Wraps a System V memory segment in a block. More...
block_t *	block_File (int fd, bool write)
	Maps a file handle in memory. More...
block_t *	block_FilePath (const char *, bool write)
	Maps a file in memory. More...
static void	block_Cleanup (void *block)

Detailed Description

Blocks of binary data.

block_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

block_cleanup_push

#define block_cleanup_push

(

block

)

vlc_cleanup_push (block_Cleanup, block)

Referenced by block_File().

BLOCK_FLAG_AU_END

#define BLOCK_FLAG_AU_END   0x0800

This block is last of its access unit.

BLOCK_FLAG_BOTTOM_FIELD_FIRST

#define BLOCK_FLAG_BOTTOM_FIELD_FIRST   0x2000

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

BLOCK_FLAG_CLOCK

#define BLOCK_FLAG_CLOCK   0x0080

This block contains a clock reference.

BLOCK_FLAG_CORE_PRIVATE_MASK

#define BLOCK_FLAG_CORE_PRIVATE_MASK   0x00ff0000

BLOCK_FLAG_CORE_PRIVATE_SHIFT

#define BLOCK_FLAG_CORE_PRIVATE_SHIFT   16

BLOCK_FLAG_CORRUPTED

#define BLOCK_FLAG_CORRUPTED   0x0400

This block is corrupted and/or there is data loss.

Referenced by DecoderUpdatePreroll(), and EsOutSend().

BLOCK_FLAG_DISCONTINUITY

#define BLOCK_FLAG_DISCONTINUITY   0x0001

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

Referenced by aout_DecPlay(), DecoderUpdatePreroll(), EsOutSend(), sout_InputSendBuffer(), and vlc_input_decoder_Decode().

BLOCK_FLAG_END_OF_SEQUENCE

#define BLOCK_FLAG_END_OF_SEQUENCE   0x0040

This block contains the last part of a sequence.

BLOCK_FLAG_HEADER

#define BLOCK_FLAG_HEADER   0x0020

Warn that this block is a header one.

BLOCK_FLAG_INTERLACED_MASK

#define BLOCK_FLAG_INTERLACED_MASK   (BLOCK_FLAG_TOP_FIELD_FIRST|BLOCK_FLAG_BOTTOM_FIELD_FIRST|BLOCK_FLAG_SINGLE_FIELD)

This block contains an interlaced picture.

BLOCK_FLAG_PREROLL

#define BLOCK_FLAG_PREROLL   0x0200

This block has to be decoded but not be displayed.

Referenced by DecoderUpdatePreroll(), and EsOutSend().

BLOCK_FLAG_PRIVATE_MASK

#define BLOCK_FLAG_PRIVATE_MASK   0xff000000

BLOCK_FLAG_PRIVATE_SHIFT

#define BLOCK_FLAG_PRIVATE_SHIFT   24

BLOCK_FLAG_SCRAMBLED

#define BLOCK_FLAG_SCRAMBLED   0x0100

This block is scrambled.

BLOCK_FLAG_SINGLE_FIELD

#define BLOCK_FLAG_SINGLE_FIELD   0x4000

This block contains a single field from interlaced picture.

BLOCK_FLAG_TOP_FIELD_FIRST

#define BLOCK_FLAG_TOP_FIELD_FIRST   0x1000

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

BLOCK_FLAG_TYPE_B

#define BLOCK_FLAG_TYPE_B   0x0008

Inter frame with backward and forward reference.

BLOCK_FLAG_TYPE_I

#define BLOCK_FLAG_TYPE_I   0x0002

Intra frame.

Referenced by httpd_StreamSend().

BLOCK_FLAG_TYPE_MASK

#define BLOCK_FLAG_TYPE_MASK   (BLOCK_FLAG_TYPE_I|BLOCK_FLAG_TYPE_P|BLOCK_FLAG_TYPE_B|BLOCK_FLAG_TYPE_PB)

BLOCK_FLAG_TYPE_P

#define BLOCK_FLAG_TYPE_P   0x0004

Inter frame with backward reference only.

BLOCK_FLAG_TYPE_PB

#define BLOCK_FLAG_TYPE_PB   0x0010

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

Function Documentation

block_Alloc()

block_t* block_Alloc

(

size_t

size

)

Allocates a block.

Creates a new block with the requested size. The block must be released with block_Release().

Parameters

size	size in bytes (possibly zero)

Returns

the created block, or NULL on memory error.

References BLOCK_ALIGN, block_Init(), BLOCK_PADDING, block_t::i_buffer, block_t::p_buffer, static_assert, and unlikely.

Referenced by aout_DecSilence(), block_ChainGather(), block_Duplicate(), block_File(), block_TryRealloc(), bo_init(), decoder_NewAudioBuffer(), TsStoragePopCmd(), vlc_chunked_read(), vlc_h1_stream_read(), vlc_stream_Block(), vlc_stream_fifo_Write(), vlc_stream_Peek(), and vlc_stream_ReadBlock().

block_Cleanup()

static void block_Cleanup ( void *  block )

inlinestatic

References block_Release().

block_CopyProperties()

static void block_CopyProperties ( block_t *  dst, const block_t *  src  )

inlinestatic

References block_t::i_dts, block_t::i_flags, block_t::i_length, block_t::i_nb_samples, block_t::i_pts, and VLC_USED.

Referenced by block_Duplicate().

block_Duplicate()

static block_t* block_Duplicate ( const block_t *  p_block )

inlinestatic

Duplicates a block.

Creates a writeable duplicate of a block.

Returns

the duplicate on success, NULL on error.

References block_Alloc(), block_CopyProperties(), block_File(), block_FilePath(), block_heap_Alloc(), block_mmap_Alloc(), block_shm_Alloc(), block_t::i_buffer, block_t::p_buffer, VLC_API, VLC_MALLOC, and VLC_USED.

Referenced by DecoderPlayCc(), and EsOutSend().

block_File()

block_t* block_File	(	int	fd,
		bool	write
	)

Maps a file handle in memory.

Loads a file into a block 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 block with the file content at p_buffer, and file length at i_buffer (release it with block_Release()), or NULL upon error (see errno).

References block_Alloc(), block_cleanup_push, block_mmap_Alloc(), block_Release(), block_t::p_buffer, S_TYPEISSHM, and vlc_cleanup_pop.

Referenced by block_Duplicate(), and block_FilePath().

block_FilePath()

block_t* block_FilePath	(	const char *	,
		bool	write
	)

Maps a file in memory.

Loads a file into a block of memory from a path to the file. See also block_File().

Parameters

write

If true, request a read/write private mapping. If false, request a read-only potentially shared mapping.

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

Referenced by block_Duplicate().

block_heap_Alloc()

block_t* block_heap_Alloc	(	void *	,
		size_t
	)

Wraps heap in a block.

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

When block_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 block_t pointer.

References block_Init(), block_mmap_Alloc(), vlc_block_callbacks::free, block_t::i_buffer, block_t::i_size, block_t::p_buffer, and block_t::p_start.

Referenced by block_Duplicate(), and vlc_h2_stream_read().

block_Init()

block_t* block_Init	(	block_t *	block,
		const struct vlc_block_callbacks *	cbs,
		void *	base,
		size_t	length
	)

Initializes a custom block.

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

Normally, blocks are allocated and initialized by block_Alloc() instead.

Parameters

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

Returns

block (this function cannot fail)

block_mmap_Alloc()

block_t* block_mmap_Alloc	(	void *	addr,
		size_t	length
	)

Wraps a memory mapping in a block.

Creates a block_t from a virtual address memory mapping (mmap). This is provided by LibVLC so that mmap blocks 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).

References block_Init(), block_shm_Alloc(), vlc_block_callbacks::free, block_t::p_start, and unlikely.

Referenced by block_Duplicate(), block_File(), and block_heap_Alloc().

block_Realloc()

block_t* block_Realloc	(	block_t *	,
		ssize_t	pre,
		size_t	body
	)

Reallocates a block.

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

Parameters

pre	count of bytes to prepend if positive, count of leading bytes to discard if negative
body	new bytes size of the block

Returns

the reallocated block on succes, NULL on error.

Note

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

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

On error, the block is discarded. To avoid that, use block_TryRealloc() instead.

References block_Release(), and block_TryRealloc().

Referenced by bo_extend().

block_Release()

void block_Release

(

block_t *

block

)

Releases a block.

This function works for any block_t block, regardless of the way it was allocated.

Note

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

Parameters

block

block to release (cannot be NULL)

References block_Check(), block_t::cbs, vlc_block_callbacks::free, and block_t::p_next.

Referenced by aout_DecPlay(), aout_FiltersPlay(), block_BytestreamFlush(), block_ChainRelease(), block_Cleanup(), block_File(), block_Realloc(), block_TryRealloc(), bo_deinit(), CmdCleanSend(), CmdExecuteSend(), decoder_QueueCc(), DecoderPlayCc(), DecoderThread_DecodeBlock(), DecoderThread_ProcessInput(), DecoderUpdatePreroll(), EsOutSend(), ImageRead(), ImageWriteUrl(), ModuleThread_PlayAudio(), ModuleThread_QueueCc(), stream_CommonDelete(), TsStoragePushCmd(), vlc_chunked_read(), vlc_h1_stream_read(), vlc_stream_Block(), vlc_stream_CopyBlock(), vlc_stream_fifo_Queue(), vlc_stream_ReadBlock(), vlc_stream_Seek(), vlc_stream_vaControl(), and VoutSaveSnapshot().

block_shm_Alloc()

block_t* block_shm_Alloc	(	void *	addr,
		size_t	length
	)

Wraps a System V memory segment in a block.

Creates a block_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).

References count.

Referenced by block_Duplicate(), and block_mmap_Alloc().

block_TryRealloc()

block_t* block_TryRealloc	(	block_t *	,
		ssize_t	pre,
		size_t	body
	)

References block_Alloc(), block_Check(), block_Release(), BlockMetaCopy(), block_t::i_buffer, block_t::i_size, block_t::p_buffer, and block_t::p_start.

Referenced by block_Realloc(), and vlc_stream_Peek().