| synopsis || return value || arguments || prev || next |
Overload navigation: 1, 2, 3, 4
bool pull_stripe( kdu_byte * stripe_bufs[], int stripe_heights[], int * sample_gaps=NULL, int * row_gaps=NULL, int * precisions=NULL)
[Declared in "../apps/support/kdu_stripe_decompressor.h"]
Decompresses new vertical stripes of samples from 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 — note that this value may have been modified by a call to kdu_codestream::apply_input_restrictions prior to supplying the kdu_codestream object to start. 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. 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 endeavour to advance the various image components in a proportional way, when processing incrementally (as opposed to decompressing the entire image into a single buffer, with 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 decompress the components in a proportional fashion, 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 decompressed depends upon how your stripe heights interact with image tiling. If the image is untiled, you are generally best off working with 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.
To understand the interpretation of the sample byte values retrieved by this function, consult the comments appearing with the precisions argument below. Other forms of the overloaded pull_stripe function are provided to allow for the accurate representation of higher precision image samples.
True until all samples of all image components have been decompressed and returned, at which point the function returns false.
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.
Array with one entry for each image component, identifying the number of lines to be decompressed for that component in the present call. All entries must be non-negative. See the discussion above, on the various constraints and guidelines which may exist regarding stripe heights and their interaction with tiling and sub-sampling.
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.
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.
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 significant bits used to represent each sample. If this value is less than 8, the remaining most significant bits in each byte will be set to 0.
There is no implied connection between the precision values, P, and the bit-depth, B, of each image component, as found in the code-stream's SIZ marker segment, and returned via kdu_codestream::get_bit_depth. The original image sample bit-depth, B, 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 the B-bit integers associated with the original compressed image components.
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 B=1 bit, as recorded in the code-stream main header. If the value of P provided by the precisions array is set to 1, the bi-level image information is written into 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 written into the most significant bit of each byte.
The sample values recovered using this function are always unsigned, regardless of whether or not the original image samples had a signed or unsigned representation (as recorded in the SIZ marker segment, and returned via kdu_codestream::get_bit_depth). If the original samples were signed, or the application requires a signed representation for other reasons, the application is responsible for level adjusting the data returned here, subtracting 2^{P-1} from the unsigned values.
| top || synopsis || return value || arguments || prev || next |