theora-exp/README

   1 These libraries were created to allow me to run my own personal experiments
   2  with Theora.
   3 They are not currently part of the official Theora distribution.
   4 Although they are based upon the VP3.2 and Theora source, which as of the time
   5  of this writing serve as the only complete documentation of the VP3 and Theora
   6  formats, they were written from scratch.
   7
   8 Decoder:
   9 The decoder here is feature-complete, up to and including all planned bitstream
  10  features for the initial Theora release.
  11 Some of these are not yet present even in the reference decoder. This decoder
  12 is strictly better than the reference decoder - it is both more complete, more
  13 secure, and faster.
  14 These include:
  15 - Support for non-VP3 style quantization matrices (i.e., complete support for
  16    the additional flexibility added to the quantization matrix specification).
  17 - Support for additional pixel formats: 4:4:4 and 4:2:2 (in addition to the
  18    4:2:0 format supported by VP3).
  19 - Support for block-level qi values.
  20 Additional features of the new library design:
  21 - Improved API design.
  22   Internal structures are hidden better, making it easier to upgrade the
  23    library and maintain binary compatibility.
  24   Generic ioctl-style API allows some encoder and decoder parameters to be
  25    modified on the fly, and provides a route of future extensibility.
  26   Additional minor improvements.
  27 - The decoder library is completely separated from the encoder library, so
  28    applications need only link against the portions they use.
  29 - Hardened against invalid video data.
  30   Special attention has been paid to eliminate possible buffer overflows and
  31    access violations when receiving invalid video data, for better security.
  32 - A backwards-compatibility API wrapper, for applications that use the older
  33   libtheora API.
  34 Algorithmic optimizations:
  35 - DCT token and motion vector decoding have been optimized to use fewer calls
  36    to oggpackB_read().
  37 - All DCT tokens are decoded in an initial pass.
  38   This allows us to buffer the tokens, instead of the complete set of DCT
  39    coefficients, yielding a reduced memory footprint and increased cache
  40    coherency.
  41 - Striped decoding API.
  42   After the tokens are decoded, the remaining steps are pipelined and clients
  43    receive decoded frame data as soon as it is available, while it is still in
  44    cache.
  45 Currently missing features:
  46 - Advanced buffering API: Client-specified buffers.
  47   Clients could provide external buffers to decode into when out-of-loop
  48    post-processing is enabled (if it isn't enabled, a copy has to be done
  49    anyway).
  50
  51 Encoder:
  52 The encoder is highly experimental.
  53 It currently generates bitstreams using ALL of the decoder features supported
  54  above.
  55 There are still a few outstanding bugs, and the HVS model is very experimental.
  56 The encoder is not built by default.
  57
  58 Compatibility Layer:
  59 theora-exp comes with a compatibility layer for libtheora so it can be used
  60 as a drop in replacement(only decoding right now). To do so, just change your
  61 pkg-config call from "theora" to "theoracompat"
  62
  63 Building:
  64 On Unix or Cygwin, building through automake is now supported.
  65 On a fresh checkout, run:
  66 ./autogen.sh --enable-encode
  67 From a distribution tarball, run:
  68 ./configure --enable-encode
  69 Then run:
  70 make
  71 make install
  72
  73 For Windows, MSVC++ 6 project files are provided.
  74
  75 A simple GNU Makefile is also provided.
  76 Edit to taste.
  77 This will likely disappear in a future version.