kdu_codestream::set_max_bytes

If used with an input codestream, this function sets the maximum number of bytes which will be read from the input code-stream. Additional bytes will be discarded. In this case, the simulate_parsing argument may modify the behaviour as described in connection with that argument below.

If used with an interchange codestream, the function does nothing at all.

If used with an output codestream, this function enables internal machinery for incrementally estimating the parameters which will be used by the PCRD-opt rate allocation algorithm, so that the block coder can be given feedback to assist it in minimizing the number of coding passes which must be processed — in many cases, most of the coding passes will be discarded. Note that the actual rate allocation performed during a call to the flush member function is independent of the value supplied here, although it is expected that max_bytes will be equal to (certainly no smaller than) the maximum layer byte count supplied in the flush call.

The following cautionary notes should be observed concerning the incremental rate control machinery enabled when this function is invoked on an output codestream:

• The rate control prediction strategy relies upon the assumption that the image samples will be processed incrementally, with all image components processed together at the same relative rate. It is not at all appropriate to process one image component completely, followed by another component and so forth. It such a processing order is intended, this function should not be called.
• The prediction strategy may inappropriately discard information, thereby harming compression, if the compressibility of the first part of the image which is processed is very different to that of the last part of the image. Although this is rare in our experience, it may be a problem with certain types of imagery, such as medical images which sometimes contain empty regions near boundaries.
• If truly lossless compression is desired, this function should not be called, no matter how large the supplied max_bytes value. This is because terminal coding passes which do not lie on the convex hull of the rate-distortion curve will be summarily discarded, violating the official mandate that a lossless code-stream contain all compressed bits.

For both input and output codestreams, the function may only be called prior to the point at which the first tile is opened and it may only be called once, if at all.

If restart is used to restart the code-stream managment machinery, the effect of the current function is lost. It may be restored by calling the function again after each call to restart.

max_bytes [kdu_long]

simulate_parsing [bool]