File size: 7,499 Bytes
9375c9a |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 |
// Copyright (C) 2003 Davis E. King ([email protected])
// License: Boost Software License See LICENSE.txt for the full license.
#undef DLIB_ENTROPY_DECODER_KERNEl_ABSTRACT_
#ifdef DLIB_ENTROPY_DECODER_KERNEl_ABSTRACT_
#include "../algs.h"
#include <iosfwd>
#include "../uintn.h"
namespace dlib
{
class entropy_decoder
{
/*!
INITIAL VALUE
stream_is_set() == false
get_target_called() == false
WHAT THIS OBJECT REPRESENTS
This object represents an entropy decoder (could be implemented as an
arithmetic decoder for example).
Note that all implementations of entropy_encoder and entropy_decoder
are paired. This means that if you use entropy_encoder_kernel_n to
encode something then you must use the corresponding
entropy_decoder_kernel_n to decode it.
WHERE IS EOF?
It is important to note that this object will not give any indication
that is has hit the end of the input stream when it occurs. It is
up to you to use some kind of coding scheme to detect this in the
compressed data stream.
Another important thing to know is that decode() must be called
exactly the same number of times as encode() and with the same values
supplied for TOTAL, high_count, and low_count. Doing this ensures
that the decoder consumes exactly all the bytes from the input
stream that were written by the entropy_encoder.
NOTATION:
At any moment each symbol has a certain probability of appearing in
the input stream. These probabilities may change as each symbol is
decoded and the probability model is updated accordingly.
- Before considering current symbol:
let P(i) be a function which gives the probability of seeing the ith
symbol of an N symbol alphabet. Note that P(i) refers to the probability
of seeing the ith symbol WITHOUT considering the symbol currently given
by get_target(TOTAL). ( The domain of P(i) is from 0 to N-1. )
for each i: P(i) == COUNT/TOTAL where COUNT and TOTAL are integers
and TOTAL is the same number for all P(i) but COUNT may vary.
let LOW_COUNT(i) be the sum of all P(x)*TOTAL from x == 0 to x == i-1
(note that LOW_COUNT(0) == 0)
let HIGH_COUNT(i) be the sum of all P(x)*TOTAL from x == 0 to x == i
- After considering current symbol:
let #P(i) be a function which gives the probability of seeing the ith
symbol after we have updated our probability model to take the symbol
given by get_target(TOTAL) into account.
for each i: #P(i) == #COUNT/#TOTAL where #COUNT and #TOTAL are integers
and #TOTAL is the same number for all #P(i) but #COUNT may vary.
!*/
public:
entropy_decoder (
);
/*!
ensures
- #*this is properly initialized
throws
- std::bad_alloc
!*/
virtual ~entropy_decoder (
);
/*!
ensures
- all memory associated with *this has been released
!*/
void clear(
);
/*!
ensures
- #*this has its initial value
- if (stream_is_set())
- clears any state accumulated in *this from decoding data from
the stream get_stream()
throws
- any exception
if this exception is thrown then #*this is unusable
until clear() is called and succeeds
!*/
void set_stream (
std::istream& in
);
/*!
ensures
- #*this will read data from in and decode it
- #stream_is_set() == true
- #get_target() == a number representing the first symbol from in
- #get_target_called() == false
- if (stream_is_set())
- clears any state accumulated in *this from decoding data from
the stream get_stream()
throws
- any exception
if this exception is thrown then #*this is unusable
until clear() is called and succeeds
!*/
bool stream_is_set (
) const;
/*!
ensures
- returns true if a stream has been associated with *this by calling
set_stream()
!*/
std::istream& get_stream (
) const;
/*!
requires
- stream_is_set() == true
ensures
- returns a reference to the istream object that *this is reading
encoded data from
!*/
void decode (
uint32 low_count,
uint32 high_count
);
/*!
requires
- get_target_called() == true
- stream_is_set() == true
- low_count == LOW_COUNT(S) where S is the symbol represented
by get_target(TOTAL)
- high_count == HIGH_COUNT(S) where S is the symbol represented
by get_target(TOTAL)
- low_count <= get_target(TOTAL) < high_count <= TOTAL
ensures
- #get_target(#TOTAL) == a number which represents the next symbol
- #get_target_called() == false
throws
- any exception
if this exception is thrown then #*this is unusable
until clear() is called and succeeds
!*/
bool get_target_called (
) const;
/*!
ensures
- returns true if get_target() has been called and since then decode()
and set_stream() have not been called
- returns false otherwise
!*/
uint32 get_target (
uint32 total
);
/*!
requires
- 0 < total < 65536 (2^16)
- total == TOTAL
- stream_is_set() == true
ensures
- in the next call to decode() the value of TOTAL will be
considered to be total
- #get_target_called() == true
- returns a number N such that:
- N is in the range 0 to total - 1
- N represents a symbol S where
LOW_COUNT(S) <= N < HIGH_COUNT(S)
throws
- any exception
if this exception is thrown then #*this is unusable
until clear() is called and succeeds
!*/
private:
// restricted functions
entropy_decoder(entropy_decoder&); // copy constructor
entropy_decoder& operator=(entropy_decoder&); // assignment operator
};
}
#endif // DLIB_ENTROPY_DECODER_KERNEl_ABSTRACT_
|