libopenmpt  0.4.1+release
cross-platform C++ and C library to decode tracked music files
openmpt::module Class Reference

#include <libopenmpt/libopenmpt.hpp>

Inheritance diagram for openmpt::module:
openmpt::module_ext

Public Types

enum  render_param { RENDER_MASTERGAIN_MILLIBEL = 1, RENDER_STEREOSEPARATION_PERCENT = 2, RENDER_INTERPOLATIONFILTER_LENGTH = 3, RENDER_VOLUMERAMPING_STRENGTH = 4 }
 Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param. More...
 
enum  command_index {
  command_note = 0, command_instrument = 1, command_volumeffect = 2, command_effect = 3,
  command_volume = 4, command_parameter = 5
}
 Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format_pattern_row_channel_command and openmpt::module::highlight_pattern_row_channel_command. More...
 

Public Member Functions

 module (std::istream &stream, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 Construct an openmpt::module. More...
 
 module (const std::vector< std::uint8_t > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const std::uint8_t *beg, const std::uint8_t *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const std::uint8_t *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const std::vector< char > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const char *beg, const char *end, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const char *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
 module (const void *data, std::size_t size, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
 
virtual ~module ()
 
void select_subsong (std::int32_t subsong)
 Select a sub-song from a multi-song module. More...
 
std::int32_t get_selected_subsong () const
 Get currently selected sub-song from a multi-song module. More...
 
void set_repeat_count (std::int32_t repeat_count)
 Set Repeat Count. More...
 
std::int32_t get_repeat_count () const
 Get Repeat Count. More...
 
double get_duration_seconds () const
 Get approximate song duration. More...
 
double set_position_seconds (double seconds)
 Set approximate current song position. More...
 
double get_position_seconds () const
 Get current song position. More...
 
double set_position_order_row (std::int32_t order, std::int32_t row)
 Set approximate current song position. More...
 
std::int32_t get_render_param (int param) const
 Get render parameter. More...
 
void set_render_param (int param, std::int32_t value)
 Set render parameter. More...
 
std::vector< std::string > get_metadata_keys () const
 Get the list of supported metadata item keys. More...
 
std::string get_metadata (const std::string &key) const
 Get a metadata item value. More...
 
std::int32_t get_current_speed () const
 Get the current speed. More...
 
std::int32_t get_current_tempo () const
 Get the current tempo. More...
 
std::int32_t get_current_order () const
 Get the current order. More...
 
std::int32_t get_current_pattern () const
 Get the current pattern. More...
 
std::int32_t get_current_row () const
 Get the current row. More...
 
std::int32_t get_current_playing_channels () const
 Get the current amount of playing channels. More...
 
float get_current_channel_vu_mono (std::int32_t channel) const
 Get an approximate indication of the channel volume. More...
 
float get_current_channel_vu_left (std::int32_t channel) const
 Get an approximate indication of the channel volume on the front-left speaker. More...
 
float get_current_channel_vu_right (std::int32_t channel) const
 Get an approximate indication of the channel volume on the front-right speaker. More...
 
float get_current_channel_vu_rear_left (std::int32_t channel) const
 Get an approximate indication of the channel volume on the rear-left speaker. More...
 
float get_current_channel_vu_rear_right (std::int32_t channel) const
 Get an approximate indication of the channel volume on the rear-right speaker. More...
 
std::int32_t get_num_subsongs () const
 Get the number of sub-songs. More...
 
std::int32_t get_num_channels () const
 Get the number of pattern channels. More...
 
std::int32_t get_num_orders () const
 Get the number of orders. More...
 
std::int32_t get_num_patterns () const
 Get the number of patterns. More...
 
std::int32_t get_num_instruments () const
 Get the number of instruments. More...
 
std::int32_t get_num_samples () const
 Get the number of samples. More...
 
std::vector< std::string > get_subsong_names () const
 Get a list of sub-song names. More...
 
std::vector< std::string > get_channel_names () const
 Get a list of channel names. More...
 
std::vector< std::string > get_order_names () const
 Get a list of order names. More...
 
std::vector< std::string > get_pattern_names () const
 Get a list of pattern names. More...
 
std::vector< std::string > get_instrument_names () const
 Get a list of instrument names. More...
 
std::vector< std::string > get_sample_names () const
 Get a list of sample names. More...
 
std::int32_t get_order_pattern (std::int32_t order) const
 Get pattern at order position. More...
 
std::int32_t get_pattern_num_rows (std::int32_t pattern) const
 Get the number of rows in a pattern. More...
 
std::uint8_t get_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
 Get raw pattern content. More...
 
std::string format_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
 Get formatted (human-readable) pattern content. More...
 
std::string highlight_pattern_row_channel_command (std::int32_t pattern, std::int32_t row, std::int32_t channel, int command) const
 Get highlighting information for formatted pattern content. More...
 
std::string format_pattern_row_channel (std::int32_t pattern, std::int32_t row, std::int32_t channel, std::size_t width=0, bool pad=true) const
 Get formatted (human-readable) pattern content. More...
 
std::string highlight_pattern_row_channel (std::int32_t pattern, std::int32_t row, std::int32_t channel, std::size_t width=0, bool pad=true) const
 Get highlighting information for formatted pattern content. More...
 
std::vector< std::string > get_ctls () const
 Retrieve supported ctl keys. More...
 
std::string ctl_get (const std::string &ctl) const
 Get current ctl value. More...
 
void ctl_set (const std::string &ctl, const std::string &value)
 Set ctl value. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, std::int16_t *mono)
 Render audio data. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right)
 Render audio data. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right, std::int16_t *rear_left, std::int16_t *rear_right)
 Render audio data. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, float *mono)
 Render audio data. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, float *left, float *right)
 Render audio data. More...
 
std::size_t read (std::int32_t samplerate, std::size_t count, float *left, float *right, float *rear_left, float *rear_right)
 Render audio data. More...
 
std::size_t read_interleaved_stereo (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_stereo)
 Render audio data. More...
 
std::size_t read_interleaved_quad (std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_quad)
 Render audio data. More...
 
std::size_t read_interleaved_stereo (std::int32_t samplerate, std::size_t count, float *interleaved_stereo)
 Render audio data. More...
 
std::size_t read_interleaved_quad (std::int32_t samplerate, std::size_t count, float *interleaved_quad)
 Render audio data. More...
 

Friends

class module_ext
 

Member Enumeration Documentation

◆ command_index

Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format_pattern_row_channel_command and openmpt::module::highlight_pattern_row_channel_command.

Enumerator
command_note 
command_instrument 
command_volumeffect 
command_effect 
command_volume 
command_parameter 

◆ render_param

Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param.

Enumerator
RENDER_MASTERGAIN_MILLIBEL 

Master Gain.

The related value represents a relative gain in milliBel.
The default value is 0.
The supported value range is unlimited.

RENDER_STEREOSEPARATION_PERCENT 

Stereo Separation.

The related value represents the stereo separation generated by the libopenmpt mixer in percent.
The default value is 100.
The supported value range is [0,200].

RENDER_INTERPOLATIONFILTER_LENGTH 

Interpolation Filter.

The related value represents the interpolation filter length used by the libopenmpt mixer.
The default value is 0, which indicates a recommended default value.
The supported value range is [0,inf). Values greater than the implementation limit are clamped to the maximum supported value.
Currently supported values:

  • 0: internal default
  • 1: no interpolation (zero order hold)
  • 2: linear interpolation
  • 4: cubic interpolation
  • 8: windowed sinc with 8 taps
RENDER_VOLUMERAMPING_STRENGTH 

Volume Ramping Strength.

The related value represents the amount of volume ramping done by the libopenmpt mixer.
The default value is -1, which indicates a recommended default value.
The meaningful value range is [-1..10].
A value of 0 completely disables volume ramping. This might cause clicks in sound output.
Higher values imply slower/softer volume ramps.

Constructor & Destructor Documentation

◆ module() [1/8]

openmpt::module::module ( std::istream &  stream,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)

Construct an openmpt::module.

Parameters
streamInput stream from which the module is loaded. After the constructor has finished successfully, the input position of stream is set to the byte after the last byte that has been read. If the constructor fails, the state of the input position of stream is undefined.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [2/8]

openmpt::module::module ( const std::vector< std::uint8_t > &  data,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
dataData to load the module from.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [3/8]

openmpt::module::module ( const std::uint8_t *  beg,
const std::uint8_t *  end,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
begBegin of data to load the module from.
endEnd of data to load the module from.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [4/8]

openmpt::module::module ( const std::uint8_t *  data,
std::size_t  size,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
dataData to load the module from.
sizeAmount of data available.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [5/8]

openmpt::module::module ( const std::vector< char > &  data,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
dataData to load the module from.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [6/8]

openmpt::module::module ( const char *  beg,
const char *  end,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
begBegin of data to load the module from.
endEnd of data to load the module from.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [7/8]

openmpt::module::module ( const char *  data,
std::size_t  size,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
dataData to load the module from.
sizeAmount of data available.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ module() [8/8]

openmpt::module::module ( const void *  data,
std::size_t  size,
std::ostream &  log = std::clog,
const std::map< std::string, std::string > &  ctls = detail::initial_ctls_map() 
)
Parameters
dataData to load the module from.
sizeAmount of data available.
logLog where any warnings or errors are printed to. The lifetime of the reference has to be as long as the lifetime of the module instance.
ctlsA map of initial ctl values, see openmpt::module::get_ctls.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the provided file cannot be opened.
Remarks
The input data can be discarded after an openmpt::module has been constructed successfully.
See also
File I/O

◆ ~module()

virtual openmpt::module::~module ( )
virtual

Member Function Documentation

◆ ctl_get()

std::string openmpt::module::ctl_get ( const std::string &  ctl) const

Get current ctl value.

Parameters
ctlThe ctl key whose value should be retrieved.
Returns
The associated ctl value.
See also
openmpt::module::get_ctls

◆ ctl_set()

void openmpt::module::ctl_set ( const std::string &  ctl,
const std::string &  value 
)

Set ctl value.

Parameters
ctlThe ctl key whose value should be set.
valueThe value that should be set.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception in case the value is not sensible (e.g. negative tempo factor) or under the circumstances outlined in openmpt::module::get_ctls.
See also
openmpt::module::get_ctls

◆ format_pattern_row_channel()

std::string openmpt::module::format_pattern_row_channel ( std::int32_t  pattern,
std::int32_t  row,
std::int32_t  channel,
std::size_t  width = 0,
bool  pad = true 
) const

Get formatted (human-readable) pattern content.

Parameters
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
widthThe maximum number of characters the string should contain. 0 means no limit.
padIf true, the string will be resized to the exact length provided in the width parameter.
Returns
The formatted pattern data at the given pattern position.
See also
openmpt::module::highlight_pattern_row_channel

◆ format_pattern_row_channel_command()

std::string openmpt::module::format_pattern_row_channel_command ( std::int32_t  pattern,
std::int32_t  row,
std::int32_t  channel,
int  command 
) const

Get formatted (human-readable) pattern content.

Parameters
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved.
Returns
The formatted pattern data at the given pattern position. See openmpt::module::command_index
See also
openmpt::module::highlight_pattern_row_channel_command

◆ get_channel_names()

std::vector<std::string> openmpt::module::get_channel_names ( ) const

Get a list of channel names.

Returns
All channel names.
See also
openmpt::module::get_num_channels

◆ get_ctls()

std::vector<std::string> openmpt::module::get_ctls ( ) const

Retrieve supported ctl keys.

Returns
A vector containing all supported ctl keys.
Remarks
Currently supported ctl values are:
  • load.skip_samples: Set to "1" to avoid loading samples into memory
  • load.skip_patterns: Set to "1" to avoid loading patterns into memory
  • load.skip_plugins: Set to "1" to avoid loading plugins
  • load.skip_subsongs_init: Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking.
  • seek.sync_samples: Set to "1" to sync sample playback when using openmpt::module::set_position_seconds or openmpt::module::set_position_order_row.
  • subsong: The current subsong. Setting it has identical semantics as openmpt::module::select_subsong(), getting it returns the currently selected subsong.
  • play.at_end: Chooses the behaviour when the end of song is reached:
    • "fadeout": Fades the module out for a short while. Subsequent reads after the fadeout will return 0 rendered frames.
    • "continue": Returns 0 rendered frames when the song end is reached. Subsequent reads will continue playing from the song start or loop start.
    • "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames.
  • play.tempo_factor: Set a floating point tempo factor. "1.0" is the default tempo.
  • play.pitch_factor: Set a floating point pitch factor. "1.0" is the default pitch.
  • render.resampler.emulate_amiga: Set to "1" to enable the Amiga resampler for Amiga modules. This emulates the sound characteristics of the Paula chip and overrides the selected interpolation filter. Non-Amiga module formats are not affected by this setting.
  • render.opl.volume_factor: Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume.
  • dither: Set the dither algorithm that is used for the 16 bit versions of openmpt::module::read. Supported values are:
    • 0: No dithering.
    • 1: Default mode. Chosen by OpenMPT code, might change.
    • 2: Rectangular, 0.5 bit depth, no noise shaping (original ModPlug Tracker).
    • 3: Rectangular, 1 bit depth, simple 1st order noise shaping

An exclamation mark ("!") or a question mark ("?") can be appended to any ctl key in order to influence the behaviour in case of an unknown ctl key. "!" causes an exception to be thrown; "?" causes the ctl to be silently ignored. In case neither is appended to the key name, unknown init_ctls are ignored by default and other ctls throw an exception by default.

◆ get_current_channel_vu_left()

float openmpt::module::get_current_channel_vu_left ( std::int32_t  channel) const

Get an approximate indication of the channel volume on the front-left speaker.

Parameters
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ get_current_channel_vu_mono()

float openmpt::module::get_current_channel_vu_mono ( std::int32_t  channel) const

Get an approximate indication of the channel volume.

Parameters
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ get_current_channel_vu_rear_left()

float openmpt::module::get_current_channel_vu_rear_left ( std::int32_t  channel) const

Get an approximate indication of the channel volume on the rear-left speaker.

Parameters
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ get_current_channel_vu_rear_right()

float openmpt::module::get_current_channel_vu_rear_right ( std::int32_t  channel) const

Get an approximate indication of the channel volume on the rear-right speaker.

Parameters
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ get_current_channel_vu_right()

float openmpt::module::get_current_channel_vu_right ( std::int32_t  channel) const

Get an approximate indication of the channel volume on the front-right speaker.

Parameters
channelThe channel whose volume should be retrieved.
Returns
The approximate channel volume.
Remarks
The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account.

◆ get_current_order()

std::int32_t openmpt::module::get_current_order ( ) const

Get the current order.

Returns
The current order at which the module is being played back.

◆ get_current_pattern()

std::int32_t openmpt::module::get_current_pattern ( ) const

Get the current pattern.

Returns
The current pattern that is being played.

◆ get_current_playing_channels()

std::int32_t openmpt::module::get_current_playing_channels ( ) const

Get the current amount of playing channels.

Returns
The amount of sample channels that are currently being rendered.

◆ get_current_row()

std::int32_t openmpt::module::get_current_row ( ) const

Get the current row.

Returns
The current row at which the current pattern is being played.

◆ get_current_speed()

std::int32_t openmpt::module::get_current_speed ( ) const

Get the current speed.

Returns
The current speed in ticks per row.

◆ get_current_tempo()

std::int32_t openmpt::module::get_current_tempo ( ) const

Get the current tempo.

Returns
The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used.

◆ get_duration_seconds()

double openmpt::module::get_duration_seconds ( ) const

Get approximate song duration.

Returns
Approximate duration of current sub-song in seconds.

◆ get_instrument_names()

std::vector<std::string> openmpt::module::get_instrument_names ( ) const

Get a list of instrument names.

Returns
All instrument names.
See also
openmpt::module::get_num_instruments

◆ get_metadata()

std::string openmpt::module::get_metadata ( const std::string &  key) const

Get a metadata item value.

Parameters
keyMetadata item key to query. Use openmpt::module::get_metadata_keys to check for available keys. Possible keys are:
  • type: Module format extension (e.g. it)
  • type_long: Format name associated with the module format (e.g. Impulse Tracker)
  • originaltype: Module format extension (e.g. it) of the original module in case the actual type is a converted format (e.g. mo3 or gdm)
  • originaltype_long: Format name associated with the module format (e.g. Impulse Tracker) of the original module in case the actual type is a converted format (e.g. mo3 or gdm)
  • container: Container format the module file is embedded in, if any (e.g. umx)
  • container_long: Full container name if the module is embedded in a container (e.g. Unreal Music)
  • tracker: Tracker that was (most likely) used to save the module file, if known
  • artist: Author of the module
  • title: Module title
  • date: Date the module was last saved, in ISO-8601 format.
  • message: Song message. If the song message is empty or the module format does not support song messages, a list of instrument and sample names is returned instead.
  • message_raw: Song message. If the song message is empty or the module format does not support song messages, an empty string is returned.
  • warnings: A list of warnings that were generated while loading the module.
Returns
The associated value for key.
See also
openmpt::module::get_metadata_keys

◆ get_metadata_keys()

std::vector<std::string> openmpt::module::get_metadata_keys ( ) const

Get the list of supported metadata item keys.

Returns
Metadata item keys supported by openmpt::module::get_metadata
See also
openmpt::module::get_metadata

◆ get_num_channels()

std::int32_t openmpt::module::get_num_channels ( ) const

Get the number of pattern channels.

Returns
The number of pattern channels in the module. Not all channels do necessarily contain data.
Remarks
The number of pattern channels is completely independent of the number of output channels. libopenmpt can render modules in mono, stereo or quad surround, but the choice of which of the three modes to use must not be made based on the return value of this function, which may be any positive integer amount. Only use this function for informational purposes.

◆ get_num_instruments()

std::int32_t openmpt::module::get_num_instruments ( ) const

Get the number of instruments.

Returns
The number of instrument slots in the module. Instruments are a layer on top of samples, and are not supported by all module formats.

◆ get_num_orders()

std::int32_t openmpt::module::get_num_orders ( ) const

Get the number of orders.

Returns
The number of orders in the current sequence of the module.

◆ get_num_patterns()

std::int32_t openmpt::module::get_num_patterns ( ) const

Get the number of patterns.

Returns
The number of distinct patterns in the module.

◆ get_num_samples()

std::int32_t openmpt::module::get_num_samples ( ) const

Get the number of samples.

Returns
The number of sample slots in the module.

◆ get_num_subsongs()

std::int32_t openmpt::module::get_num_subsongs ( ) const

Get the number of sub-songs.

Returns
The number of sub-songs in the module. This includes any "hidden" songs (songs that share the same sequence, but start at different order indices) and "normal" sub-songs or "sequences" (if the format supports them).
See also
openmpt::module::get_subsong_names, openmpt::module::select_subsong, openmpt::module::get_selected_subsong

◆ get_order_names()

std::vector<std::string> openmpt::module::get_order_names ( ) const

Get a list of order names.

Returns
All order names.
See also
openmpt::module::get_num_orders

◆ get_order_pattern()

std::int32_t openmpt::module::get_order_pattern ( std::int32_t  order) const

Get pattern at order position.

Parameters
orderThe order item whose pattern index should be retrieved.
Returns
The pattern index found at the given order position of the current sequence.

◆ get_pattern_names()

std::vector<std::string> openmpt::module::get_pattern_names ( ) const

Get a list of pattern names.

Returns
All pattern names.
See also
openmpt::module::get_num_patterns

◆ get_pattern_num_rows()

std::int32_t openmpt::module::get_pattern_num_rows ( std::int32_t  pattern) const

Get the number of rows in a pattern.

Parameters
patternThe pattern whose row count should be retrieved.
Returns
The number of rows in the given pattern. If the pattern does not exist, 0 is returned.

◆ get_pattern_row_channel_command()

std::uint8_t openmpt::module::get_pattern_row_channel_command ( std::int32_t  pattern,
std::int32_t  row,
std::int32_t  channel,
int  command 
) const

Get raw pattern content.

Parameters
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved. See openmpt::module::command_index
Returns
The internal, raw pattern data at the given pattern position.

◆ get_position_seconds()

double openmpt::module::get_position_seconds ( ) const

Get current song position.

Returns
Current song position in seconds.
See also
openmpt::module::set_position_seconds

◆ get_render_param()

std::int32_t openmpt::module::get_render_param ( int  param) const

Get render parameter.

Parameters
paramParameter to query. See openmpt::module::render_param.
Returns
The current value of the parameter.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception if param is invalid.
See also
openmpt::module::render_param
openmpt::module::set_render_param

◆ get_repeat_count()

std::int32_t openmpt::module::get_repeat_count ( ) const

Get Repeat Count.

Returns
Repeat Count
  • -1: repeat forever
  • 0: play once, repeat zero times (the default)
  • n>0: play once and repeat n times after that
See also
openmpt::module::set_repeat_count

◆ get_sample_names()

std::vector<std::string> openmpt::module::get_sample_names ( ) const

Get a list of sample names.

Returns
All sample names.
See also
openmpt::module::get_num_samples

◆ get_selected_subsong()

std::int32_t openmpt::module::get_selected_subsong ( ) const

Get currently selected sub-song from a multi-song module.

Returns
Currently selected sub-song. -1 for all subsongs consecutively, 0 or greater for the current sub-song index.
See also
openmpt::module::get_num_subsongs, openmpt::module::select_subsong, openmpt::module::get_subsong_names
Since
0.3.0

◆ get_subsong_names()

std::vector<std::string> openmpt::module::get_subsong_names ( ) const

Get a list of sub-song names.

Returns
All sub-song names.
See also
openmpt::module::get_num_subsongs, openmpt::module::select_subsong, openmpt::module::get_selected_subsong

◆ highlight_pattern_row_channel()

std::string openmpt::module::highlight_pattern_row_channel ( std::int32_t  pattern,
std::int32_t  row,
std::int32_t  channel,
std::size_t  width = 0,
bool  pad = true 
) const

Get highlighting information for formatted pattern content.

Parameters
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
widthThe maximum number of characters the string should contain. 0 means no limit.
padIf true, the string will be resized to the exact length provided in the width parameter.
Returns
The highlighting string for the formatted pattern data as retrieved by openmpt::module::format_pattern_row_channel at the given pattern position.
See also
openmpt::module::format_pattern_row_channel

◆ highlight_pattern_row_channel_command()

std::string openmpt::module::highlight_pattern_row_channel_command ( std::int32_t  pattern,
std::int32_t  row,
std::int32_t  channel,
int  command 
) const

Get highlighting information for formatted pattern content.

Parameters
patternThe pattern whose data should be retrieved.
rowThe row from which the data should be retrieved.
channelThe channel from which the data should be retrieved.
commandThe cell index at which the data should be retrieved. See openmpt::module::command_index
Returns
The highlighting string for the formatted pattern data as retrieved by openmpt::module::get_pattern_row_channel_command at the given pattern position.
Remarks
The returned string will map each character position of the string returned by openmpt::module::get_pattern_row_channel_command to a highlighting instruction. Possible highlighting characters are:
  • " " : empty/space
  • "." : empty/dot
  • "n" : generic note
  • "m" : special note
  • "i" : generic instrument
  • "u" : generic volume column effect
  • "v" : generic volume column parameter
  • "e" : generic effect column effect
  • "f" : generic effect column parameter
See also
openmpt::module::get_pattern_row_channel_command

◆ read() [1/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
std::int16_t *  mono 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
monoPointer to a buffer of at least count elements that receives the mono/center output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ read() [2/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
std::int16_t *  left,
std::int16_t *  right 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ read() [3/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
std::int16_t *  left,
std::int16_t *  right,
std::int16_t *  rear_left,
std::int16_t *  rear_right 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
rear_leftPointer to a buffer of at least count elements that receives the rear left output.
rear_rightPointer to a buffer of at least count elements that receives the rear right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ read() [4/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
float *  mono 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
monoPointer to a buffer of at least count elements that receives the mono/center output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ read() [5/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
float *  left,
float *  right 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ read() [6/6]

std::size_t openmpt::module::read ( std::int32_t  samplerate,
std::size_t  count,
float *  left,
float *  right,
float *  rear_left,
float *  rear_right 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
leftPointer to a buffer of at least count elements that receives the left output.
rightPointer to a buffer of at least count elements that receives the right output.
rear_leftPointer to a buffer of at least count elements that receives the rear left output.
rear_rightPointer to a buffer of at least count elements that receives the rear right output.
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ read_interleaved_quad() [1/2]

std::size_t openmpt::module::read_interleaved_quad ( std::int32_t  samplerate,
std::size_t  count,
std::int16_t *  interleaved_quad 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_quadPointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ read_interleaved_quad() [2/2]

std::size_t openmpt::module::read_interleaved_quad ( std::int32_t  samplerate,
std::size_t  count,
float *  interleaved_quad 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_quadPointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ read_interleaved_stereo() [1/2]

std::size_t openmpt::module::read_interleaved_stereo ( std::int32_t  samplerate,
std::size_t  count,
std::int16_t *  interleaved_stereo 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_stereoPointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
It is recommended to use the floating point API because of the greater dynamic range and no implied clipping.
See also
Output Format

◆ read_interleaved_stereo() [2/2]

std::size_t openmpt::module::read_interleaved_stereo ( std::int32_t  samplerate,
std::size_t  count,
float *  interleaved_stereo 
)

Render audio data.

Parameters
samplerateSample rate to render output. Should be in [8000,192000], but this is not enforced.
countNumber of audio frames to render per channel.
interleaved_stereoPointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R).
Returns
The number of frames actually rendered.
Return values
0The end of song has been reached.
Remarks
The output buffers are only written to up to the returned number of elements.
You can freely switch between any of the "read*" variants if you see a need to do so. libopenmpt tries to introduce as little switching annoyances as possible. Normally, you would only use a single one of these functions for rendering a particular module.
Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot.
See also
Output Format

◆ select_subsong()

void openmpt::module::select_subsong ( std::int32_t  subsong)

Select a sub-song from a multi-song module.

Parameters
subsongIndex of the sub-song. -1 plays all sub-songs consecutively.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception if sub-song is not in range [-1,openmpt::module::get_num_subsongs()[
See also
openmpt::module::get_num_subsongs, openmpt::module::get_selected_subsong, openmpt::module::get_subsong_names
Remarks
Whether subsong -1 (all subsongs consecutively), subsong 0 or some other subsong is selected by default, is an implementation detail and subject to change. If you do not want to care about subsongs, it is recommended to just not call openmpt::module::select_subsong() at all.

◆ set_position_order_row()

double openmpt::module::set_position_order_row ( std::int32_t  order,
std::int32_t  row 
)

Set approximate current song position.

If order or row are out of range, to position is not modified and the current position is returned.

Parameters
orderPattern order number to seek to.
rowPattern row number to seek to.
Returns
Approximate new song position in seconds.
See also
openmpt::module::set_position_seconds
openmpt::module::get_position_seconds

◆ set_position_seconds()

double openmpt::module::set_position_seconds ( double  seconds)

Set approximate current song position.

Parameters
secondsSeconds to seek to. If seconds is out of range, the position gets set to song start or end respectively.
Returns
Approximate new song position in seconds.
See also
openmpt::module::get_position_seconds

◆ set_render_param()

void openmpt::module::set_render_param ( int  param,
std::int32_t  value 
)

Set render parameter.

Parameters
paramParameter to set. See openmpt::module::render_param.
valueThe value to set param to.
Exceptions
openmpt::exceptionThrows an exception derived from openmpt::exception if param is invalid or value is out of range.
See also
openmpt::module::render_param
openmpt::module::get_render_param

◆ set_repeat_count()

void openmpt::module::set_repeat_count ( std::int32_t  repeat_count)

Set Repeat Count.

Parameters
repeat_countRepeat Count
  • -1: repeat forever
  • 0: play once, repeat zero times (the default)
  • n>0: play once and repeat n times after that
See also
openmpt::module::get_repeat_count

Friends And Related Function Documentation

◆ module_ext

friend class module_ext
friend

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