kdu_precinct::get_packets

This function plays a complementary role to that of size_packets, except that it actually generates packet data, rather than just simulating and sizing packets. As with that function, packets are generated in sequence and the function may be called multiple times. The first call sets the state of the internal machinery to indicate that packets are now being generated, rather than sized, and it resets internal counters identifying the number of packets which have been generated so far and the cumulative number of bytes associated with those packets. In each call to the function, zero or more additional packets are generated until the total number of packets which have been generated so far reaches or exceeds the value of cumulative_packets and the number of bytes associated with these packets reaches or exceeds the value of cumulative_bytes.

Each generated packet is exported to the supplied kdu_output derived object, out, except in the event that the packet index (starting from 0) is less than the value of leading_skip_packets or the cumulative number of bytes associated with all packets generated so far is less than the value of leading_skip_bytes.

On exit, the values of cumulative_packets and cumulative_bytes are adjusted to reflect the total number of packets which have been generated and the total number of bytes associated with these packets, regardless of whether these packets were all written out to the out object.

If further sizing is performed after some packet data has been generated using the current function, sizing starts from scratch with the first packet again. Any subsequent generation of packet data then also starts from scratch, so that the same packets may be generated multiple times. The principle purpose of the leading_skip_bytes argument is to skip over previously generated packets when the application must ping-pong between sizing and generating data.

The curious reader may well wonder at this point how the function determines which code-block contributions should belong to which packet. This decision is based on the conventions described with the kdu_block::pass_slopes member array. In particular, the function assumes that code-block contributions which are assigned a pass slope of 0xFFFF-q belong to quality layer q, where the quality layer indices start from q=0. In most cases, the code-block data will be recovered from a separate input codestream, in which case the pass slope values will be set up to have exactly this interpretation already.

False if one or more of the precinct's code-blocks have yet to be loaded ( check_loaded would return false); in this case, the function does nothing else.

leading_skip_packets [int]

leading_skip_bytes [int]

cumulative_packets [int &]

cumulative_bytes [int &]

out [kdu_output *]