kdu_subband::open_block

Code-block access is bracketed by calls to open_block and close_block. It is currently illegal to have more than one code-block open at once. In fact, the underlying structure manages storage for a single kdu_block object, returning a pointer to this object in response to the open_block call. The restriction on multiple simultaneously open code-blocks could, however, easily be removed to support parallel processing implementations.

It is also illegal to open any given block a second time without first closing the tile (input codestreams) or the relevant precinct (interchange codestreams) and re-opening it. Moreover, such activities are permitted only with interchange codestreams or input codestreams which have been set up for persistence by calling the kdu_codestream::set_persistent function.

This restriction on multiple openings of any given code-block is important for the efficiency of the system, since it allows the internal machinery to determine when resources can be destroyed, recycled or temporarily swapped out of memory. Applications which do wish to open blocks multiple times will generally be happy to close and re-open the tile (or precinct) anyway.

The returned kdu_block object contains all necessary information for encoding or decoding the code-block, including its dimensions, coding mode switches and so forth.

For input codestreams (created using the particular form of the overloaded kdu_codestream::create function which takes a compressed data source), the block will have all coding pass and code-byte information intact, ready to be decoded.

Otherwise (output or interchange codestreams), all relevant members of the returned kdu_block object will be initialized to the empty state, ready to accept newly generated (or copied) code bytes.

It is worth noting that opening a block may have far reaching implications for the internal code-stream management machinery. Precincts may be created for the first time; packets may be read and de-sequenced; tile-parts may be opened and so forth. There is no restriction on the order in which code-blocks may be opened, although different orders can have very different implications for the amount of the code-stream which must be buffered internally, especially if the compressed data source does not support seeking, or the code-stream does not provide seeking hints (these are optional JPEG2000 marker segments).

Although this function may be used with interchange codestreams, its namesake in the kdu_precinct interface is recommended instead for interchange applications. For more on this, consult the comments appearing with kdu_precinct::open_block and kdu_precinct::close_block.

block_idx [kdu_coords]

return_tpart [int *]