Clementine Documentation

git clone https://github.com/clementine-player/Clementine.git && cd Clementine

cd bin
cmake ..
make -j$(nproc)
sudo make install

uv tool install clang-format==23.1.0

dist/format.py -i

Show the song's lyrics in time with the song

Release-note: Lyrics scroll along with the song, when they're timed.

Release-note: Lyrics scroll along with the song, when they're timed.
Co-Authored-By: Someone <[email protected]>

/* Detailed source-code truncated for AI context efficiency. */

Plan StreamPlanner::Plan(const MediaPlaybackRequest& req, const Song& song,
                         const RendererCaps& caps, const StreamSettings& s);

struct Plan {
  enum Mode { Direct, Pipeline };
  Mode mode;
  // Pipeline only: remux the source's own codec, or decode and encode.
  enum Output { Passthrough, Encode };
  Output output;
  TranscoderPreset preset;    // Encode only
  QString mime_type;          // what the renderer will receive
  qint64 length_nanosec;      // known length, used for seek bars and ?t=
};

uridecodebin(uri = req.MediaUrl, caps = raw | <passthrough caps>)
  ├─ Passthrough: <parser> ! <muxer> ! appsink
  └─ Encode:      audioconvert ! [rgvolume ! rglimiter] ! [equalizer-nbands ! audiopanorama]
                  ! audioresample ! capsfilter(rate/channels <= caps)
                  ! <preset encoder> ! <preset muxer> ! appsink

/* Detailed source-code truncated for AI context efficiency. */

src/engines/enginerouter.{h,cpp}           EngineRouter (Engine::Base)
src/engines/gstpipelinehelpers.{h,cpp}     source setup (headers, user agent) and RG/EQ/balance elements, shared by GstEnginePipeline and GstStreamPipeline
src/networkremote/streaming/
    remoteengine.{h,cpp}                   RemoteEngine (Engine::Base)
    rendererregistry.{h,cpp}               renderer_id -> RemoteEngine; owns OUTPUTS
    streamplanner.{h,cpp}                  pure planning logic
    protocolsniffer.{h,cpp}                first-byte routing of accepted sockets (§5.0)
    mediahttpserver.{h,cpp}                HTTP request parsing, token check, dispatch
    directresponder.{h,cpp}                file + Range
    pipelineresponder.{h,cpp}              owns a GstStreamPipeline, appsink -> socket
    gststreampipeline.{h,cpp}              GstPipelineBase subclass
src/ui/outputpicker.{h,cpp}                toolbar button + menu: "This computer", renderers

Mandatory packages:

.. code:: bash

   sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev

**Important:** projectM requires CMake 3.21 or newer. Current stable distributions already ship a new enough
CMake (e.g. Debian 12 "bookworm" with CMake 3.25, Ubuntu 22.04 and newer with CMake 3.22+). Only end-of-life releases
like Debian 11 "bullseye" (CMake 3.18) need a manual install, in which case get the latest CMake
release `from Kitware's download page <https://cmake.org/download/>`__.

Optional packages:

.. code:: bash

   sudo apt install ninja-build # To build projectM with Ninja instead of make
   sudo apt install libsdl2-dev # To build the development test UI

Download the projectM sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For production use, it is highly recommended to use the latest stable version of projectM. Download the latest release
from the `Releases page on GitHub <https://github.com/projectM-visualizer/projectm/releases>`__ and unpack it.

Using a development version
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you prefer a bleeding-edge version or want to modify the code, clone the Git repository and initialize any
submodules:

.. code:: bash

   sudo apt install git # Probably already installed
   git clone https://github.com/projectM-visualizer/projectm.git /path/to/local/repo
   cd /path/to/local/repo
   git fetch --all --tags
   git submodule init
   git submodule update

Build and install projectM
~~~~~~~~~~~~~~~~~~~~~~~~~~

Replace ``/usr/local`` with your preferred installation prefix.

Configure the project using CMake
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: bash

   sudo apt install cmake
   mkdir build
   cd build
   cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..

To generate Ninja scripts instead of Makefiles, add ``-GNinja`` to the above command.

Build and install
^^^^^^^^^^^^^^^^^

These commands will build projectM and install it to /usr/local or the configured installation prefix set in the step
before:

.. code:: bash

   cmake --build . -- -j && sudo cmake --build . --target install

**Note**: You won't need to use ``sudo`` if the install prefix is writeable by your non-privileged user.

Test projectM
^^^^^^^^^^^^^

The SDL-based developer test UI is off by default. To build it, add ``-DENABLE_SDL_UI=ON`` to the configure command
above (requires SDL2, e.g. ``sudo apt install libsdl2-dev``). It is not installed; after building, run it from the build
directory, e.g. ``./src/sdl-test-ui/projectM-Test-UI``.

Dependencies
------------

Depending on the OS/distribution and packaging system, libraries might be split into separate packages with binaries and
development files. To build projectM, both binaries and development files need to be installed.

General build dependencies for all platforms:

- Linux distributions will have packages available for most (if not all) required libraries. The package names and
  commands to install them vary widely between distributions (and even versions of the same distribution). Please refer
  to the documentation of your build OS on how to find and install the required libraries.
- On *BSD*, install the appropriate Ports with ``pkg install``.
- On macOS, a working Xcode installation is required. CMake (and libSDL2 for the test UI) can be installed
  using `Homebrew <https://brew.sh/>`__.

Building
~~~~~~~~

The steps documented below are a bare minimum quickstart guide on how to build and install the project. If you want to
configure the build to your needs, require more in-depth information about the build process and available tweaks, or on
how to use libprojectM in your own CMake-based projects, see the `Building with CMake`_ reference section below.

Using CMake is the only supported way of building projectM since version 4.0. CMake is a platform-independent tool that
is able to generate files for multiple build systems and toolsets while using only a single set of build instructions.

Building the project with CMake requires two steps:

- Configure the build and generate project files.
- Build and install the project using the selected build tools.

**Note:** The build directory should always be different from the source directory. Generating the build files directly
inside the source tree is possible, but strongly discouraged. Using a subdirectory, e.g. ``cmake-build`` inside the source
directory is fine though.

This documentation only covers project-specific information. CMake is way too versatile and feature-rich to cover any
possible platform- and toolset-specific configuration details here. If you are not experienced in using CMake, please
first read the `official CMake documentation <https://cmake.org/cmake/help/latest/>`__ (at least
the `User Interaction Guide <https://cmake.org/cmake/help/latest/guide/user-interaction/index.html>`__) for basic usage
instructions.

Configure the build
^^^^^^^^^^^^^^^^^^^

Configuring a non-debug build with default options and install prefix (``/usr/local``) can be done with these commands,
building in a subdirectory inside the source directory:

.. code:: shell

   cd /path/to/source
   mkdir cmake-build
   cd cmake-build
   cmake -DCMAKE_BUILD_TYPE=Release ..

CMake will check all required dependencies and display any errors. If configuration was successful, a summary of the
build configuration is printed and CMake should display a ``Generating done`` line. The project is now ready to build.

Compile and install the project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Depending on your generator choice, you can use your selected toolset as usual to build and install projectM:

- With ``Unix Makefiles``, run ``make && sudo make install``.
- With ``Ninja``, run ``ninja && sudo ninja install``.
- With ``Xcode``, select the appropriate target and configuration in Xcode and build it, or ``INSTALL`` to install the
  project.

You can also use CMake's build mode to run the selected toolset and build any specified target. CMake knows which
command to call and which parameters to pass, so the syntax works on all platforms with all generators. If you've
already set the top-level build directory as working directory, simply pass ``.`` as ``/path/to/build/dir``:

.. code:: shell

   cmake --build /path/to/build/dir --config Release
   sudo cmake --build /path/to/build/dir --config Release --target install

If you don't need root permissions to install to the given path, running the second command without ``sudo`` is
sufficient.

To control how many files are compiled in parallel, pass the ``--parallel N`` argument to the build command, with ``N``
being the number of concurrent compile commands. If not given explicitly, the build processor (make, ninja, MSBuild,
xcodebuild etc.) will decide the limit, which may range from one file at a time to all files at once.

If you want to provide arguments directly to the toolset command, add ``--`` at the end of the CMake command line followed
by any additional arguments. CMake will pass these *unchanged and unchecked* to the subcommand:

.. code:: shell

   cmake --build /path/to/build/dir --config Release -- <additional build tool args>

Building on Windows
-------------------

To build the projectM library and the SDL-based standalone application, CMake must be used to create the project files
first. Using vcpkg to pull in the build dependencies is highly recommended, as CMake can't use NuGet (NuGet pulls in
dependencies using the project files, while CMake requires the libraries before creating the project files).

Installing the dependencies with vcpkg

CMake provides separate generators for different Visual Studio versions. Newer CMake versions will support recent Visual
Studio releases, but may remove generators for older ones. To get a list of available generators from the command line,
use the ``-G`` switch without an argument. The CMake GUI will present you a dropdown list you can easily select from.

To set the build architecture in Visual Studio builds, use the ``-A`` switch and specify either ``Win32`` or ``X64`` as the
argument. If you want to build for both architectures, create separate build directories and configure them accordingly.

To make CMake aware of the installed vcpkg packages, simply use the provided toolchain file when configuring the
projectM build by
pointing `CMAKE_TOOLCHAIN_FILE <https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html>`__ to it.

Here is a full command line example to create a Visual Studio 2022 solution for X64:

.. code:: console

   cmake -G "Visual Studio 17 2022" -A "X64" -DCMAKE_TOOLCHAIN_FILE="<path to vcpkg>/scripts/buildsystems/vcpkg.cmake" -S "<path to source dir>" -B "<path to build dir>"

If you use the CMake GUI, check the "Specify toolchain file for cross-compiling" option in the first page of the
configuration assistant, then select the above ``vcpkg.cmake`` file on the second page.

Another option is to open the project folder in a recent Visual Studio version as a CMake project and configure CMake
using Visual Studio's JSON-based settings file.

Building the solution
~~~~~~~~~~~~~~~~~~~~~

To build the project, open the generated solution in Visual Studio and build it like any other solution. Each time the
CMake files are changed, Visual Studio will automatically regenerate the CMake build files and reload the solution
before continuing the build. Be aware that in old Visual Studio versions (2015 and earlier) the reload-and-continue
might not work properly.

You can also build the solution with msbuild via the command line, or use CMake's build wrapper to do that for you:

.. code:: console

   cmake --build "" --config Release

Using Ninja to build
~~~~~~~~~~~~~~~~~~~~

The Ninja build system is shipped with Visual Studio since version 2019 and used by default if loading a CMake project
directly from within the IDE. Ninja can also be `installed separately <https://github.com/ninja-build/ninja/releases>`__.

To configure the build directory for Ninja, pass ``Ninja`` or ``Ninja Multi-Config`` as the argument for the ``-G`` switch.
The difference between both generators is that the former uses ``CMAKE_BUILD_TYPE`` to specify the configuration (
e.g. ``Debug`` or ``Release``) while the latter supports all configurations in a single build directory, specified during
build time.

The architecture is determined from the toolset, so make sure to run the commands in the correct Visual Studio command
prompt, e.g. "Native Tools for X64".

Configure and build for a single-configuration Release build with vcpkg:

.. code:: console

   cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B ""
   cmake --build ""

Same, but using the multi-configuration generator:

.. code:: console

   cmake -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B ""
   cmake --build "" --config Release

Notes on other platforms and features
-------------------------------------

Supported platforms
~~~~~~~~~~~~~~~~~~~

libprojectM is designed to be compatible with as many platforms and architectures as possible. Thus, the code base
doesn't use any non-portable code like OS-specific APIs or assembly instructions.

The code compiles for the following target architectures:

- i686 (x32 / x86)
- x86_64 (x64)
- armv7 (arm)
- aarch64 (arm64 / armv8)
- WASM

Other architectures such as PPC, RISC and MIPS should be supported as well. Big-endian support is untested and thus
might be buggy.

libprojectM builds at least on the following platforms:

- Windows
- Linux
- macOS (iOS/tvOS as well, but be aware that Apple's TOS may prevent its use in Store apps!)
- BSD derivatives
- Android
- WebGL/WASM (using emscripten)

As long as a platform provides OpenGL Core 3.3 or OpenGL ES 3.2 libraries and supports at least C++ 14, libprojectM
should build fine.

Raspberry Pi (and other embedded systems)

To build projectM using the Android SDK, please refer to the official NDK docs:

https://developer.android.com/ndk/guides/cmake

It is highly recommended using the latest NDK and CMake >= 3.21 for building.

Using libprojectM with pkgconfig

Previous projectM versions (before 4.0) shipped several UIs and audio capture implementations in this repository.
To reduce the size of the code base and separate the release cycles of the core library and the frontends, these were
moved into their own repositories under the `projectM-visualizer organization <https://github.com/projectM-visualizer>`__
(e.g. the SDL-based desktop app and the Qt-based desktop app with PipeWire/PulseAudio/JACK backends).

libprojectM on its own does not have any means of capturing audio, it simply takes PCM data via the API. Applications
using projectM can supply this data from their own audio sources, e.g. music playing in an audio player or capturing
audio data from OS or other external sources.

.. _Building with CMake:

Building with CMake
-------------------

This section contains in-depth information for building with the CMake build system.

To use the library in other projects, it is required to install it. Use ``CMAKE_INSTALL_PREFIX`` to specify the
installation directory. If you use other build systems, you have to specify the include and library paths manually.

Selecting a specific project file generator

CMake has no built-in way of printing all available configuration options. You can either refer to the
top-level ``CMakeLists.txt`` which contains a block of ``option`` and ``cmake_dependent_option`` commands, or use one of the
available CMake UIs which will display the options after configuring the project once.

Important build switches
^^^^^^^^^^^^^^^^^^^^^^^^

The following table also gives you an overview of important build options and their defaults. All options accept a
boolean
value (``YES``/``NO``, ``TRUE``/``FALSE``, ``ON``/``OFF`` or ``1``/``0``) and can be provided on the configuration-phase command line
using the ``-D`` switch.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Required dependencies
     - Description
   * - ``BUILD_TESTING``
     - ``OFF``
     -
     - Builds the unit tests.
   * - ``BUILD_DOCS``
     - ``OFF``
     - ``Doxygen``, ``Sphinx``
     - Builds the API/developer documentation in ``docs/``.
   * - ``BUILD_SHARED_LIBS``
     - ``ON``
     -
     - Build projectM as shared libraries. If ``OFF``, build static libraries.
   * - ``ENABLE_PLAYLIST``
     - ``ON``
     -
     - Builds and installs the playlist library.
   * - ``ENABLE_EMSCRIPTEN``
     - (auto)
     - ``Emscripten``
     - Forced ``ON`` when building with the Emscripten toolchain, otherwise ``OFF``. Not user-settable.
   * - ``ENABLE_GLES``
     - ``OFF``
     - ``GLES``
     - Use OpenGL ES 3 profile for rendering instead of the Core profile.

Note that ``ENABLE_GLES`` will be forcibly set to ``ON`` for Emscripten and Android builds, making it mandatory.

Experimental and application-dependent build switches
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following table contains a list of build options which are only useful in special circumstances, e.g. when
developing libprojectM, trying experimental features or building the library for a special use-case/environment.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Required dependencies
     - Description
   * - ``ENABLE_SDL_UI``
     - ``OFF``
     - ``SDL2``
     - Builds the SDL-based test application. Only used for development testing, will not be installed.
   * - ``ENABLE_INSTALL``
     - ``ON`` (top-level) / ``OFF`` (subproject)
     -
     - Enable projectM install targets. Automatically ``ON`` when built standalone, ``OFF`` when added via ``add_subdirectory()``.
   * - ``ENABLE_DEBUG_POSTFIX``
     - ``ON``
     -
     - Adds ``d`` (by default) to the name of any binary file in debug builds.
   * - ``ENABLE_SYSTEM_GLM``
     - ``OFF``
     -
     - Builds against a system-installed GLM library.
   * - ``ENABLE_SYSTEM_PROJECTM_EVAL``
     - ``ON``
     -
     - Uses a system-installed projectM-eval library if found, otherwise the bundled sources in ``vendor/``.
   * - ``ENABLE_BOOST_FILESYSTEM``
     - ``OFF``
     - ``Boost``
     - Forces the use of ``boost::filesystem`` instead of ``std::filesystem``. Only needed on toolchains without C++17 filesystem support.
   * - ``ENABLE_MACOS_FRAMEWORK``
     - ``OFF``
     - macOS
     - Build as macOS Framework bundles instead of plain shared libraries.
   * - ``ENABLE_CXX_INTERFACE``
     - ``OFF``
     -
     - Exports symbols for the ``ProjectM`` and ``PCM`` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported.
   * - ``ENABLE_VERBOSE_LOGGING``
     - ``OFF``
     -
     - Enables code for ``TRACE`` and ``DEBUG`` log levels in release builds. By default, these will only be compiled for ``Debug`` builds. Enabling this will negatively affect performance, even if the actual log level is set to ``INFORMATION`` or higher.

Path options
^^^^^^^^^^^^

There are also a few textual parameters that can be used to fine-tune the installation directories. Relative paths in
the following options are appended to the value
of `CMAKE_INSTALL_PREFIX <https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html>`__ (which, on most UNIX
platforms, defaults to ``/usr/local``):

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Description
   * - ``CMAKE_INSTALL_PREFIX``
     - (OS dependent)
     - Base directory where the projectM libraries, includes and support files will be installed.
   * - ``PROJECTM_BIN_DIR``
     - ``bin``
     - Directory where executables (e.g. the SDL standalone application) are installed.
   * - ``PROJECTM_LIB_DIR``
     - ``lib[64]``
     - Directory where libprojectM is installed.
   * - ``PROJECTM_INCLUDE_DIR``
     - ``include``
     - Directory where the libprojectM include files will be installed under.

Other options
^^^^^^^^^^^^^

Various other options for specific needs.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Description
   * - ``CMAKE_DEBUG_POSTFIX``
     - ``d`` (if ``ENABLE_DEBUG_POSTFIX`` is set)
     - Postfix appended to debug libraries.
   * - ``CMAKE_INSTALL_BINDIR``
     - ``bin``
     - Another way to specify the binary installation directory. Used as default value for ``PROJECTM_BIN_DIR``.
   * - ``CMAKE_INSTALL_LIBDIR``
     - ``lib`` or ``lib64``
     - Another way to specify the library installation directory. Used as default value for ``PROJECTM_LIB_DIR``.
   * - ``CMAKE_INSTALL_INCLUDEDIR``
     - ``include``
     - Another way to specify the include file installation directory. Used as default value for ``PROJECTM_INCLUDE_DIR``.

Always perform out-of-tree builds!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most classic IDEs and build systems directly make use of the source tree and create project files, temporary build
artifacts (e.g. object files) and the final binaries in the same directory structure as the source files. An advantage
of this approach is that you can find all compiled binaries side-by-side with their sources and generated headers are
already in the same directories as the source files including them. This approach has some drawbacks though:

- Only a single build configuration is supported as files are overwritten in-place.
- A lot of noise is created in the source directory, making it hard to distinguish between generated and original source
  files.
- A very large ``.gitignore`` file is required to cover all unwanted files.
- Mistakes in the build scripts can overwrite source files, causing errors and destroy uncommitted work.

Some of these can be mitigated by providing additional targets (``make clean`` and ``make distclean``) or creating
subdirectories for Debug/Release build configurations.

While CMake also supports in-tree builds, it is "discouraged" in the official documentation, for the above reasons.
Building out-of-tree allows it to create multiple build directories with different configurations which do not influence
each other in any way. If a build directory contains unwanted artifacts, and you want to start fresh, simply delete and
recreate the whole directory - no work is lost.

This project follow this principle by treating the original source tree as read-only and avoiding potential conflicts:

- Everything under `CMAKE_SOURCE_DIR <https://cmake.org/cmake/help/latest/variable/CMAKE_SOURCE_DIR.html>`__ must only be
  read, never changed or written to.
- Everything under `CMAKE_BINARY_DIR <https://cmake.org/cmake/help/latest/variable/CMAKE_BINARY_DIR.html>`__ is temporary
  and related to the current build configuration.
- When generating configuration-dependent files,
  use `CMAKE_CONFIGURATION_TYPES <https://cmake.org/cmake/help/latest/variable/CMAKE_CONFIGURATION_TYPES.html>`__
  and `CMAKE_BUILD_TYPE <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`__ to create non-conflicting
  files in the build tree.

While this project will not force you to build out-of-tree, there is no mechanism to clean up the generated files after
running cmake in-tree.

CMake build directory layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are new to CMake, the way of how CMake creates the build directory and where it creates the build targets might
be confusing. Here is a summary of what's in the build directory and how it is structured in general.

Using files from the build tree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is generally not good practice to directly take binaries and other files from the build tree for packaging, for
several reasons:

1. The directory structure is generated by CMake and depends on the generator used. The layout might change between
   CMake versions, even for the same generator.
2. On platforms with RPATH support, CMake will store absolute paths in executables and shared libraries which point to
   the absolute paths of any linked dependencies, either from the build tree or external libraries as well. These
   binaries are not relocatable and will most certainly not work if run on any other computer (or even on the same after
   deleting the build directory).
3. For some configurations, even Release build artifacts may contain debug symbols until they are installed.

It is fine to build and run executables from the build directory for development and debugging. For packaging or using
libprojectM in other projects, always use the ``install`` target and copy files from there.

Generated files
^^^^^^^^^^^^^^^

In the top-level build directory, CMake creates a few files that are present on any platform:

- ``CMakeCache.txt``: This file contains all variables and build settings CMake needs to remember from the first
  configuration run. This file can be edited on demand either manually or using a CMake UI to change any values. On the
  next build, CMake will regenerate the project files if this file has been modified.
- ``cmake_install.cmake``: Contains generated install-related settings.
- ``install_manifest.txt``: After installing the project, this file contains a list with absolute filenames of all
  installed files. It can be used for packaging or deleting installed files as CMake doesn't define an ``uninstall``
  target.
- The top-level project file for use with the selected build toolset, e.g. ``Makefile``, ``build.ninja``, ``projectm.sln``
  or ``projectm.xcodeproj``, plus additional toolset-specific files.

The projectM build files generate additional files used in the build and install phases. These are scattered over the
build tree, but installed into the proper directories. Do not try and gather these files yourself from the build tree.

Subdirectory structure
^^^^^^^^^^^^^^^^^^^^^^

The rest of the directory structure generally resembles the source tree. Source directories containing
a ``CMakeLists.txt`` file will also be created in the build tree with the same relative path. Each of these subdirectories
contains a ``CMakeFiles`` directory with CMake-internal data, generated project files for the select toolset, e.g.
makefiles and any temporary compile artifacts.

The directory structure is created by CMake and may change depending on the generator and CMake version used.

Executable and library locations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Build targets - shared/static libraries and executables - are created in the same subdirectory in the build tree as
the ``CMakeLists.txt`` file that defines the target in the source tree (which, in most cases, resides in the same
directory as the source files). Depending on the generator used, the binaries are created directly in the directory for
single-configuration generators (like ``Unix Makefiles`` or ``Ninja``) and in a subdirectory with the configuration name,
e.g. ``Debug`` or ``Release``, for multi-configuration generators like ``Xcode`` or ``Visual Studio 17 2022``.

You may also find additional files and symbolic links in the same location depending on the platform, e.g. ``.pdb`` files
on Windows.

Using libprojectM in other CMake projects

// Create the SDL window (will be tied to the Emscripten HTML5 canvas)
   SDL_window* window = NULL;
   SDL_renderer* renderer = NULL;
   SDL_CreateWindowAndRenderer(1024, 768, SDL_WINDOW_OPENGL, &window, &renderer);
   if (window == NULL || renderer == NULL)
   {
       fprintf(stderr, "Failed to create SDL renderer: %s\n", SDL_GetError());
       return 1;
   }

   // Enable floating-point texture support for motion vector grid.
   auto webGlContext = emscripten_webgl_get_current_context();
   emscripten_webgl_enable_extension(webGlContext, "OES_texture_float");

   // Initialize projectM and put all other stuff below.
   
   return 0;

This repository now only contains the projectM shared/static library.
All frontends, plug-ins and other tools were outsourced into separate
repositories. If you’re not a developer and just look for a download to
run projectM visuals on your machine or device, please use one of the
links listed below. The releases section in this repository only
contains source-code and binary releases of the projectM development
libraries and headers, which aren’t useful for end users.

End-User Applications
~~~~~~~~~~~~~~~~~~~~~

**Important**: projectM is currently undergoing heavy development. The
available end-user frontends are development previews, which are not
feature-complete and may have bugs.

Windows
^^^^^^^

-  Standalone (`projectMSDL 2.0
   pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__)
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Same as standalone development preview)
-  `Windows Store <https://www.microsoft.com/store/apps/9NDCVH0VCWJN>`__
   (Old 3.1.12 release)

macOS
^^^^^

-  Standalone

   -  `C++ app
      pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__
   -  `Rust app development preview
      (signed) <https://github.com/projectM-visualizer/frontend-sdl-rust/releases/tag/v0.1.0>`__
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Old 3.1.12 release)
-  Music.app Plugin (currently only available as an *unsigned*
   `development
   preview <https://github.com/kblaschke/frontend-music-plug-in/releases/tag/v3.0-pre1>`__)
-  `Brew <https://formulae.brew.sh/formula/projectm>`__ (Old 3.1.12
   release)

Linux
^^^^^

-  Standalone (`projectMSDL 2.0
   pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__,
   also available as ``.deb`` and ``.tar.gz``)
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Same as standalone development preview)

Or check your distribution’s package manager for a binary release. If it
is outdated, please contact the package maintainer, as the projectM
development team does not maintain any of the distribution-specific
packages.

Android
^^^^^^^

-  `Google
   Play <https://play.google.com/store/apps/details?id=com.psperl.prjM>`__

**Note**: Both the free and paid apps plus the Android TV app are *not*
created or supported by the projectM developers! If you have technical
troubles or other inquiries, please contact the app author via the means
provided in the Play Store. Any bug reports in the projectM issue
tracker regarding the apps will be closed immediately.

Xbox / Windows Phone
^^^^^^^^^^^^^^^^^^^^

-  `Windows Store <https://www.microsoft.com/store/apps/9NDCVH0VCWJN>`__
   (Old 3.1.12 release)

Other
^^^^^

Source code and other resources, mostly aimed at developers.

-  `Library source
   code <https://github.com/projectM-visualizer/projectm/>`__ (this
   repository)
-  `Qt <https://www.qt.io/>`__ based (Qt5/Qt6) desktop apps for Linux
   with `PipeWire <https://pipewire.org/>`__,
   `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__
   and JACK audio backends (`source
   code <https://github.com/projectM-visualizer/frontend-qt>`__,
   requires libprojectM 4.x).
-  `ALSA, XMMS, Winamp,
   JACK <https://sourceforge.net/projects/projectm/files/>`__ (legacy
   2.x sources for historic purposes, unmaintained since 2012)

Discord chat
~~~~~~~~~~~~

`Chat with us on Discord! <https://discord.gg/N9DyQfCH4j>`__

Click For Demo Videos
~~~~~~~~~~~~~~~~~~~~~

A demo playlist is available on
`YouTube <https://www.youtube.com/watch?v=jJmLQGhYWys&list=PLFLkbObX4o6TK1jGL6pm1wMwvq2FXnpYJ>`__.

Presets
~~~~~~~

The preset files define the visualizations via pixel shaders and
Milkdrop-style equations and parameters.

The projectM library does not ship with any presets. The frontends come
with varying preset packs which can be found in separate repositories in
the projectM repository list:

-  `Base Milkdrop texture
   pack <https://github.com/projectM-visualizer/presets-milkdrop-texture-pack>`__
   - Recommended for use with *any* preset pack!
-  `Cream of the Crop
   Pack <https://github.com/projectM-visualizer/presets-cream-of-the-crop>`__
   - A collection of about 10K presets compiled by Jason Fletcher.
   Currently, projectM’s default preset pack.
-  `Classic projectM
   Presets <https://github.com/projectM-visualizer/presets-projectm-classic>`__
   - A bit over 4K presets shipped with previous versions of projectM.
-  `Milkdrop 2
   Presets <https://github.com/projectM-visualizer/presets-milkdrop-original>`__
   - The original preset collection shipped with Milkdrop and Winamp.
-  `En D
   Presets <https://github.com/projectM-visualizer/presets-en-d>`__ -
   About 50 presets created by “En D”.

Included with projectM are the bltc201, Milkdrop 1 and 2, projectM,
tryptonaut and yin collections. You can grab these presets
`here <http://spiegelmc.com/pub/projectm_presets.zip>`__.

You can also download an enormous 130k+ presets from the MegaPack
`here <https://drive.google.com/file/d/1DlszoqMG-pc5v1Bo9x4NhemGPiwT-0pv/view>`__
(4.08GB zipped, incl. textures).

Also Featured In
~~~~~~~~~~~~~~~~

`|Kodi| Kodi (formerly XBMC) <https://kodi.tv/>`__

`|Helix|
Helix <https://web.archive.org/web/20180628174410/http://ghostfiregames.com/helixhome.html>`__

`|Silverjuke| Silverjuke (FOSS Jukebox) <https://www.silverjuke.net>`__

`|VLC Media Player| VLC Media Player (AKA VideoLAN
Client) <https://www.videolan.org/vlc/>`__

Reminder: These are all third-party integrations of libprojectM and not
developed or supported by the projectM development team. Please report
bugs in those applications to their respective developers.

Screenshots
-----------

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.31.20\ AM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.33.50\ AM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.14.41\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.13.53\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.15.36\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-16\ at\ 4.49.32\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-16\ at\ 4.50.37\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.31.07\ AM.png
   :alt: Screenshot

   Screenshot

Architecture
------------

-  `Article <https://lwn.net/Articles/750152/>`__

Building from source
--------------------

See :doc:`building` and the `developer documentation in the
wiki <https://github.com/projectM-visualizer/projectm/wiki/Building-libprojectM>`__.

Using the library
-----------------

At its core projectM is a library, `libprojectM <src/libprojectM>`__.
This library is responsible for parsing presets, analyzing audio PCM
data with beat detection and FFT, applying the preset to the audio
feature data and rendering the resulting output with OpenGL. It can
render to a dedicated OpenGL context or a texture.

To get started using projectM in your own projects, please go to the
wiki and read the `developer
documentation <https://github.com/projectM-visualizer/projectm/wiki#integrating-projectm-into-applications>`__
available there.

There are some open-source applications that make use of libprojectM
which can be found in the `projectM organization’s
repositories <https://github.com/projectM-visualizer>`__ and elsewhere.

Help
----

Report issues on GitHub in the respective repositories:

-  `Rendering issues, crashes or the libprojectM
   core/API <https://github.com/projectM-visualizer/projectm/issues>`__
-  `Standalone SDL
   app <https://github.com/projectM-visualizer/frontend-sdl2/issues>`__
   (including the Steam release)
-  `Windows Store
   App <https://github.com/projectM-visualizer/frontend-uwp/issues>`__
-  `Apple Music
   plug-in <https://github.com/projectM-visualizer/frontend-music-plug-in/issues>`__
-  Issues regarding the **projectM Android apps in the Play Store**,
   please contact the app author via the Play Store. We cannot help with
   any problems or requests.

If unsure, post your issue in the main `libprojectM issue
tracker <https://github.com/projectM-visualizer/projectm/issues>`__.
Please always check any existing issues if your problem has already been
posted by another user. If so, add your logs and findings to the
existing issue instead of opening a new ticket.

Get in contact with us
----------------------

`Chat with us on Discord. <https://discord.gg/N9DyQfCH4j>`__

Contribute to projectM
----------------------

If you would like to help improve this project, either with
documentation, code, porting, hardware or anything else please let us
know! We gladly accept pull requests and issues.

Before starting to write code, please take your time to read the
`contribution
guidelines <https://github.com/projectM-visualizer/projectm/wiki#contributing-to-projectm>`__
in our wiki.

Package Maintainers
-------------------

If you maintain packages of libprojectM, we are happy to work with you!
Please note well:

-  The main focus of this project is libprojectM. It’s a library that
   only really depends on OpenGL. The other applications are more like
   examples and demos.
-  Many of the frontend applications are likely outdated and of less
   utility than the core library. If you desire to use them or depend on
   them, please file an issue in the respective repository so we can
   help update them.
-  The “canonical” application for actually viewing the visualizations
   is now
   `projectMSDL <https://github.com/projectM-visualizer/frontend-sdl-cpp>`__,
   based on libSDL2 because it supports audio input and is completely
   cross-platform.
-  This is an open source project! If you don’t like something, feel
   free to contribute improvements!
-  Yes, you are looking at the official version. This is not a fork.

Authors
-------

`Authors <https://github.com/projectM-visualizer/projectm/raw/master/AUTHORS.txt>`__

License
-------

The core projectM library is released under the `GNU Lesser General
Public License
2.1 <https://github.com/projectM-visualizer/projectm/raw/master/LICENSE.txt>`__
to keep any changes open-sourced, but also enable the use of libprojectM
in closed-source applications (as a shared library) as long as the
license terms are adhered to. The up- and downstream projects may use
different licenses - please check all parts of the software to be
compatible with your specific project if you plan an integration.

Wiki
----

More information for developers is available from the `projectM
Wiki <https://github.com/projectM-visualizer/projectm/wiki>`__.

.. |Windows Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_windows.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_windows.yml
.. |Linux Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_linux.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_linux.yml
.. |macOS Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_osx.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_osx.yml
.. |Emscripten Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_emscripten.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_emscripten.yml
.. |Android Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml
.. |Discord Shield| image:: https://discordapp.com/api/guilds/737206408482914387/widget.png?style=shield
.. |Kodi| image:: web/kodi.png
.. |Helix| image:: web/helix.jpg
.. |Silverjuke| image:: web/silverjuke.png
.. |VLC Media Player| image:: web/vlc.png

---

### 3rdparty Libprojectm Vendor Projectm Eval Docs Compiler Internals (`3rdparty/libprojectm/vendor/projectm-eval/docs/Compiler-Internals.md`)

Compiler Internals
==================

This document describes how the compiler works and how its functionality can be extended. It is aimed at developers
integrating projectM-EvalLib into their own applications and looking for adding functions and new features on top of the
supported set of Milkdrop-compatible expression syntax.

## Scanner

The scanner (or lexer) is responsible for tokenizing the input data stream and return the type and possible content of
these tokens to the parser. This library uses GNU Flex to generate ode from a rules file, called `Scanner.l`. The
scanner looks for these kinds of symbols, with letters always being case-insensitive:

- Inline comments, starting with `//` until end of the current line
- Block comments, enclosed in `/* ... */`, which can appear anywhere and also span multiple lines.
- HEX constants in the form `$Xnn...`, scanned until any non-hexadecimal character is encountered (`[0-9a-f]`)
- ORD constants in the form `$'c'` where `c` is any single character.
- Math constants `$PI`, `$E` and `$PHI`.
- The `gmem` identifier, as it's used in the non-function form `gmem[index]`, requiring special treatment in the
  grammar.
- Numbers in integer and floating-point notation with an optional exponent. Note that these numbers are always positive,
  negativity is applied later via the `-` unary operator in the parser.
- Identifiers starting with an underscore or alphabetical letter, and also numbers on any following character.
  These can be returned as two different tokens:
    - If the (lower-case) name exists in the function table, the name is returned as a `FUN` token.
    - Anything else is returned as a `VAR` token and identifies a variable.

## Grammar

The grammar is defined in Bison (yacc) syntax and specifies the order in which tokens can appear and how they are
transformed into a tree structure.

In the grammar, different syntactical features are specified:

- Tokens returned by the scanner and their associated C data types in the parser.
- Operator precedence and associativity: Determines which operators are evaluated before others, and in which
  direction (left-to-right or right-to-left).
- The recursively defined grammar, consisting of a list of tokens per rule and an action.

Bison creates a state machine from the grammar, analyze any issues like potential ambiguities and take care of the
proper shift/reduce operations. Bison also provides error handling.

### Compilation Errors

In this grammar, any syntax error encountered will fail the compilation of the whole program. __This is a difference in
comparison to the Milkdrop parser__, which will not fail compilation on certain circumstances, silently ignoring errors
in the code. Reproducing the exact same behaviour would require a completely different approach in the grammar, scanner
and parser.

## Expression Tree

### Node Object

All grammar as described in the previous sections is scanned and compiled into a tree structure by the parser actions.
Each node is a `prjm_eval_exptreenode` struct, which contains:

- A function pointer `func`, which is determined the behaviour of this node.
- A fixed float value `value` to store constant numbers or temporary values.
- A union of either `var`, pointing to a variable storage location, or `memory_buffer` which is a pointer to
  a `projectm_eval_mem_buffer` with (g)megabuf data.
- An array of pointers `args`, pointing to the argument node objects of the function.
- A linked-list pointer `list` which stores an instruction list to be executed by loops or the special `/*list*/`"
  function.

In general, only a few different "objects" will be created as tree nodes:

- Constant: Return simple read-only float-typed numbers. Uses the `value` member to store the constant.
- Variable: Return a read/write variable reference. USes the `var` member to store the variable storage location.
- Memory access function: Operates on the memory buffer specified in `memory_buffer`, either retrieving or setting data.
- Function: Executes objects in `args` and/or the expressions in `list`, then eventually applies an operation on the
  result and sets the return value to either a constant value or a variable reference.

### Node Function

The function in each node object has a `void` return value and takes two parameters:

- The execution context `ctx`, which is a pointer to the `prjm_eval_exptreenode` object the function will be executed on.
  Think of it as the C++ `this` pointers.
- A pointer to a float pointer `ret_val`, which is the return value of the function.

Every node function _must_ return either a value or a value reference. By convention, this is either the result of the
operation the function carried out, or for functions using instruction lists, the result of the _last executed
instruction_.

Depending on the function, the result can either be a simple constant value or a reference to a variable.

When calling a math function like `sin()`, implementing a math operator or returning a constant, the function must
assign the value to the value pointed to by `*ret_val`. Use the `assign_ret_val()` macro to assign the return value:

```c
assign_ret_val(sin(x));
```

Some functions will not carry out an actual math operation, but return the result of an expression, which may be a
variable reference, which may be used as the first argument of the internal `_set` function (or the
AVS-specific `assign` function) to assign it the result of another expression. A reference can be assigned using
the `assign_ret_ref` macro, example taken from the `prjm_eval_func_var` function:

```c
assign_ret_ref(ctx->var);
```

As with all pointers, an assigned pointer must stay valid at least until the end of the program's execution. It is
recommended to only use the following memory references:

- The `var` pointer in variable access functions.
- The address of the `value` member of the current `prjm_eval_exptreenode` object in which context the function runs.

Do not assign pointers to locally defined variables.

Passing `ret_val` as the return value to a function argument and let the function set it to the desired result is also
viable:

```C
prjm_eval_function_decl(myfunc)
{
    assert_valid_ctx();

    invoke_arg(0, ret_val);
}
```

The `if` function evaluates its first argument, and depending on it being a true or false value, returns either the
second (`true`) or the third (`false`) argument. Both arguments may return a variable reference, so the `if` functions
needs to take care of this by simply calling the appropriate function and passing the current `ret_val` to it. This way,
whatever the sub-expression assign to it will be returned by the `if` function.

### Temporary Compiler Objects

#### Node Object

Any tree node object created in a parser action will be wrapped inside a temporary compiler node of
type `prjm_eval_compiler_node`, which stores a few additional flags only required inside the parser's reduce actions:

- The type of the current parser node, either a single expression or an expression list.
- Constness and state-changing flags of the expression (last expression in a list).
- combined constness and state-changing flags of the expression list. Same as the previous one if only a single
  expression is stored in the compiler node.

#### Function Argument List

Inside a function argument list, all expressions are collected in a special `prjm_eval_compiler_arg_list` wrapper holding
one compiler node object for each potential function argument. It also keeps the argument count as a separate variable
for easy access.

When the arguments have been collected and the function is reduced in the parser, the action will then compare the
actual argument count against the count expected by the function. If the numbers don't match, a parse error is thrown.

### Optimizations

The parser does perform two different optimizations during compile time to save execution time:

#### Compile-time Evaluable Functions

The compiler optimizes the generated code by evaluating constant expressions at compile time. These expressions purely
consist of functions which both only have constant-evaluable arguments and have a fixed, deterministic behaviour.
Examples of such functions, given their arguments are also const-evaluable:

- Functions which return compile-time constants.
- Non-assigment Operators.
- Math functions like `sin`.

Non-constant functions are functions which depend on variables or other memory contents which may change during or
between executions or produce a non-deterministic result on each execution. Examples are:

- Functions which have at least one non-const-evaluable argument.
- Variable and memory access functions.
- Random number generators.

During compilation, when a new node is created from a subtree, each argument and the new node are checked for being
const-evaluable. If all are, then the new node is immediately evaluated by calling the function, and a new constant node
is inserted with the calculated value, replacing both the currently processed node and its argument nodes.

#### Expression List Optimization

In function arguments and inside parentheses, expression lists, e.g. multiple expressions separated by semicolons, can
be written. This is a useful feature to execute a list of expressions based on certain conditions (e.g. in `if`
or `loop`). While only the _last_ expression in a list determines the return value of the whole list, other expressions
may perform calculations, set variables etc. and also need to be executed in order to achieve the correct result.

There could also be expressions in the list which do not assign anything, and which are not the last expressions. These
expressions are referred to as "non state-changing", and only waste CPU cycles because the result of any calculation
done there is discarded. The expression compiler will keep track of the state-changing flag hierarchically, similar to
the const flag, and remove any expressions which are nether state-changing nor relevant to the return value.

In the case that a state-changing operator, e.g. an assignment, has a constant value as the left operand, it will be
replaced by the const-evaluation optimization and lose its state-changing flag. Consider the following expression, where
the first two expressions will be optimized out:

```
sin(1 + 2; 3);
tan(5) = x;
5 = rand(100);
x = cos($PI * .54);
5;
```

The third expression cannot be optimized out, because the assignment operator is potentially state-changing if it
assigns to a variable or memory location and the `rand` function is not const-evaluable.

The fourth expression is very similar, but this time, the use of a variable prevents the expression form being
const-evaluable.

The fifth and last expression is a simple constant and determines the return value of the whole expression list.

---

### 3rdparty Libprojectm Vendor Projectm Eval Docs Expression Syntax (`3rdparty/libprojectm/vendor/projectm-eval/docs/Expression-Syntax.md`)

Milkdrop Preset Expression Syntax
=================================

This document contains a full writeup of the expression syntax in Milkdrop presets. It documents the general syntax,
available operators and functions and also any specific, non-obvious behaviours. Any differences between Milkdrop's
original parser and projectM's are also documented where applicable.

This document does _not_ cover the `warp_` and `comp_` shader code blocks. The shader code is written in DirectX HLSL,
which is better explained by Microsoft's documentation in the MSDN.

The document also doesn't cover the different code blocks, predefined variables and scope of the special t/q values.
Please refer to the preset authoring guide for these.

## General Syntax

The expression language only knows a few syntactic features:

- Numbers, with or without decimals. Can also contain a base 10 exponent using the `e[+-]n` notation.
- Variables to hold a single number, both user-defined and predefined. May contain characters a-z, 0-9 and the
  underscore (`_`), while 0-9 must not be the first letter.
- Special constants beginning with `$`.
- A single expression, separated from other expressions in the same list via semicolons (`;`), with the last semicolon
  being optional.
- Calls to built-in functions in the form `func(arg1, arg2, ...)`.
- Mathematical, assignment and other operators.
- Subscript access `[]` for megabuf/gmegabuf access.
- Parentheses (`()`) to group statements and override precedence.
- In-line comments starting with `//` until the end of the current line
- Multi-line comments starting with `/*` and ended with `*/`.

### Return Types

Expressions can return either a numeric value or a reference to a variable or memory location. What is actually returned
is determined by the function or operator that is executed last. If the expression only consists or a single token, then
the following applies:

- If the expression token is a constant number (`1.0;`), the number is returned by value.
- If the expression token is a variable name (`x;`), a reference to the variable is returned.

For most functions, the return type doesn't matter. If it's a reference, the value pointed to by the reference is used.
References only behave differently when used on the left side of assignments or in the forst argument of the  `assign()`
function. In this case, the variable or (g)megabuf location the reference points to is assigned a new value.

### Expression Result

Every expression returns its outermost result, as a value or reference as described above. When writing multiple
expressions (separated by semicolon) in a list, the result of the _rightmost_ (or last) expression is returned. The
results of previous expressions are discarded.

In general, each expression will be in the form `var = expression;`, assigning a value to the given variable (or
megabuf index). Expressions will also always return a value, so when used as function arguments, this value will be
used. For example, all the following statements will call the `sin()` function with the argument `4`:

```
x = sin(val = 2 * 2);
y = sin(2 + 2);
z = sin(4.0);
```

### Variable and Function Names, Limits

Variable and function names are generally case-insensitive, making `variable` equivalent to `vArIaBlE`.

Any text in expressions - starting with either a letter from a to z or an underscore, followed by more of these
characters and also numbers from 0 to 9 - is first checked to be a built-in function. If it is not a function, the
parser will interpret it as a variable.

Functions always need to be followed by parentheses (`sin(expr)`), while variables must not.

Milkdrop imposes a 16-character limit on variable names. projectm-eval does not have a hard limit, but it's advisable to
not use more than 16 characters for Milkdrop compatibility.

Milkdrop also has a limit of 64 user-defined variables, which also isn't applied by projectm-eval.

#### Global "Register" Variables

In addition to gmegabuf, there are an additional 100 variables which can be used to store global values. These variables
are named `reg00`, `reg01` etc. up to `reg99`. Values stored in those variables are available in al execution contexts,
in the same way as gmegabuf.

Note the index must always be written with two digits. `reg3` is _not_ considered a global variable and will only have a
local scope as any other variable. The same is true for more digits like `reg123`.

Same as with gmegabuf, global variables are not necessarily `0` when a preset is initialized, and they can change at any
time when two presets using the same global variables are blended during a transition.

### Constants

All constants are converted into floating-point numbers internally, even if written as integers.

As with all other names, constant names (and hexadecimal values) are also case-insensitive.

#### Numerical Constants

Basic numerical/decimal constants can be defined in the code in the following formats:

- Integer values: `1` (or `1.`)
- Decimal values: `1.234` (values between 0 and 1 can be abbreviated with `.234`, which equals `0.234`)
- Base 10 exponential form: `1.234e5` equals `123400` and `1.234e-5` equals `0.00001234`

#### Predefined Constants

A few named convenience constants can be used:

- `$PI`: Equals `3.141592653589793`
- `$E`: Equals `2.71828183`
- `$PHI`: Equals `1.61803399`

#### Hexadecimal Constants

Hexadecimal constants start with `$X`, immediately followed by the hexadecimal numbers.

Example: `$XFF` converts to `255`.

#### Character (Ordinal) Constants

Constants can also convert a single character into its ordinal (ASCII) value using the form `$'c'`, where `c` is the
character to convert.

Example: `$'a'` converts to `97`.

### Operator Precedence

Operator precedence is defined in a similar way as in C, except the `^` operator, which has a different
meaning in Milkdrop presets (pow() instead of binary XOR).

See the [C precedence table on cppreference.com](https://en.cppreference.com/w/c/language/operator_precedence) for
details. The pow operator is applied just after the unary plus/minus operators, having a slightly lower precedence.

### Subscript Access

The subscript operator or "array access operator" has a slightly different meaning than in other programming languages.
The Milkdrop expression syntax only knows a single data type, individual numbers, so there are no arrays.

If any index value is not an integer, it is _rounded_ to the nearest integer after calculating the final index (e.g.
adding index and offset first, then rounding).

The subscript operator is instead used to address memory locations in megabuf and gmegabuf. There are three possible
syntax variants:

#### Global Memory Access

Accessing the gmegabuf is possible by using the special keyword `gmem`, followed by an index in the subscript brackets.
The following statement sets gmegabuf location 10.000 to the current value of `x`:

```
gmem[10000] = x;
```

Any memory index from 0 to 8.388.607 (= 128 * 65536) can be addressed.

#### Local Memory Access

Accessing the current context memory buffer (megabuf) can be done by writing the index before a set of empty brackets.
The following example is analogous to the above, but it sets index 10.000 of the local memory instead:

```
10000[] = x;
```

#### Local Memory Access with Offset

An optional offset can be provided in the brackets, which is simply added to the index on the outside. The following
example will set memory index 10.123 to the value of `x`:

```
10000[123] = x;
```

Both index and offset values can of course be calculated with expressions. So the following expression is valid:

```
if(x > 5,5000,1000)[(sin(y) + 1 * .5) * 1000] = z;
```

### Using Parentheses

Parentheses can be used to specify a specific order in which operations are executed. Expressions inside parentheses are
always evaluated, and the result of the evaluation is then used to evaluate any outside expression.

Inside parentheses, using expression lists is also valid. The result is, as described above, the value of the last
expression in the list. For example, the following expression will use `5` as the return value:

```
x = a * (b + c; d + e; 2 + 3);
```

The first two operations will do nothing, as they don't set a variable or memory value and the results are discarded.

### Comments

For more complex calculations, it might be a good idea to leave some comments in the expressions to describe what's done
in a specific line or block. Comments can also be useful to quickly disable a line or block of code to try out things
when writing a preset.

Comments can be used as end-of-line or block variants:

```
x = sin(5); // This comment is only valid until the line ends
y = sin($PI * .5); /* This comment
spans
multiple
lines and the following expression is executed: */ z = 5;
```

Comments can appear inside any expression, but _not_ within a variable, function name, number or other constant.
Writing `x = var/*comment*/iable;` is invalid (but `x = sin/*comment*/(variable);` is).

## Operators

The following operators can be used in expressions.

### Mathematical Operators

These operators carry out basic mathematical operations.

- `+`: Adds both operands.
- `-`: Subtracts the right operand from the left.
- `*`: Multiplies both operands.
- `/`: Divides the left operand by the right. If the divisor is zero, the result of the operation is `0` instead
  of `Inf`.
- `%`: Converts the operands to integers and returns the remainder of the left by the right operand.
- `^`: Calculates the left operand to the power of the right operand.

### Equality Operators

These operators check for equality or inequality of the operands and return a boolean result:

- `==`: Equal. Returns `1` if both operands are equal, `0` if not.
- `!=`: Not equal. Returns `1` if both operands are not equal, `0` if they are.
- `<`: Below. Returns `1` if the left operand is below the right operand, `0` otherwise.
- `>`: Above. Returns `1` if the left operand is above the right operand, `0` otherwise.
- `<=`: Below or equal. Returns `1` if the left operand is below or equal to the right operand, `0` otherwise.
- `>=`: Above or equal. Returns `1` if the left operand is above or equal to the right operand, `0` otherwise.

### Binary Arithmetic Operators

The following operators allow to carry out bitwise operations on integer representations of the operands:

- `&`: Converts both arguments to integers and calculates the bitwise AND between the resulting operands.
- `|`: Converts both arguments to integers and calculates the bitwise OR between the resulting operands.

### Boolean Operators

Boolean operators only check an operand to be zero or non-zero, then return the according result:

- `&&`: Returns `1` if both operands are non-zero and `0` if any operand is zero.
- `||`: Returns `1` if one or both operands are non-zero and `0` if both operands are zero.
- `!`: Unary operator. Returns `1` if the operand is zero and `0` if the operand is non-zero.
- `a ? b : c`: The ternary operator. Evaluates the `a` operand and evaluates and returns the `b` operand if the
  condition is non-zero. If the condition evaluates to zero, only the `c` operand is evaluated and returned.

### Assignment Operators

Assignment operators can simply assign the result of the right-hand side to a variable or megabuf index, or in case of
compound operators `a OP= b` also carry out an additional operation equivalent to `a = a OP B`. All assignment operators
return a reference to the left operand.

- `=`: Assigns the value of the right operand to the left operand.
- `+=`: Adds the value of the right operand to the left operand and assigns the result to the left operand.
- `-=`: Subtracts the value of the right operand from the left operand and assigns the result to the left operand.
- `*=`: Multiplies the value of the right operand with the left operand and assigns the result to the left operand.
- `/=`: Divides the left operand by the value of the right operand and assigns the result to the left operand. If the
  divisor is zero, the result of the operation is `0` instead of `Inf`.
- `%=`: Calculates the remainder of the rounded integer values of the left operand divided by the right operand and
  assigns the result to the left operand. If the divisor is `0`, the result will also be `0`.
- `^=`: Calculates the left operand to the power of the right operand and assigns the result to the left operand.
- `&=`: Calculates the binary AND of the rounded integer values of the left and right operands and assigns the result to
  the left operand.
- `|=`: Calculates the binary OR of the rounded integer values of the left and right operands and assigns the result to
  the left operand.

### Subscript Operator

The subscript - or index - operator `[]` is a special notation to access megabuf and gmegabuf. If the inside of the
brackets is empty, it is interpreted as a `0`. For more details, see the "Subscript Access" section above.

## Built-in Functions

The following functions are built into the expression parser and can be used in all Milkdrop 2.x presets.

### above(left, right)

Returns `1` if `left` has a larger value than `right`, otherwise `0`.

Same as the `>` operator.

### abs(val)

Returns the absolute (positive) value of `val`.

### acos(val)

Calculates and returns the arc cosine (inverse cosine) of `val`. The angle is interpreted as radians.

### asin(val)

Calculates and returns the arc sine (inverse sine) of `val`. The angle is interpreted as radians.

### assign(dest, val)

Assign `val` to the reference pointed by `dest` and return `dest`. If `dest` is not a reference, the result is the
_value_ of `val`.

Same as the assignment operator `=`.

### atan(val)

Calculates and returns the arc tangent (inverse tangent) of `val`. The angle is interpreted as radians.

### atan2(x, y)

Calculates and returns the polar coordinate angle associated with the coordinate represented by `x,y`. The angle is
returned as radians.

See the [Wikipedia definition of atan2](https://en.wikipedia.org/wiki/Atan2) for details.

### band(left, right)

Evaluates both arguments and returns `1` if both arguments evaluate to a non-zero value and `0` if at least one argument
is zero.

Note: The boolean AND operator `&&` returns the same result, but only evaluates the second argument if the first one is
not zero!

### below(left, right)

Returns `1` if `left` has a smaller value than `right`, otherwise `0`.

Same as the `<` operator.

### bnot(val)

Boolean NOT operator. Returns `1` if `val` is `0`, otherwise `0`.

Same as the `!` operator.

### bor(left, right)

Evaluates both arguments and returns `1` if at least one argument evaluates to a non-zero value and `0` if both
arguments are zero.

Note: The boolean OR operator `||` returns the same result, but only evaluates the second argument if the first one is
zero!

### ceil(val)

Rounds the value of `val` to the next _larger_ integer number in reference to `0`.

### cos(val)

Calculates and returns the cosine of `val`. The angle is interpreted as radians.

### equal(left, right)

Compares both values and returns `1` of they are equal or `0`if not.

Same as the `==` operator.

### exec2(expr1, expr2)

Executes both expressions and returns the result of the second one.

### exec3(expr1, expr2, expr3)

Executes all three expressions in order and returns the result of the third one.

### exp(val)

Exponential function with base `e` to the power of `val`.

Equivalent to the expression `$E ^ val`.

### floor(val)

Rounds the value of `val` to the next _smaller_ integer number in reference to `0`.

### freembuf(index)

Requests freeing all memory blocks in `megabuf` (NOT `gmegabuf`) beginning with the block `index` is in. This may result
in memory being freed before the given index.

**Note:** This function is currently a no-op in both Milkdrop and projectM. It does _not_ actually free any memory or
reset the memory contents.

Memory blocks are 65536 entries large, and there is a total of 128 blocks.

### gmegabuf(index)

Returns a reference to the storage location of `index` in the global memory buffer.

Any memory index from 0 to 8.388.607 (= 128 * 65536) can be addressed. Any index outside of this range will return the
fixed _value_ `0`, and no memory is changed when assigning another value to it.

### if(cond, trueval, falseval)

Evaluates `cond`, and returns `trueval` if the result is non-zero. Otherwise, `falseval` is returned.

If either `trueval` or `falseval` evaluate to a reference, the reference is passed through. Thus, assigning a value to
the result of `if()` is possible:

`if(x > 5, a, b) = 10;` will assign `10` to `a`  if `x > 5` and to `b` if `x <= 5`.

### int(val)

Truncates any decimals from `val`, effectively converting it into an integer.

### invsqrt(val)

Calculates the [fast inverse square root](https://en.wikipedia.org/wiki/Fast_inverse_square_root) of `val`.

### log(val)

Calculates and returns the ("natural") logarithm to base `e` of `val`.

### log10

Calculates and returns the logarithm to base 10 of `val`.

### loop(count, expr)

Executes `expr` exactly `count` times.

As mentioned in the grammar section, `expr` can also consist of multiple expressions separated by semicolon. this is
also true for `count`, but expressions in this argument are only evaluated once before the first loop iteration starts.

The loop will always abort after 2^20 (~1 million) iterations.

Be careful when nesting loops, as the loop count and associated run time will grow exponentially with each nesting
level, which can hang up the application.

### max(val1, val2)

Returns the larger of the two _values_ of `val1` and `val2`.

### megabuf(index)

Returns a reference to the storage location of `index` in the local memory buffer.

Any memory index from 0 to 8.388.607 (= 128 * 65536) can be addressed. Any index outside of this range will return the
fixed _value_ `0`, and no memory is changed when assigning another value to it.

### memcpy(dest, src, count)

Copies `count` values starting at `src` to `dest`. Returns a reference to `dest`.

Memory areas are allowed to overlap.

Any source or destination memory falls outside the allowed indices of 0 to 8.388.607, the range is trimmed accordingly
and only a data block is copied that fits into both areas.

### memset(dest, value, count)

Fills `count` number of memory slots beginning at `dest` with `value`.

If the range falls outside the allowed indices of 0 to 8.388.607, the range is trimmed accordingly.

This function is _way_ faster than setting individual values to 0 in a `loop()` and should be preferred if a larger
memory block needs to be initialized or reset with a single number.

### min(val1, val2)

Returns the smaller of the two _values_ of `val1` and `val2`.

### pow(base, exp)

Calculates `base` to the power of `exp` and returns the resulting value.

### rand(max)

Calculates a pseudo-random number (using the Mersenne-Twister algorithm) between 0 and `max`.

`max` can be a floating-point value.

### sigmoid(a, b)

Calculates the logistic curve with an argument of `(-a * b)` and returns the result.

This is equivalent to the expression `tmp = 1 + pow($E, (-a + b)); if(tmp > 0.00001, 1 / tmp, 0);`.

### sign(val)

Returns the signage of `val`, which is `-1` for negative values, `1` for positive values and `0` for `0`.

### sin

Calculates and returns the sine of `val`. The angle is interpreted as radians.

### sqr(val)

Calculates and returns the square of `val`.

This is equivalent to the expression `val * val`.

### sqrt(val)

Calculates and returns the square root of `val`.

### tan(val)

Calculates and returns the tangent of `val`. The angle is interpreted as radians.

### while(expr)

Executes `expr` at least once and loops until it returns `0`.

`expr` can be a semicolon-separated list of expressions. Only the return value of the last expression in the list is
used to determine the loop abort condition.

The loop will always abort after 2^20 (~1 million) iterations.

Be careful when nesting loops, as the loop count and associated run time will grow exponentially with each nesting
level, which can hang up the application.

### Internal Functions and Aliases

The following functions are defined internally, some being aliases to the above functions, others being used as actual
implementations of operators. Depending on the operator being unary or binary, each function has one or two parameters.

- _aboeq => Operator `>=`
- _above => Operator `>`
- _add => Operator `+`
- _addop => Operator `+=`
- _and => Operator `&&`
- _andop => Operator `&=`
- _beleq => Operator `<=`
- _below => Operator `<`
- _div => Operator `/`
- _divop => Operator `/=`
- _equal => Operator `==`
- _gmem => Alias for `gmegabuf`
- _if => Operator `?:`, alias for `if`
- _mem => Alias for `megabuf`
- _mod => Operator `%`
- _modop => Operator `%=`
- _mul => Operator `*`
- _mulop => Operator `*=`
- _neg => Negation operator `-`
- _not => Operator `!`
- _noteq => Operator `!=`
- _or => Operator `||`
- _orop => Operator `|=`
- _powop => Operator `^=`
- _set => Operator `=`, alias for `assign`
- _sub => Operator `-`
- _subop => Operator `-=`

### Externally-defined Functions

Be aware that if this parser is used in other projects or non-Milkdrop-compatible presets, additional functions may be
defined which can't be used as variable names. One example are the additional `getosc` and `getspec` functions defined
in AVS.

## Memory Buffers

Each execution context has two associated memory buffers, a local buffer and a global buffer. Each buffer can hold up to
2^23 (8.388.608) individual floating-point numbers which can be addressed via their zero-based index.

The local buffer is only valid within the same execution context. In classic Milkdrop, there are these contexts, each of
which having its own `megabuf`:

- The global per-frame context (`per_frame_init_` and `per_frame_`)
- The per-vertex/per-pixel mesh context (`per_pixel_`)
- The wave per-frame context, one per waveform (`wave_N_init` and `wave_N_per_frame`)
- The wave per-point context, one per waveform (`wave_N_per_point`)
- The shape per-frame context, one per shape (`shape_N_init` and `shape_N_per_frame`)

The global memory buffer, referred to as `gmegabuf`, only exists once and is used for _all_ execution contexts. It is
even shared between different Milkdrop presets. Keep this in mind when using the buffer, as the contents may be changed
by another preset during the transition phase!

Local buffers always start empty and return zero for all indices when being accessed the first time. The global buffer
will also start this way, but is never reset. Code using the global megabuf should initialize the required indices with
known values.

Memory is allocated in blocks of 64K (65.536) values each, with a total of 128 of such blocks per buffer. When using
memory indices, ideally keep the indices close together to allocate only a minimum number of blocks and save the user's
RAM resources.

### Setting Large Blocks of Memory to a Certain Value

If a larger memory region needs to be initialized with a single value, e.g. resetting a part of `gmegabuf`, assigning
single values in a `loop` is time-consuming. The `memset` function can be used to achieve the same result in a very fast
operation. Calling the following function will reset values 10.000 to 19.999 to `5`:

```
memset(10000, 5, 10000);
```

### Copying/Moving a Range of Data

Sometimes it's required to copy or move a continuous block of values, e.g. moving data from previous frames left and
adding a new set of data points at the end. This can be done in a `loop`, but again is very time-consuming. The `memcpy`
function is able to perform this operation in a single call. It also supports moving memory in overlapping areas - the
original contents are first copied into a temporary buffer, then written to the new location. To move data forward in a
1000-value large block by 100 indices, with the block starting at index 5000 looks like this:

```
memcpy(5000, 5100, 900);
```

The last 100 values will appear twice in the block, while the first 100 got overwritten.

## Caveats and Tricks

For most uses, the expression language is quite straightforward to use. Due to the implementation, users can take
advantage of some features while they need to be aware of a few details that may cause problems.

### Using References

As mentioned in the sections above, some functions may or may not return variable or memory references. It is, in any
case, valid to assign a value to any other value, even a constant. So while the following statement doesn't do anything
useful, it is valid:

```
assign(1, 2);
```

The function itself will return the value `2` as expected, but the actual assignment is discarded.

Other constructs are more helpful, for example to choose between two or more variables to assign a value to. The
following code will assign `10` to either `a`, `b` or `c` depending on the value of `x`:

```
assign(if(x < 0, a, if(x > 0), c, b), 10);
```

This works because `if` will pass the result of the appropriate true/false expression, which can be a reference to a
variable. In the above example, it would also be valid to return `0` instead of `b` is no assignment is wanted, but
the `assign()` function should still return the value 10 in any case.

The last example can also be written in the assignment form, with `if()` as the left operand:

```
if(x < 0, a, if(x > 0), c, b) = 10;
```

### Conditions in `if` and `while`

A few functions check a condition to execute a certain instruction. For example, `if` decides whether to use the true or
false argument, and `while` uses the value of the last expression to check if the loop should abort.

Due to how floating-point numbers work in computers, not all calculations may return exactly `0.0`, even when using
simple constants. The reason is that some numbers can't be exactly represented by the binary number used by the CPU and
needs to be slightly modified. Using such a number in math equations may even increase the error, and the result might
never be exactly zero.

To make the expression work as intended, one of the following approaches may be used, depending on what is required:

1. If only the integer part of the value is of interest, use `int(val)` to truncate any decimals.
2. Round the result to the nearest integer with `round(val)` if the error can be larger than `0.5`.
3. Compare the absolute value of the number to be smaller/larger than the allowed error, e.g. `abs(val) > 0.0001`

The boolean comparison operators (`<`, `==` etc.) will always return either `0.0` or `1.0`, which don't need to be
rounded and can be used directly for the condition check. Using those operators should always be preferred over directly
passing a calculated variable value as the conditional.

### Performance

While execution of the compiled programs is generally quite fast, some functions and code constructs can heavily impact
the performance, especially on low-end and embedded devices like the Raspberry Pi. To make presets available to a broad
audience, keep the following considerations in mind:

- Keep code in the `per_pixel_` block small and fast. If possible, perform CPU-intensive work in the `per_frame_` block
  and store the result in the `q` variables (or `gmegabuf` if required).
- The same is true for instanced shape and waveform `per_point` code.
- Do not overuse `loop` and `while`, especially avoid nesting them. If they are required, make sure the abort condition
  on the `while` loop is not affected by rounding errors. Try not to calculate heavy stuff inside a loop.
- Some math functions, specifically trigonometrical ones like `sin` and also `sqrt`, are expensive. Try to cache and
  reuse values instead of recalculating them multiple times.
- Try not to use `megabuf` and `gmegabuf` for everything. Normal variables, including the global `regNN`, have less
  overhead, as they do not require the additional memory allocation checking and address calculation.

---

### 3rdparty Libprojectm Vendor Projectm Eval Docs Memory Handling (`3rdparty/libprojectm/vendor/projectm-eval/docs/Memory-Handling.md`)

Handling Global Memory
======================

Each projectM-Eval context has its own megabuf, which will live inside the context and is deleted when the context is
destroyed. The same is true for any script-defined or externally registered variables. To share global data between
different execution contexts, there are two methods:

- The reg00-reg99 variables.
- The gmegabuf memory buffer.

The reg variables were available for a long time, while megabuf and gmegabuf were introduced in ns-eel2 during Milkdrop
2 development.

## Using the Built-in Global Memory Buffer

If the embedding application doesn't need to use multiple global memory buffers, for example if all execution contexts
will share the same global memory, then the built-in buffer and reg vars can be used by passing NULL for both parameters
in the `projectm_eval_context_create()` function:

```c
struct projectm_eval_context* ctx = projectm_eval_context_create(NULL, NULL);
```

To free and reset the global memory buffer, call `projectm_eval_memory_global_destroy()`. This will not reset the reg
variables though.

## Using Application-defined Global Memory Buffers

Both the gmegabuf and the reg variables can be instantiated by the embedding application to control which execution
contexts will share the data. Both the buffer and the reg variables can be shared individually.

### Custom gmegabuf

To create a custom global memory buffer, call `projectm_eval_memory_buffer_create()` and store the resulting pointer. It
is an opaque data structure which will receive the gmegabuf data as scripts execute. Then pass the pointer to all newly
created contexts. If the buffer is no longer needed, e.g. all contexts using it were destroyed, remember to also free
the buffer.

Example:

```c
projectm_eval_mem_buffer gmbuf = projectm_eval_memory_buffer_create();
struct projectm_eval_context* ctx = projectm_eval_context_create(gmbuf, NULL);

/* Execute stuff */

projectm_eval_context_destroy(ctx);
projectm_eval_memory_buffer_destroy(gmbuf);
```

Note that when creating the buffer, it doesn't allocate any actual buffer memory. Memory is reserved in small blocks
whenever an index is accessed for which no buffer exists yet.

### Custom reg Variables

Similar to the memory buffer, the reg variables need to be allocated and a pointer passed to the context upon creation.
In contrast to the buffer, the reg variables are stored in a simple array of type PRJM_EVAL_F with the size of 100
entries:

```c
PRJM_EVAL_F reg_vars[100] = {0};
struct projectm_eval_context* ctx = projectm_eval_context_create(NULL, &reg_vars);

/* Execute stuff */

projectm_eval_context_destroy(ctx);
```

## Multi-Threading Considerations

In general, executing code in the same context in multiple threads at the same time is generally unsupported as the
variables are shared between contexts. This also holds true for contexts sharing reg variables - while it may work,
multiple scripts changing reg vars in different threads may have negative impact on the other instances.

The above stays true for gmegabuf as well, but allocating memory makes things a bit more complicated. If there is a real
requirement of using the same gmegabuf in multiple threads at once, this can be done by implementing
the `projectm_eval_memory_host_lock_mutex()` and `projectm_eval_memory_host_unlock_mutex()` functions to set and release
proper locks. A non-recursive mutex is sufficient.

Note that using a mutex will prevent race conditions and memory loss (e.g. two thread trying to allocate the same memory
area), but it won't change the unpredictable behaviour of values changing unexpectedly.

As noted in the quick-start guide, an application using projectM-Eval is _required_ to implement the above functions. If
no locking is needed, they can be empty stubs.

---

--- METRICS ---
- Files Extracted: 8
- Estimated Token Budget: ~38163 tokens
- Canonical Reference: https://codewiki.google/github.com/clementine-player/Clementine