ref_roi_common.h

JPEG2000实现的源码

         The `parent' field points to the `roi_stage' object which from which
     ROI information should be requested via its `pull_mask_line' interface
     function.  The field will be NULL if and only if this is the root of the
     tree, in which case ROI information must be derived directly from the
     `regions' list.
         The `regions' field either holds NULL or else points to a list of
     records, each of which holds the boost and geometry for a particular
     region of interest.  At the root of the tree, i.e. when `parent' is NULL,
     the `regions' field simply holds a copy of the pointer to the list
     managed by the relevant `roi_component_info' structure.  If the
     `roi_component_info' structure's `is_rectangular' field is non-zero
     (i.e. true), then all entries in the list must have purely rectangular
     geometries.  Moreover, in this and only this case, the `regions' field
     for non-root stages will be non-NULL.  Specifically, when all region
     geometries are rectangular, the `regions' list for each stage will be
     generated on-demand as each stage invokes its parent's
     `roi_stage__get_mask_rects' function.  Then, requests for mask
     information from the encoder or decoder objects will be satisfied
     immediately by examining the relevant lists.  For non-rectangular
     region geometries, the `regions' pointer will be NULL in non-root
     stages.
         The `buffer' structure manages the dynamic buffering of rows of
     ROI boost masks obtained from either the parent or directly from the
     regions (if `parent' is NULL).

     SAIC General Decomp. Begin
         `vert_limit' indicates the number of vertical wavelet splits for
     the current stage.  The normal value for this field is 2 and would result
     in vertically lowpass and highpass downsampled versions of the input to
     this stage.  A value of 1 indicates that filtering and downsampling
     should not be performed in the vertical direction in this stage.
         `horiz_limit' indicates the number of horizontal wavelet splits for
     the current stage.  The normal value for this field is 2 and would result
     in horizontally lowpass and highpass downsampled versions of the input to
     this stage.  A value of 1 indicates that filtering and downsampling
     should not be performed in the horizontal direction in this stage.
     SAIC General Decomp. End */

/*****************************************************************************/
/*                             roi_horizontal_obj                            */
/*****************************************************************************/

typedef
  struct roi_horizontal_obj {
    roi_stage_obj base;
    int next_branch_row[2];
  } roi_horizontal_obj, *roi_horizontal_ref;
  /* This structure defines a horizontal ROI mask generation stage object,
     derived from the basic `roi_stage' object, which determines the effect
     of the corresponding horizontal Wavelet decomposition stage on ROI
     mask information.
         The `next_branch_row' array holds the index of the next row to
     be requested by each of the two branches (low-pass and high-pass). */

/*****************************************************************************/
/*                              roi_vertical_obj                             */
/*****************************************************************************/

typedef
  struct roi_vertical_obj {
    roi_stage_obj base;
    int next_branch_row[2];
    std_byte **bufs;
  } roi_vertical_obj, *roi_vertical_ref;
  /* This structure defines a vertical ROI mask generation stage object,
     derived from the basic `roi_stage' object, which determines the effect
     of the corresponding vertical Wavelet decomposition stage on ROI
     mask information.
         The `next_branch_row' array holds the index of the next row to
     be requested by each of the two branches (low-pass and high-pass).
         The `bufs' array is a working buffer which should be large enough
     to span the support of the low- and high-pass synthesis regions of
     support.  It is used to retrieve a swath of input rows from the
     `roi_buffer__access_rows' function. */

/*****************************************************************************/
/*                                roi_band_obj                               */
/*****************************************************************************/

typedef
  struct roi_band_obj {
    roi_stage_obj base;
  } roi_band_obj, *roi_band_ref;
  /* This structure defines a leaf in the ROI mask generation tree,
     corresponding to a single subband.  ROI mask information requests
     are ultimately generated at these leaves and propagated up the tree
     until the relevant information can be determined. */

/*****************************************************************************/
/*                               roi_level_info                              */
/*****************************************************************************/

typedef
  struct roi_level_info {

    /* SAIC General Decomp. Begin */
    int max_hp_descent;
    /* SAIC General Decomp. End */

    int min_band, max_band;
    roi_band_ref *bands;
    int roi_generation_needed;
    int block_aligned;
  } roi_level_info, *roi_level_info_ptr;
  /* This structure manages a single resolution level in the decomposition
     of a particular image component.  Its main purpose is to identify the
     relevant leaves of the ROI decomposition tree for subbands in this
     resolution level.  It provides the necessary framework for efficiently
     serving requests to the master ROI object's `check_roi' interface
     function.
         The `max_hp_descent' field is not really used, but is provided as
     a matter of completeness.
         The `min_band' and `max_band' fields identify the range of
     subband indices which may be supplied in calls to the `check_roi'
     interface function for this resolution level.
         The `bands' array contains `max_band'+1 entries of which the
     first `min_band' entries are unused.  Each of the remaining entries
     points to an `roi_band' object, which is a leaf in the ROI mask
     generation tree.  Subbands in levels which are unused will have NULL
     entries in this array.
         The `roi_generation_needed' flag is used only during decompression
     to signal whether or not the relevant resolution level has been
     discarded so that no ROI mask generation is required.  This
     information is important since the ROI objects have no way of knowing
     whether or not they should buffer this ROI information until it is
     requested, unless they are informed that it never will be requested.
         The `block_aligned' flag is true if the ROI is expected to be
     homogeneous over each code-block. */

/*****************************************************************************/
/*                                   roi_tile                                */
/*****************************************************************************/

typedef
  struct roi_tile {
    int tnum;
    canvas_dims dims; /* Dimensions of the tile. */
    roi_region_ptr regions;
    int implicit_partition;
    int max_boost;
    int is_rectangular;
    int tile_specific_params; /* Used only during compression. */
  } roi_tile, *roi_tile_ptr;
  /* Maintains tile-specific information for each component.
         The `regions' field points to the head of a list of ROI regions,
     identifying their geometry and associated boost values.  The list
     is unique for each component and for each tile.  A copy of this pointer
     is maintained inside the `root' object in the containing
     `roi_component_info' structure when this tile becomes the current tile,
     so that destruction of the root object at the end of the tile will
     also deallocate this list.
         The `implicit_partition' flag indicates whether or not the
     region geometry is to be derived implicitly by the decompressor using
     the `max_shift' method.
         The `max_boost' field holds the maximum boost value over all
     regions which intersect with the current tile in the relevant component.
         The `is_rectangular' field indicates whether or not all of the
     ROI regions for the current tile in the current component have
     rectangular geometries.  If so, the ROI mask computation can be and is
     substantially accelerated by exploiting the fact that rectangular
     regions in the image domain remain recangular in the subband domain,
     since only separable Wavelet transforms are employed.  This property
     is not shared by other geometries.
         The `tile_specific_params' flag indicates whether or not the
     region geometries and boost values and the `implicit_partition' value
     for this tile differ from global defaults; if not, no tile-specific
     marker need be written (this is of interest only during compression). */

/*****************************************************************************/
/*                              roi_component_info                           */
/*****************************************************************************/

typedef
  struct roi_component_info {
    int num_levels;
    roi_stage_ref root;
    int max_boost;
    int implicit_partition;
    int is_rectangular;  /* ROIrect */
    int mask_buf_size;   /* ROIrect */
    std_byte *mask_buf;  /* ROIrect */
    roi_level_info_ptr levels;
    canvas_dims image_dims; /* Required only for compression. */
    int num_tiles;
    int current_tile_idx;
    roi_tile_ptr tiles;
  } roi_component_info, *roi_component_info_ptr;
  /* This structure manages the stage of an entire image component.
         The `num_levels' field identifies the number of resolution levels
     in the Wavelet decomposition associated with this component.
         The `root' field points to the root of the ROI mask generation
     tree, which is usually an `roi_vertical_obj' object, but may be an
     `roi_band_obj' object.
         The `max_boost', `implicit_partition' and `is_rectangular' fields
     contain copies of their namesakes in the `roi_tile' structure
     representing the current tile.
         The `mask_buf_size' argument identifies the maximum number of
     entries which can be stored in the block of memory referenced by
     `mask_buf'.
         The `mask_buf' field holds NULL until the first attempt is made
     to obtain ROI information for a block of samples when the
     `is_rectangular' flag is true.  At that point a block of memory is
     allocated to store the ROI boost mask.  The buffer is dynamically
     augmented whenever a new request arrives for ROI information over a
     block which is larger than can be accommodated by the existing buffer.
         The `levels' array points to an array with 1+`num_levels' entries,
     which enables efficient access to the relevant leaf of the ROI mask
     generation tree to serve calls to the `check_roi' interface function.
         The `image_dims' structure holds the dimensions and location of the
     entire image.
         The `num_tiles' field indicates the total number of tiles representing
     the image.
         The `current_tile_idx' field holds the zero-based index of the
     current tile.
         The `tiles' field points to an array of `num_tiles' structures
     used to maintain tile-specific information.  When we advance to a new
     tile, the `current_tile_idx' field is updated and the relevant tile
     structure is used to build a new `root' object and update the
     `is_rectangular' and `max_boost' fields. */

/* ========================================================================= */
/* --------------------- External Function Declarations -------------------- */
/* ========================================================================= */

roi_stage_ref
  ref_roi_create_band_stage(void);
  /* Creates an `roi_band' object, returning a pointer to the base
     `roi_stage' object from which it is derived. */

roi_stage_ref
  ref_roi_create_horizontal_stage(void);
  /* Creates an `roi_horizontal' object, returning a pointer to the base
     `roi_stage' object from which it is derived. */

roi_stage_ref
  ref_roi_create_vertical_stage(void);
  /* Creates an `roi_vertical' object, returning a pointer to the base
     `roi_stage' object from which it is derived. */

void
  ref_roi_get_band_mask(roi_band_ref band, int block_rows, int block_cols,
                        int top_row, int left_col, std_byte *mask[],
                        roi_component_info_ptr comp_info); /* ROIrect */
  /* This is the main function for accessing information from an ROI
     mask generation tree.  The `band' argument references one of the
     leaves of the tree, while the next four arguments identify a block
     of samples from within the relevant subband, for which an ROI
     boost mask is being requested.  The mask itself is returned via
     the `mask' argument.  Specifically, this must be an array with
     `block_rows' entries; the function fills in each entry with a pointer
     to the relevant portion of an internal buffered line of boost
     masks.  The `comp_info' argument points to the `roi_component_info'
     structure to which this band ultimately belongs. */

void
  ref_roi_terminate_component(roi_component_info_ptr comp);
  /* Destroys all internal structures referenced from `comp', except for
     `tiles' list and the component structure itself.  The function is
     useful both while terminating the ROI object and also in preparing to
     build a new structure in a new tile. */

#endif /* REF_ROI_COMMON_H */