containers/packetizers.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 #ifndef VC_PACKETIZERS_H
  28 #define VC_PACKETIZERS_H
  29
  30 /** \file packetizers.h
  31  * Public API for packetizing data (i.e. framing and timestamping)
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 #include "containers/containers.h"
  39
  40 /** \defgroup VcPacketizerApi Packetizer API
  41  *  API for packetizers */
  42 /* @{ */
  43
  44 /** \name Packetizer flags
  45  * \anchor packetizerflags
  46  * The following flags describe properties of a packetizer */
  47 /* @{ */
  48 #define VC_PACKETIZER_FLAG_ES_CHANGED 0x1 /**< ES definition has changed */
  49 /* @} */
  50
  51 /** Definition of the packetizer type */
  52 typedef struct VC_PACKETIZER_T
  53 {
  54    struct VC_PACKETIZER_PRIVATE_T *priv; /**< Private member used by the implementation */
  55    uint32_t flags;                       /**< Flags describing the properties of a packetizer.
  56                                            * See \ref packetizerflags "Packetizer flags". */
  57
  58    VC_CONTAINER_ES_FORMAT_T *in;  /**< Format of the input elementary stream */
  59    VC_CONTAINER_ES_FORMAT_T *out;  /**< Format of the output elementary stream */
  60
  61    uint32_t max_frame_size; /**< Maximum size of a packetized frame */
  62
  63 } VC_PACKETIZER_T;
  64
  65 /** Open a packetizer to convert the input format into the requested output format.
  66  * This will create an an instance of a packetizer and its associated context.
  67  *
  68  * If no packetizer is found for the requested format, this will return a null pointer as well as
  69  * an error code indicating why this failed.
  70  *
  71  * \param  in           Input elementary stream format
  72  * \param  out_variant  Requested output variant for the output elementary stream format
  73  * \param  status       Returns the status of the operation
  74  * \return              A pointer to the context of the new instance of the packetizer.
  75  *                      Returns NULL on failure.
  76  */
  77 VC_PACKETIZER_T *vc_packetizer_open(VC_CONTAINER_ES_FORMAT_T *in, VC_CONTAINER_FOURCC_T out_variant,
  78    VC_CONTAINER_STATUS_T *status);
  79
  80 /** Closes an instance of a packetizer.
  81  * This will free all the resources associated with the context.
  82  *
  83  * \param  context   Pointer to the context of the instance to close
  84  * \return           the status of the operation
  85  */
  86 VC_CONTAINER_STATUS_T vc_packetizer_close( VC_PACKETIZER_T *context );
  87
  88 /** \name Packetizer flags
  89  * The following flags can be passed during a packetize call */
  90 /* @{ */
  91 /** Type definition for the packetizer flags */
  92 typedef uint32_t VC_PACKETIZER_FLAGS_T;
  93 /** Ask the packetizer to only return information on the next packet without reading it */
  94 #define VC_PACKETIZER_FLAG_INFO   0x1
  95 /** Ask the packetizer to skip the next packet */
  96 #define VC_PACKETIZER_FLAG_SKIP   0x2
  97 /** Ask the packetizer to flush any data being processed */
  98 #define VC_PACKETIZER_FLAG_FLUSH   0x4
  99 /** Force the packetizer to release an input packet */
 100 #define VC_PACKETIZER_FLAG_FORCE_RELEASE_INPUT 0x8
 101 /* @} */
 102
 103 /** Push a new packet of data to the packetizer.
 104  * This is the mechanism used to feed data into the packetizer. Once a packet has been
 105  * pushed into the packetizer it is owned by the packetizer until released by a call to
 106  * \ref vc_packetizer_pop
 107  *
 108  * \param  context   Pointer to the context of the packetizer to use
 109  * \param  packet    Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
 110  *                   to push into the packetizer.
 111  * \return           the status of the operation
 112  */
 113 VC_CONTAINER_STATUS_T vc_packetizer_push( VC_PACKETIZER_T *context,
 114    VC_CONTAINER_PACKET_T *packet);
 115
 116 /** Pop a packet of data from the packetizer.
 117  * This allows the client to retrieve consumed data from the packetizer. Packets returned by
 118  * the packetizer in this manner can then be released / recycled by the client.
 119  * It is possible for the client to retrieve non-consumed data by passing the
 120  * VC_PACKETIZER_FLAG_FORCE_RELEASE_INPUT flag. This will however trigger some internal buffering
 121  * inside the packetizer and thus is less efficient.
 122  *
 123  * \param  context   Pointer to the context of the packetizer to use
 124  * \param  packet    Pointer used to return a consumed packet
 125  * \param  flags     Miscellaneous flags controlling the operation
 126  *
 127  * \return           VC_CONTAINER_SUCCESS if a consumed packet was retrieved,
 128  *                   VC_CONTAINER_ERROR_INCOMPLETE_DATA if none is available.
 129  */
 130 VC_CONTAINER_STATUS_T vc_packetizer_pop( VC_PACKETIZER_T *context,
 131    VC_CONTAINER_PACKET_T **packet, VC_PACKETIZER_FLAGS_T flags);
 132
 133 /** Read packetized data out of the packetizer.
 134  *
 135  * \param  context   Pointer to the context of the packetizer to use
 136  * \param  packet    Pointer to the VC_CONTAINER_PACKET_T structure describing the data packet
 137  *                   This might need to be partially filled before the call (buffer, buffer_size)
 138  *                   depending on the flags used.
 139  * \param  flags     Miscellaneous flags controlling the operation
 140  * \return           the status of the operation
 141  */
 142 VC_CONTAINER_STATUS_T vc_packetizer_read( VC_PACKETIZER_T *context,
 143    VC_CONTAINER_PACKET_T *out, VC_PACKETIZER_FLAGS_T flags);
 144
 145 /** Reset packetizer state.
 146  * This will reset the state of the packetizer as well as mark all data pushed to it as consumed.
 147  *
 148  * \param  context   Pointer to the context of the packetizer to reset
 149  * \return           the status of the operation
 150  */
 151 VC_CONTAINER_STATUS_T vc_packetizer_reset( VC_PACKETIZER_T *context );
 152
 153 /* @} */
 154
 155 #ifdef __cplusplus
 156 }
 157 #endif
 158
 159 #endif /* VC_PACKETIZERS_H */