Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/distrho/DistrhoDetails.hpp @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
1 /*
2 * DISTRHO Plugin Framework (DPF)
3 * Copyright (C) 2012-2023 Filipe Coelho <falktx@falktx.com>
4 *
5 * Permission to use, copy, modify, and/or distribute this software for any purpose with
6 * or without fee is hereby granted, provided that the above copyright notice and this
7 * permission notice appear in all copies.
8 *
9 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD
10 * TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN
11 * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
12 * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
13 * IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
14 * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 */
16
17 #ifndef DISTRHO_DETAILS_HPP_INCLUDED
18 #define DISTRHO_DETAILS_HPP_INCLUDED
19
20 #include "extra/String.hpp"
21
22 START_NAMESPACE_DISTRHO
23
24 /* --------------------------------------------------------------------------------------------------------------------
25 * Audio Port Hints */
26
27 /**
28 @defgroup AudioPortHints Audio Port Hints
29
30 Various audio port hints.
31 @see AudioPort::hints
32 @{
33 */
34
35 /**
36 Audio port can be used as control voltage (LV2 and JACK standalone only).
37 */
38 static constexpr const uint32_t kAudioPortIsCV = 0x1;
39
40 /**
41 Audio port should be used as sidechan (LV2 and VST3 only).
42 This hint should not be used with CV style ports.
43 @note non-sidechain audio ports must exist in the plugin if this flag is set.
44 */
45 static constexpr const uint32_t kAudioPortIsSidechain = 0x2;
46
47 /**
48 CV port has bipolar range (-1 to +1, or -5 to +5 if scaled).
49 This is merely a hint to tell the host what value range to expect.
50 */
51 static constexpr const uint32_t kCVPortHasBipolarRange = 0x10;
52
53 /**
54 CV port has negative unipolar range (-1 to 0, or -10 to 0 if scaled).
55 This is merely a hint to tell the host what value range to expect.
56 */
57 static constexpr const uint32_t kCVPortHasNegativeUnipolarRange = 0x20;
58
59 /**
60 CV port has positive unipolar range (0 to +1, or 0 to +10 if scaled).
61 This is merely a hint to tell the host what value range to expect.
62 */
63 static constexpr const uint32_t kCVPortHasPositiveUnipolarRange = 0x40;
64
65 /**
66 CV port has scaled range to match real values (-5 to +5v bipolar, +/-10 to 0v unipolar).
67 One other range flag is required if this flag is set.
68
69 When enabled, this makes the port a mod:CVPort, compatible with the MOD Devices platform.
70 */
71 static constexpr const uint32_t kCVPortHasScaledRange = 0x80;
72
73 /**
74 CV port is optional, allowing hosts that do no CV ports to load the plugin.
75 When loaded in hosts that don't support CV, the float* buffer for this port will be null.
76 */
77 static constexpr const uint32_t kCVPortIsOptional = 0x100;
78
79 /** @} */
80
81 /* --------------------------------------------------------------------------------------------------------------------
82 * Parameter Hints */
83
84 /**
85 @defgroup ParameterHints Parameter Hints
86
87 Various parameter hints.
88 @see Parameter::hints
89 @{
90 */
91
92 /**
93 Parameter is automatable (real-time safe).
94 @see Plugin::setParameterValue(uint32_t, float)
95 */
96 static constexpr const uint32_t kParameterIsAutomatable = 0x01;
97
98 /** It was a typo, sorry.. */
99 DISTRHO_DEPRECATED_BY("kParameterIsAutomatable")
100 static constexpr const uint32_t kParameterIsAutomable = kParameterIsAutomatable;
101
102 /**
103 Parameter value is boolean.@n
104 It's always at either minimum or maximum value.
105 */
106 static constexpr const uint32_t kParameterIsBoolean = 0x02;
107
108 /**
109 Parameter value is integer.
110 */
111 static constexpr const uint32_t kParameterIsInteger = 0x04;
112
113 /**
114 Parameter value is logarithmic.
115 */
116 static constexpr const uint32_t kParameterIsLogarithmic = 0x08;
117
118 /**
119 Parameter is of output type.@n
120 When unset, parameter is assumed to be of input type.
121
122 Parameter inputs are changed by the host and typically should not be changed by the plugin.@n
123 One exception is when changing programs, see Plugin::loadProgram().@n
124 The other exception is with parameter change requests, see Plugin::requestParameterValueChange().@n
125 Outputs are changed by the plugin and never modified by the host.
126
127 If you are targetting VST2, make sure to order your parameters so that all inputs are before any outputs.
128 */
129 static constexpr const uint32_t kParameterIsOutput = 0x10;
130
131 /**
132 Parameter value is a trigger.@n
133 This means the value resets back to its default after each process/run call.@n
134 Cannot be used for output parameters.
135
136 @note Only officially supported under LV2. For other formats DPF simulates the behaviour.
137 */
138 static constexpr const uint32_t kParameterIsTrigger = 0x20 | kParameterIsBoolean;
139
140 /**
141 Parameter should be hidden from the host and user-visible GUIs.@n
142 It is still saved and handled as any regular parameter, just not visible to the user
143 (for example in a host generated GUI)
144 */
145 static constexpr const uint32_t kParameterIsHidden = 0x40;
146
147 /** @} */
148
149 /* --------------------------------------------------------------------------------------------------------------------
150 * State Hints */
151
152 /**
153 @defgroup StateHints State Hints
154
155 Various state hints.
156 @see State::hints
157 @{
158 */
159
160 /**
161 State is visible and readable by hosts that support string-type plugin parameters.
162 */
163 static constexpr const uint32_t kStateIsHostReadable = 0x01;
164
165 /**
166 State is writable by the host, allowing users to arbitrarily change the state.@n
167 For obvious reasons a writable state is also readable by the host.
168 */
169 static constexpr const uint32_t kStateIsHostWritable = 0x02 | kStateIsHostReadable;
170
171 /**
172 State is a filename path instead of a regular string.@n
173 The readable and writable hints are required for filenames to work, and thus are automatically set.
174 */
175 static constexpr const uint32_t kStateIsFilenamePath = 0x04 | kStateIsHostWritable;
176
177 /**
178 State is a base64 encoded string.
179 */
180 static constexpr const uint32_t kStateIsBase64Blob = 0x08;
181
182 /**
183 State is for Plugin/DSP side only, meaning there is never a need to notify the UI when it changes.
184 */
185 static constexpr const uint32_t kStateIsOnlyForDSP = 0x10;
186
187 /**
188 State is for UI side only.@n
189 If the DSP and UI are separate and the UI is not available, this property won't be saved.
190 */
191 static constexpr const uint32_t kStateIsOnlyForUI = 0x20;
192
193 /** @} */
194
195 /* --------------------------------------------------------------------------------------------------------------------
196 * Base Plugin structs */
197
198 /**
199 @defgroup BasePluginStructs Base Plugin Structs
200 @{
201 */
202
203 /**
204 Parameter designation.@n
205 Allows a parameter to be specially designated for a task, like bypass.
206
207 Each designation is unique, there must be only one parameter that uses it.@n
208 The use of designated parameters is completely optional.
209
210 @note Designated parameters have strict ranges.
211 @see ParameterRanges::adjustForDesignation()
212 */
213 enum ParameterDesignation {
214 /**
215 Null or unset designation.
216 */
217 kParameterDesignationNull = 0,
218
219 /**
220 Bypass designation.@n
221 When on (> 0.5f), it means the plugin must run in a bypassed state.
222 */
223 kParameterDesignationBypass = 1
224 };
225
226 /**
227 Predefined Port Groups Ids.
228
229 This enumeration provides a few commonly used groups for convenient use in plugins.
230 For preventing conflicts with user code, negative values are used here.
231 When rolling your own port groups, you MUST start their group ids from 0 and they MUST be sequential.
232
233 @see PortGroup
234 */
235 enum PredefinedPortGroupsIds {
236 /**
237 Null or unset port group.
238 */
239 kPortGroupNone = (uint32_t)-1,
240
241 /**
242 A single channel audio group.
243 */
244 kPortGroupMono = (uint32_t)-2,
245
246 /**
247 A 2-channel discrete stereo audio group,
248 where the 1st audio port is the left channel and the 2nd port is the right channel.
249 */
250 kPortGroupStereo = (uint32_t)-3
251 };
252
253 /**
254 Audio Port.
255
256 Can be used as CV port by specifying kAudioPortIsCV in hints,@n
257 but this is only supported in LV2 and JACK standalone formats.
258 */
259 struct AudioPort {
260 /**
261 Hints describing this audio port.
262 @see AudioPortHints
263 */
264 uint32_t hints;
265
266 /**
267 The name of this audio port.@n
268 An audio port name can contain any character, but hosts might have a hard time with non-ascii ones.@n
269 The name doesn't have to be unique within a plugin instance, but it's recommended.
270 */
271 String name;
272
273 /**
274 The symbol of this audio port.@n
275 An audio port symbol is a short restricted name used as a machine and human readable identifier.@n
276 The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9.
277 @note Audio port and parameter symbols MUST be unique within a plugin instance.
278 */
279 String symbol;
280
281 /**
282 The group id that this audio/cv port belongs to.
283 No group is assigned by default.
284
285 You can use a group from PredefinedPortGroups or roll your own.@n
286 When rolling your own port groups, you MUST start their group ids from 0 and they MUST be sequential.
287 @see PortGroup, Plugin::initPortGroup
288 */
289 uint32_t groupId;
290
291 /**
292 Default constructor for a regular audio port.
293 */
294 AudioPort() noexcept
295 : hints(0x0),
296 name(),
297 symbol(),
298 groupId(kPortGroupNone) {}
299 };
300
301 /**
302 Parameter ranges.@n
303 This is used to set the default, minimum and maximum values of a parameter.
304
305 By default a parameter has 0.0 as minimum, 1.0 as maximum and 0.0 as default.@n
306 When changing this struct values you must ensure maximum > minimum and default is within range.
307 */
308 struct ParameterRanges {
309 /**
310 Default value.
311 */
312 float def;
313
314 /**
315 Minimum value.
316 */
317 float min;
318
319 /**
320 Maximum value.
321 */
322 float max;
323
324 /**
325 Default constructor, using 0.0 as default, 0.0 as minimum, 1.0 as maximum.
326 */
327 constexpr ParameterRanges() noexcept
328 : def(0.0f),
329 min(0.0f),
330 max(1.0f) {}
331
332 /**
333 Constructor using custom values.
334 */
335 constexpr ParameterRanges(float df, float mn, float mx) noexcept
336 : def(df),
337 min(mn),
338 max(mx) {}
339
340 /**
341 Fix the default value within range.
342 */
343 void fixDefault() noexcept
344 {
345 fixValue(def);
346 }
347
348 /**
349 Fix a value within range.
350 */
351 void fixValue(float& value) const noexcept
352 {
353 if (value < min)
354 value = min;
355 else if (value > max)
356 value = max;
357 }
358
359 /**
360 Get a fixed value within range.
361 */
362 float getFixedValue(const float& value) const noexcept
363 {
364 if (value <= min)
365 return min;
366 if (value >= max)
367 return max;
368 return value;
369 }
370
371 /**
372 Get a value normalized to 0.0<->1.0.
373 */
374 float getNormalizedValue(const float& value) const noexcept
375 {
376 const float normValue = (value - min) / (max - min);
377
378 if (normValue <= 0.0f)
379 return 0.0f;
380 if (normValue >= 1.0f)
381 return 1.0f;
382 return normValue;
383 }
384
385 /**
386 Get a value normalized to 0.0<->1.0.
387 Overloaded function using double precision values.
388 */
389 double getNormalizedValue(const double& value) const noexcept
390 {
391 const double normValue = (value - min) / (max - min);
392
393 if (normValue <= 0.0)
394 return 0.0;
395 if (normValue >= 1.0)
396 return 1.0;
397 return normValue;
398 }
399
400 /**
401 Get a value normalized to 0.0<->1.0, fixed within range.
402 */
403 float getFixedAndNormalizedValue(const float& value) const noexcept
404 {
405 if (value <= min)
406 return 0.0f;
407 if (value >= max)
408 return 1.0f;
409
410 const float normValue = (value - min) / (max - min);
411
412 if (normValue <= 0.0f)
413 return 0.0f;
414 if (normValue >= 1.0f)
415 return 1.0f;
416
417 return normValue;
418 }
419
420 /**
421 Get a value normalized to 0.0<->1.0, fixed within range.
422 Overloaded function using double precision values.
423 */
424 double getFixedAndNormalizedValue(const double& value) const noexcept
425 {
426 if (value <= min)
427 return 0.0;
428 if (value >= max)
429 return 1.0;
430
431 const double normValue = (value - min) / (max - min);
432
433 if (normValue <= 0.0)
434 return 0.0;
435 if (normValue >= 1.0)
436 return 1.0;
437
438 return normValue;
439 }
440
441 /**
442 Get a proper value previously normalized to 0.0<->1.0.
443 */
444 float getUnnormalizedValue(const float& value) const noexcept
445 {
446 if (value <= 0.0f)
447 return min;
448 if (value >= 1.0f)
449 return max;
450
451 return value * (max - min) + min;
452 }
453
454 /**
455 Get a proper value previously normalized to 0.0<->1.0.
456 Overloaded function using double precision values.
457 */
458 double getUnnormalizedValue(const double& value) const noexcept
459 {
460 if (value <= 0.0)
461 return min;
462 if (value >= 1.0)
463 return max;
464
465 return value * (max - min) + min;
466 }
467 };
468
469 /**
470 Parameter enumeration value.@n
471 A string representation of a plugin parameter value.@n
472 Used together can be used to give meaning to parameter values, working as an enumeration.
473 */
474 struct ParameterEnumerationValue {
475 /**
476 Parameter value.
477 */
478 float value;
479
480 /**
481 String representation of this value.
482 */
483 String label;
484
485 /**
486 Default constructor, using 0.0 as value and empty label.
487 */
488 ParameterEnumerationValue() noexcept
489 : value(0.0f),
490 label() {}
491
492 /**
493 Constructor using custom values.
494 */
495 ParameterEnumerationValue(float v, const char* l) noexcept
496 : value(v),
497 label(l) {}
498
499 #if __cplusplus >= 201703L
500 /**
501 Constructor using custom values, constexpr compatible variant.
502 */
503 constexpr ParameterEnumerationValue(float v, const std::string_view& l) noexcept
504 : value(v),
505 label(l) {}
506 #endif
507 };
508
509 /**
510 Details around parameter enumeration values.@n
511 Wraps ParameterEnumerationValues and provides a few extra details to the host about these values.
512 */
513 struct ParameterEnumerationValues {
514 /**
515 Number of elements allocated in @values.
516 */
517 uint8_t count;
518
519 /**
520 Whether the host is to be restricted to only use enumeration values.
521
522 @note This mode is only a hint! Not all hosts and plugin formats support this mode.
523 */
524 bool restrictedMode;
525
526 /**
527 Array of @ParameterEnumerationValue items.@n
528 When assining this pointer manually, it must be allocated on the heap with `new ParameterEnumerationValue[count]`.@n
529 The array pointer will be automatically deleted later unless @p deleteLater is set to false.
530 */
531 ParameterEnumerationValue* values;
532
533 /**
534 Whether to take ownership of the @p values pointer.@n
535 Defaults to true unless stated otherwise.
536 */
537 bool deleteLater;
538
539 /**
540 Default constructor, for zero enumeration values.
541 */
542 constexpr ParameterEnumerationValues() noexcept
543 : count(0),
544 restrictedMode(false),
545 values(nullptr),
546 deleteLater(true) {}
547
548 /**
549 Constructor using custom values.@n
550 When using this constructor the pointer to @values MUST have been statically declared.@n
551 It will not be automatically deleted later.
552 */
553 constexpr ParameterEnumerationValues(uint32_t c, bool r, ParameterEnumerationValue* v) noexcept
554 : count(c),
555 restrictedMode(r),
556 values(v),
557 deleteLater(false) {}
558
559 // constexpr
560 ~ParameterEnumerationValues() noexcept
561 {
562 if (deleteLater)
563 delete[] values;
564 }
565 };
566
567 /**
568 Parameter.
569 */
570 struct Parameter {
571 /**
572 Hints describing this parameter.
573 @see ParameterHints
574 */
575 uint32_t hints;
576
577 /**
578 The name of this parameter.@n
579 A parameter name can contain any character, but hosts might have a hard time with non-ascii ones.@n
580 The name doesn't have to be unique within a plugin instance, but it's recommended.
581 */
582 String name;
583
584 /**
585 The short name of this parameter.@n
586 Used when displaying the parameter name in a very limited space.
587 @note This value is optional, the full name is used when the short one is missing.
588 */
589 String shortName;
590
591 /**
592 The symbol of this parameter.@n
593 A parameter symbol is a short restricted name used as a machine and human readable identifier.@n
594 The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9.
595 @note Parameter symbols MUST be unique within a plugin instance.
596 */
597 String symbol;
598
599 /**
600 The unit of this parameter.@n
601 This means something like "dB", "kHz" and "ms".@n
602 Can be left blank if a unit does not apply to this parameter.
603 */
604 String unit;
605
606 /**
607 An extensive description/comment about the parameter.
608 @note This value is optional and only used for LV2.
609 */
610 String description;
611
612 /**
613 Ranges of this parameter.@n
614 The ranges describe the default, minimum and maximum values.
615 */
616 ParameterRanges ranges;
617
618 /**
619 Enumeration details.@n
620 Can be used to give meaning to parameter values, working as an enumeration.
621 */
622 ParameterEnumerationValues enumValues;
623
624 /**
625 Designation for this parameter.
626 */
627 ParameterDesignation designation;
628
629 /**
630 MIDI CC to use by default on this parameter.@n
631 A value of 0 or 32 (bank change) is considered invalid.@n
632 Must also be less or equal to 120.
633 @note This value is only a hint! Hosts might map it automatically or completely ignore it.
634 */
635 uint8_t midiCC;
636
637 /**
638 The group id that this parameter belongs to.
639 No group is assigned by default.
640
641 You can use a group from PredefinedPortGroups or roll your own.@n
642 When rolling your own port groups, you MUST start their group ids from 0 and they MUST be sequential.
643 @see PortGroup, Plugin::initPortGroup
644 */
645 uint32_t groupId;
646
647 /**
648 Default constructor for a null parameter.
649 */
650 Parameter() noexcept
651 : hints(0x0),
652 name(),
653 shortName(),
654 symbol(),
655 unit(),
656 ranges(),
657 enumValues(),
658 designation(kParameterDesignationNull),
659 midiCC(0),
660 groupId(kPortGroupNone) {}
661
662 /**
663 Constructor using custom values.
664 */
665 Parameter(uint32_t h, const char* n, const char* s, const char* u, float def, float min, float max) noexcept
666 : hints(h),
667 name(n),
668 shortName(),
669 symbol(s),
670 unit(u),
671 ranges(def, min, max),
672 enumValues(),
673 designation(kParameterDesignationNull),
674 midiCC(0),
675 groupId(kPortGroupNone) {}
676
677 #ifdef DISTRHO_PROPER_CPP11_SUPPORT
678 /**
679 Constructor using custom values and enumeration.
680 Assumes enumeration details should have `restrictedMode` on.
681 */
682 Parameter(uint32_t h, const char* n, const char* s, const char* u, float def, float min, float max,
683 uint8_t evcount, ParameterEnumerationValue ev[]) noexcept
684 : hints(h),
685 name(n),
686 shortName(),
687 symbol(s),
688 unit(u),
689 ranges(def, min, max),
690 enumValues(evcount, true, ev),
691 designation(kParameterDesignationNull),
692 midiCC(0),
693 groupId(kPortGroupNone) {}
694 #endif
695
696 #if __cplusplus >= 201703L
697 /**
698 Constructor for constexpr compatible data.
699 */
700 constexpr Parameter(uint32_t h,
701 const std::string_view& n,
702 const std::string_view& sn,
703 const std::string_view& sym,
704 const std::string_view& u,
705 const std::string_view& desc) noexcept
706 : hints(h),
707 name(n),
708 shortName(sn),
709 symbol(sym),
710 unit(u),
711 description(desc),
712 ranges(),
713 enumValues(),
714 designation(kParameterDesignationNull),
715 midiCC(0),
716 groupId(kPortGroupNone) {}
717 #endif
718
719 /**
720 Initialize a parameter for a specific designation.
721 */
722 void initDesignation(ParameterDesignation d) noexcept
723 {
724 designation = d;
725
726 switch (d)
727 {
728 case kParameterDesignationNull:
729 break;
730 case kParameterDesignationBypass:
731 hints = kParameterIsAutomatable|kParameterIsBoolean|kParameterIsInteger;
732 name = "Bypass";
733 shortName = "Bypass";
734 symbol = "dpf_bypass";
735 unit = "";
736 midiCC = 0;
737 groupId = kPortGroupNone;
738 ranges.def = 0.0f;
739 ranges.min = 0.0f;
740 ranges.max = 1.0f;
741 break;
742 }
743 }
744 };
745
746 #if __cplusplus >= 202001L /* TODO */
747 /**
748 Bypass parameter definition in constexpr form.
749 */
750 static constexpr const Parameter kParameterBypass = {
751 kParameterIsAutomatable|kParameterIsBoolean|kParameterIsInteger,
752 "Bypass", "Bypass", "dpf_bypass", "", "", {}, {}, 0, kPortGroupNone,
753 };
754 #endif
755
756 /**
757 Port Group.@n
758 Allows to group together audio/cv ports or parameters.
759
760 Each unique group MUST have an unique symbol and a name.
761 A group can be applied to both inputs and outputs (at the same time).
762 The same group cannot be used in audio ports and parameters.
763
764 When both audio and parameter groups are used, audio groups MUST be defined first.
765 That is, group indexes start with audio ports, then parameters.
766
767 An audio port group logically combines ports which should be considered part of the same stream.@n
768 For example, two audio ports in a group may form a stereo stream.
769
770 A parameter group provides meta-data to the host to indicate that some parameters belong together.
771
772 The use of port groups is completely optional.
773
774 @see Plugin::initPortGroup, AudioPort::group, Parameter::group
775 */
776 struct PortGroup {
777 /**
778 The name of this port group.@n
779 A port group name can contain any character, but hosts might have a hard time with non-ascii ones.@n
780 The name doesn't have to be unique within a plugin instance, but it's recommended.
781 */
782 String name;
783
784 /**
785 The symbol of this port group.@n
786 A port group symbol is a short restricted name used as a machine and human readable identifier.@n
787 The first character must be one of _, a-z or A-Z and subsequent characters can be from _, a-z, A-Z and 0-9.
788 @note Port group symbols MUST be unique within a plugin instance.
789 */
790 String symbol;
791 };
792
793 /**
794 State.
795
796 In DPF states refer to key:value string pairs, used to store arbitrary non-parameter data.@n
797 By default states are completely internal to the plugin and not visible by the host.@n
798 Flags can be set to allow hosts to see and/or change them.
799
800 TODO API under construction
801 */
802 struct State {
803 /**
804 Hints describing this state.
805 @note Changing these hints can break compatibility with previously saved data.
806 @see StateHints
807 */
808 uint32_t hints;
809
810 /**
811 The key or "symbol" of this state.@n
812 A state key is a short restricted name used as a machine and human readable identifier.
813 @note State keys MUST be unique within a plugin instance.
814 TODO define rules for allowed characters, must be usable as URI non-encoded parameters
815 */
816 String key;
817
818 /**
819 The default value of this state.@n
820 Can be left empty if considered a valid initial state.
821 */
822 String defaultValue;
823
824 /**
825 String representation of this state.
826 */
827 String label;
828
829 /**
830 An extensive description/comment about this state.
831 @note This value is optional and only used for LV2.
832 */
833 String description;
834
835 #ifdef __MOD_DEVICES__
836 /**
837 The file types that a filename path state supports, written as a comma-separated string without whitespace.
838 Currently supported file types are:
839 - audioloop: Audio Loops, meant to be used for looper-style plugins
840 - audiorecording: Audio Recordings, triggered by plugins and stored in the unit
841 - audiosample: One-shot Audio Samples, meant to be used for sampler-style plugins
842 - audiotrack: Audio Tracks, meant to be used as full-performance/song or backtrack
843 - cabsim: Speaker Cabinets, meant as small IR audio files
844 - h2drumkit: Hydrogen Drumkits, must use h2drumkit file extension
845 - ir: Impulse Responses
846 - midiclip: MIDI Clips, to be used in sync with host tempo, must have mid or midi file extension
847 - midisong: MIDI Songs, meant to be used as full-performance/song or backtrack
848 - sf2: SF2 Instruments, must have sf2 or sf3 file extension
849 - sfz: SFZ Instruments, must have sfz file extension
850
851 @note This is a custom extension only valid in builds MOD Audio.
852 */
853 String fileTypes;
854 #endif
855
856 /**
857 Default constructor for a null state.
858 */
859 State() noexcept
860 : hints(0x0),
861 key(),
862 defaultValue(),
863 label(),
864 description() {}
865 };
866
867 /**
868 MIDI event.
869 */
870 struct MidiEvent {
871 /**
872 Size of internal data.
873 */
874 static constexpr const uint32_t kDataSize = 4;
875
876 /**
877 Time offset in frames.
878 */
879 uint32_t frame;
880
881 /**
882 Number of bytes used.
883 */
884 uint32_t size;
885
886 /**
887 MIDI data.@n
888 If size > kDataSize, dataExt is used (otherwise null).
889
890 When dataExt is used, the event holder is responsible for
891 keeping the pointer valid during the entirety of the run function.
892 */
893 uint8_t data[kDataSize];
894 const uint8_t* dataExt;
895 };
896
897 /**
898 Time position.@n
899 The @a playing and @a frame values are always valid.@n
900 BBT values are only valid when @a bbt.valid is true.
901
902 This struct is inspired by the [JACK Transport API](https://jackaudio.org/api/structjack__position__t.html).
903 */
904 struct TimePosition {
905 /**
906 Wherever the host transport is playing/rolling.
907 */
908 bool playing;
909
910 /**
911 Current host transport position in frames.
912 @note This value is not always monotonic,
913 with some plugin hosts assigning it based on a source that can accumulate rounding errors.
914 */
915 uint64_t frame;
916
917 /**
918 Bar-Beat-Tick time position.
919 */
920 struct BarBeatTick {
921 /**
922 Wherever the host transport is using BBT.@n
923 If false you must not read from this struct.
924 */
925 bool valid;
926
927 /**
928 Current bar.@n
929 Should always be > 0.@n
930 The first bar is bar '1'.
931 */
932 int32_t bar;
933
934 /**
935 Current beat within bar.@n
936 Should always be > 0 and <= @a beatsPerBar.@n
937 The first beat is beat '1'.
938 */
939 int32_t beat;
940
941 /**
942 Current tick within beat.@n
943 Should always be >= 0 and < @a ticksPerBeat.@n
944 The first tick is tick '0'.
945 @note Fraction part of tick is only available on some plugin formats.
946 */
947 double tick;
948
949 /**
950 Number of ticks that have elapsed between frame 0 and the first beat of the current measure.
951 */
952 double barStartTick;
953
954 /**
955 Time signature "numerator".
956 */
957 float beatsPerBar;
958
959 /**
960 Time signature "denominator".
961 */
962 float beatType;
963
964 /**
965 Number of ticks within a beat.@n
966 Usually a moderately large integer with many denominators, such as 1920.0.
967 */
968 double ticksPerBeat;
969
970 /**
971 Number of beats per minute.
972 */
973 double beatsPerMinute;
974
975 /**
976 Default constructor for a null BBT time position.
977 */
978 BarBeatTick() noexcept
979 : valid(false),
980 bar(0),
981 beat(0),
982 tick(0),
983 barStartTick(0.0),
984 beatsPerBar(0.0f),
985 beatType(0.0f),
986 ticksPerBeat(0.0),
987 beatsPerMinute(0.0) {}
988
989 /**
990 Reinitialize this position using the default null initialization.
991 */
992 void clear() noexcept
993 {
994 valid = false;
995 bar = 0;
996 beat = 0;
997 tick = 0;
998 barStartTick = 0.0;
999 beatsPerBar = 0.0f;
1000 beatType = 0.0f;
1001 ticksPerBeat = 0.0;
1002 beatsPerMinute = 0.0;
1003 }
1004 } bbt;
1005
1006 /**
1007 Default constructor for a time position.
1008 */
1009 TimePosition() noexcept
1010 : playing(false),
1011 frame(0),
1012 bbt() {}
1013
1014 /**
1015 Reinitialize this position using the default null initialization.
1016 */
1017 void clear() noexcept
1018 {
1019 playing = false;
1020 frame = 0;
1021 bbt.clear();
1022 }
1023 };
1024
1025 /** @} */
1026
1027 // --------------------------------------------------------------------------------------------------------------------
1028
1029 END_NAMESPACE_DISTRHO
1030
1031 #endif // DISTRHO_DETAILS_HPP_INCLUDED