hpbit_stream_in_local.h

JPEG2000实现的源码

     subsequently converted to pre-markers having the form expected by
     the `stream_in__size_marker_elt' and `stream_in__get_marker_val'
     interface functions.
         The `total_codestream_bytes' field holds the sum of the `num_bytes'
     fields from all elements of the list referenced by the
     `codestream_markers' field, plus the number of bytes associated with
     the SOC or SOT/SOD markers which form part of the relevant scope
     (global markers or tile-specific markers), but are not explicitly
     included on the list of codestream markers for simplicity. */

/*****************************************************************************/
/*                              hpbit_tilepart                               */
/*****************************************************************************/

typedef
  struct hpbit_tilepart {
    int tnum;
    int tpart, num_tileparts;
    int resync;
    int eph;
    hpbit_markers markers;
    std_ushort packet_sequence_idx;
    int data_bytes, data_bytes_left, actual_length_unknown;
    std_byte *data_handle, *data;
    hpbit_packed_head_ptr packed_heads;
    struct hpbit_tilepart *last_part;
    struct hpbit_tilepart *next;
  } hpbit_tilepart, *hpbit_tilepart_ptr;
  /* This structure manages a single tile-part in the codestream.  It is
     capable of buffering the tile part if necessary, but every effort is
     made to avoid buffering the codestream inside this object, unless the
     sequence in which information is requested makes this unavoidable.
         `tnum' holds the zero-based tile index for the tile part.  There
     is no guarantee that tiles appear in any particular sequence in the
     codestream.
         `tpart' holds the zero-based tile-part index.  Tile parts from the
     same tile must appear in sequence within the codestream and the primary
     function of this field is to verify this fact.
         `num_tileparts' holds the total number of tile-parts expected for
     this tile.  This information is important, since it enables the
     decoder to determine when it has recovered the last packet which is
     available in the codestream for each tile.  Otherwise, the decoder
     might have to buffer the entire codestream before it could be certain
     of having received all the information for any particular packet.
         `markers' manages markers for the tile-part.  Most tile-specific
     markers must appear in the first tile-part of a tile, but there are some
     exceptions.
         The `resync' field indicates whether or not resync markers are
     to be used in the current tile part.
         The `eph' field indicates whether or not End-Of-Packet-Head markers
     are to be used in the current tile part.
         `packet_sequence_idx' holds the sequence index for the next packet's
     resynchronization marker, when `resync' is non-zero.  The sequence
     index cycles through the range 0 to 2^16-1.  Packet sequence numbers
     are unique to each tile, but span tile-part boundaries within the tile.
     Once all packets from one tile part have been consumed the packet
     sequence index is copied into the next tile-part for that tile.
         The `data_bytes' field holds the total number of bytes in the
     tile-part, starting immediately after the SOD marker, up until (but not
     including) the next SOT or EOC marker.  This field is initially set
     based upon the tile-part length field in the SOT marker, but may be
     modified if an SOT marker or an EOC marker is encountered prematurely,
     suggesting a corrupted length field, or if the end of the file is
     encountered.  It is also reduced as necessary to reflect any limit
     imposed by the `max_bytes' field of the containing object.
         The `data_bytes_left' field identifies the number of data bytes
     from the tile-part which have not been accessed; all data bytes in a
     tile-part must be accessed through the relevant packet calls (i.e.
     `start_packet', `pull_head_bytes', `pull_body_bytes' and `end_packet').
     The value of this field is initially set identical to `data_bytes'.
         The `actual_length_unknown' flag is set if the SOT marker contains
     0 in the tile-length field; this is legal only for the last-tile-part
     in the codestream; in this case, the `data_bytes' and `data_bytes_left'
     fields represent upper bounds on the length, based upon file truncation
     lengths, if any, until the codestream has actually been read from the
     file.
         The `data' field will be NULL unless some attempt has been made to
     access header information from a later tile or tile-part, in which case
     the `data' field points to an array containing `data_bytes_left'
     entries, representing the contents of the remaining portion of the
     tile-part which has not yet been read, up until (but not including) the
     next SOT or EOC marker.  We deliberately avoid file seeks here, to ensure
     support for non-seekable file streams (e.g. stdin).  It is the
     responsibility of client objects to avoid requesting tile-specific
     markers until they really need to so as to minimize the
     amount of the bit-stream which must actually be buffered up.
         The `data_handle' field points to the block of memory which was
     allocated (if any) to hold the buffer into which the `data' field
     points.  The `data' field is advanced as data is consumed from the
     tile-part, but the `data_handle' field is left unchanged, so that the
     array can later be deallocated.
         The `packed_heads' field is NULL unless the current tile-part's
     packet heads have been packed into a PPT/PPM marker, in which case the
     relevant head bytes are retrieved via this list.
         The `last_part' field points to the previous tile-part from the
     same tile; it holds NULL if this is the first tile-part. */

/*****************************************************************************/
/*                            hpbit_stream_in_obj                            */
/*****************************************************************************/

typedef
  struct hpbit_stream_in_obj {
    stream_in_obj base;
    FILE *fp;
    hpbit_markers global_markers;
    hpbit_tilepart_ptr tileparts, current_tilepart;
    int byte_limit_set, max_bytes;
    int non_data_bytes_left;
    int have_sot;
    int global_resync;
    int global_eph;
    int eph_found;
    int missing_packets;
    int virgin_tilepart;
    int open_packet;
    int packet_bytes;
    int num_non_compliant_markers;
    int failed_marker_translations;
    hpbit_stored_heads_ptr stored_heads;
  } hpbit_stream_in_obj, *hpbit_stream_in_ref;
  /* This structure defines the augmented state of the `stream_in' object
     created by `create_reference_stream_in'.
         `fp' points to the open file associated with the bit-stream.
         `global_markers' contains all information concerning the markers
     found in the global header of the codestream, i.e. before the first
     tile header.
         `tileparts' points to a linked list of `hpbit_tilepart' structures
     for which tile- or tile-part-specific information is available.  The
     elements in this list appear in the same order as the tile-parts appear
     in the codestream; however, there is no guarantee that this order follows
     any predictable pattern at all.  Elements are added to the list only as
     necessary.
         `current_tilepart' points to the element of the `tileparts' list which
     represents the tile-part from which packets are currently being read.
         `byte_limit_set' indicates whether or not any limit is set to
     the number of bytes which may be read from the file.
         `max_bytes' is valid only if `byte_limit_set' is true (non-zero),
     in which case it always holds the byte limit supplied during the
     call to `stream_in__set_max_bytes'.
         `non_data_bytes_left' holds the quantity L-A where L denotes the
     byte limit stored in `max_bytes' and A denotes the anticipated number
     of bytes from the start of the file up until the end of the last
     tile-part whose header has been read.  While reading the global header
     or any tile-part header, A is simply the total number of bytes consumed
     from the file so-far.  While reading data from a tile-part, A denotes
     the total number of bytes which will have been read from the file once
     the tile-part data has been completely consumed.
         `have_sot' indicates whether or not the 2 byte marker code of
     an SOT marker has most recently been consumed from the file.  Since
     the SOT marker serves as an important delimiter for various file
     reading events, this flag often gets raised; subsequent attempts to
     read a new tile-part header use this flag to determine whether or not
     the SOT marker needs to be read.
         `global_resync' holds 1 or 0, depending upon whether resync (SOP)
     markers are expected before each packet as the global ERS style.
     The flag is copied into each individual tile-part's `resync' field, until
     explicitly overridden in one or more tile-parts.
         `global_eph' holds 1 or 0, depending upon whether end-of-packet-head
     (EPH) markers are expected before each packet as the global ERS style.
     The flag is copied into each individual tile-part's `eph' field, until
     explicitly overridden in one or more tile-parts.
         `missing_packets' will normally be zero, except when resync markers
     are being used in the current tile-part and one or more packets from
     the tile-part are judged to be corrupt or missing.  If the current
     packet is found to be corrupt (usually by encountering a resync marker
     unexpectely), or if the next anticipated resync marker is not found at
     the end of a packet, input bytes are consumed until the next valid
     resync marker is encountered and the number of missing packets
     (including the current one, if the problem occurs before the
     `end_packet' call) is calculated and set into the `missing_packets'
     field.
         `eph_found' is a flag which is reset at the start of each packet
     and set only if an EPH marker is found in the packet; later, we could
     use the marker for error resilience.
         `virgin_tilepart' is a flag holding 1 if no packets have yet been
     opened from the tile-part; otherwise, it holds 0.
         `open_packet' is non-zero if a `start_packet' call has not been
     concluded by a matching `end_packet' call.
         `packet_bytes' keeps track of the total number of bytes in the
     current packet, including resync markers and any extra bytes which
     must be stuffed to avoid misdetection of resync markers.
         `num_non_compliant_markers' indicates the total number of codestream
     markers which the decompressor must understand to meaningfully decompress
     the codestream, yet which are not currently compliant with the
     standard.
         `failed_marker_translations' indicates the total number of markers
     which appear to convey information essential for successful decompression,
     yet could not be successfully translated.
         `stored_heads' points to a list of tile-part packed packet header
     information with one entry in the list for each tile-part.  The list
     is created when a PPM marker is encountered and elements are stripped
     from its head as each new tile-part is encountered in the codestream. */

#endif /* HPBIT_STREAM_IN_LOCAL_H */