mirror/projectm
3
0
Fork 0
mirror of https://github.com/projectM-visualizer/projectm.git synced 2026-02-05 00:35:39 +00:00
Code Issues Projects Releases Wiki Activity

Split up API headers into smaller, categorized files.

Browse Source 
Also updated copyright and prefixed the render-related function with "opengl".
This commit is contained in:
Kai Blaschke
2023-01-18 12:57:57 +01:00
parent 05a2f2a41a
commit 1f33c810b3
28 changed files with 1744 additions and 1127 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
src/api/CMakeLists.txt
View File

@ -3,7 +3,12 @@ add_library(projectM_api INTERFACE)
target_sources(projectM_api
PRIVATE
"${PROJECTM_EXPORT_HEADER}"
include/libprojectM/audio.h
include/libprojectM/callbacks.h
include/libprojectM/debug.h
include/libprojectM/memory.h
include/libprojectM/projectM.h
include/libprojectM/types.h
)
set_target_properties(projectM_api PROPERTIES

99
src/api/include/libprojectM/audio.h Normal file
View File

@ -0,0 +1,99 @@
/**
* @file audio.h
* @copyright 2003-2023 projectM Team
* @brief Functions to pass in audio data to libprojectM.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Returns the maximum number of audio samples that can be stored.
*
* Each PCM data UpdateMeshSize should not exceed this number of samples. If more samples
* are added, only this number of samples is stored and the remainder discarded.
*
* @return The number of audio samples that are stored, per channel.
*/
PROJECTM_EXPORT unsigned int projectm_pcm_get_max_samples();
/**
* @brief Adds 32-bit floating-point audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* Each sample is expected to be within the range -1 to 1.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_float(projectm_handle instance, const float* samples,
unsigned int count, projectm_channels channels);
/**
* @brief Adds 16-bit integer audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_int16(projectm_handle instance, const int16_t* samples,
unsigned int count, projectm_channels channels);
/**
* @brief Adds 8-bit unsigned integer audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_uint8(projectm_handle instance, const uint8_t* samples,
unsigned int count, projectm_channels channels);
#ifdef __cplusplus
} // extern "C"
#endif

89
src/api/include/libprojectM/callbacks.h Normal file
View File

@ -0,0 +1,89 @@
/**
* @file callbacks.h
* @copyright 2003-2023 projectM Team
* @brief Functions and prototypes for projectM callbacks.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Callback function that is executed whenever projectM wants to switch to a new preset.
*
* @param is_hard_cut If true, the transition was triggered by a beat-driven event.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_preset_switch_requested_event)(bool is_hard_cut, void* user_data);
/**
* @brief Callback function that is executed if a preset change failed.
*
* The message and filename pointers are only valid inside the callback. Make a copy if these values
* need to be retained for later use.
*
* @param preset_filename The filename of the failed preset.
* @param message The error message.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_preset_switch_failed_event)(const char* preset_filename,
const char* message, void* user_data);
/**
* @brief Sets a callback function that will be called when a preset change is requested.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* @param instance The projectM instance handle.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_EXPORT void projectm_set_preset_switch_requested_event_callback(projectm_handle instance,
projectm_preset_switch_requested_event callback,
void* user_data);
/**
* @brief Sets a callback function that will be called when a preset change failed.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* @param instance The projectM instance handle.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_handle instance,
projectm_preset_switch_failed_event callback,
void* user_data);
#ifdef __cplusplus
} // extern "C"
#endif

98
src/api/include/libprojectM/core.h Normal file
View File

@ -0,0 +1,98 @@
/**
* @file core.h
* @copyright 2003-2023 projectM Team
* @brief Core functions to instantiate, destroy and control projectM.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Creates a new projectM instance.
* @return A projectM handle for the newly created instance that must be used in subsequent API calls.
* NULL if the instance could not be created successfully.
*/
PROJECTM_EXPORT projectm_handle projectm_create();
/**
* @brief Destroys the given instance and frees the resources.
*
* After destroying the handle, it must not be used for any other calls to the API.
*
* @param instance A handle returned by projectm_create() or projectm_create_settings().
*/
PROJECTM_EXPORT void projectm_destroy(projectm_handle instance);
/**
* @brief Loads a preset from the given filename/URL.
*
* Ideally, the filename should be given as a standard local path. projectM also supports loading
* "file://" URLs. Additionally, the special filename "idle://" can be used to load the default
* idle preset, displaying the "M" logo.
*
* Other URL schemas aren't supported and will cause a loading error.
*
* If the preset can't be loaded, no switch takes place and the current preset will continue to
* be displayed. Note that if there's a transition in progress when calling this function, the
* transition will be finished immediately, even if the new preset can't be loaded.
*
* @param instance The projectM instance handle.
* @param filename The preset filename or URL to load.
* @param smooth_transition If true, the new preset is smoothly blended over.
*/
PROJECTM_EXPORT void projectm_load_preset_file(projectm_handle instance, const char* filename,
bool smooth_transition);
/**
* @brief Loads a preset from the data pointer.
*
* Currently, the preset data is assumed to be in Milkdrop format.
*
* If the preset can't be loaded, no switch takes place and the current preset will continue to
* be displayed. Note that if there's a transition in progress when calling this function, the
* transition will be finished immediately, even if the new preset can't be loaded.
*
* @param instance The projectM instance handle.
* @param data The preset contents to load.
* @param smooth_transition If true, the new preset is smoothly blended over.
*/
PROJECTM_EXPORT void projectm_load_preset_data(projectm_handle instance, const char* data,
bool smooth_transition);
/**
* @brief Reloads all textures.
*
* Calling this method will clear and reload all textures, including the main rendering texture.
* Can cause a small delay/lag in rendering. Only use if texture paths were changed.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_reset_textures(projectm_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif

45
src/api/include/libprojectM/debug.h Normal file
View File

@ -0,0 +1,45 @@
/**
* @file debug.h
* @copyright 2003-2023 projectM Team
* @brief Debug functions for both libprojectM and preset developers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Writes a .bmp framedump after rendering the next main texture, before shaders are applied.
*
* The image is written to the current working directory and is named "frame_texture_contents-[date].bmp".
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif

57
src/api/include/libprojectM/memory.h Normal file
View File

@ -0,0 +1,57 @@
/**
* @file memory.h
* @copyright 2003-2023 projectM Team
* @brief Memory allocation/deallocation helpers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Allocates memory for a string and returns the pointer.
*
* To free the allocated memory, call projectm_free_string(). Do not use free()!
*
* @return A pointer to a zero-initialized memory area.
*/
PROJECTM_EXPORT char* projectm_alloc_string(unsigned int length);
/**
* @brief Frees the memory of an allocated string.
*
* <p>Frees the memory allocated by a call to projectm_alloc_string() or any
* (const) char* pointers returned by a projectM API call.</p>
*
* <p>Do not use free() to delete the pointer!</p>
*
* @param str A pointer returned by projectm_alloc_string().
*/
PROJECTM_EXPORT void projectm_free_string(const char* str);
#ifdef __cplusplus
} // extern "C"
#endif

292
src/api/include/libprojectM/parameters.h Normal file
View File

@ -0,0 +1,292 @@
/**
* @file parameters.h
* @copyright 2003-2023 projectM Team
* @brief Functions to set and retrieve all sorts of projectM parameters and setting.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Sets the texture search paths.
*
* Calling this method will clear and reload all textures, including the main rendering texture.
* Can cause a small delay/lag in rendering. Only use if texture paths were changed.
*
* @param instance The projectM instance handle.
* @param texture_search_paths A list of texture search paths.
* @param count The number of paths in the list.
*/
PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance,
const char** texture_search_paths,
size_t count);
/**
* @brief Changes the size of the internal render texture.
* @note This will recreate the internal renderer.
* @param instance The projectM instance handle.
* @param size The new size of the render texture. Must be a power of 2.
*/
PROJECTM_EXPORT void projectm_set_texture_size(projectm_handle instance, size_t size);
/**
* @brief Returns the size of the internal render texture.
* @param instance The projectM instance handle.
* @return The size of the internal rendering texture.
*/
PROJECTM_EXPORT size_t projectm_get_texture_size(projectm_handle instance);
/**
* @brief Sets the beat sensitivity.
*
* The beat sensitivity to be used.
*
* @param instance The projectM instance handle.
* @param sensitivity The sensitivity setting.
*/
PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, float sensitivity);
/**
* @brief Returns the beat sensitivity.
* @param instance The projectM instance handle.
* @return The current sensitivity setting.
*/
PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance);
/**
* @brief Sets the minimum display time before a hard cut can happen.
*
* <p>Hard cuts are beat-sensitive preset transitions, immediately changing from
* one preset to the next without a smooth blending period.</p>
*
* <p>Set this to a higher value than preset duration to disable hard cuts.</p>
*
* @param instance The projectM instance handle.
* @param seconds Minimum number of seconds the preset will be displayed before a hard cut.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, double seconds);
/**
* @brief Returns the minimum display time before a hard cut can happen.
* @param instance The projectM instance handle.
* @return The minimum number of seconds the preset will be displayed before a hard cut.
*/
PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance);
/**
* @brief Enables or disables hard cuts.
*
* Even if enabled, the hard cut duration must be set to a value lower than the preset duration
* to work properly.
*
* @param instance The projectM instance handle.
* @param enabled True to enable hard cuts, false to disable.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, bool enabled);
/**
* @brief Returns whether hard cuts are enabled or not.
* @param instance The projectM instance handle.
* @return True if hard cuts are enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance);
/**
* @brief Sets the hard cut volume sensitivity.
*
* The beat detection volume difference that must be surpassed to trigger a hard cut.
*
* @param instance The projectM instance handle.
* @param sensitivity The volume threshold that triggers a hard cut if surpassed.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, float sensitivity);
/**
* @brief Returns the current hard cut sensitivity.
* @param instance The projectM instance handle.
* @return The current hard cut sensitivity.
*/
PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance);
/**
* @brief Sets the time in seconds for a soft transition between two presets.
*
* During a soft cut, both presets are rendered and slowly transitioned from one
* to the other.
*
* @param instance The projectM instance handle.
* @param seconds Time in seconds it takes to smoothly transition from one preset to another.
*/
PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, double seconds);
/**
* @brief Returns the time in seconds for a soft transition between two presets.
* @param instance The projectM instance handle.
* @return Time in seconds it takes to smoothly transition from one preset to another.
*/
PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance);
/**
* @brief Sets the preset display duration before switching to the next using a soft cut.
*
* This can be considered as the maximum time a preset is displayed. If this time is reached,
* a smooth cut will be initiated. A hard cut, if any, will always happen before this time.
*
* @param instance The projectM instance handle.
* @param seconds The number of seconds a preset will be displayed before the next is shown.
*/
PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, double seconds);
/**
* @brief Returns the preset display duration before switching to the next using a soft cut.
*
* This can be considered as the maximum time a preset is displayed. If this time is reached,
* a smooth cut will be initiated. A hard cut, if any, will always happen before this time.
*
* @param instance The projectM instance handle.
* @return The currently set preset display duration in seconds.
*/
PROJECTM_EXPORT double projectm_get_preset_duration(projectm_handle instance);
/**
* @brief Sets the per-pixel equation mesh size in units.
* @note This will currently remove any active presets and reload the default "idle" preset.
* @param instance The projectM instance handle.
* @param width The new width of the mesh.
* @param height The new height of the mesh.
*/
PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t width, size_t height);
/**
* @brief Returns the per-pixel equation mesh size in units.
* @param instance The projectM instance handle.
* @param width The width of the mesh.
* @param height The height of the mesh.
*/
PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* width, size_t* height);
/**
* @brief Sets the current/average frames per second.
*
* Applications running projectM should UpdateMeshSize this value regularly and set it to the calculated
* (and possibly averaged) FPS value the output rendered with. The value is passed on to presets,
* which may choose to use it for calculations. It is not used in any other way by the library.
*
* @param instance The projectM instance handle.
* @param fps The current FPS value projectM is running with.
*/
PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps);
/**
* @brief Returns the current/average frames per second.
*
* This value needs to be set by the application. If it wasn't set, a default value of 60 is used.
*
* @param instance The projectM instance handle.
* @return The current/average frames per second.
*/
PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance);
/**
* @brief Enabled or disables aspect ratio correction in presets that support it.
*
* This sets a flag presets can use to aspect-correct rendered shapes, which otherwise would
* be distorted if the viewport isn't exactly square.
*
* @param instance The projectM instance handle.
* @param enabled True to enable aspect correction, false to disable it.
*/
PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bool enabled);
/**
* @brief Returns whether aspect ratio correction is enabled or not.
* @param instance The projectM instance handle.
* @return True if aspect ratio correction is enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance);
/**
* @brief Sets the "easter egg" value.
*
* <p>This doesn't enable any fancy feature, it only influences the randomized display time of presets. It's
* passed as the "sigma" value of the gaussian random number generator used to determine the maximum display time,
* effectively multiplying the generated number of seconds by this amount.</p>
*
* <p>See function sampledPresetDuration() of the TimeKeeper class on how it is used.</p>
*
* @param instance The projectM instance handle.
* @param value The new "easter egg" value.
*/
PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float value);
/**
* @brief Returns the current "easter egg" value.
* @param instance The projectM instance handle.
* @return The current "easter egg" value.
*/
PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance);
/**
* @brief Locks or unlocks the current preset.
*
* Locking effectively disables automatic preset transitions, both hard and soft cuts. Programmatic
* preset switches will still be executed.
*
* @param instance The projectM instance handle.
* @param lock True to lock the current preset, false to enable automatic transitions.
*/
PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool lock);
/**
* @brief Returns whether the current preset is locked or not.
* @param instance The projectM instance handle.
* @return True if the preset lock is enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance);
/**
* @brief Sets the current viewport size in pixels.
*
* Calling this function will reset the OpenGL renderer.
*
* @param instance The projectM instance handle.
* @param width New viewport width in pixels.
* @param height New viewport height in pixels.
*/
PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t width, size_t height);
/**
* @brief Returns the current viewport size in pixels.
* @param instance The projectM instance handle.
* @param width Valid pointer to a size_t variable that will receive the window width value.
* @param height Valid pointer to a size_t variable that will receive the window height value.
*/
PROJECTM_EXPORT void projectm_get_window_size(projectm_handle instance, size_t* width, size_t* height);
#ifdef __cplusplus
} // extern "C"
#endif

587
src/api/include/libprojectM/projectM.h
View File

@ -1,8 +1,9 @@
/**
* @file projectM.h
* @copyright 2003-2023 projectM Team
* @brief Convenience include file that includes all other API headers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2021 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
@ -23,579 +24,11 @@
#pragma once
#include "libprojectM/projectM_export.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#ifdef __cplusplus
extern "C" {
#endif
struct projectm; //!< Opaque projectM instance type.
typedef struct projectm* projectm_handle; //!< A pointer to the opaque projectM instance.
/**
* For specifying audio data format.
*/
typedef enum
{
PROJECTM_MONO = 1,
PROJECTM_STEREO = 2
} projectm_channels;
/**
* Placeholder values that can be used to address channel indices in PCM data arrays.
*/
typedef enum
{
PROJECTM_CHANNEL_L = 0, //!< Left audio channel.
PROJECTM_CHANNEL_0 = 0, //!< Left audio channel.
PROJECTM_CHANNEL_R = 1, //!< Right audio channel.
PROJECTM_CHANNEL_1 = 1 //!< Right audio channel.
} projectm_pcm_channel;
/**
* Waveform render types used in the touch start method.
*/
typedef enum
{
PROJECTM_TOUCH_TYPE_RANDOM, //!< Random waveform type.
PROJECTM_TOUCH_TYPE_CIRCLE, //!< Draws a circular waveform.
PROJECTM_TOUCH_TYPE_RADIAL_BLOB, //!< Draws a radial blob waveform.
PROJECTM_TOUCH_TYPE_BLOB2, //!< Draws a blob-style waveform.
PROJECTM_TOUCH_TYPE_BLOB3, //!< Draws another blob-style waveform.
PROJECTM_TOUCH_TYPE_DERIVATIVE_LINE, //!< Draws a derivative-line waveform.
PROJECTM_TOUCH_TYPE_BLOB5, //!< Draws a five-blob waveform.
PROJECTM_TOUCH_TYPE_LINE, //!< Draws a single-line waveform.
PROJECTM_TOUCH_TYPE_DOUBLE_LINE //!< Draws a double-line waveform.
} projectm_touch_type;
/**
* @brief Allocates memory for a string and returns the pointer.
*
* To free the allocated memory, call projectm_free_string(). Do not use free()!
*
* @return A pointer to a zero-initialized memory area.
*/
PROJECTM_EXPORT char* projectm_alloc_string(unsigned int length);
/**
* @brief Frees the memory of an allocated string.
*
* <p>Frees the memory allocated by a call to projectm_alloc_string() or any
* (const) char* pointers returned by a projectM API call.</p>
*
* <p>Do not use free() to delete the pointer!</p>
*
* @param str A pointer returned by projectm_alloc_string().
*/
PROJECTM_EXPORT void projectm_free_string(const char* str);
/**
* @brief Callback function that is executed whenever projectM wants to switch to a new preset.
*
* @param is_hard_cut If true, the transition was triggered by a beat-driven event.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_preset_switch_requested_event)(bool is_hard_cut, void* user_data);
/**
* @brief Callback function that is executed if a preset change failed.
*
* The message and filename pointers are only valid inside the callback. Make a copy if these values
* need to be retained for later use.
*
* @param preset_filename The filename of the failed preset.
* @param message The error message.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_preset_switch_failed_event)(const char* preset_filename,
const char* message, void* user_data);
/**
* @brief Creates a new projectM instance.
* @return A projectM handle for the newly created instance that must be used in subsequent API calls.
* NULL if the instance could not be created successfully.
*/
PROJECTM_EXPORT projectm_handle projectm_create();
/**
* @brief Destroys the given instance and frees the resources.
*
* After destroying the handle, it must not be used for any other calls to the API.
*
* @param instance A handle returned by projectm_create() or projectm_create_settings().
*/
PROJECTM_EXPORT void projectm_destroy(projectm_handle instance);
/**
* @brief Loads a preset from the given filename/URL.
*
* Ideally, the filename should be given as a standard local path. projectM also supports loading
* "file://" URLs. Additionally, the special filename "idle://" can be used to load the default
* idle preset, displaying the "M" logo.
*
* Other URL schemas aren't supported and will cause a loading error.
*
* If the preset can't be loaded, no switch takes place and the current preset will continue to
* be displayed. Note that if there's a transition in progress when calling this function, the
* transition will be finished immediately, even if the new preset can't be loaded.
*
* @param instance The projectM instance handle.
* @param filename The preset filename or URL to load.
* @param smooth_transition If true, the new preset is smoothly blended over.
*/
PROJECTM_EXPORT void projectm_load_preset_file(projectm_handle instance, const char* filename,
bool smooth_transition);
/**
* @brief Loads a preset from the data pointer.
*
* Currently, the preset data is assumed to be in Milkdrop format.
*
* If the preset can't be loaded, no switch takes place and the current preset will continue to
* be displayed. Note that if there's a transition in progress when calling this function, the
* transition will be finished immediately, even if the new preset can't be loaded.
*
* @param instance The projectM instance handle.
* @param data The preset contents to load.
* @param smooth_transition If true, the new preset is smoothly blended over.
*/
PROJECTM_EXPORT void projectm_load_preset_data(projectm_handle instance, const char* data,
bool smooth_transition);
/**
* @brief Sets a callback function that will be called when a preset change is requested.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* @param instance The projectM instance handle.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_EXPORT void projectm_set_preset_switch_requested_event_callback(projectm_handle instance,
projectm_preset_switch_requested_event callback,
void* user_data);
/**
* @brief Sets a callback function that will be called when a preset change failed.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* @param instance The projectM instance handle.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_EXPORT void projectm_set_preset_switch_failed_event_callback(projectm_handle instance,
projectm_preset_switch_failed_event callback,
void* user_data);
/**
* @brief Sets the texture search paths.
*
* Calling this method will clear and reload all textures, including the main rendering texture.
* Can cause a small delay/lag in rendering. Only use if texture paths were changed.
*
* @param instance The projectM instance handle.
* @param texture_search_paths A list of texture search paths.
* @param count The number of paths in the list.
*/
PROJECTM_EXPORT void projectm_set_texture_search_paths(projectm_handle instance,
const char** texture_search_paths,
size_t count);
/**
* @brief Reloads all textures.
*
* Calling this method will clear and reload all textures, including the main rendering texture.
* Can cause a small delay/lag in rendering. Only use if texture paths were changed.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_reset_textures(projectm_handle instance);
/**
* @brief Renders a single frame.
*
* @note Separate two-pass frame rendering is currently not supported by the C API as it is rarely used
* and also depends on the loaded preset.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_render_frame(projectm_handle instance);
/**
* @brief Enables render-to-texture.
*
* Useful if projectM output will be part of a more complex OpenGL scene. The size of the texture is determined by the
* given viewport size and the dimensions should be a power of 2.
*
* @param instance The projectM instance handle.
* @return A GLuint value with the texture ID projectM will render to.
*/
PROJECTM_EXPORT unsigned int projectm_init_render_to_texture(projectm_handle instance);
/**
* @brief Returns the size of the internal render texture.
* @param instance The projectM instance handle.
* @return The size of the internal rendering texture.
*/
PROJECTM_EXPORT size_t projectm_get_texture_size(projectm_handle instance);
/**
* @brief Changes the size of the internal render texture.
* @note This will recreate the internal renderer.
* @param instance The projectM instance handle.
* @param size The new size of the render texture. Must be a power of 2.
*/
PROJECTM_EXPORT void projectm_set_texture_size(projectm_handle instance, size_t size);
/**
* @brief Sets the beat sensitivity.
*
* The beat sensitivity to be used.
*
* @param instance The projectM instance handle.
* @param sensitivity The sensitivity setting.
*/
PROJECTM_EXPORT void projectm_set_beat_sensitivity(projectm_handle instance, float sensitivity);
/**
* @brief Returns the beat sensitivity.
* @param instance The projectM instance handle.
* @return The current sensitivity setting.
*/
PROJECTM_EXPORT float projectm_get_beat_sensitivity(projectm_handle instance);
/**
* @brief Returns the minimum display time before a hard cut can happen.
* @param instance The projectM instance handle.
* @return The minimum number of seconds the preset will be displayed before a hard cut.
*/
PROJECTM_EXPORT double projectm_get_hard_cut_duration(projectm_handle instance);
/**
* @brief Sets the minimum display time before a hard cut can happen.
*
* <p>Hard cuts are beat-sensitive preset transitions, immediately changing from
* one preset to the next without a smooth blending period.</p>
*
* <p>Set this to a higher value than preset duration to disable hard cuts.</p>
*
* @param instance The projectM instance handle.
* @param seconds Minimum number of seconds the preset will be displayed before a hard cut.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_duration(projectm_handle instance, double seconds);
/**
* @brief Returns whether hard cuts are enabled or not.
* @param instance The projectM instance handle.
* @return True if hard cuts are enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_hard_cut_enabled(projectm_handle instance);
/**
* @brief Enables or disables hard cuts.
*
* Even if enabled, the hard cut duration must be set to a value lower than the preset duration
* to work properly.
*
* @param instance The projectM instance handle.
* @param enabled True to enable hard cuts, false to disable.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_enabled(projectm_handle instance, bool enabled);
/**
* @brief Returns the current hard cut sensitivity.
* @param instance The projectM instance handle.
* @return The current hard cut sensitivity.
*/
PROJECTM_EXPORT float projectm_get_hard_cut_sensitivity(projectm_handle instance);
/**
* @brief Sets the hard cut volume sensitivity.
*
* The beat detection volume difference that must be surpassed to trigger a hard cut.
*
* @param instance The projectM instance handle.
* @param sensitivity The volume threshold that triggers a hard cut if surpassed.
*/
PROJECTM_EXPORT void projectm_set_hard_cut_sensitivity(projectm_handle instance, float sensitivity);
/**
* @brief Returns the time in seconds for a soft transition between two presets.
* @param instance The projectM instance handle.
* @return Time in seconds it takes to smoothly transition from one preset to another.
*/
PROJECTM_EXPORT double projectm_get_soft_cut_duration(projectm_handle instance);
/**
* @brief Sets the time in seconds for a soft transition between two presets.
*
* During a soft cut, both presets are rendered and slowly transitioned from one
* to the other.
*
* @param instance The projectM instance handle.
* @param seconds Time in seconds it takes to smoothly transition from one preset to another.
*/
PROJECTM_EXPORT void projectm_set_soft_cut_duration(projectm_handle instance, double seconds);
/**
* @brief Returns the preset display duration before switching to the next using a soft cut.
*
* This can be considered as the maximum time a preset is displayed. If this time is reached,
* a smooth cut will be initiated. A hard cut, if any, will always happen before this time.
*
* @param instance The projectM instance handle.
* @return The currently set preset display duration in seconds.
*/
PROJECTM_EXPORT double projectm_get_preset_duration(projectm_handle instance);
/**
* @brief Sets the preset display duration before switching to the next using a soft cut.
*
* This can be considered as the maximum time a preset is displayed. If this time is reached,
* a smooth cut will be initiated. A hard cut, if any, will always happen before this time.
*
* @param instance The projectM instance handle.
* @param seconds The number of seconds a preset will be displayed before the next is shown.
*/
PROJECTM_EXPORT void projectm_set_preset_duration(projectm_handle instance, double seconds);
/**
* @brief Returns the per-pixel equation mesh size in units.
* @param instance The projectM instance handle.
* @param width The width of the mesh.
* @param height The height of the mesh.
*/
PROJECTM_EXPORT void projectm_get_mesh_size(projectm_handle instance, size_t* width, size_t* height);
/**
* @brief Sets the per-pixel equation mesh size in units.
* @note This will currently remove any active presets and reload the default "idle" preset.
* @param instance The projectM instance handle.
* @param width The new width of the mesh.
* @param height The new height of the mesh.
*/
PROJECTM_EXPORT void projectm_set_mesh_size(projectm_handle instance, size_t width, size_t height);
/**
* @brief Returns the current/average frames per second.
*
* This value needs to be set by the application. If it wasn't set, a default value of 60 is used.
*
* @param instance The projectM instance handle.
* @return The current/average frames per second.
*/
PROJECTM_EXPORT int32_t projectm_get_fps(projectm_handle instance);
/**
* @brief Sets the current/average frames per second.
*
* Applications running projectM should UpdateMeshSize this value regularly and set it to the calculated
* (and possibly averaged) FPS value the output rendered with. The value is passed on to presets,
* which may choose to use it for calculations. It is not used in any other way by the library.
*
* @param instance The projectM instance handle.
* @param fps The current FPS value projectM is running with.
*/
PROJECTM_EXPORT void projectm_set_fps(projectm_handle instance, int32_t fps);
/**
* @brief Enabled or disables aspect ratio correction in presets that support it.
*
* This sets a flag presets can use to aspect-correct rendered shapes, which otherwise would
* be distorted if the viewport isn't exactly square.
*
* @param instance The projectM instance handle.
* @param enabled True to enable aspect correction, false to disable it.
*/
PROJECTM_EXPORT void projectm_set_aspect_correction(projectm_handle instance, bool enabled);
/**
* @brief Returns whether aspect ratio correction is enabled or not.
* @param instance The projectM instance handle.
* @return True if aspect ratio correction is enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_aspect_correction(projectm_handle instance);
/**
* @brief Sets the "easter egg" value.
*
* <p>This doesn't enable any fancy feature, it only influences the randomized display time of presets. It's
* passed as the "sigma" value of the gaussian random number generator used to determine the maximum display time,
* effectively multiplying the generated number of seconds by this amount.</p>
*
* <p>See function sampledPresetDuration() of the TimeKeeper class on how it is used.</p>
*
* @param instance The projectM instance handle.
* @param value The new "easter egg" value.
*/
PROJECTM_EXPORT void projectm_set_easter_egg(projectm_handle instance, float value);
/**
* @brief Returns the current "easter egg" value.
* @param instance The projectM instance handle.
* @return The current "easter egg" value.
*/
PROJECTM_EXPORT float projectm_get_easter_egg(projectm_handle instance);
/**
* @brief Starts a touch event or moves an existing waveform.
*
* This will add or move waveforms in addition to the preset waveforms. If there is an existing waveform
* at the given coordinates, it will be centered on the new coordinates. If there is no waveform, a new one
* will be added.
*
* @param instance The projectM instance handle.
* @param x The x coordinate of the touch event.
* @param y The y coordinate of the touch event.
* @param pressure The amount of pressure applied in a range from 0.0 to 1.0.
* @param touch_type The waveform type that will be rendered on touch.
*/
PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y,
int pressure, projectm_touch_type touch_type);
/**
* @brief Centers any waveforms under the coordinates to simulate dragging.
* @param instance The projectM instance handle.
* @param x The x coordinate of the drag.
* @param y the y coordinate of the drag.
* @param pressure The amount of pressure applied in a range from 0.0 to 1.0.
*/
PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, float y, int pressure);
/**
* @brief Removes any additional touch waveforms under the given coordinates.
* @param instance The projectM instance handle.
* @param x The last known x touch coordinate.
* @param y The last known y touch coordinate.
*/
PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, float y);
/**
* @brief Removes all touch waveforms from the screen.
*
* Preset-defined waveforms will still be displayed.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_touch_destroy_all(projectm_handle instance);
/**
* @brief Returns whether the current preset is locked or not.
* @param instance The projectM instance handle.
* @return True if the preset lock is enabled, false otherwise.
*/
PROJECTM_EXPORT bool projectm_get_preset_locked(projectm_handle instance);
/**
* @brief Locks or unlocks the current preset.
*
* Locking effectively disables automatic preset transitions, both hard and soft cuts. Programmatic
* preset switches will still be executed.
*
* @param instance The projectM instance handle.
* @param lock True to lock the current preset, false to enable automatic transitions.
*/
PROJECTM_EXPORT void projectm_set_preset_locked(projectm_handle instance, bool lock);
/**
* @brief Returns the current viewport size in pixels.
* @param instance The projectM instance handle.
* @param width Valid pointer to a size_t variable that will receive the window width value.
* @param height Valid pointer to a size_t variable that will receive the window height value.
*/
PROJECTM_EXPORT void projectm_get_window_size(projectm_handle instance, size_t* width, size_t* height);
/**
* @brief Sets the current viewport size in pixels.
*
* Calling this function will reset the OpenGL renderer.
*
* @param instance The projectM instance handle.
* @param width New viewport width in pixels.
* @param height New viewport height in pixels.
*/
PROJECTM_EXPORT void projectm_set_window_size(projectm_handle instance, size_t width, size_t height);
/**
* @brief Returns the maximum number of audio samples that can be stored.
*
* Each PCM data UpdateMeshSize should not exceed this number of samples. If more samples
* are added, only this number of samples is stored and the remainder discarded.
*
* @return The number of audio samples that are stored, per channel.
*/
PROJECTM_EXPORT unsigned int projectm_pcm_get_max_samples();
/**
* @brief Adds 32-bit floating-point audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* Each sample is expected to be within the range -1 to 1.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_float(projectm_handle instance, const float* samples,
unsigned int count, projectm_channels channels);
/**
* @brief Adds 16-bit integer audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_int16(projectm_handle instance, const int16_t* samples,
unsigned int count, projectm_channels channels);
/**
* @brief Adds 8-bit unsigned integer audio samples.
*
* This function is used to add new audio data to projectM's internal audio buffer. It is internally converted
* to 2-channel float data, duplicating the channel.
*
* If stereo, the channel order in samples is LRLRLR.
*
* @param instance The projectM instance handle.
* @param samples An array of PCM samples.
* @param count The number of audio samples in a channel.
* @param channels If the buffer is mono or stereo.
* Can be PROJECTM_MONO or PROJECTM_STEREO.
*/
PROJECTM_EXPORT void projectm_pcm_add_uint8(projectm_handle instance, const uint8_t* samples,
unsigned int count, projectm_channels channels);
/**
* @brief Writes a .bmp framedump after rendering the next main texture, before shaders are applied.
*
* The image is written to the current working directory and is named "frame_texture_contents-[date].bmp".
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_write_debug_image_on_next_frame(projectm_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif
#include "libprojectM/audio.h"
#include "libprojectM/callbacks.h"
#include "libprojectM/core.h"
#include "libprojectM/debug.h"
#include "libprojectM/memory.h"
#include "libprojectM/parameters.h"
#include "libprojectM/render_opengl.h"
#include "libprojectM/touch.h"

57
src/api/include/libprojectM/render_opengl.h Normal file
View File

@ -0,0 +1,57 @@
/**
* @file render_opengl.h
* @copyright 2003-2023 projectM Team
* @brief Functions to configure and render projectM visuals using OpenGL.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Renders a single frame.
*
* @note Separate two-pass frame rendering is currently not supported by the C API as it is rarely used
* and also depends on the loaded preset.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_opengl_render_frame(projectm_handle instance);
/**
* @brief Enables render-to-texture.
*
* Useful if projectM output will be part of a more complex OpenGL scene. The size of the texture is determined by the
* given viewport size and the dimensions should be a power of 2.
*
* @param instance The projectM instance handle.
* @return A GLuint value with the texture ID projectM will render to.
*/
PROJECTM_EXPORT unsigned int projectm_opengl_init_render_to_texture(projectm_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif

78
src/api/include/libprojectM/touch.h Normal file
View File

@ -0,0 +1,78 @@
/**
* @file touch.h
* @copyright 2003-2023 projectM Team
* @brief Touch-related functions to add random waveforms.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Starts a touch event or moves an existing waveform.
*
* This will add or move waveforms in addition to the preset waveforms. If there is an existing waveform
* at the given coordinates, it will be centered on the new coordinates. If there is no waveform, a new one
* will be added.
*
* @param instance The projectM instance handle.
* @param x The x coordinate of the touch event.
* @param y The y coordinate of the touch event.
* @param pressure The amount of pressure applied in a range from 0.0 to 1.0.
* @param touch_type The waveform type that will be rendered on touch.
*/
PROJECTM_EXPORT void projectm_touch(projectm_handle instance, float x, float y,
int pressure, projectm_touch_type touch_type);
/**
* @brief Centers any waveforms under the coordinates to simulate dragging.
* @param instance The projectM instance handle.
* @param x The x coordinate of the drag.
* @param y the y coordinate of the drag.
* @param pressure The amount of pressure applied in a range from 0.0 to 1.0.
*/
PROJECTM_EXPORT void projectm_touch_drag(projectm_handle instance, float x, float y, int pressure);
/**
* @brief Removes any additional touch waveforms under the given coordinates.
* @param instance The projectM instance handle.
* @param x The last known x touch coordinate.
* @param y The last known y touch coordinate.
*/
PROJECTM_EXPORT void projectm_touch_destroy(projectm_handle instance, float x, float y);
/**
* @brief Removes all touch waveforms from the screen.
*
* Preset-defined waveforms will still be displayed.
*
* @param instance The projectM instance handle.
*/
PROJECTM_EXPORT void projectm_touch_destroy_all(projectm_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif

80
src/api/include/libprojectM/types.h Normal file
View File

@ -0,0 +1,80 @@
/**
* @file types.h
* @copyright 2003-2023 projectM Team
* @brief Types and enumerations used in the other API headers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/projectM_export.h"
#ifdef __cplusplus
extern "C" {
#endif
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
struct projectm; //!< Opaque projectM instance type.
typedef struct projectm* projectm_handle; //!< A pointer to the opaque projectM instance.
/**
* For specifying audio data format.
*/
typedef enum
{
PROJECTM_MONO = 1,
PROJECTM_STEREO = 2
} projectm_channels;
/**
* Placeholder values that can be used to address channel indices in PCM data arrays.
*/
typedef enum
{
PROJECTM_CHANNEL_L = 0, //!< Left audio channel.
PROJECTM_CHANNEL_0 = 0, //!< Left audio channel.
PROJECTM_CHANNEL_R = 1, //!< Right audio channel.
PROJECTM_CHANNEL_1 = 1 //!< Right audio channel.
} projectm_pcm_channel;
/**
* Waveform render types used in the touch start method.
*/
typedef enum
{
PROJECTM_TOUCH_TYPE_RANDOM, //!< Random waveform type.
PROJECTM_TOUCH_TYPE_CIRCLE, //!< Draws a circular waveform.
PROJECTM_TOUCH_TYPE_RADIAL_BLOB, //!< Draws a radial blob waveform.
PROJECTM_TOUCH_TYPE_BLOB2, //!< Draws a blob-style waveform.
PROJECTM_TOUCH_TYPE_BLOB3, //!< Draws another blob-style waveform.
PROJECTM_TOUCH_TYPE_DERIVATIVE_LINE, //!< Draws a derivative-line waveform.
PROJECTM_TOUCH_TYPE_BLOB5, //!< Draws a five-blob waveform.
PROJECTM_TOUCH_TYPE_LINE, //!< Draws a single-line waveform.
PROJECTM_TOUCH_TYPE_DOUBLE_LINE //!< Draws a double-line waveform.
} projectm_touch_type;
#ifdef __cplusplus
} // extern "C"
#endif

4
src/libprojectM/ProjectMCWrapper.cpp
View File

@ -134,13 +134,13 @@ void projectm_reset_textures(projectm_handle instance)
projectMInstance->ResetTextures();
}
void projectm_render_frame(projectm_handle instance)
void projectm_opengl_render_frame(projectm_handle instance)
{
auto projectMInstance = handle_to_instance(instance);
projectMInstance->RenderFrame();
}
unsigned int projectm_init_render_to_texture(projectm_handle instance)
unsigned int projectm_opengl_init_render_to_texture(projectm_handle instance)
{
auto projectMInstance = handle_to_instance(instance);
return projectMInstance->InitRenderToTexture();

22
src/playlist/CMakeLists.txt
View File

@ -10,14 +10,22 @@ add_library(projectM_playlist_main OBJECT
Playlist.cpp
Playlist.hpp
PlaylistCWrapper.cpp
PlaylistCWrapper.h
playlist.h
PlaylistCWrapper.hpp
api/libprojectM/playlist.h
api/libprojectM/playlist_callbacks.h
api/libprojectM/playlist_core.h
api/libprojectM/playlist_filter.h
api/libprojectM/playlist_items.h
api/libprojectM/playlist_memory.h
api/libprojectM/playlist_playback.h
api/libprojectM/playlist_types.h
)
target_include_directories(projectM_playlist_main
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/api>
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
)
target_link_libraries(projectM_playlist_main
@ -39,7 +47,7 @@ set_target_properties(projectM_playlist PROPERTIES
target_include_directories(projectM_playlist
PUBLIC
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
$<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/api>
$<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}/include>
"$<INSTALL_INTERFACE:${PROJECTM_INCLUDE_DIR}>"
)
@ -94,12 +102,16 @@ install(TARGETS projectM_playlist
)
install(FILES
playlist.h
"${CMAKE_CURRENT_BINARY_DIR}/include/libprojectM/projectM_playlist_export.h"
DESTINATION "${PROJECTM_INCLUDE_DIR}/libprojectM"
COMPONENT Devel
)
install(DIRECTORY api/libprojectM
DESTINATION "${PROJECTM_INCLUDE_DIR}"
COMPONENT Devel
)
# For use from an installed package (system install, vcpkg, homebrew etc.)
include(CMakePackageConfigHelpers)

5
src/playlist/PlaylistCWrapper.cpp
View File

@ -1,4 +1,7 @@
#include "PlaylistCWrapper.h"
#include "PlaylistCWrapper.hpp"
#include "libprojectM/callbacks.h"
#include "libprojectM/core.h"
using ProjectM::Playlist::Playlist;

2
src/playlist/PlaylistCWrapper.h → src/playlist/PlaylistCWrapper.hpp
View File

@ -1,6 +1,6 @@
#pragma once
#include "playlist.h"
#include "libprojectM/playlist.h"
#include "Playlist.hpp"

34
src/playlist/api/libprojectM/playlist.h Normal file
View File

@ -0,0 +1,34 @@
/**
* @file playlist.h
* @copyright 2003-2023 projectM Team
* @brief Optional playlist API for libprojectM.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_callbacks.h"
#include "libprojectM/playlist_core.h"
#include "libprojectM/playlist_filter.h"
#include "libprojectM/playlist_items.h"
#include "libprojectM/playlist_memory.h"
#include "libprojectM/playlist_playback.h"
#include "libprojectM/playlist_types.h"

103
src/playlist/api/libprojectM/playlist_callbacks.h Normal file
View File

@ -0,0 +1,103 @@
/**
* @file playlist_callbacks.h
* @copyright 2003-2023 projectM Team
* @brief Functions and prototypes for projectM playlist callbacks.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Callback function that is executed on each preset change.
*
* Can be used for example to UpdateMeshSize the application window title. Applications must not
* switch presets inside this callback, as it can lead to infinite recursion.
*
* @param is_hard_cut True if the preset was switched using a hard cut via beat detection.
* @param index The playlist index of the new preset.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_playlist_preset_switched_event)(bool is_hard_cut, unsigned int index,
void* user_data);
/**
* @brief Callback function that is executed if a preset change failed too often.
*
* Similar to the projectM API function, but will only be called if the preset switch failed
* multiple times in a row, e.g. due to missing files or broken presets. The application should
* decide what action to take.
*
* @note Do NOT call any functions that switch presets inside the callback, at it might
* lead to infinite recursion and thus a stack overflow!
* @note The message pointer is only valid inside the callback. Make a copy if it need to be
* retained for later use.
* @param preset_filename The filename of the failed preset.
* @param message The last error message.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_playlist_preset_switch_failed_event)(const char* preset_filename,
const char* message, void* user_data);
/**
* @brief Sets a callback function that will be called when a preset changes.
*
* Only one callback can be registered per playlist instance. To remove the callback, use NULL.
*
* @param instance The playlist manager instance.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switched_event_callback(projectm_playlist_handle instance,
projectm_playlist_preset_switched_event callback,
void* user_data);
/**
* @brief Sets a callback function that will be called when a preset change failed.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* If the application want to receive projectM's analogous callback directly, use the
* projectm_set_preset_switch_failed_event_callback() function after calling
* projectm_playlist_create() or projectm_playlist_connect(), respectively, as these will both
* override the callback set in projectM.
*
* @param instance The playlist manager instance.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switch_failed_event_callback(projectm_playlist_handle instance,
projectm_playlist_preset_switch_failed_event callback,
void* user_data);
#ifdef __cplusplus
} // extern "C"
#endif

79
src/playlist/api/libprojectM/playlist_core.h Normal file
View File

@ -0,0 +1,79 @@
/**
* @file playlist_core.h
* @copyright 2003-2023 projectM Team
* @brief Core functions to instantiate, destroy and connect a projectM playlist.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/types.h"
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Creates a playlist manager for the given projectM instance
*
* Only one active playlist manager is supported per projectM instance. If multiple playlists use
* the same projectM instance, only the last created playlist manager will receive preset change
* callbacks from the projectM instance.
*
* To switch to another playlist, use the projectm_playlist_connect() method.
*
* @param projectm_instance The projectM instance to connect to. Can be a null pointer to leave the newly
* created playlist instance unconnected.
* @return An opaque pointer to the newly created playlist manager instance. Null if creation failed.
*/
PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(projectm_handle projectm_instance);
/**
* @brief Destroys a previously created playlist manager.
*
* If the playlist manager is currently connected to a projectM instance, it will be disconnected.
*
* @param instance The playlist manager instance to destroy.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle instance);
/**
* @brief Connects the playlist manager to a projectM instance.
*
* Sets or removes the preset switch callbacks and stores the projectM instance handle for use with
* manual preset switches via the playlist API.
*
* When switching between multiple playlist managers, first call this method on the last used
* playlist manager with a null pointer for the projectM instance, then call this method with the
* actual projectM instance on the playlist manager that should be activated. It is also safe to
* call projectm_playlist_connect() with a null projectM handle on all playlist manager instances
* before activating a single one with a valid, non-null projectM handle.
*
* @param instance The playlist manager instance.
* @param projectm_instance The projectM instance to connect to. Can be a null pointer to remove
* an existing binding and clear the projectM preset switch callback.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_connect(projectm_playlist_handle instance, projectm_handle projectm_instance);
#ifdef __cplusplus
} // extern "C"
#endif

99
src/playlist/api/libprojectM/playlist_filter.h Normal file
View File

@ -0,0 +1,99 @@
/**
* @file playlist_filter.h
* @copyright 2003-2023 projectM Team
* @brief Playlist filter functions.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Sets a new filter list.
*
* <p>Does not immediately apply the new list to an existing playlist, only newly added files
* will be affected. If you need to filter the existing playlist after calling this method,
* additionally call projectm_playlist_apply_filter() afterwards.</p>
*
* <p>The filter list consists of simple globbing expressions similar to the .gitignore syntax:</p>
*
* <ul>
* <li><strong>?</strong>: Matches any single character except /.</li>
* <li><strong>*</strong>: Matches 0 or more characters except /.</li>
* <li><strong>/</strong>: When used at the begin of a glob, matches if
* pathname has no path separator.</li>
* <li><strong>**&zwj;/</strong>: Matches 0 or more directories.</li>
* <li><strong>/&zwj;**</strong>: When at the end of the glob, matches everything after the /.</li>
* </ul>
*
* <p>In globbing expressions, \\ can be used as path separator instead of /. The backslash can't
* be used to escape globbing patterns, so matching literal * and ? in filenames is not possible.
* This is not a huge issue as Windows doesn't allow those characters in filenames and Milkdrop
* files originate from the Windows world. Character classes like "[0-9]" are also not supported to
* keep the syntax simple.</p>
*
* <p>Each line can be prefixed with either + or - to either include files matching the pattern
* or excluding them. Any other character is not interpreted as a prefix and the filter line is
* matching as an exclude filter. To match a literal + or - at the beginning, add the appropriate
* prefix in front. Empty filters never match anything, even if the filename is empty.</p>
*
* <p>The filter list is checked in order. The first pattern that matches the filename determines
* the filter result (include or exclude). If no pattern matches, the file is included. In the case
* that a default exclude action is required, add a "-/&zwj;**" filter at the end of the list.</p>
*
* @param instance The playlist manager instance.
* @param filter_list An array with filter strings.
* @param count The size of the filter array.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_handle instance, const char** filter_list,
size_t count);
/**
* @brief Returns the current filter list.
*
* Always call projectm_playlist_free_string_array() on the returned pointer if the data is
* no longer needed.
*
* @param instance The playlist manager instance.
* @param[out] count The size of the filter array.
* @return An array with filter strings.
*/
PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_handle instance, size_t* count);
/**
* @brief Applies the current filter list to the existing playlist.
*
* Note this function only removes items. Previously filtered items are not added again. If items
* were removed, the playback history is cleared.
*
* @param instance The playlist manager instance.
* @return The number of removed items.
*/
PROJECTM_PLAYLIST_EXPORT size_t projectm_playlist_apply_filter(projectm_playlist_handle instance);
#ifdef __cplusplus
} // extern "C"
#endif

241
src/playlist/api/libprojectM/playlist_items.h Normal file
View File

@ -0,0 +1,241 @@
/**
* @file playlist_items.h
* @copyright 2003-2023 projectM Team
* @brief Playlist item management functions.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Returns the number of presets in the current playlist.
* @param instance The playlist manager instance.
* @return The number of presets in the current playlist.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_size(projectm_playlist_handle instance);
/**
* @brief Clears the playlist.
* @param instance The playlist manager instance to clear.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle instance);
/**
* @brief Returns a list of preset files inside the given range of the current playlist, in order.
*
* This function can be used to return the whole playlist to save it to a file, or just a part of
* it for use in virtual lists. If less elements than given in @a count are available, only the
* remainder of items after the starting index are returned. If the starting index equals or exceeds
* the playlist size, an empty list is returned.
*
* @note Call projectm_playlist_free_string_array() when you're done using the list.
* @note Ideally, don't rely on the value provided as count to iterate over the filenames.
* Instead, look for the terminating null pointer to abort the loop.
* @param instance The playlist manager instance.
* @param start The zero-based starting index of the range to return.
* @param count The maximum number if items to return.
* @return A pointer to a list of char pointers, each containing a single preset. The last entry
* is denoted by a null pointer.
*/
PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle instance, uint32_t start, uint32_t count);
/**
* @brief Returns the name of a preset at the given index in the current playlist.
* @note Call projectm_playlist_free_string() when you're done using the return value.
* @note If you need to retrieve a major part of playlist filenames, use projectm_playlist_items()
* instead.
* @param instance The playlist manager instance.
* @param index The index to retrieve the filename for.
* @return The filename of the requested preset, or NULL if the index was out of bounds or the
* playlist is empty.
*/
PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle instance, uint32_t index);
/**
* @brief Appends presets from the given path to the end of the current playlist.
*
* This method will scan the given path for files with a ".milk" extension and add these to the
* playlist.
*
* Symbolic links are not followed.
*
* @param instance The playlist manager instance.
* @param path A local filesystem path to scan for presets.
* @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false,
* only the exact path given is searched for presets.
* @param allow_duplicates If true, files found will always be added. If false, only files are
* added that do not already exist in the current playlist.
* @return The number of files added. 0 may indicate issues scanning the path.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_handle instance, const char* path,
bool recurse_subdirs, bool allow_duplicates);
/**
* @brief Inserts presets from the given path to the end of the current playlist.
*
* This method will scan the given path for files with a ".milk" extension and add these to the
* playlist.
*
* Symbolic links are not followed.
*
* @param instance The playlist manager instance.
* @param path A local filesystem path to scan for presets.
* @param index The index to insert the presets at. If it exceeds the playlist size, the presets are
* added at the end of the playlist.
* @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false,
* only the exact path given is searched for presets.
* @param allow_duplicates If true, files found will always be added. If false, only files are
* added that do not already exist in the current playlist.
* @return The number of files added. 0 may indicate issues scanning the path.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_path(projectm_playlist_handle instance, const char* path,
uint32_t index, bool recurse_subdirs, bool allow_duplicates);
/**
* @brief Adds a single preset to the end of the playlist.
*
* @note The file is not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filename A local preset filename.
* @param allow_duplicates If true, the preset filename will always be added. If false, the preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return True if the file was added to the playlist, false if the file was a duplicate and
* allow_duplicates was set to false.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_handle instance, const char* filename,
bool allow_duplicates);
/**
* @brief Adds a single preset to the playlist at the specified position.
*
* To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is
* performs better.
*
* @note The file is not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filename A local preset filename.
* @param index The index to insert the preset at. If it exceeds the playlist size, the preset is
* added at the end of the playlist.
* @param allow_duplicates If true, the preset filename will always be added. If false, the preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return True if the file was added to the playlist, false if the file was a duplicate and
* allow_duplicates was set to false.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_handle instance, const char* filename,
uint32_t index, bool allow_duplicates);
/**
* @brief Adds a list of presets to the end of the playlist.
*
* @note The files are not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filenames A list of local preset filenames.
* @param count The number of files in the list.
* @param allow_duplicates If true, the preset filenames will always be added. If false, a preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return The number of files added to the playlist. Ranges between 0 and count.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlist_handle instance, const char** filenames,
uint32_t count, bool allow_duplicates);
/**
* @brief Adds a single preset to the playlist at the specified position.
*
* To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is
* performs better.
*
* @note The files are not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filenames A list of local preset filenames.
* @param count The number of files in the list.
* @param index The index to insert the presets at. If it exceeds the playlist size, the presets are
* added at the end of the playlist.
* @param allow_duplicates If true, the preset filenames will always be added. If false, a preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return The number of files added to the playlist. Ranges between 0 and count.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_presets(projectm_playlist_handle instance, const char** filenames,
uint32_t count, unsigned int index, bool allow_duplicates);
/**
* @brief Removes a single preset from the playlist at the specified position.
*
* @param instance The playlist manager instance.
* @param index The preset index to remove. If it exceeds the playlist size, no preset will be
* removed.
* @return True if the preset was removed from the playlist, false if the index was out of range.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_handle instance, uint32_t index);
/**
* @brief Removes a number of presets from the playlist from the specified position.
*
* @param instance The playlist manager instance.
* @param index The first preset index to remove. If it exceeds the playlist size, no preset will be
* removed.
* @param count The number of presets to remove from the given index.
* @return The number of presets removed from the playlist.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_playlist_handle instance, uint32_t index,
uint32_t count);
/**
* @brief Sorts part or the whole playlist according to the given predicate and order.
*
* It is safe to provide values in start_index and count that will exceed the number of items
* in the playlist. Only items that fall into an existing index range are sorted. If start_index
* is equal to or larger than the playlist size, no items are sorted. If start_index is inside the
* playlist, but adding count results in an index outside the playlist, items until the end are
* sorted.
*
* Sort order is lexicographical for both predicates and case-sensitive.
*
* If invalid values are provides as predicate or order, the defaults as mentioned in the parameter
* description are used.
*
* @param instance The playlist manager instance.
* @param start_index The starting index to begin sorting at.
* @param count The number of items, beginning at start_index, to sort.
* @param predicate The predicate to use for sorting. Default is SORT_PREDICATE_FULL_PATH.
* @param order The sort order. Default is SORT_ORDER_ASCENDING.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_sort(projectm_playlist_handle instance, uint32_t start_index, uint32_t count,
projectm_playlist_sort_predicate predicate, projectm_playlist_sort_order order);
#ifdef __cplusplus
} // extern "C"
#endif

56
src/playlist/api/libprojectM/playlist_memory.h Normal file
View File

@ -0,0 +1,56 @@
/**
* @file playlist_memory.h
* @copyright 2003-2023 projectM Team
* @brief Memory allocation/deallocation helpers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Frees a char pointer returned by any of the playlist API functions.
*
* Please only use this function with char pointers returned by the playlist library, and don't use
* other projectM memory management functions with pointers returned by the playlist library.
*
* @param string A pointer to a string that should be freed.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string);
/**
* @brief Frees a string array returned by any of the playlist API functions.
*
* Please only use this function with pointers returned by the playlist library, and don't use
* other projectM memory management functions with pointers returned by the playlist library.
*
* @param array The pointer to the array of strings that should be freed.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string_array(char** array);
#ifdef __cplusplus
} // extern "C"
#endif

136
src/playlist/api/libprojectM/playlist_playback.h Normal file
View File

@ -0,0 +1,136 @@
/**
* @file playlist_playback.h
* @copyright 2003-2023 projectM Team
* @brief Playback control functions.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/playlist_types.h"
#ifdef __cplusplus
extern "C" {
#endif
/**
* @brief Enable or disable shuffle mode.
* @param instance The playlist manager instance.
* @param shuffle True to enable random shuffling, false to play presets in playlist order.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_handle instance, bool shuffle);
/**
* @brief Retrieves the current state of shuffle mode.
* @param instance The playlist manager instance.
* @return True if shuffle mode is enabled, false otherwise.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_handle instance);
/**
* @brief Sets the number of retries after failed preset switches.
* @note Don't set this value too high, as each retry is done recursively.
* @param instance The playlist manager instance.
* @param retry_count The number of retries after failed preset switches. Default is 5. Set to 0
* to simply forward the failure event from projectM.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlist_handle instance, uint32_t retry_count);
/**
* @brief Returns the number of retries after failed preset switches.
* @param instance The playlist manager instance.
* @return The number of retries after failed preset switches.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_playlist_handle instance);
/**
* @brief Plays the preset at the requested playlist position and returns the actual playlist index.
*
* If the requested position is out of bounds, the returned position will wrap to 0, effectively
* repeating the playlist as if shuffle was disabled. It has no effect if the playlist is empty.
*
* This method ignores the shuffle setting and will always jump to the requested index, given it is
* withing playlist bounds.
*
* @param instance The playlist manager instance.
* @param new_position The new position to jump to.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playlist_handle instance, uint32_t new_position,
bool hard_cut);
/**
* @brief Returns the current playlist position.
* @param instance The playlist manager instance.
* @return The current playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playlist_handle instance);
/**
* @brief Plays the next playlist item and returns the index of the new preset.
*
* If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the
* end of the playlist is reached in continuous mode, it will wrap back to 0.
*
* The old playlist item is added to the history.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_handle instance, bool hard_cut);
/**
* @brief Plays the previous playlist item and returns the index of the new preset.
*
* If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the
* end of the playlist is reached in continuous mode, it will wrap back to 0.
*
* The old playlist item is added to the history.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playlist_handle instance, bool hard_cut);
/**
* @brief Plays the last preset played in the history and returns the index of the preset.
*
* The history keeps track of the last 1000 presets and will go back in the history. The
* playback history will be cleared whenever the playlist items are changed.
*
* If the history is empty, this call behaves identical to projectm_playlist_play_previous(),
* but the item is not added to the history.
*
* Presets which failed to load are not recorded in the history and thus will be skipped when
* calling this method.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_last(projectm_playlist_handle instance, bool hard_cut);
#ifdef __cplusplus
} // extern "C"
#endif

58
src/playlist/api/libprojectM/playlist_types.h Normal file
View File

@ -0,0 +1,58 @@
/**
* @file playlist_types.h
* @copyright 2003-2023 projectM Team
* @brief Types and enumerations used in the playlist API headers.
*
* projectM -- Milkdrop-esque visualisation SDK
* Copyright (C)2003-2023 projectM Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
* See 'LICENSE.txt' included within this release
*
*/
#pragma once
#include "libprojectM/projectM_playlist_export.h"
#ifdef __cplusplus
extern "C" {
#endif
struct projectm_playlist; //!< Opaque projectM playlist instance type.
typedef struct projectm_playlist* projectm_playlist_handle; //!< A pointer to the opaque projectM playlist instance.
/**
* Sort predicate for playlist sorting.
*/
typedef enum
{
SORT_PREDICATE_FULL_PATH, //!< Sort by full path name
SORT_PREDICATE_FILENAME_ONLY //!< Sort only by preset filename
} projectm_playlist_sort_predicate;
/**
* Sort order for playlist sorting.
*/
typedef enum
{
SORT_ORDER_ASCENDING, //!< Sort in alphabetically ascending order.
SORT_ORDER_DESCENDING //!< Sort in alphabetically descending order.
} projectm_playlist_sort_order;
#ifdef __cplusplus
} // extern "C"
#endif

537
src/playlist/playlist.h
View File

@ -1,537 +0,0 @@
/**
* @file playlist.h
*
* Optional playlist API for libprojectM.
*/
#pragma once
#include "libprojectM/projectM.h"
#include "libprojectM/projectM_playlist_export.h"
#ifdef __cplusplus
extern "C" {
#endif
struct projectm_playlist; //!< Opaque projectM playlist instance type.
typedef struct projectm_playlist* projectm_playlist_handle; //!< A pointer to the opaque projectM playlist instance.
/**
* Sort predicate for playlist sorting.
*/
typedef enum
{
SORT_PREDICATE_FULL_PATH, //!< Sort by full path name
SORT_PREDICATE_FILENAME_ONLY //!< Sort only by preset filename
} projectm_playlist_sort_predicate;
/**
* Sort order for playlist sorting.
*/
typedef enum
{
SORT_ORDER_ASCENDING, //!< Sort in alphabetically ascending order.
SORT_ORDER_DESCENDING //!< Sort in alphabetically descending order.
} projectm_playlist_sort_order;
/**
* @brief Frees a char pointer returned by any of the playlist API functions.
*
* Please only use this function with char pointers returned by the playlist library, and don't use
* other projectM memory management functions with pointers returned by the playlist library.
*
* @param string A pointer to a string that should be freed.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string(char* string);
/**
* @brief Frees a string array returned by any of the playlist API functions.
*
* Please only use this function with pointers returned by the playlist library, and don't use
* other projectM memory management functions with pointers returned by the playlist library.
*
* @param array The pointer to the array of strings that should be freed.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_free_string_array(char** array);
/**
* @brief Callback function that is executed on each preset change.
*
* Can be used for example to UpdateMeshSize the application window title. Applications must not
* switch presets inside this callback, as it can lead to infinite recursion.
*
* @param is_hard_cut True if the preset was switched using a hard cut via beat detection.
* @param index The playlist index of the new preset.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_playlist_preset_switched_event)(bool is_hard_cut, unsigned int index,
void* user_data);
/**
* @brief Callback function that is executed if a preset change failed too often.
*
* Similar to the projectM API function, but will only be called if the preset switch failed
* multiple times in a row, e.g. due to missing files or broken presets. The application should
* decide what action to take.
*
* @note Do NOT call any functions that switch presets inside the callback, at it might
* lead to infinite recursion and thus a stack overflow!
* @note The message pointer is only valid inside the callback. Make a copy if it need to be
* retained for later use.
* @param preset_filename The filename of the failed preset.
* @param message The last error message.
* @param user_data A user-defined data pointer that was provided when registering the callback,
* e.g. context information.
*/
typedef void (*projectm_playlist_preset_switch_failed_event)(const char* preset_filename,
const char* message, void* user_data);
/**
* @brief Creates a playlist manager for the given projectM instance
*
* Only one active playlist manager is supported per projectM instance. If multiple playlists use
* the same projectM instance, only the last created playlist manager will receive preset change
* callbacks from the projectM instance.
*
* To switch to another playlist, use the projectm_playlist_connect() method.
*
* @param projectm_instance The projectM instance to connect to. Can be a null pointer to leave the newly
* created playlist instance unconnected.
* @return An opaque pointer to the newly created playlist manager instance. Null if creation failed.
*/
PROJECTM_PLAYLIST_EXPORT projectm_playlist_handle projectm_playlist_create(projectm_handle projectm_instance);
/**
* @brief Destroys a previously created playlist manager.
*
* If the playlist manager is currently connected to a projectM instance, it will be disconnected.
*
* @param instance The playlist manager instance to destroy.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_destroy(projectm_playlist_handle instance);
/**
* @brief Sets a callback function that will be called when a preset changes.
*
* Only one callback can be registered per playlist instance. To remove the callback, use NULL.
*
* @param instance The playlist manager instance.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switched_event_callback(projectm_playlist_handle instance,
projectm_playlist_preset_switched_event callback,
void* user_data);
/**
* @brief Sets a callback function that will be called when a preset change failed.
*
* Only one callback can be registered per projectM instance. To remove the callback, use NULL.
*
* If the application want to receive projectM's analogous callback directly, use the
* projectm_set_preset_switch_failed_event_callback() function after calling
* projectm_playlist_create() or projectm_playlist_connect(), respectively, as these will both
* override the callback set in projectM.
*
* @param instance The playlist manager instance.
* @param callback A pointer to the callback function.
* @param user_data A pointer to any data that will be sent back in the callback, e.g. context
* information.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_preset_switch_failed_event_callback(projectm_playlist_handle instance,
projectm_playlist_preset_switch_failed_event callback,
void* user_data);
/**
* @brief Connects the playlist manager to a projectM instance.
*
* Sets or removes the preset switch callbacks and stores the projectM instance handle for use with
* manual preset switches via the playlist API.
*
* When switching between multiple playlist managers, first call this method on the last used
* playlist manager with a null pointer for the projectM instance, then call this method with the
* actual projectM instance on the playlist manager that should be activated. It is also safe to
* call projectm_playlist_connect() with a null projectM handle on all playlist manager instances
* before activating a single one with a valid, non-null projectM handle.
*
* @param instance The playlist manager instance.
* @param projectm_instance The projectM instance to connect to. Can be a null pointer to remove
* an existing binding and clear the projectM preset switch callback.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_connect(projectm_playlist_handle instance, projectm_handle projectm_instance);
/**
* @brief Returns the number of presets in the current playlist.
* @param instance The playlist manager instance.
* @return The number of presets in the current playlist.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_size(projectm_playlist_handle instance);
/**
* @brief Clears the playlist.
* @param instance The playlist manager instance to clear.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_clear(projectm_playlist_handle instance);
/**
* @brief Returns a list of preset files inside the given range of the current playlist, in order.
*
* This function can be used to return the whole playlist to save it to a file, or just a part of
* it for use in virtual lists. If less elements than given in @a count are available, only the
* remainder of items after the starting index are returned. If the starting index equals or exceeds
* the playlist size, an empty list is returned.
*
* @note Call projectm_playlist_free_string_array() when you're done using the list.
* @note Ideally, don't rely on the value provided as count to iterate over the filenames.
* Instead, look for the terminating null pointer to abort the loop.
* @param instance The playlist manager instance.
* @param start The zero-based starting index of the range to return.
* @param count The maximum number if items to return.
* @return A pointer to a list of char pointers, each containing a single preset. The last entry
* is denoted by a null pointer.
*/
PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_items(projectm_playlist_handle instance, uint32_t start, uint32_t count);
/**
* @brief Returns the name of a preset at the given index in the current playlist.
* @note Call projectm_playlist_free_string() when you're done using the return value.
* @note If you need to retrieve a major part of playlist filenames, use projectm_playlist_items()
* instead.
* @param instance The playlist manager instance.
* @param index The index to retrieve the filename for.
* @return The filename of the requested preset, or NULL if the index was out of bounds or the
* playlist is empty.
*/
PROJECTM_PLAYLIST_EXPORT char* projectm_playlist_item(projectm_playlist_handle instance, uint32_t index);
/**
* @brief Appends presets from the given path to the end of the current playlist.
*
* This method will scan the given path for files with a ".milk" extension and add these to the
* playlist.
*
* Symbolic links are not followed.
*
* @param instance The playlist manager instance.
* @param path A local filesystem path to scan for presets.
* @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false,
* only the exact path given is searched for presets.
* @param allow_duplicates If true, files found will always be added. If false, only files are
* added that do not already exist in the current playlist.
* @return The number of files added. 0 may indicate issues scanning the path.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_path(projectm_playlist_handle instance, const char* path,
bool recurse_subdirs, bool allow_duplicates);
/**
* @brief Inserts presets from the given path to the end of the current playlist.
*
* This method will scan the given path for files with a ".milk" extension and add these to the
* playlist.
*
* Symbolic links are not followed.
*
* @param instance The playlist manager instance.
* @param path A local filesystem path to scan for presets.
* @param index The index to insert the presets at. If it exceeds the playlist size, the presets are
* added at the end of the playlist.
* @param recurse_subdirs If true, subdirectories of the given path will also be scanned. If false,
* only the exact path given is searched for presets.
* @param allow_duplicates If true, files found will always be added. If false, only files are
* added that do not already exist in the current playlist.
* @return The number of files added. 0 may indicate issues scanning the path.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_path(projectm_playlist_handle instance, const char* path,
uint32_t index, bool recurse_subdirs, bool allow_duplicates);
/**
* @brief Adds a single preset to the end of the playlist.
*
* @note The file is not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filename A local preset filename.
* @param allow_duplicates If true, the preset filename will always be added. If false, the preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return True if the file was added to the playlist, false if the file was a duplicate and
* allow_duplicates was set to false.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_add_preset(projectm_playlist_handle instance, const char* filename,
bool allow_duplicates);
/**
* @brief Adds a single preset to the playlist at the specified position.
*
* To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is
* performs better.
*
* @note The file is not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filename A local preset filename.
* @param index The index to insert the preset at. If it exceeds the playlist size, the preset is
* added at the end of the playlist.
* @param allow_duplicates If true, the preset filename will always be added. If false, the preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return True if the file was added to the playlist, false if the file was a duplicate and
* allow_duplicates was set to false.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_insert_preset(projectm_playlist_handle instance, const char* filename,
uint32_t index, bool allow_duplicates);
/**
* @brief Adds a list of presets to the end of the playlist.
*
* @note The files are not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filenames A list of local preset filenames.
* @param count The number of files in the list.
* @param allow_duplicates If true, the preset filenames will always be added. If false, a preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return The number of files added to the playlist. Ranges between 0 and count.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_add_presets(projectm_playlist_handle instance, const char** filenames,
uint32_t count, bool allow_duplicates);
/**
* @brief Adds a single preset to the playlist at the specified position.
*
* To always add a file at the end of the playlist, use projectm_playlist_add_preset() as it is
* performs better.
*
* @note The files are not checked for existence or for being readable.
*
* @param instance The playlist manager instance.
* @param filenames A list of local preset filenames.
* @param count The number of files in the list.
* @param index The index to insert the presets at. If it exceeds the playlist size, the presets are
* added at the end of the playlist.
* @param allow_duplicates If true, the preset filenames will always be added. If false, a preset
* is only added to the playlist if the exact filename doesn't exist in the
* current playlist.
* @return The number of files added to the playlist. Ranges between 0 and count.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_insert_presets(projectm_playlist_handle instance, const char** filenames,
uint32_t count, unsigned int index, bool allow_duplicates);
/**
* @brief Removes a single preset from the playlist at the specified position.
*
* @param instance The playlist manager instance.
* @param index The preset index to remove. If it exceeds the playlist size, no preset will be
* removed.
* @return True if the preset was removed from the playlist, false if the index was out of range.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_remove_preset(projectm_playlist_handle instance, uint32_t index);
/**
* @brief Removes a number of presets from the playlist from the specified position.
*
* @param instance The playlist manager instance.
* @param index The first preset index to remove. If it exceeds the playlist size, no preset will be
* removed.
* @param count The number of presets to remove from the given index.
* @return The number of presets removed from the playlist.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_remove_presets(projectm_playlist_handle instance, uint32_t index,
uint32_t count);
/**
* @brief Retrieves the current state of shuffle mode.
* @param instance The playlist manager instance.
* @return True if shuffle mode is enabled, false otherwise.
*/
PROJECTM_PLAYLIST_EXPORT bool projectm_playlist_get_shuffle(projectm_playlist_handle instance);
/**
* @brief Enable or disable shuffle mode.
* @param instance The playlist manager instance.
* @param shuffle True to enable random shuffling, false to play presets in playlist order.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_shuffle(projectm_playlist_handle instance, bool shuffle);
/**
* @brief Sorts part or the whole playlist according to the given predicate and order.
*
* It is safe to provide values in start_index and count that will exceed the number of items
* in the playlist. Only items that fall into an existing index range are sorted. If start_index
* is equal to or larger than the playlist size, no items are sorted. If start_index is inside the
* playlist, but adding count results in an index outside the playlist, items until the end are
* sorted.
*
* Sort order is lexicographical for both predicates and case-sensitive.
*
* If invalid values are provides as predicate or order, the defaults as mentioned in the parameter
* description are used.
*
* @param instance The playlist manager instance.
* @param start_index The starting index to begin sorting at.
* @param count The number of items, beginning at start_index, to sort.
* @param predicate The predicate to use for sorting. Default is SORT_PREDICATE_FULL_PATH.
* @param order The sort order. Default is SORT_ORDER_ASCENDING.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_sort(projectm_playlist_handle instance, uint32_t start_index, uint32_t count,
projectm_playlist_sort_predicate predicate, projectm_playlist_sort_order order);
/**
* @brief Returns the number of retries after failed preset switches.
* @param instance The playlist manager instance.
* @return The number of retries after failed preset switches.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_retry_count(projectm_playlist_handle instance);
/**
* @brief Sets the number of retries after failed preset switches.
* @note Don't set this value too high, as each retry is done recursively.
* @param instance The playlist manager instance.
* @param retry_count The number of retries after failed preset switches. Default is 5. Set to 0
* to simply forward the failure event from projectM.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_retry_count(projectm_playlist_handle instance, uint32_t retry_count);
/**
* @brief Returns the current playlist position.
* @param instance The playlist manager instance.
* @return The current playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_get_position(projectm_playlist_handle instance);
/**
* @brief Plays the preset at the requested playlist position and returns the actual playlist index.
*
* If the requested position is out of bounds, the returned position will wrap to 0, effectively
* repeating the playlist as if shuffle was disabled. It has no effect if the playlist is empty.
*
* This method ignores the shuffle setting and will always jump to the requested index, given it is
* withing playlist bounds.
*
* @param instance The playlist manager instance.
* @param new_position The new position to jump to.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_set_position(projectm_playlist_handle instance, uint32_t new_position,
bool hard_cut);
/**
* @brief Plays the next playlist item and returns the index of the new preset.
*
* If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the
* end of the playlist is reached in continuous mode, it will wrap back to 0.
*
* The old playlist item is added to the history.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_next(projectm_playlist_handle instance, bool hard_cut);
/**
* @brief Plays the previous playlist item and returns the index of the new preset.
*
* If shuffle is on, it will select a random preset, otherwise the next in the playlist. If the
* end of the playlist is reached in continuous mode, it will wrap back to 0.
*
* The old playlist item is added to the history.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_previous(projectm_playlist_handle instance, bool hard_cut);
/**
* @brief Plays the last preset played in the history and returns the index of the preset.
*
* The history keeps track of the last 1000 presets and will go back in the history. The
* playback history will be cleared whenever the playlist items are changed.
*
* If the history is empty, this call behaves identical to projectm_playlist_play_previous(),
* but the item is not added to the history.
*
* Presets which failed to load are not recorded in the history and thus will be skipped when
* calling this method.
*
* @param instance The playlist manager instance.
* @param hard_cut If true, the preset transition is instant. If true, a smooth transition is played.
* @return The new playlist position. If the playlist is empty, 0 will be returned.
*/
PROJECTM_PLAYLIST_EXPORT uint32_t projectm_playlist_play_last(projectm_playlist_handle instance, bool hard_cut);
/**
* @brief Sets a new filter list.
*
* <p>Does not immediately apply the new list to an existing playlist, only newly added files
* will be affected. If you need to filter the existing playlist after calling this method,
* additionally call projectm_playlist_apply_filter() afterwards.</p>
*
* <p>The filter list consists of simple globbing expressions similar to the .gitignore syntax:</p>
*
* <ul>
* <li><strong>?</strong>: Matches any single character except /.</li>
* <li><strong>*</strong>: Matches 0 or more characters except /.</li>
* <li><strong>/</strong>: When used at the begin of a glob, matches if
* pathname has no path separator.</li>
* <li><strong>**&zwj;/</strong>: Matches 0 or more directories.</li>
* <li><strong>/&zwj;**</strong>: When at the end of the glob, matches everything after the /.</li>
* </ul>
*
* <p>In globbing expressions, \\ can be used as path separator instead of /. The backslash can't
* be used to escape globbing patterns, so matching literal * and ? in filenames is not possible.
* This is not a huge issue as Windows doesn't allow those characters in filenames and Milkdrop
* files originate from the Windows world. Character classes like "[0-9]" are also not supported to
* keep the syntax simple.</p>
*
* <p>Each line can be prefixed with either + or - to either include files matching the pattern
* or excluding them. Any other character is not interpreted as a prefix and the filter line is
* matching as an exclude filter. To match a literal + or - at the beginning, add the appropriate
* prefix in front. Empty filters never match anything, even if the filename is empty.</p>
*
* <p>The filter list is checked in order. The first pattern that matches the filename determines
* the filter result (include or exclude). If no pattern matches, the file is included. In the case
* that a default exclude action is required, add a "-/&zwj;**" filter at the end of the list.</p>
*
* @param instance The playlist manager instance.
* @param filter_list An array with filter strings.
* @param count The size of the filter array.
*/
PROJECTM_PLAYLIST_EXPORT void projectm_playlist_set_filter(projectm_playlist_handle instance, const char** filter_list,
size_t count);
/**
* @brief Returns the current filter list.
*
* Always call projectm_playlist_free_string_array() on the returned pointer if the data is
* no longer needed.
*
* @param instance The playlist manager instance.
* @param[out] count The size of the filter array.
* @return An array with filter strings.
*/
PROJECTM_PLAYLIST_EXPORT char** projectm_playlist_get_filter(projectm_playlist_handle instance, size_t* count);
/**
* @brief Applies the current filter list to the existing playlist.
*
* Note this function only removes items. Previously filtered items are not added again. If items
* were removed, the playback history is cleared.
*
* @param instance The playlist manager instance.
* @return The number of removed items.
*/
PROJECTM_PLAYLIST_EXPORT size_t projectm_playlist_apply_filter(projectm_playlist_handle instance);
#ifdef __cplusplus
}
// extern "C"
#endif

2
src/sdl-test-ui/pmSDL.cpp
View File

@ -440,7 +440,7 @@ void projectMSDL::renderFrame()
glClearColor(0.0, 0.0, 0.0, 0.0);
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT);
projectm_render_frame(_projectM);
projectm_opengl_render_frame(_projectM);
SDL_GL_SwapWindow(_sdlWindow);
}

2
src/sdl-test-ui/pmSDL.hpp
View File

@ -39,8 +39,8 @@
#define STEREOSCOPIC_SBS 0
// projectM
#include <libprojectM/playlist.h>
#include <libprojectM/projectM.h>
#include <playlist.h>
// projectM SDL
#include "audioCapture.hpp"

2
tests/playlist/APITest.cpp
View File

@ -1,6 +1,6 @@
#include "PlaylistCWrapperMock.h"
#include <playlist.h>
#include <api/libprojectM/playlist.h>
#include <gtest/gtest.h>

2
tests/playlist/PlaylistCWrapperMock.h
View File

@ -1,6 +1,6 @@
#pragma once
#include <PlaylistCWrapper.h>
#include <PlaylistCWrapper.hpp>
#include <gmock/gmock.h>