src/lib/openjp2/sparse_array.h

   1 /*
   2  * The copyright in this software is being made available under the 2-clauses
   3  * BSD License, included below. This software may be subject to other third
   4  * party and contributor rights, including patent rights, and no such rights
   5  * are granted under this license.
   6  *
   7  * Copyright (c) 2017, IntoPix SA <contact@intopix.com>
   8  * All rights reserved.
   9  *
  10  * Redistribution and use in source and binary forms, with or without
  11  * modification, are permitted provided that the following conditions
  12  * are met:
  13  * 1. Redistributions of source code must retain the above copyright
  14  *    notice, this list of conditions and the following disclaimer.
  15  * 2. Redistributions in binary form must reproduce the above copyright
  16  *    notice, this list of conditions and the following disclaimer in the
  17  *    documentation and/or other materials provided with the distribution.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS `AS IS'
  20  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  21  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  22  * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  23  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  24  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  25  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  26  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  27  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  29  * POSSIBILITY OF SUCH DAMAGE.
  30  */
  31
  32 #include "opj_includes.h"
  33
  34 #ifndef OPJ_SPARSE_ARRAY_H
  35 #define OPJ_SPARSE_ARRAY_H
  36 /**
  37 @file sparse_array.h
  38 @brief Sparse array management
  39
  40 The functions in this file manage sparse arrays. Sparse arrays are arrays with
  41 potential big dimensions, but with very few samples actually set. Such sparse
  42 arrays require allocating a low amount of memory, by just allocating memory
  43 for blocks of the array that are set. The minimum memory allocation unit is a
  44 a block. There is a trade-off to pick up an appropriate dimension for blocks.
  45 If it is too big, and pixels set are far from each other, too much memory will
  46 be used. If blocks are too small, the book-keeping costs of blocks will raise.
  47 */
  48
  49 /** @defgroup SPARSE_ARRAY SPARSE ARRAYS - Sparse arrays */
  50 /*@{*/
  51
  52 /** Opaque type for sparse arrays that contain int32 values */
  53 typedef struct opj_sparse_array_int32 opj_sparse_array_int32_t;
  54
  55 /** Creates a new sparse array.
  56  * @param width total width of the array.
  57  * @param height total height of the array
  58  * @param block_width width of a block.
  59  * @param block_height height of a block.
  60  * @return a new sparse array instance, or NULL in case of failure.
  61  */
  62 opj_sparse_array_int32_t* opj_sparse_array_int32_create(OPJ_UINT32 width,
  63         OPJ_UINT32 height,
  64         OPJ_UINT32 block_width,
  65         OPJ_UINT32 block_height);
  66
  67 /** Frees a sparse array.
  68  * @param sa sparse array instance.
  69  */
  70 void opj_sparse_array_int32_free(opj_sparse_array_int32_t* sa);
  71
  72 /** Returns whether region bounds are valid (non empty and within array bounds)
  73  * @param sa sparse array instance.
  74  * @param x0 left x coordinate of the region.
  75  * @param y0 top x coordinate of the region.
  76  * @param x1 right x coordinate (not included) of the region. Must be greater than x0.
  77  * @param y1 bottom y coordinate (not included) of the region. Must be greater than y0.
  78  * @return OPJ_TRUE or OPJ_FALSE.
  79  */
  80 OPJ_BOOL opj_sparse_array_is_region_valid(opj_sparse_array_int32_t* sa,
  81         OPJ_UINT32 x0,
  82         OPJ_UINT32 y0,
  83         OPJ_UINT32 x1,
  84         OPJ_UINT32 y1);
  85
  86 /** Read the content of a rectangular region of the sparse array into a
  87  * user buffer.
  88  *
  89  * Regions not written with opj_sparse_array_int32_write() are read as 0.
  90  *
  91  * @param sa sparse array instance.
  92  * @param x0 left x coordinate of the region to read in the sparse array.
  93  * @param y0 top x coordinate of the region to read in the sparse array.
  94  * @param x1 right x coordinate (not included) of the region to read in the sparse array. Must be greater than x0.
  95  * @param y1 bottom y coordinate (not included) of the region to read in the sparse array. Must be greater than y0.
  96  * @param dest user buffer to fill. Must be at least sizeof(int32) * ( (y1 - y0 - 1) * dest_line_stride + (x1 - x0 - 1) * dest_col_stride + 1) bytes large.
  97  * @param dest_col_stride spacing (in elements, not in bytes) in x dimension between consecutive elements of the user buffer.
  98  * @param dest_line_stride spacing (in elements, not in bytes) in y dimension between consecutive elements of the user buffer.
  99  * @param forgiving if set to TRUE and the region is invalid, OPJ_TRUE will still be returned.
 100  * @return OPJ_TRUE in case of success.
 101  */
 102 OPJ_BOOL opj_sparse_array_int32_read(opj_sparse_array_int32_t* sa,
 103                                      OPJ_UINT32 x0,
 104                                      OPJ_UINT32 y0,
 105                                      OPJ_UINT32 x1,
 106                                      OPJ_UINT32 y1,
 107                                      OPJ_INT32* dest,
 108                                      OPJ_UINT32 dest_col_stride,
 109                                      OPJ_UINT32 dest_line_stride,
 110                                      OPJ_BOOL forgiving);
 111
 112
 113 /** Write the content of a rectangular region into the sparse array from a
 114  * user buffer.
 115  *
 116  * Blocks intersecting the region are allocated, if not already done.
 117  *
 118  * @param sa sparse array instance.
 119  * @param x0 left x coordinate of the region to write into the sparse array.
 120  * @param y0 top x coordinate of the region to write into the sparse array.
 121  * @param x1 right x coordinate (not included) of the region to write into the sparse array. Must be greater than x0.
 122  * @param y1 bottom y coordinate (not included) of the region to write into the sparse array. Must be greater than y0.
 123  * @param src user buffer to fill. Must be at least sizeof(int32) * ( (y1 - y0 - 1) * src_line_stride + (x1 - x0 - 1) * src_col_stride + 1) bytes large.
 124  * @param src_col_stride spacing (in elements, not in bytes) in x dimension between consecutive elements of the user buffer.
 125  * @param src_line_stride spacing (in elements, not in bytes) in y dimension between consecutive elements of the user buffer.
 126  * @param forgiving if set to TRUE and the region is invalid, OPJ_TRUE will still be returned.
 127  * @return OPJ_TRUE in case of success.
 128  */
 129 OPJ_BOOL opj_sparse_array_int32_write(opj_sparse_array_int32_t* sa,
 130                                       OPJ_UINT32 x0,
 131                                       OPJ_UINT32 y0,
 132                                       OPJ_UINT32 x1,
 133                                       OPJ_UINT32 y1,
 134                                       const OPJ_INT32* src,
 135                                       OPJ_UINT32 src_col_stride,
 136                                       OPJ_UINT32 src_line_stride,
 137                                       OPJ_BOOL forgiving);
 138
 139 /*@}*/
 140
 141 #endif /* OPJ_SPARSE_ARRAY_H */