jpx_source::access_codestream

Provides access to the codestream identified by which. If which is 0, this is the first codestream in the data source; if which is 1, it is the second codestream in the data source, and so forth.

If the function is unable to access the requested codestream at present, it returns an empty interface (one whose jpx_codestream_source::exists function returns false). This may happen either because the total number of codestreams in the data source is less than or equal to which, or because the function is not yet able to parse far enough into the data source to recover the relevant boxes along with the code-stream's main header. The latter generally occurs only if the underlying jp2_family_src objct is fueled by a dynamic cache (i.e., a kdu_cache object).

Before this function will return a non-empty interface, it must have encountered the contiguous codestream (jp2c) or fragment table (ftbl) box which holds the codestream's contents. For data sources which are fueled by a dynamic cache, the entire code-stream main header must also be available already. The object must also have either seen all top level box headers in the data source, or have encountered both the JP2 header (jp2h) box and the relevant codestream header (chdr) box.

In other words, the function will not return a non-empty interface until it can be sure that all relevant information has been parsed from the data source and the codestream box itself can at least be successfully opened using jpx_codestream_source::open_stream. These conditions are more stringent than those required to count codestreams, so that which may be much less than the number returned by count_codestreams, yet this function still returns an empty interface. This just means that the underlying dynamic cache must receive more data before the codestream can be accessed.

which [int]