| synopsis || return value || arguments || prev || next |
kdrc_stream * get_next_codestream( kdrc_stream * last_stream_ref, bool only_active_codestreams, bool no_duplicates)
[Declared in "../apps/support/kdu_region_compositor.h"]
You may use this function to walk through the various codestreams which are currently open within the object. The codestreams are referenced by an opaque pointer type, kdrc_stream, which is provided only to enhance type checking (it could be any address for all you care).
It is important to realize that an underlying JPEG2000 code-stream may be used multiple times within a single image composition. For example, a single composed image may use the same code-stream to create a compositing layer which is placed at the top left hand corner of the compositing surface, and another layer which is overlayed at the bottom right hand corner of the compositing surface, possibly even with different scales.
To distinguish between such multiple uses, the present function is best understood as returning references to "layer codestreams". A layer codestream is associated with exactly one real JPEG2000 code-stream, and at most one compositing layer. Both the code-stream index and the layer index may subsequently be retrieved by calling get_codestream_info.
If you are using the present function to scan through real JPEG2000 code-streams, you may wish to set the no_duplicates argument to true. Where a JPEG2000 code-stream is shared by multiple layer codestreams, this option will ensure that only one of the layer codestreams will appear in the sequence. You have no guarantees regarding which of the layer codestreams which share a common JPEG2000 code-stream will appear in the sequence, except that if any of them is active, the layer codestream which appears in the sequence will be one of the active ones.
There are two types of layer codestreams: 1) those which are currently in use (active), contributing to the composited image which is being (or has been) built; and 2) those which are inactive, but have not been permanently destroyed. Included in the latter category are code-streams which were opened to serve compositing layers which have since been removed using remove_compositing_layer, but not permanently. The only_active_codestreams argument determines whether you wish to scan through only the active code-streams, or both the active and inactive code-streams.
To access the first layer codestream in sequence, supply a NULL last_stream_ref argument. The next layer codestreams in sequence may then be retrieved by supplying the previously returned pointer as the last_stream_ref argument in a subsequent call to this function. The actual sequence in which the layer codestreams appear has no particular significance and may potentially change each time a set of compositing layers is configured. However, you can be guaranteed that all active layer codestreams will appear before any inactive layer codestreams in the sequence.
Opaque pointer which may be passed to access_codestream or get_codestream_info, or used with the present function to advance to the next layer codestream in sequence.
If NULL, the returned pointer references the first layer codestream in sequence. Otherwise, the function returns a reference to the stream following that identified by last_stream_ref, after skipping over any duplicates (if no_duplicates=true).
If true, the sequence of layer codestreams returned by this function will include only those on the internal active list; not the inactive ones.
If true, the sequence of layer codestreams returned by this function will skip layer codestreams as required to ensure that only one of the layer codestreams which use any given JPEG2000 code-stream will be seen.
| top || synopsis || return value || arguments || prev || next |