OpenJPH
Open-source implementation of JPEG2000 Part-15
|
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_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. 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_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. 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::codestream * | state |
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.
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.
ojph::codestream::~codestream | ( | ) |
default destructor
This object destroys the internal local::codestream object.
Definition at line 58 of file ojph_codestream.cpp.
References state.
param_cod ojph::codestream::access_cod | ( | ) |
Returns the underlying COD marker segment object.
Definition at line 76 of file ojph_codestream.cpp.
References ojph::local::codestream::cod, and state.
Referenced by main().
param_nlt ojph::codestream::access_nlt | ( | ) |
Returns the underlying NLT marker segment object.
Definition at line 88 of file ojph_codestream.cpp.
References ojph::local::codestream::nlt, and state.
Referenced by main().
param_qcd ojph::codestream::access_qcd | ( | ) |
Returns the underlying QCD marker segment object.
Definition at line 82 of file ojph_codestream.cpp.
References ojph::local::codestream::qcd, and state.
Referenced by main().
param_siz ojph::codestream::access_siz | ( | ) |
Returns the underlying SIZ marker segment object.
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().
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().
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().
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().
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.
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. |
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().
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().
bool ojph::codestream::is_planar | ( | ) | const |
Query if the codestream extraction is planar or not. See the documentation for ojph::codestream::set_planar()
Definition at line 144 of file ojph_codestream.cpp.
References ojph::local::codestream::is_planar(), and state.
Referenced by main().
bool ojph::codestream::is_tilepart_division_at_components | ( | ) |
Query if the tile will be partitioned at component boundary.
Definition at line 125 of file ojph_codestream.cpp.
References ojph::local::codestream::get_tilepart_div(), ojph::OJPH_TILEPART_COMPONENTS, and state.
bool ojph::codestream::is_tilepart_division_at_resolutions | ( | ) |
Query if the tile will be partitioned at resolution boundary.
Definition at line 118 of file ojph_codestream.cpp.
References ojph::local::codestream::get_tilepart_div(), ojph::OJPH_TILEPART_RESOLUTIONS, and state.
bool ojph::codestream::is_tlm_requested | ( | ) |
Query if the optional TLM marker segment is to be added.
Definition at line 138 of file ojph_codestream.cpp.
References ojph::local::codestream::is_tlm_needed(), and state.
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.
comp_num | returns the component to which the returned line_buf object belongs. |
Definition at line 184 of file ojph_codestream.cpp.
References ojph::local::codestream::pull(), and state.
Referenced by cpp_pull_j2c_line(), and main().
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().
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 164 of file ojph_codestream.cpp.
References ojph::local::codestream::read_headers(), and state.
Referenced by cpp_init_j2c_data(), and main().
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())
needed | true 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().
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()
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 170 of file ojph_codestream.cpp.
References ojph::local::codestream::restrict_input_resolution(), and state.
Referenced by cpp_restrict_input_resolution(), and main().
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.
planar | true 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().
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.
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 100 of file ojph_codestream.cpp.
References ojph::local::codestream::set_profile(), and state.
Referenced by main().
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.
at_resolutions | partitions the tile into tile parts at resolutions. |
at_components | partitions 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().
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().
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 150 of file ojph_codestream.cpp.
References state, and ojph::local::codestream::write_headers().
Referenced by main().
|
private |
Definition at line 365 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(), restrict_input_resolution(), set_planar(), set_profile(), set_tilepart_divisions(), write_headers(), and ~codestream().