kdu_compressed_source::get_capabilities

Returns the logical OR of one or more capability flags, whose values are identified by the macros, KDU_SOURCE_CAP_SEQUENTIAL, KDU_SOURCE_CAP_SEEKABLE and KDU_SOURCE_CAP_CACHED. These flags have the following interpretation:

• KDU_SOURCE_CAP_SEQUENTIAL: If this flag is set, the source supports sequential reading of data in the order expected of a valid JPEG2000 code-stream. If this flag is not set, the KDU_SOURCE_CAP_CACHED flag must be set.
• KDU_SOURCE_CAP_SEEKABLE: If this flag is set, the source supports random access using the seek function. Most file or memory based sources should support seeking, although disabling the seeking capability can have useful effects on the sequencing of code-stream parsing operations. In particular, if the source advertises seekability, Kakadu will attempt to use optional pointer marker segments to minimize code-stream buffering. In some cases, however, this may result in undesirable disk access patterns. Error resilience is also weakened or destroyed when seeking is employed.
• KDU_SOURCE_CAP_CACHED: If this flag is set, the source is a client cache, which does not guarantee to support regular sequential reading of the code-stream beyond the end of the main header. To access individual tile headers, the set_tileheader_scope function must be invoked. To access packet data for individual precincts, the set_precinct_scope function must be used.

Cached sources might conceivably support sequential reading as well, meaning that it is possible to read the code-stream linearly as if it were organized in a file. However, in most cases only one of the KDU_SOURCE_CAP_SEQUENTIAL and KDU_SOURCE_CAP_CACHED flags will be set.

Both cached and sequential sources may support seekability. If a cached source is seekable, seeking is performed with respect to the current scope. Specifically, this is the scope of the precinct associated with the most recent call to set_precinct_scope or the tile header associated with the most recent set_tile_header_scope, whichever call was invoked most recently, or the scope of the main code-stream header, if neither set_precinct_scope nor set_tile_header_scope has yet been called.