interface/mmal/mmal_buffer.h

   1 /*
   2 Copyright (c) 2012, Broadcom Europe Ltd
   3 All rights reserved.
   4
   5 Redistribution and use in source and binary forms, with or without
   6 modification, are permitted provided that the following conditions are met:
   7     * Redistributions of source code must retain the above copyright
   8       notice, this list of conditions and the following disclaimer.
   9     * Redistributions in binary form must reproduce the above copyright
  10       notice, this list of conditions and the following disclaimer in the
  11       documentation and/or other materials provided with the distribution.
  12     * Neither the name of the copyright holder nor the
  13       names of its contributors may be used to endorse or promote products
  14       derived from this software without specific prior written permission.
  15
  16 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  17 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  18 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  19 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
  20 DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  21 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  22 LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  23 ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26 */
  27
  28 #ifndef MMAL_BUFFER_H
  29 #define MMAL_BUFFER_H
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /** \defgroup MmalBufferHeader Buffer headers
  36  * Definition of a buffer header and its associated API.
  37  * Buffer headers are the basic element used to pass data and information between different
  38  * parts of the system. They are passed to components via ports and sent back to the client
  39  * using a callback mechanism.
  40  */
  41 /* @{ */
  42
  43 /** Specific data associated with video frames */
  44 typedef struct {
  45    uint32_t planes;     /**< Number of planes composing the video frame */
  46    uint32_t offset[4];  /**< Offsets to the different planes. These must point within the
  47                              payload buffer */
  48    uint32_t pitch[4];   /**< Pitch (size in bytes of a line of a plane) of the different
  49                              planes */
  50    uint32_t flags;      /**< Flags describing video specific properties of a buffer header
  51                              (see \ref videobufferheaderflags "Video buffer header flags") */
  52    /* TBD stereoscopic support */
  53 } MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T;
  54
  55 /** Type specific data that's associated with a payload buffer */
  56 typedef union
  57 {
  58    /** Specific data associated with video frames */
  59    MMAL_BUFFER_HEADER_VIDEO_SPECIFIC_T video;
  60
  61 } MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T;
  62
  63 /** Definition of the buffer header structure.
  64  * A buffer header does not directly carry the data to be passed to a component but instead
  65  * it references the actual data using a pointer (and an associated length).
  66  * It also contains an internal area which can be used to store command or metadata to be
  67  * associated with the external data.
  68  */
  69 typedef struct MMAL_BUFFER_HEADER_T
  70 {
  71    struct MMAL_BUFFER_HEADER_T *next; /**< Used to link several buffer headers together */
  72
  73    struct MMAL_BUFFER_HEADER_PRIVATE_T *priv; /**< Data private to the framework */
  74
  75    uint32_t cmd;              /**< Defines what the buffer header contains. This is a FourCC
  76                                    with 0 as a special value meaning stream data */
  77
  78    uint8_t  *data;            /**< Pointer to the start of the payload buffer (should not be
  79                                    changed by component) */
  80    uint32_t alloc_size;       /**< Allocated size in bytes of payload buffer */
  81    uint32_t length;           /**< Number of bytes currently used in the payload buffer (starting
  82                                    from offset) */
  83    uint32_t offset;           /**< Offset in bytes to the start of valid data in the payload buffer */
  84
  85    uint32_t flags;            /**< Flags describing properties of a buffer header (see
  86                                    \ref bufferheaderflags "Buffer header flags") */
  87
  88    int64_t  pts;              /**< Presentation timestamp in microseconds. \ref MMAL_TIME_UNKNOWN
  89                                    is used when the pts is unknown. */
  90    int64_t  dts;              /**< Decode timestamp in microseconds (dts = pts, except in the case
  91                                    of video streams with B frames). \ref MMAL_TIME_UNKNOWN
  92                                    is used when the dts is unknown. */
  93
  94    /** Type specific data that's associated with a payload buffer */
  95    MMAL_BUFFER_HEADER_TYPE_SPECIFIC_T *type;
  96
  97    void *user_data;           /**< Field reserved for use by the client */
  98
  99 } MMAL_BUFFER_HEADER_T;
 100
 101 /** \name Buffer header flags
 102  * \anchor bufferheaderflags
 103  * The following flags describe properties of a buffer header */
 104 /* @{ */
 105 /** Signals that the current payload is the end of the stream of data */
 106 #define MMAL_BUFFER_HEADER_FLAG_EOS                    (1<<0)
 107 /** Signals that the start of the current payload starts a frame */
 108 #define MMAL_BUFFER_HEADER_FLAG_FRAME_START            (1<<1)
 109 /** Signals that the end of the current payload ends a frame */
 110 #define MMAL_BUFFER_HEADER_FLAG_FRAME_END              (1<<2)
 111 /** Signals that the current payload contains only complete frames (1 or more) */
 112 #define MMAL_BUFFER_HEADER_FLAG_FRAME                  (MMAL_BUFFER_HEADER_FLAG_FRAME_START|MMAL_BUFFER_HEADER_FLAG_FRAME_END)
 113 /** Signals that the current payload is a keyframe (i.e. self decodable) */
 114 #define MMAL_BUFFER_HEADER_FLAG_KEYFRAME               (1<<3)
 115 /** Signals a discontinuity in the stream of data (e.g. after a seek).
 116  * Can be used for instance by a decoder to reset its state */
 117 #define MMAL_BUFFER_HEADER_FLAG_DISCONTINUITY          (1<<4)
 118 /** Signals a buffer containing some kind of config data for the component
 119  * (e.g. codec config data) */
 120 #define MMAL_BUFFER_HEADER_FLAG_CONFIG                 (1<<5)
 121 /** Signals an encrypted payload */
 122 #define MMAL_BUFFER_HEADER_FLAG_ENCRYPTED              (1<<6)
 123 /** Signals a buffer containing side information */
 124 #define MMAL_BUFFER_HEADER_FLAG_CODECSIDEINFO          (1<<7)
 125 /** Signals a buffer which is the snapshot/postview image from a stills capture */
 126 #define MMAL_BUFFER_HEADER_FLAGS_SNAPSHOT              (1<<8)
 127 /** Signals a buffer which contains data known to be corrupted */
 128 #define MMAL_BUFFER_HEADER_FLAG_CORRUPTED              (1<<9)
 129 /** Signals that a buffer failed to be transmitted */
 130 #define MMAL_BUFFER_HEADER_FLAG_TRANSMISSION_FAILED    (1<<10)
 131 /** Signals the output buffer won't be used, just update reference frames */
 132 #define MMAL_BUFFER_HEADER_FLAG_DECODEONLY             (1<<11)
 133 /** User flags - can be passed in and will get returned */
 134 #define MMAL_BUFFER_HEADER_FLAG_USER0                  (1<<28)
 135 #define MMAL_BUFFER_HEADER_FLAG_USER1                  (1<<29)
 136 #define MMAL_BUFFER_HEADER_FLAG_USER2                  (1<<30)
 137 #define MMAL_BUFFER_HEADER_FLAG_USER3                  (1<<31)
 138 /* @} */
 139
 140 /** \name Video buffer header flags
 141  * \anchor videobufferheaderflags
 142  * The following flags describe properties of a video buffer header */
 143 #define MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START (1<<16)
 144 /* @{ */
 145 /** Signals an interlaced video frame */
 146 #define MMAL_BUFFER_HEADER_VIDEO_FLAG_INTERLACED       (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<0)
 147 /** Signals that the top field of the current interlaced frame should be displayed first */
 148 #define MMAL_BUFFER_HEADER_VIDEO_FLAG_TOP_FIELD_FIRST  (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<1)
 149 /** Signals that the buffer should be displayed on external display if attached. */
 150 #define MMAL_BUFFER_HEADER_VIDEO_FLAG_DISPLAY_EXTERNAL (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<3)
 151 /** Signals that contents of the buffer requires copy protection. */
 152 #define MMAL_BUFFER_HEADER_VIDEO_FLAG_PROTECTED        (MMAL_BUFFER_HEADER_FLAG_FORMAT_SPECIFIC_START<<4)
 153 /* @} */
 154
 155 /** Acquire a buffer header.
 156  * Acquiring a buffer header increases a reference counter on it and makes sure that the
 157  * buffer header won't be recycled until all the references to it are gone.
 158  * This is useful for instance if a component needs to return a buffer header but still needs
 159  * access to it for some internal processing (e.g. reference frames in video codecs).
 160  *
 161  * @param header buffer header to acquire
 162  */
 163 void mmal_buffer_header_acquire(MMAL_BUFFER_HEADER_T *header);
 164
 165 /** Reset a buffer header.
 166  * Resets all header variables to default values.
 167  *
 168  * @param header buffer header to reset
 169  */
 170 void mmal_buffer_header_reset(MMAL_BUFFER_HEADER_T *header);
 171
 172 /** Release a buffer header.
 173  * Releasing a buffer header will decrease its reference counter and when no more references
 174  * are left, the buffer header will be recycled by calling its 'release' callback function.
 175  *
 176  * If a pre-release callback is set (\ref MMAL_BH_PRE_RELEASE_CB_T), this will be invoked
 177  * before calling the buffer's release callback and potentially postpone buffer recycling.
 178  * Once pre-release is complete the buffer header is recycled with
 179  * \ref mmal_buffer_header_release_continue.
 180  *
 181  * @param header buffer header to release
 182  */
 183 void mmal_buffer_header_release(MMAL_BUFFER_HEADER_T *header);
 184
 185 /** Continue the buffer header release process.
 186  * This should be called to complete buffer header recycling once all pre-release activity
 187  * has been completed.
 188  *
 189  * @param header buffer header to release
 190  */
 191 void mmal_buffer_header_release_continue(MMAL_BUFFER_HEADER_T *header);
 192
 193 /** Buffer header pre-release callback.
 194  * The callback is invoked just before a buffer is released back into a
 195  * pool. This is used by clients who need to trigger additional actions
 196  * before the buffer can finally be released (e.g. wait for a bulk transfer
 197  * to complete).
 198  *
 199  * The callback should return TRUE if the buffer release need to be post-poned.
 200  *
 201  * @param header   buffer header about to be released
 202  * @param userdata user-specific data
 203  *
 204  * @return TRUE if the buffer should not be released
 205  */
 206 typedef MMAL_BOOL_T (*MMAL_BH_PRE_RELEASE_CB_T)(MMAL_BUFFER_HEADER_T *header, void *userdata);
 207
 208 /** Set a buffer header pre-release callback.
 209  * If the callback is NULL, the buffer will be released back into the pool
 210  * immediately as usual.
 211  *
 212  * @param header   buffer header to associate callback with
 213  * @param cb       pre-release callback to invoke
 214  * @param userdata user-specific data
 215  */
 216 void mmal_buffer_header_pre_release_cb_set(MMAL_BUFFER_HEADER_T *header, MMAL_BH_PRE_RELEASE_CB_T cb, void *userdata);
 217
 218 /** Replicate a buffer header into another one.
 219  * Replicating a buffer header will not only do an exact copy of all the public fields of the
 220  * buffer header (including data and alloc_size), but it will also acquire a reference to the
 221  * source buffer header which will only be released once the replicate has been released.
 222  *
 223  * @param dest buffer header into which to replicate
 224  * @param src buffer header to use as the source for the replication
 225  * @return MMAL_SUCCESS on success
 226  */
 227 MMAL_STATUS_T mmal_buffer_header_replicate(MMAL_BUFFER_HEADER_T *dest, MMAL_BUFFER_HEADER_T *src);
 228
 229 /** Lock the data buffer contained in the buffer header in memory.
 230  * This call does nothing on all platforms except VideoCore where it is needed to pin a
 231  * buffer in memory before any access to it.
 232  *
 233  * @param header buffer header to lock
 234  */
 235 MMAL_STATUS_T mmal_buffer_header_mem_lock(MMAL_BUFFER_HEADER_T *header);
 236
 237 /** Unlock the data buffer contained in the buffer header.
 238  * This call does nothing on all platforms except VideoCore where it is needed to un-pin a
 239  * buffer in memory after any access to it.
 240  *
 241  * @param header buffer header to unlock
 242  */
 243 void mmal_buffer_header_mem_unlock(MMAL_BUFFER_HEADER_T *header);
 244
 245 /* @} */
 246
 247 #ifdef __cplusplus
 248 }
 249 #endif
 250
 251 #endif /* MMAL_BUFFER_H */