OpenJPH
Open-source implementation of JPEG2000 Part-15
ojph::codestream Class Reference

The object represent a codestream. More...

#include <ojph_codestream.h>

Public Member Functions

 codestream ()
 default constructor More...
 
 ~codestream ()
 default destructor More...
 
void set_planar (bool planar)
 Sets the sequence of pushing or pull rows from the machinery. More...
 
void set_profile (const char *s)
 Sets the codestream profile. More...
 
void set_tilepart_divisions (bool at_resolutions, bool at_components)
 Sets the locations where a tile is partitioned into tile parts. More...
 
bool is_tilepart_division_at_resolutions ()
 Query if the tile will be partitioned at resolution boundary. More...
 
bool is_tilepart_division_at_components ()
 Query if the tile will be partitioned at component boundary. More...
 
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()) More...
 
bool is_tlm_requested ()
 Query if the optional TLM marker segment is to be added. More...
 
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(). More...
 
line_bufexchange (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. More...
 
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(). More...
 
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(). More...
 
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(). More...
 
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() More...
 
void create ()
 This call is for a decoding (or reading) codestream. Call this function after calling restrict_input_resolution(), if restrictions are needed. More...
 
line_bufpull (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. More...
 
void close ()
 Call this function to close the underlying file; works for both encoding and decoding codestreams. More...
 
param_siz access_siz ()
 Returns the underlying SIZ marker segment object. More...
 
param_cod access_cod ()
 Returns the underlying COD marker segment object. More...
 
param_qcd access_qcd ()
 Returns the underlying QCD marker segment object. More...
 
param_nlt access_nlt ()
 Returns the underlying NLT marker segment object. More...
 
bool is_planar () const
 Query if the codestream extraction is planar or not. See the documentation for ojph::codestream::set_planar() More...
 

Private Attributes

local::codestreamstate
 

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 object instantiate the actual implementation object local::codestream, using new.

Definition at line 64 of file ojph_codestream.cpp.

References state.

◆ ~codestream()

ojph::codestream::~codestream ( )

default destructor

This object 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 76 of file ojph_codestream.cpp.

References ojph::local::codestream::cod, and state.

Referenced by main().

◆ 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 88 of file ojph_codestream.cpp.

References ojph::local::codestream::nlt, and 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 82 of file ojph_codestream.cpp.

References ojph::local::codestream::qcd, and state.

Referenced by main().

◆ 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 70 of file ojph_codestream.cpp.

References ojph::local::codestream::siz, and 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(), and main().

◆ close()

void ojph::codestream::close ( )

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

Definition at line 197 of file ojph_codestream.cpp.

References ojph::local::codestream::close(), and state.

Referenced by main().

◆ 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 178 of file ojph_codestream.cpp.

References ojph::local::codestream::read(), and state.

Referenced by cpp_parse_j2c_data(), and main().

◆ 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 158 of file ojph_codestream.cpp.

References ojph::local::codestream::enable_resilience(), and state.

Referenced by enable_resilience(), 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
lineA line_buf object; first call should supply NULL. Subsequent calls should pass the line_buf object obtained in the previous call.
next_componentreturns 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 203 of file ojph_codestream.cpp.

References ojph::local::codestream::exchange(), and state.

Referenced by main().

◆ 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 191 of file ojph_codestream.cpp.

References ojph::local::codestream::flush(), and state.

Referenced by main().

◆ 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 144 of file ojph_codestream.cpp.

References ojph::local::codestream::is_planar(), and state.

Referenced by 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 125 of file ojph_codestream.cpp.

References ojph::local::codestream::get_tilepart_div(), 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 118 of file ojph_codestream.cpp.

References ojph::local::codestream::get_tilepart_div(), 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 138 of file ojph_codestream.cpp.

References ojph::local::codestream::is_tlm_needed(), and 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_numreturns 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 184 of file ojph_codestream.cpp.

References ojph::local::codestream::pull(), and state.

Referenced by cpp_pull_j2c_line(), and main().

◆ 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
fileThe 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 164 of file ojph_codestream.cpp.

References ojph::local::codestream::read_headers(), and state.

Referenced by cpp_init_j2c_data(), and main().

◆ 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
neededtrue when the marker is needed.

Definition at line 132 of file ojph_codestream.cpp.

References ojph::local::codestream::request_tlm_marker(), and state.

Referenced by main().

◆ 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_dataspecifies 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_reconspecifies 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 170 of file ojph_codestream.cpp.

References ojph::local::codestream::restrict_input_resolution(), and state.

Referenced by cpp_restrict_input_resolution(), and main().

◆ 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
planartrue for when components are pushed in full one at a time.

Definition at line 94 of file ojph_codestream.cpp.

References ojph::local::codestream::set_planar(), and state.

Referenced by cpp_parse_j2c_data(), and main().

◆ 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
sa string of the profile name, value can be from OJPH_PN_STRING_XXXX, where only IMF and BROADCAST are currently supported.

Definition at line 100 of file ojph_codestream.cpp.

References ojph::local::codestream::set_profile(), and 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_resolutionspartitions the tile into tile parts at resolutions.
at_componentspartitions every tile into tile parts are components

Definition at line 106 of file ojph_codestream.cpp.

References ojph::OJPH_TILEPART_COMPONENTS, ojph::OJPH_TILEPART_RESOLUTIONS, ojph::local::codestream::set_tilepart_divisions(), 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
fileA class inherited from outfile_base, which used to store compressed image bitstream. This enables storing the compressed bitstream to memory or an actual file.
commentsA 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_commentsThe number of elements in the comments array.

Definition at line 150 of file ojph_codestream.cpp.

References state, and ojph::local::codestream::write_headers().

Referenced by main().

Member Data Documentation

◆ state


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