OpenJPH: ojph::codestream Class Reference

OpenJPH Open-source implementation of JPEG2000 Part-15

Loading...
Searching...
No Matches
ojph::codestream Class Reference

The object represent a codestream. More...

`#include <ojph_codestream.h>`

## Public Member Functions
| codestream ()
| default constructor
| ~codestream ()
| default destructor
void | restart ()
| Restarts the codestream.
void | set_planar (bool planar)
| Sets the sequence of pushing or pull rows from the machinery.
void | set_profile (const char *s)
| Sets the codestream profile.
void | set_tilepart_divisions (bool at_resolutions, bool at_components)
| Sets the locations where a tile is partitioned into tile parts.
bool | is_tilepart_division_at_resolutions ()
| Query if the tile will be partitioned at resolution boundary.
bool | is_tilepart_division_at_components ()
| Query if the tile will be partitioned at component boundary.
void | request_tlm_marker (bool needed)
| Request the addition of the optional TLM marker segment. This request should occur before writing codestream headers ojph::codestream::write_headers()).
bool | is_tlm_requested ()
| Query if the optional TLM marker segment is to be added.
void | write_headers (outfile_base *file, const comment_exchange *comments=NULL, ui32 num_comments=0)
| Writes codestream headers when the codestream is used for writing. This function should be called after setting all the codestream parameters, but before pushing image lines using ojph::codestream::exchange().
line_buf * | exchange (line_buf *line, ui32 &next_component)
| This call is used to send image data rows to the library. We expect to send one row from a single component with each call. The first call is always with line == NULL; the call would return a line_buf, and the component number or index in next_component. The caller would then need to fill the buffer of the line_buf with one row from the component indexed by next_component, and call exchange again to pass the component and get a new line_buf.
void | flush ()
| This is the last call to a writing (encoding) codestream. This will write encoded bitstream data to the file. This call does not close the file, because, in the future, we might wish to write more data to the file. If you do not want to write more data, then call codestream::close().
void | enable_resilience ()
| This enables codestream resilience; that is, the library tries its best to decode the codestream, even if there are errors. This call is for a decoding (or reading) codestream, and should be called before all other calls, before codestream::read_headers().
void | read_headers (infile_base *file)
| This call reads the headers of a codestream. It is for a reading (or decoding) codestream, and should be called after codestream::enable_resilience(), but before codestream::restrict_input_resolution().
void | restrict_input_resolution (ui32 skipped_res_for_data, ui32 skipped_res_for_recon)
| This function restricts resolution decoding for a codestream. It is for a reading (decoding) codestream. We can limit the restrictions to decoding and reconstruction resolution, or decoding only. Call this function after codestream::read_headers() but before codestream::create().
void | create ()
| This call is for a decoding (or reading) codestream. Call this function after calling restrict_input_resolution(), if restrictions are needed.
line_buf * | pull (ui32 &comp_num)
| This call is to pull one row from the codestream, being decoded. The returned line_buf object holds one row from the image; the returned comp_num tells the reader the component to which this row belongs.
void | close ()
| Call this function to close the underlying file; works for both encoding and decoding codestreams.
param_siz | access_siz ()
| Returns the underlying SIZ marker segment object.
param_cod | access_cod ()
| Returns the underlying COD marker segment object.
param_qcd | access_qcd ()
| Returns the underlying QCD marker segment object.
param_nlt | access_nlt ()
| Returns the underlying NLT marker segment object.
bool | is_planar () const
| Query if the codestream extraction is planar or not. See the documentation for ojph::codestream::set_planar().

## Private Attributes
local::codestream * | state

## Detailed Description

The object represent a codestream.

Most end-user use this object to create a j2c codestream. The object currently can be used in one of two modes, reading or writing.

We try to follow the pImpl (pointer to Implementation) approach; therefore, objects in the ojph namespace hold pointers to internal implementations. The actual implementation is usually in the ojph::local namespace. The actual implementation of the ojph::codestream object is in ojph_codestream.cpp, while the actual implementation can be found in ojph_codestream_local.h and ojph_codestream_local.cpp.

Most of these member functions provides nothing more than calls into the internal implementation. See ojph_codestream_local.h for more documentation – yet to be added.

Definition at line 88 of file ojph_codestream.h.

## Constructor & Destructor Documentation

## ◆ codestream()

ojph::codestream::codestream | ( |  | ) |

default constructor

This function instantiate the actual implementation object local::codestream, using new.

Definition at line 66 of file ojph_codestream.cpp.

References state.

## ◆ ~codestream()

ojph::codestream::~codestream | ( |  | ) |

default destructor

This function destroys the internal local::codestream object.

Definition at line 58 of file ojph_codestream.cpp.

References state.

## Member Function Documentation

## ◆ access_cod()

param_cod ojph::codestream::access_cod | ( |  | ) |

Returns the underlying COD marker segment object.

Returns
  param_cod This object holds COD marker segment information, which deals with coding parameters, such as codeblock sizes, progression order, reversible, ... etc.

Definition at line 85 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ access_nlt()

param_nlt ojph::codestream::access_nlt | ( |  | ) |

Returns the underlying NLT marker segment object.

Returns
  param_nlt This object holds NLT marker segment information, which deals with non-linearity point transformation for each component.

Definition at line 97 of file ojph_codestream.cpp.

References state.

Referenced by main().

## ◆ access_qcd()

param_qcd ojph::codestream::access_qcd | ( |  | ) |

Returns the underlying QCD marker segment object.

Returns
  param_qcd This object holds QCD marker segment information, which deals with quantization parameters – quantization step size for each subband.

Definition at line 91 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ access_siz()

param_siz ojph::codestream::access_siz | ( |  | ) |

Returns the underlying SIZ marker segment object.

Returns
  param_siz This object holds SIZ marker segment information, which deals with codestream dimensions, number of components, bit depth, ... etc.

Definition at line 79 of file ojph_codestream.cpp.

References state.

Referenced by get_j2c_bit_depth(), get_j2c_downsampling_x(), get_j2c_downsampling_y(), get_j2c_height(), get_j2c_is_signed(), get_j2c_num_components(), get_j2c_width(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ close()

void ojph::codestream::close | ( |  | ) |

Call this function to close the underlying file; works for both encoding and decoding codestreams.

Definition at line 206 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ create()

void ojph::codestream::create | ( |  | ) |

This call is for a decoding (or reading) codestream. Call this function after calling restrict_input_resolution(), if restrictions are needed.

Definition at line 187 of file ojph_codestream.cpp.

References state.

Referenced by cpp_parse_j2c_data(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ enable_resilience()

void ojph::codestream::enable_resilience | ( |  | ) |

This enables codestream resilience; that is, the library tries its best to decode the codestream, even if there are errors. This call is for a decoding (or reading) codestream, and should be called before all other calls, before codestream::read_headers().

Definition at line 167 of file ojph_codestream.cpp.

References state.

Referenced by enable_resilience(), LLVMFuzzerTestOneInput(), and main().

## ◆ exchange()

line_buf * ojph::codestream::exchange | ( | line_buf * | line,
|  | ui32 & | next_component )

This call is used to send image data rows to the library. We expect to send one row from a single component with each call. The first call is always with line == NULL; the call would return a line_buf, and the component number or index in next_component. The caller would then need to fill the buffer of the line_buf with one row from the component indexed by next_component, and call exchange again to pass the component and get a new line_buf.

Parameters

  line | A line_buf object; first call should supply NULL. Subsequent calls should pass the line_buf object obtained in the previous call.
  next_component | returns a component index; the end user must fill the returned line_buf from the component indexed by this index.

Returns
  line_buf* A line_buf which must be filled with the component indexed by next_component, before calling exchange again to pass this line.

Definition at line 212 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ flush()

void ojph::codestream::flush | ( |  | ) |

This is the last call to a writing (encoding) codestream. This will write encoded bitstream data to the file. This call does not close the file, because, in the future, we might wish to write more data to the file. If you do not want to write more data, then call codestream::close().

Definition at line 200 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ is_planar()

bool ojph::codestream::is_planar | ( |  | ) | const

Query if the codestream extraction is planar or not. See the documentation for ojph::codestream::set_planar().

Returns
  true if it is planar
  false if it is not planar (interleaved)

Definition at line 153 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), and main().

## ◆ is_tilepart_division_at_components()

bool ojph::codestream::is_tilepart_division_at_components | ( |  | ) |

Query if the tile will be partitioned at component boundary.

Returns
  true if component-boundary tile partitioning is employed.
  false if component-boundary tile partitioning is not requested.

Definition at line 134 of file ojph_codestream.cpp.

References ojph::OJPH_TILEPART_COMPONENTS, and state.

## ◆ is_tilepart_division_at_resolutions()

bool ojph::codestream::is_tilepart_division_at_resolutions | ( |  | ) |

Query if the tile will be partitioned at resolution boundary.

Returns
  true if resolution-boundary tile partitioning is employed.
  false if resolution-boundary tile partitioning is not requested.

Definition at line 127 of file ojph_codestream.cpp.

References ojph::OJPH_TILEPART_RESOLUTIONS, and state.

## ◆ is_tlm_requested()

bool ojph::codestream::is_tlm_requested | ( |  | ) |

Query if the optional TLM marker segment is to be added.

Returns
  true if the addition of the optional TLM marker segment is to be added.
  false if the addition of the optional TLM marker segment was not requested.

Definition at line 147 of file ojph_codestream.cpp.

References state.

## ◆ pull()

line_buf * ojph::codestream::pull | ( | ui32 & | comp_num | ) |

This call is to pull one row from the codestream, being decoded. The returned line_buf object holds one row from the image; the returned comp_num tells the reader the component to which this row belongs.

Parameters

  comp_num | returns the component to which the returned line_buf object belongs.

Returns
  line_buf* this object holds one row of the component indexed by comp_num.

Definition at line 193 of file ojph_codestream.cpp.

References state.

Referenced by cpp_pull_j2c_line(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ read_headers()

void ojph::codestream::read_headers | ( | infile_base * | file | ) |

This call reads the headers of a codestream. It is for a reading (or decoding) codestream, and should be called after codestream::enable_resilience(), but before codestream::restrict_input_resolution().

Parameters

  file | The file to read from. The file should be inherited from ojph::infile_base; this enables reading from an actual file or from memory-based file.

Definition at line 173 of file ojph_codestream.cpp.

References state.

Referenced by cpp_init_j2c_data(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ request_tlm_marker()

void ojph::codestream::request_tlm_marker | ( | bool | needed | ) |

Request the addition of the optional TLM marker segment. This request should occur before writing codestream headers ojph::codestream::write_headers()).

Parameters

  needed | true when the marker is needed.

Definition at line 141 of file ojph_codestream.cpp.

References state.

Referenced by main().

## ◆ restart()

void ojph::codestream::restart | ( |  | ) |

Restarts the codestream.

This function restarts the codestream; after this call, the codestream object behaves like it has never been used before, except that all memory allocations are preserved. Thus, after restart(), there is no need to allocate memory, unless the new codestream needs more storage to store codeblocks, or has a different structure.

restart() is useful if we are decoding multiple codestreams that have largely the same structure and byte length.

Definition at line 72 of file ojph_codestream.cpp.

References state.

## ◆ restrict_input_resolution()

void ojph::codestream::restrict_input_resolution | ( | ui32 | skipped_res_for_data,
|  | ui32 | skipped_res_for_recon )

This function restricts resolution decoding for a codestream. It is for a reading (decoding) codestream. We can limit the restrictions to decoding and reconstruction resolution, or decoding only. Call this function after codestream::read_headers() but before codestream::create().

Parameters

  skipped_res_for_data | specifies for how many fine resolutions decoding is skipped, i.e., reading and decoding is not performed for this number of fine resolutions.
  skipped_res_for_recon | specifies for how many fine resolutions reconstruction is skipped; the resulting image is smaller than the original. This number should be smaller or equal to skipped_res_for_data, as it does not make sense otherwise.

Definition at line 179 of file ojph_codestream.cpp.

References state.

Referenced by cpp_restrict_input_resolution(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ set_planar()

void ojph::codestream::set_planar | ( | bool | planar | ) |

Sets the sequence of pushing or pull rows from the machinery.

For this function, planar means that the machinery processes one colour component in full before processing the next component. This more efficient because the cache is used for one component instead of many components, but it is not practical when a color transform is employed. This is because we need to employ the transform to the first three components. Therefore, planar, while recommended, can only be used when there is no color transform.

Parameters

  planar | true for when components are pushed in full one at a time.

Definition at line 103 of file ojph_codestream.cpp.

References state.

Referenced by cpp_parse_j2c_data(), LLVMFuzzerTestOneInput(), main(), and TEST().

## ◆ set_profile()

void ojph::codestream::set_profile | ( | const char * | s | ) |

Sets the codestream profile.

This is currently rather incomplete, but it accepts two profiles IMF and BROADCAST. More work is needed to improve this. Note that Rsiz field in the SIZ marker segment is not set properly.

Parameters

  s | a string of the profile name, value can be from OJPH_PN_STRING_XXXX, where only IMF and BROADCAST are currently supported.

Definition at line 109 of file ojph_codestream.cpp.

References state.

Referenced by main().

## ◆ set_tilepart_divisions()

void ojph::codestream::set_tilepart_divisions | ( | bool | at_resolutions,
|  | bool | at_components )

Sets the locations where a tile is partitioned into tile parts.

This function signals that we are interested in partitioning each tile into tile parts at resolution or component level, or both. This is useful when used with the TLM marker segment, because the TLM marker segment provides information about the locations of these partitions in the file. This way we can identify where resolution information ends within the codestream. It is also useful when large images are compressed, because an unpartitioned tile cannot be more than 4GB, but when partitioned, each tile part can be 4GB – it is possible to partition at precinct boundaries to better utilize tile parts, and achieve a tile in the vicinity of 1TB, but this option is currently unsupported.

Parameters

  at_resolutions | partitions the tile into tile parts at resolutions.
  at_components | partitions every tile into tile parts are components

Definition at line 115 of file ojph_codestream.cpp.

References ojph::OJPH_TILEPART_COMPONENTS, ojph::OJPH_TILEPART_RESOLUTIONS, and state.

Referenced by main().

## ◆ write_headers()

void ojph::codestream::write_headers | ( | outfile_base * | file,
|  | const comment_exchange * | comments = NULL,
|  | ui32 | num_comments = 0 )

Writes codestream headers when the codestream is used for writing. This function should be called after setting all the codestream parameters, but before pushing image lines using ojph::codestream::exchange().

Parameters

  file | A class inherited from outfile_base, which used to store compressed image bitstream. This enables storing the compressed bitstream to memory or an actual file.
  comments | A pointer to an array of comment_exchange objects. Each object stores one comment to be inserted in the bitstreams. The number of elements in the array should be equal to num_comments.
  num_comments | The number of elements in the comments array.

Definition at line 159 of file ojph_codestream.cpp.

References state.

Referenced by LLVMFuzzerTestOneInput(), main(), and TEST().

## Member Data Documentation

## ◆ state

local::codestream* ojph::codestream::state
| private

Definition at line 382 of file ojph_codestream.h.

Referenced by access_cod(), access_nlt(), access_qcd(), access_siz(), close(), codestream(), create(), enable_resilience(), exchange(), flush(), is_planar(), is_tilepart_division_at_components(), is_tilepart_division_at_resolutions(), is_tlm_requested(), pull(), read_headers(), request_tlm_marker(), restart(), restrict_input_resolution(), set_planar(), set_profile(), set_tilepart_divisions(), write_headers(), and ~codestream().

The documentation for this class was generated from the following files:

- /build/openjph/src/OpenJPH/src/core/openjph/ojph_codestream.h
- /build/openjph/src/OpenJPH/src/core/codestream/ojph_codestream.cpp