media/filters/vp8_bool_decoder.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4 //
   5
   6 /*
   7  * Copyright (c) 2010, The WebM Project authors. All rights reserved.
   8  *
   9  * Redistribution and use in source and binary forms, with or without
  10  * modification, are permitted provided that the following conditions are
  11  * met:
  12  *
  13  *   * Redistributions of source code must retain the above copyright
  14  *     notice, this list of conditions and the following disclaimer.
  15  *
  16  *   * Redistributions in binary form must reproduce the above copyright
  17  *     notice, this list of conditions and the following disclaimer in
  18  *     the documentation and/or other materials provided with the
  19  *     distribution.
  20  *
  21  *   * Neither the name of Google, nor the WebM Project, nor the names
  22  *     of its contributors may be used to endorse or promote products
  23  *     derived from this software without specific prior written
  24  *     permission.
  25  *
  26  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  27  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  28  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  29  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  30  * HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  31  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  32  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  33  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  34  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  35  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  36  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  37  */
  38
  39 // This file is modified from the dboolhuff.{c,h} from the WebM's libvpx
  40 // project. (http://www.webmproject.org/code)
  41 // It is used to decode bits from a vp8 stream.
  42
  43 #ifndef MEDIA_FILTERS_VP8_BOOL_DECODER_H_
  44 #define MEDIA_FILTERS_VP8_BOOL_DECODER_H_
  45
  46 #include <sys/types.h>
  47
  48 #include "base/basictypes.h"
  49 #include "base/logging.h"
  50 #include "media/base/media_export.h"
  51
  52 namespace media {
  53
  54 // A class to decode the VP8's boolean entropy coded stream. It's a variant of
  55 // arithmetic coding. See RFC 6386 - Chapter 7. Boolean Entropy Decoder.
  56 class MEDIA_EXPORT Vp8BoolDecoder {
  57  public:
  58   Vp8BoolDecoder();
  59
  60   // Initializes the decoder to start decoding |data|, |size| being size
  61   // of |data| in bytes. Returns false if |data| is NULL or empty.
  62   bool Initialize(const uint8_t* data, size_t size);
  63
  64   // Reads a boolean from the coded stream. Returns false if it has reached the
  65   // end of |data| and failed to read the boolean. The probability of |out| to
  66   // be true is |probability| / 256, e.g., when |probability| is 0x80, the
  67   // chance is 1/2 (i.e., 0x80 / 256).
  68   bool ReadBool(bool* out, uint8_t probability);
  69
  70   // Reads a boolean from the coded stream with the default probability 1/2.
  71   // Returns false if it has reached the end of |data| and failed to read the
  72   // boolean.
  73   bool ReadBool(bool* out);
  74
  75   // Reads a "literal", that is, a "num_bits"-wide unsigned value whose bits
  76   // come high- to low-order, with each bit encoded at probability 1/2.
  77   // Returns false if it has reached the end of |data| and failed to read the
  78   // literal.
  79   bool ReadLiteral(size_t num_bits, int* out);
  80
  81   // Reads a literal with sign from the coded stream. This is similar to
  82   // the ReadListeral(), it first read a "num_bits"-wide unsigned value, and
  83   // then read an extra bit as the sign of the literal. Returns false if it has
  84   // reached the end of |data| and failed to read the literal or the sign.
  85   // This is different from the "read_signed_literal(d, n)" defined in RFC 6386.
  86   bool ReadLiteralWithSign(size_t num_bits, int* out);
  87
  88   // The following methods are used to get the internal states of the decoder.
  89
  90   // Returns the bit offset to the current top bit of the coded stream. It is
  91   // also the number of bits that have been written in the corresponding
  92   // encoding state. More specifically, we have the following constraint:
  93   //    w + (bottom * S) <= v < w + (bottom + range) * S,
  94   // where "w" is for the bits already written,
  95   //       "v" is for the possible values of the coded number.
  96   //       "S" is the scale for the current bit position,
  97   //           i.e., S = pow(2, -(n + 8)), where "n" is the bit number of "w".
  98   // BitOffset() returns the bit count of "w", i.e., "n".
  99   size_t BitOffset();
 100
 101   // Gets the "bottom" of the current coded value. See BitOffset() for
 102   // more details.
 103   uint8_t GetBottom();
 104
 105   // Gets the "range" of the current coded value. See BitOffset() for
 106   // more details.
 107   uint8_t GetRange();
 108
 109  private:
 110   // Reads the next bit from the coded stream. The probability of the bit to
 111   // be one is |probability| / 256.
 112   int ReadBit(int probability);
 113
 114   // Fills more bits from |user_buffer_| to |value_|. We shall keep at least 8
 115   // bits of the current |user_buffer_| in |value_|.
 116   void FillDecoder();
 117
 118   // Returns true iff we have ran out of bits.
 119   bool OutOfBuffer();
 120
 121   const uint8_t* user_buffer_;
 122   const uint8_t* user_buffer_start_;
 123   const uint8_t* user_buffer_end_;
 124   size_t value_;
 125   int count_;
 126   size_t range_;
 127
 128   DISALLOW_COPY_AND_ASSIGN(Vp8BoolDecoder);
 129 };
 130
 131 }  // namespace media
 132
 133 #endif  // MEDIA_FILTERS_VP8_BOOL_DECODER_H_