pulp::format::detail Namespace Reference

The plugin processor interface. More...

Classes
struct	EditorResizeHandlerEntry
struct	ParamEventsOptOutSlot
	The parameter-event queues adapters hand to opted-out processors, keyed by address, with a flag param_events() sets when one of them is read. More...
struct	StandaloneTestMidiNote
struct	StandaloneTestTransportUpdate
struct	StandaloneTestTransportState
class	StandaloneTestInputHost
	Bounded control-thread to audio-thread bridge for standalone inspector test input. More...

Typedefs
using	EditorResizeHandler
using	EditorResizeHandlerSet
using	StandaloneMidiInputQueue

Enumerations
enum class	StandaloneTestMidiKind : std::uint8_t { NoteOn , NoteOff }
enum class	StandaloneTestInputResult : std::uint8_t { Applied , InvalidArgument , QueueFull }

Functions
void	reset_editor_prewarm_requests_for_tests ()
	Forget which bundles were requested (tests only).
std::mutex &	editor_resize_mutex ()
	Backing store for the editor→host resize handler (see Processor::request_editor_resize).
std::unordered_map< const void *, EditorResizeHandlerSet > &	editor_resize_handlers ()
std::unordered_map< const void *, bool > &	standalone_processors ()
	Processors a Pulp standalone app owns, keyed by this so Processor's layout is unchanged.
std::unordered_map< const void *, std::shared_ptr< PanicState > > &	panic_states ()
	Panic request/state per processor, in a side table for the same layout reason as the handlers above.
std::size_t	param_events_opt_out_home (const void *queue) noexcept
ParamEventsOptOutSlot *	param_events_opt_out_find (const void *queue) noexcept
	The slot registered for queue, or null.
std::size_t	drain_standalone_midi_input (StandaloneMidiInputQueue &queue, midi::MidiBuffer &out)
bool	install_standalone_control_host_factory (StandaloneControlHostFactory factory) noexcept
	Installs the single generated factory for this executable.
StandaloneControlHostCreation	create_standalone_control_host ()
	Creates the explicitly installed host.
template<typename HostRequest>
bool	negotiate_preferred_size (ViewBridge &bridge, uint32_t width, uint32_t height, HostRequest &&request)
	Internal transaction shared by the CLAP and VST3 adapters.
void	view_editor_prewarm_scheduler (const Processor::EditorPrewarm &request)
	The scheduler pulp-format-view installs for request_editor_prewarm() (see editor_prewarm.hpp): copies the processor's EditorPrewarm and queues it on view::prewarm_scripted_ui()'s background worker.

Variables
constexpr DeviceQuotas	kQuotaTable [platform::kDeviceCapabilityTierCount][platform::kThermalStateCount]
	The quota table, indexed [tier][thermal state].
constexpr GenerationRoute	kProposalRouteTable [platform::kDeviceCapabilityTierCount][platform::kThermalStateCount]
	Baseline route for ProposalGeneration, indexed [tier][thermal state].
constexpr std::size_t	kParamEventsOptOutSlots = 256
constexpr std::size_t	kParamEventsOptOutProbe = 8
ParamEventsOptOutSlot	param_events_opt_out_slots [kParamEventsOptOutSlots]
std::atomic< std::size_t >	param_events_opt_out_count {0}
constexpr std::size_t	kStandaloneMidiInputQueueCapacity = 2048
constexpr std::size_t	kStandaloneTestMidiQueueCapacity = 256
constexpr std::size_t	kStandaloneTestMidiNoteCount = 16 * 128
constexpr std::size_t	kStandaloneMidiBufferEventCapacity

Detailed Description

The plugin processor interface.

This is the central abstraction in Pulp. Plugin developers subclass Processor and implement four methods:

• descriptor() — returns plugin metadata
• define_parameters() — registers parameters with the state store
• prepare() — allocates resources at the given sample rate
• process() — real-time audio callback

Format adapters (VST3, AU, CLAP) wrap a Processor instance and translate between the host API and Pulp's interface. The developer writes one processor; the build system creates multiple format targets.

class MyGain : public pulp::format::Processor {
    PluginDescriptor descriptor() const override { ... }
    void define_parameters(state::StateStore& store) override { ... }
    void prepare(const PrepareContext& ctx) override { ... }
    void process(BufferView<float>& out, const BufferView<const float>& in,
                 MidiBuffer& midi_in, MidiBuffer& midi_out,
                 const ProcessContext& ctx) override { ... }
};

Thread Safety

• process() is called on the audio thread. No allocation, no locks, no exceptions, no I/O.
• prepare() and release() are called on the host thread with the audio thread stopped.
• define_parameters() is called once during construction on the host thread.

Typedef Documentation

EditorResizeHandler

using pulp::format::detail::EditorResizeHandler

Initial value:

 
    std::function<bool(uint32_t, uint32_t)>

EditorResizeHandlerSet

using pulp::format::detail::EditorResizeHandlerSet

Initial value:

 
    std::unordered_map<const void*, EditorResizeHandlerEntry>

StandaloneMidiInputQueue

using pulp::format::detail::StandaloneMidiInputQueue

Initial value:

 
    runtime::SpscQueue<midi::MidiEvent, kStandaloneMidiInputQueueCapacity>

Enumeration Type Documentation

StandaloneTestInputResult

enum class pulp::format::detail::StandaloneTestInputResult : std::uint8_t

strong

Enumerator
Applied
InvalidArgument
QueueFull

StandaloneTestMidiKind

enum class pulp::format::detail::StandaloneTestMidiKind : std::uint8_t

strong

Enumerator
NoteOn
NoteOff

Function Documentation

create_standalone_control_host()

StandaloneControlHostCreation pulp::format::detail::create_standalone_control_host

(

)

Creates the explicitly installed host.

The separate installation bit lets callers distinguish a production-stripped executable from a control-enabled executable whose factory failed, which must fail closed.

drain_standalone_midi_input()

std::size_t pulp::format::detail::drain_standalone_midi_input ( StandaloneMidiInputQueue & queue, midi::MidiBuffer & out )

inline

editor_resize_handlers()

std::unordered_map< const void *, EditorResizeHandlerSet > & pulp::format::detail::editor_resize_handlers ( )

inline

editor_resize_mutex()

std::mutex & pulp::format::detail::editor_resize_mutex ( )

inline

Backing store for the editor→host resize handler (see Processor::request_editor_resize).

Kept in a side table keyed first by the processor and then by each editor's opaque owner pointer rather than as a Processor DATA MEMBER on purpose: Processor is a widely-inherited public base, and growing sizeof(Processor) breaks every prebuilt library that already constructs a subclass (it crashed ~Processor() on a mixed old-lib/new-header SDK). A side table keeps the class layout — and therefore the ABI — frozen while still adding the capability. The key is const void* (not const Processor*) so this block needs no forward declaration of Processor, which would otherwise confuse the node-ABI gate's class parser. Access is main-thread in practice; the mutex only guards a stray off-thread teardown. One instance across TUs (inline-function local statics are merged).

install_standalone_control_host_factory()

bool pulp::format::detail::install_standalone_control_host_factory ( StandaloneControlHostFactory factory )

noexcept

Installs the single generated factory for this executable.

Repeated or empty installation fails closed.

negotiate_preferred_size()

template<typename HostRequest>

bool pulp::format::detail::negotiate_preferred_size	(	ViewBridge &	bridge,
		uint32_t	width,
		uint32_t	height,
		HostRequest &&	request )

Internal transaction shared by the CLAP and VST3 adapters.

The bridge is updated before request because hosts may synchronously query the plugin's new size constraints while handling the request. Refusal restores the prior preferred size and aspect. Live viewport mutation belongs after this function returns true.

panic_states()

std::unordered_map< const void *, std::shared_ptr< PanicState > > & pulp::format::detail::panic_states ( )

inline

Panic request/state per processor, in a side table for the same layout reason as the handlers above.

The shared_ptr is handed to the adapter once, off the audio thread; the audio thread never touches this table or its mutex. Guarded by editor_resize_mutex().

param_events_opt_out_find()

ParamEventsOptOutSlot * pulp::format::detail::param_events_opt_out_find ( const void * queue )

inlinenoexcept

The slot registered for queue, or null.

param_events_opt_out_home()

std::size_t pulp::format::detail::param_events_opt_out_home ( const void * queue )

inlinenoexcept

reset_editor_prewarm_requests_for_tests()

void pulp::format::detail::reset_editor_prewarm_requests_for_tests

(

)

Forget which bundles were requested (tests only).

standalone_processors()

std::unordered_map< const void *, bool > & pulp::format::detail::standalone_processors ( )

inline

Processors a Pulp standalone app owns, keyed by this so Processor's layout is unchanged.

Absent means the processor is hosted as a plug-in. Guarded by editor_resize_mutex().

view_editor_prewarm_scheduler()

void pulp::format::detail::view_editor_prewarm_scheduler

(

const Processor::EditorPrewarm &

request

)

The scheduler pulp-format-view installs for request_editor_prewarm() (see editor_prewarm.hpp): copies the processor's EditorPrewarm and queues it on view::prewarm_scripted_ui()'s background worker.

Variable Documentation

kParamEventsOptOutProbe

std::size_t pulp::format::detail::kParamEventsOptOutProbe = 8

inlineconstexpr

kParamEventsOptOutSlots

std::size_t pulp::format::detail::kParamEventsOptOutSlots = 256

inlineconstexpr

kProposalRouteTable

GenerationRoute pulp::format::detail::kProposalRouteTable[platform::kDeviceCapabilityTierCount][platform::kThermalStateCount]

inlineconstexpr

Initial value:

= {
        
        
        {GenerationRoute::Server, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
        
        
        {GenerationRoute::Server, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
        
        
        {GenerationRoute::OnDevice, GenerationRoute::Server, GenerationRoute::Server,
         GenerationRoute::QueueForLater},
}

Baseline route for ProposalGeneration, indexed [tier][thermal state].

Only proposal generation needs a table: the other two classes have a single answer each and stating them as tables would imply a variation that does not exist. Playback and receipts are always local — they are what the product falls back to, so routing them anywhere else would make degradation depend on the very connectivity that degraded.

Two orderings hold across this table and are asserted in test: along a row, the route never moves back toward the device as the machine gets hotter; down a column, it never moves further from the device as the tier rises. Together they say heat only ever pushes work away and capability only ever pulls it closer, which is the whole intent of the policy in two sentences.

kQuotaTable

DeviceQuotas pulp::format::detail::kQuotaTable[platform::kDeviceCapabilityTierCount][platform::kThermalStateCount]

inlineconstexpr

Initial value:

= {
        
        {
            {16, 48, 1, PreviewQuality::Reduced},
            {12, 40, 1, PreviewQuality::Reduced},
            {8, 32, 1, PreviewQuality::Reduced},
            {4, 16, 1, PreviewQuality::Disabled},
        },
        
        {
            {64, 192, 2, PreviewQuality::Full},
            {48, 160, 2, PreviewQuality::Full},
            {32, 112, 1, PreviewQuality::Reduced},
            {16, 64, 1, PreviewQuality::Disabled},
        },
        
        {
            {256, 768, 4, PreviewQuality::Full},
            {192, 640, 3, PreviewQuality::Full},
            {128, 448, 2, PreviewQuality::Reduced},
            {64, 256, 1, PreviewQuality::Disabled},
        },
}

The quota table, indexed [tier][thermal state].

Written out cell by cell rather than derived from a scaling formula so the table is reviewable as data and so the monotonicity property is a real assertion about these numbers rather than a restatement of a formula.

Two orderings hold across the table and are asserted in test: along a row, no field ever rises as the device gets hotter; down a column, no field ever falls as the tier rises.

kStandaloneMidiBufferEventCapacity

std::size_t pulp::format::detail::kStandaloneMidiBufferEventCapacity

inlineconstexpr

Initial value:

=
    kStandaloneMidiInputQueueCapacity +
    kStandaloneTestMidiQueueCapacity +
    kStandaloneTestMidiNoteCount +
    midi::MidiMessageCollector<>::capacity() +
    midi::MidiMessageCollector<>::pending_capacity()

kStandaloneMidiInputQueueCapacity

std::size_t pulp::format::detail::kStandaloneMidiInputQueueCapacity = 2048

inlineconstexpr

kStandaloneTestMidiNoteCount

std::size_t pulp::format::detail::kStandaloneTestMidiNoteCount = 16 * 128

inlineconstexpr

kStandaloneTestMidiQueueCapacity

std::size_t pulp::format::detail::kStandaloneTestMidiQueueCapacity = 256

inlineconstexpr

param_events_opt_out_count

std::atomic<std::size_t> pulp::format::detail::param_events_opt_out_count {0}

inline

param_events_opt_out_slots

ParamEventsOptOutSlot pulp::format::detail::param_events_opt_out_slots[kParamEventsOptOutSlots]

inline