Kakadu Hyper-Doc (kdu_cache::add_to

virtual void add_to_databin( int databin_class, kdu_long codestream_id, kdu_long databin_id, kdu_byte data[], int offset, int num_bytes, bool is_final, bool add_as_most_recent=true, bool mark_if_augmented=false)

Synopsis

Augments the cached representation of the indicated data-bin. The data-bin is identified by a class code, databin_class, a code-stream ID (normally 0, unless the cache is used to manage multiple code-streams simultaneously) and an in-class identifier, databin_id. Currently, the classes defined by this object are KDU_META_DATABIN, KDU_MAIN_HEADER_DATABIN, KDU_TILE_HEADER_DATABIN, KDU_PRECINCT_DATABIN and KDU_TILE_DATABIN.

The KDU_META_DATABIN class is used with JP2-family file formats to communicate meta-data and file structure information. Amongst other things, this meta-data provides the framework within which the content of code-stream specific data-bins are to be interpreted. This data-bin class may be used only with codestream_id=0. Raw code-streams have exactly one meta data-bin (the one with databin_id=0) which must be empty — it must be signalled as finalized after transferring 0 bytes of content data.
For the KDU_MAIN_HEADER_DATABIN class, the in-class identifier must be equal to 0, while the code-stream identifier indicates the code-stream whose main header is being augmented.
For the KDU_TILE_HEADER_DATABIN class, the in-class identifier ( databin_id) holds the tile number, starting from 0 for the tile in the upper left hand corner of the image.
For the KDU_PRECINCT_DATABIN class, the in-class identifier has the interpretation described in connection with kdu_compressed_source::set_precinct_scope.
For the KDU_TILE_DATABIN class, the in-class identifier has the same interpretation as for KDU_TILE_HEADER_DATABIN. Generally, an interactive communication involves either the KDU_TILE_HEADER_DATABIN and KDU_PRECINCT_DATABIN classes, or the KDU_TILE_DATABIN class, but not both.

New data may be added to the cache in any desired order, which is why the absolute location ( offset) and length ( num_bytes) of the new data are explicitly specified in the call. If the new data range overlaps with data which already exists in the cache, the present function may either overwrite or leave the overlapping data bytes as they were. Both interpretations are assumed to produce the same result, since the nominal contents of any given data-bin are not permitted to change over time.

Arguments

databin_class [int]

codestream_id [kdu_long]

databin_id [kdu_long]

data[] [kdu_byte]

offset [int]

num_bytes [int]

is_final [bool]

If true, the cache is being informed that the supplied bytes represent the terminal portion of the data-bin. If there are no holes, the cache representation is complete. If there are holes, the cache representation of the data-bin will be complete once these holes have been filled in. At that time, the get_databin_length function will set an is_complete argument to true.

add_as_most_recent [bool]

If true, the data-bin to which data is added is automatically promoted to the head of the "most recently used" list. Otherwise, the data-bin's current position in the list is not affected. If a new data-bin entry needs to be created in the cache and the add_as_most_recent argument is false, the new entry is placed at the tail of the "most recently used" list, not its head.

mark_if_augmented [bool]

If true, the data-bin's marking flag will be set (future calls to mark_databin will return true) if and only if the present call augments the cached contents of the indicated data-bin. This is useful when adding data obtained from a cache file generated during a previous browsing session. The marked state can then be used to keep track of data-bins whose state is not fully known by a server.

kdu_cache::add_to_databin

Java: Kdu_cache::Add_to_databin