libprojectM Major Release v4.0.0

This is the final 4.0 release of libprojectM.

It's been about two years after the last 3.1 release, but the projectM core team and community worked hard to make projectM better for both end users and developers integrating the library into their own applications.

Since this release is mainly aimed at developers, we will only attach source packages to this release. If you want pre-built libraries, please download the latest artifacts from the automated GitHub Actions builds.

As always, if you find bugs or have feature suggestions or requests, please feel free to create an issue or post in the discussions board. We're also available for chat on our Discrod server, which is linked on the project page.

Target Audience: Developers

This release is mainly aimed at developers integrating projectM into their applications. The main focus of this major release was to provide a new, stable API based on pure C functions, which will make it easier to create bindings for other languages as well as using it as a shared library. We also fixed many crashes and improved the overall visual quality and compatibility of presets to some degree.

The API will remain stable and forward-compatible until the next major release. Any changes made will only include new functions, so the ABI will always stay forward-compatible. This means an application built and linked against a specific 4.x version will build and run with any libprojectM with a major version of 4 and the same or higher minor version. If an application uses libprojectM as a shared library, no relinking is required at all - simply swap the library file with the new one and it should work.

What About Users?

If you are an end user looking for the standalone visualizer or the Apple Music plug-in, this release isn't very useful as it only contains the projectM development libraries and headers, but no frontend or executable you can run.

Since modernizing the projectM ecosystem is a big undertaking, we've decided to postpone the major visual and UI improvements to a later point, first releasing the core library so developers can adopt the new programming interface.

You can expect a new frontend application and great Milkdrop compatibility improvements on the upcoming minor 4.1 release, which we will make available together with the updated frontends. Until then, you can use these development releases, which contain most of the changes in this 4.0 release:

• Standalone application for Windows/macOS/Linux: https://github.com/kblaschke/frontend-sdl2/releases
• Apple Music plug-in for macOS: https://github.com/kblaschke/frontend-music-plug-in/releases/tag/v3.0-pre1

Changes Since 3.1.12

To better distiguish what's part of this release and what's not, we have compiled a changelog and a list with issues that will not be fixed or implemented in the initial 4.0 version:

User-Related Changes

• Improved waveform and shape line rendering to match Milkdrop's way of drawing.
• Fixed some bugs rendering the different waveform types.
• Added support for instanced shapes. In previous releases, only a single shape was rendered for each shapecode block, breaking many presets.
• Fixed the built-in noise textures used by preset shaders by reimplementing Milkdrop's generator code. Noise textures now have four different color channels instead of having the same value on RGB and 1.0 only in the alpha channel.
• Fixed texture coordinates in textured shapes.
• Fixes in the preset comp/warp shader parsing code, leading to fewer broken presets.
• Fixed numerous crashes when parsing invalid preset expressions or shaders.
• Many more small stability and quality improvements.

Developer-Related Changes

• Replaced the platform-specific build files with CMake.
• Removed all non-library-related applications and files from the repository. This includes all presets except the development test presets, any user-faced frontends and other old code. The previous SDL frontend was retained as a developer-only test UI, but is not built by default and also not installed alongside the library.
• Added a new C API, hiding all C++ types by default. This will make it easier to integrate projectM into other languages.
• Added proper export defines to all functions. libprojectM can now be used as a shared library on all supported platforms, including Windows.
• Moved preset playlist support to a separate, optional library. The core library now only supports loading a single preset plus a second one during transitions. The new playlist library supports loading multiple paths/files and can apply .gitignore-style filter patterns. Rating support has been removed though.
• Removed all text overlays.
• Replaced the key handler with specific API functions.
• Replaced the settings struct with getter and setter API functions.
• Removed built-in configuration file support. All non-default settings now need to be passed in from the embedding application.
• Improved and modernized the audio data interface.
• Enabled OpenMP support on all platforms.
• Support multiple texture search paths.
• Added support for loading presets from a character buffer instead of a file.
• Added callbacks for preset switches and loading failures in the core library.
• Fixed a crash that occurred if OpenGL wasn't initialized properly. projectm_create() will now simply return NULL in this case.

Issues Remaining Unresolved in the 4.0.0 Release

These issues will be fixed or implemented after the 4.0 release, as they don't affect the API backward compatibility:

• Supporting missing expression features like megabuf and loop.
• Fixing the issue projectM is loading all textures into (V)RAM on startup instead of only loading those which are used by the current preset.
• Improve rendering quality on high-res displays by gradually scaling line thickness.
• Adding more debugging functions to analyze rendering internals and preset expression values on the application side.