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 24 /*! 25 * \page libopenmpt_cpp_overview C++ API 26 * 27 * \section libopenmpt_cpp_error Error Handling 28 * 29 * libopenmpt C++ uses C++ exception handling for errror reporting. 30 * 31 * Unless otherwise noted, any libopenmpt function may throw exceptions and 32 * all exceptions thrown by libopenmpt itself are derived from 33 * openmpt::exception. 34 * In addition, any libopenmpt function may also throw any exception specified 35 * by the C++ language and C++ standard library. These are all derived from 36 * std::exception. 37 * 38 * \section libopenmpt_cpp_strings Strings 39 * 40 * - All strings returned from libopenmpt are encoded in UTF-8. 41 * - All strings passed to libopenmpt should also be encoded in UTF-8. 42 * Behaviour in case of invalid UTF-8 is unspecified. 43 * - libopenmpt does not enforce or expect any particular Unicode 44 * normalization form. 45 * 46 * \section libopenmpt_cpp_fileio File I/O 47 * 48 * libopenmpt can use 3 different strategies for file I/O. 49 * 50 * - openmpt::module::module() with any kind of memory buffer as parameter will 51 * load the module from the provided memory buffer, which will require loading 52 * all data upfront by the library 53 * caller. 54 * - openmpt::module::module() with a seekable std::istream as parameter will 55 * load the module via the stream interface. libopenmpt will not implement an 56 * additional buffering layer in this case whih means the callbacks are assumed 57 * to be performant even with small i/o sizes. 58 * - openmpt::module::module() with an unseekable std::istream as parameter 59 * will load the module via the stream interface. libopempt will make an 60 * internal copy as it goes along, and sometimes have to pre-cache the whole 61 * file in case it needs to know the complete file size. This strategy is 62 * intended to be used if the file is located on a high latency network. 63 * 64 * | constructor | speed | memory consumption | 65 * | ----------------: | :----: | :----------------: | 66 * | memory buffer | <p style="background-color:green" >fast </p> | <p style="background-color:yellow">medium</p> | 67 * | seekable stream | <p style="background-color:red" >slow </p> | <p style="background-color:green" >low </p> | 68 * | unseekable stream | <p style="background-color:yellow">medium</p> | <p style="background-color:red" >high </p> | 69 * 70 * In all cases, the data or stream passed to the constructor is no longer 71 * needed after the openmpt::module has been constructed and can be destroyed 72 * by the caller. 73 * 74 * \section libopenmpt_cpp_outputformat Output Format 75 * 76 * libopenmpt supports a wide range of PCM output formats: 77 * [8000..192000]/[mono|stereo|quad]/[f32|i16]. 78 * 79 * Unless you have some very specific requirements demanding a particular aspect 80 * of the output format, you should always prefer 48000/stereo/f32 as the 81 * libopenmpt PCM format. 82 * 83 * - Please prefer 48000Hz unless the user explicitly demands something else. 84 * Practically all audio equipment and file formats use 48000Hz nowadays. 85 * - Practically all module formats are made for stereo output. Mono will not 86 * give you any measurable speed improvements and can trivially be obtained from 87 * the stereo output anyway. Quad is not expected by almost all modules and even 88 * if they do use surround effects, they expect the effects to be mixed to 89 * stereo. 90 * - Floating point output provides headroom instead of hard clipping if the 91 * module is louder than 0dBFs, will give you a better signal-to-noise ratio 92 * than int16 output, and avoid the need to apply an additional dithering to the 93 * output by libopenmpt. Unless your platform has no floating point unit at all, 94 * floating point will thus also be slightly faster. 95 * 96 * \section libopenmpt_cpp_threads libopenmpt in multi-threaded environments 97 * 98 * - libopenmpt is thread-aware. 99 * - Individual libopenmpt objects are not thread-safe. 100 * - libopenmpt itself does not spawn any user-visible threads but may spawn 101 * threads for internal use. 102 * - You must ensure to only ever access a particular libopenmpt object via 103 * non-const member functions from a single thread at a time. 104 * - You may access a particular libopenmpt objects concurrently from different 105 * threads when using only const member functions from all threads. 106 * - Consecutive accesses can happen from different threads. 107 * - Different objects can be accessed concurrently from different threads. 108 * 109 * \section libopenmpt-cpp-windows Windows support 110 * 111 * Using the libopenmpt C++ API when libopenmpt is compiled as a DLL on Windows 112 * requires `#define LIBOPENMPT_USE_DLL` (or some equivalent build system 113 * configuration) before `#include <libopenmpt/libopenmpt.hpp>` in order to 114 * correctly import the symbols from the DLL. 115 * 116 * \section libopenmpt-cpp-detailed Detailed documentation 117 * 118 * \ref libopenmpt_cpp 119 * 120 * \section libopenmpt_cpp_examples Example 121 * 122 * \include libopenmpt_example_cxx.cpp 123 * 124 */ 125 126 /*! \defgroup libopenmpt_cpp libopenmpt C++ */ 127 128 /*! \addtogroup libopenmpt_cpp 129 @{ 130 */ 131 132 namespace openmpt { 133 134 #if defined(_MSC_VER) 135 #pragma warning(push) 136 #pragma warning(disable:4275) 137 #endif 138 //! libopenmpt exception base class 139 /*! 140 Base class used for all exceptions that are thrown by libopenmpt itself. Libopenmpt may additionally throw any exception thrown by the standard library which are all derived from std::exception. 141 \sa \ref libopenmpt_cpp_error 142 */ 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 159 //! Get the libopenmpt version number 160 /*! 161 Returns the libopenmpt version number. 162 \return The value represents (major << 24 + minor << 16 + patch << 0). 163 \remarks libopenmpt < 0.3.0-pre used the following scheme: (major << 24 + minor << 16 + revision). 164 */ 165 LIBOPENMPT_CXX_API std::uint32_t get_library_version(); 166 167 //! Get the core version number 168 /*! 169 Return the OpenMPT core version number. 170 \return The value represents (majormajor << 24 + major << 16 + minor << 8 + minorminor). 171 */ 172 LIBOPENMPT_CXX_API std::uint32_t get_core_version(); 173 174 namespace string { 175 176 //! Return a verbose library version string from openmpt::string::get(). \deprecated Please use `"library_version"` directly. 177 LIBOPENMPT_DEPRECATED static const char library_version LIBOPENMPT_ATTR_DEPRECATED [] = "library_version"; 178 //! Return a verbose library features string from openmpt::string::get(). \deprecated Please use `"library_features"` directly. 179 LIBOPENMPT_DEPRECATED static const char library_features LIBOPENMPT_ATTR_DEPRECATED [] = "library_features"; 180 //! Return a verbose OpenMPT core version string from openmpt::string::get(). \deprecated Please use `"core_version"` directly. 181 LIBOPENMPT_DEPRECATED static const char core_version LIBOPENMPT_ATTR_DEPRECATED [] = "core_version"; 182 //! Return information about the current build (e.g. the build date or compiler used) from openmpt::string::get(). \deprecated Please use `"build"` directly. 183 LIBOPENMPT_DEPRECATED static const char build LIBOPENMPT_ATTR_DEPRECATED [] = "build"; 184 //! Return all contributors from openmpt::string::get(). \deprecated Please use `"credits"` directly. 185 LIBOPENMPT_DEPRECATED static const char credits LIBOPENMPT_ATTR_DEPRECATED [] = "credits"; 186 //! Return contact information about libopenmpt from openmpt::string::get(). \deprecated Please use `"contact"` directly. 187 LIBOPENMPT_DEPRECATED static const char contact LIBOPENMPT_ATTR_DEPRECATED [] = "contact"; 188 //! Return the libopenmpt license from openmpt::string::get(). \deprecated Please use `"license"` directly. 189 LIBOPENMPT_DEPRECATED static const char license LIBOPENMPT_ATTR_DEPRECATED [] = "license"; 190 191 //! Get library related metadata. 192 /*! 193 \param key Key to query. 194 Possible keys are: 195 - "library_version": verbose library version string 196 - "library_version_major": libopenmpt major version number 197 - "library_version_minor": libopenmpt minor version number 198 - "library_version_patch": libopenmpt patch version number 199 - "library_version_prerel": libopenmpt pre-release version string 200 - "library_version_is_release": "1" if the version is an officially released version 201 - "library_features": verbose library features string 202 - "core_version": verbose OpenMPT core version string 203 - "source_url": original source code URL 204 - "source_date": original source code date 205 - "source_revision": original source code revision 206 - "source_is_modified": "1" if the original source has been modified 207 - "source_has_mixed_revisions": "1" if the original source has been compiled from different various revision 208 - "source_is_package": "1" if the original source has been obtained from a source pacakge instead of source code version control 209 - "build": information about the current build (e.g. the build date or compiler used) 210 - "build_compiler": information about the compiler used to build libopenmpt 211 - "credits": all contributors 212 - "contact": contact information about libopenmpt 213 - "license": the libopenmpt license 214 - "url": libopenmpt website URL 215 - "support_forum_url": libopenmpt support and discussions forum URL 216 - "bugtracker_url": libopenmpt bug and issue tracker URL 217 218 \return A (possibly multi-line) string containing the queried information. If no information is available, the string is empty. 219 */ 220 LIBOPENMPT_CXX_API std::string get( const std::string & key ); 221 222 } // namespace string 223 224 //! Get a list of supported file extensions 225 /*! 226 \return The list of extensions supported by this libopenmpt build. The extensions are returned lower-case without a leading dot. 227 */ 228 LIBOPENMPT_CXX_API std::vector<std::string> get_supported_extensions(); 229 230 //! Query whether a file extension is supported 231 /*! 232 \param extension file extension to query without a leading dot. The case is ignored. 233 \return true if the extension is supported by libopenmpt, false otherwise. 234 */ 235 LIBOPENMPT_CXX_API bool is_extension_supported( const std::string & extension ); 236 237 //! Roughly scan the input stream to find out whether libopenmpt might be able to open it 238 /*! 239 \param stream Input stream to scan. 240 \param effort Effort to make when validating stream. Effort 0.0 does not even look at stream at all and effort 1.0 completely loads the file from stream. A lower effort requires less data to be loaded but only gives a rough estimate answer. Use an effort of 0.25 to only verify the header data of the module file. 241 \param log Log where warning and errors are written. 242 \return Probability between 0.0 and 1.0. 243 \remarks openmpt::probe_file_header() provides a simpler and faster interface that fits almost all use cases better. It is recommended to use openmpt::probe_file_header() instead of openmpt::could_open_probability(). 244 \remarks openmpt::could_open_probability() can return any value between 0.0 and 1.0. Only 0.0 and 1.0 are definitive answers, all values in between are just estimates. In general, any return value >0.0 means that you should try loading the file, and any value below 1.0 means that loading may fail. If you want a threshold above which you can be reasonably sure that libopenmpt will be able to load the file, use >=0.5. If you see the need for a threshold below which you could reasonably outright reject a file, use <0.25 (Note: Such a threshold for rejecting on the lower end is not recommended, but may be required for better integration into some other framework's probe scoring.). 245 \remarks openmpt::could_open_probability() expects the complete file data to be eventually available to it, even if it is asked to just parse the header. Verification will be unreliable (both false positives and false negatives), if you pretend that the file is just some few bytes of initial data threshold in size. In order to really just access the first bytes of a file, check in your std::istream implementation whether data or seeking is requested beyond your initial data threshold, and in that case, return an error. openmpt::could_open_probability() will treat this as any other I/O error and return 0.0. You must not expect the correct result in this case. You instead must remember that it asked for more data than you currently want to provide to it and treat this situation as if openmpt::could_open_probability() returned 0.5. 246 \sa \ref libopenmpt_c_fileio 247 \sa openmpt::probe_file_header() 248 \since 0.3.0 249 */ 250 LIBOPENMPT_CXX_API double could_open_probability( std::istream & stream, double effort = 1.0, std::ostream & log = std::clog ); 251 252 //! Roughly scan the input stream to find out whether libopenmpt might be able to open it 253 /*! 254 \deprecated Please use openmpt::module::could_open_probability(). 255 */ 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 258 //! Get recommended header size for successfull format probing 259 /*! 260 \sa openmpt::probe_file_header() 261 \since 0.3.0 262 */ 263 LIBOPENMPT_CXX_API std::size_t probe_file_header_get_recommended_size(); 264 265 //! Probe for module formats in openmpt::probe_file_header(). \since 0.3.0 266 static const std::uint64_t probe_file_header_flags_modules = 0x1ul; 267 268 //! Probe for module-specific container formats in openmpt::probe_file_header(). \since 0.3.0 269 static const std::uint64_t probe_file_header_flags_containers = 0x2ul; 270 271 //! Probe for the default set of formats in openmpt::probe_file_header(). \since 0.3.0 272 static const std::uint64_t probe_file_header_flags_default = probe_file_header_flags_modules | probe_file_header_flags_containers; 273 274 //! Probe for no formats in openmpt::probe_file_header(). \since 0.3.0 275 static const std::uint64_t probe_file_header_flags_none = 0x0ul; 276 277 //! Possible return values for openmpt::probe_file_header(). \since 0.3.0 278 enum probe_file_header_result { 279 probe_file_header_result_success = 1, 280 probe_file_header_result_failure = 0, 281 probe_file_header_result_wantmoredata = -1 282 }; 283 284 //! Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it 285 /*! 286 \param flags Ored mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default. 287 \param data Beginning of the file data. 288 \param size Size of the beginning of the file data. 289 \param filesize Full size of the file data on disk. 290 \remarks It is recommended to provide openmpt::probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size and filesize to the file's size. 291 \remarks openmpt::could_open_probability() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt::probe_file_header() though, if possible. 292 \retval probe_file_header_result_success The file will most likely be supported by libopenmpt. 293 \retval probe_file_header_result_failure The file is not supported by libopenmpt. 294 \retval probe_file_header_result_wantmoredata An answer could not be determined with the amount of data provided. 295 \sa openmpt::probe_file_header_get_recommended_size() 296 \sa openmpt::could_open_probability() 297 \since 0.3.0 298 */ 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 301 //! Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it 302 /*! 303 \param flags Ored mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default. 304 \param data Beginning of the file data. 305 \param size Size of the beginning of the file data. 306 \remarks It is recommended to use the overload of this function that also takes the filesize as parameter if at all possile. libopenmpt can provide more accurate answers if the filesize is known. 307 \remarks It is recommended to provide openmpt::probe_file_header_get_recommended_size() bytes of data for data and size. If the file is smaller, only provide the filesize amount and set size to the file's size. 308 \remarks openmpt::could_open_probability() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt::probe_file_header() though, if possible. 309 \retval probe_file_header_result_success The file will most likely be supported by libopenmpt. 310 \retval probe_file_header_result_failure The file is not supported by libopenmpt. 311 \retval probe_file_header_result_wantmoredata An answer could not be determined with the amount of data provided. 312 \sa openmpt::probe_file_header_get_recommended_size() 313 \sa openmpt::could_open_probability() 314 \since 0.3.0 315 */ 316 LIBOPENMPT_CXX_API int probe_file_header( std::uint64_t flags, const std::uint8_t * data, std::size_t size ); 317 318 //! Probe the provided bytes from the beginning of a file for supported file format headers to find out whether libopenmpt might be able to open it 319 /*! 320 \param flags Ored mask of openmpt::probe_file_header_flags_modules and openmpt::probe_file_header_flags_containers, or openmpt::probe_file_header_flags_default. 321 \param stream Input stream to scan. 322 \remarks stream is left in an unspecified state when this function returns. 323 \remarks openmpt::could_open_probability() provides a more elaborate interface that might be required for special use cases. It is recommended to use openmpt::probe_file_header() though, if possible. 324 \retval probe_file_header_result_success The file will most likely be supported by libopenmpt. 325 \retval probe_file_header_result_failure The file is not supported by libopenmpt. 326 \retval probe_file_header_result_wantmoredata An answer could not be determined with the amount of data provided. 327 \sa openmpt::probe_file_header_get_recommended_size() 328 \sa openmpt::could_open_probability() 329 \since 0.3.0 330 */ 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 349 //! Parameter index to use with openmpt::module::get_render_param and openmpt::module::set_render_param 350 enum render_param { 351 //! Master Gain 352 /*! 353 The related value represents a relative gain in milliBel.\n 354 The default value is 0.\n 355 The supported value range is unlimited.\n 356 */ 357 RENDER_MASTERGAIN_MILLIBEL = 1, 358 //! Stereo Separation 359 /*! 360 The related value represents the stereo separation generated by the libopenmpt mixer in percent.\n 361 The default value is 100.\n 362 The supported value range is [0,200].\n 363 */ 364 RENDER_STEREOSEPARATION_PERCENT = 2, 365 //! Interpolation Filter 366 /*! 367 The related value represents the interpolation filter length used by the libopenmpt mixer.\n 368 The default value is 0, which indicates a recommended default value.\n 369 The supported value range is [0,inf). Values greater than the implementation limit are clamped to the maximum supported value.\n 370 Currently supported values: 371 - 0: internal default 372 - 1: no interpolation (zero order hold) 373 - 2: linear interpolation 374 - 4: cubic interpolation 375 - 8: windowed sinc with 8 taps 376 */ 377 RENDER_INTERPOLATIONFILTER_LENGTH = 3, 378 //! Volume Ramping Strength 379 /*! 380 The related value represents the amount of volume ramping done by the libopenmpt mixer.\n 381 The default value is -1, which indicates a recommended default value.\n 382 The meaningful value range is [-1..10].\n 383 A value of 0 completely disables volume ramping. This might cause clicks in sound output.\n 384 Higher values imply slower/softer volume ramps. 385 */ 386 RENDER_VOLUMERAMPING_STRENGTH = 4 387 }; 388 389 //! 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 390 enum command_index { 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: 410 //! Construct an openmpt::module 411 /*! 412 \param stream Input 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. 413 \param log Log 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. 414 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 415 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 416 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 417 \sa \ref libopenmpt_cpp_fileio 418 */ 419 module( std::istream & stream, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() ); 420 /*! 421 \param data Data to load the module from. 422 \param log Log 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. 423 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 424 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 425 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 426 \sa \ref libopenmpt_cpp_fileio 427 */ 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() ); 429 /*! 430 \param beg Begin of data to load the module from. 431 \param end End of data to load the module from. 432 \param log Log 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. 433 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 434 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 435 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 436 \sa \ref libopenmpt_cpp_fileio 437 */ 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() ); 439 /*! 440 \param data Data to load the module from. 441 \param size Amount of data available. 442 \param log Log 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. 443 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 444 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 445 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 446 \sa \ref libopenmpt_cpp_fileio 447 */ 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() ); 449 /*! 450 \param data Data to load the module from. 451 \param log Log 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. 452 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 453 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 454 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 455 \sa \ref libopenmpt_cpp_fileio 456 */ 457 module( const std::vector<char> & data, std::ostream & log = std::clog, const std::map< std::string, std::string > & ctls = detail::initial_ctls_map() ); 458 /*! 459 \param beg Begin of data to load the module from. 460 \param end End of data to load the module from. 461 \param log Log 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. 462 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 463 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 464 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 465 \sa \ref libopenmpt_cpp_fileio 466 */ 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() ); 468 /*! 469 \param data Data to load the module from. 470 \param size Amount of data available. 471 \param log Log 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. 472 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 473 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 474 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 475 \sa \ref libopenmpt_cpp_fileio 476 */ 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() ); 478 /*! 479 \param data Data to load the module from. 480 \param size Amount of data available. 481 \param log Log 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. 482 \param ctls A map of initial ctl values, see openmpt::module::get_ctls. 483 \throws openmpt::exception Throws an exception derived from openmpt::exception in case the provided file cannot be opened. 484 \remarks The input data can be discarded after an openmpt::module has been constructed successfully. 485 \sa \ref libopenmpt_cpp_fileio 486 */ 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 491 //! Select a sub-song from a multi-song module 492 /*! 493 \param subsong Index of the sub-song. -1 plays all sub-songs consecutively. 494 \throws openmpt::exception Throws an exception derived from openmpt::exception if sub-song is not in range [-1,openmpt::module::get_num_subsongs()[ 495 \sa openmpt::module::get_num_subsongs, openmpt::module::get_selected_subsong, openmpt::module::get_subsong_names 496 \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. 497 */ 498 void select_subsong( std::int32_t subsong ); 499 //! Get currently selected sub-song from a multi-song module 500 /*! 501 \return Currently selected sub-song. -1 for all subsongs consecutively, 0 or greater for the current sub-song index. 502 \sa openmpt::module::get_num_subsongs, openmpt::module::select_subsong, openmpt::module::get_subsong_names 503 \since 0.3.0 504 */ 505 std::int32_t get_selected_subsong() const; 506 //! Set Repeat Count 507 /*! 508 \param repeat_count Repeat Count 509 - -1: repeat forever 510 - 0: play once, repeat zero times (the default) 511 - n>0: play once and repeat n times after that 512 \sa openmpt::module::get_repeat_count 513 */ 514 void set_repeat_count( std::int32_t repeat_count ); 515 //! Get Repeat Count 516 /*! 517 \return Repeat Count 518 - -1: repeat forever 519 - 0: play once, repeat zero times (the default) 520 - n>0: play once and repeat n times after that 521 \sa openmpt::module::set_repeat_count 522 */ 523 std::int32_t get_repeat_count() const; 524 525 //! Get approximate song duration 526 /*! 527 \return Approximate duration of current sub-song in seconds. 528 */ 529 double get_duration_seconds() const; 530 531 //! Set approximate current song position 532 /*! 533 \param seconds Seconds to seek to. If seconds is out of range, the position gets set to song start or end respectively. 534 \return Approximate new song position in seconds. 535 \sa openmpt::module::get_position_seconds 536 */ 537 double set_position_seconds( double seconds ); 538 //! Get current song position 539 /*! 540 \return Current song position in seconds. 541 \sa openmpt::module::set_position_seconds 542 */ 543 double get_position_seconds() const; 544 545 //! Set approximate current song position 546 /*! 547 If order or row are out of range, to position is not modified and the current position is returned. 548 \param order Pattern order number to seek to. 549 \param row Pattern row number to seek to. 550 \return Approximate new song position in seconds. 551 \sa openmpt::module::set_position_seconds 552 \sa openmpt::module::get_position_seconds 553 */ 554 double set_position_order_row( std::int32_t order, std::int32_t row ); 555 556 //! Get render parameter 557 /*! 558 \param param Parameter to query. See openmpt::module::render_param. 559 \return The current value of the parameter. 560 \throws openmpt::exception Throws an exception derived from openmpt::exception if param is invalid. 561 \sa openmpt::module::render_param 562 \sa openmpt::module::set_render_param 563 */ 564 std::int32_t get_render_param( int param ) const; 565 //! Set render parameter 566 /*! 567 \param param Parameter to set. See openmpt::module::render_param. 568 \param value The value to set param to. 569 \throws openmpt::exception Throws an exception derived from openmpt::exception if param is invalid or value is out of range. 570 \sa openmpt::module::render_param 571 \sa openmpt::module::get_render_param 572 */ 573 void set_render_param( int param, std::int32_t value ); 574 575 /*@{*/ 576 //! Render audio data 577 /*! 578 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 579 \param count Number of audio frames to render per channel. 580 \param mono Pointer to a buffer of at least count elements that receives the mono/center output. 581 \return The number of frames actually rendered. 582 \retval 0 The end of song has been reached. 583 \remarks The output buffers are only written to up to the returned number of elements. 584 \remarks 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. 585 \remarks It is recommended to use the floating point API because of the greater dynamic range and no implied clipping. 586 \sa \ref libopenmpt_cpp_outputformat 587 */ 588 std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * mono ); 589 //! Render audio data 590 /*! 591 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 592 \param count Number of audio frames to render per channel. 593 \param left Pointer to a buffer of at least count elements that receives the left output. 594 \param right Pointer to a buffer of at least count elements that receives the right output. 595 \return The number of frames actually rendered. 596 \retval 0 The end of song has been reached. 597 \remarks The output buffers are only written to up to the returned number of elements. 598 \remarks 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. 599 \remarks It is recommended to use the floating point API because of the greater dynamic range and no implied clipping. 600 \sa \ref libopenmpt_cpp_outputformat 601 */ 602 std::size_t read( std::int32_t samplerate, std::size_t count, std::int16_t * left, std::int16_t * right ); 603 //! Render audio data 604 /*! 605 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 606 \param count Number of audio frames to render per channel. 607 \param left Pointer to a buffer of at least count elements that receives the left output. 608 \param right Pointer to a buffer of at least count elements that receives the right output. 609 \param rear_left Pointer to a buffer of at least count elements that receives the rear left output. 610 \param rear_right Pointer to a buffer of at least count elements that receives the rear right output. 611 \return The number of frames actually rendered. 612 \retval 0 The end of song has been reached. 613 \remarks The output buffers are only written to up to the returned number of elements. 614 \remarks 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. 615 \remarks It is recommended to use the floating point API because of the greater dynamic range and no implied clipping. 616 \sa \ref libopenmpt_cpp_outputformat 617 */ 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 ); 619 //! Render audio data 620 /*! 621 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 622 \param count Number of audio frames to render per channel. 623 \param mono Pointer to a buffer of at least count elements that receives the mono/center output. 624 \return The number of frames actually rendered. 625 \retval 0 The end of song has been reached. 626 \remarks The output buffers are only written to up to the returned number of elements. 627 \remarks 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. 628 \remarks Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot. 629 \sa \ref libopenmpt_cpp_outputformat 630 */ 631 std::size_t read( std::int32_t samplerate, std::size_t count, float * mono ); 632 //! Render audio data 633 /*! 634 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 635 \param count Number of audio frames to render per channel. 636 \param left Pointer to a buffer of at least count elements that receives the left output. 637 \param right Pointer to a buffer of at least count elements that receives the right output. 638 \return The number of frames actually rendered. 639 \retval 0 The end of song has been reached. 640 \remarks The output buffers are only written to up to the returned number of elements. 641 \remarks 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. 642 \remarks Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot. 643 \sa \ref libopenmpt_cpp_outputformat 644 */ 645 std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right ); 646 //! Render audio data 647 /*! 648 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 649 \param count Number of audio frames to render per channel. 650 \param left Pointer to a buffer of at least count elements that receives the left output. 651 \param right Pointer to a buffer of at least count elements that receives the right output. 652 \param rear_left Pointer to a buffer of at least count elements that receives the rear left output. 653 \param rear_right Pointer to a buffer of at least count elements that receives the rear right output. 654 \return The number of frames actually rendered. 655 \retval 0 The end of song has been reached. 656 \remarks The output buffers are only written to up to the returned number of elements. 657 \remarks 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. 658 \remarks Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot. 659 \sa \ref libopenmpt_cpp_outputformat 660 */ 661 std::size_t read( std::int32_t samplerate, std::size_t count, float * left, float * right, float * rear_left, float * rear_right ); 662 //! Render audio data 663 /*! 664 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 665 \param count Number of audio frames to render per channel. 666 \param interleaved_stereo Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R). 667 \return The number of frames actually rendered. 668 \retval 0 The end of song has been reached. 669 \remarks The output buffers are only written to up to the returned number of elements. 670 \remarks 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. 671 \remarks It is recommended to use the floating point API because of the greater dynamic range and no implied clipping. 672 \sa \ref libopenmpt_cpp_outputformat 673 */ 674 std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_stereo ); 675 //! Render audio data 676 /*! 677 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 678 \param count Number of audio frames to render per channel. 679 \param interleaved_quad Pointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR). 680 \return The number of frames actually rendered. 681 \retval 0 The end of song has been reached. 682 \remarks The output buffers are only written to up to the returned number of elements. 683 \remarks 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. 684 \remarks It is recommended to use the floating point API because of the greater dynamic range and no implied clipping. 685 \sa \ref libopenmpt_cpp_outputformat 686 */ 687 std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, std::int16_t * interleaved_quad ); 688 //! Render audio data 689 /*! 690 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 691 \param count Number of audio frames to render per channel. 692 \param interleaved_stereo Pointer to a buffer of at least count*2 elements that receives the interleaved stereo output in the order (L,R). 693 \return The number of frames actually rendered. 694 \retval 0 The end of song has been reached. 695 \remarks The output buffers are only written to up to the returned number of elements. 696 \remarks 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. 697 \remarks Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot. 698 \sa \ref libopenmpt_cpp_outputformat 699 */ 700 std::size_t read_interleaved_stereo( std::int32_t samplerate, std::size_t count, float * interleaved_stereo ); 701 //! Render audio data 702 /*! 703 \param samplerate Sample rate to render output. Should be in [8000,192000], but this is not enforced. 704 \param count Number of audio frames to render per channel. 705 \param interleaved_quad Pointer to a buffer of at least count*4 elements that receives the interleaved suad surround output in the order (L,R,RL,RR). 706 \return The number of frames actually rendered. 707 \retval 0 The end of song has been reached. 708 \remarks The output buffers are only written to up to the returned number of elements. 709 \remarks 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. 710 \remarks Floating point samples are in the [-1.0..1.0] nominal range. They are not clipped to that range though and thus might overshoot. 711 \sa \ref libopenmpt_cpp_outputformat 712 */ 713 std::size_t read_interleaved_quad( std::int32_t samplerate, std::size_t count, float * interleaved_quad ); 714 /*@}*/ 715 716 //! Get the list of supported metadata item keys 717 /*! 718 \return Metadata item keys supported by openmpt::module::get_metadata 719 \sa openmpt::module::get_metadata 720 */ 721 std::vector<std::string> get_metadata_keys() const; 722 //! Get a metadata item value 723 /*! 724 \param key Metadata item key to query. Use openmpt::module::get_metadata_keys to check for available keys. 725 Possible keys are: 726 - type: Module format extension (e.g. it) 727 - type_long: Format name associated with the module format (e.g. Impulse Tracker) 728 - 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) 729 - 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) 730 - container: Container format the module file is embedded in, if any (e.g. umx) 731 - container_long: Full container name if the module is embedded in a container (e.g. Unreal Music) 732 - tracker: Tracker that was (most likely) used to save the module file, if known 733 - artist: Author of the module 734 - title: Module title 735 - date: Date the module was last saved, in ISO-8601 format. 736 - 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. 737 - message_raw: Song message. If the song message is empty or the module format does not support song messages, an empty string is returned. 738 - warnings: A list of warnings that were generated while loading the module. 739 \return The associated value for key. 740 \sa openmpt::module::get_metadata_keys 741 */ 742 std::string get_metadata( const std::string & key ) const; 743 744 //! Get the current speed 745 /*! 746 \return The current speed in ticks per row. 747 */ 748 std::int32_t get_current_speed() const; 749 //! Get the current tempo 750 /*! 751 \return The current tempo in tracker units. The exact meaning of this value depends on the tempo mode being used. 752 */ 753 std::int32_t get_current_tempo() const; 754 //! Get the current order 755 /*! 756 \return The current order at which the module is being played back. 757 */ 758 std::int32_t get_current_order() const; 759 //! Get the current pattern 760 /*! 761 \return The current pattern that is being played. 762 */ 763 std::int32_t get_current_pattern() const; 764 //! Get the current row 765 /*! 766 \return The current row at which the current pattern is being played. 767 */ 768 std::int32_t get_current_row() const; 769 //! Get the current amount of playing channels. 770 /*! 771 \return The amount of sample channels that are currently being rendered. 772 */ 773 std::int32_t get_current_playing_channels() const; 774 775 //! Get an approximate indication of the channel volume. 776 /*! 777 \param channel The channel whose volume should be retrieved. 778 \return The approximate channel volume. 779 \remarks The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account. 780 */ 781 float get_current_channel_vu_mono( std::int32_t channel ) const; 782 //! Get an approximate indication of the channel volume on the front-left speaker. 783 /*! 784 \param channel The channel whose volume should be retrieved. 785 \return The approximate channel volume. 786 \remarks The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account. 787 */ 788 float get_current_channel_vu_left( std::int32_t channel ) const; 789 //! Get an approximate indication of the channel volume on the front-right speaker. 790 /*! 791 \param channel The channel whose volume should be retrieved. 792 \return The approximate channel volume. 793 \remarks The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account. 794 */ 795 float get_current_channel_vu_right( std::int32_t channel ) const; 796 //! Get an approximate indication of the channel volume on the rear-left speaker. 797 /*! 798 \param channel The channel whose volume should be retrieved. 799 \return The approximate channel volume. 800 \remarks The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account. 801 */ 802 float get_current_channel_vu_rear_left( std::int32_t channel ) const; 803 //! Get an approximate indication of the channel volume on the rear-right speaker. 804 /*! 805 \param channel The channel whose volume should be retrieved. 806 \return The approximate channel volume. 807 \remarks The returned value is solely based on the note velocity and does not take the actual waveform of the playing sample into account. 808 */ 809 float get_current_channel_vu_rear_right( std::int32_t channel ) const; 810 811 //! Get the number of sub-songs 812 /*! 813 \return 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). 814 \sa openmpt::module::get_subsong_names, openmpt::module::select_subsong, openmpt::module::get_selected_subsong 815 */ 816 std::int32_t get_num_subsongs() const; 817 //! Get the number of pattern channels 818 /*! 819 \return The number of pattern channels in the module. Not all channels do necessarily contain data. 820 \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. 821 */ 822 std::int32_t get_num_channels() const; 823 //! Get the number of orders 824 /*! 825 \return The number of orders in the current sequence of the module. 826 */ 827 std::int32_t get_num_orders() const; 828 //! Get the number of patterns 829 /*! 830 \return The number of distinct patterns in the module. 831 */ 832 std::int32_t get_num_patterns() const; 833 //! Get the number of instruments 834 /*! 835 \return The number of instrument slots in the module. Instruments are a layer on top of samples, and are not supported by all module formats. 836 */ 837 std::int32_t get_num_instruments() const; 838 //! Get the number of samples 839 /*! 840 \return The number of sample slots in the module. 841 */ 842 std::int32_t get_num_samples() const; 843 844 //! Get a list of sub-song names 845 /*! 846 \return All sub-song names. 847 \sa openmpt::module::get_num_subsongs, openmpt::module::select_subsong, openmpt::module::get_selected_subsong 848 */ 849 std::vector<std::string> get_subsong_names() const; 850 //! Get a list of channel names 851 /*! 852 \return All channel names. 853 \sa openmpt::module::get_num_channels 854 */ 855 std::vector<std::string> get_channel_names() const; 856 //! Get a list of order names 857 /*! 858 \return All order names. 859 \sa openmpt::module::get_num_orders 860 */ 861 std::vector<std::string> get_order_names() const; 862 //! Get a list of pattern names 863 /*! 864 \return All pattern names. 865 \sa openmpt::module::get_num_patterns 866 */ 867 std::vector<std::string> get_pattern_names() const; 868 //! Get a list of instrument names 869 /*! 870 \return All instrument names. 871 \sa openmpt::module::get_num_instruments 872 */ 873 std::vector<std::string> get_instrument_names() const; 874 //! Get a list of sample names 875 /*! 876 \return All sample names. 877 \sa openmpt::module::get_num_samples 878 */ 879 std::vector<std::string> get_sample_names() const; 880 881 //! Get pattern at order position 882 /*! 883 \param order The order item whose pattern index should be retrieved. 884 \return The pattern index found at the given order position of the current sequence. 885 */ 886 std::int32_t get_order_pattern( std::int32_t order ) const; 887 888 //! Get the number of rows in a pattern 889 /*! 890 \param pattern The pattern whose row count should be retrieved. 891 \return The number of rows in the given pattern. If the pattern does not exist, 0 is returned. 892 */ 893 std::int32_t get_pattern_num_rows( std::int32_t pattern ) const; 894 895 //! Get raw pattern content 896 /*! 897 \param pattern The pattern whose data should be retrieved. 898 \param row The row from which the data should be retrieved. 899 \param channel The channel from which the data should be retrieved. 900 \param command The cell index at which the data should be retrieved. See openmpt::module::command_index 901 \return The internal, raw pattern data at the given pattern position. 902 */ 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 905 //! Get formatted (human-readable) pattern content 906 /*! 907 \param pattern The pattern whose data should be retrieved. 908 \param row The row from which the data should be retrieved. 909 \param channel The channel from which the data should be retrieved. 910 \param command The cell index at which the data should be retrieved. 911 \return The formatted pattern data at the given pattern position. See openmpt::module::command_index 912 \sa openmpt::module::highlight_pattern_row_channel_command 913 */ 914 std::string format_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const; 915 916 //! Get highlighting information for formatted pattern content 917 /*! 918 \param pattern The pattern whose data should be retrieved. 919 \param row The row from which the data should be retrieved. 920 \param channel The channel from which the data should be retrieved. 921 \param command The cell index at which the data should be retrieved. See openmpt::module::command_index 922 \return The highlighting string for the formatted pattern data as retrieved by openmpt::module::get_pattern_row_channel_command at the given pattern position. 923 \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. 924 Possible highlighting characters are: 925 - " " : empty/space 926 - "." : empty/dot 927 - "n" : generic note 928 - "m" : special note 929 - "i" : generic instrument 930 - "u" : generic volume column effect 931 - "v" : generic volume column parameter 932 - "e" : generic effect column effect 933 - "f" : generic effect column parameter 934 \sa openmpt::module::get_pattern_row_channel_command 935 */ 936 std::string highlight_pattern_row_channel_command( std::int32_t pattern, std::int32_t row, std::int32_t channel, int command ) const; 937 938 //! Get formatted (human-readable) pattern content 939 /*! 940 \param pattern The pattern whose data should be retrieved. 941 \param row The row from which the data should be retrieved. 942 \param channel The channel from which the data should be retrieved. 943 \param width The maximum number of characters the string should contain. 0 means no limit. 944 \param pad If true, the string will be resized to the exact length provided in the width parameter. 945 \return The formatted pattern data at the given pattern position. 946 \sa openmpt::module::highlight_pattern_row_channel 947 */ 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; 949 //! Get highlighting information for formatted pattern content 950 /*! 951 \param pattern The pattern whose data should be retrieved. 952 \param row The row from which the data should be retrieved. 953 \param channel The channel from which the data should be retrieved. 954 \param width The maximum number of characters the string should contain. 0 means no limit. 955 \param pad If true, the string will be resized to the exact length provided in the width parameter. 956 \return The highlighting string for the formatted pattern data as retrieved by openmpt::module::format_pattern_row_channel at the given pattern position. 957 \sa openmpt::module::format_pattern_row_channel 958 */ 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 961 //! Retrieve supported ctl keys 962 /*! 963 \return A vector containing all supported ctl keys. 964 \remarks Currently supported ctl values are: 965 - load.skip_samples: Set to "1" to avoid loading samples into memory 966 - load.skip_patterns: Set to "1" to avoid loading patterns into memory 967 - load.skip_plugins: Set to "1" to avoid loading plugins 968 - load.skip_subsongs_init: Set to "1" to avoid pre-initializing sub-songs. Skipping results in faster module loading but slower seeking. 969 - seek.sync_samples: Set to "1" to sync sample playback when using openmpt::module::set_position_seconds or openmpt::module::set_position_order_row. 970 - subsong: The current subsong. Setting it has identical semantics as openmpt::module::select_subsong(), getting it returns the currently selected subsong. 971 - play.at_end: Chooses the behaviour when the end of song is reached: 972 - "fadeout": Fades the module out for a short while. Subsequent reads after the fadeout will return 0 rendered frames. 973 - "continue": Returns 0 rendered frames when the song end is reached. Subsequent reads will continue playing from the song start or loop start. 974 - "stop": Returns 0 rendered frames when the song end is reached. Subsequent reads will return 0 rendered frames. 975 - play.tempo_factor: Set a floating point tempo factor. "1.0" is the default tempo. 976 - play.pitch_factor: Set a floating point pitch factor. "1.0" is the default pitch. 977 - 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. 978 - render.opl.volume_factor: Set volume factor applied to synthesized OPL sounds, relative to the default OPL volume. 979 - dither: Set the dither algorithm that is used for the 16 bit versions of openmpt::module::read. Supported values are: 980 - 0: No dithering. 981 - 1: Default mode. Chosen by OpenMPT code, might change. 982 - 2: Rectangular, 0.5 bit depth, no noise shaping (original ModPlug Tracker). 983 - 3: Rectangular, 1 bit depth, simple 1st order noise shaping 984 985 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. 986 */ 987 std::vector<std::string> get_ctls() const; 988 989 //! Get current ctl value 990 /*! 991 \param ctl The ctl key whose value should be retrieved. 992 \return The associated ctl value. 993 \sa openmpt::module::get_ctls 994 */ 995 std::string ctl_get( const std::string & ctl ) const; 996 //! Set ctl value 997 /*! 998 \param ctl The ctl key whose value should be set. 999 \param value The value that should be set. 1000 \throws openmpt::exception Throws 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. 1001 \sa openmpt::module::get_ctls 1002 */ 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 1011 /*! 1012 @} 1013 */ 1014 1015 #endif // LIBOPENMPT_HPP 1016