Klang C++ 0.7.15
Language Reference (draft)
Loading...
Searching...
No Matches
klang::Controls

Language Guide / Controls and Parameters

Controls

klang::Controls

Collection of a model’s controls.

Declare the collection when constructing the model. A control supplies its label, range and initial value to Studio. Read the current value by index in declaration order, or borrow a named Control member when several parts of the model need to refer to it.

Example · Expose a level dial

Dial("Level") uses the default range of 0 to 1 and starts at 0. Turn it up to hear the input.

struct Level : Effect {
    Level() {
        controls = {
            Dial("Level")
        };
    }

    void process() {
        in * controls[0] >> out;
    }
};

Choose control types

Use a Dial or Slider for continuous values, Toggle for an on/off state, Button for a momentary action, and Menu for a choice. A Meter displays a value supplied by the model.

controls = {
    Slider("Mix"),
    Toggle("Enabled"),
    Button("Reset"),
    Menu("Shape", "Sine", "Saw"),
    Meter("Output")
};

Size and group controls

The optional size supplies x, y, width, and height for placement in Studio. Omit it to use automatic layout. Put related controls in a Group to give them a shared label.

controls = {
    { "Tone",
        Dial("Cutoff", 20, 12000, 1000, { 0, 0, 45, 45 }),
        Dial("Resonance", 0.1, 4, 0.7)
    }
};

Reference existing controls

A plugin can expose controls from another plugin instance it can access. Here the first control on source is its level. Pass it by reference to share that value. The two interfaces then address the same control.

struct LevelPanel : Sound {
    LevelPanel(Sound& source) {
        controls = { source.controls[0] };
    }
};

Pass the whole collection to expose all of the source plugin’s controls. Keep the source plugin alive for as long as the borrowing plugin uses them.

struct FullPanel : Sound {
    FullPanel(Sound& source) {
        controls = { source.controls };
    }
};

#include <klang.h>

+ Inheritance diagram for klang::Controls:

Public Member Functions

 Controls ()
 
 Controls (const Controls &other)
 
 Controls (Controls &&other)
 
 ~Controls ()
 
Control & operator[] (int index)
 Resolve one actual control; ordinary owned collections take the direct path.
 
const Control & operator[] (int index) const
 
void clear ()
 
Controls & operator= (const Controls &) &&=delete
 
template<class Source , std::enable_if_t< std::is_same_v< std::decay_t< Source >, Controls >, int > = 0>
Controls & operator= (Source &&source) &
 
Controls & operator= (std::initializer_list< klang::Group > declaration)
 
void operator+= (Control &control)
 
void operator+= (const Control &control)
 
void operator+= (Control &&control)
 
void operator+= (Controls &controls)
 
void add (const Control &control)
 
Control * add ()
 
void add (const char *name, Control::Type type=Control::ROTARY, float min=0.f, float max=1.f, float initial=0.f, Control::Size size=Automatic)
 
void add (const char *name, Control::Type type, std::initializer_list< const char * > options, Control::Size size=Automatic)
 
bool inGroup (int index) const
 
const Control::Group * getGroup (int index) const
 
bool changed ()
 
float max () const
 
float mean () const
 
float rms () const
 
void normalise (float target=1, int mode=Peak)
 
void group (const char *name, unsigned int start, unsigned int length, Control::Size size=Automatic)
 
template<class... Args>
void set (Args... args)
 
void set (const Preset &preset)
 
Controls & operator= (const Preset &preset)
 
const char * key (int index) const
 Stable declaration key for metadata/retention; never a pointer or a default value.
 
const char * scope (int index) const
 
int scopeStart (int index) const
 
int scopeSize (int index) const
 
bool isInput (int index) const
 
void markInput (int index, bool state=true)
 
bool hasReferences () const
 
void setMetadata (int index, const char *identity, const char *block, int start, int length, bool gameInput)
 Preserve original identities when a proxy reconstructs a flat schema.
 
void bindAlias (int index, int canonicalIndex)
 Reconstruct an earlier canonical slot when a proxy flattens aliases.
 
const Control * snapshot ()
 Refresh only the legacy contiguous metadata/value snapshot before raw ABI export.
 
const Control * snapshot () const
 
unsigned int size () const
 The current number of items in the array.
 

Static Public Member Functions

static int capacity ()
 The maximum capacity of the array.
 

Public Attributes

float value [128] = { 0 }
 
Array< Control::Group, 10 > groups
 
unsigned int count
 
Control items [CAPACITY]
 

Detailed Description

An owned control collection with optional borrowed value entries. Mutable Control and Controls lvalues in a declaration borrow their values; temporary factory results are owned. Referenced schemas are fixed while borrowed. An individual borrowed Control must outlive this collection. DSP code normally continues reading the child's original Controls object. The legacy count/items/value/groups prefix and Control layout are retained; the binding sidecar is internal, never the MiniPlugin host ABI record.

Definition at line 2079 of file klang.h.

Constructor & Destructor Documentation

◆ Controls() [1/3]

klang::Controls::Controls ( )
inline

Definition at line 2311 of file klang.h.

2311 {
2312 lifetime = std::make_shared<Lifetime>(construction());
2313 scopes[0].name = "root";
2314 auto& owners = registry();
2315 const std::lock_guard<std::mutex> lock(owners.mutex);
2316 owners.collections.push_back({ this, items, lifetime->creator.get() });
2317 }
Control items[CAPACITY]
Definition klang.h:309

References klang::Array< Control, 128 >::items.

◆ Controls() [2/3]

klang::Controls::Controls ( const Controls & other)
inline

Definition at line 2318 of file klang.h.

2318: Controls() { *this = other; }

◆ Controls() [3/3]

klang::Controls::Controls ( Controls && other)
inline

Definition at line 2319 of file klang.h.

2319: Controls(static_cast<const Controls&>(other)) {}

◆ ~Controls()

klang::Controls::~Controls ( )
inline

Definition at line 2320 of file klang.h.

2320 {
2321 if (lifetime) lifetime->alive = false;
2322 auto& owners = registry();
2323 const std::lock_guard<std::mutex> lock(owners.mutex);
2324 owners.collections.erase(std::remove_if(owners.collections.begin(), owners.collections.end(),
2325 [this](const Registry::Entry& entry) { return entry.owner == this; }), owners.collections.end());
2326 }

Member Function Documentation

◆ add() [1/4]

Control * klang::Controls::add ( )
inline

Definition at line 2402 of file klang.h.

2402 {
2403 mutableSchema();
2404 if (count == 128) return nullptr;
2405 appendOwned(Control{});
2406 return &items[count - 1];
2407 }

References klang::Array< Control, 128 >::count, and klang::Array< Control, 128 >::items.

◆ add() [2/4]

void klang::Controls::add ( const char * name,
Control::Type type,
std::initializer_list< const char * > options,
Control::Size size = Automatic )
inline

Definition at line 2417 of file klang.h.

2418 {
2419 mutableSchema();
2420 room(1);
2421 if (options.size() > 128) invalid("Control options capacity exceeded");
2422 Control control {};
2423 control.name = name; control.type = type;
2424 control.min = 0; control.max = static_cast<float>(options.size()) - 1;
2425 control.initial = 0; control.value = 0; control.size = size;
2426 for (const char* option : options) control.options.add(Caption::from(option));
2427 appendOwned(control);
2428 }
unsigned int size() const
Definition klang.h:315
static Text from(const char *in)
Definition klang.h:1092

References klang::Text< 32 >::from(), klang::Control::name, and klang::Array< Control, 128 >::size().

◆ add() [3/4]

void klang::Controls::add ( const char * name,
Control::Type type = Control::ROTARY,
float min = 0.f,
float max = 1.f,
float initial = 0.f,
Control::Size size = Automatic )
inline

Definition at line 2408 of file klang.h.

2409 {
2410 mutableSchema();
2411 Control control {};
2412 control.name = name; control.type = type;
2413 control.min = min; control.max = max; control.initial = initial;
2414 control.size = size; control.value = initial;
2415 appendOwned(control);
2416 }
float max() const
Definition klang.h:2447

References max(), klang::Control::name, klang::Array< Control, 128 >::size(), and klang::signal::value.

◆ add() [4/4]

void klang::Controls::add ( const Control & control)
inline

Definition at line 2401 of file klang.h.

2401{ mutableSchema(); appendOwned(control); }

◆ bindAlias()

void klang::Controls::bindAlias ( int index,
int canonicalIndex )
inline

Definition at line 2529 of file klang.h.

2529 {
2530 mutableSchema();
2531 if (index <= 0 || index >= static_cast<int>(count) || canonicalIndex < 0 || canonicalIndex >= index)
2532 invalid("Invalid proxy control alias");
2533 Control* target = &(*this)[canonicalIndex];
2534 const auto state = aliases[canonicalIndex].lifetime;
2535 items[index] = *target;
2536 aliases[index] = { target, state };
2537 pin(state); // Null for this collection's own canonical storage.
2538 borrowed = true;
2539 markInput(canonicalIndex, input[canonicalIndex]);
2540 metadataDirty = true;
2541 }
void markInput(int index, bool state=true)
Definition klang.h:2495

References klang::Array< Control, 128 >::count, klang::Array< Control, 128 >::items, and markInput().

◆ capacity()

static int klang::Array< Control, CAPACITY >::capacity ( )
inlinestaticinherited

Definition at line 312 of file klang.h.

312{ return CAPACITY; }

◆ changed()

bool klang::Controls::changed ( )
inline

Definition at line 2439 of file klang.h.

2439 {
2440 bool result = false;
2441 for (unsigned int i = 0; i < count; ++i) {
2442 const float current = (*this)[i];
2443 if (current != value[i]) { value[i] = current; result = true; }
2444 }
2445 return result;
2446 }
float value[128]
Definition klang.h:2080

References klang::Array< Control, 128 >::count, and value.

◆ clear()

void klang::Controls::clear ( )
inline

Definition at line 2343 of file klang.h.

2343 {
2344 mutableSchema();
2345 count = 0;
2346 groups.clear();
2347 for (auto& alias : aliases) alias = {};
2348 lifetime->dependencies.clear();
2349 for (auto& flag : input) flag = false;
2350 for (auto& index : scopeIndex) index = 0;
2351 borrowed = false;
2352 scopeCount = 1;
2353 metadataDirty = true;
2354 }
Array< Control::Group, 10 > groups
Definition klang.h:2081

References klang::Array< Control, 128 >::count, and groups.

Referenced by operator=(), and operator=().

◆ getGroup()

const Control::Group * klang::Controls::getGroup ( int index) const
inline

Definition at line 2434 of file klang.h.

2434 {
2435 for (unsigned int group = 0; group < groups.count; ++group)
2436 if (groups[group].contains(index)) return &groups[group];
2437 return nullptr;
2438 }
void group(const char *name, unsigned int start, unsigned int length, Control::Size size=Automatic)
Definition klang.h:2473

References group(), and groups.

◆ group()

void klang::Controls::group ( const char * name,
unsigned int start,
unsigned int length,
Control::Size size = Automatic )
inline

Definition at line 2473 of file klang.h.

2473 {
2474 mutableSchema();
2475 if (groups.count == 10 || start > count || length > count - start)
2476 invalid("Invalid Controls group");
2477 groups.add({ Caption::from(name), size, start, length });
2478 metadataDirty = true;
2479 }

References klang::Array< Control, 128 >::count, klang::Text< 32 >::from(), groups, and klang::Array< Control, 128 >::size().

Referenced by getGroup(), inGroup(), and operator=().

◆ hasReferences()

bool klang::Controls::hasReferences ( ) const
inline

Definition at line 2502 of file klang.h.

2502{ return borrowed; }

◆ inGroup()

bool klang::Controls::inGroup ( int index) const
inline

Definition at line 2429 of file klang.h.

2429 {
2430 for (unsigned int group = 0; group < groups.count; ++group)
2431 if (groups[group].contains(index)) return true;
2432 return false;
2433 }

References group(), and groups.

◆ isInput()

bool klang::Controls::isInput ( int index) const
inline

Definition at line 2494 of file klang.h.

2494{ return input[index]; }

Referenced by operator=(), and set().

◆ key()

const char * klang::Controls::key ( int index) const
inline

Definition at line 2490 of file klang.h.

2490{ refreshMetadata(); return keys[index].c_str(); }

◆ markInput()

void klang::Controls::markInput ( int index,
bool state = true )
inline

Definition at line 2495 of file klang.h.

2495 {
2496 if (index < 0 || index >= static_cast<int>(count)) return;
2497 mutableSchema();
2498 const Control* target = &(*this)[index];
2499 for (unsigned int i = 0; i < count; ++i)
2500 if (&(*this)[i] == target) input[i] = state;
2501 }

References klang::Array< Control, 128 >::count.

Referenced by bindAlias(), and setMetadata().

◆ max()

float klang::Controls::max ( ) const
inline

Definition at line 2447 of file klang.h.

2447 {
2448 float result = 0;
2449 for (unsigned int i = 0; i < count; ++i) result = std::max(result, std::abs(float((*this)[i])));
2450 return result;
2451 }

References klang::Array< Control, 128 >::count.

Referenced by add(), and normalise().

◆ mean()

float klang::Controls::mean ( ) const
inline

Definition at line 2452 of file klang.h.

2452 {
2453 float result = 0;
2454 for (unsigned int i = 0; i < count; ++i) result += std::abs(float((*this)[i]));
2455 return result / count;
2456 }

References klang::Array< Control, 128 >::count.

Referenced by normalise().

◆ normalise()

void klang::Controls::normalise ( float target = 1,
int mode = Peak )
inline

Definition at line 2462 of file klang.h.

2462 {
2463 if (!count) return;
2464 const float current = mode == Peak ? max() : mode == Mean ? mean() : rms();
2465 const float scale = current == 0 ? 0 : target / current;
2466 for (unsigned int i = 0; i < count; ++i) {
2467 bool duplicate = false;
2468 if (borrowed) for (unsigned int previous = 0; previous < i; ++previous)
2469 duplicate = duplicate || &(*this)[previous] == &(*this)[i];
2470 if (!duplicate) (*this)[i] *= scale;
2471 }
2472 }
@ Peak
Definition klang.h:149
@ Mean
Definition klang.h:149
float rms() const
Definition klang.h:2457
float mean() const
Definition klang.h:2452

References klang::Array< Control, 128 >::count, max(), klang::Mean, mean(), klang::Peak, and rms().

◆ operator+=() [1/4]

void klang::Controls::operator+= ( const Control & control)
inline

Definition at line 2398 of file klang.h.

2398{ mutableSchema(); appendOwned(control); }

◆ operator+=() [2/4]

void klang::Controls::operator+= ( Control && control)
inline

Definition at line 2399 of file klang.h.

2399{ mutableSchema(); appendOwned(control); }

◆ operator+=() [3/4]

void klang::Controls::operator+= ( Control & control)
inline

Definition at line 2397 of file klang.h.

2397{ mutableSchema(); appendReference(control); }

◆ operator+=() [4/4]

void klang::Controls::operator+= ( Controls & controls)
inline

Definition at line 2400 of file klang.h.

2400{ mutableSchema(); appendCollection(controls); }

◆ operator=() [1/4]

Controls & klang::Controls::operator= ( const Controls & ) &&
delete

◆ operator=() [2/4]

Controls & klang::Controls::operator= ( const Preset & preset)
inline

Definition at line 2566 of file klang.h.

2566 {
2567 set(preset);
2568 return *this;
2569 }
void set(Args... args)
Definition klang.h:2480

References set().

◆ operator=() [3/4]

template<class Source , std::enable_if_t< std::is_same_v< std::decay_t< Source >, Controls >, int > = 0>
Controls & klang::Controls::operator= ( Source && source) &
inline

Definition at line 2360 of file klang.h.

2360 {
2361 const Controls& other = source;
2362 if (this == &other) return *this;
2363 clear();
2364 for (unsigned int i = 0; i < other.count; ++i) appendOwned(other[i]);
2365 groups = other.groups;
2366 for (unsigned int i = 0; i < count; ++i) input[i] = other.isInput(i);
2367 return *this;
2368 }
void clear()
Definition klang.h:2343

References clear(), klang::Array< TYPE, CAPACITY >::count, klang::Array< Control, 128 >::count, groups, and isInput().

◆ operator=() [4/4]

Controls & klang::Controls::operator= ( std::initializer_list< klang::Group > declaration)
inline

Definition at line 2369 of file klang.h.

2369 {
2370 mutableSchema();
2371 unsigned int entries = 0, headings = 0;
2372 for (const auto& group : declaration) {
2373 for (const auto& entry : group.controls) {
2374 if (entry.kind == ControlEntry::Collection) {
2375 if (entry.collection == this) invalid("A Controls collection cannot reference itself");
2376 for (unsigned int i = 0; i < entry.collection->count; ++i)
2377 if (owns(&(*entry.collection)[i])) invalid("Cyclic Controls reference");
2378 entries += entry.collection->count;
2379 } else {
2380 if (entry.kind == ControlEntry::Reference && owns(entry.reference))
2381 invalid("A Controls collection cannot reference its own storage");
2382 ++entries;
2383 }
2384 }
2385 if (group.name && group.name[0]) ++headings;
2386 }
2387 if (entries > 128 || headings > 10) invalid("Controls declaration capacity exceeded");
2388 clear();
2389 for (const auto& group : declaration) {
2390 const auto start = count;
2391 for (const auto& entry : group.controls) append(entry);
2392 if (group.name && group.name[0]) groups.add({ Caption::from(group.name), group.size, start, count - start });
2393 }
2394 metadataDirty = true;
2395 return *this;
2396 }
@ Reference
Definition klang.h:2023
@ Collection
Definition klang.h:2023

References clear(), klang::ControlEntry::Collection, klang::Array< Control, 128 >::count, klang::Text< 32 >::from(), group(), groups, and klang::ControlEntry::Reference.

◆ operator[]() [1/2]

Control & klang::Controls::operator[] ( int index)
inline

Definition at line 2329 of file klang.h.

2329 {
2330 if (!borrowed || !aliases[index].target) return items[index];
2331 auto& alias = aliases[index];
2332 if (!live(alias.lifetime))
2333 invalid("Referenced Controls owner has been destroyed");
2334 return *alias.target;
2335 }

References klang::Array< Control, 128 >::items.

Referenced by set().

◆ operator[]() [2/2]

const Control & klang::Controls::operator[] ( int index) const
inline

Definition at line 2336 of file klang.h.

2336 {
2337 if (!borrowed || !aliases[index].target) return items[index];
2338 const auto& alias = aliases[index];
2339 if (!live(alias.lifetime))
2340 invalid("Referenced Controls owner has been destroyed");
2341 return *alias.target;
2342 }

References klang::Array< Control, 128 >::items.

◆ rms()

float klang::Controls::rms ( ) const
inline

Definition at line 2457 of file klang.h.

2457 {
2458 float result = 0;
2459 for (unsigned int i = 0; i < count; ++i) { const float sample = (*this)[i]; result += sample * sample; }
2460 return std::sqrt(result / count);
2461 }

References klang::Array< Control, 128 >::count.

Referenced by normalise().

◆ scope()

const char * klang::Controls::scope ( int index) const
inline

Definition at line 2491 of file klang.h.

2491{ return scopes[scopeIndex[index]].name.c_str(); }

Referenced by setMetadata().

◆ scopeSize()

int klang::Controls::scopeSize ( int index) const
inline

Definition at line 2493 of file klang.h.

2493{ return scopeIndex[index] ? static_cast<int>(scopes[scopeIndex[index]].length) : static_cast<int>(count); }

References klang::Array< Control, 128 >::count.

◆ scopeStart()

int klang::Controls::scopeStart ( int index) const
inline

Definition at line 2492 of file klang.h.

2492{ return scopeIndex[index] ? static_cast<int>(scopes[scopeIndex[index]].start) : 0; }

◆ set() [1/2]

template<class... Args>
void klang::Controls::set ( Args... args)
inline

Definition at line 2480 of file klang.h.

2480 {
2481 static_assert((std::is_arithmetic_v<Args> && ...), "Controls::set() accepts scalar arguments");
2482 const float values[] = { static_cast<float>(args)... };
2483 const unsigned int n = std::min(count, static_cast<unsigned int>(sizeof...(Args)));
2484 for (unsigned int i = 0; i < n; ++i) (*this)[i].set(values[i]);
2485 }

References klang::Array< Control, 128 >::count.

Referenced by operator=().

◆ set() [2/2]

void klang::Controls::set ( const Preset & preset)
inline

Definition at line 2561 of file klang.h.

2561 {
2562 for (unsigned int p = 0; p < preset.values.count && p < count; p++)
2563 if (!isInput(p)) operator[](p).set(preset.values[p]);
2564 }
Control & set(float x)
Definition klang.h:1875
bool isInput(int index) const
Definition klang.h:2494
Control & operator[](int index)
Resolve one actual control; ordinary owned collections take the direct path.
Definition klang.h:2329

References klang::Array< TYPE, CAPACITY >::count, klang::Array< Control, 128 >::count, isInput(), operator[](), klang::Control::set(), and klang::Preset::values.

◆ setMetadata()

void klang::Controls::setMetadata ( int index,
const char * identity,
const char * block,
int start,
int length,
bool gameInput )
inline

Definition at line 2505 of file klang.h.

2505 {
2506 mutableSchema();
2507 if (index < 0 || index >= static_cast<int>(count) || !identity ||
2508 !block || !block[0] || start < 0 || length <= 0 || start > index ||
2509 index >= start + length || start + length > static_cast<int>(count))
2510 invalid("Invalid Controls metadata");
2511 unsigned int scope = 0;
2512 std::string scopeName = !identity[0] && std::strcmp(block, "root") == 0
2513 ? "external:metadata" + std::to_string(index) : block;
2514 if (scopeName != "root") {
2515 for (scope = 1; scope < scopeCount && scopes[scope].name != scopeName; ++scope) {}
2516 if (scope == scopeCount) {
2517 if (scopeCount == 129) invalid("Controls scope capacity exceeded");
2518 ++scopeCount;
2519 }
2520 scopes[scope] = { scopeName, static_cast<unsigned int>(start), static_cast<unsigned int>(length) };
2521 }
2522 scopeIndex[index] = scope;
2523 sourceKeys[index] = identity;
2524 markInput(index, gameInput);
2525 metadataDirty = true;
2526 }
const char * scope(int index) const
Definition klang.h:2491

References klang::Array< Control, 128 >::count, markInput(), and scope().

◆ size()

unsigned int klang::Array< Control, CAPACITY >::size ( ) const
inlineinherited

Definition at line 315 of file klang.h.

315{ return count; }

Referenced by add(), add(), and group().

◆ snapshot() [1/2]

const Control * klang::Controls::snapshot ( )
inline

Definition at line 2544 of file klang.h.

2544 {
2545 for (unsigned int i = 0; i < count; ++i)
2546 if (aliases[i].target) items[i] = (*this)[i];
2547 return items;
2548 }

References klang::Array< Control, 128 >::count, and klang::Array< Control, 128 >::items.

◆ snapshot() [2/2]

const Control * klang::Controls::snapshot ( ) const
inline

Definition at line 2549 of file klang.h.

2549{ return const_cast<Controls*>(this)->snapshot(); }
const Control * snapshot()
Refresh only the legacy contiguous metadata/value snapshot before raw ABI export.
Definition klang.h:2544

References snapshot().

Referenced by snapshot().

Member Data Documentation

◆ count

unsigned int klang::Array< Control, CAPACITY >::count
inherited

◆ groups

Array<Control::Group, 10> klang::Controls::groups

Definition at line 2081 of file klang.h.

Referenced by clear(), getGroup(), group(), inGroup(), operator=(), and operator=().

◆ items

Control klang::Array< Control, CAPACITY >::items[CAPACITY]
inherited

Definition at line 309 of file klang.h.

Referenced by Controls(), add(), bindAlias(), operator[](), operator[](), and snapshot().

◆ value

float klang::Controls::value[128] = { 0 }

Definition at line 2080 of file klang.h.

2080{ 0 };

Referenced by changed().