libopenmpt  0.4.3+release.autotools
cross-platform C++ and C library to decode tracked music files
libopenmpt.hpp
Go to the documentation of this file.
1 /*
2  * libopenmpt.hpp
3  * --------------
4  * Purpose: libopenmpt public c++ interface
5  * Notes : (currently none)
6  * Authors: OpenMPT Devs
7  * The OpenMPT source code is released under the BSD license. Read LICENSE for more details.
8  */
9 
10 #ifndef LIBOPENMPT_HPP
11 #define LIBOPENMPT_HPP
12 
13 #include "libopenmpt_config.h"
14 
15 #include <exception>
16 #include <iosfwd>
17 #include <iostream>
18 #include <map>
19 #include <string>
20 #include <vector>
21 
22 #include <cstdint>
23 
132 namespace openmpt {
133 
134 #if defined(_MSC_VER)
135 #pragma warning(push)
136 #pragma warning(disable:4275)
137 #endif
138 
143 class LIBOPENMPT_CXX_API exception : public std::exception {
144 private:
145  char * text;
146 public:
147  exception( const std::string & text ) noexcept;
148  exception( const exception & other ) noexcept;
149  exception( exception && other ) noexcept;
150  exception & operator = ( const exception & other ) noexcept;
151  exception & operator = ( exception && other ) noexcept;
152  virtual ~exception() noexcept;
153  const char * what() const noexcept override;
154 }; // class exception
155 #if defined(_MSC_VER)
156 #pragma warning(pop)
157 #endif
158 
160 
165 LIBOPENMPT_CXX_API std::uint32_t get_library_version();
166 
168 
172 LIBOPENMPT_CXX_API std::uint32_t get_core_version();
173 
174 namespace string {
175 
177 LIBOPENMPT_DEPRECATED static const char library_version LIBOPENMPT_ATTR_DEPRECATED [] = "library_version";
179 LIBOPENMPT_DEPRECATED static const char library_features LIBOPENMPT_ATTR_DEPRECATED [] = "library_features";
181 LIBOPENMPT_DEPRECATED static const char core_version LIBOPENMPT_ATTR_DEPRECATED [] = "core_version";
183 LIBOPENMPT_DEPRECATED static const char build LIBOPENMPT_ATTR_DEPRECATED [] = "build";
185 LIBOPENMPT_DEPRECATED static const char credits LIBOPENMPT_ATTR_DEPRECATED [] = "credits";
187 LIBOPENMPT_DEPRECATED static const char contact LIBOPENMPT_ATTR_DEPRECATED [] = "contact";
189 LIBOPENMPT_DEPRECATED static const char license LIBOPENMPT_ATTR_DEPRECATED [] = "license";
190 
192 
220 LIBOPENMPT_CXX_API std::string get( const std::string & key );
221 
222 } // namespace string
223 
225 
228 LIBOPENMPT_CXX_API std::vector<std::string> get_supported_extensions();
229 
231 
235 LIBOPENMPT_CXX_API bool is_extension_supported( const std::string & extension );
236 
238 
250 LIBOPENMPT_CXX_API double could_open_probability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
251 
253 
256 LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API LIBOPENMPT_DEPRECATED double could_open_propability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
257 
259 
263 LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size();
264 
266 static const std::uint64_t probe_file_header_flags_modules = 0x1ul;
267 
269 static const std::uint64_t probe_file_header_flags_containers = 0x2ul;
270 
273 
275 static const std::uint64_t probe_file_header_flags_none = 0x0ul;
276 
282 };
283 
285 
299 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size, std::uint64_t filesize );
300 
302 
316 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size );
317 
319 
331 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, std::istream & stream );
332 
333 class module_impl;
334 
335 class module_ext;
336 
337 namespace detail {
338 
339 typedef std::map< std::string, std::string > initial_ctls_map;
340 
341 } // namespace detail
342 
343 class LIBOPENMPT_CXX_API module {
344 
345  friend class module_ext;
346 
347 public:
348 
352 
357  RENDER_MASTERGAIN_MILLIBEL = 1,
359 
364  RENDER_STEREOSEPARATION_PERCENT = 2,
366 
377  RENDER_INTERPOLATIONFILTER_LENGTH = 3,
379 
386  RENDER_VOLUMERAMPING_STRENGTH = 4
387  };
388 
391  command_note = 0,
392  command_instrument = 1,
393  command_volumeffect = 2,
394  command_effect = 3,
395  command_volume = 4,
396  command_parameter = 5
397  };
398 
399 private:
400  module_impl * impl;
401 private:
402  // non-copyable
403  module( const module & );
404  void operator = ( const module & );
405 private:
406  // for module_ext
407  module();
408  void set_impl( module_impl * i );
409 public:
411 
419  module( std::istream & stream, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
428  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() );
438  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() );
448  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() );
457  module( const std::vector<char> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
467  module( const char * beg, const char * end, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
477  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() );
487  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() );
488  virtual ~module();
489 public:
490 
492 
498  void select_subsong( std::int32_t subsong );
500 
505  std::int32_t get_selected_subsong() const;
507 
514  void set_repeat_count( std::int32_t repeat_count );
516 
523  std::int32_t get_repeat_count() const;
524 
526 
529  double get_duration_seconds() const;
530 
532 
537  double set_position_seconds( double seconds );
539 
543  double get_position_seconds() const;
544 
546 
554  double set_position_order_row( std::int32_t order, std::int32_t row );
555 
557 
564  std::int32_t get_render_param( int param ) const;
566 
573  void set_render_param( int param, std::int32_t value );
574 
576 
588  std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * mono );
590 
602  std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * left, std::int16_t * right );
604 
618  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 );
620 
631  std::size_t read( std::int32_t samplerate, std::size_t count, float * mono );
633 
645  std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right );
647 
661  std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right, float * rear_left, float * rear_right );
663 
674  std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_stereo );
676 
687  std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_quad );
689 
700  std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, float * interleaved_stereo );
702 
713  std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, float * interleaved_quad );
716 
721  std::vector<std::string> get_metadata_keys() const;
723 
742  std::string get_metadata( const std::string & key ) const;
743 
745 
748  std::int32_t get_current_speed() const;
750 
753  std::int32_t get_current_tempo() const;
755 
758  std::int32_t get_current_order() const;
760 
763  std::int32_t get_current_pattern() const;
765 
768  std::int32_t get_current_row() const;
770 
773  std::int32_t get_current_playing_channels() const;
774 
776 
781  float get_current_channel_vu_mono( std::int32_t channel ) const;
783 
788  float get_current_channel_vu_left( std::int32_t channel ) const;
790 
795  float get_current_channel_vu_right( std::int32_t channel ) const;
797 
802  float get_current_channel_vu_rear_left( std::int32_t channel ) const;
804 
809  float get_current_channel_vu_rear_right( std::int32_t channel ) const;
810 
812 
816  std::int32_t get_num_subsongs() const;
818 
822  std::int32_t get_num_channels() const;
824 
827  std::int32_t get_num_orders() const;
829 
832  std::int32_t get_num_patterns() const;
834 
837  std::int32_t get_num_instruments() const;
839 
842  std::int32_t get_num_samples() const;
843 
845 
849  std::vector<std::string> get_subsong_names() const;
851 
855  std::vector<std::string> get_channel_names() const;
857 
861  std::vector<std::string> get_order_names() const;
863 
867  std::vector<std::string> get_pattern_names() const;
869 
873  std::vector<std::string> get_instrument_names() const;
875 
879  std::vector<std::string> get_sample_names() const;
880 
882 
886  std::int32_t get_order_pattern( std::int32_t order ) const;
887 
889 
893  std::int32_t get_pattern_num_rows( std::int32_t pattern ) const;
894 
896 
903  std::uint8_t get_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
904 
906 
914  std::string format_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
915 
917 
936  std::string highlight_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
937 
939 
948  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;
950 
959  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;
960 
962 
987  std::vector<std::string> get_ctls() const;
988 
990 
995  std::string ctl_get( const std::string & ctl ) const;
997 
1003  void ctl_set( const std::string & ctl, const std::string & value );
1004 
1005  // remember to add new functions to both C and C++ interfaces and to increase OPENMPT_API_VERSION_MINOR
1006 
1007 }; // class module
1008 
1009 } // namespace openmpt
1010 
1015 #endif // LIBOPENMPT_HPP
openmpt::module::highlight_pattern_row_channel_command
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.
openmpt::string::get
LIBOPENMPT_CXX_API std::string get(const std::string &key)
Get library related metadata.
openmpt::module::get_current_speed
std::int32_t get_current_speed() const
Get the current speed.
openmpt::module::read_interleaved_stereo
std::size_t read_interleaved_stereo(std::int32_t samplerate, std::size_t count, float *interleaved_stereo)
Render audio data.
openmpt::module::get_metadata_keys
std::vector< std::string > get_metadata_keys() const
Get the list of supported metadata item keys.
openmpt::module::set_position_order_row
double set_position_order_row(std::int32_t order, std::int32_t row)
Set approximate current song position.
openmpt::module::get_num_patterns
std::int32_t get_num_patterns() const
Get the number of patterns.
openmpt::module::highlight_pattern_row_channel
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.
openmpt::probe_file_header_result_success
@ probe_file_header_result_success
Definition: libopenmpt.hpp:279
openmpt::module::get_subsong_names
std::vector< std::string > get_subsong_names() const
Get a list of sub-song names.
openmpt::module::get_current_order
std::int32_t get_current_order() const
Get the current order.
openmpt::module::get_num_orders
std::int32_t get_num_orders() const
Get the number of orders.
openmpt::module::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())
libopenmpt_config.h
openmpt::module::command_index
command_index
Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format...
Definition: libopenmpt.hpp:390
openmpt::module::~module
virtual ~module()
openmpt::module::read
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.
openmpt::module::get_current_channel_vu_left
float get_current_channel_vu_left(std::int32_t channel) const
Get an approximate indication of the channel volume on the front-left speaker.
openmpt::module::select_subsong
void select_subsong(std::int32_t subsong)
Select a sub-song from a multi-song module.
openmpt::module::format_pattern_row_channel_command
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.
openmpt::probe_file_header_get_recommended_size
LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size()
Get recommended header size for successfull format probing.
openmpt::probe_file_header_flags_containers
static const std::uint64_t probe_file_header_flags_containers
Probe for module-specific container formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:269
openmpt::module::read
std::size_t read(std::int32_t samplerate, std::size_t count, float *mono)
Render audio data.
openmpt::module_ext
Definition: libopenmpt_ext.hpp:37
openmpt::module::get_order_pattern
std::int32_t get_order_pattern(std::int32_t order) const
Get pattern at order position.
openmpt::get_library_version
LIBOPENMPT_CXX_API std::uint32_t get_library_version()
Get the libopenmpt version number.
openmpt::module::read_interleaved_quad
std::size_t read_interleaved_quad(std::int32_t samplerate, std::size_t count, float *interleaved_quad)
Render audio data.
openmpt::exception::exception
exception(exception &&other) noexcept
LIBOPENMPT_DEPRECATED
#define LIBOPENMPT_DEPRECATED
Definition: libopenmpt_config.h:149
openmpt::module::read
std::size_t read(std::int32_t samplerate, std::size_t count, std::int16_t *left, std::int16_t *right)
Render audio data.
openmpt::module::get_instrument_names
std::vector< std::string > get_instrument_names() const
Get a list of instrument names.
openmpt::module::get_sample_names
std::vector< std::string > get_sample_names() const
Get a list of sample names.
openmpt::module::get_current_playing_channels
std::int32_t get_current_playing_channels() const
Get the current amount of playing channels.
openmpt::module::get_metadata
std::string get_metadata(const std::string &key) const
Get a metadata item value.
openmpt::module::get_pattern_num_rows
std::int32_t get_pattern_num_rows(std::int32_t pattern) const
Get the number of rows in a pattern.
openmpt::module::get_current_channel_vu_right
float get_current_channel_vu_right(std::int32_t channel) const
Get an approximate indication of the channel volume on the front-right speaker.
openmpt::module::get_channel_names
std::vector< std::string > get_channel_names() const
Get a list of channel names.
openmpt::module::read
std::size_t read(std::int32_t samplerate, std::size_t count, std::int16_t *mono)
Render audio data.
openmpt::module::get_selected_subsong
std::int32_t get_selected_subsong() const
Get currently selected sub-song from a multi-song module.
openmpt::module::get_current_channel_vu_rear_left
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.
openmpt::module::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())
openmpt::module::get_pattern_names
std::vector< std::string > get_pattern_names() const
Get a list of pattern names.
openmpt::probe_file_header_flags_modules
static const std::uint64_t probe_file_header_flags_modules
Probe for module formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:266
openmpt::module::get_pattern_row_channel_command
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.
openmpt::module::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())
openmpt::is_extension_supported
LIBOPENMPT_CXX_API bool is_extension_supported(const std::string &extension)
Query whether a file extension is supported.
openmpt::module::get_current_tempo
std::int32_t get_current_tempo() const
Get the current tempo.
openmpt::module::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())
openmpt::module::get_num_subsongs
std::int32_t get_num_subsongs() const
Get the number of sub-songs.
openmpt::get_core_version
LIBOPENMPT_CXX_API std::uint32_t get_core_version()
Get the core version number.
openmpt::could_open_probability
LIBOPENMPT_CXX_API double could_open_probability(std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
Roughly scan the input stream to find out whether libopenmpt might be able to open it.
openmpt::module::get_duration_seconds
double get_duration_seconds() const
Get approximate song duration.
openmpt::module::get_current_channel_vu_rear_right
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.
openmpt::probe_file_header_result
probe_file_header_result
Possible return values for openmpt::probe_file_header().
Definition: libopenmpt.hpp:278
openmpt::probe_file_header_flags_default
static const std::uint64_t probe_file_header_flags_default
Probe for the default set of formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:272
openmpt::exception::~exception
virtual ~exception() noexcept
openmpt::module::set_position_seconds
double set_position_seconds(double seconds)
Set approximate current song position.
openmpt::module::get_render_param
std::int32_t get_render_param(int param) const
Get render parameter.
openmpt::module::read
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.
openmpt::probe_file_header
LIBOPENMPT_CXX_API int probe_file_header(std::uint64_t flags, const std::uint8_t *data, std::size_t size, std::uint64_t filesize)
Probe the provided bytes from the beginning of a file for supported file format headers to find out w...
openmpt::module::read
std::size_t read(std::int32_t samplerate, std::size_t count, float *left, float *right)
Render audio data.
openmpt::module::get_ctls
std::vector< std::string > get_ctls() const
Retrieve supported ctl keys.
openmpt::module::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())
openmpt::module::format_pattern_row_channel
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.
openmpt::module::set_render_param
void set_render_param(int param, std::int32_t value)
Set render parameter.
openmpt::module::ctl_get
std::string ctl_get(const std::string &ctl) const
Get current ctl value.
openmpt::module::read_interleaved_stereo
std::size_t read_interleaved_stereo(std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_stereo)
Render audio data.
openmpt::module::get_current_channel_vu_mono
float get_current_channel_vu_mono(std::int32_t channel) const
Get an approximate indication of the channel volume.
openmpt::module::module
module(const std::vector< char > &data, std::ostream &log=std::clog, const std::map< std::string, std::string > &ctls=detail::initial_ctls_map())
openmpt::module::get_num_samples
std::int32_t get_num_samples() const
Get the number of samples.
openmpt::exception::exception
exception(const exception &other) noexcept
openmpt::module::get_repeat_count
std::int32_t get_repeat_count() const
Get Repeat Count.
openmpt::exception::exception
exception(const std::string &text) noexcept
openmpt::module::get_current_pattern
std::int32_t get_current_pattern() const
Get the current pattern.
openmpt::module::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.
openmpt
Definition: libopenmpt.hpp:132
openmpt::could_open_propability
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double could_open_propability(std::istream &stream, double effort=1.0, std::ostream &log=std::clog)
Roughly scan the input stream to find out whether libopenmpt might be able to open it.
openmpt::module::get_current_row
std::int32_t get_current_row() const
Get the current row.
openmpt::module::ctl_set
void ctl_set(const std::string &ctl, const std::string &value)
Set ctl value.
openmpt::string::LIBOPENMPT_ATTR_DEPRECATED
static const char library_version LIBOPENMPT_ATTR_DEPRECATED[]
Return a verbose library version string from openmpt::string::get().
Definition: libopenmpt.hpp:177
openmpt::module::get_num_channels
std::int32_t get_num_channels() const
Get the number of pattern channels.
openmpt::module::get_order_names
std::vector< std::string > get_order_names() const
Get a list of order names.
openmpt::exception
libopenmpt exception base class
Definition: libopenmpt.hpp:143
openmpt::module::set_repeat_count
void set_repeat_count(std::int32_t repeat_count)
Set Repeat Count.
openmpt::module::read_interleaved_quad
std::size_t read_interleaved_quad(std::int32_t samplerate, std::size_t count, std::int16_t *interleaved_quad)
Render audio data.
openmpt::module
Definition: libopenmpt.hpp:343
openmpt::get_supported_extensions
LIBOPENMPT_CXX_API std::vector< std::string > get_supported_extensions()
Get a list of supported file extensions.
openmpt::module::render_param
render_param
Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param.
Definition: libopenmpt.hpp:350
openmpt::probe_file_header_result_wantmoredata
@ probe_file_header_result_wantmoredata
Definition: libopenmpt.hpp:281
openmpt::probe_file_header_result_failure
@ probe_file_header_result_failure
Definition: libopenmpt.hpp:280
openmpt::module::get_position_seconds
double get_position_seconds() const
Get current song position.
openmpt::module::get_num_instruments
std::int32_t get_num_instruments() const
Get the number of instruments.
openmpt::module::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())
openmpt::probe_file_header_flags_none
static const std::uint64_t probe_file_header_flags_none
Probe for no formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:275