kdu_precinct::size_packets

This function may be used by server applications to determine an appropriate number of packets to deliver to a client in a single batch. Applications interact with the size_packets and get_packets functions in an alternating fashion.

The application first calls size_packets one or more times to determine the number of bytes associated with a certain number of packets or vice-versa (see below). It then calls get_packets to actually generate the data bytes from a range of packets. Thereafter, the application may go back to sizing packets again and so forth. Between sizing and generating packet data, the internal packet coding state machinery is reset, which incurs some computational effort. For this reason, it is desirable to keep the number of switches between sizing and generating packet data to a minimum.

During a single sizing session (i.e., after the last generation session, if any, and before the next one), the internal machinery keeps track of the number of packets which have been sized already. It also keeps track of the total number of bytes represented by these sized packets. If the number of sized packets is less than the value of cumulative_packets on entry, or if the total size of all packets sized so far (starting from the first packet of the precinct) is less than cumulative_bytes, the function sizes one or more additional packets. This continues until the number of sized packets reaches or exceeds the value of cumulative_packets and the total number of bytes associated with these sized packets reaches or exceeds the value of cumulative_bytes. The function returns after setting the value of cumulative_packets to reflect the total number of sized packets and the value of cumulative_bytes to reflect the total number of bytes associated with all packets sized so far.

Once the number of sized packets reaches the number of apparent quality layers, as set by any call to kdu_codestream::apply_input_restrictions, the function will return without attempting to size further packets.

The behaviour described above may be exploited in a variety of ways. If a server has already transmitted some number of packets to a client, the number of bytes associated with these packets may be determined by setting cumulative_bytes to 0 and setting cumulative_packets equal to the number of packets which have been transmitted. Alternatively, if the server remembers the number of bytes which have been transmitted, this may be converted into a number of packets by calling the function with cumulative_bytes equal to the number of transmitted bytes and cumulative_packets equal to 0. The server may then use the function to determine the number of additional layers which can be transmitted, subject to a given size restriction. The results of such simulations may be used to drive the get_packets function. In this way, it is possible to implement memory efficient servers whose state information consists of as little as a single 16-bit integer (sufficient for packets consisting of only a few blocks) for each precinct, representing the number of bytes actually transmitted for that precinct's packets.

Remember, that after generating packet data with get_packets, sizing calls start from scratch with the first packet in the precinct.

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.

cumulative_packets [int &]

cumulative_bytes [int &]

is_significant [bool &]