PipeWire: Buffers

PipeWire 1.2.1

Loading...
Searching...
No Matches
Files | Data Structures | Enumerations | Macros | Functions | Variables
Buffers
SPA

## 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...
struct | spa_meta_sync_timeline
| A timeline point for explicit sync. More...

## Enumerations
enum | spa_data_type { SPA_DATA_Invalid , SPA_DATA_MemPtr , SPA_DATA_MemFd , SPA_DATA_DmaBuf , SPA_DATA_MemId , SPA_DATA_SyncObj , _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_SyncTimeline , _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 ":"
#define | SPA_TYPE_INFO_META_Transformation SPA_TYPE_INFO_ENUM_BASE "Meta:Transformation"
#define | SPA_TYPE_INFO_META_TRANSFORMATION_BASE SPA_TYPE_INFO_META_Transformation ":"

## 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_videotransform_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 | memfd, mmap to get to memory.
SPA_DATA_DmaBuf | fd to dmabuf memory. This might not be readily mappable (unless the MAPPABLE flag is set) and should normally be handled with DMABUF apis.
SPA_DATA_MemId | memory is identified with an id. The actual memory can be obtained in some other way and can be identified with this id.
SPA_DATA_SyncObj | a syncobj, usually requires a spa_meta_sync_timeline metadata with timeline points.
_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_SyncTimeline | struct spa_meta_sync_timeline
_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 buffer 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.

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

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

## ◆ SPA_TYPE_INFO_META_Transformation

#define SPA_TYPE_INFO_META_Transformation SPA_TYPE_INFO_ENUM_BASE "Meta:Transformation"

## ◆ SPA_TYPE_INFO_META_TRANSFORMATION_BASE

#define SPA_TYPE_INFO_META_TRANSFORMATION_BASE SPA_TYPE_INFO_META_Transformation ":"

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

const struct spa_type_info spa_type_meta_videotransform_type[]
| static

## ◆ spa_type_meta_type

const struct spa_type_info spa_type_meta_type[]
| static