libdirac_decoder/dirac_parser.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2 *
   3 * $Id$ $Name$
   4 *
   5 * Version: MPL 1.1/GPL 2.0/LGPL 2.1
   6 *
   7 * The contents of this file are subject to the Mozilla Public License
   8 * Version 1.1 (the "License"); you may not use this file except in compliance
   9 * with the License. You may obtain a copy of the License at
  10 * http://www.mozilla.org/MPL/
  11 *
  12 * Software distributed under the License is distributed on an "AS IS" basis,
  13 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
  14 * the specific language governing rights and limitations under the License.
  15 *
  16 * The Original Code is BBC Research and Development code.
  17 *
  18 * The Initial Developer of the Original Code is the British Broadcasting
  19 * Corporation.
  20 * Portions created by the Initial Developer are Copyright (C) 2004.
  21 * All Rights Reserved.
  22 *
  23 * Contributor(s): Anuradha Suraparaju (Original Author)
  24 *                 Andrew Kennedy
  25 *
  26 * Alternatively, the contents of this file may be used under the terms of
  27 * the GNU General Public License Version 2 (the "GPL"), or the GNU Lesser
  28 * Public License Version 2.1 (the "LGPL"), in which case the provisions of
  29 * the GPL or the LGPL are applicable instead of those above. If you wish to
  30 * allow use of your version of this file only under the terms of the either
  31 * the GPL or LGPL and not to allow others to use your version of this file
  32 * under the MPL, indicate your decision by deleting the provisions above
  33 * and replace them with the notice and other provisions required by the GPL
  34 * or LGPL. If you do not delete the provisions above, a recipient may use
  35 * your version of this file under the terms of any one of the MPL, the GPL
  36 * or the LGPL.
  37 * ***** END LICENSE BLOCK ***** */
  38
  39 #ifndef DIRAC_PARSER_H
  40 #define DIRAC_PARSER_H
  41
  42 #include <libdirac_common/dirac_types.h>
  43 #include <libdirac_decoder/decoder_types.h>
  44
  45 /*! \file
  46 \brief C interface to Dirac decoder.
  47
  48  A set of 'C' functions that define the public interface to the Dirac decoder.
  49  Refer to the the reference decoder source code, decoder/decmain.cpp for
  50  an example of how to use the "C" interface. The pseudocode below gives
  51  a brief description of the "C" interface usage.
  52
  53 \verbatim
  54  #include <libdirac_decoder/dirac_parser.h>\n
  55  Initialise the decoder
  56
  57  dirac_decoder_t *decoder_handle = dirac_decoder_init();
  58  do
  59  {
  60      dirac_decoder_state_t state = dirac_parse (decoder_handle);
  61      switch (state)
  62      {
  63      case STATE_BUFFER:
  64          read more data.
  65          Pass data to the decoder.
  66          dirac_buffer (decoder_handle, data_start, data_end)
  67          break;
  68
  69      case STATE_SEQUENCE:
  70          handle start of sequence.
  71          The decoder returns the sequence parameters in the
  72          seq_params member of the decoder handle.
  73          Allocate space for the frame data buffers and pass
  74          this to the decoder.
  75          dirac_set_buf (decoder_handle, buf, NULL);
  76          break;
  77
  78      case STATE_SEQUENCE_END:
  79          Deallocate frame data buffers
  80          break;
  81
  82      case STATE_PICTURE_AVAIL:
  83          Handle picture data.
  84          The decoder sets the fbuf member in the decoder
  85          handle to the frame decoded.
  86          break;
  87
  88      case STATE_INVALID:
  89          Unrecoverable error. Stop all processing
  90          break;
  91      }
  92  } while (data available && decoder state != STATE_INVALID
  93
  94  Free the decoder resources
  95  dirac_decoder_close(decoder_handle)
  96  \endverbatim
  97 */
  98 #ifdef __cplusplus
  99 extern "C" {
 100 #endif
 101
 102 typedef DecoderState dirac_decoder_state_t;
 103
 104 /*! Structure that holds the information returned by the parser */
 105 typedef struct
 106 {
 107     /*! parser state */
 108     dirac_decoder_state_t state;
 109     /*! parse parameters */
 110     dirac_parseparams_t parse_params;
 111     /*! source parameters */
 112     dirac_sourceparams_t src_params;
 113     /*! frame (NOT picture) number */
 114     unsigned int frame_num;
 115     /*! void pointer to internal parser */
 116     void *parser;
 117     /*! frame (NOT picture) buffer to hold luma and chroma data */
 118     dirac_framebuf_t *fbuf;
 119     /*! boolean flag that indicates if a decoded frame (NOT picture) is available */
 120     int frame_avail;
 121     /*! verbose output */
 122     int verbose;
 123
 124 } dirac_decoder_t;
 125
 126 /*!
 127     Decoder Init
 128     Initialise the decoder.
 129     \param  verbose boolean flag to set verbose output
 130     \return decoder handle
 131 */
 132 extern DllExport dirac_decoder_t *dirac_decoder_init(int verbose);
 133
 134 /*!
 135     Release the decoder resources
 136     \param decoder  Decoder object
 137 */
 138 extern DllExport void dirac_decoder_close(dirac_decoder_t *decoder);
 139
 140 /*!
 141     Parses the data in the input buffer. This function returns the
 142     following values.
 143     \n STATE_BUFFER:         Not enough data in internal buffer to process
 144     \n STATE_SEQUENCE:       Start of sequence detected. The seq_params member
 145                              in the decoder object is set to the details of the
 146                              next sequence to be processed.
 147     \n STATE_PICTURE_START:  Start of picture detected. The frame_params member
 148                              of the decoder object is set to the details of the
 149                              next frame to be processed.
 150     \n STATE_PICTURE_AVAIL:  Decoded picture available. The frame_aprams member
 151                              of the decoder object is set the the details of
 152                              the decoded frame available. The fbuf member of
 153                              the decoder object has the luma and chroma data of
 154                              the decompressed frame.
 155     \n STATE_SEQUENCE_END:   End of sequence detected.
 156     \n STATE_INVALID:        Invalid stream. Stop further processing.
 157
 158     \param decoder  Decoder object
 159     \return         Decoder state
 160
 161 */
 162 extern DllExport dirac_decoder_state_t dirac_parse (dirac_decoder_t *decoder);
 163
 164 /*!
 165     Copy data into internal buffer
 166     \param decoder  Decoder object
 167     \param start    Start of data
 168     \param end      End of data
 169 */
 170 extern DllExport void dirac_buffer (dirac_decoder_t *decoder, unsigned char *start, unsigned char *end);
 171
 172 /*!
 173     Set the output buffer into which the decoder copies the decoded data
 174     \param decoder  Decoder object
 175     \param buf      Array of char buffers to hold luma and chroma data
 176     \param id       User data
 177 */
 178 extern DllExport void dirac_set_buf (dirac_decoder_t *decoder, unsigned char *buf[3], void *id);
 179
 180 #ifdef __cplusplus
 181 }
 182 #endif
 183 #endif