From 3eaa733b8b0bba39deda7fc7bf4dd7093604065c Mon Sep 17 00:00:00 2001 From: Kai Blaschke Date: Mon, 9 Dec 2024 14:07:49 +0100 Subject: [PATCH 1/2] Added the version since each API call is available to Doxygen comments. --- src/api/include/projectM-4/audio.h | 13 +++++--- src/api/include/projectM-4/callbacks.h | 7 ++++- src/api/include/projectM-4/core.h | 9 ++++++ src/api/include/projectM-4/debug.h | 2 ++ src/api/include/projectM-4/memory.h | 3 ++ src/api/include/projectM-4/parameters.h | 30 +++++++++++++++++++ src/api/include/projectM-4/projectM.h | 1 + src/api/include/projectM-4/render_opengl.h | 2 ++ src/api/include/projectM-4/touch.h | 5 ++++ src/api/include/projectM-4/types.h | 4 +++ src/playlist/api/projectM-4/playlist.h | 1 + .../api/projectM-4/playlist_callbacks.h | 5 ++++ src/playlist/api/projectM-4/playlist_core.h | 4 +++ src/playlist/api/projectM-4/playlist_filter.h | 4 +++ src/playlist/api/projectM-4/playlist_items.h | 14 +++++++++ src/playlist/api/projectM-4/playlist_memory.h | 3 ++ .../api/projectM-4/playlist_playback.h | 10 +++++++ src/playlist/api/projectM-4/playlist_types.h | 16 ++++++++-- 18 files changed, 126 insertions(+), 7 deletions(-) diff --git a/src/api/include/projectM-4/audio.h b/src/api/include/projectM-4/audio.h index 23ee09d611..81bbec40f8 100644 --- a/src/api/include/projectM-4/audio.h +++ b/src/api/include/projectM-4/audio.h @@ -2,6 +2,7 @@ * @file audio.h * @copyright 2003-2024 projectM Team * @brief Functions to pass in audio data to libprojectM. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -38,6 +39,7 @@ extern "C" { * are added, only this number of samples is stored and the remainder discarded. * * @return The number of audio samples that are stored, per channel. + * @since 4.0.0 */ PROJECTM_EXPORT unsigned int projectm_pcm_get_max_samples(); @@ -51,10 +53,11 @@ PROJECTM_EXPORT unsigned int projectm_pcm_get_max_samples(); * * @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. + * 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. + * Can be PROJECTM_MONO, PROJECTM_STEREO or the actual numerical channel count. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_pcm_add_float(projectm_handle instance, const float* samples, unsigned int count, projectm_channels channels); @@ -71,7 +74,8 @@ PROJECTM_EXPORT void projectm_pcm_add_float(projectm_handle instance, const floa * @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. + * Can be PROJECTM_MONO, PROJECTM_STEREO or the actual numerical channel count. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_pcm_add_int16(projectm_handle instance, const int16_t* samples, unsigned int count, projectm_channels channels); @@ -88,7 +92,8 @@ PROJECTM_EXPORT void projectm_pcm_add_int16(projectm_handle instance, const int1 * @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. + * Can be PROJECTM_MONO, PROJECTM_STEREO or the actual numerical channel count. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_pcm_add_uint8(projectm_handle instance, const uint8_t* samples, unsigned int count, projectm_channels channels); diff --git a/src/api/include/projectM-4/callbacks.h b/src/api/include/projectM-4/callbacks.h index 64b4c7946d..e652855b29 100644 --- a/src/api/include/projectM-4/callbacks.h +++ b/src/api/include/projectM-4/callbacks.h @@ -2,6 +2,7 @@ * @file callbacks.h * @copyright 2003-2024 projectM Team * @brief Functions and prototypes for projectM callbacks. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -36,7 +37,8 @@ extern "C" { * * @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. + * e.g. context information. + * @since 4.0.0 */ typedef void (*projectm_preset_switch_requested_event)(bool is_hard_cut, void* user_data); @@ -50,6 +52,7 @@ typedef void (*projectm_preset_switch_requested_event)(bool is_hard_cut, void* u * @param message The error message. * @param user_data A user-defined data pointer that was provided when registering the callback, * e.g. context information. + * @since 4.0.0 */ typedef void (*projectm_preset_switch_failed_event)(const char* preset_filename, const char* message, void* user_data); @@ -64,6 +67,7 @@ typedef void (*projectm_preset_switch_failed_event)(const char* preset_filename, * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_preset_switch_requested_event_callback(projectm_handle instance, projectm_preset_switch_requested_event callback, @@ -78,6 +82,7 @@ PROJECTM_EXPORT void projectm_set_preset_switch_requested_event_callback(project * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_handle instance, projectm_preset_switch_failed_event callback, diff --git a/src/api/include/projectM-4/core.h b/src/api/include/projectM-4/core.h index 2188cc505c..53c03b45e4 100644 --- a/src/api/include/projectM-4/core.h +++ b/src/api/include/projectM-4/core.h @@ -2,6 +2,7 @@ * @file core.h * @copyright 2003-2024 projectM Team * @brief Core functions to instantiate, destroy and control projectM. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -39,6 +40,7 @@ extern "C" { * * @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. + * @since 4.0.0 */ PROJECTM_EXPORT projectm_handle projectm_create(); @@ -48,6 +50,7 @@ PROJECTM_EXPORT projectm_handle projectm_create(); * 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(). + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_destroy(projectm_handle instance); @@ -67,6 +70,7 @@ PROJECTM_EXPORT void projectm_destroy(projectm_handle instance); * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_load_preset_file(projectm_handle instance, const char* filename, bool smooth_transition); @@ -83,6 +87,7 @@ PROJECTM_EXPORT void projectm_load_preset_file(projectm_handle instance, const c * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_load_preset_data(projectm_handle instance, const char* data, bool smooth_transition); @@ -94,6 +99,7 @@ PROJECTM_EXPORT void projectm_load_preset_data(projectm_handle instance, const c * Can cause a small delay/lag in rendering. Only use if texture paths were changed. * * @param instance The projectM instance handle. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_reset_textures(projectm_handle instance); @@ -105,6 +111,7 @@ PROJECTM_EXPORT void projectm_reset_textures(projectm_handle instance); * @param major A pointer to an int that will be set to the major version. * @param minor A pointer to an int that will be set to the minor version. * @param patch A pointer to an int that will be set to the patch version. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_get_version_components(int* major, int* minor, int* patch); @@ -115,6 +122,7 @@ PROJECTM_EXPORT void projectm_get_version_components(int* major, int* minor, int * needed. * * @return The library version in the format major.minor.patch. + * @since 4.0.0 */ PROJECTM_EXPORT char* projectm_get_version_string(); @@ -127,6 +135,7 @@ PROJECTM_EXPORT char* projectm_get_version_string(); * needed. * * @return The VCS revision number the projectM library was built from. + * @since 4.0.0 */ PROJECTM_EXPORT char* projectm_get_vcs_version_string(); diff --git a/src/api/include/projectM-4/debug.h b/src/api/include/projectM-4/debug.h index 12c0e8d400..77b6231aef 100644 --- a/src/api/include/projectM-4/debug.h +++ b/src/api/include/projectM-4/debug.h @@ -2,6 +2,7 @@ * @file debug.h * @copyright 2003-2024 projectM Team * @brief Debug functions for both libprojectM and preset developers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -47,6 +48,7 @@ extern "C" { * * @param instance The projectM instance handle. * @param output_file The filename to write the dump to or NULL. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance, const char* output_file); diff --git a/src/api/include/projectM-4/memory.h b/src/api/include/projectM-4/memory.h index 2ff0fb55c2..2e2074eb1a 100644 --- a/src/api/include/projectM-4/memory.h +++ b/src/api/include/projectM-4/memory.h @@ -2,6 +2,7 @@ * @file memory.h * @copyright 2003-2024 projectM Team * @brief Memory allocation/deallocation helpers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -37,6 +38,7 @@ extern "C" { * To free the allocated memory, call projectm_free_string(). Do not use free()! * * @return A pointer to a zero-initialized memory area. + * @since 4.0.0 */ PROJECTM_EXPORT char* projectm_alloc_string(unsigned int length); @@ -49,6 +51,7 @@ PROJECTM_EXPORT char* projectm_alloc_string(unsigned int length); *

Do not use free() to delete the pointer!

* * @param str A pointer returned by projectm_alloc_string(). + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_free_string(const char* str); diff --git a/src/api/include/projectM-4/parameters.h b/src/api/include/projectM-4/parameters.h index 04604abd4c..a72d0c9575 100644 --- a/src/api/include/projectM-4/parameters.h +++ b/src/api/include/projectM-4/parameters.h @@ -2,6 +2,7 @@ * @file parameters.h * @copyright 2003-2024 projectM Team * @brief Functions to set and retrieve all sorts of projectM parameters and setting. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -40,6 +41,7 @@ extern "C" { * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance, const char** texture_search_paths, @@ -63,6 +65,7 @@ PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance, * * @param instance The projectM instance handle. * @param seconds_since_first_frame Any value >= 0 to use user-specified timestamps, values < 0 will use the system clock. + * @since 4.2.0 */ PROJECTM_EXPORT void projectm_set_frame_time(projectm_handle instance, double seconds_since_first_frame); @@ -74,6 +77,7 @@ PROJECTM_EXPORT void projectm_set_frame_time(projectm_handle instance, double se * @param instance The projectM instance handle. * @return Time elapsed since projectM was started, or the value of the user-specified time value used * to render the last frame. + * @since 4.2.0 */ PROJECTM_EXPORT double projectm_get_last_frame_time(projectm_handle instance); @@ -84,6 +88,7 @@ PROJECTM_EXPORT double projectm_get_last_frame_time(projectm_handle instance); * * @param instance The projectM instance handle. * @param sensitivity The sensitivity setting. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, float sensitivity); @@ -91,6 +96,7 @@ PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, flo * @brief Returns the beat sensitivity. * @param instance The projectM instance handle. * @return The current sensitivity setting. + * @since 4.0.0 */ PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance); @@ -104,6 +110,7 @@ PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance); * * @param instance The projectM instance handle. * @param seconds Minimum number of seconds the preset will be displayed before a hard cut. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, double seconds); @@ -111,6 +118,7 @@ PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, do * @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. + * @since 4.0.0 */ PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance); @@ -122,6 +130,7 @@ PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance); * * @param instance The projectM instance handle. * @param enabled True to enable hard cuts, false to disable. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, bool enabled); @@ -129,6 +138,7 @@ PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, boo * @brief Returns whether hard cuts are enabled or not. * @param instance The projectM instance handle. * @return True if hard cuts are enabled, false otherwise. + * @since 4.0.0 */ PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance); @@ -139,6 +149,7 @@ PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance); * * @param instance The projectM instance handle. * @param sensitivity The volume threshold that triggers a hard cut if surpassed. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, float sensitivity); @@ -146,6 +157,7 @@ PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, * @brief Returns the current hard cut sensitivity. * @param instance The projectM instance handle. * @return The current hard cut sensitivity. + * @since 4.0.0 */ PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance); @@ -157,6 +169,7 @@ PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance * * @param instance The projectM instance handle. * @param seconds Time in seconds it takes to smoothly transition from one preset to another. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, double seconds); @@ -164,6 +177,7 @@ PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, do * @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. + * @since 4.0.0 */ PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance); @@ -175,6 +189,7 @@ PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance); * * @param instance The projectM instance handle. * @param seconds The number of seconds a preset will be displayed before the next is shown. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, double seconds); @@ -186,16 +201,20 @@ PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, doub * * @param instance The projectM instance handle. * @return The currently set preset display duration in seconds. + * @since 4.0.0 */ PROJECTM_EXPORT double projectm_get_preset_duration(projectm_handle instance); /** * @brief Sets the per-pixel equation mesh size in units. + * * Will internally be clamped to [8,300] in each axis. If any dimension is set to an odd value, it will be incremented by 1 * so only multiples of two are used. + * * @param instance The projectM instance handle. * @param width The new width of the mesh. * @param height The new height of the mesh. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t width, size_t height); @@ -204,6 +223,7 @@ PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t wid * @param instance The projectM instance handle. * @param width The width of the mesh. * @param height The height of the mesh. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* width, size_t* height); @@ -216,6 +236,7 @@ PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* wi * * @param instance The projectM instance handle. * @param fps The current FPS value projectM is running with. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps); @@ -226,6 +247,7 @@ PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps); * * @param instance The projectM instance handle. * @return The current/average frames per second. + * @since 4.0.0 */ PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance); @@ -237,6 +259,7 @@ PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance); * * @param instance The projectM instance handle. * @param enabled True to enable aspect correction, false to disable it. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bool enabled); @@ -244,6 +267,7 @@ PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bo * @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. + * @since 4.0.0 */ PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance); @@ -258,6 +282,7 @@ PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance); * * @param instance The projectM instance handle. * @param value The new "easter egg" value. Must be greater than zero, otherwise a default sigma value of 1.0 will be used. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float value); @@ -265,6 +290,7 @@ PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float val * @brief Returns the current "easter egg" value. * @param instance The projectM instance handle. * @return The current "easter egg" value. + * @since 4.0.0 */ PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance); @@ -276,6 +302,7 @@ PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance); * * @param instance The projectM instance handle. * @param lock True to lock the current preset, false to enable automatic transitions. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool lock); @@ -283,6 +310,7 @@ PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool l * @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. + * @since 4.0.0 */ PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance); @@ -294,6 +322,7 @@ PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance); * @param instance The projectM instance handle. * @param width New viewport width in pixels. * @param height New viewport height in pixels. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t width, size_t height); @@ -302,6 +331,7 @@ PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t w * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_get_window_size(projectm_handle instance, size_t* width, size_t* height); diff --git a/src/api/include/projectM-4/projectM.h b/src/api/include/projectM-4/projectM.h index 28a01d427a..ba4f70a794 100644 --- a/src/api/include/projectM-4/projectM.h +++ b/src/api/include/projectM-4/projectM.h @@ -2,6 +2,7 @@ * @file projectM.h * @copyright 2003-2024 projectM Team * @brief Convenience include file that includes all other API headers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * diff --git a/src/api/include/projectM-4/render_opengl.h b/src/api/include/projectM-4/render_opengl.h index 348cec0808..c40c7bbdc3 100644 --- a/src/api/include/projectM-4/render_opengl.h +++ b/src/api/include/projectM-4/render_opengl.h @@ -35,6 +35,7 @@ extern "C" { * @brief Renders a single frame. * * @param instance The projectM instance handle. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_opengl_render_frame(projectm_handle instance); @@ -43,6 +44,7 @@ PROJECTM_EXPORT void projectm_opengl_render_frame(projectm_handle instance); * * @param instance The projectM instance handle. * @param framebuffer_object_id The OpenGL FBO ID to render to. + * @since 4.2.0 */ PROJECTM_EXPORT void projectm_opengl_render_frame_fbo(projectm_handle instance, uint32_t framebuffer_object_id); diff --git a/src/api/include/projectM-4/touch.h b/src/api/include/projectM-4/touch.h index aa9a3d46cf..b73c5131e6 100644 --- a/src/api/include/projectM-4/touch.h +++ b/src/api/include/projectM-4/touch.h @@ -2,6 +2,7 @@ * @file touch.h * @copyright 2003-2024 projectM Team * @brief Touch-related functions to add random waveforms. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -43,6 +44,7 @@ extern "C" { * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y, int pressure, projectm_touch_type touch_type); @@ -53,6 +55,7 @@ PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y, * @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. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, float y, int pressure); @@ -61,6 +64,7 @@ PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, floa * @param instance The projectM instance handle. * @param x The last known x touch coordinate. * @param y The last known y touch coordinate. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, float y); @@ -70,6 +74,7 @@ PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, f * Preset-defined waveforms will still be displayed. * * @param instance The projectM instance handle. + * @since 4.0.0 */ PROJECTM_EXPORT void projectm_touch_destroy_all(projectm_handle instance); diff --git a/src/api/include/projectM-4/types.h b/src/api/include/projectM-4/types.h index c33cc8bc76..56b3730645 100644 --- a/src/api/include/projectM-4/types.h +++ b/src/api/include/projectM-4/types.h @@ -2,6 +2,7 @@ * @file types.h * @copyright 2003-2024 projectM Team * @brief Types and enumerations used in the other API headers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -40,6 +41,7 @@ typedef struct projectm* projectm_handle; //!< A pointer to the opaque projectM /** * For specifying audio data format. + * @since 4.0.0 */ typedef enum { @@ -49,6 +51,7 @@ typedef enum /** * Placeholder values that can be used to address channel indices in PCM data arrays. + * @since 4.0.0 */ typedef enum { @@ -60,6 +63,7 @@ typedef enum /** * Waveform render types used in the touch start method. + * @since 4.0.0 */ typedef enum { diff --git a/src/playlist/api/projectM-4/playlist.h b/src/playlist/api/projectM-4/playlist.h index be133b8516..26fb5c3931 100644 --- a/src/playlist/api/projectM-4/playlist.h +++ b/src/playlist/api/projectM-4/playlist.h @@ -2,6 +2,7 @@ * @file playlist.h * @copyright 2003-2024 projectM Team * @brief Optional playlist API for libprojectM. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team diff --git a/src/playlist/api/projectM-4/playlist_callbacks.h b/src/playlist/api/projectM-4/playlist_callbacks.h index 9b9f3529b2..477613c173 100644 --- a/src/playlist/api/projectM-4/playlist_callbacks.h +++ b/src/playlist/api/projectM-4/playlist_callbacks.h @@ -2,6 +2,7 @@ * @file playlist_callbacks.h * @copyright 2003-2024 projectM Team * @brief Functions and prototypes for projectM playlist callbacks. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -42,6 +43,7 @@ extern "C" { * @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. + * @since 4.0.0 */ typedef void (*projectm_playlist_preset_switched_event)(bool is_hard_cut, unsigned int index, void* user_data); @@ -61,6 +63,7 @@ typedef void (*projectm_playlist_preset_switched_event)(bool is_hard_cut, unsign * @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. + * @since 4.0.0 */ typedef void (*projectm_playlist_preset_switch_failed_event)(const char* preset_filename, const char* message, void* user_data); @@ -75,6 +78,7 @@ typedef void (*projectm_playlist_preset_switch_failed_event)(const char* preset_ * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switched_event_callback(projectm_playlist_handle instance, projectm_playlist_preset_switched_event callback, @@ -94,6 +98,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switched_event_callba * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switch_failed_event_callback(projectm_playlist_handle instance, projectm_playlist_preset_switch_failed_event callback, diff --git a/src/playlist/api/projectM-4/playlist_core.h b/src/playlist/api/projectM-4/playlist_core.h index e82ac24b6f..6080c7f7e4 100644 --- a/src/playlist/api/projectM-4/playlist_core.h +++ b/src/playlist/api/projectM-4/playlist_core.h @@ -2,6 +2,7 @@ * @file playlist_core.h * @copyright 2003-2024 projectM Team * @brief Core functions to instantiate, destroy and connect a projectM playlist. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -44,6 +45,7 @@ extern "C" { * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(projectm_handle projectm_instance); @@ -53,6 +55,7 @@ PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(proje * If the playlist manager is currently connected to a projectM instance, it will be disconnected. * * @param instance The playlist manager instance to destroy. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle instance); @@ -71,6 +74,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_connect(projectm_playlist_handle instance, projectm_handle projectm_instance); diff --git a/src/playlist/api/projectM-4/playlist_filter.h b/src/playlist/api/projectM-4/playlist_filter.h index 911e9cec01..d91ae3d357 100644 --- a/src/playlist/api/projectM-4/playlist_filter.h +++ b/src/playlist/api/projectM-4/playlist_filter.h @@ -2,6 +2,7 @@ * @file playlist_filter.h * @copyright 2003-2024 projectM Team * @brief Playlist filter functions. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -67,6 +68,7 @@ extern "C" { * @param instance The playlist manager instance. * @param filter_list An array with filter strings. * @param count The size of the filter array. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_handle instance, const char** filter_list, size_t count); @@ -80,6 +82,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_han * @param instance The playlist manager instance. * @param[out] count The size of the filter array. * @return An array with filter strings. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_handle instance, size_t* count); @@ -91,6 +94,7 @@ PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_h * * @param instance The playlist manager instance. * @return The number of removed items. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT size_t projectm_playlist_apply_filter(projectm_playlist_handle instance); diff --git a/src/playlist/api/projectM-4/playlist_items.h b/src/playlist/api/projectM-4/playlist_items.h index c0cac5efcd..020286ec70 100644 --- a/src/playlist/api/projectM-4/playlist_items.h +++ b/src/playlist/api/projectM-4/playlist_items.h @@ -2,6 +2,7 @@ * @file playlist_items.h * @copyright 2003-2024 projectM Team * @brief Playlist item management functions. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -35,12 +36,14 @@ extern "C" { * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_size(projectm_playlist_handle instance); /** * @brief Clears the playlist. * @param instance The playlist manager instance to clear. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle instance); @@ -60,6 +63,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle i * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle instance, uint32_t start, uint32_t count); @@ -72,6 +76,7 @@ PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle instance, uint32_t index); @@ -90,6 +95,7 @@ PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle i * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_handle instance, const char* path, bool recurse_subdirs, bool allow_duplicates); @@ -112,6 +118,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_h * @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. + * @since 4.0.0 */ 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); @@ -128,6 +135,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_path(projectm_playlis * 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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_handle instance, const char* filename, bool allow_duplicates); @@ -149,6 +157,7 @@ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_han * 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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_handle instance, const char* filename, uint32_t index, bool allow_duplicates); @@ -165,6 +174,7 @@ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_ * 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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlist_handle instance, const char** filenames, uint32_t count, bool allow_duplicates); @@ -186,6 +196,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlis * 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. + * @since 4.0.0 */ 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); @@ -197,6 +208,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_presets(projectm_play * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_handle instance, uint32_t index); @@ -208,6 +220,7 @@ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_ * removed. * @param count The number of presets to remove from the given index. * @return The number of presets removed from the playlist. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_playlist_handle instance, uint32_t index, uint32_t count); @@ -231,6 +244,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_play * @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. + * @since 4.0.0 */ 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); diff --git a/src/playlist/api/projectM-4/playlist_memory.h b/src/playlist/api/projectM-4/playlist_memory.h index aa8560bdaf..40e9d5ed07 100644 --- a/src/playlist/api/projectM-4/playlist_memory.h +++ b/src/playlist/api/projectM-4/playlist_memory.h @@ -2,6 +2,7 @@ * @file playlist_memory.h * @copyright 2003-2024 projectM Team * @brief Memory allocation/deallocation helpers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -38,6 +39,7 @@ extern "C" { * other projectM memory management functions with pointers returned by the playlist library. * * @param string A pointer to a string that should be freed. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string); @@ -48,6 +50,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string); * 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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string_array(char** array); diff --git a/src/playlist/api/projectM-4/playlist_playback.h b/src/playlist/api/projectM-4/playlist_playback.h index dcef349fd8..20ba00bbc3 100644 --- a/src/playlist/api/projectM-4/playlist_playback.h +++ b/src/playlist/api/projectM-4/playlist_playback.h @@ -2,6 +2,7 @@ * @file playlist_playback.h * @copyright 2003-2024 projectM Team * @brief Playback control functions. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -35,6 +36,7 @@ extern "C" { * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_handle instance, bool shuffle); @@ -42,6 +44,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_ha * @brief Retrieves the current state of shuffle mode. * @param instance The playlist manager instance. * @return True if shuffle mode is enabled, false otherwise. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_handle instance); @@ -51,6 +54,7 @@ PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_ha * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlist_handle instance, uint32_t retry_count); @@ -58,6 +62,7 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlis * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_playlist_handle instance); @@ -74,6 +79,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_pla * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playlist_handle instance, uint32_t new_position, bool hard_cut); @@ -82,6 +88,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playli * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playlist_handle instance); @@ -96,6 +103,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playli * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_handle instance, bool hard_cut); @@ -110,6 +118,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_ * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playlist_handle instance, bool hard_cut); @@ -128,6 +137,7 @@ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playl * @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. + * @since 4.0.0 */ PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_last(projectm_playlist_handle instance, bool hard_cut); diff --git a/src/playlist/api/projectM-4/playlist_types.h b/src/playlist/api/projectM-4/playlist_types.h index 4d124491c0..e2ba425f74 100644 --- a/src/playlist/api/projectM-4/playlist_types.h +++ b/src/playlist/api/projectM-4/playlist_types.h @@ -2,6 +2,7 @@ * @file playlist_types.h * @copyright 2003-2024 projectM Team * @brief Types and enumerations used in the playlist API headers. + * @since 4.0.0 * * projectM -- Milkdrop-esque visualisation SDK * Copyright (C)2003-2024 projectM Team @@ -31,11 +32,21 @@ 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. +/** + * Opaque projectM playlist instance type. + * @since 4.0.0 + */ +struct projectm_playlist; + +/** + * A pointer to the opaque projectM playlist instance. + * @since 4.0.0 + */ +typedef struct projectm_playlist* projectm_playlist_handle; /** * Sort predicate for playlist sorting. + * @since 4.0.0 */ typedef enum { @@ -46,6 +57,7 @@ typedef enum /** * Sort order for playlist sorting. + * @since 4.0.0 */ typedef enum { From e90dc28e355b36d41c29d442d1ec27f380d1855e Mon Sep 17 00:00:00 2001 From: Kai Blaschke Date: Mon, 9 Dec 2024 14:20:19 +0100 Subject: [PATCH 2/2] Improve playlist documentation regarding callbacks. Doxygen documentation now mentions that the playlist library will set the preset switch callbacks in projectM and needs them to function properly. Added hints on how to restore functionality if needed. --- src/playlist/api/projectM-4/playlist_core.h | 34 +++++++++++++++------ 1 file changed, 25 insertions(+), 9 deletions(-) diff --git a/src/playlist/api/projectM-4/playlist_core.h b/src/playlist/api/projectM-4/playlist_core.h index 6080c7f7e4..5fb69ddffd 100644 --- a/src/playlist/api/projectM-4/playlist_core.h +++ b/src/playlist/api/projectM-4/playlist_core.h @@ -36,11 +36,18 @@ extern "C" { /** * @brief Creates a playlist manager for the given projectM instance * - * Only one active playlist manager is supported per projectM instance. If multiple playlists use + *

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. + * callbacks from the projectM instance.

* - * To switch to another playlist, use the projectm_playlist_connect() method. + *

To switch to another playlist, use the projectm_playlist_connect() method.

+ * + * @important

If the projectM handle is not NULL, this method will register the playlist manager with the + * projectm_preset_switch_requested_event and projectm_preset_switch_failed_event callbacks + * of the referenced projectM instance. Setting any one of those callbacks to another function pointer + * afterwards will cause the playlist manager to no longer being able to switch presets.

+ *

If the callback needs to be changed temporarily, the playlist functionality can be restored by calling + * projectm_playlist_connect(), which will re-register the callbacks.

* * @param projectm_instance The projectM instance to connect to. Can be a null pointer to leave the newly * created playlist instance unconnected. @@ -52,7 +59,9 @@ PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(proje /** * @brief Destroys a previously created playlist manager. * - * If the playlist manager is currently connected to a projectM instance, it will be disconnected. + * If the playlist manager is currently connected to a projectM instance, it will be disconnected + * by resetting the projectm_preset_switch_requested_event and + * projectm_preset_switch_failed_event callbacks to NULL. * * @param instance The playlist manager instance to destroy. * @since 4.0.0 @@ -62,14 +71,21 @@ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle /** * @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. + *

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 + *

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. + * 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.

+ * + * @important

If the projectM handle is not NULL, this method will register the playlist manager with the + * projectm_preset_switch_requested_event and projectm_preset_switch_failed_event callbacks + * of the referenced projectM instance. Setting any one of those callbacks to another function pointer + * afterwards will cause the playlist manager to no longer being able to switch presets.

+ *

If the callback needs to be changed temporarily, the playlist functionality can be restored by calling + * projectm_playlist_connect(), which will re-register the callbacks.

* * @param instance The playlist manager instance. * @param projectm_instance The projectM instance to connect to. Can be a null pointer to remove