ref_roi_common.h

JPEG2000实现的源码

/*****************************************************************************/
/* Copyright 1998, Hewlett-Packard Company                                   */
/* All rights reserved                                                       */
/* File: "ref_roi_common.h"                                                  */
/* Description: Common definitions for "ref_forward_roi_local.h",            */
/*              "ref_reverse_roi_local.h" and "ref_roi_common.c".            */
/* Author: David Taubman                                                     */
/* Affiliation: Hewlett-Packard and                                          */
/*              The University of New South Wales, Australia                 */
/* Acknowledgements: Partly developed in collaboration with Mathias Larsson  */
/*                   and his colleagues at Ericsson, Sweden                  */
/* Version: VM8.0                                                            */
/* Last Revised: 20 July, 2000                                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to support arbitrary reference points for the   */
/* transform and the various regular partitions, so as to facilitate         */
/* cropping and geometric transformations in the compressed domain and to    */
/* enable full support for CRF's single-sample overlap Wavelet transform,    */
/* as originally documented in Seoul.  Changes are too numerous to flag      */
/* individually within the code.  Changes copyrighted by HP with all rights  */
/* reserved for the modified parts.                                          */
/*****************************************************************************/

/*****************************************************************************/
/* Modified by David Taubman to support interface modifications, arbitrary   */
/* changes in coding parameters from component to component and from tile    */
/* to tile, to support the full generality of PART-1 of the JPEG2000         */
/* standard, and to support most anticipated generality of PART-2.  Changes  */
/* are too numerous to flag individually within the code, which in some      */
/* places has been completely rewritten.  All changes copyrighted by HP with */
/* all rights reserved for the modified parts.                               */
/*****************************************************************************/

/*****************************************************************************/
/* Modified for general wavelet decompositions.                              */
/* Copyright 2000 Science Applications International Corporation (SAIC).     */
/* Copyright 1995 University of Arizona, Arizona Board of Regents.           */
/* All Rights Reserved for modified parts.                                   */
/*****************************************************************************/

#ifndef REF_ROI_COMMON_H
#define REF_ROI_COMMON_H

#define ROI_MEM_KEY   "ROI OBJECT MEMORY"

/* ========================================================================= */
/* -------------------------- Forward Declarations ------------------------- */
/* ========================================================================= */

typedef struct roi_stage_obj *roi_stage_ref;


/* ========================================================================= */
/* -------------------- Structure and Object Declarations ------------------ */
/* ========================================================================= */

/*****************************************************************************/
/*                                roi_rectangle                              */
/*****************************************************************************/

typedef
  struct roi_rectangle {
    int top, left, right, bottom;
  } roi_rectangle, *roi_rectangle_ptr;
  /* Describes a rectangle.  Coordinates are expressed relative to the
     origin of the canvas, which contains the image but might be larger
     than the image.  For a detailed description of the canvas concept,
     see the special topic, "Blocks, Tiles and Frames" in "ifc.h".
         `top' and `left' identify the top left-hand corner inside
     the rectangle.
         `bottom' and `right' identify the bottom right-hand corner inside
     the rectangle. */

/*****************************************************************************/
/*                                 roi_circle                                */
/*****************************************************************************/

typedef
  struct roi_circle {
    int centre_row, centre_col;
    int radius;
    double radius_squared;
  } roi_circle, *roi_circle_ptr;
  /* Describes a circle, centred at the identified row and column indices,
     with the indicated radius.  The circle contains all points (r,c), such
     that (r-`centre_row')^2 + (c-`centre_col')^2 < (`radius'+0.5)^2.  To
     increase the efficiency of this computation, the value,
     (`radius'+0.5)^2 is precomputed and stored in the `radius_squared'
     field.  Coordinates are expressed relative to the absolute origin of
     the canvas.  For a detailed discussion of the canvas concept, see
     the special topic, "Blocks, Tiles and Frames" in "ifc.h". */

/*****************************************************************************/
/*                                 roi_region                                */
/*****************************************************************************/

typedef
  struct roi_region {
    int boost;
    int is_rectangular;
    roi_rectangle rect;
    roi_circle circle;
    struct roi_region *next;
  } roi_region, *roi_region_ptr;
  /* This structure defines a region of interest, as seen within a
     particular image component.  The dimensions represented here span
     the entire image, not just one particular tile.
         The `boost' argument corresponds to the integer shift which should be
     introduced (at least conceptually) to the magnitudes of samples which
     lie within the region of interest.
         The `is_rectangular' fiel indicates which of the `rect' or `circle'
     structures ontains the region.
         The region itself is understood as the intersection of the
     rectangular region defined by `rect' and the circular region defined
     by `circ'.
         The `next' field may be used to construct a linked list of regions
     for the same subband, each of which may potentially have different
     boost values. */

/*****************************************************************************/
/*                              roi_buffered_row                             */
/*****************************************************************************/

typedef
  struct roi_buffered_row {
    int usage_count;
    std_byte *buf;
  } roi_buffered_row, *roi_buffered_row_ptr;
  /* This structure manages a single buffered row of ROI mask values.  It
     is used by the `roi_buffer' structure to manage moving windows of
     mask rows which are allocated and recycled on demand.
         `usage_count' is a counter which is initialized to the `usage_count'
     value in the containing `roi_buffer' structure and is decremented by
     a specified amount each time the buffer is accessed.  Once the count
     reaches zero the buffer is released.  The count may be used in
     different ways.  It may represent the number of branches for a
     vertical or horizontal mask generation stage, since mask information for
     a row will be requested only once by any given object in the mask
     generation tree.  In the `roi_band_obj' objects, it is used to represent
     the width of the current tile and is decremented by the width of the
     region for which ROI information is being requested in any call to
     the `check_roi' interface function.  This works because ROI information
     must be accessed exactly once for any given subband sample. */

/*****************************************************************************/
/*                                 roi_buffer                                */
/*****************************************************************************/

typedef
  struct roi_buffer {
    int usage_count;
    int first_row, num_rows;
    int max_buffered_rows;
    roi_buffered_row_ptr rows;
    canvas_dims tile_dims;
  } roi_buffer, *roi_buffer_ptr;
  /* This structure manages a moving window of dynamically allocated mask
     row buffers.  The size of the window grows to accommodate the pattern
     of requests for ROI information.  All ROI stage objects maintain a buffer
     of this form, although the way in which they use it may vary depending
     upon whether or not the object is an "roi_band_obj" or not.
         The `usage_count' field holds the initializer for each row buffer's
     `usage_count' field, as explained in the comments appearing above with
     the definition of `roi_buffered_row'.
         The `first_row' field holds the index of the first row managed by
     the buffer, while `num_rows' holds the number of rows managed by the
     buffer, all relative to the start of the current tile.
         The `max_buffered_rows' field holds the maximum number of rows which
     can be buffered in the `rows' array.
         The `rows' array points to the `roi_buffered_row' structures which
     maintain the state of each row in the moving window.
         The `tile_dims' field maintains the location and size of the
     current tile, relative to the absolute canvas coordinate system. */

/*****************************************************************************/
/*                                roi_stage_obj                              */
/*****************************************************************************/

typedef void (*roi_stage__initialize__func)
  (roi_stage_ref self, canvas_dims_ptr tile_dims);
    /* Initializes the `roi_stage' object.  This function must recursively
       invoke the `initialize' interface functions of all descendants via
       the links in the `branches' array. */

typedef void (*roi_stage__get_mask_line__func)
  (roi_stage_ref self, roi_stage_ref requester, std_byte *mask, int width);
    /* This is the main useful function of every `roi_stage' object, with
       the exception of the derived `roi_band' object, which never uses
       this function, but constructs blocks of mask information instead.
       The `requester' argument identifies the `roi_stage' object which
       is making the request.  The `mask' array will be filled out with the
       relevant boosts for each pixel, upon return.  The `width' argument
       is provided for consistency tests only.  It holds the width of the
       `mask' array, which should be the width of the current tile. */

/* Begin ROIrect */
typedef roi_region_ptr (*roi_stage__get_mask_rects__func)
  (roi_stage_ref self, roi_stage_ref requester);
    /* This function is used in place of `roi_stage__get_mask_line' if the
       `is_rectangular' flag in the relevant `roi_component_info' structure
       is set.  Instead of incrementally computing a new line of ROI mask
       information, the function creates and returns a list of ROI regions,
       all with rectangular geometries, which describes the geometry of the
       regions in the stage of the Wavelet decomposition associated with the
       `requester'.  The requester keeps this list once it has been generated
       and uses the list exclusively to satisfy requests for ROI information;
       it need not request a regenerated list each time a request for more
       ROI information arrives. */
/* End ROIrect */

typedef void (*roi_stage__terminate__func)
  (roi_stage_ref self);
    /* Deallocates all resources managed by the `roi_stage' object, including
       that associated with the `roi_stage_obj' structure itself.  The
       function must recursively invoke the `terminate' interface functions of
       all descendants via the links in the `branches' array. */

typedef
  struct roi_stage_obj {
    roi_stage__initialize__func initialize;
    roi_stage__get_mask_line__func get_mask_line;
    roi_stage__get_mask_rects__func get_mask_rects; /* ROIrect */
    roi_stage__terminate__func terminate;
    int direction;
    roi_stage_ref branches[2];
    int branch_neg_supports[2];
    int branch_pos_supports[2];
    roi_stage_ref parent;
    roi_region_ptr regions;
    roi_buffer buffer;

    /* SAIC General Decomp. Begin */
    int vert_limit;
    int horiz_limit;
    /* SAIC General Decomp. End */

  } roi_stage_obj;
  /* This object is used as the base of three derived objects, namely
     `roi_horizontal_ob', `roi_vertical_obj' and `roi_band_obj'.  Together
     these form the mechanism whereby ROI mask information may be generated
     efficiently on demand for any number of arbitrarily shaped ROI regions,
     in response to calls to the ROI object's `check_roi' interface
     function.  The objects are arranged in a hierarchy which models the
     Wavelet transform structure.  At the top of this hierarchy is a single
     stage (usually a vertical decomposition stage, but may be a leaf
     `roi_band_obj' strage), which forms the root of the initialization,
     termination and `start_tile' recursive calls.  The ROI information,
     however, is requested directly from the leaves of the tree, which are
     invariably `roi_band_obj' objects.  Calls propagate up the tree until
     the necessary information is complete.
         The `direction' field holds one of INFO__HORIZONTAL or INFO__VERTICAL,
     unless this is an `roi_band_obj' object, in which case it holds 0.
         The `branches' array holds two pointers, which reference the low-pass
     branch and high-pass branch respectively.  Calls to the object's
     `pull_mask_line' interface function must pass one of these two references
     as the `requester' argument.  Both entries of the `branches' array
     will be NULL if this is an `roi_band_obj' object.
         The `branch_neg_supports' and `branch_pos_supports' arrays hold
     the negative and positive support extents of the synthesis kernels
     for each of the two branches (low-pass for branch 0, high-pass for
     branch 1).