arcstk::v_1_0_0::CalcContext class
#include <include/calculate.hpp>

Interface for information about the current audio input.

CalcContext provides the metadata that is required to perform the Calculation correctly.

The CalcContext determines whether the input is single- or multitrack and whether it has to skip samples on the beginning of the first or the end of the last track.

CalcContext also provides service methods for identifying the first and last sample of a track relevant for Calculation or to get the track for a given sample.

CalcContext offers also access to its underlying TOC data.

CalcContext instances are created exclusively via the variants of make_context().

A CalcContext is intended as a "read-only" object, it should never be required to modify the CalcContext of an audio input. The only exception is notify_skips() which depends on the concrete algorithm that is only known within Calculation. Thus, Calculation must inform its CalcContext about it.

Constructors, destructors, conversion operators

~CalcContext() pure virtual noexcept: Virtual default destructor.

Public functions

auto audio_size() const -> const AudioSize& noexcept: Return the size of the referenced audio file.
auto clone() const -> std::unique_ptr<CalcContext> noexcept: Clone this CalcContext object.
auto filename() const -> std::string noexcept: Name of current audio file.
auto first_relevant_sample() const -> sample_count_t noexcept: Get 0-based index of the first relevant sample of the current audio input.
auto first_relevant_sample(const TrackNo track) const -> sample_count_t noexcept: Get 0-based index of the first relevant sample of the specified 1-based track.
auto id() const -> ARId noexcept: Return the ARId of the current medium, if known.
auto is_multi_track() const -> bool noexcept: Returns TRUE if this instances indicates a processing for multiple tracks on a single input file.
auto last_relevant_sample() const -> sample_count_t noexcept: Get 0-based index of the last relevant sample of the current audio input.
auto last_relevant_sample(const TrackNo track) const -> sample_count_t noexcept: Get 0-based index of the last relevant sample of the specified 1-based track.
auto length(const int track) const -> lba_count_t noexcept: Return the normalized length of the specified 0-based track.
void notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back) noexcept: Notifies the instance about configured skipping amounts at the beginning of the first track and the end of the last track.
auto num_skip_back() const -> sample_count_t noexcept: Returns the amount of samples to skip at the end of the last track.
auto num_skip_front() const -> sample_count_t noexcept: Returns the amount of samples to skip at the beginning of the first track.
auto offset(const int track) const -> lba_count_t noexcept: Return the offset of the specified 0-based track from the TOC.
void set_audio_size(const AudioSize& audio_size): Inform about the AudioSize of the current file.
void set_filename(const std::string& filename) noexcept: Set the name of the current audio file.
auto skips_back() const -> bool noexcept: Returns TRUE iff this context will skip the last 2940 samples (5 LBA frames) of the last track.
auto skips_front() const -> bool noexcept: Returns TRUE iff this context will skip the first 2939 samples of the first track.
auto total_tracks() const -> int noexcept: Convenience method: Total number of tracks.
auto track(const sample_count_t smpl) const -> int noexcept: Returns 1-based track number of the track containing the specified 0-based sample.

Private functions

auto do_audio_size() const -> const AudioSize& pure virtual noexcept: Implements audio_size() const.
auto do_clone() const -> std::unique_ptr<CalcContext> pure virtual noexcept: Implements clone() const.
auto do_filename() const -> std::string pure virtual noexcept: Implements filename() const.
auto do_first_relevant_sample(const TrackNo track) const -> sample_count_t pure virtual noexcept: Implements first_relevant_sample(const TrackNo track) const.
auto do_first_relevant_sample_no_parms() const -> sample_count_t pure virtual noexcept: Implements first_relevant_sample() const.
auto do_id() const -> ARId pure virtual noexcept: Implements id() const.
auto do_is_multi_track() const -> bool pure virtual noexcept: Implements is_multi_track() const.
auto do_last_relevant_sample(const TrackNo track) const -> sample_count_t pure virtual noexcept: Implements last_relevant_sample(const TrackNo track) const.
auto do_last_relevant_sample_no_parms() const -> sample_count_t pure virtual noexcept: Implements last_relevant_sample() const.
auto do_length(const int track) const -> lba_count_t pure virtual noexcept: Implements length(const int track) const.
void do_notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back) pure virtual noexcept: Implements notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back).
auto do_num_skip_back() const -> sample_count_t pure virtual noexcept: Implements num_skip_back() const.
auto do_num_skip_front() const -> sample_count_t pure virtual noexcept: Implements num_skip_front() const.
auto do_offset(const int track) const -> lba_count_t pure virtual noexcept: Implements offset(const int track) const.
void do_set_audio_size(const AudioSize& audio_size) pure virtual: Implements set_audio_size(const AudioSize &audio_size).
void do_set_filename(const std::string& filename) pure virtual noexcept: Implements set_filename(const std::string &filename).
auto do_skips_back() const -> bool pure virtual noexcept: Implements skips_back() const.
auto do_skips_front() const -> bool pure virtual noexcept: Implements skips_front() const.
auto do_total_tracks() const -> int pure virtual noexcept: Implements total_tracks() const.
auto do_track(const sample_count_t smpl) const -> int pure virtual noexcept: Implements track(const sample_count_t smpl) const.

Function documentation

const AudioSize& arcstk::v_1_0_0::CalcContext::audio_size() const noexcept

Return the size of the referenced audio file.

Returns	The size of the referenced audio file

std::unique_ptr<CalcContext> arcstk::v_1_0_0::CalcContext::clone() const noexcept

Clone this CalcContext object.

Returns	A clone of this instance

A clone is a deep copy, i.e. the result of the cloning will be a different object with the exact same state.

std::string arcstk::v_1_0_0::CalcContext::filename() const noexcept

Name of current audio file.

Returns	Name of the audio file that is currently processed

sample_count_t arcstk::v_1_0_0::CalcContext::first_relevant_sample() const noexcept

Get 0-based index of the first relevant sample of the current audio input.

Returns	Index of the first sample contributing to the first track's ARCS

Which sample is actually the first relevant one depends on

the offset of the first track and
whether samples in the beginning of the first track are to be skipped.

Always equivalent with first_relevant_sample(1).

sample_count_t arcstk::v_1_0_0::CalcContext::first_relevant_sample(const TrackNo track) const noexcept

Get 0-based index of the first relevant sample of the specified 1-based track.

Parameters
track in	The 1-based track number
Returns	Index of the first sample contributing to the track's ARCS

Note that parameter track is 1-based, which means that first_relevant_sample(2) returns the first 0-based sample of the actual track 2 (and not track 3).

ARId arcstk::v_1_0_0::CalcContext::id() const noexcept

Return the ARId of the current medium, if known.

Returns	The ARId of the current medium

The value returned will only be significant iff non-empty offsets and non-zero total PCM byte count are available. Otherwise the ARId returned will be empty() .

bool arcstk::v_1_0_0::CalcContext::is_multi_track() const noexcept

Returns TRUE if this instances indicates a processing for multiple tracks on a single input file.

Returns	`TRUE` if this context specifies multitrack mode, otherwise `FALSE`

If this is FALSE, no chunks will be available. Multitrack mode is activated by setting a TOC.

sample_count_t arcstk::v_1_0_0::CalcContext::last_relevant_sample() const noexcept

Get 0-based index of the last relevant sample of the current audio input.

Returns	Index of the last sample contributing to the last track's ARCS

Which sample is actually the last relevant one depends on whether samples in the end of the last track are to be skipped.

Always equivalent with last_relevant_sample(this->total_tracks()).

sample_count_t arcstk::v_1_0_0::CalcContext::last_relevant_sample(const TrackNo track) const noexcept

Get 0-based index of the last relevant sample of the specified 1-based track.

Parameters
track in	1-based track number, accepts 0 as offset of track 1
Returns	Index of last sample contributing to the specified track's ARCS

Note that parameter track is 1-based, which means that last_relevant_sample(2) returns the last 0-based sample of the actual track 2 (and not track 3).

If no offsets are set, the output will always be identical to last_relevant_sample().

For track == 0, the last sample of the offset before track 1 is returned. This may of course be 0 iff the offset of track 1 is 0.

lba_count_t arcstk::v_1_0_0::CalcContext::length(const int track) const noexcept

Return the normalized length of the specified 0-based track.

Parameters
track in	The 0-based track to get the length for
Returns	The length for the specified 0-based track

Note that length(i) == offset(i+2) - offset(i+1) for all i: 0 <= i < toc().total_tracks() - 1.

For the last track t = toc().total_tracks() - 1, the value of length(t) may be 0 if the TOC is incomplete and the instance is not yet updated with the concrete AudioSize, otherwise it is length(t) == leadout_frame() - offset(t+1).

void arcstk::v_1_0_0::CalcContext::notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back) noexcept

Notifies the instance about configured skipping amounts at the beginning of the first track and the end of the last track.

Parameters
num_skip_front in	Actual amount of skipped samples at the beginning
num_skip_back in	Actual amount of skipped samples at the end

Whether actual skipping takes place can be determined by skips_front() and skips_back().

sample_count_t arcstk::v_1_0_0::CalcContext::num_skip_back() const noexcept

Returns the amount of samples to skip at the end of the last track.

Returns	The number of samples to skip at the end of the last track

If the audio input contains only one track, this track is the last track.

The value is either 2940 or 0.

The skipping is already active if this instance skips_back().

sample_count_t arcstk::v_1_0_0::CalcContext::num_skip_front() const noexcept

Returns the amount of samples to skip at the beginning of the first track.

Returns	The number of samples to skip at the beginning of the first track

If the audio input contains only one track, this track is the first track.

The value is either 2939 or 0.

The skipping is already active if this instance skips_front().

lba_count_t arcstk::v_1_0_0::CalcContext::offset(const int track) const noexcept

Return the offset of the specified 0-based track from the TOC.

Parameters
track in	The 0-based track to get the offset for
Returns	The offset for the specified 0-based track

Note that offset(i) == toc().offset(i+1) for all i: 0 <= i < toc().total_tracks().

void arcstk::v_1_0_0::CalcContext::set_audio_size(const AudioSize& audio_size)

Inform about the AudioSize of the current file.

Parameters
audio_size in	AudioSize

This contains the information about the leadout frame. This information must be known before Calculation::update is called on the last block.

void arcstk::v_1_0_0::CalcContext::set_filename(const std::string& filename) noexcept

Set the name of the current audio file.

Parameters
filename in	Name of the audio file that is to be processed

bool arcstk::v_1_0_0::CalcContext::skips_back() const noexcept

Returns TRUE iff this context will skip the last 2940 samples (5 LBA frames) of the last track.

Returns	`TRUE` iff context will signal to skip the last samples.

bool arcstk::v_1_0_0::CalcContext::skips_front() const noexcept

Returns TRUE iff this context will skip the first 2939 samples of the first track.

Returns	`TRUE` iff context will signal to skip the first samples.

int arcstk::v_1_0_0::CalcContext::total_tracks() const noexcept

Convenience method: Total number of tracks.

Returns	The number of tracks represented in this file

This number will aways be a non-negative integer up to 99 .

Since the track count should be accessed in a uniform way, regardless whether we actually have multiple tracks or only one.

int arcstk::v_1_0_0::CalcContext::track(const sample_count_t smpl) const noexcept

Returns 1-based track number of the track containing the specified 0-based sample.

Parameters
smpl in	The sample to get the track for
Returns	Track number of the track containing sample `smpl`

If total_samples() is 0, the method will return 0 regardless of the actual value of smpl.

If smpl is bigger than total_samples() - 1, the method will return an invalid high track number ("infinite").

The user has therefore to check for the validity of the result by checking whether 0 < result <= CDDA::MAX_TRACKCOUNT.

const AudioSize& arcstk::v_1_0_0::CalcContext::do_audio_size() const pure virtual private noexcept

Implements audio_size() const.

Returns	The total number of bytes of the PCM samples

std::unique_ptr<CalcContext> arcstk::v_1_0_0::CalcContext::do_clone() const pure virtual private noexcept

Implements clone() const.

Returns	A clone of this instance

std::string arcstk::v_1_0_0::CalcContext::do_filename() const pure virtual private noexcept

Implements filename() const.

Returns	Name of the audio file that is currently processed

sample_count_t arcstk::v_1_0_0::CalcContext::do_first_relevant_sample(const TrackNo track) const pure virtual private noexcept

Implements first_relevant_sample(const TrackNo track) const.

Parameters
track in	The 1-based track number
Returns	Index of the first sample contributing to the track's ARCS

sample_count_t arcstk::v_1_0_0::CalcContext::do_first_relevant_sample_no_parms() const pure virtual private noexcept

Implements first_relevant_sample() const.

Returns	Index of the first sample contributing to the first track's ARCS

ARId arcstk::v_1_0_0::CalcContext::do_id() const pure virtual private noexcept

Implements id() const.

Returns	The ARId of the current medium

bool arcstk::v_1_0_0::CalcContext::do_is_multi_track() const pure virtual private noexcept

Implements is_multi_track() const.

Returns	`TRUE` if this context specifies multitrack mode, otherwise `FALSE`

sample_count_t arcstk::v_1_0_0::CalcContext::do_last_relevant_sample(const TrackNo track) const pure virtual private noexcept

Implements last_relevant_sample(const TrackNo track) const.

Parameters
track in	1-based track number, accepts 0 as offset of track 1
Returns	Index of last sample contributing to the specified track's ARCS

sample_count_t arcstk::v_1_0_0::CalcContext::do_last_relevant_sample_no_parms() const pure virtual private noexcept

Implements last_relevant_sample() const.

Returns	Index of the last sample contributing to the last track's ARCS

lba_count_t arcstk::v_1_0_0::CalcContext::do_length(const int track) const pure virtual private noexcept

Implements length(const int track) const.

Parameters
track in	The 0-based track to get the length for
Returns	The length for the specified 0-based track

void arcstk::v_1_0_0::CalcContext::do_notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back) pure virtual private noexcept

Implements notify_skips(const sample_count_t num_skip_front, const sample_count_t num_skip_back).

Parameters
num_skip_front in	Actual amount of skipped samples at the beginning
num_skip_back in	Actual amount of skipped samples at the end

sample_count_t arcstk::v_1_0_0::CalcContext::do_num_skip_back() const pure virtual private noexcept

Implements num_skip_back() const.

Returns	The number of samples to skip at the end of the last track

sample_count_t arcstk::v_1_0_0::CalcContext::do_num_skip_front() const pure virtual private noexcept

Implements num_skip_front() const.

Returns	The number of samples to skip at the beginning of the first track

lba_count_t arcstk::v_1_0_0::CalcContext::do_offset(const int track) const pure virtual private noexcept

Implements offset(const int track) const.

Parameters
track in	The 0-based track to get the offset for
Returns	The offset for the specified 0-based track

void arcstk::v_1_0_0::CalcContext::do_set_audio_size(const AudioSize& audio_size) pure virtual private

Implements set_audio_size(const AudioSize &audio_size).

Parameters
audio_size in	AudioSize

void arcstk::v_1_0_0::CalcContext::do_set_filename(const std::string& filename) pure virtual private noexcept

Implements set_filename(const std::string &filename).

Parameters
filename in	Name of the audio file that is to be processed

bool arcstk::v_1_0_0::CalcContext::do_skips_back() const pure virtual private noexcept

Implements skips_back() const.

Returns	`TRUE` iff context will signal to skip the last samples.

bool arcstk::v_1_0_0::CalcContext::do_skips_front() const pure virtual private noexcept

Implements skips_front() const.

Returns	`TRUE` iff context will signal to skip the first samples.

int arcstk::v_1_0_0::CalcContext::do_total_tracks() const pure virtual private noexcept

Implements total_tracks() const.

Returns	The number of tracks represented in this file

int arcstk::v_1_0_0::CalcContext::do_track(const sample_count_t smpl) const pure virtual private noexcept

Implements track(const sample_count_t smpl) const.

Parameters
smpl in	The sample to get the track for
Returns	Track number of the track containing sample `smpl`