kdu_stripe_compressor::start

Interface to a kdu_codestream object whose create function has already been called. The kdu_params::finalize_all function should not be called by the application; it will be invoked from within the present function, possibly after making some final adjustments to coding parameter attributes which have not been configured by the application.

If this argument is equal to 0, the number of quality layers to build into the code-stream is recovered from the Clayers coding parameter attribute, which the application may have been configured prior to calling this function. If the Clayers attribute was not set, it will default to 1 when the kdu_params::finalize_all function is called from within this function. If the present argument is greater than 0, and the Clayers attribute has not already been set, it will be set equal to the value of num_layer_specs. Regardless of the final number of code-stream quality layers which is used, the num_layer_specs argument provides the number of entries in the layer_sizes and layer_slopes arrays, if non-NULL. These arrays, if provided, allow the application to specify the properties of the quality layers. If no layer sizes or slopes are specified, a logarithmically spaced set of quality layers will be constructed, following the conventions described with the kdu_codestream::flush function.

If non-NULL, this argument points to an array with num_layer_specs entries, containing the cumulative number of bytes from the start of the code-stream to the end of each quality layer, if the code-stream were to be arranged in layer progressive order. The code-stream may be arranged in a very different order, of course, but that has no impact on the sizes of the layers, as controlled by this argument. If the actual number of quality layers, as specified by the Clayers attribute, is smaller than num_layer_specs, not all of the entries in this array will be used. If the actual number of quality layers is larger than num_layer_specs, the additional quality layers will be empty. This argument is ignored if num_layer_specs is 0.

If non-NULL, this argument points to an array with num_layer_specs entries, containing the distortion-length slope thresholds associated with each quality layer. This argument is ignored if layer_sizes is non-NULL, or num_layer_specs is 0. For an explanation of the logarithmic representation used for distortion length slope thresholds in Kakadu, see the comments associated with the kdu_codestream::flush function.

If this argument is non-zero, the kdu_codestream::set_min_slope_threshold function will be used to apply this slope threshold prior to compression. As explained in connection with that function, this can help to speed up the compression process significantly. Although the application could invoke kdu_codestream::set_min_slope_threshold itself, providing a non-zero argument here will prevent the present function from calling kdu_codestream::set_max_bytes if the layer_sizes array is non-NULL. More precisely, the function follows the following set of rules in determining what speedup features to apply:

• If no_prediction is true, no speedup features will be applied;
• else, if min_slope_threshold is non-zero, the value will be supplied to kdu_codestream::set_min_slope_threshold;
• else, if layer_sizes is non-NULL, the last entry in the layer_sizes array will be passed to kdu_codestream::set_max_bytes;
• else, if layer_slopes is non-NULL, the last entry in the layer_slopes array will be passed to kdu_codestream::set_min_slope_threshold.

If true, neither the kdu_codestream::set_max_bytes function, nor the kdu_codestream::set_min_slope_threshold function will be invoked. Applications should set this argument to true only if they want to adopt a very conservative stance in relation to maximizing image quality at the expense of compression speed. For typical images, Kakadu's code-block truncation prediction mechanisms have no impact on image quality at all, while saving processing time.

If true, 32-bit internal representations are used by the compression engines created by this object, regardless of the precision of the image samples reported by kdu_codestream::get_bit_depth.

If true, the rate-distortion slope and the target number of bytes associated with each quality layer will be recorded in a COM (comment) marker segment in the main code-stream header. This can be very useful for applications which wish to process the code-stream later in a manner which depends upon the interpretation of the quality layers. For this reason, you should generally set this argument to true, unless you want to get the smallest possible file size when compressing small images. For more information on this option, consult the comments appearing with its namesake in kdu_codestream::flush.

This argument is ignored unless layering is controlled by cumulative layer sizes supplied via a layer_sizes array. In this case, it may be used to trade accuracy for speed when determining the distortion-length slopes which achieve the target layer sizes as closely as possible. In particular, the algorithm will finish once it has found a distortion-length slope which yields a size in the range target*(1-tolerance) <= size <= target, where target is the target size for the relevant layer. If no such slope can be found, the layer is assigned a slope such that the size is as close as possible to the target, without exceeding it.