lib/lame/reservoir.c

   1 /*
   2  *      bit reservoir source file
   3  *
   4  *      Copyright (c) 1999 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.2 2006/02/09 16:56:23 kramm Exp $ */
  23
  24 #include <stdlib.h>
  25 #include "config_static.h"
  26
  27 #include <assert.h>
  28 #include "util.h"
  29 #include "reservoir.h"
  30
  31 #ifdef WITH_DMALLOC
  32 #include <dmalloc.h>
  33 #endif
  34
  35 /*
  36   ResvFrameBegin:
  37   Called (repeatedly) at the beginning of a frame. Updates the maximum
  38   size of the reservoir, and checks to make sure main_data_begin
  39   was set properly by the formatter
  40 */
  41
  42 /*
  43  *  Background information:
  44  *
  45  *  This is the original text from the ISO standard. Because of
  46  *  sooo many bugs and irritations correcting comments are added
  47  *  in brackets []. A '^W' means you should remove the last word.
  48  *
  49  *  1) The following rule can be used to calculate the maximum
  50  *     number of bits used for one granule [^W frame]:
  51  *     At the highest possible bitrate of Layer III (320 kbps
  52  *     per stereo signal [^W^W^W], 48 kHz) the frames must be of
  53  *     [^W^W^W are designed to have] constant length, i.e.
  54  *     one buffer [^W^W the frame] length is:
  55  *
  56  *         320 kbps * 1152/48 kHz = 7680 bit = 960 byte
  57  *
  58  *     This value is used as the maximum buffer per channel [^W^W] at
  59  *     lower bitrates [than 320 kbps]. At 64 kbps mono or 128 kbps
  60  *     stereo the main granule length is 64 kbps * 576/48 kHz = 768 bit
  61  *     [per granule and channel] at 48 kHz sampling frequency.
  62  *     This means that there is a maximum deviation (short time buffer
  63  *     [= reservoir]) of 7680 - 2*2*768 = 4608 bits is allowed at 64 kbps.
  64  *     The actual deviation is equal to the number of bytes [with the
  65  *     meaning of octets] denoted by the main_data_end offset pointer.
  66  *     The actual maximum deviation is (2^9-1)*8 bit = 4088 bits
  67  *     [for MPEG-1 and (2^8-1)*8 bit for MPEG-2, both are hard limits].
  68  *     ... The xchange of buffer bits between the left and right channel
  69  *     is allowed without restrictions [exception: dual channel].
  70  *     Because of the [constructed] constraint on the buffer size
  71  *     main_data_end is always set to 0 in the case of bit_rate_index==14,
  72  *     i.e. data rate 320 kbps per stereo signal [^W^W^W]. In this case
  73  *     all data are allocated between adjacent header [^W sync] words
  74  *     [, i.e. there is no buffering at all].
  75  */
  76
  77 int
  78 ResvFrameBegin(lame_global_flags *gfp,III_side_info_t *l3_side, int mean_bits, int frameLength )
  79 {
  80     lame_internal_flags *gfc=gfp->internal_flags;
  81     int fullFrameBits;
  82     int resvLimit;
  83     int maxmp3buf;
  84
  85 /*
  86  *  Meaning of the variables:
  87  *      resvLimit: (0, 8, ..., 8*255 (MPEG-2), 8*511 (MPEG-1))
  88  *          Number of bits can be stored in previous frame(s) due to
  89  *          counter size constaints
  90  *      maxmp3buf: ( ??? ... 8*1951 (MPEG-1 and 2), 8*2047 (MPEG-2.5))
  91  *          Number of bits allowed to encode one frame (you can take 8*511 bit
  92  *          from the bit reservoir and at most 8*1440 bit from the current
  93  *          frame (320 kbps, 32 kHz), so 8*1951 bit is the largest possible
  94  *          value for MPEG-1 and -2)
  95  *
  96  *          maximum allowed granule/channel size times 4 = 8*2047 bits.,
  97  *          so this is the absolute maximum supported by the format.
  98  *
  99  *
 100  *      fullFrameBits:  maximum number of bits available for encoding
 101  *                      the current frame.
 102  *
 103  *      mean_bits:      target number of bits per granule.
 104  *
 105  *      frameLength:
 106  *
 107  *      gfc->ResvMax:   maximum allowed reservoir
 108  *
 109  *      gfc->ResvSize:  current reservoir size
 110  *
 111  *      l3_side->resvDrain_pre:
 112  *         ancillary data to be added to previous frame:
 113  *         (only usefull in VBR modes if it is possible to have
 114  *         maxmp3buf < fullFrameBits)).  Currently disabled,
 115  *         see #define NEW_DRAIN
 116  *
 117  *      l3_side->resvDrain_post:
 118  *         ancillary data to be added to this frame:
 119  *
 120  */
 121
 122     /* main_data_begin has 9 bits in MPEG-1, 8 bits MPEG-2 */
 123     resvLimit = (gfp->version==1) ? 8*511 : 8*255 ;
 124
 125
 126     /* maximum allowed frame size.  dont use more than this number of
 127        bits, even if the frame has the space for them: */
 128     /* Bouvigne suggests this more lax interpretation of the ISO doc
 129        instead of using 8*960. */
 130     if (gfp->strict_ISO) {
 131         if (gfp->version==1)
 132             maxmp3buf=8*((int)(320000/(gfp->out_samplerate / (FLOAT8)1152)/8 +.5));
 133         else
 134             maxmp3buf=8*((int)(160000/(gfp->out_samplerate / (FLOAT8)576)/8 +.5));
 135     } else
 136         /*all mp3 decoders should have enough buffer to handle this value: size of a 320kbps 32kHz frame*/
 137         maxmp3buf = 8*1440;
 138
 139
 140     if ( frameLength > maxmp3buf ||  gfp->disable_reservoir ) {
 141         gfc->ResvMax = 0;
 142     } else {
 143         gfc->ResvMax = maxmp3buf - frameLength;
 144         if ( gfc->ResvMax > resvLimit )
 145           gfc->ResvMax = resvLimit;
 146     }
 147
 148     fullFrameBits = mean_bits * gfc->mode_gr + Min ( gfc->ResvSize, gfc->ResvMax );
 149
 150     if ( fullFrameBits > maxmp3buf )
 151         fullFrameBits = maxmp3buf;
 152
 153     assert ( 0 == gfc->ResvMax % 8 );
 154     assert ( gfc->ResvMax >= 0 );
 155
 156     l3_side->resvDrain_pre = 0;
 157
 158     if ( gfc->pinfo != NULL ) {
 159         gfc->pinfo->mean_bits = mean_bits / 2;  /* expected bits per channel per granule [is this also right for mono/stereo, MPEG-1/2 ?] */
 160         gfc->pinfo->resvsize  = gfc->ResvSize;
 161     }
 162
 163     return fullFrameBits;
 164 }
 165
 166
 167 /*
 168   ResvMaxBits
 169   returns targ_bits:  target number of bits to use for 1 granule
 170          extra_bits:  amount extra available from reservoir
 171   Mark Taylor 4/99
 172 */
 173 void ResvMaxBits(lame_global_flags *gfp, int mean_bits, int *targ_bits, int *extra_bits)
 174 {
 175   lame_internal_flags *gfc=gfp->internal_flags;
 176   int add_bits;
 177   int full_fac;
 178
 179   *targ_bits = mean_bits ;
 180
 181   /* extra bits if the reservoir is almost full */
 182   full_fac=9;
 183   if (gfc->ResvSize > ((gfc->ResvMax * full_fac) / 10)) {
 184     add_bits= gfc->ResvSize-((gfc->ResvMax * full_fac) / 10);
 185     *targ_bits += add_bits;
 186   }else {
 187     add_bits =0 ;
 188     /* build up reservoir.  this builds the reservoir a little slower
 189      * than FhG.  It could simple be mean_bits/15, but this was rigged
 190      * to always produce 100 (the old value) at 128kbs */
 191     /*    *targ_bits -= (int) (mean_bits/15.2);*/
 192     if (!gfp->disable_reservoir)
 193       *targ_bits -= .1*mean_bits;
 194   }
 195
 196
 197   /* amount from the reservoir we are allowed to use. ISO says 6/10 */
 198   *extra_bits =
 199     (gfc->ResvSize  < (gfc->ResvMax*6)/10  ? gfc->ResvSize : (gfc->ResvMax*6)/10);
 200   *extra_bits -= add_bits;
 201
 202   if (*extra_bits < 0) *extra_bits=0;
 203
 204
 205 }
 206
 207 /*
 208   ResvAdjust:
 209   Called after a granule's bit allocation. Readjusts the size of
 210   the reservoir to reflect the granule's usage.
 211 */
 212 void
 213 ResvAdjust(lame_internal_flags *gfc,gr_info *gi, III_side_info_t *l3_side, int mean_bits )
 214 {
 215   gfc->ResvSize += (mean_bits / gfc->channels_out) - gi->part2_3_length;
 216 #if 0
 217   printf("part2_3_length:  %i  avg=%i  incres: %i  resvsize=%i\n",gi->part2_3_length,
 218          mean_bits/gfc->channels_out,
 219 mean_bits/gfc->channels_out-gi->part2_3_length,gfc->ResvSize);
 220 #endif
 221 }
 222
 223
 224 /*
 225   ResvFrameEnd:
 226   Called after all granules in a frame have been allocated. Makes sure
 227   that the reservoir size is within limits, possibly by adding stuffing
 228   bits.
 229 */
 230 void
 231 ResvFrameEnd(lame_internal_flags *gfc, III_side_info_t *l3_side, int mean_bits)
 232 {
 233     int stuffingBits;
 234     int over_bits;
 235
 236
 237     /* just in case mean_bits is odd, this is necessary... */
 238     if ( gfc->channels_out == 2  &&  (mean_bits & 1) )
 239         gfc->ResvSize += 1;
 240
 241     stuffingBits=0;
 242     l3_side->resvDrain_post = 0;
 243     l3_side->resvDrain_pre = 0;
 244
 245     /* we must be byte aligned */
 246     if ( (over_bits = gfc->ResvSize % 8) != 0 )
 247         stuffingBits += over_bits;
 248
 249
 250     over_bits = (gfc->ResvSize - stuffingBits) - gfc->ResvMax;
 251     if (over_bits > 0) {
 252       assert ( 0 == over_bits % 8 );
 253       assert ( over_bits >= 0 );
 254       stuffingBits += over_bits;
 255     }
 256
 257
 258 #undef NEW_DRAIN
 259 #ifdef NEW_DRAIN
 260     /* drain as many bits as possible into previous frame ancillary data
 261      * In particular, in VBR mode ResvMax may have changed, and we have
 262      * to make sure main_data_begin does not create a reservoir bigger
 263      * than ResvMax  mt 4/00*/
 264   {
 265     int mdb_bytes = Min(l3_side->main_data_begin*8,stuffingBits)/8;
 266     l3_side->resvDrain_pre += 8*mdb_bytes;
 267     stuffingBits -= 8*mdb_bytes;
 268     gfc->ResvSize -= 8*mdb_bytes;
 269     l3_side->main_data_begin -= mdb_bytes;
 270
 271
 272     /* drain just enough to be byte aligned.  The remaining bits will
 273      * be added to the reservoir, and we will deal with them next frame.
 274      * If the next frame is at a lower bitrate, it may have a larger ResvMax,
 275      * and we will not have to waste these bits!  mt 4/00 */
 276     assert ( stuffingBits >= 0 );
 277     l3_side->resvDrain_post += (stuffingBits % 8);
 278     gfc->ResvSize -= stuffingBits % 8;
 279   }
 280 #else
 281     /* drain the rest into this frames ancillary data*/
 282     l3_side->resvDrain_post += stuffingBits;
 283     gfc->ResvSize -= stuffingBits;
 284 #endif
 285
 286     return;
 287 }
 288
 289