kdu_codestream::flush

In most cases, this is the function you use to actually write out code-stream data once the subband data has been generated and encoded. Starting from version 3.3, this function may be invoked multiple times, in order to generate the code-stream incrementally. This allows you to interleave image data transformation and encoding steps with code-stream flushing, avoiding the need to buffer all compressed data in memory.

The function may be used in two quite different ways:

• Firstly, it may be used to generate quality layers whose compressed sizes conform to the limits identified in a supplied layer_bytes array. This mode of operation is employed if the layer_thresholds argument is NULL, or if the first entry in a non-NULL layer_thresholds array is 0. The function selects the smallest distortion-length slope threshold which is consistent with these layer sizes. Note that the k'th entry in the layer_bytes array holds the maximum cumulative size of the first k quality layers, including all code-stream headers, excepting only the size of optional pointer marker segments (e.g., PLT marker segments for recording packet lengths in tile-part headers).
• Secondly, it may be used to generate quality layers whose distortion-length slope thresholds are given explicitly through a supplied layer_thresholds array, whose first entry is non-zero. The actual slope thresholds recorded in this array are 16-bit unsigned integers, whose values have the form A+256*log_2(delta_D/delta_L) where delta_D is the reduction in MSE (possibly weighted according to the frequency weights supplied via the Cband_weights, Clev_weights and Cweight attributes) associated with an increase of delta_L in the byte count. The offset, A, is selected to ensure that the entire range of slopes which could reasonably be encountered can fit into the range 0 to 2^16. For the purpose of determining appropriate layer_thresholds values, we point out that a threshold of 0 yields the largest possible output size, i.e., all bytes are included by the end of that layer. A slope threshold of 0xFFFF yields the smallest possible output size, i.e., no code-blocks are included in the layer.

Normally, num_layer_specs should be identical to the actual number of quality layers to be generated. In this case, every non-zero entry in a layer_bytes array identifies the target maximum number of bytes for the corresponding quality layer and every non-zero entry in a layer_thresholds array identifies a distortion-length slope threshold for the corresponding layer.

It can happen that individual tiles have fewer quality layers. In this case, these tiles participate only in the rate allocation associated with the initial quality layers and they make no contribution to the later (higher rate) layers. If no tiles have num_layer_specs quality layers, the code-stream size will be limited to that specified in the highest layer_bytes entry for which at least one tile has a quality layer.

It can happen that individual tiles have more quality layers than the number of layer specs provided here. Packets associated with all such layers will be written with the "empty header bit" set to 0 — they will thus have the minimum 1 byte representation. These useless packet bytes are taken into account in the rate allocation process, so as to guarantee that the complete code-stream does not exceed the size specified in a final layer spec.

When a layer_bytes array is used to size the quality layers, zero valued entries in this array mean that the rate allocator should attempt to assign roughly logarithmically spaced sizes (or bit-rates) to those quality layers. The logarithmic spacing rule is applied after first subtracting a minimal header offset consisting of the main and tile header bytes, plus 1 byte per packet (3 bytes if EPH markers are being used, 7 bytes if SOP marker segments are being used, and 9 bytes if both SOP and EPH marker segments are being used). Any or all of the entries may be 0. If the last entry is 0, all generated bits will be output by the time the last quality layer is encountered.

If the first entry in the layer_bytes array is 0 and there are multiple layers, the function employs the following reasonable policy to determine suitable rate allocation targets.

• Let Z be the number of initial layers whose size is not explicitly specified (if the last layer has no assigned size, it will first be assigned the number of bytes required to including all compressed information in the code-stream, as described above.
• Let R be the target number of bytes for the next layer.
• Let H_k be the minimal header cost mentioned above (main and tile headers, plus 1 byte per packet, but more if SOP and/or EPH markers are used) for the first k quality layers.
• The rate allocator will try to allocate H_1+(R-H_Z)/sqrt(2^Z) bytes to the first layer. The logarithmic spacing policy will then assign roughly 2 layers per octave change in the bit-rate.

If one or more initial layers are assigned non-zero target sizes, but these are followed by further non-final layers which have no explicitly specified target size (0 valued entries in the layer_bytes array), the function adds the appropriate minimum header size to the size specified for all initial non-zero layers. This behaviour allows the user or application to safely specify arbitrarily small bounds for the lowest quality layers and usually mimics most closely the effect an application or user would like to see.

If both the layer_bytes and the layer_thresholds arguments are NULL, the function behaves as though layer_bytes pointed to an array having all zero entries, so that the layer size allocation policy described above will be employed.

As noted at the beginning of this description, the function now supports incremental flushing of the code-stream. What this means is that you can generate some of the compressed data, pushing the code-block bit-streams into the code-stream management machinery using the kdu_subband::open_block and kdu_subband::close_block interfaces, and then call flush to flush as much of the generated data to the attached kdu_compressed_target object as possible. You can then continue generating coded block bit-streams, calling the flush function every so often. This behaviour allows you to minimize the amount of coded data which must be stored internally. While the idea is quite straightforward, there are quite a number of important factors which you should take into account if incremental flushing is to be beneficial to your application:

• Most significantly, for the Post-Compression-Rate-Distortion (PCRD) optimization algorithm to work reliably, a large amount of compressed data must be available for sizing the various quality layers prior to code-stream generation. This means that you should generally call the flush function as infrequently as possible. In a typical application, you should process at least 500 lines of image data between calls to this function and maybe quite a bit more, depending upon the code-block dimensions you are using. If you are supplying explicit distortion-length slope layer_thresholds to the function rather than asking for them to be generated by the PCRD optimization algorithm, you may call the flush function more often, to reduce the amount of compressed data which must be buffered internally. Note, however, that the remaining considerations below still apply. In particular, the tile-part restriction may still force you to call the function as infrequently as possible and the dimensions of the low resolution precincts may render frequent calls to this function useless.
• Before calling this function you should generally issue a call to ready_for_flush which will tell you whether or not any new data can be written to the code-stream. The ability to generate new code-stream data is affected by the packet progression sequence, as well as the precinct dimensions, particularly those of the lower resolution levels. For effective incremental flushing, you should employ a packet progression order which sequences all of the packets for each precinct consecutively. This means that you should use one of PCRL, CPRL or RPCL. In practice, only the first two are likely to be of much use, since the packet progression should also reflect the order in which coded data becomes available. In most applications, it is best to process the image components in an interleaved fashion so as to allow safe utilization of the max_bytes function, which limits the number of useless coding passes which are generated by the block encoder. For this reason, the PCRL packet progression order will generally be the one you want. Moreover, it is important that low resolution precincts have as little height as possible, since they typically represent the key bottlenecks preventing smooth incremental flushing of the code-stream. As an example, suppose you wish to flush a large image every 700 lines or so, and that 7 levels of DWT are employed. In this case, the height of the lowest resolution's precincts (these represent the LL subband) should be around 4 samples. The precinct height in each successive resolution level can double, although you should often select somewhat smaller precincts than this rule would suggest for the highest resolution levels. For example, you might use the following parameter values for the Cprecincts attribute: "{128,256},{128,128},{64,64},{32,64},{16,64}, {8,64},{4,32}".
• If the image has been vertically tiled, you would do best to invoke this function after generating compressed data for a whole number of tiles. In this case, careful construction of vertical precinct dimensions, as suggested above, is not necessary, since the tiles will automatically induce an hierarchically descending set of precinct dimensions.
• You should be aware of the fact that each call to this function adds a new tile-part to each tile whose compressed data has not yet been completely written. The standard imposes a limit of at most 255 tile-parts for any tile, so if the image is not tiled, you must call this function no more than 255 times. To avoid generating empty tile-parts, you can use the ready_for_flush function, which returns true only if enough data is available to ensure that the next call to the present function will generate at least one non-empty tile-part.

We conclude this introductory discussion by noting the way in which values are taken in from and returned via any non-NULL layer_bytes and layer_thresholds arrays when the function is invoked one or more times. When the function is first invoked, the mode of operation is determined to be either size driven, or slope driven, depending upon whether or not a layer_thresholds array is supplied having a non-zero first entry. If the layer sized mode of operation is in force, the target layer sizes are copied to an internal array and the same overall layer size targets are used for this and all subsequent calls to the flush function until the code-stream has been entirely flushed; it makes no difference what values are supplied in the layer_bytes array for subsequent flush calls in an incremental flushing sequence. If the explicit slope thresholds mode is in force, the supplied slope thresholds are also copied to an internal array and the same mode is employed for all future calls to this function until the code-stream has been completely flushed. If subsequent calls provide a non-NULL layer_thresholds array, however, the supplied thresholds will replace those stored in the internal array. This allows the application to implement its own rate control loop, adapting the slope thresholds between incremental flush calls so as to achieve some objective.

Regardless of the mode of operation, whenever this function returns it copies into any non-NULL layer_bytes array, the total number of bytes which have actually been written out to the code-stream so far for each specified layer. Similarly, whenever the function returns, it copies into any non-NULL layer_thresholds array, the actual slope threshold used when generating code-stream data for each layer during this call.

layer_bytes [kdu_long *]

num_layer_specs [int]

layer_thresholds [kdu_uint16 *]

trim_to_rate [bool]

record_in_comseg [bool]

tolerance [double]