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.

If zero, the number of image components to be supplied to the push_stripe function is identical to the value returned by kdu_codestream::get_num_components, with its optional want_output_comps argument set to true. However, you may supply a smaller number of image components during compression, if you think that these provide sufficient information to generate all codestream image components. This can happen where a Part 2 multi-component transformation defines more MCT output components than there are codestream image components. Then, during compression, it may be possible to invert the defined multi-component transform network by supplying only a subset of the MCT output components as source components (the components supplied to push_stripe). If a non-zero num_components argument is supplied, this is the number of components you will push to push_stripe — if there are not sufficient components, the machinery will generate an appropriate error message through kdu_error. For more on this, consult the description of the kdu_multi_analysis object on which this is built.

If this argument is true and force_precise is false, the function selects a 16-bit internal representation (usually leads to the fastest processing) even if this will result in reduced image quality, at least for irreversible processing. For image components which require reversible compression, the 32-bit representation must be selected if the image sample precision is too high, or else numerical overflow might occur.

This argument is used to establish multi-threaded processing. For a discussion of the multi-threaded processing features offered by the present object, see the introductory comments to kdu_stripe_compressor. We remind you here, however, that all calls to start, process and finish must be executed from the same thread, which is identified only in this function. If you re-use the object to process a subsequent image, you may change threads between the two uses, passing the appropriate appropriate kdu_thread_env reference in each call to start. For the single-threaded processing model used prior to Kakadu version 5.1, set this argument to NULL.

This argument is ignored unless env is non-NULL, in which case a non-NULL env_queue means that all multi-threaded processing queues created inside the present object, by calls to process, should be created as sub-queues of the identified env_queue.

This argument may be used to introduce and control parallelism in the DWT processing steps, allowing you to distribute the load associated with multiple tile-components across multiple threads. In the simplest case, this argument is 0, and parallel processing applies only to the block encoding processes. For a small number of processors, this is usually sufficient to keep all CPU's active. If this argument is non-zero, however, the kdu_multi_analysis objects on which all processing is based, are created with double_buffering equal to true and a processing_stripe_height equal to the value supplied for this argument. See kdu_multi_analysis::create for a more comprehensive discussion of double buffering principles and guidelines.