libopenmpt: libopenmpt/libopenmpt.hpp Source File

libopenmpt 0.5.41-pre.0+r24821 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 exception : public std::exception {
146 private:
147 char * text;
148 public:
149 exception( const std::string & text ) noexcept;
150 exception( const exception & other ) noexcept;
151 exception( exception && other ) noexcept;
152 exception & operator = ( const exception & other ) noexcept;
153 exception & operator = ( exception && other ) noexcept;
154 virtual ~exception() noexcept;
155 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 = 0x1ull;
277
279 static const std::uint64_t probe_file_header_flags_containers = 0x2ull;
280
282 static const std::uint64_t probe_file_header_flags_default = probe_file_header_flags_modules | probe_file_header_flags_containers;
283
285 static const std::uint64_t probe_file_header_flags_none = 0x0ull;
286
288 enum probe_file_header_result {
289 probe_file_header_result_success = 1,
290 probe_file_header_result_failure = 0,
291 probe_file_header_result_wantmoredata = -1
292 };
293
295
309 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size, std::uint64_t filesize );
311
325 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size, std::uint64_t filesize );
326
328
342 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::byte * data, std::size_t size );
344
358 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size );
359
361
373 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, std::istream & stream );
374
375 class module_impl;
376
377 class module_ext;
378
379 namespace detail {
380
381 typedef std::map< std::string, std::string > initial_ctls_map;
382
383 } // namespace detail
384
385 class LIBOPENMPT_CXX_API module {
386
387 friend class module_ext;
388
389 public:
390
392 enum render_param {
394
399 RENDER_MASTERGAIN_MILLIBEL = 1,
401
406 RENDER_STEREOSEPARATION_PERCENT = 2,
408
419 RENDER_INTERPOLATIONFILTER_LENGTH = 3,
421
428 RENDER_VOLUMERAMPING_STRENGTH = 4
429 };
430
432 enum command_index {
433 command_note = 0,
434 command_instrument = 1,
435 command_volumeffect = 2,
436 command_effect = 3,
437 command_volume = 4,
438 command_parameter = 5
439 };
440
441 private:
442 module_impl * impl;
443 private:
444 // non-copyable
445 module( const module & );
446 void operator = ( const module & );
447 private:
448 // for module_ext
449 module();
450 void set_impl( module_impl * i );
451 public:
453
461 module( std::istream & stream, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
471 module( const std::vector<std::byte> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
482 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() );
493 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() );
502 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() );
512 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() );
522 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() );
531 module( const std::vector<char> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
541 module( const char * beg, const char * end, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() );
551 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() );
561 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() );
562 virtual ~module();
563 public:
564
566
572 void select_subsong( std::int32_t subsong );
574
579 std::int32_t get_selected_subsong() const;
581
588 void set_repeat_count( std::int32_t repeat_count );
590
597 std::int32_t get_repeat_count() const;
598
600
603 double get_duration_seconds() const;
604
606
611 double set_position_seconds( double seconds );
613
617 double get_position_seconds() const;
618
620
628 double set_position_order_row( std::int32_t order, std::int32_t row );
629
631
638 std::int32_t get_render_param( int param ) const;
640
647 void set_render_param( int param, std::int32_t value );
648
650
662 std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * mono );
664
676 std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * left, std::int16_t * right );
678
692 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 );
694
705 std::size_t read( std::int32_t samplerate, std::size_t count, float * mono );
707
719 std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right );
721
735 std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right, float * rear_left, float * rear_right );
737
748 std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_stereo );
750
761 std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_quad );
763
774 std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, float * interleaved_stereo );
776
787 std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, float * interleaved_quad );
790
795 std::vector<std::string> get_metadata_keys() const;
797
816 std::string get_metadata( const std::string & key ) const;
817
819
824 double get_current_estimated_bpm() const;
826
829 std::int32_t get_current_speed() const;
831
834 std::int32_t get_current_tempo() const;
836
839 std::int32_t get_current_order() const;
841
844 std::int32_t get_current_pattern() const;
846
849 std::int32_t get_current_row() const;
851
854 std::int32_t get_current_playing_channels() const;
855
857
862 float get_current_channel_vu_mono( std::int32_t channel ) const;
864
869 float get_current_channel_vu_left( std::int32_t channel ) const;
871
876 float get_current_channel_vu_right( std::int32_t channel ) const;
878
883 float get_current_channel_vu_rear_left( std::int32_t channel ) const;
885
890 float get_current_channel_vu_rear_right( std::int32_t channel ) const;
891
893
897 std::int32_t get_num_subsongs() const;
899
903 std::int32_t get_num_channels() const;
905
908 std::int32_t get_num_orders() const;
910
913 std::int32_t get_num_patterns() const;
915
918 std::int32_t get_num_instruments() const;
920
923 std::int32_t get_num_samples() const;
924
926
930 std::vector<std::string> get_subsong_names() const;
932
936 std::vector<std::string> get_channel_names() const;
938
942 std::vector<std::string> get_order_names() const;
944
948 std::vector<std::string> get_pattern_names() const;
950
954 std::vector<std::string> get_instrument_names() const;
956
960 std::vector<std::string> get_sample_names() const;
961
963
967 std::int32_t get_order_pattern( std::int32_t order ) const;
968
970
974 std::int32_t get_pattern_num_rows( std::int32_t pattern ) const;
975
977
984 std::uint8_t get_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
985
987
995 std::string format_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
996
998
1017 std::string highlight_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const;
1018
1020
1029 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;
1031
1040 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;
1041
1043
1073 std::vector<std::string> get_ctls() const;
1074
1076
1082 LIBOPENMPT_ATTR_DEPRECATED std::string ctl_get( const std::string & ctl ) const;
1084
1090 bool ctl_get_boolean( std::string_view ctl ) const;
1092
1098 std::int64_t ctl_get_integer( std::string_view ctl ) const;
1100
1106 double ctl_get_floatingpoint( std::string_view ctl ) const;
1108
1114 std::string ctl_get_text( std::string_view ctl ) const;
1115
1117
1124 LIBOPENMPT_ATTR_DEPRECATED void ctl_set( const std::string & ctl, const std::string & value );
1126
1133 void ctl_set_boolean( std::string_view ctl, bool value );
1135
1142 void ctl_set_integer( std::string_view ctl, std::int64_t value );
1144
1151 void ctl_set_floatingpoint( std::string_view ctl, double value );
1153
1160 void ctl_set_text( std::string_view ctl, std::string_view value );
1161
1162 // remember to add new functions to both C and C++ interfaces and to increase OPENMPT_API_VERSION_MINOR
1163
1164 }; // class module
1165
1170 } // namespace openmpt
1171
1172 #endif // LIBOPENMPT_HPP
openmpt::probe_file_header_result_failure
Definition: libopenmpt.hpp:290
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::command_index
command_index
Parameter index to use with openmpt::module::get_pattern_row_channel_command, openmpt::module::format...
Definition: libopenmpt.hpp:432
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:179
openmpt::probe_file_header_result
probe_file_header_result
Possible return values for openmpt::probe_file_header().
Definition: libopenmpt.hpp:288
openmpt::probe_file_header
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...
openmpt::probe_file_header_result_success
Definition: libopenmpt.hpp:289
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:276
openmpt::get_supported_extensions
LIBOPENMPT_CXX_API std::vector< std::string > get_supported_extensions()
Get a list of supported file extensions.
openmpt::exception
libopenmpt exception base class
Definition: libopenmpt.hpp:145
openmpt::is_extension_supported2
LIBOPENMPT_CXX_API bool is_extension_supported2(std::string_view extension)
Query whether a file extension is supported.
openmpt
Definition: libopenmpt.hpp:130
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:279
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:282
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:285
libopenmpt_config.h
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::get_core_version
LIBOPENMPT_CXX_API std::uint32_t get_core_version()
Get the core version number.
openmpt::probe_file_header_result_wantmoredata
Definition: libopenmpt.hpp:291
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:392
openmpt::is_extension_supported
LIBOPENMPT_ATTR_DEPRECATED LIBOPENMPT_CXX_API bool is_extension_supported(const std::string &extension)
Query whether a file extension is supported.
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::get_library_version
LIBOPENMPT_CXX_API std::uint32_t get_library_version()
Get the libopenmpt version number.
openmpt::module_ext
Definition: libopenmpt_ext.hpp:37
openmpt::module
Definition: libopenmpt.hpp:385