hplx_vert_lifting.h

JPEG2000实现的源码

     be requested in order to generate a new output row from the lifting
     step.  The lifting kernel is applied to these source rows and the
     result is used to modify the target row.
         `target' points to the buffering stage from which the target row
     should be requested, which is to be updated by the lifting step in
     order to generate an output row.  */

/*****************************************************************************/
/*                             hplx_buffering_stage                          */
/*****************************************************************************/

typedef
  struct hplx_buffering_stage {
    int cols, rows;
    int odd_lines;
    int first_extension, last_extension; /* Christos Chrysafis (HPL)*/
    int special_first, special_last, skip_last;
    int missing_first_row;
    int min_row_idx, next_row_idx;
    int max_buffered_rows;
    int num_users;
    hplx_row_buffer_state_ptr *row_buffers;
    hplx_lifting_step_ptr generator;
    hplx_row_buffer_heap_ptr heap;
  } hplx_buffering_stage; /* Pointer type declared forward. */
  /* This structure is key to understanding how we implement vertical
     lifting in a memory efficient manner.  There is a single buffering
     stage for every lifting step, plus two additional buffering stages.
     These manage windows into the initial, final and intermediate even and
     odd line sub-sequences.  For a description of the way in which these
     buffering stages are used, consult the comments appearing with the
     definition of `hplx_vert_analysis_by_lifting' and
     `hplx_vert_synthesis_by_lifting'.
         `cols' and `rows' identify the width and height of the
     relevant line sub-sequence (either even lines or odd lines) within
     the current tile.
         `odd_lines' indicates whether the buffering stage manages odd
     or even indexed lines.  Note that the line indices are relative to
     the absolute canvas coordinate system, not the start of the image,
     tile or frame.  Thus, a particular tile or frame may start with
     either an odd or even line.
         `first_extension' and `last_extension' identify the type of
     extension to be applied to the first and last rows of the current
     frame.  For odd length filters, the only valid extensions are currently
     odd/whole point extension (value of 0) and even (half point) extension
     (value of 1).  In the former case the boundary sample is not repeated,
     while in the latter case the boundary sample is repeated.  The extension
     type depends upon the dimensions and the absolute index of the first and
     last rows in the frame.
         `special_first' and `special_last' are zero except for buffering
     stages which manage even indexed rows in the 1-sample overlap mode.
     In this case, `special_first' will be equal to 1 for all but the first
     vertical frame, while `special_last' will be equal to 1 for all but the
     last vertical frame.  These "special" rows overlap between consecutive
     frames so that the transform must be careful to only output them to
     the coder once.  There is a special mode in which the tile boundaries
     also use SSO-DWT style extensions in which case the `special_first'
     and `special_last' flags will be set for the boundary frames as well
     so long as the relevant boundaries have even coordinates.  To distinguish
     these two different usages, the `skip_last' flag is provided which is
     identical to `special_last' except on the last frame when it holds
     0.  When `skip_last' is true, the last row of the frame should never be
     output; it will be output when the next frame is processed.  Even if
     the `skip_last' row is the last row of the tile, there is guaranteed
     to be another vertical frame which will process just this row.
     Note that the "special" rows should have the relevant DC gain applied
     instead of the lifting steps.
         `missing_first_row' is equal to 0 except for the even row sub-sequence
     when the first row in the sequence follows the first row in the odd
     sub-sequence.  This can only occur when the relevant frame or tile
     commences with an odd indexed row relative to the canvas coordinate
     system.  In this case we think of the first even indexed row as missing.
         `min_row_idx' holds the zero-based index of the first row which is
     available in the buffer.  This index is expressed relative to the
     start of the frame in the relevant row subsequence (even or odd as
     appropriate); it does not have absolute significance on the canvas
     coordinate system.
         `next_row_idx' holds the zero-based index of the first row which has
     not yet been added into the buffer.  Again, this is expressed relative
     to the first row of the frame in the relevant row subsequence; it does
     not have absolute significance on the canvas coordinate system.
         `max_buffered_rows' holds the size of the `row_buffers' array so that
     this array may be reallocated as necessary.
         `num_users' holds the number of users which will be accessing
     buffers from this structure.  This is the value which is used to
     initialize new entries added to the `row_buffers' array.
         `row_buffers' stores pointers to the row buffers in the range
     `min_row_idx' through `next_row_idx'-1.
         `generator' points to the lifting step which must be used to
     generate new rows, if they do not already reside on the buffer.  If this
     field holds NULL, then requests for buffered rows may be satisfied only
     if the rows already exist on the buffer or if an alternative
     mechanism is provided; during synthesis, the structure is extended
     to include the information required to recover rows from the
     dequantizer or other levels in the hierarchical transform, as
     appropriate.  Exactly two of the buffering stages will always have
     NULL generators.
         `heap' points to the common heap structure maintained within the
     `hplx_vert_analysis_by_lifting' and `hplx_vert_synthesis_by_lifting'
     objects. */

/* ========================================================================= */
/* -------------------- Exported Function Definitions ---------------------- */
/* ========================================================================= */

extern hplx_row_buffer_state_ptr
  hplx_lift_heap__get_buffer(hplx_row_buffer_heap_ptr heap);
   /* Allocate a new buffer from the heap. */

extern void
  hplx_lift_heap__return_buffer(hplx_row_buffer_heap_ptr heap,
                                hplx_row_buffer_state_ptr buf);
   /* Recycle a buffer to the heap. */

extern hplx_row_buffer_state_ptr
  hplx_lift_heap__get_tmp_buffer(hplx_row_buffer_heap_ptr heap);
   /* Same as `get_buffer', followed immediately by `return_buffer', i.e.
      returns a pointer to a buffer, which does not belong to anyone else, but
      leaves the buffer on the heap.  This is handy when a temporary buffer
      is required, which might already reside on the heap, and we can be
      quite sure that no other calls to `get_buffer' will occur before we
      are finished with the temporary resource. */

extern hplx_row_buffer_state_ptr
  hplx_lift_stage__add_row(hplx_buffering_stage_ptr stage);
   /* Adds a new row to the buffering stage, retrieving it from the heap,
      and returns a pointer to that row's buffer-state structure. */

extern void
  hplx_lift_stage__release_row(hplx_buffering_stage_ptr stage, int row_idx);

   /* Decrements the users count of the buffered row with the indicated index,
      recycling it to the heap if the count reaches 0. */

#endif /* HPLX_VERT_LIFTING_H */