Buffers

Buffers describe the data and metadata that is exchanged between ports of a node. More...

Files
file	alloc.h
	spa/buffer/alloc.h
file	buffer.h
	spa/buffer/buffer.h
file	meta.h
	spa/buffer/meta.h
file	type-info.h
	spa/buffer/type-info.h

Data Structures
struct	spa_buffer_alloc_info
	information about the buffer layout More...
struct	spa_chunk
	Chunk of memory, can change for each buffer. More...
struct	spa_data
	Data for a buffer this stays constant for a buffer. More...
struct	spa_buffer
	A Buffer. More...
struct	spa_meta
	A metadata element. More...
struct	spa_meta_header
	Describes essential buffer header metadata such as flags and timestamps. More...
struct	spa_meta_region
	metadata structure for Region or an array of these for RegionArray More...
struct	spa_meta_bitmap
	Bitmap information. More...
struct	spa_meta_cursor
	Cursor information. More...
struct	spa_meta_control
	a timed set of events associated with the buffer More...
struct	spa_meta_busy
	a busy counter for the buffer More...
struct	spa_meta_videotransform
	a transformation of the buffer More...

Enumerations
enum	spa_data_type {   SPA_DATA_Invalid , SPA_DATA_MemPtr , SPA_DATA_MemFd , SPA_DATA_DmaBuf ,   SPA_DATA_MemId , _SPA_DATA_LAST }
enum	spa_meta_type {   SPA_META_Invalid , SPA_META_Header , SPA_META_VideoCrop , SPA_META_VideoDamage ,   SPA_META_Bitmap , SPA_META_Cursor , SPA_META_Control , SPA_META_Busy ,   SPA_META_VideoTransform , _SPA_META_LAST }
enum	spa_meta_videotransform_value {   SPA_META_TRANSFORMATION_None = 0 , SPA_META_TRANSFORMATION_90 , SPA_META_TRANSFORMATION_180 , SPA_META_TRANSFORMATION_270 ,   SPA_META_TRANSFORMATION_Flipped , SPA_META_TRANSFORMATION_Flipped90 , SPA_META_TRANSFORMATION_Flipped180 , SPA_META_TRANSFORMATION_Flipped270 }

Macros
#define	SPA_BUFFER_ALLOC_FLAG_INLINE_META   (1<<0)
	add metadata data in the skeleton
#define	SPA_BUFFER_ALLOC_FLAG_INLINE_CHUNK   (1<<1)
	add chunk data in the skeleton
#define	SPA_BUFFER_ALLOC_FLAG_INLINE_DATA   (1<<2)
	add buffer data to the skeleton
#define	SPA_BUFFER_ALLOC_FLAG_INLINE_ALL   0b111
#define	SPA_BUFFER_ALLOC_FLAG_NO_DATA   (1<<3)
	don't set data pointers
#define	SPA_CHUNK_FLAG_NONE   0
#define	SPA_CHUNK_FLAG_CORRUPTED   (1u<<0)
	chunk data is corrupted in some way
#define	SPA_CHUNK_FLAG_EMPTY   (1u<<1)
	chunk data is empty with media specific neutral data such as silence or black.
#define	SPA_DATA_FLAG_NONE   0
#define	SPA_DATA_FLAG_READABLE   (1u<<0)
	data is readable
#define	SPA_DATA_FLAG_WRITABLE   (1u<<1)
	data is writable
#define	SPA_DATA_FLAG_DYNAMIC   (1u<<2)
	data pointer can be changed
#define	SPA_DATA_FLAG_READWRITE   (SPA_DATA_FLAG_READABLE|SPA_DATA_FLAG_WRITABLE)
#define	SPA_DATA_FLAG_MAPPABLE   (1u<<3)
	data is mappable with simple mmap/munmap.
#define	spa_meta_first   spa_meta_first
#define	spa_meta_end   spa_meta_end
#define	spa_meta_check(p, m)   (SPA_PTROFF(p,sizeof(*(p)),void) <= spa_meta_end(m))
#define	SPA_META_HEADER_FLAG_DISCONT   (1 << 0)
	data is not continuous with previous buffer
#define	SPA_META_HEADER_FLAG_CORRUPTED   (1 << 1)
	data might be corrupted
#define	SPA_META_HEADER_FLAG_MARKER   (1 << 2)
	media specific marker
#define	SPA_META_HEADER_FLAG_HEADER   (1 << 3)
	data contains a codec specific header
#define	SPA_META_HEADER_FLAG_GAP   (1 << 4)
	data contains media neutral data
#define	SPA_META_HEADER_FLAG_DELTA_UNIT   (1 << 5)
	cannot be decoded independently
#define	spa_meta_region_is_valid   spa_meta_region_is_valid
#define	spa_meta_for_each(pos, meta)
	iterate all the items in a metadata
#define	spa_meta_bitmap_is_valid(m)   ((m)->format != 0)
#define	spa_meta_cursor_is_valid(m)   ((m)->id != 0)
#define	SPA_TYPE_INFO_Buffer   SPA_TYPE_INFO_POINTER_BASE "Buffer"
#define	SPA_TYPE_INFO_BUFFER_BASE   SPA_TYPE_INFO_Buffer ":"
#define	SPA_TYPE_INFO_Data   SPA_TYPE_INFO_ENUM_BASE "Data"
	Buffers contain data of a certain type.
#define	SPA_TYPE_INFO_DATA_BASE   SPA_TYPE_INFO_Data ":"
#define	SPA_TYPE_INFO_DATA_Fd   SPA_TYPE_INFO_DATA_BASE "Fd"
	base type for fd based memory
#define	SPA_TYPE_INFO_DATA_FD_BASE   SPA_TYPE_INFO_DATA_Fd ":"
#define	SPA_TYPE_INFO_Meta   SPA_TYPE_INFO_POINTER_BASE "Meta"
#define	SPA_TYPE_INFO_META_BASE   SPA_TYPE_INFO_Meta ":"
#define	SPA_TYPE_INFO_META_Array   SPA_TYPE_INFO_META_BASE "Array"
#define	SPA_TYPE_INFO_META_ARRAY_BASE   SPA_TYPE_INFO_META_Array ":"
#define	SPA_TYPE_INFO_META_Region   SPA_TYPE_INFO_META_BASE "Region"
#define	SPA_TYPE_INFO_META_REGION_BASE   SPA_TYPE_INFO_META_Region ":"
#define	SPA_TYPE_INFO_META_ARRAY_Region   SPA_TYPE_INFO_META_ARRAY_BASE "Region"
#define	SPA_TYPE_INFO_META_ARRAY_REGION_BASE   SPA_TYPE_INFO_META_ARRAY_Region ":"

Functions
static int	spa_buffer_alloc_fill_info (struct spa_buffer_alloc_info *info, uint32_t n_metas, struct spa_meta metas[], uint32_t n_datas, struct spa_data datas[], uint32_t data_aligns[])
	Fill buffer allocation information.
static struct spa_buffer *	spa_buffer_alloc_layout (struct spa_buffer_alloc_info *info, void *skel_mem, void *data_mem)
	Fill skeleton and data according to the allocation info.
static int	spa_buffer_alloc_layout_array (struct spa_buffer_alloc_info *info, uint32_t n_buffers, struct spa_buffer *buffers[], void *skel_mem, void *data_mem)
	Layout an array of buffers.
static struct spa_buffer **	spa_buffer_alloc_array (uint32_t n_buffers, uint32_t flags, uint32_t n_metas, struct spa_meta metas[], uint32_t n_datas, struct spa_data datas[], uint32_t data_aligns[])
	Allocate an array of buffers.
static struct spa_meta *	spa_buffer_find_meta (const struct spa_buffer *b, uint32_t type)
	Find metadata in a buffer.
static void *	spa_buffer_find_meta_data (const struct spa_buffer *b, uint32_t type, size_t size)
static void *	spa_meta_first (const struct spa_meta *m)
static void *	spa_meta_end (const struct spa_meta *m)
static bool	spa_meta_region_is_valid (const struct spa_meta_region *m)

Variables
static const struct spa_type_info	spa_type_data_type []
static const struct spa_type_info	spa_type_meta_type []

Detailed Description

Buffers describe the data and metadata that is exchanged between ports of a node.

See: SPA Buffers.

Enumeration Type Documentation

spa_data_type

enum spa_data_type

Enumerator
SPA_DATA_Invalid
SPA_DATA_MemPtr	pointer to memory, the data field in struct spa_data is set.
SPA_DATA_MemFd	generic fd, mmap to get to memory
SPA_DATA_DmaBuf	fd to dmabuf memory
SPA_DATA_MemId	memory is identified with an id
_SPA_DATA_LAST	not part of ABI

spa_meta_type

enum spa_meta_type

Enumerator
SPA_META_Invalid
SPA_META_Header	struct spa_meta_header
SPA_META_VideoCrop	struct spa_meta_region with cropping data
SPA_META_VideoDamage	array of struct spa_meta_region with damage, where an invalid entry or end-of-array marks the end.
SPA_META_Bitmap	struct spa_meta_bitmap
SPA_META_Cursor	struct spa_meta_cursor
SPA_META_Control	metadata contains a spa_meta_control associated with the data
SPA_META_Busy	don't write to buffer when count > 0
SPA_META_VideoTransform	struct spa_meta_transform
_SPA_META_LAST	not part of ABI/API

spa_meta_videotransform_value

enum spa_meta_videotransform_value

Enumerator
SPA_META_TRANSFORMATION_None	no transform
SPA_META_TRANSFORMATION_90	90 degree counter-clockwise
SPA_META_TRANSFORMATION_180	180 degree counter-clockwise
SPA_META_TRANSFORMATION_270	270 degree counter-clockwise
SPA_META_TRANSFORMATION_Flipped	180 degree flipped around the vertical axis. Equivalent to a reflexion through the vertical line splitting the bufffer in two equal sized parts
SPA_META_TRANSFORMATION_Flipped90	flip then rotate around 90 degree counter-clockwise
SPA_META_TRANSFORMATION_Flipped180	flip then rotate around 180 degree counter-clockwise
SPA_META_TRANSFORMATION_Flipped270	flip then rotate around 270 degree counter-clockwise

Macro Definition Documentation

SPA_BUFFER_ALLOC_FLAG_INLINE_META

#define SPA_BUFFER_ALLOC_FLAG_INLINE_META   (1<<0)

add metadata data in the skeleton

SPA_BUFFER_ALLOC_FLAG_INLINE_CHUNK

#define SPA_BUFFER_ALLOC_FLAG_INLINE_CHUNK   (1<<1)

add chunk data in the skeleton

SPA_BUFFER_ALLOC_FLAG_INLINE_DATA

#define SPA_BUFFER_ALLOC_FLAG_INLINE_DATA   (1<<2)

add buffer data to the skeleton

SPA_BUFFER_ALLOC_FLAG_INLINE_ALL

#define SPA_BUFFER_ALLOC_FLAG_INLINE_ALL   0b111

SPA_BUFFER_ALLOC_FLAG_NO_DATA

#define SPA_BUFFER_ALLOC_FLAG_NO_DATA   (1<<3)

don't set data pointers

SPA_CHUNK_FLAG_NONE

#define SPA_CHUNK_FLAG_NONE   0

SPA_CHUNK_FLAG_CORRUPTED

#define SPA_CHUNK_FLAG_CORRUPTED   (1u<<0)

chunk data is corrupted in some way

SPA_CHUNK_FLAG_EMPTY

#define SPA_CHUNK_FLAG_EMPTY   (1u<<1)

chunk data is empty with media specific neutral data such as silence or black.

This could be used to optimize processing.

SPA_DATA_FLAG_NONE

#define SPA_DATA_FLAG_NONE   0

SPA_DATA_FLAG_READABLE

#define SPA_DATA_FLAG_READABLE   (1u<<0)

data is readable

SPA_DATA_FLAG_WRITABLE

#define SPA_DATA_FLAG_WRITABLE   (1u<<1)

data is writable

SPA_DATA_FLAG_DYNAMIC

#define SPA_DATA_FLAG_DYNAMIC   (1u<<2)

data pointer can be changed

SPA_DATA_FLAG_READWRITE

#define SPA_DATA_FLAG_READWRITE   (SPA_DATA_FLAG_READABLE|SPA_DATA_FLAG_WRITABLE)

Examples

video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

SPA_DATA_FLAG_MAPPABLE

#define SPA_DATA_FLAG_MAPPABLE   (1u<<3)

data is mappable with simple mmap/munmap.

Some memory types are not simply mappable (DmaBuf) unless explicitly specified with this flag.

spa_meta_first

#define spa_meta_first   spa_meta_first

Examples

video-dsp-src.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

spa_meta_end

#define spa_meta_end   spa_meta_end

spa_meta_check

#define spa_meta_check	(		p,
			m
	)		(SPA_PTROFF(p,sizeof(*(p)),void) <= spa_meta_end(m))

Examples

video-dsp-src.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

SPA_META_HEADER_FLAG_DISCONT

#define SPA_META_HEADER_FLAG_DISCONT   (1 << 0)

data is not continuous with previous buffer

SPA_META_HEADER_FLAG_CORRUPTED

#define SPA_META_HEADER_FLAG_CORRUPTED   (1 << 1)

data might be corrupted

SPA_META_HEADER_FLAG_MARKER

#define SPA_META_HEADER_FLAG_MARKER   (1 << 2)

media specific marker

SPA_META_HEADER_FLAG_HEADER

#define SPA_META_HEADER_FLAG_HEADER   (1 << 3)

data contains a codec specific header

SPA_META_HEADER_FLAG_GAP

#define SPA_META_HEADER_FLAG_GAP   (1 << 4)

data contains media neutral data

SPA_META_HEADER_FLAG_DELTA_UNIT

#define SPA_META_HEADER_FLAG_DELTA_UNIT   (1 << 5)

cannot be decoded independently

spa_meta_region_is_valid

#define spa_meta_region_is_valid   spa_meta_region_is_valid

Examples

export-sink.c, video-play-pull.c, and video-play.c.

spa_meta_for_each

#define spa_meta_for_each	(		pos,
			meta
	)

iterate all the items in a metadata

Examples

export-sink.c.

spa_meta_bitmap_is_valid

#define spa_meta_bitmap_is_valid

(

m

)

((m)->format != 0)

spa_meta_cursor_is_valid

#define spa_meta_cursor_is_valid

(

m

)

((m)->id != 0)

Examples

video-play-pull.c, and video-play.c.

SPA_TYPE_INFO_Buffer

#define SPA_TYPE_INFO_Buffer   SPA_TYPE_INFO_POINTER_BASE "Buffer"

SPA_TYPE_INFO_BUFFER_BASE

#define SPA_TYPE_INFO_BUFFER_BASE   SPA_TYPE_INFO_Buffer ":"

SPA_TYPE_INFO_Data

#define SPA_TYPE_INFO_Data   SPA_TYPE_INFO_ENUM_BASE "Data"

Buffers contain data of a certain type.

SPA_TYPE_INFO_DATA_BASE

#define SPA_TYPE_INFO_DATA_BASE   SPA_TYPE_INFO_Data ":"

SPA_TYPE_INFO_DATA_Fd

#define SPA_TYPE_INFO_DATA_Fd   SPA_TYPE_INFO_DATA_BASE "Fd"

base type for fd based memory

SPA_TYPE_INFO_DATA_FD_BASE

#define SPA_TYPE_INFO_DATA_FD_BASE   SPA_TYPE_INFO_DATA_Fd ":"

SPA_TYPE_INFO_Meta

#define SPA_TYPE_INFO_Meta   SPA_TYPE_INFO_POINTER_BASE "Meta"

SPA_TYPE_INFO_META_BASE

#define SPA_TYPE_INFO_META_BASE   SPA_TYPE_INFO_Meta ":"

SPA_TYPE_INFO_META_Array

#define SPA_TYPE_INFO_META_Array   SPA_TYPE_INFO_META_BASE "Array"

SPA_TYPE_INFO_META_ARRAY_BASE

#define SPA_TYPE_INFO_META_ARRAY_BASE   SPA_TYPE_INFO_META_Array ":"

SPA_TYPE_INFO_META_Region

#define SPA_TYPE_INFO_META_Region   SPA_TYPE_INFO_META_BASE "Region"

SPA_TYPE_INFO_META_REGION_BASE

#define SPA_TYPE_INFO_META_REGION_BASE   SPA_TYPE_INFO_META_Region ":"

SPA_TYPE_INFO_META_ARRAY_Region

#define SPA_TYPE_INFO_META_ARRAY_Region   SPA_TYPE_INFO_META_ARRAY_BASE "Region"

SPA_TYPE_INFO_META_ARRAY_REGION_BASE

#define SPA_TYPE_INFO_META_ARRAY_REGION_BASE   SPA_TYPE_INFO_META_ARRAY_Region ":"

Function Documentation

spa_buffer_alloc_fill_info()

static int spa_buffer_alloc_fill_info ( struct spa_buffer_alloc_info *  info, uint32_t  n_metas, struct spa_meta  metas[], uint32_t  n_datas, struct spa_data  datas[], uint32_t  data_aligns[]  )

inlinestatic

Fill buffer allocation information.

Fill info with allocation information needed to allocate buffers with the given number of metadata and data members.

The required size of the skeleton (the struct spa_buffer) information and the memory (for the metadata, chunk and buffer memory) will be calculated.

The flags member in info should be configured before calling this functions.

Parameters

info	the information to fill
n_metas	the number of metadatas for the buffer
metas	an array of metadata items
n_datas	the number of datas for the buffer
datas	an array of n_datas items
data_aligns	n_datas alignments

Returns

0 on success.

spa_buffer_alloc_layout()

static struct spa_buffer * spa_buffer_alloc_layout ( struct spa_buffer_alloc_info *  info, void *  skel_mem, void *  data_mem  )

inlinestatic

Fill skeleton and data according to the allocation info.

Use the allocation info to create a struct Buffers into skel_mem and data_mem.

Depending on the flags given when calling spa_buffer_alloc_fill_info(), the buffer meta, chunk and memory will be referenced in either skel_mem or data_mem.

Parameters

info	an allocation info
skel_mem	memory to hold the struct Buffers and the pointers to meta, chunk and memory.
data_mem	memory to hold the meta, chunk and memory

Returns

a struct Buffers in skel_mem

spa_buffer_alloc_layout_array()

static int spa_buffer_alloc_layout_array ( struct spa_buffer_alloc_info *  info, uint32_t  n_buffers, struct spa_buffer *  buffers[], void *  skel_mem, void *  data_mem  )

inlinestatic

Layout an array of buffers.

Use the allocation info to layout the memory of an array of buffers.

skel_mem should point to at least info->skel_size * n_buffers bytes of memory. data_mem should point to at least info->mem_size * n_buffers bytes of memory.

Parameters

info	the allocation info for one buffer
n_buffers	the number of buffers to create
buffers	a array with space to hold n_buffers pointers to buffers
skel_mem	memory for the struct Buffers
data_mem	memory for the meta, chunk, memory of the buffer if not inlined in the skeleton.

Returns

0 on success.

spa_buffer_alloc_array()

static struct spa_buffer ** spa_buffer_alloc_array ( uint32_t  n_buffers, uint32_t  flags, uint32_t  n_metas, struct spa_meta  metas[], uint32_t  n_datas, struct spa_data  datas[], uint32_t  data_aligns[]  )

inlinestatic

Allocate an array of buffers.

Allocate n_buffers with the given metadata, memory and alignment information.

The buffer array, structures, data and metadata will all be allocated in one block of memory with the proper requested alignment.

Parameters

n_buffers	the number of buffers to create
flags	extra flags
n_metas	number of metadatas
metas	n_metas metadata specification
n_datas	number of datas
datas	n_datas memory specification
data_aligns	n_datas alignment specifications

Returns

an array of n_buffers pointers to struct Buffers with the given metadata, data and alignment or NULL when allocation failed.

spa_buffer_find_meta()

static struct spa_meta * spa_buffer_find_meta ( const struct spa_buffer *  b, uint32_t  type  )

inlinestatic

Find metadata in a buffer.

Examples

export-sink.c, video-dsp-src.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

spa_buffer_find_meta_data()

static void * spa_buffer_find_meta_data ( const struct spa_buffer *  b, uint32_t  type, size_t  size  )

inlinestatic

Examples

video-dsp-src.c, video-play-pull.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

spa_meta_first()

static void * spa_meta_first ( const struct spa_meta *  m )

inlinestatic

spa_meta_end()

static void * spa_meta_end ( const struct spa_meta *  m )

inlinestatic

spa_meta_region_is_valid()

static bool spa_meta_region_is_valid ( const struct spa_meta_region *  m )

inlinestatic

Variable Documentation

spa_type_data_type

const struct spa_type_info spa_type_data_type[]

static

spa_type_meta_type

const struct spa_type_info spa_type_meta_type[]

static