mirror of
https://github.com/libretro/RetroArch
synced 2025-01-29 09:32:52 +00:00
263 lines
12 KiB
C
263 lines
12 KiB
C
/*
|
|
Copyright (c) 2012, Broadcom Europe Ltd
|
|
All rights reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
* Redistributions of source code must retain the above copyright
|
|
notice, this list of conditions and the following disclaimer.
|
|
* Redistributions in binary form must reproduce the above copyright
|
|
notice, this list of conditions and the following disclaimer in the
|
|
documentation and/or other materials provided with the distribution.
|
|
* Neither the name of the copyright holder nor the
|
|
names of its contributors may be used to endorse or promote products
|
|
derived from this software without specific prior written permission.
|
|
|
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
|
|
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
|
|
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
|
|
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
|
|
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
*/
|
|
|
|
#ifndef MMAL_BUFFER_H
|
|
#define MMAL_BUFFER_H
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/** \defgroup MmalBufferHeader Buffer headers
|
|
* 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.
|
|
*/
|
|
/* @{ */
|
|
|
|
/** Specific data associated with video frames */
|
|
typedef struct {
|
|
uint32_t planes; /**< Number of planes composing the video frame */
|
|
uint32_t offset[4]; /**< Offsets to the different planes. These must point within the
|
|
payload buffer */
|
|
uint32_t pitch[4]; /**< Pitch (size in bytes of a line of a plane) of the different
|
|
planes */
|
|
uint32_t flags; /**< Flags describing video specific properties of a buffer header
|
|
(see \ref videobufferheaderflags "Video buffer header flags") */
|
|
/* TBD stereoscopic support */
|
|
} MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T;
|
|
|
|
/** Type specific data that's associated with a payload buffer */
|
|
typedef union
|
|
{
|
|
/** Specific data associated with video frames */
|
|
MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T video;
|
|
|
|
} MMAL_BUFFER_HEADER_TYPE_SPECIFIC_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.
|
|
*/
|
|
typedef struct MMAL_BUFFER_HEADER_T
|
|
{
|
|
struct MMAL_BUFFER_HEADER_T *next; /**< Used to link several buffer headers together */
|
|
|
|
struct MMAL_BUFFER_HEADER_PRIVATE_T *priv; /**< Data private to the framework */
|
|
|
|
uint32_t cmd; /**< Defines what the buffer header contains. This is a FourCC
|
|
with 0 as a special value meaning stream data */
|
|
|
|
uint8_t *data; /**< Pointer to the start of the payload buffer (should not be
|
|
changed by component) */
|
|
uint32_t alloc_size; /**< Allocated size in bytes of payload buffer */
|
|
uint32_t length; /**< Number of bytes currently used in the payload buffer (starting
|
|
from offset) */
|
|
uint32_t offset; /**< Offset in bytes to the start of valid data in the payload buffer */
|
|
|
|
uint32_t flags; /**< Flags describing properties of a buffer header (see
|
|
\ref bufferheaderflags "Buffer header flags") */
|
|
|
|
int64_t pts; /**< Presentation timestamp in microseconds. \ref MMAL_TIME_UNKNOWN
|
|
is used when the pts is unknown. */
|
|
int64_t dts; /**< Decode timestamp in microseconds (dts = pts, except in the case
|
|
of video streams with B frames). \ref MMAL_TIME_UNKNOWN
|
|
is used when the dts is unknown. */
|
|
|
|
/** Type specific data that's associated with a payload buffer */
|
|
MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T *type;
|
|
|
|
void *user_data; /**< Field reserved for use by the client */
|
|
|
|
} MMAL_BUFFER_HEADER_T;
|
|
|
|
/** \name Buffer header flags
|
|
* \anchor bufferheaderflags
|
|
* The following flags describe properties of a buffer header */
|
|
/* @{ */
|
|
/** Signals that the current payload is the end of the stream of data */
|
|
#define MMAL_BUFFER_HEADER_FLAG_EOS (1<<0)
|
|
/** Signals that the start of the current payload starts a frame */
|
|
#define MMAL_BUFFER_HEADER_FLAG_FRAME_START (1<<1)
|
|
/** Signals that the end of the current payload ends a frame */
|
|
#define MMAL_BUFFER_HEADER_FLAG_FRAME_END (1<<2)
|
|
/** Signals that the current payload contains only complete frames (1 or more) */
|
|
#define MMAL_BUFFER_HEADER_FLAG_FRAME (MMAL_BUFFER_HEADER_FLAG_FRAME_START|MMAL_BUFFER_HEADER_FLAG_FRAME_END)
|
|
/** Signals that the current payload is a keyframe (i.e. self decodable) */
|
|
#define MMAL_BUFFER_HEADER_FLAG_KEYFRAME (1<<3)
|
|
/** 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 */
|
|
#define MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY (1<<4)
|
|
/** Signals a buffer containing some kind of config data for the component
|
|
* (e.g. codec config data) */
|
|
#define MMAL_BUFFER_HEADER_FLAG_CONFIG (1<<5)
|
|
/** Signals an encrypted payload */
|
|
#define MMAL_BUFFER_HEADER_FLAG_ENCRYPTED (1<<6)
|
|
/** Signals a buffer containing side information */
|
|
#define MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO (1<<7)
|
|
/** Signals a buffer which is the snapshot/postview image from a stills capture */
|
|
#define MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT (1<<8)
|
|
/** Signals a buffer which contains data known to be corrupted */
|
|
#define MMAL_BUFFER_HEADER_FLAG_CORRUPTED (1<<9)
|
|
/** Signals that a buffer failed to be transmitted */
|
|
#define MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED (1<<10)
|
|
/** Signals the output buffer won't be used, just update reference frames */
|
|
#define MMAL_BUFFER_HEADER_FLAG_DECODEONLY (1<<11)
|
|
/** Signals that the end of the current payload ends a NAL */
|
|
#define MMAL_BUFFER_HEADER_FLAG_NAL_END (1<<12)
|
|
/** User flags - can be passed in and will get returned */
|
|
#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)
|
|
/* @} */
|
|
|
|
/** \name Video buffer header flags
|
|
* \anchor videobufferheaderflags
|
|
* 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)
|
|
/* @{ */
|
|
/** 16: Signals an interlaced video frame */
|
|
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<0)
|
|
/** 17: Signals that the top field of the current interlaced frame should be displayed first */
|
|
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<1)
|
|
/** 19: Signals that the buffer should be displayed on external display if attached. */
|
|
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<3)
|
|
/** 20: Signals that contents of the buffer requires copy protection. */
|
|
#define MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<4)
|
|
/** 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. */
|
|
#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)
|
|
/* @} */
|
|
|
|
/** 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).
|
|
*
|
|
* @param header buffer header to acquire
|
|
*/
|
|
void mmal_buffer_header_acquire(MMAL_BUFFER_HEADER_T *header);
|
|
|
|
/** Reset a buffer header.
|
|
* Resets all header variables to default values.
|
|
*
|
|
* @param header buffer header to reset
|
|
*/
|
|
void mmal_buffer_header_reset(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 (\ref 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
|
|
* \ref mmal_buffer_header_release_continue.
|
|
*
|
|
* @param header buffer header to release
|
|
*/
|
|
void mmal_buffer_header_release(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.
|
|
*
|
|
* @param header buffer header to release
|
|
*/
|
|
void mmal_buffer_header_release_continue(MMAL_BUFFER_HEADER_T *header);
|
|
|
|
/** 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.
|
|
*
|
|
* @param header buffer header about to be released
|
|
* @param userdata user-specific data
|
|
*
|
|
* @return TRUE if the buffer should not be released
|
|
*/
|
|
typedef MMAL_BOOL_T (*MMAL_BH_PRE_RELEASE_CB_T)(MMAL_BUFFER_HEADER_T *header, 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.
|
|
*
|
|
* @param header buffer header to associate callback with
|
|
* @param cb pre-release callback to invoke
|
|
* @param userdata user-specific data
|
|
*/
|
|
void mmal_buffer_header_pre_release_cb_set(MMAL_BUFFER_HEADER_T *header, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata);
|
|
|
|
/** 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.
|
|
*
|
|
* @param dest buffer header into which to replicate
|
|
* @param src buffer header to use as the source for the replication
|
|
* @return MMAL_SUCCESS on success
|
|
*/
|
|
MMAL_STATUS_T mmal_buffer_header_replicate(MMAL_BUFFER_HEADER_T *dest, MMAL_BUFFER_HEADER_T *src);
|
|
|
|
/** 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.
|
|
*
|
|
* @param header buffer header to lock
|
|
*/
|
|
MMAL_STATUS_T mmal_buffer_header_mem_lock(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.
|
|
*
|
|
* @param header buffer header to unlock
|
|
*/
|
|
void mmal_buffer_header_mem_unlock(MMAL_BUFFER_HEADER_T *header);
|
|
|
|
/* @} */
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* MMAL_BUFFER_H */
|