// Copyright (C) 2003 Davis E. King (davis@dlib.net) // 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{classentropy_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 !*/voidclear( ); /*! 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 !*/voidset_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 !*/boolstream_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 !*/voiddecode( 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 !*/boolget_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 !*/ uint32get_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 functionsentropy_decoder(entropy_decoder&); // copy constructor entropy_decoder&operator=(entropy_decoder&); // assignment operator};}#endif // DLIB_ENTROPY_DECODER_KERNEl_ABSTRACT_