1.1.1.16 OcaDynamicsCurve

Class Hierarchy:

OcaRoot : OcaWorker : OcaActuator : OcaDynamicsCurve

class OcaDynamicsCurve : OcaActuator

Dynamic compression / expansion curve. Curve means a function that expresses the relationship of output level to input level. The dependent variable (Y) of the curve is output level; the independent variable (X) is input level. Every curve shall be composed of (n+1) straight-line segments joined by (n) small fillets called knees. Each knee shall occur at a particular input level value called the threshold. Each segment shall be characterized by its slope. ** ** | ** / ** | S3 ** / ** | S2 ** / ** | T1**————-T2 | ** / ** | S1 ** / ** | ** / ** | ** / ** +———————————— This “drawing” shows a three-segment curve. The horizontal axis is input level, vertical axis is output level. Algebraically, a curve shall be a function ** Out = Curve( In, T[1..n-1], S[1..n], K[1..n-1] ) where n is the number of segments, and In is input level in dBr Out is output level in dBr T[1…n-1] is an array of thresholds in dBr S[1…n] is an array of slopes in dBr per dBr, i.e. unitless K[1..n] is the knee parameter, an implementation-dependant parameter that specifies the shape of the curve around the knee. Each segment shall have a slope that expresses its ratio of output level to input level. Note that this slope is the inverse of what dynamics processors call “ratio”. For example, a ratio of 2:1 shall be represented by a curve segment with slope 1/2 = 0.5. This model can represent various kinds of audio dynamics elements (we ignore K[] in these examples): - Compressor with ratio of 2:1 and threshold of 10dBr: ** n = 2** ** T[1] = 10** ** S[1] = 1** ** S[2] = 0.5** - Hard limiter with threshold of 18dBr: ** n = 2** T[1] = 18 S[1] = 1 S[2] = 0 - Upward expander with ratio of 1.5:1 and threshold of -12dBr: ** n = 2** T[1] = -12 S[1] = 1 S[2] = 1.5 - Downward expander (gate) with ratio of 50:1 and threshold of -45dBr: ** n = 2** T[1] = -45 S[1] = 50 S[2] = 1 This class, OcaDynamicsCurve, shall add two additional parameters to the basic curve mechanism. Out = Curve( In, T[1..n-1], S[1..n], K[1..n-1] , Floor, Ceiling) where In, T[], and S[], and K[] are as defined above. Floor shall be the lowest gain (in dBr) that the dynamics element is allowed to produce. Ceiling shall be the highest gain (in dBr) that the dynamics element is allowed to produce. To show the use of Floor and Ceiling, we revisit some of the examples above (again, K[] is ignored): - Compressor with ratio of 2:1, threshold of 10dBr, and max gain reduction of 20dB: ** n = 2** ** T[1] = 10** ** S[1] = 1** ** S[2] = 0.5** ** Floor = -20** ** Ceiling = 0** - Upward expander with ratio of 1.5:1, threshold of -12dBr, and max gain boost of 4dB: ** n = 2** T[1] = -12 S[1] = 1 S[2] = 1.5 Floor = 0 Ceiling = 4.0 More complex dynamics curves may be modeled by using more segments (n > 2).

Properties:

static const OcaClassID ClassID = "1.1.1.16"

Number that uniquely identifies the class. Note that this differs from the object number, which identifies the instantiated object. This property is an override of the OcaRoot property.

This property has id 1.1.

static const OcaClassVersionNumber ClassVersion = 3

Identifies the interface version of the class. Any change to the class definition leads to a higher class version. This property is an override of the OcaRoot property.

This property has id 1.2.

OcaDB DynamicGainCeiling

Highest allowed dynamic gain value. See class description for details.

This property has id 4.6.

OcaDB DynamicGainFloor

Lowest allowed dynamic gain value. See class description for details.

This property has id 4.5.

OcaList<OcaFloat32> KneeParameters

K[1..n]. See class description for details.

This property has id 4.4.

OcaUint8 nSegments

Number of curve segments.

This property has id 4.1.

OcaList<OcaFloat32> Slopes

S[1..n]. See class description for details.

This property has id 4.3.

OcaList<OcaDBr> Thresholds

List of curve segment thresholds. See class description.

This property has id 4.2.

Properties inherited from 1.1.1 OcaActuator:

Methods:

OcaStatus GetNSegments(OcaUint8 &NSegments, OcaUint8 &minN, OcaUint8 &maxN)

Gets the count, min count, and max count of curve segments.

This method has id 4.1.

OcaStatus SetNSegments(OcaUint8 Slope)

Sets the number of curve segments. If this method increases the value of n, the data in properties Threshold, Slope, and KneeParameter of the new segment are by default set to the values of the previous segment.

This method has id 4.2.

  • Slope: Input parameter.

OcaStatus GetThreshold(OcaDBr &Threshold, OcaDBz &minThreshold, OcaDBz &maxThreshold)

Gets the list of Threshold values. Deprecated in v3 of this class, replaced by GetThresholds(…). Note: this method contains a definition error and should not be used.

This method has id 4.3.

OcaStatus SetThresholds(OcaList<OcaDBr> Threshold)

Sets the list of Threshold values. In v3 of this class, replaces SetThreshold(..)

This method has id 4.4.

OcaStatus GetSlopes(OcaList<OcaFloat32> &Slopes, OcaList<OcaFloat32> &minSlope, OcaList<OcaFloat32> &maxSlope)

Gets the lists of Slope values, minima, and maxima. In v3 of this class, replaces GetSlope(..).

This method has id 4.5.

OcaStatus SetSlopes(OcaList<OcaFloat32> slope)

Sets the list of Slope values. In v3 of this class, replaces SetSlope(..)

This method has id 4.6.

  • slope: Input parameter.

OcaStatus GetKneeParameters(OcaList<OcaFloat32> &Parameters, OcaList<OcaFloat32> &minParameter, OcaList<OcaFloat32> &maxParameter)

Gets the list of KneeParameter values, minima, and maxima. In v3 of this class, replaces GetKneeParameter(..).

This method has id 4.7.

OcaStatus SetKneeParameters(OcaList<OcaFloat32> Parameters)

Sets the list of KneeParameter values. In v3 of this class, replaces SetKneeParameter(..).

This method has id 4.8.

OcaStatus GetDynamicGainCeiling(OcaDB &Gain, OcaDB &minGain, OcaDB &maxGain)

Gets the value and limits of the DynamicGainCeiling property.

This method has id 4.9.

OcaStatus SetDynamicGainCeiling(OcaDB gain)

Sets the value of the DynamicGainCeiling property.

This method has id 4.10.

  • gain: Input parameter.

OcaStatus GetDynamicGainFloor(OcaDB &Gain, OcaDB &minGain, OcaDB &maxGain)

Gets the value and limits of the DynamicGainFloor property.

This method has id 4.11.

OcaStatus SetDynamicGainFloor(OcaDB Gain)

Sets the value of the DynamicGainFloor property.

This method has id 4.12.

  • Gain: Input parameter.

OcaStatus SetMultiple(OcaParameterMask Mask, OcaUint8 NSegments, OcaList<OcaDBr> Thresholds, OcaList<OcaFloat32> Slope, OcaList<OcaFloat32> KneeParameter, OcaDB DynamicGainFloor, OcaDB DynamicGainCeiling)

Sets some or all dynamics curve parameters. The action of this method shall be atomic - if any of the value changes fails, none of the changes shall be made.

This method has id 4.13.

OcaStatus GetThresholds(OcaList<OcaDBr> &Thresholds, OcaDBz &minThreshold, OcaDBz &maxThreshold)

Gets the list of Threshold values, and the minimum and maximum slope. In v3 of this class, replaces GetThreshold(..).

This method has id 4.14.

Methods inherited from 1.1.1 OcaActuator: