sparse_array.h File Reference

Sparse array management. More...

`#include "opj_includes.h"`

Go to the source code of this file.

## Typedefs

typedef struct opj_sparse_array_int32 | opj_sparse_array_int32_t
| Opaque type for sparse arrays that contain int32 values.

## Functions

opj_sparse_array_int32_t * | opj_sparse_array_int32_create (OPJ_UINT32 width, OPJ_UINT32 height, OPJ_UINT32 block_width, OPJ_UINT32 block_height)
| Creates a new sparse array.
void | opj_sparse_array_int32_free (opj_sparse_array_int32_t *sa)
| Frees a sparse array.
OPJ_BOOL | opj_sparse_array_is_region_valid (const opj_sparse_array_int32_t *sa, OPJ_UINT32 x0, OPJ_UINT32 y0, OPJ_UINT32 x1, OPJ_UINT32 y1)
| Returns whether region bounds are valid (non empty and within array bounds)
OPJ_BOOL | opj_sparse_array_int32_read (const opj_sparse_array_int32_t *sa, OPJ_UINT32 x0, OPJ_UINT32 y0, OPJ_UINT32 x1, OPJ_UINT32 y1, OPJ_INT32 *dest, OPJ_UINT32 dest_col_stride, OPJ_UINT32 dest_line_stride, OPJ_BOOL forgiving)
| Read the content of a rectangular region of the sparse array into a user buffer.
OPJ_BOOL | opj_sparse_array_int32_write (opj_sparse_array_int32_t *sa, OPJ_UINT32 x0, OPJ_UINT32 y0, OPJ_UINT32 x1, OPJ_UINT32 y1, const OPJ_INT32 *src, OPJ_UINT32 src_col_stride, OPJ_UINT32 src_line_stride, OPJ_BOOL forgiving)
| Write the content of a rectangular region into the sparse array from a user buffer.

## Detailed Description

Sparse array management.

The functions in this file manage sparse arrays. Sparse arrays are arrays with potential big dimensions, but with very few samples actually set. Such sparse arrays require allocating a low amount of memory, by just allocating memory for blocks of the array that are set. The minimum memory allocation unit is a a block. There is a trade-off to pick up an appropriate dimension for blocks. If it is too big, and pixels set are far from each other, too much memory will be used. If blocks are too small, the book-keeping costs of blocks will raise.

## Typedef Documentation

## opj_sparse_array_int32_t

typedef struct opj_sparse_array_int32 opj_sparse_array_int32_t

Opaque type for sparse arrays that contain int32 values.

## Function Documentation

## opj_sparse_array_int32_create()

opj_sparse_array_int32_t * opj_sparse_array_int32_create | ( | OPJ_UINT32 | width,
|  | OPJ_UINT32 | height,
|  | OPJ_UINT32 | block_width,
|  | OPJ_UINT32 | block_height
| ) |  |

Creates a new sparse array.

Parameters

  width | total width of the array.
  height | total height of the array
  block_width | width of a block.
  block_height | height of a block.

Returns
  a new sparse array instance, or NULL in case of failure.

References opj_sparse_array_int32::block_count_hor, opj_sparse_array_int32::block_count_ver, opj_sparse_array_int32::block_height, opj_sparse_array_int32::block_width, opj_sparse_array_int32::data_blocks, opj_sparse_array_int32::height, opj_calloc(), opj_free(), opj_uint_ceildiv(), and opj_sparse_array_int32::width.

Referenced by main(), and opj_dwt_init_sparse_array().

## opj_sparse_array_int32_free()

void opj_sparse_array_int32_free | ( | opj_sparse_array_int32_t * | sa | ) |

Frees a sparse array.

Parameters

  sa | sparse array instance.

References opj_sparse_array_int32::block_count_hor, opj_sparse_array_int32::block_count_ver, opj_sparse_array_int32::data_blocks, and opj_free().

Referenced by main(), opj_dwt_decode_partial_97(), opj_dwt_decode_partial_tile(), and opj_dwt_init_sparse_array().

## opj_sparse_array_int32_read()

OPJ_BOOL opj_sparse_array_int32_read | ( | const opj_sparse_array_int32_t * | sa,
|  | OPJ_UINT32 | x0,
|  | OPJ_UINT32 | y0,
|  | OPJ_UINT32 | x1,
|  | OPJ_UINT32 | y1,
|  | OPJ_INT32 * | dest,
|  | OPJ_UINT32 | dest_col_stride,
|  | OPJ_UINT32 | dest_line_stride,
|  | OPJ_BOOL | forgiving
| ) |  |

Read the content of a rectangular region of the sparse array into a user buffer.

Regions not written with opj_sparse_array_int32_write() are read as 0.

Parameters

  sa | sparse array instance.
  x0 | left x coordinate of the region to read in the sparse array.
  y0 | top x coordinate of the region to read in the sparse array.
  x1 | right x coordinate (not included) of the region to read in the sparse array. Must be greater than x0.
  y1 | bottom y coordinate (not included) of the region to read in the sparse array. Must be greater than y0.
  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.
  dest_col_stride | spacing (in elements, not in bytes) in x dimension between consecutive elements of the user buffer.
  dest_line_stride | spacing (in elements, not in bytes) in y dimension between consecutive elements of the user buffer.
  forgiving | if set to TRUE and the region is invalid, OPJ_TRUE will still be returned.

Returns
  OPJ_TRUE in case of success.

References opj_sparse_array_int32_read_or_write(), and OPJ_TRUE.

Referenced by main(), opj_dwt_decode_partial_97(), opj_dwt_decode_partial_tile(), opj_dwt_interleave_partial_h(), opj_dwt_interleave_partial_v(), opj_v8dwt_interleave_partial_h(), and opj_v8dwt_interleave_partial_v().

## opj_sparse_array_int32_write()

OPJ_BOOL opj_sparse_array_int32_write | ( | opj_sparse_array_int32_t * | sa,
|  | OPJ_UINT32 | x0,
|  | OPJ_UINT32 | y0,
|  | OPJ_UINT32 | x1,
|  | OPJ_UINT32 | y1,
|  | const OPJ_INT32 * | src,
|  | OPJ_UINT32 | src_col_stride,
|  | OPJ_UINT32 | src_line_stride,
|  | OPJ_BOOL | forgiving
| ) |  |

Write the content of a rectangular region into the sparse array from a user buffer.

Blocks intersecting the region are allocated, if not already done.

Parameters

  sa | sparse array instance.
  x0 | left x coordinate of the region to write into the sparse array.
  y0 | top x coordinate of the region to write into the sparse array.
  x1 | right x coordinate (not included) of the region to write into the sparse array. Must be greater than x0.
  y1 | bottom y coordinate (not included) of the region to write into the sparse array. Must be greater than y0.
  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.
  src_col_stride | spacing (in elements, not in bytes) in x dimension between consecutive elements of the user buffer.
  src_line_stride | spacing (in elements, not in bytes) in y dimension between consecutive elements of the user buffer.
  forgiving | if set to TRUE and the region is invalid, OPJ_TRUE will still be returned.

Returns
  OPJ_TRUE in case of success.

References OPJ_FALSE, and opj_sparse_array_int32_read_or_write().

Referenced by main(), opj_dwt_decode_partial_97(), opj_dwt_decode_partial_tile(), and opj_dwt_init_sparse_array().

## opj_sparse_array_is_region_valid()

OPJ_BOOL opj_sparse_array_is_region_valid | ( | const opj_sparse_array_int32_t * | sa,
|  | OPJ_UINT32 | x0,
|  | OPJ_UINT32 | y0,
|  | OPJ_UINT32 | x1,
|  | OPJ_UINT32 | y1
| ) |  |

Returns whether region bounds are valid (non empty and within array bounds)

Parameters

  sa | sparse array instance.
  x0 | left x coordinate of the region.
  y0 | top x coordinate of the region.
  x1 | right x coordinate (not included) of the region. Must be greater than x0.
  y1 | bottom y coordinate (not included) of the region. Must be greater than y0.

Returns
  OPJ_TRUE or OPJ_FALSE.

References opj_sparse_array_int32::height, and opj_sparse_array_int32::width.

Referenced by opj_sparse_array_int32_read_or_write().