| synopsis || return value || arguments || prev || next |

kdu_stripe_compressor::push_stripe

Overload navigation: 1, 2, 3, 4, 5, 6, 7, 8

bool push_stripe( kdu_byte * stripe_bufs[], int stripe_heights[], int * sample_gaps=NULL, int * row_gaps=NULL, int * precisions=NULL, int flush_period=0)

[Declared in "../apps/support/kdu_stripe_compressor.h"]

Go to class description.


Synopsis

Supplies vertical stripes of samples for each image component. The number of entries in each of the arrays here is equal to the number of image components, as returned by kdu_codestream::get_num_components with its optional want_output_comps argument set to true. Each stripe spans the entire width of its image component, which must be no larger than the ratio between the corresponding entries in the row_gaps and sample_gaps arrays.

Each successive call to this function advances the vertical position within each image component by the number of lines identified within the stripe_heights array. To properly compress the image, you must eventually advance all components to the bottom. At this point, the present function returns false (no more lines needed in any component) and a subsequent call to finish will return true.

Note that although components nominally advance from the top to the bottom, if kdu_codestream::change_appearance was used to flip the appearance of the vertical dimension, the supplied data actually advances the true underlying image components from the bottom up to the top. This is exactly what one should expect from the description of kdu_codestream::change_appearance and requires no special processing in the implemenation of the present object.

Although considerable flexibility is offered with regard to stripe heights, there are a number of constraints. As a general rule, you should attempt to advance the various image components in a proportional way, when processing incrementally (as opposed to supplying the entire image in a single call to this function). What this means is that the stripe height for each component should, ideally, be inversely proportional to its vertical sub-sampling factor. If you do not intend to do this for any reason, the following notes should be taken into account:

In addition to the constraints and guidelines mentioned above regarding the selection of suitable stripe heights, it is worth noting that the efficiency (computational and memory efficiency) with which image data is compressed depends upon how your stripe heights interact with image tiling. If the image is untiled, you are generally best off passing small stripes, unless your application naturally provides larger stripe buffers. If, however, the image is tiled, then the implementation is most efficient if your stripes happen to be aligned on vertical tile boundaries. To simplify the determination of suitable stripe heights (all other things being equal), the present object provides a convenient utility, get_recommended_stripe_heights, which you can call at any time. Alternatively, just push in whatever stripes your application produces naturally.

To understand the interpretation of the sample bytes passed to this function, consult the comments appearing with the precisions argument below. Other forms of the overloaded push_stripe function are provided to allow for compression of higher precision image samples.


Return Value

True until all samples for all image components have been pushed in, at which point the function returns false.

Arguments

stripe_bufs[] [kdu_byte *]

Array with one entry for each image component, containing a pointer to a buffer which holds the stripe samples for that component. The pointers may all point into a single common buffer managed by the application, or they might point to separate buffers. This, together with the information contained in the sample_gaps and row_gaps arrays allows the application to implement a wide variety of different stripe buffering strategies. The entries (pointers) in the stripe_bufs array are not modified by this function.

stripe_heights[] [int]

Array with one entry for each image component, identifying the number of lines being supplied for that component in the present call. All entries must be non-negative. See the extensive discussion above, on the various constraints and guidelines which may exist regarding stripe heights and their interaction with tiling and sub-sampling.

sample_gaps [int *]

Array containing one entry for each image component, identifying the separation between horizontally adjacent samples within the corresponding stripe buffer found in the stripe_bufs array. If this argument is NULL, all component stripe buffers are assumed to have a sample gap of 1.

row_gaps [int *]

Array containing one entry for each image component, identifying the separation between vertically adjacent samples within the corresponding stripe buffer found in the stripe_bufs array. If this argument is NULL, all component stripe buffers are assumed to hold contiguous lines from their respective components.

precisions [int *]

If NULL, all component precisions are deemed to be 8; otherwise, the argument points to an array with a single precision value for each component. The precision identifies the number of least significant bits which are actually used in each sample. If this value is less than 8, one or more most significant bits of each byte will be ignored.

There is no implied connection between the precision values, P, and the bit-depth of each image component, as provided by the Sprecision attribute managed by the siz_params object passed to kdu_codestream::create. The original image sample bit-depth may be larger or smaller than the value of P, supplied via the precisions argument. In any event, the most significant bit of the P-bit integer represented by each sample byte is aligned with the most significant bit of image sample words which we actually compress internally. Zero padding and discarding of excess least significant bits is applied as required.

These conventions, provide the application with tremendous flexibility in how it chooses to represent image sample values. Suppose, for example, that the original image sample precision for some component is only 1 bit, as represented by the Sprecision attribute managed by the siz_params object (this is the bit-depth value actually recorded in the code-stream). If the value of P provided by the precisions array is set to 1, the bi-level image information is embedded in the least significant bit of each byte supplied to this function. On the other hand, if the value of P is 8, the bi-level image information is embedded in the most significant bit of each byte.

The sample values supplied to this function are always unsigned, regardless of whether or not the Ssigned attribute managed by siz_params identifies an image component as having an originally signed representation. In this, relatively unlikely, event, the application is responsible for level adjusting the original sample values, by adding 2^{P-1} to each originally signed value.

flush_period [int]

This argument may be used to control Kakadu's incremental code-stream flushing machinery, where applicable. If 0, no incremental flushing will be attempted. Otherwise, the function checks to see if at least this number of lines have been pushed in for the first image component, since the last successful call to kdu_codestream::flush (or since the call to start). If so, an attempt is made to flush the code-stream again, after first calling kdu_codestream::ready_for_flush to see whether a new call to kdu_codestream::flush will succeed. Incremental flushing is possible only under a very narrow set of conditions on the packet progression order and precinct dimensions. For a detailed discussion of these conditions, you should carefully review the comments provided with kdu_codestream::flush before trying to use this feature.


| top || synopsis || return value || arguments || prev || next |