My Project
Buffer headers

Classes

struct  MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T
 
union  MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T
 
struct  MMAL_BUFFER_HEADER_T
 

Typedefs

typedef struct MMAL_BUFFER_HEADER_T MMAL_BUFFER_HEADER_T
 
typedef MMAL_BOOL_T(* MMAL_BH_PRE_RELEASE_CB_T) (MMAL_BUFFER_HEADER_T *header, void *userdata)
 

Functions

void mmal_buffer_header_acquire (MMAL_BUFFER_HEADER_T *header)
 
void mmal_buffer_header_reset (MMAL_BUFFER_HEADER_T *header)
 
void mmal_buffer_header_release (MMAL_BUFFER_HEADER_T *header)
 
void mmal_buffer_header_release_continue (MMAL_BUFFER_HEADER_T *header)
 
void mmal_buffer_header_pre_release_cb_set (MMAL_BUFFER_HEADER_T *header, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata)
 
MMAL_STATUS_T mmal_buffer_header_replicate (MMAL_BUFFER_HEADER_T *dest, MMAL_BUFFER_HEADER_T *src)
 
MMAL_STATUS_T mmal_buffer_header_mem_lock (MMAL_BUFFER_HEADER_T *header)
 
void mmal_buffer_header_mem_unlock (MMAL_BUFFER_HEADER_T *header)
 

Buffer header flags

The following flags describe properties of a buffer header

#define MMAL_BUFFER_HEADER_FLAG_EOS   (1<<0)
 
#define MMAL_BUFFER_HEADER_FLAG_FRAME_START   (1<<1)
 
#define MMAL_BUFFER_HEADER_FLAG_FRAME_END   (1<<2)
 
#define MMAL_BUFFER_HEADER_FLAG_FRAME   (MMAL_BUFFER_HEADER_FLAG_FRAME_START|MMAL_BUFFER_HEADER_FLAG_FRAME_END)
 
#define MMAL_BUFFER_HEADER_FLAG_KEYFRAME   (1<<3)
 
#define MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY   (1<<4)
 
#define MMAL_BUFFER_HEADER_FLAG_CONFIG   (1<<5)
 
#define MMAL_BUFFER_HEADER_FLAG_ENCRYPTED   (1<<6)
 
#define MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO   (1<<7)
 
#define MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT   (1<<8)
 
#define MMAL_BUFFER_HEADER_FLAG_CORRUPTED   (1<<9)
 
#define MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED   (1<<10)
 
#define MMAL_BUFFER_HEADER_FLAG_DECODEONLY   (1<<11)
 
#define MMAL_BUFFER_HEADER_FLAG_NAL_END   (1<<12)
 
#define MMAL_BUFFER_HEADER_FLAG_USER0   (1<<28)
 
#define MMAL_BUFFER_HEADER_FLAG_USER1   (1<<29)
 
#define MMAL_BUFFER_HEADER_FLAG_USER2   (1<<30)
 
#define MMAL_BUFFER_HEADER_FLAG_USER3   (1<<31)
 

Video buffer header flags

The following flags describe properties of a video buffer header. As there is no collision with the MMAL_BUFFER_HEADER_FLAGS_ defines, these flags will also be present in the MMAL_BUFFER_HEADER_T flags field.

#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT   16
 
#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START   (1<<MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<0)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<1)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<3)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<4)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT+8)
 
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_MASK   (0xF<<MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT)
 

Detailed Description

Definition of a buffer header and its associated API. Buffer headers are the basic element used to pass data and information between different parts of the system. They are passed to components via ports and sent back to the client using a callback mechanism.

Macro Definition Documentation

◆ MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO

#define MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO   (1<<7)

Signals a buffer containing side information

Definition at line 124 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_CONFIG

#define MMAL_BUFFER_HEADER_FLAG_CONFIG   (1<<5)

Signals a buffer containing some kind of config data for the component (e.g. codec config data)

Definition at line 120 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_CORRUPTED

#define MMAL_BUFFER_HEADER_FLAG_CORRUPTED   (1<<9)

Signals a buffer which contains data known to be corrupted

Definition at line 128 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_DECODEONLY

#define MMAL_BUFFER_HEADER_FLAG_DECODEONLY   (1<<11)

Signals the output buffer won't be used, just update reference frames

Definition at line 132 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY

#define MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY   (1<<4)

Signals a discontinuity in the stream of data (e.g. after a seek). Can be used for instance by a decoder to reset its state

Definition at line 117 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_ENCRYPTED

#define MMAL_BUFFER_HEADER_FLAG_ENCRYPTED   (1<<6)

Signals an encrypted payload

Definition at line 122 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_EOS

#define MMAL_BUFFER_HEADER_FLAG_EOS   (1<<0)

Signals that the current payload is the end of the stream of data

Definition at line 106 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START

#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START   (1<<MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT)

Definition at line 149 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT

#define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT   16

Definition at line 148 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_FRAME

#define MMAL_BUFFER_HEADER_FLAG_FRAME   (MMAL_BUFFER_HEADER_FLAG_FRAME_START|MMAL_BUFFER_HEADER_FLAG_FRAME_END)

Signals that the current payload contains only complete frames (1 or more)

Definition at line 112 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_FRAME_END

#define MMAL_BUFFER_HEADER_FLAG_FRAME_END   (1<<2)

Signals that the end of the current payload ends a frame

Definition at line 110 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_FRAME_START

#define MMAL_BUFFER_HEADER_FLAG_FRAME_START   (1<<1)

Signals that the start of the current payload starts a frame

Definition at line 108 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_KEYFRAME

#define MMAL_BUFFER_HEADER_FLAG_KEYFRAME   (1<<3)

Signals that the current payload is a keyframe (i.e. self decodable)

Definition at line 114 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_NAL_END

#define MMAL_BUFFER_HEADER_FLAG_NAL_END   (1<<12)

Signals that the end of the current payload ends a NAL

Definition at line 134 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED

#define MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED   (1<<10)

Signals that a buffer failed to be transmitted

Definition at line 130 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_USER0

#define MMAL_BUFFER_HEADER_FLAG_USER0   (1<<28)

User flags - can be passed in and will get returned

Definition at line 136 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_USER1

#define MMAL_BUFFER_HEADER_FLAG_USER1   (1<<29)

Definition at line 137 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_USER2

#define MMAL_BUFFER_HEADER_FLAG_USER2   (1<<30)

Definition at line 138 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAG_USER3

#define MMAL_BUFFER_HEADER_FLAG_USER3   (1<<31)

Definition at line 139 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT

#define MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT   (1<<8)

Signals a buffer which is the snapshot/postview image from a stills capture

Definition at line 126 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_MASK

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_MASK   (0xF<<MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT)

Definition at line 163 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_COLUMN_LOG2_SHIFT   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START_BIT+8)

27-24: If non-zero it signals the video frame is encoded in column mode, with a column width equal to 2^<masked value>="">. Zero is raster order.

Definition at line 162 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<3)

19: Signals that the buffer should be displayed on external display if attached.

Definition at line 156 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<0)

16: Signals an interlaced video frame

Definition at line 152 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<4)

20: Signals that contents of the buffer requires copy protection.

Definition at line 158 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST

#define MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST   (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<1)

17: Signals that the top field of the current interlaced frame should be displayed first

Definition at line 154 of file mmal_buffer.h.

Typedef Documentation

◆ MMAL_BH_PRE_RELEASE_CB_T

typedef MMAL_BOOL_T(* MMAL_BH_PRE_RELEASE_CB_T) (MMAL_BUFFER_HEADER_T *header, void *userdata)

Buffer header pre-release callback. The callback is invoked just before a buffer is released back into a pool. This is used by clients who need to trigger additional actions before the buffer can finally be released (e.g. wait for a bulk transfer to complete).

The callback should return TRUE if the buffer release need to be post-poned.

Parameters
headerbuffer header about to be released
userdatauser-specific data
Returns
TRUE if the buffer should not be released

Definition at line 217 of file mmal_buffer.h.

◆ MMAL_BUFFER_HEADER_T

Definition of the buffer header structure. A buffer header does not directly carry the data to be passed to a component but instead it references the actual data using a pointer (and an associated length). It also contains an internal area which can be used to store command to be associated with the external data.

Function Documentation

◆ mmal_buffer_header_acquire()

void mmal_buffer_header_acquire ( MMAL_BUFFER_HEADER_T header)

Acquire a buffer header. Acquiring a buffer header increases a reference counter on it and makes sure that the buffer header won't be recycled until all the references to it are gone. This is useful for instance if a component needs to return a buffer header but still needs access to it for some internal processing (e.g. reference frames in video codecs).

Parameters
headerbuffer header to acquire

◆ mmal_buffer_header_mem_lock()

MMAL_STATUS_T mmal_buffer_header_mem_lock ( MMAL_BUFFER_HEADER_T header)

Lock the data buffer contained in the buffer header in memory. This call does nothing on all platforms except VideoCore where it is needed to pin a buffer in memory before any access to it.

Parameters
headerbuffer header to lock

◆ mmal_buffer_header_mem_unlock()

void mmal_buffer_header_mem_unlock ( MMAL_BUFFER_HEADER_T header)

Unlock the data buffer contained in the buffer header. This call does nothing on all platforms except VideoCore where it is needed to un-pin a buffer in memory after any access to it.

Parameters
headerbuffer header to unlock

◆ mmal_buffer_header_pre_release_cb_set()

void mmal_buffer_header_pre_release_cb_set ( MMAL_BUFFER_HEADER_T header,
MMAL_BH_PRE_RELEASE_CB_T  cb,
void *  userdata 
)

Set a buffer header pre-release callback. If the callback is NULL, the buffer will be released back into the pool immediately as usual.

Parameters
headerbuffer header to associate callback with
cbpre-release callback to invoke
userdatauser-specific data

◆ mmal_buffer_header_release()

void mmal_buffer_header_release ( MMAL_BUFFER_HEADER_T header)

Release a buffer header. Releasing a buffer header will decrease its reference counter and when no more references are left, the buffer header will be recycled by calling its 'release' callback function.

If a pre-release callback is set (MMAL_BH_PRE_RELEASE_CB_T), this will be invoked before calling the buffer's release callback and potentially postpone buffer recycling. Once pre-release is complete the buffer header is recycled with mmal_buffer_header_release_continue.

Parameters
headerbuffer header to release

◆ mmal_buffer_header_release_continue()

void mmal_buffer_header_release_continue ( MMAL_BUFFER_HEADER_T header)

Continue the buffer header release process. This should be called to complete buffer header recycling once all pre-release activity has been completed.

Parameters
headerbuffer header to release

◆ mmal_buffer_header_replicate()

MMAL_STATUS_T mmal_buffer_header_replicate ( MMAL_BUFFER_HEADER_T dest,
MMAL_BUFFER_HEADER_T src 
)

Replicate a buffer header into another one. Replicating a buffer header will not only do an exact copy of all the public fields of the buffer header (including data and alloc_size), but it will also acquire a reference to the source buffer header which will only be released once the replicate has been released.

Parameters
destbuffer header into which to replicate
srcbuffer header to use as the source for the replication
Returns
MMAL_SUCCESS on success

◆ mmal_buffer_header_reset()

void mmal_buffer_header_reset ( MMAL_BUFFER_HEADER_T header)

Reset a buffer header. Resets all header variables to default values.

Parameters
headerbuffer header to reset