kunitoki · kunitoki · Sep 26, 2026 · Sep 20, 2026 · Sep 20, 2026 · Sep 21, 2026
diff --git a/.github/workflows/deploy_website.yml b/.github/workflows/deploy_website.yml
@@ -5,7 +5,8 @@ on:
     paths:
       - "**/workflows/deploy_website.yml"
       - "website/**"
-      - "docs/_static/images/**"
+      - "docs/**"
+      - "modules/*/yup_*.h"
       - "logo.svg"
     branches:
       - main

diff --git a/.gitignore b/.gitignore
@@ -39,6 +39,7 @@
 build/*
 cmake-build*
 out/*
+infer-out/*
 
 # Ides/Agents
 __pycache__/

diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -28,6 +28,7 @@ _yup_get_project_version_string (${CMAKE_CURRENT_LIST_DIR}/modules yup_version)
 _yup_message (STATUS "Building project version ${yup_version}")
 
 set (CMAKE_CXX_SCAN_FOR_MODULES 0)
+set (CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 if (YUP_PLATFORM_MAC)
     set (CMAKE_OSX_DEPLOYMENT_TARGET 11.0)

diff --git a/cmake/platforms/emscripten/shell.html b/cmake/platforms/emscripten/shell.html
@@ -91,8 +91,8 @@
       }
 
       .brand svg {
-        width: 20px;
-        height: 20px;
+        width: 24px;
+        height: 24px;
         filter: drop-shadow(0 0 8px rgba(10, 132, 255, 0.55));
       }
 
@@ -418,9 +418,9 @@
   <body data-mode="embedded">
     <header class="rail rail--top">
       <div class="brand">
-        <svg viewBox="0 0 24 24" aria-hidden="true">
-          <ellipse cx="12" cy="11" rx="10.2" ry="5.4" transform="rotate(-24 12 11)" fill="none" stroke="#0A84FF" stroke-width="1.6" opacity="0.65"/>
-          <path d="M12 2 21 21 12 16.4 3 21Z" fill="#0A84FF"/>
+        <svg viewBox="0 0 785 788" aria-hidden="true">
+          <path d="m 218,304 c 1.46086,2.14121 2.81679,4.35215 4.063,6.625 6.87,11.894 14.92,22.61 23.735,33.135 6.79935,7.89095 13.88584,15.74304 20.827,23.303 6.9847,7.85044 21.02947,19.89757 32.375,28.937 l 2.883,2.297 C 341.117,429.002 384.922,452.415 431,471 l 3.005,1.22 c 48.133,19.403 99.325,29.104 151.072,30.332 2.11733,0.0527 4.235,0.10833 6.353,0.167 l 3.757,0.092 C 598,503 598,503 599,504 c 0.096,2.008 0.117,4.019 0.113,6.028 v 1.987 c -0.004,2.27067 -0.0117,4.54167 -0.023,6.813 l -0.012,5.014 C 599.0598,529.8947 599.0338,535.94737 599,542 l -0.019,3.602 c -0.1954,37.39226 -0.6881,124.00677 -1.282,149.927 -0.0424,2.00555 -0.0784,4.01122 -0.108,6.017 -0.19,6.749 -1.089,12.17 -3.591,18.454 l -2,2 c -5.387,3.592 -8.524,4.627 -15,4 -8.63517,-4.36284 -12.57238,-9.33244 -19.71034,-16.64483 -7.41688,-7.78631 -10.20335,-11.02435 -16.94257,-18.3573 C 491.1243,634.11061 486,628 486,628 450.45729,587.68879 420.12289,552.17238 384.879,511.328 c -6.807,-8.434 -15.207,-14.76 -24.817,-19.64 -0.63,-0.326 -1.262,-0.651 -1.913,-0.986 -9.27,-4.524 -19.217,-6.205 -29.364,-7.534 l -3.492,-0.476 C 221.50265,469.07295 177.28506,462.05833 119.743,454.8 101.35194,452.44882 82.963199,450.07355 64.598,447.527 l -2.284,-0.287 c -6.542,-0.949 -12.243,-2.956 -16.751,-7.928 -2.64,-5.596 -3.224,-10.107 -1.438,-16.062 3.216,-5.575 7.676,-8.993 12.96,-12.543 l 1.739,-1.174 c 1.847333,-1.244 3.697667,-2.484 5.551,-3.72 l 3.861,-2.6 c 6.625124,-4.46088 13.265831,-8.89858 19.922,-13.313 5.675,-3.77 11.302,-7.607 16.934,-11.438 l 1.783,-1.213 1.78,-1.211 c 11.58,-7.873 23.223,-15.648 34.89,-23.39 9.906,-6.58 19.7,-13.3 29.424,-20.149 6.678,-4.682 13.493,-9.16 20.29,-13.666 1.73733,-1.152 3.474,-2.305 5.21,-3.459 l 1.69,-1.12 c 4.362,-2.902 8.618,-5.933 12.835,-9.04 C 215,304 215,304 218,304" fill="#005aff"/>
+          <path d="m 593,58 c 5.039,2.475 7.886,5.383 10.068,10.51 1.22,4.568 1.162,8.752 1.088,13.459 l -0.024,3.111 C 604.099,88.72 604.05,92.36 604,96 l -0.075,6.578 c -0.11482,9.79152 -0.24449,19.58287 -0.389,29.374 l -0.18,12.915 C 603.23867,153.24433 603.12,161.622 603,170 l 2.386,0.93 c 2.335,0.956 4.076,1.935 6.094,3.418 l 1.838,1.334 1.87,1.38 c 5.91986,3.54867 10.83927,8.23645 16.281,12.407 l 1.963,1.466 2.068,1.565 2.14,1.614 c 30.032,22.798 30.032,22.798 32.36,32.886 0.674,5.952 -0.671,10.144 -4,15 -3.335,3.526 -6.551,5.765 -11.488,6.238 -11.38,0.3 -16.481,-5.892 -24.512,-13.238 -6.23,-5.59 -12.871,-10.694 -19.482,-15.822 -1.25639,-0.97706 -2.5084,-1.95974 -3.756,-2.948 -1.854,-1.419 -1.854,-1.419 -4.762,-2.23 l 0.007,2.647 c 0.182,75.202 0.182,75.202 -0.579,112.75 l -0.139,6.923 -0.071,3.558 c -0.353,18.278 -0.537,36.559 -0.747,54.838 l -0.1,8.708 C 600.24367,414.28133 600.12,425.14 600,436 c 3.935,-0.442 7.868,-0.896 11.8,-1.352 l 3.33,-0.373 c 24.081,-2.816 45.83602,-5.91944 68.268,-26.841 7.17113,-6.90384 6.01539,-6.05577 8.915,-9.559 11.216,-14.364 13.126,-31.394 11.37,-49.059 -2.402,-16.297 -8.34,-31.482 -16.62,-45.628 -3.216,-5.845 -4.393,-10.59 -3.063,-17.188 1.706,-4.822 4.591,-8.412 9,-11 5.953,-2.11 11.077,-2.574 16.98,-0.145 14.044,7.96 22.081,34.825 26.253,49.432 7.97,29.798 6.676,60.462 -8.694,87.647 C 717.06,429.397 700.805,442.63 683,452 l -2.992,1.617 C 667.058,460.39 653.315,465.122 639,468 l -2.614,0.556 c -17.088,3.487 -34.005,3.82 -51.386,3.819 l -3.292,0.005 c -18.783,-0.003 -37.1,-1.234 -55.583,-4.692 l -3.602,-0.663 C 462.015,455.708 402.275,433.78 350,401 l -2.313,-1.438 C 338.635,393.93 329.617,388.285 321,382 l -3.543,-2.55 c -10.968,-7.933 -21.359,-16.443 -31.6,-25.29 -2.454,-2.118 -4.908,-4.2 -7.459,-6.203 C 275.744,345.791 273.394,343.45 271,341 l -2.648,-2.613 C 263.009,333.097 257.87,327.73 253,322 c -0.90133,-1.02667 -1.80367,-2.05267 -2.707,-3.078 C 227.468,292.884 207.84,262.115 200,228 l -0.53,-2.278 c -2.08023,-14.2604 -3.41946,-11.35453 -1.92,-29.122 -0.173,-23.24399 7.132,-39.834 19.45,-56.6 l 1.781,-2.492 C 222.668,132.261 226.921,128.08 232,124 l 2.73,-2.305 C 267.325,95.174 312.071,87.513 353,87.688 l 2.71,0.005 c 14.954,0.051 29.5,1.012 44.29,3.307 l 7.625,1.102 c 23.99,3.537 46.912,9.54 69.996,16.847 l 3.328,1.052 c 1.906,0.624 3.803,1.276 5.684,1.97 4.515,1.662 7.613,2.603 12.367,1.029 2.887,-1.634 2.887,-1.634 5.75,-3.812 15.15487,-11.173383 2.67041,-1.58396 33.438,-22.813 6.87,-4.744 13.797,-9.393 20.754,-14.007 2.312,-1.538 4.622,-3.08 6.93,-4.626 l 2.488,-1.664 c 1.61,-1.076667 3.219,-2.154 4.827,-3.232 l 2.208,-1.475 1.964,-1.315 C 582.153,56.97 587.46,57.471 593,58 m -281,69 -2.08,0.34 c -24.116,4.074 -49.285,14.24 -64.42,34.223 -8.47,12.57 -12.073,24.46 -11.937,39.625 l 0.022,3.6 c 0.175,9.342 1.292,17.396 4.415,26.212 l 1.32,3.77 c 4.547,12.337 11.498,30.775 22.68,38.23 124.78758,-83.49956 164.03866,-108.97569 187.273,-125.631 3.33,-2.163 5.14,-3.752 6.727,-7.369 -25.121,-7.11 -49.998,-12.444 -76,-15 l -2.86,-0.29 c -8.126,-0.759 -16.231,-0.95 -24.39,-0.96 l -2.102,-0.004 C 337.69677,123.7425 324.76831,124.83102 312,127" fill="#005aff"/>
         </svg>
         <b>YUP<i>!</i></b>
       </div>

diff --git a/cmake/yup_dsp_compiler.cmake b/cmake/yup_dsp_compiler.cmake
@@ -49,7 +49,7 @@ function (yup_add_ydsp_bundle library_name)
     set (multi_value_args TARGETS OPTIONS)
     cmake_parse_arguments (YUP_ARG "" "${one_value_args}" "${multi_value_args}" ${ARGN})
     if (NOT YUP_ARG_SOURCE)
-        message (FATAL_ERROR "yup_add_ydsp_bundle: SOURCE argument is required")
+        _yup_message (FATAL_ERROR "yup_add_ydsp_bundle: SOURCE argument is required")
     endif()
 
     _yup_set_default (YUP_ARG_OUTPUT_NAME "${library_name}")
@@ -60,7 +60,7 @@ function (yup_add_ydsp_bundle library_name)
 
     set (bundle_path "${CMAKE_CURRENT_BINARY_DIR}/${YUP_ARG_OUTPUT_NAME}.ydsb")
     if (NOT EXISTS "${source_path}")
-        message (FATAL_ERROR "yup_add_ydsp_bundle: source file not found: ${source_path}")
+        _yup_message (FATAL_ERROR "yup_add_ydsp_bundle: source file not found: ${source_path}")
     endif()
     set (target_arguments)
     foreach (target IN LISTS YUP_ARG_TARGETS)

diff --git a/cmake/yup_shader_bundler.cmake b/cmake/yup_shader_bundler.cmake
@@ -65,30 +65,38 @@ function (_yup_build_shader_bundler_tool output_variable)
     list (LENGTH candidate_exes num_candidates)
 
     if (num_candidates EQUAL 0)
-        message (FATAL_ERROR "Failed to locate built shader bundler tool in ${tool_build_dir}")
+        _yup_message (FATAL_ERROR "Failed to locate built shader bundler tool in ${tool_build_dir}")
     endif()
 
     list (GET candidate_exes 0 tool_exe)
 
+    file (SHA256 "${tool_exe}" tool_hash)
     set_property (GLOBAL PROPERTY YUP_SHADER_BUNDLER_EXECUTABLE "${tool_exe}")
+    set_property (GLOBAL PROPERTY YUP_SHADER_BUNDLER_SHA256 "${tool_hash}")
     _yup_message (STATUS " * shader bundler executable: ${tool_exe}")
 
     set (${output_variable} "${tool_exe}" PARENT_SCOPE)
 endfunction()
 
 #==============================================================================
-# Compiles a vertex/fragment GLSL shader pair into a .ysl bundle (at configure
-# time) and embeds it into an OBJECT library that can be linked into a target.
+# Compiles a vertex/fragment GLSL shader pair, or a compute shader, into a .ysl
+# bundle (at configure time) and embeds it into an OBJECT library that can be
+# linked into a target. The bundle is only regenerated when the tool, the
+# arguments or the content of a stage or DEPENDS file changed.
 #
 # Usage:
 #   yup_add_shader_bundle (<library_name>
 #       VERT           <path to .vert file>
 #       FRAG           <path to .frag file>
+#       | COMPUTE      <path to .comp file>
 #       [OUTPUT_NAME   <basename>]      # default: <library_name>
 #       [RESOURCE_NAME <symbol>]        # default: <library_name>
 #       [NAMESPACE     <namespace>]     # default: yup
 #       [ENTRY         <entry point>]   # default: main
 #       [GLSL_VERSION  <version>]       # default: 450
+#       [BUNDLE_RESOURCE <variable>]    # don't embed, see below
+#       [BUNDLE_DESTINATION <path>]     # default: <OUTPUT_NAME>.ysl
+#       [DEPENDS       <file>...]       # extra inputs, e.g. #included files
 #       [OPTIONS       <flag>...])      # extra flags forwarded to yup_shader_bundler
 #
 # OPTIONS forwards any additional yup_shader_bundler flags verbatim, e.g.
@@ -99,53 +107,107 @@ endfunction()
 #     extern const uint8_t  <RESOURCE_NAME>_data[];
 #     extern const size_t   <RESOURCE_NAME>_size;
 # The bytes can be loaded at runtime with ShaderBundle::loadFromData().
+#
+# With BUNDLE_RESOURCE no library is created: the .ysl is left in
+# CMAKE_CURRENT_BINARY_DIR and <variable> is set to "<ysl path>@<BUNDLE_DESTINATION>",
+# ready to be passed to the BUNDLE_RESOURCES of yup_standalone_app. Load it at
+# runtime with ShaderBundle::loadFromFile().
 
 function (yup_add_shader_bundle library_name)
     set (options "")
-    set (one_value_args VERT FRAG OUTPUT_NAME RESOURCE_NAME NAMESPACE ENTRY GLSL_VERSION)
-    set (multi_value_args OPTIONS)
+    set (one_value_args VERT FRAG COMPUTE OUTPUT_NAME RESOURCE_NAME NAMESPACE ENTRY GLSL_VERSION BUNDLE_RESOURCE BUNDLE_DESTINATION)
+    set (multi_value_args OPTIONS DEPENDS)
 
     cmake_parse_arguments (YUP_ARG "${options}" "${one_value_args}" "${multi_value_args}" ${ARGN})
 
-    if (NOT YUP_ARG_VERT)
-        message (FATAL_ERROR "yup_add_shader_bundle: VERT argument is required")
+    if (YUP_ARG_COMPUTE AND (YUP_ARG_VERT OR YUP_ARG_FRAG))
+        _yup_message (FATAL_ERROR "yup_add_shader_bundle: COMPUTE can't be combined with VERT or FRAG")
     endif()
-    if (NOT YUP_ARG_FRAG)
-        message (FATAL_ERROR "yup_add_shader_bundle: FRAG argument is required")
+    if (NOT YUP_ARG_COMPUTE AND NOT (YUP_ARG_VERT AND YUP_ARG_FRAG))
+        _yup_message (FATAL_ERROR "yup_add_shader_bundle: either VERT and FRAG, or COMPUTE, are required")
     endif()
 
     _yup_set_default (YUP_ARG_OUTPUT_NAME "${library_name}")
     _yup_set_default (YUP_ARG_RESOURCE_NAME "${library_name}")
     _yup_set_default (YUP_ARG_NAMESPACE "yup")
     _yup_set_default (YUP_ARG_ENTRY "main")
     _yup_set_default (YUP_ARG_GLSL_VERSION "450")
-
-    get_filename_component (vert_path "${YUP_ARG_VERT}" ABSOLUTE)
-    get_filename_component (frag_path "${YUP_ARG_FRAG}" ABSOLUTE)
-
-    if (NOT EXISTS "${vert_path}")
-        message (FATAL_ERROR "yup_add_shader_bundle: vertex shader not found: ${vert_path}")
-    endif()
-    if (NOT EXISTS "${frag_path}")
-        message (FATAL_ERROR "yup_add_shader_bundle: fragment shader not found: ${frag_path}")
-    endif()
+    _yup_set_default (YUP_ARG_BUNDLE_DESTINATION "${YUP_ARG_OUTPUT_NAME}.ysl")
+
+    set (stage_args "")
+    set (stage_paths "")
+    set (stage_arg_names VERT FRAG COMPUTE)
+    set (stage_names vertex fragment compute)
+    foreach (stage_arg stage IN ZIP_LISTS stage_arg_names stage_names)
+        if (NOT YUP_ARG_${stage_arg})
+            continue()
+        endif()
+
+        get_filename_component (stage_path "${YUP_ARG_${stage_arg}}" ABSOLUTE)
+        if (NOT EXISTS "${stage_path}")
+            _yup_message (FATAL_ERROR "yup_add_shader_bundle: ${stage} shader not found: ${stage_path}")
+        endif()
+
+        list (APPEND stage_args --stage ${stage} "${stage_path}")
+        list (APPEND stage_paths "${stage_path}")
+    endforeach()
+
+    set (depend_paths "")
+    foreach (depend IN LISTS YUP_ARG_DEPENDS)
+        get_filename_component (depend_path "${depend}" ABSOLUTE)
+        if (NOT EXISTS "${depend_path}")
+            _yup_message (FATAL_ERROR "yup_add_shader_bundle: dependency not found: ${depend_path}")
+        endif()
+
+        list (APPEND depend_paths "${depend_path}")
+    endforeach()
+
+    # ==== Re-run the configure step when an input changes
+    set_property (DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${stage_paths} ${depend_paths})
 
     # ==== Ensure the host tool is available (built and cached once)
     _yup_build_shader_bundler_tool (shader_bundler_exe)
 
-    # ==== Generate the .ysl bundle at configure time
+    # ==== Generate the .ysl bundle at configure time, unless tool, arguments and inputs are unchanged
     set (bundle_path "${CMAKE_CURRENT_BINARY_DIR}/${YUP_ARG_OUTPUT_NAME}.ysl")
+    set (bundle_key_path "${bundle_path}.sha256")
 
-    _yup_message (STATUS "Generating shader bundle ${bundle_path}")
-    _yup_execute_process_or_fail (
+    set (bundler_command
         "${shader_bundler_exe}"
-            --vert "${vert_path}"
-            --frag "${frag_path}"
+            ${stage_args}
             --output "${bundle_path}"
             --entry "${YUP_ARG_ENTRY}"
             --glsl-version "${YUP_ARG_GLSL_VERSION}"
             ${YUP_ARG_OPTIONS})
 
+    get_property (bundle_key GLOBAL PROPERTY YUP_SHADER_BUNDLER_SHA256)
+    string (APPEND bundle_key "${bundler_command}")
+    foreach (input_path IN LISTS stage_paths depend_paths)
+        file (SHA256 "${input_path}" input_hash)
+        string (APPEND bundle_key "${input_path}=${input_hash}")
+    endforeach()
+    string (SHA256 bundle_key "${bundle_key}")
+
+    set (previous_bundle_key "")
+    if (EXISTS "${bundle_path}" AND EXISTS "${bundle_key_path}")
+        file (READ "${bundle_key_path}" previous_bundle_key)
+    endif()
+
+    if (bundle_key STREQUAL previous_bundle_key)
+        _yup_message (STATUS "Shader bundle ${bundle_path} is up to date")
+    else()
+        _yup_message (STATUS "Generating shader bundle ${bundle_path}")
+        file (REMOVE "${bundle_key_path}")
+        _yup_execute_process_or_fail (${bundler_command})
+        file (WRITE "${bundle_key_path}" "${bundle_key}")
+    endif()
+
+    # ==== Hand the bundle over to BUNDLE_RESOURCES instead of embedding it
+    if (YUP_ARG_BUNDLE_RESOURCE)
+        set (${YUP_ARG_BUNDLE_RESOURCE} "${bundle_path}@${YUP_ARG_BUNDLE_DESTINATION}" PARENT_SCOPE)
+        return()
+    endif()
+
     # ==== Embed the generated bundle into an object library
     yup_add_embedded_binary_resources (
         ${library_name}

diff --git a/cmake/yup_utilities.cmake b/cmake/yup_utilities.cmake
@@ -298,7 +298,7 @@ endfunction()
 
 function (_yup_merge_plist original_plist subset_xml_string output_plist)
     if (NOT EXISTS "${original_plist}")
-        message (FATAL_ERROR "Original plist file does not exist: ${original_plist}")
+        _yup_message (FATAL_ERROR "Original plist file does not exist: ${original_plist}")
     endif()
 
     file (COPY "${original_plist}" DESTINATION "${output_plist}")
@@ -312,7 +312,7 @@ function (_yup_merge_plist original_plist subset_xml_string output_plist)
         ERROR_VARIABLE error_message)
 
     if (NOT result EQUAL 0)
-        message (FATAL_ERROR "Failed to merge plist: ${error_message}")
+        _yup_message (FATAL_ERROR "Failed to merge plist: ${error_message}")
     endif()
 
     file (REMOVE "${temp_plist}")
@@ -329,7 +329,7 @@ function (_yup_execute_process_or_fail)
 
     if (NOT result EQUAL 0)
         _yup_join_list_with_separator ("${ARGN}" " " "" "" command_string)
-        message (FATAL_ERROR "Failed to execute command '${command_string}': ${error_message}")
+        _yup_message (FATAL_ERROR "Failed to execute command '${command_string}': ${error_message}")
     endif()
 endfunction()
 
@@ -342,7 +342,7 @@ function (_yup_download_file url file_path expected_sha256)
     foreach (attempt RANGE 1 ${max_attempts})
         if (attempt GREATER 1)
             math (EXPR retry_delay "(${attempt} - 1) * 5")
-            message (STATUS "Download of ${url} failed (${error_message}), retrying in ${retry_delay}s (attempt ${attempt}/${max_attempts})")
+            _yup_message (STATUS "Download of ${url} failed (${error_message}), retrying in ${retry_delay}s (attempt ${attempt}/${max_attempts})")
             execute_process (COMMAND "${CMAKE_COMMAND}" -E sleep ${retry_delay})
         endif()
 
@@ -366,7 +366,7 @@ function (_yup_download_file url file_path expected_sha256)
         file (REMOVE "${file_path}")
     endforeach()
 
-    message (FATAL_ERROR "Failed to download ${url} after ${max_attempts} attempts: ${error_message}")
+    _yup_message (FATAL_ERROR "Failed to download ${url} after ${max_attempts} attempts: ${error_message}")
 endfunction()
 
 #==============================================================================

diff --git a/codecov.yml b/codecov.yml
@@ -15,6 +15,7 @@ coverage:
         threshold: 5%
         base: auto
         flags:
+          - yup_ai
           - yup_animation
           - yup_audio_basics
           - yup_audio_devices

diff --git a/docs/_static/images/yup_3d_components.png b/docs/_static/images/yup_3d_components.png
diff --git a/docs/_static/images/yup_component_effects.jpg b/docs/_static/images/yup_component_effects.jpg
diff --git a/docs/_static/images/yup_prism_synth.jpg b/docs/_static/images/yup_prism_synth.jpg
diff --git a/docs/_static/images/yup_widgets.png b/docs/_static/images/yup_widgets.png
diff --git a/docs/core/system-and-app.md b/docs/core/system-and-app.md
@@ -26,6 +26,10 @@ String yup     = SystemStats::getYUPVersion();
 String path    = SystemStats::getEnvironmentVariable ("PATH", {});
 ```
 
+`isOperatingSystem64Bit()` reports the bitness of the OS, not of the build, so a
+32-bit binary on a 64-bit OS returns true. On WebAssembly it is a best-effort guess
+about the host.
+
 `getUniqueDeviceID()` returns a stable per-device identifier, and the
 language/region getters (`getUserLanguage`, `getUserRegion`, `getDisplayLanguage`)
 support localization.

diff --git a/docs/dsp/filters.md b/docs/dsp/filters.md
@@ -147,6 +147,30 @@ svf.processMultipleOutputs (in, lp, hp, bp, bs, n); // any output buffer may be
 lowpass). Coefficients are `k = 1/Q`, `g = tan(ω/2)`, normalized as
 `g / (1 + g·(k + g))`.
 
+### VAStateVariableFilter
+
+`VAStateVariableFilter` is a topology preserving transform SVF after Zavalishin.
+Where `StateVariableFilter` offers four outputs and clamps Q, this one produces
+eight outputs from one pass, takes a resonance in `0..1` (`Q = 1 / (2 (1 - r))`)
+or a raw Q, and adds a band shelf whose gain is set in dB.
+
+```cpp
+VAStateVariableFilter<float> svf;
+svf.setParameters (yup::FilterMode::bandpassCpg, 1200.f, 4.f, 0.f, 48000.0);
+svf.setResonance (0.8f);                    // or setQ()
+svf.setCutoffPitch (60.f);                  // MIDI note, 440 Hz at 69
+
+float y = svf.processSample (x);            // output selected by the mode
+auto outs = svf.processAllOutputs (x);      // .lowpass .highpass .bandpass .unityGainBandpass
+                                            // .bandShelf .notch .allpass .peak
+```
+
+Supported modes: `lowpass`, `highpass`, `bandpassCsg` (peak gain `Q`),
+`bandpassCpg` (unity peak gain), `bandstop`, `allpass` and `peak` (the band shelf,
+`input + K · 2 R · BP` with `K = 10^(dB / 20) - 1`). The lowpass-minus-highpass
+output of the original is available as `Outputs::peak` only. `getComplexResponse`
+is analytic through the bilinear substitution, so it matches the processed signal.
+
 ### ButterworthFilter
 
 `ButterworthFilter` is a mathematically correct Butterworth design (analog