diff --git a/src/api/include/projectM-4/audio.h b/src/api/include/projectM-4/audio.h index 23ee09d61..81bbec40f 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 64b4c7946..e652855b2 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 2188cc505..53c03b45e 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 12c0e8d40..77b6231ae 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 2ff0fb55c..2e2074eb1 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 04604abd4..a72d0c957 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 28a01d427..ba4f70a79 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 348cec080..c40c7bbdc 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 aa9a3d46c..b73c5131e 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 c33cc8bc7..56b373064 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 be133b851..26fb5c393 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 9b9f3529b..477613c17 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 e82ac24b6..5fb69ddff 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 @@ -35,42 +36,61 @@ 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.
+ * + * @importantIf 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. * @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); /** * @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 */ PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle instance); /** * @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.
+ * + * @importantIf 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 * 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 911e9cec0..d91ae3d35 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 c0cac5efc..020286ec7 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 aa8560bda..40e9d5ed0 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 dcef349fd..20ba00bbc 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 4d124491c..e2ba425f7 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 {