libopenmpt  0.7.8+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 <string_view>
21 #include <vector>
22 
23 #include <cstddef>
24 #include <cstdint>
25 
130 namespace openmpt {
131 
136 #if defined(_MSC_VER)
137 #pragma warning(push)
138 #pragma warning(disable:4275)
139 #endif
140 
145 class LIBOPENMPT_CXX_API_CLASS exception : public std::exception {
146 private:
147  char * text;
148 public:
149  LIBOPENMPT_CXX_API_MEMBER exception( const std::string & text ) noexcept;
150  LIBOPENMPT_CXX_API_MEMBER exception( const exception & other ) noexcept;
151  LIBOPENMPT_CXX_API_MEMBER exception( exception && other ) noexcept;
152  LIBOPENMPT_CXX_API_MEMBER exception & operator = ( const exception & other ) noexcept;
153  LIBOPENMPT_CXX_API_MEMBER exception & operator = ( exception && other ) noexcept;
154  LIBOPENMPT_CXX_API_MEMBER virtual ~exception() noexcept;
155  LIBOPENMPT_CXX_API_MEMBER const char * what() const noexcept override;
156 }; // class exception
157 #if defined(_MSC_VER)
158 #pragma warning(pop)
159 #endif
160 
162 
167 LIBOPENMPT_CXX_API std::uint32_t get_library_version();
168 
170 
174 LIBOPENMPT_CXX_API std::uint32_t get_core_version();
175 
176 namespace string {
177 
179 static const char library_version LIBOPENMPT_ATTR_DEPRECATED [] = "library_version";
181 static const char library_features LIBOPENMPT_ATTR_DEPRECATED [] = "library_features";
183 static const char core_version LIBOPENMPT_ATTR_DEPRECATED [] = "core_version";
185 static const char build LIBOPENMPT_ATTR_DEPRECATED [] = "build";
187 static const char credits LIBOPENMPT_ATTR_DEPRECATED [] = "credits";
189 static const char contact LIBOPENMPT_ATTR_DEPRECATED [] = "contact";
191 static const char license LIBOPENMPT_ATTR_DEPRECATED [] = "license";
192 
194 
222 LIBOPENMPT_CXX_API std::string get( const std::string & key );
223 
224 } // namespace string
225 
227 
230 LIBOPENMPT_CXX_API std::vector<std::string> get_supported_extensions();
231 
233 
238 LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool is_extension_supported( const std::string & extension );
240 
245 LIBOPENMPT_CXX_API bool is_extension_supported2( std::string_view extension );
246 
248 
260 LIBOPENMPT_CXX_API double could_open_probability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
261 
263 
266 LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API double could_open_propability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog );
267 
269 
273 LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size();
274 
276 static const std::uint64_t probe_file_header_flags_modules LIBOPENMPT_ATTR_DEPRECATED = 0x1ull;
277 
279 static const std::uint64_t probe_file_header_flags_containers LIBOPENMPT_ATTR_DEPRECATED = 0x2ull;
280 
282 static const std::uint64_t probe_file_header_flags_default LIBOPENMPT_ATTR_DEPRECATED = 0x1ull | 0x2ull;
283 
285 static const std::uint64_t probe_file_header_flags_none LIBOPENMPT_ATTR_DEPRECATED = 0x0ull;
286 
288 enum probe_file_header_flags : std::uint64_t {
297 };
298 
307 };
308 
310 
324 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size, std::uint64_t filesize );
326 
340 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size, std::uint64_t filesize );
341 
343 
357 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size );
359 
373 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size );
374 
376 
388 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, std::istream & stream );
389 
390 class module_impl;
391 
392 class module_ext;
393 
394 namespace detail {
395 
396 typedef std::map< std::string, std::string > initial_ctls_map;
397 
398 } // namespace detail
399 
400 class LIBOPENMPT_CXX_API_CLASS module {
401 
402  friend class module_ext;
403 
404 public:
405 
409 
414  RENDER_MASTERGAIN_MILLIBEL = 1,
416 
421  RENDER_STEREOSEPARATION_PERCENT = 2,
423 
434  RENDER_INTERPOLATIONFILTER_LENGTH = 3,
436 
443  RENDER_VOLUMERAMPING_STRENGTH = 4
444  };
445 
448  command_note = 0,
449  command_instrument = 1,
450  command_volumeffect = 2,
451  command_effect = 3,
452  command_volume = 4,
453  command_parameter = 5
454  };
455 
456 private:
457  module_impl * impl;
458 private:
459  // non-copyable
460  module( const module & );
461  void operator = ( const module & );
462 private:
463  // for module_ext
464  module();
465  void set_impl( module_impl * i );
466 public:
468 
476  LIBOPENMPT_CXX_API_MEMBER module( std::istream & stream, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
486  LIBOPENMPT_CXX_API_MEMBER module( const std::vector<std::byte> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
497  LIBOPENMPT_CXX_API_MEMBER module( const std::byte * beg, const std::byte * end, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
508  LIBOPENMPT_CXX_API_MEMBER module( const std::byte * data, std::size_t size, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
517  LIBOPENMPT_CXX_API_MEMBER 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() );
527  LIBOPENMPT_CXX_API_MEMBER 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() );
537  LIBOPENMPT_CXX_API_MEMBER 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() );
546  LIBOPENMPT_CXX_API_MEMBER module( const std::vector<char> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
556  LIBOPENMPT_CXX_API_MEMBER module( const char * beg, const char * end, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
566  LIBOPENMPT_CXX_API_MEMBER 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() );
576  LIBOPENMPT_CXX_API_MEMBER 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() );
577  LIBOPENMPT_CXX_API_MEMBER virtual ~module();
578 public:
579 
581 
587  LIBOPENMPT_CXX_API_MEMBER void select_subsong( std::int32_t subsong );
589 
594  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_selected_subsong() const;
596 
603  LIBOPENMPT_CXX_API_MEMBER void set_repeat_count( std::int32_t repeat_count );
605 
612  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_repeat_count() const;
613 
615 
619  LIBOPENMPT_CXX_API_MEMBER double get_duration_seconds() const;
620 
622 
627  LIBOPENMPT_CXX_API_MEMBER double set_position_seconds( double seconds );
629 
633  LIBOPENMPT_CXX_API_MEMBER double get_position_seconds() const;
634 
636 
644  LIBOPENMPT_CXX_API_MEMBER double set_position_order_row( std::int32_t order, std::int32_t row );
645 
647 
654  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_render_param( int param ) const;
656 
663  LIBOPENMPT_CXX_API_MEMBER void set_render_param( int param, std::int32_t value );
664 
666 
678  LIBOPENMPT_CXX_API_MEMBER std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * mono );
680 
692  LIBOPENMPT_CXX_API_MEMBER std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * left, std::int16_t * right );
694 
708  LIBOPENMPT_CXX_API_MEMBER 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 );
710 
721  LIBOPENMPT_CXX_API_MEMBER std::size_t read( std::int32_t samplerate, std::size_t count, float * mono );
723 
735  LIBOPENMPT_CXX_API_MEMBER std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right );
737 
751  LIBOPENMPT_CXX_API_MEMBER std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right, float * rear_left, float * rear_right );
753 
764  LIBOPENMPT_CXX_API_MEMBER std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_stereo );
766 
777  LIBOPENMPT_CXX_API_MEMBER std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_quad );
779 
790  LIBOPENMPT_CXX_API_MEMBER std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, float * interleaved_stereo );
792 
803  LIBOPENMPT_CXX_API_MEMBER std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, float * interleaved_quad );
806 
811  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_metadata_keys() const;
813 
832  LIBOPENMPT_CXX_API_MEMBER std::string get_metadata( const std::string & key ) const;
833 
835 
840  LIBOPENMPT_CXX_API_MEMBER double get_current_estimated_bpm() const;
842 
845  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_speed() const;
847 
851  LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_tempo() const;
853 
857  LIBOPENMPT_CXX_API_MEMBER double get_current_tempo2() const;
859 
862  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_order() const;
864 
867  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_pattern() const;
869 
872  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_row() const;
874 
877  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_current_playing_channels() const;
878 
880 
885  LIBOPENMPT_CXX_API_MEMBER float get_current_channel_vu_mono( std::int32_t channel ) const;
887 
892  LIBOPENMPT_CXX_API_MEMBER float get_current_channel_vu_left( std::int32_t channel ) const;
894 
899  LIBOPENMPT_CXX_API_MEMBER float get_current_channel_vu_right( std::int32_t channel ) const;
901 
906  LIBOPENMPT_CXX_API_MEMBER float get_current_channel_vu_rear_left( std::int32_t channel ) const;
908 
913  LIBOPENMPT_CXX_API_MEMBER float get_current_channel_vu_rear_right( std::int32_t channel ) const;
914 
916 
920  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_subsongs() const;
922 
926  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_channels() const;
928 
931  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_orders() const;
933 
936  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_patterns() const;
938 
941  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_instruments() const;
943 
946  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_num_samples() const;
947 
949 
953  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_subsong_names() const;
955 
959  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_channel_names() const;
961 
965  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_order_names() const;
967 
971  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_pattern_names() const;
973 
977  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_instrument_names() const;
979 
983  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_sample_names() const;
984 
986 
990  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_order_pattern( std::int32_t order ) const;
991 
993 
997  LIBOPENMPT_CXX_API_MEMBER std::int32_t get_pattern_num_rows( std::int32_t pattern ) const;
998 
1000 
1007  LIBOPENMPT_CXX_API_MEMBER std::uint8_t get_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1008 
1010 
1018  LIBOPENMPT_CXX_API_MEMBER std::string format_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1019 
1021 
1040  LIBOPENMPT_CXX_API_MEMBER std::string highlight_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1041 
1043 
1052  LIBOPENMPT_CXX_API_MEMBER 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;
1054 
1063  LIBOPENMPT_CXX_API_MEMBER 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;
1064 
1066 
1096  LIBOPENMPT_CXX_API_MEMBER std::vector<std::string> get_ctls() const;
1097 
1099 
1105  LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER std::string ctl_get( const std::string & ctl ) const;
1107 
1113  LIBOPENMPT_CXX_API_MEMBER bool ctl_get_boolean( std::string_view ctl ) const;
1115 
1121  LIBOPENMPT_CXX_API_MEMBER std::int64_t ctl_get_integer( std::string_view ctl ) const;
1123 
1129  LIBOPENMPT_CXX_API_MEMBER double ctl_get_floatingpoint( std::string_view ctl ) const;
1131 
1137  LIBOPENMPT_CXX_API_MEMBER std::string ctl_get_text( std::string_view ctl ) const;
1138 
1140 
1147  LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API_MEMBER void ctl_set( const std::string & ctl, const std::string & value );
1149 
1156  LIBOPENMPT_CXX_API_MEMBER void ctl_set_boolean( std::string_view ctl, bool value );
1158 
1165  LIBOPENMPT_CXX_API_MEMBER void ctl_set_integer( std::string_view ctl, std::int64_t value );
1167 
1174  LIBOPENMPT_CXX_API_MEMBER void ctl_set_floatingpoint( std::string_view ctl, double value );
1176 
1183  LIBOPENMPT_CXX_API_MEMBER void ctl_set_text( std::string_view ctl, std::string_view value );
1184 
1185  // remember to add new functions to both C and C++ interfaces and to increase OPENMPT_API_VERSION_MINOR
1186 
1187 }; // class module
1188 
1193 } // namespace openmpt
1194 
1195 #endif // LIBOPENMPT_HPP
The file is not supported by libopenmpt.
Definition: libopenmpt.hpp:304
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...
command_index
Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format...
Definition: libopenmpt.hpp:447
Probe for the default set of formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:294
probe_file_header_result
Possible return values for openmpt::probe_file_header().
Definition: libopenmpt.hpp:300
LIBOPENMPT_CXX_API int probe_file_header(std::uint64_t flags, const std::byte *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...
The file will most likely be supported by libopenmpt.
Definition: libopenmpt.hpp:302
static const std::uint64_t probe_file_header_flags_modules LIBOPENMPT_ATTR_DEPRECATED
Probe for module formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:276
LIBOPENMPT_CXX_API std::vector< std::string > get_supported_extensions()
Get a list of supported file extensions.
libopenmpt exception base class
Definition: libopenmpt.hpp:145
Probe for module-specific container formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:292
LIBOPENMPT_CXX_API bool is_extension_supported2(std::string_view extension)
Query whether a file extension is supported.
Definition: libopenmpt.hpp:130
Probe for no formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:296
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...
LIBOPENMPT_CXX_API std::uint32_t get_core_version()
Get the core version number.
An answer could not be determined with the amount of data provided.
Definition: libopenmpt.hpp:306
render_param
Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param.
Definition: libopenmpt.hpp:407
probe_file_header_flags
Possible values for openmpt::probe_file_header() flags parameter.
Definition: libopenmpt.hpp:288
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool is_extension_supported(const std::string &extension)
Query whether a file extension is supported.
LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size()
Get recommended header size for successfull format probing.
LIBOPENMPT_CXX_API std::uint32_t get_library_version()
Get the libopenmpt version number.
Definition: libopenmpt_ext.hpp:37
Definition: libopenmpt.hpp:400
Probe for module formats in openmpt::probe_file_header().
Definition: libopenmpt.hpp:290