kdu_stripe_compressor::push_stripe

See description of the first form of the push_stripe function.

See description of the first form of the push_stripe function.

See description of the first form of the push_stripe function.

If NULL, all component samples are deemed to have a nominal range of 1.0; that is, signed values lie in the range -0.5 to +0.5, while unsigned values lie in the range 0.0 to 1.0; equivalently, the precision is taken to be P=0. Otherwise, the argument points to an array with one precision value for each component. The precision value, P, identifies the nominal range of the input samples, such that signed values range from -2^{P-1} to +2^{P-1}, while unsigned values range from 0 to 2^P.

The value of P, provided by the precisions argument may be the same, larger or smaller than the actual bit-depth, B, of the corresponding image component, as provided by the Sprecision attribute (or the Mprecision attribute) managed by the siz_params object passed to kdu_codestream::create. The relationship between samples represented at bit-depth B and the floating point quantities supplied to this function is that the latter are understood to have been scaled by the value 2^{P-B}.

While this scaling factor seems quite natural, you should pay particular attention to its implications for small values of B. For example, when P=1 and B=1, the nominal range of unsigned floating point quantities is from 0 to 2, while the actual range of 1-bit sample values is obviously from 0 to 1. Thus, the maximum "white" value actually occurs when the floating point quantity equals 1.0 (half its nominal maximum value). For signed floating point representations, the implications are even less intuitive, with the maximum integer value achieved when the floating point sample value is 0.0. More generally, although the nominal range of the floating point component sample values is of size 2^P, a small upper fraction — 2^{-B} — of this nominal range lies beyond the range which can be represented by B-bit samples. You can use this "invalid" portion of the nominal range if you like, but values may be clipped during decompression. To minimize the impact of this small "invalid" fraction of the nominal range, you might choose to set the image bit-depth, B, to a large value when compressing data which you really think of as floating point data. This will also help to minimize the effective quantization error introduced by reversible compression, if used, although irreversible compression makes a lot more sense if you are working with floating point samples.

It is worth noting that this function, unlike its predecessors, allows P to take both negative and positive values. For implementation reasons, though, we restrict precisions to take values in the range -64 to +64. Also unlike its predecessors, this function does not limit the range of input samples. To a certain extent, therefore, you can get away with exceeding the nominal dynamic range, without causing overflow. This extent is determined by the number of guard bits. However, overflow problems might be encountered in some decompressor implementations if you take too many liberties here.

If NULL, the supplied samples for each component, c, are assumed to have a signed representation, with a nominal range from -2^{ precisions[c]-1} to +2^{ precisions[c]-1}. Otherwise, this argument points to an array with one element for each component. If is_signed[c] is true, the default signed representation is assumed for that component; if false, the component samples are assumed to have an unsigned representation, with a nominal range from 0.0 to 2^{ precisions[c]}. What this means is that the function subtracts 2^{ precisions[c]-1} from the samples of any component for which is_signed[c] is false — if precisions is NULL, 0.5 is subtracted.

See description of the first form of the push_stripe function.