host_quirks.hpp

Go to the documentation of this file.

#pragma once

 
#include <pulp/format/host_type.hpp>
#include <pulp/format/host_version.hpp>
 
#include <optional>
#include <string_view>
#include <vector>
 
namespace pulp::format {

enum class QuirkStatus : unsigned char {
    Validated,   
    Speculative, 
    LessonOnly,  
};

struct HostQuirks {
    // ── Cheap defenses (always-on by default; rows 23–28 of the
    //    DAW-quirks catalog cross-format defaults) ──
    bool synthesize_bypass_parameter = true;
    bool clamp_latency_to_nonneg = true;
    bool silence_unsupported_bus_arrangements = true;
 
    // ── Host-gated cheap-ish (default off, single host) ──
 
    // Cubase 10
    bool cubase10_async_view_resize_queue = false;     
    bool cubase10_param_gesture_ordering = false;      
    bool cubase10_fractional_scale_correction = false; 
 
    // Cubase 9
    bool cubase9_state_blob_size_validation = false;   
 
    // Ableton Live
    bool live_vst3_canresize_ignore = false;           
    bool live_vst3_windows_dpi_defer = false;          
    bool double_string_buffer_for_live_10_1_13 = false;
 
    // Bitwig
    bool bitwig_vst3_linux_repaint_after_resize = false; 
    bool bitwig_vst3_setbusarrangements_while_active = false; 
 
    // Ardour family (Ardour + Harrison Mixbus 32C)
    bool skip_bus_arrangement_call = false;
 
    // Wavelab
    bool wavelab_vst3_defer_activation = false;        
    bool wavelab_state_blob_fallback = false;          
    bool tolerate_state_read_nontrue_status = false;
 
    // FL Studio
    bool fl_studio_setactive_process_mutex = false;    
    bool fl_studio_state_reader_skip = false;          
 
    // Reaper (rows 15 + R1–R7)
    bool reaper_vst3_gesture_ordering = false;         
    bool reaper_process_while_bypassed = false;        
    bool reaper_keyboard_passthrough = false;          
    bool reaper_permissive_bus_arrangements = false;   
    bool reaper_anticipative_fx_buffer_variability = false; 
    bool reaper_midsession_setstate = false;           
    bool reaper_keyboard_only_space = false;
 
    // Pro Tools (AAX, opt-in)
    bool pro_tools_aax_sidechain_negotiation = false;  
    bool pro_tools_aax_latency_callback_push = false;  
    bool pro_tools_aax_mono_second_bus = false;        
    bool aax_vendor_version_unknown = false;
 
    // Logic Pro AU
    int logic_au_channel_probe_cap = 64;               
    bool logic_au_tail_time_conversion = false;        
    bool logic_au_v2_container_resize = false;
    // NOTE (no runtime flag — handled in the AU v3 adapter, recorded here so the
    // DAW-quirks ledger captures it): Logic Pro AU v3 editor SIZING has two
    // confirmed behaviors a fixed-design GPU editor must accommodate:
    //   1. Logic locks the editor window to its selected view-config aspect
    //      (it offers only oversized ~4:3 configs), so a wide fixed design
    //      letterboxes. Fix: do NOT implement supportedViewConfigurations: /
    //      selectViewConfiguration: → Logic free-resizes to the design aspect.
    //   2. Logic (out-of-process) does NOT deliver the editor view's restored
    //      window size on first open, so a GPU surface created at the design
    //      size clips its first paint. Fix: defer GPU-host creation until the
    //      view reports a real settled size.
    // Both live in core/format/src/{au_adapter,au_view_controller_mac}.mm and
    // .agents/skills/auv3/SKILL.md. Verified live in Logic 2026-05-29.
 
    // AU v3 cross-host
    bool au_v3_bypass_dual_tracking = false;           
    bool au_v3_host_id_from_wrapper = false;           

    bool reaper_auv3_in_process_preferred_size_sync = false;

    bool studio_one_restart_component_ui_thread = false;

    bool digital_performer_param_list_reload = false;

    bool cubase13_midi_cc_param_id_stable = false;
};

struct HostQuirksMeta {
    QuirkStatus synthesize_bypass_parameter = QuirkStatus::Validated;
    QuirkStatus clamp_latency_to_nonneg = QuirkStatus::Validated;
    QuirkStatus silence_unsupported_bus_arrangements = QuirkStatus::Validated;
 
    QuirkStatus cubase10_async_view_resize_queue = QuirkStatus::Speculative;
    QuirkStatus cubase10_param_gesture_ordering = QuirkStatus::Speculative;
    QuirkStatus cubase10_fractional_scale_correction = QuirkStatus::Speculative;
 
    QuirkStatus cubase9_state_blob_size_validation = QuirkStatus::Speculative;
 
    QuirkStatus live_vst3_canresize_ignore = QuirkStatus::Speculative;
    QuirkStatus live_vst3_windows_dpi_defer = QuirkStatus::Speculative;
    // Exact-version Live 10.1.13 getString buffer-doubling —
    // documented from release notes + reproducer notes, no in-tree
    // bench yet → LessonOnly.
    QuirkStatus double_string_buffer_for_live_10_1_13 = QuirkStatus::LessonOnly;
 
    // Bitwig + FL Studio + Logic + AU v3 cross-host all have per-host
    // headers under `host_quirks/<host>.hpp`, reproducer docs in the
    // catalog, and isolation tests.
    // Bench evidence under the real DAW is still pending → Speculative.
    QuirkStatus bitwig_vst3_linux_repaint_after_resize = QuirkStatus::Speculative;
    QuirkStatus bitwig_vst3_setbusarrangements_while_active = QuirkStatus::Speculative;
 
    // Ardour + Mixbus 32C setBusArrangements bypass — documented from
    // Ardour docs + reproducer notes, no in-tree bench yet → LessonOnly.
    QuirkStatus skip_bus_arrangement_call = QuirkStatus::LessonOnly;
 
    QuirkStatus wavelab_vst3_defer_activation = QuirkStatus::Speculative;
    QuirkStatus wavelab_state_blob_fallback = QuirkStatus::Speculative;
    // Documented from Steinberg spec + reproducer notes, no in-tree
    // bench yet → LessonOnly.
    QuirkStatus tolerate_state_read_nontrue_status = QuirkStatus::LessonOnly;
 
    QuirkStatus fl_studio_setactive_process_mutex = QuirkStatus::Speculative;
    QuirkStatus fl_studio_state_reader_skip = QuirkStatus::Speculative;
 
    // Reaper rows have a per-host header (`host_quirks/reaper.hpp`) +
    // per-symptom isolation tests pinning the dispatch. Rows backed by
    // checked-in REAPER 7.x DAW-bench evidence are Validated; the rest
    // stay Speculative.
    QuirkStatus reaper_vst3_gesture_ordering = QuirkStatus::Validated;
    QuirkStatus reaper_process_while_bypassed = QuirkStatus::Validated;
    QuirkStatus reaper_keyboard_passthrough = QuirkStatus::Speculative;
    QuirkStatus reaper_permissive_bus_arrangements = QuirkStatus::Validated;
    QuirkStatus reaper_anticipative_fx_buffer_variability = QuirkStatus::Speculative;
    QuirkStatus reaper_midsession_setstate = QuirkStatus::Speculative;
    // REAPER keyboard only-Space — documented across 5.x–7.x line, no
    // in-tree bench yet → LessonOnly.
    QuirkStatus reaper_keyboard_only_space = QuirkStatus::LessonOnly;
 
    // Pro Tools AAX rows have a per-host header
    // (`host_quirks/pro_tools.hpp`) + per-symptom isolation tests.
    // AAX adapter use is gated on the developer-supplied Avid
    // SDK (`PULP_AAX_SDK`); the quirk dispatch itself is unconditional
    // so filter behavior matches across builds. In-DAW bench evidence
    // requires the SDK → Speculative until those rows ship.
    QuirkStatus pro_tools_aax_sidechain_negotiation = QuirkStatus::Speculative;
    QuirkStatus pro_tools_aax_latency_callback_push = QuirkStatus::Speculative;
    QuirkStatus pro_tools_aax_mono_second_bus = QuirkStatus::Speculative;
    // Pro Tools AAX vendor-version unreliability — documented via Avid
    // AAX docs, no bench → LessonOnly.
    QuirkStatus aax_vendor_version_unknown = QuirkStatus::LessonOnly;
 
    QuirkStatus logic_au_channel_probe_cap = QuirkStatus::Speculative;
    QuirkStatus logic_au_tail_time_conversion = QuirkStatus::Speculative;
    QuirkStatus logic_au_v2_container_resize = QuirkStatus::Validated;
 
    QuirkStatus au_v3_bypass_dual_tracking = QuirkStatus::Speculative;
    QuirkStatus au_v3_host_id_from_wrapper = QuirkStatus::Speculative;
 
    // Documented from each host's vendor docs + reproducer issue (Pulp
    // #3044 / #3045 / #3046 / #3047), no in-tree bench yet →
    // LessonOnly. Cubase 13+ MIDI CC ID stability lands as Speculative
    // because it has a per-host header + per-symptom isolation test,
    // mirroring the rest of the Cubase rows.
    QuirkStatus reaper_auv3_in_process_preferred_size_sync = QuirkStatus::LessonOnly;
    QuirkStatus studio_one_restart_component_ui_thread = QuirkStatus::LessonOnly;
    QuirkStatus digital_performer_param_list_reload = QuirkStatus::LessonOnly;
    QuirkStatus cubase13_midi_cc_param_id_stable = QuirkStatus::Speculative;
};

inline constexpr HostQuirksMeta kHostQuirksMeta{};

struct QuirkFilter {
    bool allow_validated = true;
    bool allow_speculative = true;
    bool allow_lesson_only = true;
};

inline constexpr QuirkFilter kQuirkFilterValidatedOnly{
    .allow_validated = true,
    .allow_speculative = false,
    .allow_lesson_only = false,
};

inline constexpr QuirkFilter kQuirkFilterOff{
    .allow_validated = false,
    .allow_speculative = false,
    .allow_lesson_only = false,
};

void apply_filter(HostQuirks& q, QuirkFilter filter);

HostQuirks make_quirks_for(HostType type, HostVersion version);

HostQuirks make_quirks_for_validated_only(HostType type, HostVersion version);

HostQuirks detect_quirks();
 
// ── Runtime policy ────────────────────────────────────────────────────
//
// The compile-time `PULP_HOST_QUIRKS_DEFAULT_POLICY` option sets the
// baseline tier filter. A runtime override layers on top so a user
// who doesn't trust a quirk can dial it back without recompiling, while
// the default stays ON (validated quirks enforced). Precedence, highest
// first:
//
//   per-quirk override  >  set_host_quirk_policy() (API)
//                       >  PULP_HOST_QUIRKS env  >  compile-time default
//
// All of this is init-time configuration — resolve once when the adapter
// is constructed. None of it is real-time safe; never call the setters
// from the audio thread.

enum class QuirkPolicySource : unsigned char {
    CompileDefault,  
    Environment,     
    Api,             
};

struct ResolvedQuirkPolicy {
    QuirkFilter filter;
    QuirkPolicySource source = QuirkPolicySource::CompileDefault;
};

ResolvedQuirkPolicy resolve_quirk_policy();

void set_host_quirk_policy(std::optional<QuirkFilter> filter);

void set_quirk_override(std::string_view flag, bool enabled);

void clear_quirk_overrides();

struct QuirkFieldStatus {
    std::string_view name;  
    QuirkStatus tier;       
    bool enforced;          
};

std::vector<QuirkFieldStatus> enumerate_quirk_fields(const HostQuirks& q);

HostQuirks resolved_quirks(HostType type, HostVersion version);
 
// ── Accommodation application helpers ─────────────────────────────────
//
// Small pure helpers that apply a single quirk to a value, so format
// adapters share one tested implementation instead of open-coding the
// accommodation at each call site. Each takes the resolved `HostQuirks`
// the adapter cached at init.

constexpr int reported_latency_samples(int raw, const HostQuirks& q) noexcept {
    return (q.clamp_latency_to_nonneg && raw < 0) ? 0 : raw;
}
 
}  // namespace pulp::format