src/parser/parser.h

   1 /* ***** BEGIN LICENSE BLOCK *****
   2 *
   3 * $Id: parser.h 40 2008-02-10 18:02:04Z andrea $
   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 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) 2007.
  21 * All Rights Reserved.
  22 *
  23 * Contributor(s): Andrea Gabriellini (Original Author)
  24 *
  25 * Alternatively, the contents of this file may be used under the terms of
  26 * the GNU General Public License Version 2 (the "GPL"), or the GNU Lesser
  27 * Public License Version 2.1 (the "LGPL"), in which case the provisions of
  28 * the GPL or the LGPL are applicable instead of those above. If you wish to
  29 * allow use of your version of this file only under the terms of the either
  30 * the GPL or LGPL and not to allow others to use your version of this file
  31 * under the MPL, indicate your decision by deleting the provisions above
  32 * and replace them with the notice and other provisions required by the GPL
  33 * or LGPL. If you do not delete the provisions above, a recipient may use
  34 * your version of this file under the terms of any one of the MPL, the GPL
  35 * or the LGPL.
  36 * ***** END LICENSE BLOCK ***** */
  37
  38 #ifndef _PARSER_H_
  39 #define _PARSER_H_
  40
  41
  42 #include <common/dirac.h>
  43
  44 #include <string.h>
  45
  46 #ifdef  __cplusplus
  47
  48 namespace dirac
  49 {
  50 namespace parser_project
  51 {
  52 extern "C" {
  53
  54 #endif
  55
  56   /*! The parser interface expects the user to manage the buffer containing
  57       the bitstream to parse. The API accepts a reference to a cursor into
  58       the buffer, pointing to the current parsing position in the stream.
  59       The parser API will move the cursor along the buffer, looking for
  60       the required type of access unit. If the cursor is already pointing
  61       to the start of the desired access unit the API will not move
  62       the cursor forward.
  63       The API also offers a function to move the cursor forward by exactly
  64       one access unit; this function is to be used once the stream is in sync.
  65       In this case the client can invoke a "get" followed by a "move".
  66       All functions return 0 in case of failure and non-zero upon success.
  67       In case of failure the cursor will be moved as far forward as possible.
  68       Non-zero is only returned if the entire access unit is contained in
  69       the passed buffer.
  70
  71       While parsing the stream backwards the cursor will be moved to the start
  72       of the first access unit which occurs entirely before the current position
  73       of the cursor.
  74       The API expects all pointers to be not NULL. Undefined behaviour
  75       will ensue if this is not the case.   */
  76
  77   /*! scans the passed buffer from the cursor position forward for up to
  78       buffer_size_fwd bytes looking for a sequence header entirely contained
  79       in the buffer. If found, the cursor position is moved to the start
  80       of the sequence header while the length of the access unit is saved
  81       in seq_hdr_size_reference.
  82       Returns non-zero upon success, when the cursor and seq_hdr_size_reference
  83       are changed, zero upon failure, when the cursor is moved as much forward
  84       as possible in the buffer. seq_hdr_size_reference is not changed in this
  85       case.
  86       cursor_reference and seq_hdr_size_reference cannot be null    */
  87   int
  88   dirac_parser_get_sequence_header    ( uint8 const** cursor_reference
  89                                       , size_t        buffer_size_fwd
  90                                       , size_t*       seq_hdr_size_reference );
  91
  92   /*! same as above but for the pictures  */
  93   int
  94   dirac_parser_get_next_picture       ( uint8 const** cursor_reference
  95                                       , size_t        buffer_size_fwd
  96                                       , size_t*       pic_size_reference );
  97
  98   /*! same as above but for any type of access unit  */
  99   int
 100   dirac_parser_get_next_access_unit   ( uint8 const** cursor_reference
 101                                       , size_t        buffer_size_fwd
 102                                       , size_t*       acc_unit_size_reference );
 103
 104   /*! same as above but only for i pictures */
 105   int
 106   dirac_parser_get_next_i_picture     ( uint8 const** cursor_reference
 107                                       , size_t        buffer_size_fwd
 108                                       , size_t*       pic_size_reference );
 109
 110   /*! scans the passed buffer forward or backward looking for a picture.
 111       The size of the available buffer is given by the sum of buffer_size_fwd
 112       and buffer_size_bwd. If scanning forward, n==0 means get the next pic,
 113       n==1 means the next + 1, etc. Negative values equates to scanning the
 114       buffer backward, so n==-1 means fetching the first picture entirely
 115       contained in the buffer and ending before the current position of the
 116       cursor.
 117       The function will move the cursor while trying to find the required pic.
 118       It returns non-zero upon success, when the cursor will be moved
 119       to the start of the required pic and pic_size_reference carries the
 120       length of the pic. Returns zero upon failure, when the cursor is moved
 121       as far forward (or backward, for negative values of n) as possible
 122       while pic_size_reference is not modified.
 123       n is decreased according to the pics found by the function scanning
 124       cursor_reference, n and pic_size_reference cannot be null   */
 125   int
 126   dirac_parser_get_picture_skip_n     ( uint8 const** cursor_reference
 127                                       , size_t        buffer_size_fwd
 128                                       , size_t        buffer_size_bwd
 129                                       , int*          n
 130                                       , size_t*       pic_size_reference );
 131
 132   /*! same as above but for intra pictures only   */
 133   int
 134   dirac_parser_get_i_picture_skip_n   ( uint8 const** cursor_reference
 135                                       , size_t        buffer_size_fwd
 136                                       , size_t        buffer_size_bwd
 137                                       , int*          n
 138                                       , size_t*       pic_size_reference );
 139
 140   /*! cursor_reference is a reference to the current position of the cursor
 141       in the client-provided buffer. buffer_size_fwd is the available data
 142       in the buffer past the cursor, buffer_size_bwd is the available data
 143       before the cursor (to be used for scanning the buffer backwards).
 144       picture_size is a reference to the size of the i picture parsed by this
 145       function. It will be set to 0 if it cannot find an I picture   */
 146   int
 147   dirac_parser_get_previous_i_picture ( uint8 const** cursor_reference
 148                                       , size_t        buffer_size_fwd
 149                                       , size_t        buffer_size_bwd
 150                                       , size_t*       pic_size_reference );
 151
 152   /*! move the cursor by one access unit - this function should be used once
 153       the stream is in sync, ie we have already parsed at least one
 154       access unit.
 155       The function expects the cursor to point to the start of an access unit
 156       and that the entire access unit is contained in the passed buffer.
 157       It returns 0 if it cannot move the cursor to the start of the next access
 158       unit (this includes if it is on the last access unit in the buffer),
 159       non zero upon success.
 160       Note that you don't need to move the cursor if you're scanning the stream
 161       backwards, since it is assumed that the user is looking for the previous
 162       access unit, which should end one byte before the position pointed by the
 163       passed cursor.
 164       The cursor cannot be null (same applies to its reference)
 165       buffer_size_fwd carries the number of available bytes in the buffer
 166       from the cursor's position (scanning forward).  */
 167   int
 168   dirac_parser_move_cursor_fwd        ( uint8 const** cursor_reference
 169                                       , size_t        buffer_size_fwd );
 170
 171   /*! the following group of functions are self-explanatory: the functions
 172       return 0 if the passed buffer doesn't contain the expected type
 173       of dirac access unit, and non zero otherwise.
 174       Note that cursor must point to the start of the access unit;
 175       the entire access unit must be contained in the passed buffer for
 176       this function to return non-zero.
 177       The cursor cannot be null.     */
 178   int
 179   dirac_parser_is_access_unit         ( uint8 const*  cursor
 180                                       , size_t        buffer_size_fwd );
 181   int
 182   dirac_parser_is_sequence_header     ( uint8 const*  cursor
 183                                       , size_t        buffer_size_fwd );
 184   int
 185   dirac_parser_is_picture             ( uint8 const*  cursor
 186                                       , size_t        buffer_size_fwd );
 187   int
 188   dirac_parser_is_i_picture           ( uint8 const*  cursor
 189                                       , size_t        buffer_size_fwd );
 190   int
 191   dirac_parser_is_auxiliary_data      ( uint8 const*  cursor
 192                                       , size_t        buffer_size_fwd );
 193   int
 194   dirac_parser_is_padding_data        ( uint8 const*  cursor
 195                                       , size_t        buffer_size_fwd );
 196   int
 197   dirac_parser_is_end_of_sequence     ( uint8 const*  cursor
 198                                       , size_t        buffer_size_fwd );
 199   int
 200   dirac_parser_is_last_end_of_sequence
 201                                       ( uint8 const*  cursor
 202                                       , size_t        buffer_size_fwd );
 203
 204   /*! to be used on access units containing pictures - this function expects
 205       the cursor to point to the start of an access unit and contain a picture.
 206       Failure to ensure that will result in undefined behaviour.
 207       It will check that there is enough data to decode the entire picture.
 208       It will return 0 if it cannot decode the picture number (eg, because
 209       the buffer doesn't contain an access unit or because the buffer is not
 210       long enough or doesn't start with an access unit) and pic_number will
 211       not be changed.
 212       It will return non zero if successful and will set *pic_number to
 213       the picture number.
 214       cursor cannot be null, cursor must point to start of picture access unit
 215       or else undefined behaviour  */
 216   int
 217   dirac_parser_get_picture_number     ( uint8 const*  cursor
 218                                       , size_t        size
 219                                       , uint32*       pic_number_reference );
 220
 221   /*! current version of this API */
 222   int
 223   dirac_parser_get_version_major();
 224   int
 225   dirac_parser_get_version_minor();
 226   int
 227   dirac_parser_get_revision();
 228
 229 #ifdef __cplusplus
 230
 231 } /* extern "C" */
 232
 233 } /* parser_project */
 234
 235 } /* dirac */
 236
 237
 238 /* we'll use this alias for the Parser module */
 239 namespace parser = ::dirac::parser_project;
 240
 241 #endif
 242
 243 #endif /* _PARSER_H_ */