src/lib/doslib/ext/lame/reservoir.c

   1 /*
   2  *      bit reservoir source file
   3  *
   4  *      Copyright (c) 1999-2000 Mark Taylor
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Library General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Library General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Library General Public
  17  * License along with this library; if not, write to the
  18  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  19  * Boston, MA 02111-1307, USA.
  20  */
  21
  22 /* $Id: reservoir.c,v 1.45 2011/05/07 16:05:17 rbrito Exp $ */
  23
  24 #ifdef HAVE_CONFIG_H
  25 # include <config.h>
  26 #endif
  27
  28
  29 #include "lame.h"
  30 #include "machine.h"
  31 #include "encoder.h"
  32 #include "util.h"
  33 #include "reservoir.h"
  34
  35 #include "bitstream.h"
  36 #include "lame-analysis.h"
  37 #include "lame_global_flags.h"
  38
  39
  40 /*
  41   ResvFrameBegin:
  42   Called (repeatedly) at the beginning of a frame. Updates the maximum
  43   size of the reservoir, and checks to make sure main_data_begin
  44   was set properly by the formatter
  45 */
  46
  47 /*
  48  *  Background information:
  49  *
  50  *  This is the original text from the ISO standard. Because of
  51  *  sooo many bugs and irritations correcting comments are added
  52  *  in brackets []. A '^W' means you should remove the last word.
  53  *
  54  *  1) The following rule can be used to calculate the maximum
  55  *     number of bits used for one granule [^W frame]:
  56  *     At the highest possible bitrate of Layer III (320 kbps
  57  *     per stereo signal [^W^W^W], 48 kHz) the frames must be of
  58  *     [^W^W^W are designed to have] constant length, i.e.
  59  *     one buffer [^W^W the frame] length is:
  60  *
  61  *         320 kbps * 1152/48 kHz = 7680 bit = 960 byte
  62  *
  63  *     This value is used as the maximum buffer per channel [^W^W] at
  64  *     lower bitrates [than 320 kbps]. At 64 kbps mono or 128 kbps
  65  *     stereo the main granule length is 64 kbps * 576/48 kHz = 768 bit
  66  *     [per granule and channel] at 48 kHz sampling frequency.
  67  *     This means that there is a maximum deviation (short time buffer
  68  *     [= reservoir]) of 7680 - 2*2*768 = 4608 bits is allowed at 64 kbps.
  69  *     The actual deviation is equal to the number of bytes [with the
  70  *     meaning of octets] denoted by the main_data_end offset pointer.
  71  *     The actual maximum deviation is (2^9-1)*8 bit = 4088 bits
  72  *     [for MPEG-1 and (2^8-1)*8 bit for MPEG-2, both are hard limits].
  73  *     ... The xchange of buffer bits between the left and right channel
  74  *     is allowed without restrictions [exception: dual channel].
  75  *     Because of the [constructed] constraint on the buffer size
  76  *     main_data_end is always set to 0 in the case of bit_rate_index==14,
  77  *     i.e. data rate 320 kbps per stereo signal [^W^W^W]. In this case
  78  *     all data are allocated between adjacent header [^W sync] words
  79  *     [, i.e. there is no buffering at all].
  80  */
  81
  82 int
  83 ResvFrameBegin(lame_internal_flags * gfc, int *mean_bits)
  84 {
  85     SessionConfig_t const *const cfg = &gfc->cfg;
  86     EncStateVar_t *const esv = &gfc->sv_enc;
  87     int     fullFrameBits;
  88     int     resvLimit;
  89     int     maxmp3buf;
  90     III_side_info_t *const l3_side = &gfc->l3_side;
  91     int     frameLength;
  92     int     meanBits;
  93
  94     frameLength = getframebits(gfc);
  95     meanBits = (frameLength - cfg->sideinfo_len * 8) / cfg->mode_gr;
  96
  97 /*
  98  *  Meaning of the variables:
  99  *      resvLimit: (0, 8, ..., 8*255 (MPEG-2), 8*511 (MPEG-1))
 100  *          Number of bits can be stored in previous frame(s) due to
 101  *          counter size constaints
 102  *      maxmp3buf: ( ??? ... 8*1951 (MPEG-1 and 2), 8*2047 (MPEG-2.5))
 103  *          Number of bits allowed to encode one frame (you can take 8*511 bit
 104  *          from the bit reservoir and at most 8*1440 bit from the current
 105  *          frame (320 kbps, 32 kHz), so 8*1951 bit is the largest possible
 106  *          value for MPEG-1 and -2)
 107  *
 108  *          maximum allowed granule/channel size times 4 = 8*2047 bits.,
 109  *          so this is the absolute maximum supported by the format.
 110  *
 111  *
 112  *      fullFrameBits:  maximum number of bits available for encoding
 113  *                      the current frame.
 114  *
 115  *      mean_bits:      target number of bits per granule.
 116  *
 117  *      frameLength:
 118  *
 119  *      gfc->ResvMax:   maximum allowed reservoir
 120  *
 121  *      gfc->ResvSize:  current reservoir size
 122  *
 123  *      l3_side->resvDrain_pre:
 124  *         ancillary data to be added to previous frame:
 125  *         (only usefull in VBR modes if it is possible to have
 126  *         maxmp3buf < fullFrameBits)).  Currently disabled,
 127  *         see #define NEW_DRAIN
 128  *         2010-02-13: RH now enabled, it seems to be needed for CBR too,
 129  *                     as there exists one example, where the FhG decoder
 130  *                     can't decode a -b320 CBR file anymore.
 131  *
 132  *      l3_side->resvDrain_post:
 133  *         ancillary data to be added to this frame:
 134  *
 135  */
 136
 137     /* main_data_begin has 9 bits in MPEG-1, 8 bits MPEG-2 */
 138     resvLimit = (8 * 256) * cfg->mode_gr - 8;
 139
 140     /* maximum allowed frame size.  dont use more than this number of
 141        bits, even if the frame has the space for them: */
 142     maxmp3buf = cfg->buffer_constraint;
 143     esv->ResvMax = maxmp3buf - frameLength;
 144     if (esv->ResvMax > resvLimit)
 145         esv->ResvMax = resvLimit;
 146     if (esv->ResvMax < 0 || cfg->disable_reservoir)
 147         esv->ResvMax = 0;
 148
 149     fullFrameBits = meanBits * cfg->mode_gr + Min(esv->ResvSize, esv->ResvMax);
 150
 151     if (fullFrameBits > maxmp3buf)
 152         fullFrameBits = maxmp3buf;
 153
 154     assert(0 == esv->ResvMax % 8);
 155     assert(esv->ResvMax >= 0);
 156
 157     l3_side->resvDrain_pre = 0;
 158
 159     if (gfc->pinfo != NULL) {
 160         gfc->pinfo->mean_bits = meanBits / 2; /* expected bits per channel per granule [is this also right for mono/stereo, MPEG-1/2 ?] */
 161         gfc->pinfo->resvsize = esv->ResvSize;
 162     }
 163     *mean_bits = meanBits;
 164     return fullFrameBits;
 165 }
 166
 167
 168 /*
 169   ResvMaxBits
 170   returns targ_bits:  target number of bits to use for 1 granule
 171          extra_bits:  amount extra available from reservoir
 172   Mark Taylor 4/99
 173 */
 174 void
 175 ResvMaxBits(lame_internal_flags * gfc, int mean_bits, int *targ_bits, int *extra_bits, int cbr)
 176 {
 177     SessionConfig_t const *const cfg = &gfc->cfg;
 178     EncStateVar_t *const esv = &gfc->sv_enc;
 179     int     add_bits, targBits, extraBits;
 180     int     ResvSize = esv->ResvSize, ResvMax = esv->ResvMax;
 181
 182     /* conpensate the saved bits used in the 1st granule */
 183     if (cbr)
 184         ResvSize += mean_bits;
 185
 186     if (gfc->sv_qnt.substep_shaping & 1)
 187         ResvMax *= 0.9;
 188
 189     targBits = mean_bits;
 190
 191     /* extra bits if the reservoir is almost full */
 192     if (ResvSize * 10 > ResvMax * 9) {
 193         add_bits = ResvSize - (ResvMax * 9) / 10;
 194         targBits += add_bits;
 195         gfc->sv_qnt.substep_shaping |= 0x80;
 196     }
 197     else {
 198         add_bits = 0;
 199         gfc->sv_qnt.substep_shaping &= 0x7f;
 200         /* build up reservoir.  this builds the reservoir a little slower
 201          * than FhG.  It could simple be mean_bits/15, but this was rigged
 202          * to always produce 100 (the old value) at 128kbs */
 203         /*    *targ_bits -= (int) (mean_bits/15.2); */
 204         if (!cfg->disable_reservoir && !(gfc->sv_qnt.substep_shaping & 1))
 205             targBits -= .1 * mean_bits;
 206     }
 207
 208
 209     /* amount from the reservoir we are allowed to use. ISO says 6/10 */
 210     extraBits = (ResvSize < (esv->ResvMax * 6) / 10 ? ResvSize : (esv->ResvMax * 6) / 10);
 211     extraBits -= add_bits;
 212
 213     if (extraBits < 0)
 214         extraBits = 0;
 215
 216     *targ_bits = targBits;
 217     *extra_bits = extraBits;
 218 }
 219
 220 /*
 221   ResvAdjust:
 222   Called after a granule's bit allocation. Readjusts the size of
 223   the reservoir to reflect the granule's usage.
 224 */
 225 void
 226 ResvAdjust(lame_internal_flags * gfc, gr_info const *gi)
 227 {
 228     gfc->sv_enc.ResvSize -= gi->part2_3_length + gi->part2_length;
 229 }
 230
 231
 232 /*
 233   ResvFrameEnd:
 234   Called after all granules in a frame have been allocated. Makes sure
 235   that the reservoir size is within limits, possibly by adding stuffing
 236   bits.
 237 */
 238 void
 239 ResvFrameEnd(lame_internal_flags * gfc, int mean_bits)
 240 {
 241     SessionConfig_t const *const cfg = &gfc->cfg;
 242     EncStateVar_t *const esv = &gfc->sv_enc;
 243     III_side_info_t *const l3_side = &gfc->l3_side;
 244     int     stuffingBits;
 245     int     over_bits;
 246
 247     esv->ResvSize += mean_bits * cfg->mode_gr;
 248     stuffingBits = 0;
 249     l3_side->resvDrain_post = 0;
 250     l3_side->resvDrain_pre = 0;
 251
 252     /* we must be byte aligned */
 253     if ((over_bits = esv->ResvSize % 8) != 0)
 254         stuffingBits += over_bits;
 255
 256
 257     over_bits = (esv->ResvSize - stuffingBits) - esv->ResvMax;
 258     if (over_bits > 0) {
 259         assert(0 == over_bits % 8);
 260         assert(over_bits >= 0);
 261         stuffingBits += over_bits;
 262     }
 263
 264
 265     /* NOTE: enabling the NEW_DRAIN code fixes some problems with FhG decoder
 266              shipped with MS Windows operating systems. Using this, it is even
 267              possible to use Gabriel's lax buffer consideration again, which
 268              assumes, any decoder should have a buffer large enough
 269              for a 320 kbps frame at 32 kHz sample rate.
 270
 271        old drain code:
 272              lame -b320 BlackBird.wav ---> does not play with GraphEdit.exe using FhG decoder V1.5 Build 50
 273
 274        new drain code:
 275              lame -b320 BlackBird.wav ---> plays fine with GraphEdit.exe using FhG decoder V1.5 Build 50
 276
 277              Robert Hegemann, 2010-02-13.
 278      */
 279     /* drain as many bits as possible into previous frame ancillary data
 280      * In particular, in VBR mode ResvMax may have changed, and we have
 281      * to make sure main_data_begin does not create a reservoir bigger
 282      * than ResvMax  mt 4/00*/
 283     {
 284         int     mdb_bytes = Min(l3_side->main_data_begin * 8, stuffingBits) / 8;
 285         l3_side->resvDrain_pre += 8 * mdb_bytes;
 286         stuffingBits -= 8 * mdb_bytes;
 287         esv->ResvSize -= 8 * mdb_bytes;
 288         l3_side->main_data_begin -= mdb_bytes;
 289     }
 290     /* drain the rest into this frames ancillary data */
 291     l3_side->resvDrain_post += stuffingBits;
 292     esv->ResvSize -= stuffingBits;
 293 }