Frees the memory allocated by a call to projectm_alloc_string() or any + * (const) char* pointers returned by a projectM API call.
+ * + *Do not use free() to delete the pointer!
+ * + * @param str A pointer returned by projectm_alloc_string(). + */ +PROJECTM_EXPORT void projectm_free_string(const char* str); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/api/include/libprojectM/parameters.h b/src/api/include/libprojectM/parameters.h new file mode 100644 index 000000000..7f34862be --- /dev/null +++ b/src/api/include/libprojectM/parameters.h @@ -0,0 +1,292 @@ +/** + * @file parameters.h + * @copyright 2003-2023 projectM Team + * @brief Functions to set and retrieve all sorts of projectM parameters and setting. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Sets the texture search paths. + * + * Calling this method will clear and reload all textures, including the main rendering texture. + * Can cause a small delay/lag in rendering. Only use if texture paths were changed. + * + * @param instance The projectM instance handle. + * @param texture_search_paths A list of texture search paths. + * @param count The number of paths in the list. + */ +PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance, + const char** texture_search_paths, + size_t count); + +/** + * @brief Changes the size of the internal render texture. + * @note This will recreate the internal renderer. + * @param instance The projectM instance handle. + * @param size The new size of the render texture. Must be a power of 2. + */ +PROJECTM_EXPORT void projectm_set_texture_size(projectm_handle instance, size_t size); + +/** + * @brief Returns the size of the internal render texture. + * @param instance The projectM instance handle. + * @return The size of the internal rendering texture. + */ +PROJECTM_EXPORT size_t projectm_get_texture_size(projectm_handle instance); + +/** + * @brief Sets the beat sensitivity. + * + * The beat sensitivity to be used. + * + * @param instance The projectM instance handle. + * @param sensitivity The sensitivity setting. + */ +PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, float sensitivity); + +/** + * @brief Returns the beat sensitivity. + * @param instance The projectM instance handle. + * @return The current sensitivity setting. + */ +PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance); + +/** + * @brief Sets the minimum display time before a hard cut can happen. + * + *Hard cuts are beat-sensitive preset transitions, immediately changing from + * one preset to the next without a smooth blending period.
+ * + *Set this to a higher value than preset duration to disable hard cuts.
+ * + * @param instance The projectM instance handle. + * @param seconds Minimum number of seconds the preset will be displayed before a hard cut. + */ +PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, double seconds); + +/** + * @brief Returns the minimum display time before a hard cut can happen. + * @param instance The projectM instance handle. + * @return The minimum number of seconds the preset will be displayed before a hard cut. + */ +PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance); + +/** + * @brief Enables or disables hard cuts. + * + * Even if enabled, the hard cut duration must be set to a value lower than the preset duration + * to work properly. + * + * @param instance The projectM instance handle. + * @param enabled True to enable hard cuts, false to disable. + */ +PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, bool enabled); + +/** + * @brief Returns whether hard cuts are enabled or not. + * @param instance The projectM instance handle. + * @return True if hard cuts are enabled, false otherwise. + */ +PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance); + +/** + * @brief Sets the hard cut volume sensitivity. + * + * The beat detection volume difference that must be surpassed to trigger a hard cut. + * + * @param instance The projectM instance handle. + * @param sensitivity The volume threshold that triggers a hard cut if surpassed. + */ +PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, float sensitivity); + +/** + * @brief Returns the current hard cut sensitivity. + * @param instance The projectM instance handle. + * @return The current hard cut sensitivity. + */ +PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance); + +/** + * @brief Sets the time in seconds for a soft transition between two presets. + * + * During a soft cut, both presets are rendered and slowly transitioned from one + * to the other. + * + * @param instance The projectM instance handle. + * @param seconds Time in seconds it takes to smoothly transition from one preset to another. + */ +PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, double seconds); + +/** + * @brief Returns the time in seconds for a soft transition between two presets. + * @param instance The projectM instance handle. + * @return Time in seconds it takes to smoothly transition from one preset to another. + */ +PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance); + +/** + * @brief Sets the preset display duration before switching to the next using a soft cut. + * + * This can be considered as the maximum time a preset is displayed. If this time is reached, + * a smooth cut will be initiated. A hard cut, if any, will always happen before this time. + * + * @param instance The projectM instance handle. + * @param seconds The number of seconds a preset will be displayed before the next is shown. + */ +PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, double seconds); + +/** + * @brief Returns the preset display duration before switching to the next using a soft cut. + * + * This can be considered as the maximum time a preset is displayed. If this time is reached, + * a smooth cut will be initiated. A hard cut, if any, will always happen before this time. + * + * @param instance The projectM instance handle. + * @return The currently set preset display duration in seconds. + */ +PROJECTM_EXPORT double projectm_get_preset_duration(projectm_handle instance); + +/** + * @brief Sets the per-pixel equation mesh size in units. + * @note This will currently remove any active presets and reload the default "idle" preset. + * @param instance The projectM instance handle. + * @param width The new width of the mesh. + * @param height The new height of the mesh. + */ +PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t width, size_t height); + +/** + * @brief Returns the per-pixel equation mesh size in units. + * @param instance The projectM instance handle. + * @param width The width of the mesh. + * @param height The height of the mesh. + */ +PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* width, size_t* height); + +/** + * @brief Sets the current/average frames per second. + * + * Applications running projectM should UpdateMeshSize this value regularly and set it to the calculated + * (and possibly averaged) FPS value the output rendered with. The value is passed on to presets, + * which may choose to use it for calculations. It is not used in any other way by the library. + * + * @param instance The projectM instance handle. + * @param fps The current FPS value projectM is running with. + */ +PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps); + +/** + * @brief Returns the current/average frames per second. + * + * This value needs to be set by the application. If it wasn't set, a default value of 60 is used. + * + * @param instance The projectM instance handle. + * @return The current/average frames per second. + */ +PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance); + +/** + * @brief Enabled or disables aspect ratio correction in presets that support it. + * + * This sets a flag presets can use to aspect-correct rendered shapes, which otherwise would + * be distorted if the viewport isn't exactly square. + * + * @param instance The projectM instance handle. + * @param enabled True to enable aspect correction, false to disable it. + */ +PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bool enabled); + +/** + * @brief Returns whether aspect ratio correction is enabled or not. + * @param instance The projectM instance handle. + * @return True if aspect ratio correction is enabled, false otherwise. + */ +PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance); + +/** + * @brief Sets the "easter egg" value. + * + *This doesn't enable any fancy feature, it only influences the randomized display time of presets. It's + * passed as the "sigma" value of the gaussian random number generator used to determine the maximum display time, + * effectively multiplying the generated number of seconds by this amount.
+ * + *See function sampledPresetDuration() of the TimeKeeper class on how it is used.
+ * + * @param instance The projectM instance handle. + * @param value The new "easter egg" value. + */ +PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float value); + +/** + * @brief Returns the current "easter egg" value. + * @param instance The projectM instance handle. + * @return The current "easter egg" value. + */ +PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance); + +/** + * @brief Locks or unlocks the current preset. + * + * Locking effectively disables automatic preset transitions, both hard and soft cuts. Programmatic + * preset switches will still be executed. + * + * @param instance The projectM instance handle. + * @param lock True to lock the current preset, false to enable automatic transitions. + */ +PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool lock); + +/** + * @brief Returns whether the current preset is locked or not. + * @param instance The projectM instance handle. + * @return True if the preset lock is enabled, false otherwise. + */ +PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance); + +/** + * @brief Sets the current viewport size in pixels. + * + * Calling this function will reset the OpenGL renderer. + * + * @param instance The projectM instance handle. + * @param width New viewport width in pixels. + * @param height New viewport height in pixels. + */ +PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t width, size_t height); + +/** + * @brief Returns the current viewport size in pixels. + * @param instance The projectM instance handle. + * @param width Valid pointer to a size_t variable that will receive the window width value. + * @param height Valid pointer to a size_t variable that will receive the window height value. + */ +PROJECTM_EXPORT void projectm_get_window_size(projectm_handle instance, size_t* width, size_t* height); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/api/include/libprojectM/projectM.h b/src/api/include/libprojectM/projectM.h index 8b688738d..f474a1b1f 100644 --- a/src/api/include/libprojectM/projectM.h +++ b/src/api/include/libprojectM/projectM.h @@ -1,8 +1,9 @@ /** * @file projectM.h + * @copyright 2003-2023 projectM Team + * @brief Convenience include file that includes all other API headers. * * projectM -- Milkdrop-esque visualisation SDK - * Copyright (C)2003-2021 projectM Team * * This library is free software; you can redistribute it and/or * modify it under the terms of the GNU Lesser General Public @@ -23,579 +24,11 @@ #pragma once -#include "libprojectM/projectM_export.h" - -#includeFrees the memory allocated by a call to projectm_alloc_string() or any - * (const) char* pointers returned by a projectM API call.
- * - *Do not use free() to delete the pointer!
- * - * @param str A pointer returned by projectm_alloc_string(). - */ -PROJECTM_EXPORT void projectm_free_string(const char* str); - -/** - * @brief Callback function that is executed whenever projectM wants to switch to a new preset. - * - * @param is_hard_cut If true, the transition was triggered by a beat-driven event. - * @param user_data A user-defined data pointer that was provided when registering the callback, -* e.g. context information. - */ -typedef void (*projectm_preset_switch_requested_event)(bool is_hard_cut, void* user_data); - -/** - * @brief Callback function that is executed if a preset change failed. - * - * The message and filename pointers are only valid inside the callback. Make a copy if these values - * need to be retained for later use. - * - * @param preset_filename The filename of the failed preset. - * @param message The error message. - * @param user_data A user-defined data pointer that was provided when registering the callback, - * e.g. context information. - */ -typedef void (*projectm_preset_switch_failed_event)(const char* preset_filename, - const char* message, void* user_data); - -/** - * @brief Creates a new projectM instance. - * @return A projectM handle for the newly created instance that must be used in subsequent API calls. - * NULL if the instance could not be created successfully. - */ -PROJECTM_EXPORT projectm_handle projectm_create(); - -/** - * @brief Destroys the given instance and frees the resources. - * - * After destroying the handle, it must not be used for any other calls to the API. - * - * @param instance A handle returned by projectm_create() or projectm_create_settings(). - */ -PROJECTM_EXPORT void projectm_destroy(projectm_handle instance); - -/** - * @brief Loads a preset from the given filename/URL. - * - * Ideally, the filename should be given as a standard local path. projectM also supports loading - * "file://" URLs. Additionally, the special filename "idle://" can be used to load the default - * idle preset, displaying the "M" logo. - * - * Other URL schemas aren't supported and will cause a loading error. - * - * If the preset can't be loaded, no switch takes place and the current preset will continue to - * be displayed. Note that if there's a transition in progress when calling this function, the - * transition will be finished immediately, even if the new preset can't be loaded. - * - * @param instance The projectM instance handle. - * @param filename The preset filename or URL to load. - * @param smooth_transition If true, the new preset is smoothly blended over. - */ -PROJECTM_EXPORT void projectm_load_preset_file(projectm_handle instance, const char* filename, - bool smooth_transition); - -/** - * @brief Loads a preset from the data pointer. - * - * Currently, the preset data is assumed to be in Milkdrop format. - * - * If the preset can't be loaded, no switch takes place and the current preset will continue to - * be displayed. Note that if there's a transition in progress when calling this function, the - * transition will be finished immediately, even if the new preset can't be loaded. - * - * @param instance The projectM instance handle. - * @param data The preset contents to load. - * @param smooth_transition If true, the new preset is smoothly blended over. - */ -PROJECTM_EXPORT void projectm_load_preset_data(projectm_handle instance, const char* data, - bool smooth_transition); - -/** - * @brief Sets a callback function that will be called when a preset change is requested. - * - * Only one callback can be registered per projectM instance. To remove the callback, use NULL. - * - * @param instance The projectM instance handle. - * @param callback A pointer to the callback function. - * @param user_data A pointer to any data that will be sent back in the callback, e.g. context - * information. - */ -PROJECTM_EXPORT void projectm_set_preset_switch_requested_event_callback(projectm_handle instance, - projectm_preset_switch_requested_event callback, - void* user_data); - -/** - * @brief Sets a callback function that will be called when a preset change failed. - * - * Only one callback can be registered per projectM instance. To remove the callback, use NULL. - * - * @param instance The projectM instance handle. - * @param callback A pointer to the callback function. - * @param user_data A pointer to any data that will be sent back in the callback, e.g. context - * information. - */ -PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_handle instance, - projectm_preset_switch_failed_event callback, - void* user_data); - -/** - * @brief Sets the texture search paths. - * - * Calling this method will clear and reload all textures, including the main rendering texture. - * Can cause a small delay/lag in rendering. Only use if texture paths were changed. - * - * @param instance The projectM instance handle. - * @param texture_search_paths A list of texture search paths. - * @param count The number of paths in the list. - */ -PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance, - const char** texture_search_paths, - size_t count); - -/** - * @brief Reloads all textures. - * - * Calling this method will clear and reload all textures, including the main rendering texture. - * Can cause a small delay/lag in rendering. Only use if texture paths were changed. - * - * @param instance The projectM instance handle. - */ -PROJECTM_EXPORT void projectm_reset_textures(projectm_handle instance); - -/** - * @brief Renders a single frame. - * - * @note Separate two-pass frame rendering is currently not supported by the C API as it is rarely used - * and also depends on the loaded preset. - * - * @param instance The projectM instance handle. - */ -PROJECTM_EXPORT void projectm_render_frame(projectm_handle instance); - -/** - * @brief Enables render-to-texture. - * - * Useful if projectM output will be part of a more complex OpenGL scene. The size of the texture is determined by the - * given viewport size and the dimensions should be a power of 2. - * - * @param instance The projectM instance handle. - * @return A GLuint value with the texture ID projectM will render to. - */ -PROJECTM_EXPORT unsigned int projectm_init_render_to_texture(projectm_handle instance); - -/** - * @brief Returns the size of the internal render texture. - * @param instance The projectM instance handle. - * @return The size of the internal rendering texture. - */ -PROJECTM_EXPORT size_t projectm_get_texture_size(projectm_handle instance); - -/** - * @brief Changes the size of the internal render texture. - * @note This will recreate the internal renderer. - * @param instance The projectM instance handle. - * @param size The new size of the render texture. Must be a power of 2. - */ -PROJECTM_EXPORT void projectm_set_texture_size(projectm_handle instance, size_t size); - -/** - * @brief Sets the beat sensitivity. - * - * The beat sensitivity to be used. - * - * @param instance The projectM instance handle. - * @param sensitivity The sensitivity setting. - */ -PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, float sensitivity); - -/** - * @brief Returns the beat sensitivity. - * @param instance The projectM instance handle. - * @return The current sensitivity setting. - */ -PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance); - -/** - * @brief Returns the minimum display time before a hard cut can happen. - * @param instance The projectM instance handle. - * @return The minimum number of seconds the preset will be displayed before a hard cut. - */ -PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance); - -/** - * @brief Sets the minimum display time before a hard cut can happen. - * - *Hard cuts are beat-sensitive preset transitions, immediately changing from - * one preset to the next without a smooth blending period.
- * - *Set this to a higher value than preset duration to disable hard cuts.
- * - * @param instance The projectM instance handle. - * @param seconds Minimum number of seconds the preset will be displayed before a hard cut. - */ -PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, double seconds); - -/** - * @brief Returns whether hard cuts are enabled or not. - * @param instance The projectM instance handle. - * @return True if hard cuts are enabled, false otherwise. - */ -PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance); - -/** - * @brief Enables or disables hard cuts. - * - * Even if enabled, the hard cut duration must be set to a value lower than the preset duration - * to work properly. - * - * @param instance The projectM instance handle. - * @param enabled True to enable hard cuts, false to disable. - */ -PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, bool enabled); - -/** - * @brief Returns the current hard cut sensitivity. - * @param instance The projectM instance handle. - * @return The current hard cut sensitivity. - */ -PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance); - -/** - * @brief Sets the hard cut volume sensitivity. - * - * The beat detection volume difference that must be surpassed to trigger a hard cut. - * - * @param instance The projectM instance handle. - * @param sensitivity The volume threshold that triggers a hard cut if surpassed. - */ -PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, float sensitivity); - -/** - * @brief Returns the time in seconds for a soft transition between two presets. - * @param instance The projectM instance handle. - * @return Time in seconds it takes to smoothly transition from one preset to another. - */ -PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance); - -/** - * @brief Sets the time in seconds for a soft transition between two presets. - * - * During a soft cut, both presets are rendered and slowly transitioned from one - * to the other. - * - * @param instance The projectM instance handle. - * @param seconds Time in seconds it takes to smoothly transition from one preset to another. - */ -PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, double seconds); - -/** - * @brief Returns the preset display duration before switching to the next using a soft cut. - * - * This can be considered as the maximum time a preset is displayed. If this time is reached, - * a smooth cut will be initiated. A hard cut, if any, will always happen before this time. - * - * @param instance The projectM instance handle. - * @return The currently set preset display duration in seconds. - */ -PROJECTM_EXPORT double projectm_get_preset_duration(projectm_handle instance); - -/** - * @brief Sets the preset display duration before switching to the next using a soft cut. - * - * This can be considered as the maximum time a preset is displayed. If this time is reached, - * a smooth cut will be initiated. A hard cut, if any, will always happen before this time. - * - * @param instance The projectM instance handle. - * @param seconds The number of seconds a preset will be displayed before the next is shown. - */ -PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, double seconds); - -/** - * @brief Returns the per-pixel equation mesh size in units. - * @param instance The projectM instance handle. - * @param width The width of the mesh. - * @param height The height of the mesh. - */ -PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* width, size_t* height); - -/** - * @brief Sets the per-pixel equation mesh size in units. - * @note This will currently remove any active presets and reload the default "idle" preset. - * @param instance The projectM instance handle. - * @param width The new width of the mesh. - * @param height The new height of the mesh. - */ -PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t width, size_t height); - -/** - * @brief Returns the current/average frames per second. - * - * This value needs to be set by the application. If it wasn't set, a default value of 60 is used. - * - * @param instance The projectM instance handle. - * @return The current/average frames per second. - */ -PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance); - -/** - * @brief Sets the current/average frames per second. - * - * Applications running projectM should UpdateMeshSize this value regularly and set it to the calculated - * (and possibly averaged) FPS value the output rendered with. The value is passed on to presets, - * which may choose to use it for calculations. It is not used in any other way by the library. - * - * @param instance The projectM instance handle. - * @param fps The current FPS value projectM is running with. - */ -PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps); - -/** - * @brief Enabled or disables aspect ratio correction in presets that support it. - * - * This sets a flag presets can use to aspect-correct rendered shapes, which otherwise would - * be distorted if the viewport isn't exactly square. - * - * @param instance The projectM instance handle. - * @param enabled True to enable aspect correction, false to disable it. - */ -PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bool enabled); - -/** - * @brief Returns whether aspect ratio correction is enabled or not. - * @param instance The projectM instance handle. - * @return True if aspect ratio correction is enabled, false otherwise. - */ -PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance); - -/** - * @brief Sets the "easter egg" value. - * - *This doesn't enable any fancy feature, it only influences the randomized display time of presets. It's - * passed as the "sigma" value of the gaussian random number generator used to determine the maximum display time, - * effectively multiplying the generated number of seconds by this amount.
- * - *See function sampledPresetDuration() of the TimeKeeper class on how it is used.
- * - * @param instance The projectM instance handle. - * @param value The new "easter egg" value. - */ -PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float value); - -/** - * @brief Returns the current "easter egg" value. - * @param instance The projectM instance handle. - * @return The current "easter egg" value. - */ -PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance); - -/** - * @brief Starts a touch event or moves an existing waveform. - * - * This will add or move waveforms in addition to the preset waveforms. If there is an existing waveform - * at the given coordinates, it will be centered on the new coordinates. If there is no waveform, a new one - * will be added. - * - * @param instance The projectM instance handle. - * @param x The x coordinate of the touch event. - * @param y The y coordinate of the touch event. - * @param pressure The amount of pressure applied in a range from 0.0 to 1.0. - * @param touch_type The waveform type that will be rendered on touch. - */ -PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y, - int pressure, projectm_touch_type touch_type); - -/** - * @brief Centers any waveforms under the coordinates to simulate dragging. - * @param instance The projectM instance handle. - * @param x The x coordinate of the drag. - * @param y the y coordinate of the drag. - * @param pressure The amount of pressure applied in a range from 0.0 to 1.0. - */ -PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, float y, int pressure); - -/** - * @brief Removes any additional touch waveforms under the given coordinates. - * @param instance The projectM instance handle. - * @param x The last known x touch coordinate. - * @param y The last known y touch coordinate. - */ -PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, float y); - -/** - * @brief Removes all touch waveforms from the screen. - * - * Preset-defined waveforms will still be displayed. - * - * @param instance The projectM instance handle. - */ -PROJECTM_EXPORT void projectm_touch_destroy_all(projectm_handle instance); - -/** - * @brief Returns whether the current preset is locked or not. - * @param instance The projectM instance handle. - * @return True if the preset lock is enabled, false otherwise. - */ -PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance); - -/** - * @brief Locks or unlocks the current preset. - * - * Locking effectively disables automatic preset transitions, both hard and soft cuts. Programmatic - * preset switches will still be executed. - * - * @param instance The projectM instance handle. - * @param lock True to lock the current preset, false to enable automatic transitions. - */ -PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool lock); - -/** - * @brief Returns the current viewport size in pixels. - * @param instance The projectM instance handle. - * @param width Valid pointer to a size_t variable that will receive the window width value. - * @param height Valid pointer to a size_t variable that will receive the window height value. - */ -PROJECTM_EXPORT void projectm_get_window_size(projectm_handle instance, size_t* width, size_t* height); - -/** - * @brief Sets the current viewport size in pixels. - * - * Calling this function will reset the OpenGL renderer. - * - * @param instance The projectM instance handle. - * @param width New viewport width in pixels. - * @param height New viewport height in pixels. - */ -PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t width, size_t height); - -/** - * @brief Returns the maximum number of audio samples that can be stored. - * - * Each PCM data UpdateMeshSize should not exceed this number of samples. If more samples - * are added, only this number of samples is stored and the remainder discarded. - * - * @return The number of audio samples that are stored, per channel. - */ -PROJECTM_EXPORT unsigned int projectm_pcm_get_max_samples(); - -/** - * @brief Adds 32-bit floating-point audio samples. - * - * This function is used to add new audio data to projectM's internal audio buffer. It is internally converted - * to 2-channel float data, duplicating the channel. - * - * If stereo, the channel order in samples is LRLRLR. - * - * @param instance The projectM instance handle. - * @param samples An array of PCM samples. - * Each sample is expected to be within the range -1 to 1. - * @param count The number of audio samples in a channel. - * @param channels If the buffer is mono or stereo. - * Can be PROJECTM_MONO or PROJECTM_STEREO. - */ -PROJECTM_EXPORT void projectm_pcm_add_float(projectm_handle instance, const float* samples, - unsigned int count, projectm_channels channels); - -/** - * @brief Adds 16-bit integer audio samples. - * - * This function is used to add new audio data to projectM's internal audio buffer. It is internally converted - * to 2-channel float data, duplicating the channel. - * - * If stereo, the channel order in samples is LRLRLR. - * - * @param instance The projectM instance handle. - * @param samples An array of PCM samples. - * @param count The number of audio samples in a channel. - * @param channels If the buffer is mono or stereo. - * Can be PROJECTM_MONO or PROJECTM_STEREO. - */ -PROJECTM_EXPORT void projectm_pcm_add_int16(projectm_handle instance, const int16_t* samples, - unsigned int count, projectm_channels channels); - -/** - * @brief Adds 8-bit unsigned integer audio samples. - * - * This function is used to add new audio data to projectM's internal audio buffer. It is internally converted - * to 2-channel float data, duplicating the channel. - * - * If stereo, the channel order in samples is LRLRLR. - * - * @param instance The projectM instance handle. - * @param samples An array of PCM samples. - * @param count The number of audio samples in a channel. - * @param channels If the buffer is mono or stereo. - * Can be PROJECTM_MONO or PROJECTM_STEREO. - */ -PROJECTM_EXPORT void projectm_pcm_add_uint8(projectm_handle instance, const uint8_t* samples, - unsigned int count, projectm_channels channels); - -/** - * @brief Writes a .bmp framedump after rendering the next main texture, before shaders are applied. - * - * The image is written to the current working directory and is named "frame_texture_contents-[date].bmp". - * - * @param instance The projectM instance handle. - */ -PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance); - -#ifdef __cplusplus -} // extern "C" -#endif +#include "libprojectM/audio.h" +#include "libprojectM/callbacks.h" +#include "libprojectM/core.h" +#include "libprojectM/debug.h" +#include "libprojectM/memory.h" +#include "libprojectM/parameters.h" +#include "libprojectM/render_opengl.h" +#include "libprojectM/touch.h" diff --git a/src/api/include/libprojectM/render_opengl.h b/src/api/include/libprojectM/render_opengl.h new file mode 100644 index 000000000..0b7c4a49d --- /dev/null +++ b/src/api/include/libprojectM/render_opengl.h @@ -0,0 +1,57 @@ +/** + * @file render_opengl.h + * @copyright 2003-2023 projectM Team + * @brief Functions to configure and render projectM visuals using OpenGL. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Renders a single frame. + * + * @note Separate two-pass frame rendering is currently not supported by the C API as it is rarely used + * and also depends on the loaded preset. + * + * @param instance The projectM instance handle. + */ +PROJECTM_EXPORT void projectm_opengl_render_frame(projectm_handle instance); + +/** + * @brief Enables render-to-texture. + * + * Useful if projectM output will be part of a more complex OpenGL scene. The size of the texture is determined by the + * given viewport size and the dimensions should be a power of 2. + * + * @param instance The projectM instance handle. + * @return A GLuint value with the texture ID projectM will render to. + */ +PROJECTM_EXPORT unsigned int projectm_opengl_init_render_to_texture(projectm_handle instance); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/api/include/libprojectM/touch.h b/src/api/include/libprojectM/touch.h new file mode 100644 index 000000000..834fcd8d1 --- /dev/null +++ b/src/api/include/libprojectM/touch.h @@ -0,0 +1,78 @@ +/** + * @file touch.h + * @copyright 2003-2023 projectM Team + * @brief Touch-related functions to add random waveforms. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Starts a touch event or moves an existing waveform. + * + * This will add or move waveforms in addition to the preset waveforms. If there is an existing waveform + * at the given coordinates, it will be centered on the new coordinates. If there is no waveform, a new one + * will be added. + * + * @param instance The projectM instance handle. + * @param x The x coordinate of the touch event. + * @param y The y coordinate of the touch event. + * @param pressure The amount of pressure applied in a range from 0.0 to 1.0. + * @param touch_type The waveform type that will be rendered on touch. + */ +PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y, + int pressure, projectm_touch_type touch_type); + +/** + * @brief Centers any waveforms under the coordinates to simulate dragging. + * @param instance The projectM instance handle. + * @param x The x coordinate of the drag. + * @param y the y coordinate of the drag. + * @param pressure The amount of pressure applied in a range from 0.0 to 1.0. + */ +PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, float y, int pressure); + +/** + * @brief Removes any additional touch waveforms under the given coordinates. + * @param instance The projectM instance handle. + * @param x The last known x touch coordinate. + * @param y The last known y touch coordinate. + */ +PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, float y); + +/** + * @brief Removes all touch waveforms from the screen. + * + * Preset-defined waveforms will still be displayed. + * + * @param instance The projectM instance handle. + */ +PROJECTM_EXPORT void projectm_touch_destroy_all(projectm_handle instance); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/api/include/libprojectM/types.h b/src/api/include/libprojectM/types.h new file mode 100644 index 000000000..b960727b5 --- /dev/null +++ b/src/api/include/libprojectM/types.h @@ -0,0 +1,80 @@ +/** + * @file types.h + * @copyright 2003-2023 projectM Team + * @brief Types and enumerations used in the other API headers. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/projectM_export.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#includeDoes not immediately apply the new list to an existing playlist, only newly added files + * will be affected. If you need to filter the existing playlist after calling this method, + * additionally call projectm_playlist_apply_filter() afterwards.
+ * + *The filter list consists of simple globbing expressions similar to the .gitignore syntax:
+ * + *In globbing expressions, \\ can be used as path separator instead of /. The backslash can't + * be used to escape globbing patterns, so matching literal * and ? in filenames is not possible. + * This is not a huge issue as Windows doesn't allow those characters in filenames and Milkdrop + * files originate from the Windows world. Character classes like "[0-9]" are also not supported to + * keep the syntax simple.
+ * + *Each line can be prefixed with either + or - to either include files matching the pattern + * or excluding them. Any other character is not interpreted as a prefix and the filter line is + * matching as an exclude filter. To match a literal + or - at the beginning, add the appropriate + * prefix in front. Empty filters never match anything, even if the filename is empty.
+ * + *The filter list is checked in order. The first pattern that matches the filename determines + * the filter result (include or exclude). If no pattern matches, the file is included. In the case + * that a default exclude action is required, add a "-/**" filter at the end of the list.
+ * + * @param instance The playlist manager instance. + * @param filter_list An array with filter strings. + * @param count The size of the filter array. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_handle instance, const char** filter_list, + size_t count); + +/** + * @brief Returns the current filter list. + * + * Always call projectm_playlist_free_string_array() on the returned pointer if the data is + * no longer needed. + * + * @param instance The playlist manager instance. + * @param[out] count The size of the filter array. + * @return An array with filter strings. + */ +PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_handle instance, size_t* count); + +/** + * @brief Applies the current filter list to the existing playlist. + * + * Note this function only removes items. Previously filtered items are not added again. If items + * were removed, the playback history is cleared. + * + * @param instance The playlist manager instance. + * @return The number of removed items. + */ +PROJECTM_PLAYLIST_EXPORT size_t projectm_playlist_apply_filter(projectm_playlist_handle instance); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/playlist/api/libprojectM/playlist_items.h b/src/playlist/api/libprojectM/playlist_items.h new file mode 100644 index 000000000..c06bd1c89 --- /dev/null +++ b/src/playlist/api/libprojectM/playlist_items.h @@ -0,0 +1,241 @@ +/** + * @file playlist_items.h + * @copyright 2003-2023 projectM Team + * @brief Playlist item management functions. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/playlist_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Returns the number of presets in the current playlist. + * @param instance The playlist manager instance. + * @return The number of presets in the current playlist. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_size(projectm_playlist_handle instance); + +/** + * @brief Clears the playlist. + * @param instance The playlist manager instance to clear. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle instance); + +/** + * @brief Returns a list of preset files inside the given range of the current playlist, in order. + * + * This function can be used to return the whole playlist to save it to a file, or just a part of + * it for use in virtual lists. If less elements than given in @a count are available, only the + * remainder of items after the starting index are returned. If the starting index equals or exceeds + * the playlist size, an empty list is returned. + * + * @note Call projectm_playlist_free_string_array() when you're done using the list. + * @note Ideally, don't rely on the value provided as count to iterate over the filenames. + * Instead, look for the terminating null pointer to abort the loop. + * @param instance The playlist manager instance. + * @param start The zero-based starting index of the range to return. + * @param count The maximum number if items to return. + * @return A pointer to a list of char pointers, each containing a single preset. The last entry + * is denoted by a null pointer. + */ +PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle instance, uint32_t start, uint32_t count); + +/** + * @brief Returns the name of a preset at the given index in the current playlist. + * @note Call projectm_playlist_free_string() when you're done using the return value. + * @note If you need to retrieve a major part of playlist filenames, use projectm_playlist_items() + * instead. + * @param instance The playlist manager instance. + * @param index The index to retrieve the filename for. + * @return The filename of the requested preset, or NULL if the index was out of bounds or the + * playlist is empty. + */ +PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle instance, uint32_t index); + +/** + * @brief Appends presets from the given path to the end of the current playlist. + * + * This method will scan the given path for files with a ".milk" extension and add these to the + * playlist. + * + * Symbolic links are not followed. + * + * @param instance The playlist manager instance. + * @param path A local filesystem path to scan for presets. + * @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false, + * only the exact path given is searched for presets. + * @param allow_duplicates If true, files found will always be added. If false, only files are + * added that do not already exist in the current playlist. + * @return The number of files added. 0 may indicate issues scanning the path. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_handle instance, const char* path, + bool recurse_subdirs, bool allow_duplicates); + + +/** + * @brief Inserts presets from the given path to the end of the current playlist. + * + * This method will scan the given path for files with a ".milk" extension and add these to the + * playlist. + * + * Symbolic links are not followed. + * + * @param instance The playlist manager instance. + * @param path A local filesystem path to scan for presets. + * @param index The index to insert the presets at. If it exceeds the playlist size, the presets are +* added at the end of the playlist. + * @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false, + * only the exact path given is searched for presets. + * @param allow_duplicates If true, files found will always be added. If false, only files are + * added that do not already exist in the current playlist. + * @return The number of files added. 0 may indicate issues scanning the path. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_path(projectm_playlist_handle instance, const char* path, + uint32_t index, bool recurse_subdirs, bool allow_duplicates); + +/** + * @brief Adds a single preset to the end of the playlist. + * + * @note The file is not checked for existence or for being readable. + * + * @param instance The playlist manager instance. + * @param filename A local preset filename. + * @param allow_duplicates If true, the preset filename will always be added. If false, the preset + * is only added to the playlist if the exact filename doesn't exist in the + * current playlist. + * @return True if the file was added to the playlist, false if the file was a duplicate and + * allow_duplicates was set to false. + */ +PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_handle instance, const char* filename, + bool allow_duplicates); + +/** + * @brief Adds a single preset to the playlist at the specified position. + * + * To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is + * performs better. + * + * @note The file is not checked for existence or for being readable. + * + * @param instance The playlist manager instance. + * @param filename A local preset filename. + * @param index The index to insert the preset at. If it exceeds the playlist size, the preset is + * added at the end of the playlist. + * @param allow_duplicates If true, the preset filename will always be added. If false, the preset + * is only added to the playlist if the exact filename doesn't exist in the + * current playlist. + * @return True if the file was added to the playlist, false if the file was a duplicate and + * allow_duplicates was set to false. + */ +PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_handle instance, const char* filename, + uint32_t index, bool allow_duplicates); + +/** + * @brief Adds a list of presets to the end of the playlist. + * + * @note The files are not checked for existence or for being readable. + * + * @param instance The playlist manager instance. + * @param filenames A list of local preset filenames. + * @param count The number of files in the list. + * @param allow_duplicates If true, the preset filenames will always be added. If false, a preset + * is only added to the playlist if the exact filename doesn't exist in the + * current playlist. + * @return The number of files added to the playlist. Ranges between 0 and count. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlist_handle instance, const char** filenames, + uint32_t count, bool allow_duplicates); + +/** + * @brief Adds a single preset to the playlist at the specified position. + * + * To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is + * performs better. + * + * @note The files are not checked for existence or for being readable. + * + * @param instance The playlist manager instance. + * @param filenames A list of local preset filenames. + * @param count The number of files in the list. + * @param index The index to insert the presets at. If it exceeds the playlist size, the presets are + * added at the end of the playlist. + * @param allow_duplicates If true, the preset filenames will always be added. If false, a preset + * is only added to the playlist if the exact filename doesn't exist in the + * current playlist. + * @return The number of files added to the playlist. Ranges between 0 and count. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_presets(projectm_playlist_handle instance, const char** filenames, + uint32_t count, unsigned int index, bool allow_duplicates); + +/** + * @brief Removes a single preset from the playlist at the specified position. + * + * @param instance The playlist manager instance. + * @param index The preset index to remove. If it exceeds the playlist size, no preset will be + * removed. + * @return True if the preset was removed from the playlist, false if the index was out of range. + */ +PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_handle instance, uint32_t index); + +/** + * @brief Removes a number of presets from the playlist from the specified position. + * + * @param instance The playlist manager instance. + * @param index The first preset index to remove. If it exceeds the playlist size, no preset will be + * removed. + * @param count The number of presets to remove from the given index. + * @return The number of presets removed from the playlist. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_playlist_handle instance, uint32_t index, + uint32_t count); + +/** + * @brief Sorts part or the whole playlist according to the given predicate and order. + * + * It is safe to provide values in start_index and count that will exceed the number of items + * in the playlist. Only items that fall into an existing index range are sorted. If start_index + * is equal to or larger than the playlist size, no items are sorted. If start_index is inside the + * playlist, but adding count results in an index outside the playlist, items until the end are + * sorted. + * + * Sort order is lexicographical for both predicates and case-sensitive. + * + * If invalid values are provides as predicate or order, the defaults as mentioned in the parameter + * description are used. + * + * @param instance The playlist manager instance. + * @param start_index The starting index to begin sorting at. + * @param count The number of items, beginning at start_index, to sort. + * @param predicate The predicate to use for sorting. Default is SORT_PREDICATE_FULL_PATH. + * @param order The sort order. Default is SORT_ORDER_ASCENDING. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_sort(projectm_playlist_handle instance, uint32_t start_index, uint32_t count, + projectm_playlist_sort_predicate predicate, projectm_playlist_sort_order order); + +#ifdef __cplusplus +} // extern "C" +#endif + diff --git a/src/playlist/api/libprojectM/playlist_memory.h b/src/playlist/api/libprojectM/playlist_memory.h new file mode 100644 index 000000000..8b53d81f7 --- /dev/null +++ b/src/playlist/api/libprojectM/playlist_memory.h @@ -0,0 +1,56 @@ +/** + * @file playlist_memory.h + * @copyright 2003-2023 projectM Team + * @brief Memory allocation/deallocation helpers. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/playlist_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Frees a char pointer returned by any of the playlist API functions. + * + * Please only use this function with char pointers returned by the playlist library, and don't use + * other projectM memory management functions with pointers returned by the playlist library. + * + * @param string A pointer to a string that should be freed. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string); + +/** + * @brief Frees a string array returned by any of the playlist API functions. + * + * Please only use this function with pointers returned by the playlist library, and don't use + * other projectM memory management functions with pointers returned by the playlist library. + * + * @param array The pointer to the array of strings that should be freed. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string_array(char** array); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/playlist/api/libprojectM/playlist_playback.h b/src/playlist/api/libprojectM/playlist_playback.h new file mode 100644 index 000000000..d0c0a32cc --- /dev/null +++ b/src/playlist/api/libprojectM/playlist_playback.h @@ -0,0 +1,136 @@ +/** + * @file playlist_playback.h + * @copyright 2003-2023 projectM Team + * @brief Playback control functions. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/playlist_types.h" + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @brief Enable or disable shuffle mode. + * @param instance The playlist manager instance. + * @param shuffle True to enable random shuffling, false to play presets in playlist order. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_handle instance, bool shuffle); + +/** + * @brief Retrieves the current state of shuffle mode. + * @param instance The playlist manager instance. + * @return True if shuffle mode is enabled, false otherwise. + */ +PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_handle instance); + +/** + * @brief Sets the number of retries after failed preset switches. + * @note Don't set this value too high, as each retry is done recursively. + * @param instance The playlist manager instance. + * @param retry_count The number of retries after failed preset switches. Default is 5. Set to 0 + * to simply forward the failure event from projectM. + */ +PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlist_handle instance, uint32_t retry_count); + +/** + * @brief Returns the number of retries after failed preset switches. + * @param instance The playlist manager instance. + * @return The number of retries after failed preset switches. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_playlist_handle instance); + +/** + * @brief Plays the preset at the requested playlist position and returns the actual playlist index. + * + * If the requested position is out of bounds, the returned position will wrap to 0, effectively + * repeating the playlist as if shuffle was disabled. It has no effect if the playlist is empty. + * + * This method ignores the shuffle setting and will always jump to the requested index, given it is + * withing playlist bounds. + * + * @param instance The playlist manager instance. + * @param new_position The new position to jump to. + * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. + * @return The new playlist position. If the playlist is empty, 0 will be returned. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playlist_handle instance, uint32_t new_position, + bool hard_cut); + +/** + * @brief Returns the current playlist position. + * @param instance The playlist manager instance. + * @return The current playlist position. If the playlist is empty, 0 will be returned. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playlist_handle instance); + +/** + * @brief Plays the next playlist item and returns the index of the new preset. + * + * If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the + * end of the playlist is reached in continuous mode, it will wrap back to 0. + * + * The old playlist item is added to the history. + * + * @param instance The playlist manager instance. + * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. + * @return The new playlist position. If the playlist is empty, 0 will be returned. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_handle instance, bool hard_cut); + +/** + * @brief Plays the previous playlist item and returns the index of the new preset. + * + * If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the + * end of the playlist is reached in continuous mode, it will wrap back to 0. + * + * The old playlist item is added to the history. + * + * @param instance The playlist manager instance. + * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. + * @return The new playlist position. If the playlist is empty, 0 will be returned. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playlist_handle instance, bool hard_cut); + +/** + * @brief Plays the last preset played in the history and returns the index of the preset. + * + * The history keeps track of the last 1000 presets and will go back in the history. The + * playback history will be cleared whenever the playlist items are changed. + * + * If the history is empty, this call behaves identical to projectm_playlist_play_previous(), + * but the item is not added to the history. + * + * Presets which failed to load are not recorded in the history and thus will be skipped when + * calling this method. + * + * @param instance The playlist manager instance. + * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. + * @return The new playlist position. If the playlist is empty, 0 will be returned. + */ +PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_last(projectm_playlist_handle instance, bool hard_cut); + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/playlist/api/libprojectM/playlist_types.h b/src/playlist/api/libprojectM/playlist_types.h new file mode 100644 index 000000000..16f8b05b9 --- /dev/null +++ b/src/playlist/api/libprojectM/playlist_types.h @@ -0,0 +1,58 @@ +/** + * @file playlist_types.h + * @copyright 2003-2023 projectM Team + * @brief Types and enumerations used in the playlist API headers. + * + * projectM -- Milkdrop-esque visualisation SDK + * Copyright (C)2003-2023 projectM Team + * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. + * + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. + * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + * See 'LICENSE.txt' included within this release + * + */ + +#pragma once + +#include "libprojectM/projectM_playlist_export.h" + +#ifdef __cplusplus +extern "C" { +#endif + +struct projectm_playlist; //!< Opaque projectM playlist instance type. +typedef struct projectm_playlist* projectm_playlist_handle; //!< A pointer to the opaque projectM playlist instance. + +/** + * Sort predicate for playlist sorting. + */ +typedef enum +{ + SORT_PREDICATE_FULL_PATH, //!< Sort by full path name + SORT_PREDICATE_FILENAME_ONLY //!< Sort only by preset filename +} projectm_playlist_sort_predicate; + + +/** + * Sort order for playlist sorting. + */ +typedef enum +{ + SORT_ORDER_ASCENDING, //!< Sort in alphabetically ascending order. + SORT_ORDER_DESCENDING //!< Sort in alphabetically descending order. +} projectm_playlist_sort_order; + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/src/playlist/playlist.h b/src/playlist/playlist.h deleted file mode 100644 index 365c89dbb..000000000 --- a/src/playlist/playlist.h +++ /dev/null @@ -1,537 +0,0 @@ -/** - * @file playlist.h - * - * Optional playlist API for libprojectM. - */ -#pragma once - -#include "libprojectM/projectM.h" -#include "libprojectM/projectM_playlist_export.h" - -#ifdef __cplusplus -extern "C" { -#endif - -struct projectm_playlist; //!< Opaque projectM playlist instance type. -typedef struct projectm_playlist* projectm_playlist_handle; //!< A pointer to the opaque projectM playlist instance. - -/** - * Sort predicate for playlist sorting. - */ -typedef enum -{ - SORT_PREDICATE_FULL_PATH, //!< Sort by full path name - SORT_PREDICATE_FILENAME_ONLY //!< Sort only by preset filename -} projectm_playlist_sort_predicate; - - -/** - * Sort order for playlist sorting. - */ -typedef enum -{ - SORT_ORDER_ASCENDING, //!< Sort in alphabetically ascending order. - SORT_ORDER_DESCENDING //!< Sort in alphabetically descending order. -} projectm_playlist_sort_order; - - -/** - * @brief Frees a char pointer returned by any of the playlist API functions. - * - * Please only use this function with char pointers returned by the playlist library, and don't use - * other projectM memory management functions with pointers returned by the playlist library. - * - * @param string A pointer to a string that should be freed. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string); - -/** - * @brief Frees a string array returned by any of the playlist API functions. - * - * Please only use this function with pointers returned by the playlist library, and don't use - * other projectM memory management functions with pointers returned by the playlist library. - * - * @param array The pointer to the array of strings that should be freed. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string_array(char** array); - -/** - * @brief Callback function that is executed on each preset change. - * - * Can be used for example to UpdateMeshSize the application window title. Applications must not - * switch presets inside this callback, as it can lead to infinite recursion. - * - * @param is_hard_cut True if the preset was switched using a hard cut via beat detection. - * @param index The playlist index of the new preset. - * @param user_data A user-defined data pointer that was provided when registering the callback, - * e.g. context information. - */ -typedef void (*projectm_playlist_preset_switched_event)(bool is_hard_cut, unsigned int index, - void* user_data); - -/** - * @brief Callback function that is executed if a preset change failed too often. - * - * Similar to the projectM API function, but will only be called if the preset switch failed - * multiple times in a row, e.g. due to missing files or broken presets. The application should - * decide what action to take. - * - * @note Do NOT call any functions that switch presets inside the callback, at it might - * lead to infinite recursion and thus a stack overflow! - * @note The message pointer is only valid inside the callback. Make a copy if it need to be - * retained for later use. - * @param preset_filename The filename of the failed preset. - * @param message The last error message. - * @param user_data A user-defined data pointer that was provided when registering the callback, - * e.g. context information. - */ -typedef void (*projectm_playlist_preset_switch_failed_event)(const char* preset_filename, - const char* message, void* user_data); - - -/** - * @brief Creates a playlist manager for the given projectM instance - * - * Only one active playlist manager is supported per projectM instance. If multiple playlists use - * the same projectM instance, only the last created playlist manager will receive preset change - * callbacks from the projectM instance. - * - * To switch to another playlist, use the projectm_playlist_connect() method. - * - * @param projectm_instance The projectM instance to connect to. Can be a null pointer to leave the newly - * created playlist instance unconnected. - * @return An opaque pointer to the newly created playlist manager instance. Null if creation failed. - */ -PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(projectm_handle projectm_instance); - -/** - * @brief Destroys a previously created playlist manager. - * - * If the playlist manager is currently connected to a projectM instance, it will be disconnected. - * - * @param instance The playlist manager instance to destroy. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle instance); - -/** - * @brief Sets a callback function that will be called when a preset changes. - * - * Only one callback can be registered per playlist instance. To remove the callback, use NULL. - * - * @param instance The playlist manager instance. - * @param callback A pointer to the callback function. - * @param user_data A pointer to any data that will be sent back in the callback, e.g. context - * information. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switched_event_callback(projectm_playlist_handle instance, - projectm_playlist_preset_switched_event callback, - void* user_data); - -/** - * @brief Sets a callback function that will be called when a preset change failed. - * - * Only one callback can be registered per projectM instance. To remove the callback, use NULL. - * - * If the application want to receive projectM's analogous callback directly, use the - * projectm_set_preset_switch_failed_event_callback() function after calling - * projectm_playlist_create() or projectm_playlist_connect(), respectively, as these will both - * override the callback set in projectM. - * - * @param instance The playlist manager instance. - * @param callback A pointer to the callback function. - * @param user_data A pointer to any data that will be sent back in the callback, e.g. context - * information. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switch_failed_event_callback(projectm_playlist_handle instance, - projectm_playlist_preset_switch_failed_event callback, - void* user_data); - -/** - * @brief Connects the playlist manager to a projectM instance. - * - * Sets or removes the preset switch callbacks and stores the projectM instance handle for use with - * manual preset switches via the playlist API. - * - * When switching between multiple playlist managers, first call this method on the last used - * playlist manager with a null pointer for the projectM instance, then call this method with the - * actual projectM instance on the playlist manager that should be activated. It is also safe to - * call projectm_playlist_connect() with a null projectM handle on all playlist manager instances - * before activating a single one with a valid, non-null projectM handle. - * - * @param instance The playlist manager instance. - * @param projectm_instance The projectM instance to connect to. Can be a null pointer to remove - * an existing binding and clear the projectM preset switch callback. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_connect(projectm_playlist_handle instance, projectm_handle projectm_instance); - -/** - * @brief Returns the number of presets in the current playlist. - * @param instance The playlist manager instance. - * @return The number of presets in the current playlist. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_size(projectm_playlist_handle instance); - -/** - * @brief Clears the playlist. - * @param instance The playlist manager instance to clear. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle instance); - -/** - * @brief Returns a list of preset files inside the given range of the current playlist, in order. - * - * This function can be used to return the whole playlist to save it to a file, or just a part of - * it for use in virtual lists. If less elements than given in @a count are available, only the - * remainder of items after the starting index are returned. If the starting index equals or exceeds - * the playlist size, an empty list is returned. - * - * @note Call projectm_playlist_free_string_array() when you're done using the list. - * @note Ideally, don't rely on the value provided as count to iterate over the filenames. - * Instead, look for the terminating null pointer to abort the loop. - * @param instance The playlist manager instance. - * @param start The zero-based starting index of the range to return. - * @param count The maximum number if items to return. - * @return A pointer to a list of char pointers, each containing a single preset. The last entry - * is denoted by a null pointer. - */ -PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle instance, uint32_t start, uint32_t count); - -/** - * @brief Returns the name of a preset at the given index in the current playlist. - * @note Call projectm_playlist_free_string() when you're done using the return value. - * @note If you need to retrieve a major part of playlist filenames, use projectm_playlist_items() - * instead. - * @param instance The playlist manager instance. - * @param index The index to retrieve the filename for. - * @return The filename of the requested preset, or NULL if the index was out of bounds or the - * playlist is empty. - */ -PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle instance, uint32_t index); - -/** - * @brief Appends presets from the given path to the end of the current playlist. - * - * This method will scan the given path for files with a ".milk" extension and add these to the - * playlist. - * - * Symbolic links are not followed. - * - * @param instance The playlist manager instance. - * @param path A local filesystem path to scan for presets. - * @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false, - * only the exact path given is searched for presets. - * @param allow_duplicates If true, files found will always be added. If false, only files are - * added that do not already exist in the current playlist. - * @return The number of files added. 0 may indicate issues scanning the path. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_handle instance, const char* path, - bool recurse_subdirs, bool allow_duplicates); - - -/** - * @brief Inserts presets from the given path to the end of the current playlist. - * - * This method will scan the given path for files with a ".milk" extension and add these to the - * playlist. - * - * Symbolic links are not followed. - * - * @param instance The playlist manager instance. - * @param path A local filesystem path to scan for presets. - * @param index The index to insert the presets at. If it exceeds the playlist size, the presets are -* added at the end of the playlist. - * @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false, - * only the exact path given is searched for presets. - * @param allow_duplicates If true, files found will always be added. If false, only files are - * added that do not already exist in the current playlist. - * @return The number of files added. 0 may indicate issues scanning the path. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_path(projectm_playlist_handle instance, const char* path, - uint32_t index, bool recurse_subdirs, bool allow_duplicates); - -/** - * @brief Adds a single preset to the end of the playlist. - * - * @note The file is not checked for existence or for being readable. - * - * @param instance The playlist manager instance. - * @param filename A local preset filename. - * @param allow_duplicates If true, the preset filename will always be added. If false, the preset - * is only added to the playlist if the exact filename doesn't exist in the - * current playlist. - * @return True if the file was added to the playlist, false if the file was a duplicate and - * allow_duplicates was set to false. - */ -PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_handle instance, const char* filename, - bool allow_duplicates); - -/** - * @brief Adds a single preset to the playlist at the specified position. - * - * To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is - * performs better. - * - * @note The file is not checked for existence or for being readable. - * - * @param instance The playlist manager instance. - * @param filename A local preset filename. - * @param index The index to insert the preset at. If it exceeds the playlist size, the preset is - * added at the end of the playlist. - * @param allow_duplicates If true, the preset filename will always be added. If false, the preset - * is only added to the playlist if the exact filename doesn't exist in the - * current playlist. - * @return True if the file was added to the playlist, false if the file was a duplicate and - * allow_duplicates was set to false. - */ -PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_handle instance, const char* filename, - uint32_t index, bool allow_duplicates); - -/** - * @brief Adds a list of presets to the end of the playlist. - * - * @note The files are not checked for existence or for being readable. - * - * @param instance The playlist manager instance. - * @param filenames A list of local preset filenames. - * @param count The number of files in the list. - * @param allow_duplicates If true, the preset filenames will always be added. If false, a preset - * is only added to the playlist if the exact filename doesn't exist in the - * current playlist. - * @return The number of files added to the playlist. Ranges between 0 and count. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlist_handle instance, const char** filenames, - uint32_t count, bool allow_duplicates); - -/** - * @brief Adds a single preset to the playlist at the specified position. - * - * To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is - * performs better. - * - * @note The files are not checked for existence or for being readable. - * - * @param instance The playlist manager instance. - * @param filenames A list of local preset filenames. - * @param count The number of files in the list. - * @param index The index to insert the presets at. If it exceeds the playlist size, the presets are - * added at the end of the playlist. - * @param allow_duplicates If true, the preset filenames will always be added. If false, a preset - * is only added to the playlist if the exact filename doesn't exist in the - * current playlist. - * @return The number of files added to the playlist. Ranges between 0 and count. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_presets(projectm_playlist_handle instance, const char** filenames, - uint32_t count, unsigned int index, bool allow_duplicates); - -/** - * @brief Removes a single preset from the playlist at the specified position. - * - * @param instance The playlist manager instance. - * @param index The preset index to remove. If it exceeds the playlist size, no preset will be - * removed. - * @return True if the preset was removed from the playlist, false if the index was out of range. - */ -PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_handle instance, uint32_t index); - -/** - * @brief Removes a number of presets from the playlist from the specified position. - * - * @param instance The playlist manager instance. - * @param index The first preset index to remove. If it exceeds the playlist size, no preset will be - * removed. - * @param count The number of presets to remove from the given index. - * @return The number of presets removed from the playlist. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_playlist_handle instance, uint32_t index, - uint32_t count); - -/** - * @brief Retrieves the current state of shuffle mode. - * @param instance The playlist manager instance. - * @return True if shuffle mode is enabled, false otherwise. - */ -PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_handle instance); - -/** - * @brief Enable or disable shuffle mode. - * @param instance The playlist manager instance. - * @param shuffle True to enable random shuffling, false to play presets in playlist order. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_handle instance, bool shuffle); - -/** - * @brief Sorts part or the whole playlist according to the given predicate and order. - * - * It is safe to provide values in start_index and count that will exceed the number of items - * in the playlist. Only items that fall into an existing index range are sorted. If start_index - * is equal to or larger than the playlist size, no items are sorted. If start_index is inside the - * playlist, but adding count results in an index outside the playlist, items until the end are - * sorted. - * - * Sort order is lexicographical for both predicates and case-sensitive. - * - * If invalid values are provides as predicate or order, the defaults as mentioned in the parameter - * description are used. - * - * @param instance The playlist manager instance. - * @param start_index The starting index to begin sorting at. - * @param count The number of items, beginning at start_index, to sort. - * @param predicate The predicate to use for sorting. Default is SORT_PREDICATE_FULL_PATH. - * @param order The sort order. Default is SORT_ORDER_ASCENDING. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_sort(projectm_playlist_handle instance, uint32_t start_index, uint32_t count, - projectm_playlist_sort_predicate predicate, projectm_playlist_sort_order order); - -/** - * @brief Returns the number of retries after failed preset switches. - * @param instance The playlist manager instance. - * @return The number of retries after failed preset switches. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_playlist_handle instance); - -/** - * @brief Sets the number of retries after failed preset switches. - * @note Don't set this value too high, as each retry is done recursively. - * @param instance The playlist manager instance. - * @param retry_count The number of retries after failed preset switches. Default is 5. Set to 0 - * to simply forward the failure event from projectM. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlist_handle instance, uint32_t retry_count); - -/** - * @brief Returns the current playlist position. - * @param instance The playlist manager instance. - * @return The current playlist position. If the playlist is empty, 0 will be returned. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playlist_handle instance); - -/** - * @brief Plays the preset at the requested playlist position and returns the actual playlist index. - * - * If the requested position is out of bounds, the returned position will wrap to 0, effectively - * repeating the playlist as if shuffle was disabled. It has no effect if the playlist is empty. - * - * This method ignores the shuffle setting and will always jump to the requested index, given it is - * withing playlist bounds. - * - * @param instance The playlist manager instance. - * @param new_position The new position to jump to. - * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. - * @return The new playlist position. If the playlist is empty, 0 will be returned. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playlist_handle instance, uint32_t new_position, - bool hard_cut); - -/** - * @brief Plays the next playlist item and returns the index of the new preset. - * - * If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the - * end of the playlist is reached in continuous mode, it will wrap back to 0. - * - * The old playlist item is added to the history. - * - * @param instance The playlist manager instance. - * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. - * @return The new playlist position. If the playlist is empty, 0 will be returned. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_handle instance, bool hard_cut); - -/** - * @brief Plays the previous playlist item and returns the index of the new preset. - * - * If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the - * end of the playlist is reached in continuous mode, it will wrap back to 0. - * - * The old playlist item is added to the history. - * - * @param instance The playlist manager instance. - * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. - * @return The new playlist position. If the playlist is empty, 0 will be returned. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playlist_handle instance, bool hard_cut); - -/** - * @brief Plays the last preset played in the history and returns the index of the preset. - * - * The history keeps track of the last 1000 presets and will go back in the history. The - * playback history will be cleared whenever the playlist items are changed. - * - * If the history is empty, this call behaves identical to projectm_playlist_play_previous(), - * but the item is not added to the history. - * - * Presets which failed to load are not recorded in the history and thus will be skipped when - * calling this method. - * - * @param instance The playlist manager instance. - * @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played. - * @return The new playlist position. If the playlist is empty, 0 will be returned. - */ -PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_last(projectm_playlist_handle instance, bool hard_cut); - -/** - * @brief Sets a new filter list. - * - *Does not immediately apply the new list to an existing playlist, only newly added files - * will be affected. If you need to filter the existing playlist after calling this method, - * additionally call projectm_playlist_apply_filter() afterwards.
- * - *The filter list consists of simple globbing expressions similar to the .gitignore syntax:
- * - *In globbing expressions, \\ can be used as path separator instead of /. The backslash can't - * be used to escape globbing patterns, so matching literal * and ? in filenames is not possible. - * This is not a huge issue as Windows doesn't allow those characters in filenames and Milkdrop - * files originate from the Windows world. Character classes like "[0-9]" are also not supported to - * keep the syntax simple.
- * - *Each line can be prefixed with either + or - to either include files matching the pattern - * or excluding them. Any other character is not interpreted as a prefix and the filter line is - * matching as an exclude filter. To match a literal + or - at the beginning, add the appropriate - * prefix in front. Empty filters never match anything, even if the filename is empty.
- * - *The filter list is checked in order. The first pattern that matches the filename determines - * the filter result (include or exclude). If no pattern matches, the file is included. In the case - * that a default exclude action is required, add a "-/**" filter at the end of the list.
- * - * @param instance The playlist manager instance. - * @param filter_list An array with filter strings. - * @param count The size of the filter array. - */ -PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_handle instance, const char** filter_list, - size_t count); - -/** - * @brief Returns the current filter list. - * - * Always call projectm_playlist_free_string_array() on the returned pointer if the data is - * no longer needed. - * - * @param instance The playlist manager instance. - * @param[out] count The size of the filter array. - * @return An array with filter strings. - */ -PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_handle instance, size_t* count); - -/** - * @brief Applies the current filter list to the existing playlist. - * - * Note this function only removes items. Previously filtered items are not added again. If items - * were removed, the playback history is cleared. - * - * @param instance The playlist manager instance. - * @return The number of removed items. - */ -PROJECTM_PLAYLIST_EXPORT size_t projectm_playlist_apply_filter(projectm_playlist_handle instance); - -#ifdef __cplusplus -} -// extern "C" -#endif diff --git a/src/sdl-test-ui/pmSDL.cpp b/src/sdl-test-ui/pmSDL.cpp index b39102ad0..8e8232384 100644 --- a/src/sdl-test-ui/pmSDL.cpp +++ b/src/sdl-test-ui/pmSDL.cpp @@ -440,7 +440,7 @@ void projectMSDL::renderFrame() glClearColor(0.0, 0.0, 0.0, 0.0); glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT); - projectm_render_frame(_projectM); + projectm_opengl_render_frame(_projectM); SDL_GL_SwapWindow(_sdlWindow); } diff --git a/src/sdl-test-ui/pmSDL.hpp b/src/sdl-test-ui/pmSDL.hpp index ee6aad055..b9a909cde 100644 --- a/src/sdl-test-ui/pmSDL.hpp +++ b/src/sdl-test-ui/pmSDL.hpp @@ -39,8 +39,8 @@ #define STEREOSCOPIC_SBS 0 // projectM +#include