Add API versions and improve playlist API docs

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);

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,

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();
 

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);
 

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);
  * <p>Do not use free() to delete the pointer!</p>
  *
  * @param str A pointer returned by projectm_alloc_string().
+ * @since 4.0.0
  */
 PROJECTM_EXPORT void projectm_free_string(const char* str);