| synopsis || return value || arguments || prev || next |
kds_chunk * generate_increments( int suggested_data_bytes, int & max_data_bytes, bool align=false, bool use_extended_message_headers=false, bool decouple_chunks=true, kds_id_encoder * id_encoder=NULL)
[Declared in "../apps/kdu_server/kdu_serve.h"]
This function returns a linked list of kds_chunk objects, representing new elements of the JPEG2000 compressed imagery or meta-data which is relevant to the window most recently passed to set_window. The chunks contain one or more whole JPIP messages, each of which represents a byte range from one such element. Possible elements are meta data-bins, precinct data-bins, code-stream main header data-bins and tile header data-bins. The object does not currently support delivery of tile data-bins, which offer substantially less flexibility. It is possible that some messages which have previously been generated by this function will overlap with the new messages, resulting in redundant transmission by the server application. This may happen if the truncate_cache_model function is used to clear the server's memory of information it may previously have generated.
Server applications typically call this function repeatedly, indicating the total number of data bytes which they would like to be contained in the returned chunks. Note carefully, that the suggested_data_bytes limit includes only the bodies of the messages contained in the returned list of kds_chunk objects. Messages and their headers are described by the JPIP standard (currently committee draft, but will become IS 15444-9).
Applications will ideally select suggested_data_bytes on the basis of their current estimates regarding the communication bandwidth. If the application attempts to transfer too much data from the current window to a remote client, the client's window of interest may change before the data can be transmitted. On the other hand, each call to this function can be quite expensive, so servers will not want to call generate_increments more frequently than necessary. Ideally, the function is called only once, between changes in the client's window of interest, but changes in the client's interests are not generally predictable in an interactive application.
Prior to return, the kdu_serve object updates its internal cache model, based on the assumption that all of the chunks will be successfully transmitted to a client which inserts all relevant data into its cache. In some cases, the application may opt not to send some or all of the chunks to a client. For example, if a remote user changes his/her window of interest dramatically before all outstanding chunks have been transmitted, the server application may choose to abandon some of the chunks. This is acceptable, so long as the application informs the kdu_serve object that it has abandoned these chunks. This may be done by asserting check_abandoned=true in the call to release_chunks. In this case, the application is expected to have marked all of the chunks which were reliably transmitted by setting their abandoned fields to false.
If the application has used the push_extra_data function to push extra data onto the internal extra data queue (as opposed to pushing it onto the end of a list of chunks returned by this function), the extra data will be included in the first chunk returned by this function, until there is no extra data left. In this case, it is possible that the present function will return no compressed image or meta-data elements at all, since the byte limit may be exhausted by the extra data.
The function will NEVER return a NULL pointer. If there is no data available, the function may return a single chunk, whose num_bytes field is set to 0. This ensures that there is always a non-empty list of data chunks which can be passed to the push_extra_data function, if required.
Suggested number of bytes in the bodies of the messages from which the returned chunks are composed. Each chunk is a concatenated list of messages, each containing a header, followed by a body, which consists of a byte range from a single data-bin (precinct, code-stream header or meta data-bin). The message headers are not included in the limit represented by suggested_data_bytes or max_data_bytes. The suggested_data_bytes limit is not interpreted strictly; instead, the function tries to include whole packets from as many relevant precinct data-bins as possible, until the suggested limit is exceeded. It may thus be exceeded by a considerable margin if packets are very large.
This argument provides a strict limit on the number of data bytes which can be included in the bodies of messages in the returned chunk list. The limit will not be exceeded unless it is impossible to avoid. This means that partial packets may be included from the final precinct data-bin which contributes to the chunk list. Upon return, the value of this variable is decremented by the actual number of message body bytes, allowing the caller to keep track of the number of bytes which can be generated in a subsequent call to the function, unless the limit has changed. The only event in which the limit may be exceeded is if the limit is greater than 0 but not sufficiently large to allow the inclusion of a single message.
If true, each message generated by this function which crosses a precinct packet boundary will finish at a subsequent packet boundary. The option has no effect on messages which correspond to data-bins other than precinct data-bins.
If true, each message which corresponds to a precinct data-bin will use the extended header format, which includes an indication of the number of complete quality layers represented by the message together with all bytes from the precinct which precede those in the message.
If true (this is a reasonable default), the first message written to each chunk will have its header coded in a manner which does not rely on successful delivery of messages in other chunks. Specifically, in this case the id_encoder→decouple function will be called prior to writing each new chunk. For applications in which the messages are delivered over a reliable stream oriented connection, it may be sufficient to decouple the message header coding only at the commencement of each response stream sent by the server (or even once per channel). In such cases, the application may choose to realize some small efficiency improvements by setting this argument to false. However, the application is then responsible for explicitly invoking the id_encoder→decouple function at appropriate junctures.
Used to supply a custom function for encoding unique data-bin identifiers. If this argument is NULL, the default id encoding implementation will be used, as described in the initial comments appearing with the kds_id_encoder class.
| top || synopsis || return value || arguments || prev || next |