Buffers
SPA

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...

## Macros

#define | SPA_BUFFER_ALLOC_FLAG_INLINE_META (1<<0)
| add metadata data in the skeleton More...
#define | SPA_BUFFER_ALLOC_FLAG_INLINE_CHUNK (1<<1)
| add chunk data in the skeleton More...
#define | SPA_BUFFER_ALLOC_FLAG_INLINE_DATA (1<<2)
| add buffer data to the skeleton More...
#define | SPA_BUFFER_ALLOC_FLAG_INLINE_ALL 0b111
#define | SPA_BUFFER_ALLOC_FLAG_NO_DATA (1<<3)
| don't set data pointers More...
#define | SPA_CHUNK_FLAG_NONE 0
#define | SPA_CHUNK_FLAG_CORRUPTED (1u<<0)
| chunk data is corrupted in some way More...
#define | SPA_DATA_FLAG_NONE 0
#define | SPA_DATA_FLAG_READABLE (1u<<0)
| data is readable More...
#define | SPA_DATA_FLAG_WRITABLE (1u<<1)
| data is writable More...
#define | SPA_DATA_FLAG_DYNAMIC (1u<<2)
| data pointer can be changed More...
#define | SPA_DATA_FLAG_READWRITE (SPA_DATA_FLAG_READABLE|SPA_DATA_FLAG_WRITABLE)
#define | spa_meta_first(m) ((m)->data)
#define | spa_meta_end(m) SPA_PTROFF((m)->data,(m)->size,void)
#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 More...
#define | SPA_META_HEADER_FLAG_CORRUPTED (1 << 1)
| data might be corrupted More...
#define | SPA_META_HEADER_FLAG_MARKER (1 << 2)
| media specific marker More...
#define | SPA_META_HEADER_FLAG_HEADER (1 << 3)
| data contains a codec specific header More...
#define | SPA_META_HEADER_FLAG_GAP (1 << 4)
| data contains media neutral data More...
#define | SPA_META_HEADER_FLAG_DELTA_UNIT (1 << 5)
| cannot be decoded independently More...
#define | spa_meta_region_is_valid(m) ((m)->region.size.width != 0 && (m)->region.size.height != 0)
#define | spa_meta_for_each(pos, meta)
| iterate all the items in a metadata More...
#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. More...
#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 More...
#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 ":"

## 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_LAST }

## 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. More...
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. More...
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. More...
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. More...
static struct spa_meta * | spa_buffer_find_meta (const struct spa_buffer *b, uint32_t type)
| Find metadata in a buffer. More...
static void * | spa_buffer_find_meta_data (const struct spa_buffer *b, uint32_t type, size_t size)

## 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.

## 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_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_meta_first

#define spa_meta_first | ( |  | m | ) | ((m)->data)

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

## spa_meta_end

#define spa_meta_end | ( |  | m | ) | SPA_PTROFF((m)->data,(m)->size,void)

## spa_meta_check

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

Examples
  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 | ( |  | m | ) | ((m)->region.size.width != 0 && (m)->region.size.height != 0)

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 ":"

## 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_LAST | not part of ABI/API

## 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[]
| ) |  |

inline static

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

inline static

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

inline static

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[]
| ) |  |

inline static

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

inline static

Find metadata in a buffer.

Examples
  export-sink.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
| ) |  |

inline static

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

## 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