theora/lib/internal.h

   1 /********************************************************************
   2  *                                                                  *
   3  * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE.   *
   4  * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
   5  * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
   6  * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
   7  *                                                                  *
   8  * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2007                *
   9  * by the Xiph.Org Foundation http://www.xiph.org/                  *
  10  *                                                                  *
  11  ********************************************************************
  12
  13   function:
  14     last mod: $Id$
  15
  16  ********************************************************************/
  17
  18 #if !defined(_internal_H)
  19 # define _internal_H (1)
  20 # include <stdlib.h>
  21 # if defined(HAVE_CONFIG_H)
  22 #  include <config.h>
  23 # endif
  24 # include "theora/codec.h"
  25 # include "theora/theora.h"
  26 # include "dec/ocintrin.h"
  27 # include "dec/huffman.h"
  28 # include "dec/quant.h"
  29
  30 /*Thank you Microsoft, I know the order of operations.*/
  31 # if defined(_MSC_VER)
  32 #  pragma warning(disable:4554) /* order of operations */
  33 #  pragma warning(disable:4799) /* disable missing EMMS warnings */
  34 # endif
  35
  36 /*This library's version.*/
  37 # define OC_VENDOR_STRING "Xiph.Org libTheora I 20071025 3 2 1"
  38
  39 /*Theora bitstream version.*/
  40 # define TH_VERSION_MAJOR (3)
  41 # define TH_VERSION_MINOR (2)
  42 # define TH_VERSION_SUB   (1)
  43 # define TH_VERSION_CHECK(_info,_maj,_min,_sub) \
  44  ((_info)->version_major>(_maj)||(_info)->version_major==(_maj)&& \
  45  ((_info)->version_minor>(_min)||(_info)->version_minor==(_min)&& \
  46  (_info)->version_subminor>=(_sub)))
  47
  48 /*A keyframe.*/
  49 #define OC_INTRA_FRAME (0)
  50 /*A predicted frame.*/
  51 #define OC_INTER_FRAME (1)
  52 /*A frame of unknown type (frame type decision has not yet been made).*/
  53 #define OC_UNKWN_FRAME (-1)
  54
  55 /*The amount of padding to add to the reconstructed frame buffers on all
  56    sides.
  57   This is used to allow unrestricted motion vectors without special casing.
  58   This must be a multiple of 2.*/
  59 #define OC_UMV_PADDING (16)
  60
  61 /*Frame classification indices.*/
  62 /*The previous golden frame.*/
  63 #define OC_FRAME_GOLD (0)
  64 /*The previous frame.*/
  65 #define OC_FRAME_PREV (1)
  66 /*The current frame.*/
  67 #define OC_FRAME_SELF (2)
  68
  69 /*The input or output buffer.*/
  70 #define OC_FRAME_IO   (3)
  71
  72 /*Macroblock modes.*/
  73 /*Macro block is invalid: It is never coded.*/
  74 #define OC_MODE_INVALID        (-1)
  75 /*Encoded difference from the same macro block in the previous frame.*/
  76 #define OC_MODE_INTER_NOMV     (0)
  77 /*Encoded with no motion compensated prediction.*/
  78 #define OC_MODE_INTRA          (1)
  79 /*Encoded difference from the previous frame offset by the given motion
  80   vector.*/
  81 #define OC_MODE_INTER_MV       (2)
  82 /*Encoded difference from the previous frame offset by the last coded motion
  83   vector.*/
  84 #define OC_MODE_INTER_MV_LAST  (3)
  85 /*Encoded difference from the previous frame offset by the second to last
  86   coded motion vector.*/
  87 #define OC_MODE_INTER_MV_LAST2 (4)
  88 /*Encoded difference from the same macro block in the previous golden
  89   frame.*/
  90 #define OC_MODE_GOLDEN_NOMV    (5)
  91 /*Encoded difference from the previous golden frame offset by the given motion
  92   vector.*/
  93 #define OC_MODE_GOLDEN_MV      (6)
  94 /*Encoded difference from the previous frame offset by the individual motion
  95   vectors given for each block.*/
  96 #define OC_MODE_INTER_MV_FOUR  (7)
  97 /*The number of (coded) modes.*/
  98 #define OC_NMODES              (8)
  99
 100 /*Macro block is not coded.*/
 101 #define OC_MODE_NOT_CODED      (8)
 102
 103 /*Predictor bit flags.*/
 104 /*Left.*/
 105 #define OC_PL  (1)
 106 /*Upper-left.*/
 107 #define OC_PUL (2)
 108 /*Up.*/
 109 #define OC_PU  (4)
 110 /*Upper-right.*/
 111 #define OC_PUR (8)
 112
 113 /*Constants for the packet state machine common between encoder and decoder.*/
 114
 115 /*Next packet to emit/read: Codec info header.*/
 116 #define OC_PACKET_INFO_HDR    (-3)
 117 /*Next packet to emit/read: Comment header.*/
 118 #define OC_PACKET_COMMENT_HDR (-2)
 119 /*Next packet to emit/read: Codec setup header.*/
 120 #define OC_PACKET_SETUP_HDR   (-1)
 121 /*No more packets to emit/read.*/
 122 #define OC_PACKET_DONE        (INT_MAX)
 123
 124
 125
 126 typedef struct oc_theora_state oc_theora_state;
 127
 128
 129
 130 /*A map from a super block to fragment numbers.*/
 131 typedef int         oc_sb_map[4][4];
 132 /*A map from a macro block to fragment numbers.*/
 133 typedef int         oc_mb_map[3][4];
 134 /*A motion vector.*/
 135 typedef signed char oc_mv[2];
 136
 137
 138
 139 /*Super block information.
 140   Super blocks are 32x32 segments of pixels in a single color plane indexed
 141    in image order.
 142   Internally, super blocks are broken up into four quadrants, each of which
 143    contains a 2x2 pattern of blocks, each of which is an 8x8 block of pixels.
 144   Quadrants, and the blocks within them, are indexed in a special order called
 145    a "Hilbert curve" within the super block.
 146
 147   In order to differentiate between the Hilbert-curve indexing strategy and
 148    the regular image order indexing strategy, blocks indexed in image order
 149    are called "fragments".
 150   Fragments are indexed in image order, left to right, then bottom to top,
 151    from Y plane to Cb plane to Cr plane.*/
 152 typedef struct{
 153   unsigned  coded_fully:1;
 154   unsigned  coded_partially:1;
 155   unsigned  quad_valid:4;
 156   oc_sb_map map;
 157 }oc_sb;
 158
 159
 160
 161 /*Macro block information.
 162   The co-located fragments in all image planes corresponding to the location of
 163    a single luma plane super block quadrant forms a macro block.
 164   Thus there is only a single set of macro blocks for all planes, which
 165    contains between 6 and 12 fragments, depending on the pixel format.
 166   Therefore macro block information is kept in a separate array from super
 167    blocks, to avoid unused space in the other planes.*/
 168 typedef struct{
 169   /*The current macro block mode.
 170     A negative number indicates the macro block lies entirely outside the
 171      coded frame.*/
 172   int           mode;
 173   /*The X location of the macro block's upper-left hand pixel.*/
 174   int           x;
 175   /*The Y location of the macro block's upper-right hand pixel.*/
 176   int           y;
 177   /*The fragments that belong to this macro block in each color plane.
 178     Fragments are stored in image order (left to right then top to bottom).
 179     When chroma components are decimated, the extra fragments have an index of
 180      -1.*/
 181   oc_mb_map     map;
 182 }oc_mb;
 183
 184
 185
 186 /*Information about a fragment which intersects the border of the displayable
 187    region.
 188   This marks which pixels belong to the displayable region, and is used to
 189    ensure that pixels outside of this region are never referenced.
 190   This allows applications to pass in buffers that are really the size of the
 191    displayable region without causing a seg fault.*/
 192 typedef struct{
 193   /*A bit mask marking which pixels are in the displayable region.
 194     Pixel (x,y) corresponds to bit (y<<3|x).*/
 195   ogg_int64_t mask;
 196   /*The number of pixels in the displayable region.
 197     This is always positive, and always less than 64.*/
 198   int         npixels;
 199 }oc_border_info;
 200
 201
 202
 203 /*Fragment information.*/
 204 typedef struct{
 205   /*A flag indicating whether or not this fragment is coded.*/
 206   unsigned        coded:1;
 207   /*A flag indicating that all of this fragment lies outside the displayable
 208      region of the frame.
 209     Note the contrast with an invalid macro block, which is outside the coded
 210      frame, not just the displayable one.*/
 211   unsigned        invalid:1;
 212   /*The quality index used for this fragment's AC coefficients.*/
 213   unsigned        qi:6;
 214   /*The mode of the macroblock this fragment belongs to.*/
 215   int             mbmode:8;
 216   /*The prediction-corrected DC component.
 217     Note that some compilers (e.g., Solaris's) will ignore the signedness of
 218      the type and treat this value as unsigned always, so it will need to be
 219      casted before being used.*/
 220   int             dc:16;
 221   /*A pointer to the portion of an image covered by this fragment in several
 222      images.
 223     The first three are reconstructed frame buffers, while the last is the
 224      input image buffer.
 225     The appropriate stride value is determined by the color plane the fragment
 226      belongs in.*/
 227   unsigned char  *buffer[4];
 228   /*Information for fragments which lie partially outside the displayable
 229      region.
 230     For fragments completely inside or outside this region, this is NULL.*/
 231   oc_border_info *border;
 232   /*The motion vector used for this fragment.*/
 233   oc_mv           mv;
 234 }oc_fragment;
 235
 236
 237
 238 /*A description of each fragment plane.*/
 239 typedef struct{
 240   /*The number of fragments in the horizontal direction.*/
 241   int nhfrags;
 242   /*The number of fragments in the vertical direction.*/
 243   int nvfrags;
 244   /*The offset of the first fragment in the plane.*/
 245   int froffset;
 246   /*The total number of fragments in the plane.*/
 247   int nfrags;
 248   /*The number of super blocks in the horizontal direction.*/
 249   int nhsbs;
 250   /*The number of super blocks in the vertical direction.*/
 251   int nvsbs;
 252   /*The offset of the first super block in the plane.*/
 253   int sboffset;
 254   /*The total number of super blocks in the plane.*/
 255   int nsbs;
 256 }oc_fragment_plane;
 257
 258
 259
 260 /*The shared (encoder and decoder) functions that have accelerated variants.*/
 261 typedef struct{
 262   void (*frag_recon_intra)(unsigned char *_dst,int _dst_ystride,
 263    const ogg_int16_t *_residue);
 264   void (*frag_recon_inter)(unsigned char *_dst,int _dst_ystride,
 265    const unsigned char *_src,int _src_ystride,const ogg_int16_t *_residue);
 266   void (*frag_recon_inter2)(unsigned char *_dst,int _dst_ystride,
 267    const unsigned char *_src1,int _src1_ystride,const unsigned char *_src2,
 268    int _src2_ystride,const ogg_int16_t *_residue);
 269   void (*state_frag_copy)(const oc_theora_state *_state,
 270    const int *_fragis,int _nfragis,int _dst_frame,int _src_frame,int _pli);
 271   void (*state_frag_recon)(oc_theora_state *_state,oc_fragment *_frag,
 272    int _pli,ogg_int16_t _dct_coeffs[128],int _last_zzi,int _ncoefs,
 273    ogg_uint16_t _dc_iquant,const ogg_uint16_t _ac_iquant[64]);
 274   void (*restore_fpu)(void);
 275   void (*state_loop_filter_frag_rows)(oc_theora_state *_state,int *_bv,
 276    int _refi,int _pli,int _fragy0,int _fragy_end);
 277 }oc_base_opt_vtable;
 278
 279
 280
 281 /*Common state information between the encoder and decoder.*/
 282 struct oc_theora_state{
 283   /*The stream information.*/
 284   th_info             info;
 285   /*Table for shared accelerated functions.*/
 286   oc_base_opt_vtable  opt_vtable;
 287   /*CPU flags to detect the presence of extended instruction sets.*/
 288   ogg_uint32_t        cpu_flags;
 289   /*The fragment plane descriptions.*/
 290   oc_fragment_plane   fplanes[3];
 291   /*The total number of fragments in a single frame.*/
 292   int                 nfrags;
 293   /*The list of fragments, indexed in image order.*/
 294   oc_fragment        *frags;
 295   /*The total number of super blocks in a single frame.*/
 296   int                 nsbs;
 297   /*The list of super blocks, indexed in image order.*/
 298   oc_sb              *sbs;
 299   /*The number of macro blocks in the X direction.*/
 300   int                 nhmbs;
 301   /*The number of macro blocks in the Y direction.*/
 302   int                 nvmbs;
 303   /*The total number of macro blocks.*/
 304   int                 nmbs;
 305   /*The list of macro blocks, indexed in super block order.
 306     That is, the macro block corresponding to the macro block mbi in (luma
 307      plane) super block sbi is (sbi<<2|mbi).*/
 308   oc_mb              *mbs;
 309   /*The list of coded fragments, in coded order.*/
 310   int                *coded_fragis;
 311   /*The number of coded fragments in each plane.*/
 312   int                 ncoded_fragis[3];
 313   /*The list of uncoded fragments.
 314     This just past the end of the list, which is in reverse order, and
 315      uses the same block of allocated storage as the coded_fragis list.*/
 316   int                *uncoded_fragis;
 317   /*The number of uncoded fragments in each plane.*/
 318   int                 nuncoded_fragis[3];
 319   /*The list of coded macro blocks in the Y plane, in coded order.*/
 320   int                *coded_mbis;
 321   /*The number of coded macro blocks in the Y plane.*/
 322   int                 ncoded_mbis;
 323   /*A copy of the image data used to fill the input pointers in each fragment.
 324     If the data pointers or strides change, these input pointers must be
 325      re-populated.*/
 326   th_ycbcr_buffer     input;
 327   /*The number of unique border patterns.*/
 328   int                 nborders;
 329   /*The storage for the border info for all border fragments.
 330     This data is pointed to from the appropriate fragments.*/
 331   oc_border_info      borders[16];
 332   /*The index of the buffers being used for each OC_FRAME_* reference frame.*/
 333   int                 ref_frame_idx[3];
 334   /*The actual buffers used for the previously decoded frames.*/
 335   th_ycbcr_buffer     ref_frame_bufs[3];
 336   /*The storage for the reference frame buffers.*/
 337   unsigned char      *ref_frame_data;
 338   /*The frame number of the last keyframe.*/
 339   ogg_int64_t         keyframe_num;
 340   /*The frame number of the current frame.*/
 341   ogg_int64_t         curframe_num;
 342   /*The granpos of the current frame.*/
 343   ogg_int64_t         granpos;
 344   /*The type of the current frame.*/
 345   int                 frame_type;
 346   /*The quality indices of the current frame.*/
 347   int                 qis[3];
 348   /*The number of quality indices used in the current frame.*/
 349   int                 nqis;
 350   /*The dequantization tables.*/
 351   oc_quant_table     *dequant_tables[2][3];
 352   oc_quant_tables     dequant_table_data[2][3];
 353   /*Loop filter strength parameters.*/
 354   unsigned char       loop_filter_limits[64];
 355 };
 356
 357
 358
 359 /*The function type used to fill in the chroma plane motion vectors for a
 360    macro block when 4 different motion vectors are specified in the luma
 361    plane.
 362   _cbmvs: The chroma block-level motion vectors to fill in.
 363   _lmbmv: The luma macro-block level motion vector to fill in for use in
 364            prediction.
 365   _lbmvs: The luma block-level motion vectors.*/
 366 typedef void (*oc_set_chroma_mvs_func)(oc_mv _cbmvs[4],const oc_mv _lbmvs[4]);
 367
 368
 369
 370 /*A map from the index in the zig zag scan to the coefficient number in a
 371    block.
 372   The extra 64 entries send out of bounds indexes to index 64.
 373   This is used to safely ignore invalid zero runs when decoding
 374    coefficients.*/
 375 extern const int OC_FZIG_ZAG[128];
 376 /*A map from the coefficient number in a block to its index in the zig zag
 377    scan.*/
 378 extern const int OC_IZIG_ZAG[64];
 379 /*The predictor frame to use for each macro block mode.*/
 380 extern const int OC_FRAME_FOR_MODE[OC_NMODES];
 381 /*A map from physical macro block ordering to bitstream macro block
 382    ordering within a super block.*/
 383 extern const int OC_MB_MAP[2][2];
 384 /*A list of the indices in the oc_mb.map array that can be valid for each of
 385    the various chroma decimation types.*/
 386 extern const int OC_MB_MAP_IDXS[TH_PF_NFORMATS][12];
 387 /*The number of indices in the oc_mb.map array that can be valid for each of
 388    the various chroma decimation types.*/
 389 extern const int OC_MB_MAP_NIDXS[TH_PF_NFORMATS];
 390 /*A table of functions used to fill in the Cb,Cr plane motion vectors for a
 391    macro block when 4 different motion vectors are specified in the luma
 392    plane.*/
 393 extern const oc_set_chroma_mvs_func OC_SET_CHROMA_MVS_TABLE[TH_PF_NFORMATS];
 394
 395
 396
 397 int oc_ilog(unsigned _v);
 398 void **oc_malloc_2d(size_t _height,size_t _width,size_t _sz);
 399 void **oc_calloc_2d(size_t _height,size_t _width,size_t _sz);
 400 void oc_free_2d(void *_ptr);
 401
 402 void oc_ycbcr_buffer_flip(th_ycbcr_buffer _dst,
 403  const th_ycbcr_buffer _src);
 404
 405 int oc_dct_token_skip(int _token,int _extra_bits);
 406
 407 int oc_frag_pred_dc(const oc_fragment *_frag,
 408  const oc_fragment_plane *_fplane,int _x,int _y,int _pred_last[3]);
 409
 410 int oc_state_init(oc_theora_state *_state,const th_info *_info);
 411 void oc_state_clear(oc_theora_state *_state);
 412 void oc_state_vtable_init_c(oc_theora_state *_state);
 413 void oc_state_borders_fill_rows(oc_theora_state *_state,int _refi,int _pli,
 414  int _y0,int _yend);
 415 void oc_state_borders_fill_caps(oc_theora_state *_state,int _refi,int _pli);
 416 void oc_state_borders_fill(oc_theora_state *_state,int _refi);
 417 void oc_state_fill_buffer_ptrs(oc_theora_state *_state,int _buf_idx,
 418  th_ycbcr_buffer _img);
 419 int oc_state_mbi_for_pos(oc_theora_state *_state,int _mbx,int _mby);
 420 int oc_state_get_mv_offsets(oc_theora_state *_state,int *_offsets,
 421  int _dx,int _dy,int _ystride,int _pli);
 422
 423 int oc_state_loop_filter_init(oc_theora_state *_state,int *_bv);
 424 void oc_state_loop_filter(oc_theora_state *_state,int _frame);
 425 #if defined(OC_DUMP_IMAGES)
 426 int oc_state_dump_frame(const oc_theora_state *_state,int _frame,
 427  const char *_suf);
 428 #endif
 429
 430 /*Shared accelerated functions.*/
 431 void oc_frag_recon_intra(const oc_theora_state *_state,
 432  unsigned char *_dst,int _dst_ystride,const ogg_int16_t *_residue);
 433 void oc_frag_recon_inter(const oc_theora_state *_state,
 434  unsigned char *_dst,int _dst_ystride,
 435  const unsigned char *_src,int _src_ystride,const ogg_int16_t *_residue);
 436 void oc_frag_recon_inter2(const oc_theora_state *_state,
 437  unsigned char *_dst,int _dst_ystride,
 438  const unsigned char *_src1,int _src1_ystride,const unsigned char *_src2,
 439  int _src2_ystride,const ogg_int16_t *_residue);
 440 void oc_state_frag_copy(const oc_theora_state *_state,const int *_fragis,
 441  int _nfragis,int _dst_frame,int _src_frame,int _pli);
 442 void oc_state_frag_recon(oc_theora_state *_state,oc_fragment *_frag,
 443  int _pli,ogg_int16_t _dct_coeffs[128],int _last_zzi,int _ncoefs,
 444  ogg_uint16_t _dc_iquant,const ogg_uint16_t _ac_iquant[64]);
 445 void oc_state_loop_filter_frag_rows(oc_theora_state *_state,int *_bv,
 446  int _refi,int _pli,int _fragy0,int _fragy_end);
 447 void oc_restore_fpu(const oc_theora_state *_state);
 448
 449 /*Default pure-C implementations.*/
 450 void oc_frag_recon_intra_c(unsigned char *_dst,int _dst_ystride,
 451  const ogg_int16_t *_residue);
 452 void oc_frag_recon_inter_c(unsigned char *_dst,int _dst_ystride,
 453  const unsigned char *_src,int _src_ystride,const ogg_int16_t *_residue);
 454 void oc_frag_recon_inter2_c(unsigned char *_dst,int _dst_ystride,
 455  const unsigned char *_src1,int _src1_ystride,const unsigned char *_src2,
 456  int _src2_ystride,const ogg_int16_t *_residue);
 457 void oc_state_frag_copy_c(const oc_theora_state *_state,const int *_fragis,
 458  int _nfragis,int _dst_frame,int _src_frame,int _pli);
 459 void oc_state_frag_recon_c(oc_theora_state *_state,oc_fragment *_frag,
 460  int _pli,ogg_int16_t _dct_coeffs[128],int _last_zzi,int _ncoefs,
 461  ogg_uint16_t _dc_iquant,const ogg_uint16_t _ac_iquant[64]);
 462 void oc_state_loop_filter_frag_rows_c(oc_theora_state *_state,int *_bv,
 463  int _refi,int _pli,int _fragy0,int _fragy_end);
 464 void oc_restore_fpu_c(void);
 465
 466 /*We need a way to call a few encoder functions without introducing a link-time
 467    dependency into the decoder, while still allowing the old alpha API which
 468    does not distinguish between encoder and decoder objects to be used.
 469   We do this by placing a function table at the start of the encoder object
 470    which can dispatch into the encoder library.
 471   We do a similar thing for the decoder in case we ever decide to split off a
 472    common base library.*/
 473 typedef void (*oc_state_clear_func)(theora_state *_th);
 474 typedef int (*oc_state_control_func)(theora_state *th,int req,
 475  void *buf,size_t buf_sz);
 476 typedef ogg_int64_t (*oc_state_granule_frame_func)(theora_state *_th,
 477  ogg_int64_t _granulepos);
 478 typedef double (*oc_state_granule_time_func)(theora_state *_th,
 479  ogg_int64_t _granulepos);
 480
 481 typedef struct oc_state_dispatch_vtbl oc_state_dispatch_vtbl;
 482
 483 struct oc_state_dispatch_vtbl{
 484   oc_state_clear_func         clear;
 485   oc_state_control_func       control;
 486   oc_state_granule_frame_func granule_frame;
 487   oc_state_granule_time_func  granule_time;
 488 };
 489
 490 #endif