Rename ParamQuantity::set/getDirectValue() to set/getImmediateValue().

Use setImmediateValue() when appropriate in ParamQuantity and SwitchQuantity, such as in reset(), randomize(), and setDisplayValue().
Add doc comments to ParamQuantity.

include/engine/ParamQuantity.hpp

@@ -16,7 +16,7 @@ struct Module;
 
 /** A Quantity that wraps an engine::Param.
 
-If `smoothEnabled` is true, all methods access/modify the target value of the Engine's smoothing algorithm for a Param instead of the value directly.
+If `smoothEnabled` is true, all methods access/modify the Param's target value of the Engine's per-sample smoothing algorithm instead of the immediate value.
 */
 struct ParamQuantity : Quantity {
 	Module* module = NULL;
@@ -68,38 +68,37 @@ struct ParamQuantity : Quantity {
 
 	Param* getParam();
 
-	/** Deprecated. Use setValue() instead, which is identical since Rack 2.3.0. */
-	DEPRECATED void setSmoothValue(float value);
-	/** Deprecated. Use getValue() instead, which is identical since Rack 2.3.0. */
-	DEPRECATED float getSmoothValue();
+	/** Sets the target value of the Engine's smoothing algorithm, or immediate value if smoothing is disabled.
 
-	/** Sets the Param value immediately without smoothing.
-	If value is currently being smoothed by the engine, smoothing is canceled.
+	Before Rack 2.3.0, this always set the Param's immediate value.
+	For this behavior, use `setImmediateValue()` instead.
 	*/
-	void setDirectValue(float value);
-	/** Gets the Param value post-smoothing.
-	If value is currently being smoothed by the engine, the return value is different than getValue().
-	*/
-	float getDirectValue();
+	void setValue(float value) override;
+	/** Gets the Param's smoothing target value, or immediate value if smoothing is disabled.
 
-	/** Sets the Param's smoothing target value, or direct value if smoothing is disabled.
+	Before Rack 2.3.0, this always got the Param's immediate value.
+	For this behavior, use `getImmediateValue()` instead.
+	*/
+	float getValue() override;
+	/** Sets the Param's value immediately without smoothing.
 
-	Before Rack 2.3.0, this always set the Param's value directly.
-	For this behavior, use `setDirectValue()` instead.
+	If the Param's value is currently being smoothed by the Engine, smoothing is canceled.
 	*/
-	void setValue(float value) override;
-	/** Gets the Param's smoothing target value, or direct value if smoothing is disabled.
+	void setImmediateValue(float value);
+	/** Gets the Param's value post-smoothing.
 
-	Before Rack 2.3.0, this always got the Param's value directly.
-	For this behavior, use `getDirectValue()` instead.
+	If (and only if) the Param's value is currently being smoothed by the Engine, the return value is different than getValue().
 	*/
-	float getValue() override;
+	float getImmediateValue();
+
 	float getMinValue() override;
 	float getMaxValue() override;
 	float getDefaultValue() override;
 	float getDisplayValue() override;
+	/** Always sets immediate value. */
 	void setDisplayValue(float displayValue) override;
 	std::string getDisplayValueString() override;
+	/** Always sets immediate value. */
 	void setDisplayValueString(std::string s) override;
 	int getDisplayPrecision() override;
 	std::string getLabel() override;
@@ -111,6 +110,11 @@ struct ParamQuantity : Quantity {
 
 	virtual json_t* toJson();
 	virtual void fromJson(json_t* rootJ);
+
+	/** Deprecated. Use setValue() instead, which is identical since Rack 2.3.0. */
+	DEPRECATED void setSmoothValue(float value);
+	/** Deprecated. Use getValue() instead, which is identical since Rack 2.3.0. */
+	DEPRECATED float getSmoothValue();
 };
 
 

src/engine/Module.cpp

@@ -250,7 +250,7 @@ void Module::paramsFromJson(json_t* rootJ) {
 
 		json_t* valueJ = json_object_get(paramJ, "value");
 		if (valueJ)
-			pq->setDirectValue(json_number_value(valueJ));
+			pq->setImmediateValue(json_number_value(valueJ));
 	}
 }
 

src/engine/ParamQuantity.cpp

@@ -18,50 +18,46 @@ engine::Param* ParamQuantity::getParam() {
 	return &module->params[paramId];
 }
 
-void ParamQuantity::setSmoothValue(float value) {
-	setValue(value);
-}
-
-float ParamQuantity::getSmoothValue() {
-	return getValue();
-}
 
-void ParamQuantity::setDirectValue(float value) {
+void ParamQuantity::setValue(float value) {
 	if (!module)
 		return;
 	value = math::clampSafe(value, getMinValue(), getMaxValue());
 	if (snapEnabled)
 		value = std::round(value);
-	APP->engine->setParamValue(module, paramId, value);
+	if (smoothEnabled)
+		APP->engine->setParamSmoothValue(module, paramId, value);
+	else
+		APP->engine->setParamValue(module, paramId, value);
 }
 
-float ParamQuantity::getDirectValue() {
+
+float ParamQuantity::getValue() {
 	if (!module)
 		return 0.f;
-	return APP->engine->getParamValue(module, paramId);
+	// Get smoothing target value regardless of `smoothEnabled`.
+	// If smoothing is enabled, value is set, and smoothing is then disabled, calling getParamValue() will return the incorrect value.
+	return APP->engine->getParamSmoothValue(module, paramId);
 }
 
-void ParamQuantity::setValue(float value) {
+
+void ParamQuantity::setImmediateValue(float value) {
 	if (!module)
 		return;
 	value = math::clampSafe(value, getMinValue(), getMaxValue());
 	if (snapEnabled)
 		value = std::round(value);
-	if (smoothEnabled)
-		APP->engine->setParamSmoothValue(module, paramId, value);
-	else
-		APP->engine->setParamValue(module, paramId, value);
+	APP->engine->setParamValue(module, paramId, value);
 }
 
-float ParamQuantity::getValue() {
+
+float ParamQuantity::getImmediateValue() {
 	if (!module)
 		return 0.f;
-	if (smoothEnabled)
-		return APP->engine->getParamSmoothValue(module, paramId);
-	else
-		return APP->engine->getParamValue(module, paramId);
+	return APP->engine->getParamValue(module, paramId);
 }
 
+
 float ParamQuantity::getMinValue() {
 	return minValue;
 }
@@ -91,6 +87,7 @@ float ParamQuantity::getDisplayValue() {
 	return v * displayMultiplier + displayOffset;
 }
 
+
 void ParamQuantity::setDisplayValue(float displayValue) {
 	// Handle displayOffset
 	float v = displayValue - displayOffset;
@@ -119,35 +116,42 @@ void ParamQuantity::setDisplayValue(float displayValue) {
 		return;
 
 	// Set the value directly without smoothing
-	setValue(v);
+	setImmediateValue(v);
 }
 
+
 int ParamQuantity::getDisplayPrecision() {
 	return displayPrecision;
 }
 
+
 std::string ParamQuantity::getDisplayValueString() {
 	return Quantity::getDisplayValueString();
 }
 
+
 void ParamQuantity::setDisplayValueString(std::string s) {
 	Quantity::setDisplayValueString(s);
 }
 
+
 std::string ParamQuantity::getLabel() {
 	if (name == "")
 		return string::f("#%d", paramId + 1);
 	return name;
 }
 
+
 std::string ParamQuantity::getUnit() {
 	return unit;
 }
 
+
 void ParamQuantity::reset() {
-	Quantity::reset();
+	setImmediateValue(getDefaultValue());
 }
 
+
 void ParamQuantity::randomize() {
 	if (!isBounded())
 		return;
@@ -156,14 +160,15 @@ void ParamQuantity::randomize() {
 		// Randomize inclusive of the maximum value
 		float value = math::rescale(random::uniform(), 0.f, 1.f, getMinValue(), getMaxValue() + 1.f);
 		value = std::floor(value);
-		setValue(value);
+		setImmediateValue(value);
 	}
 	else {
-		// Same as Quantity::randomize
-		setScaledValue(random::uniform());
+		// Same as Quantity::randomize() but with setImmediateValue()
+		setImmediateValue(fromScaled(random::uniform()));
 	}
 }
 
+
 std::string ParamQuantity::getDescription() {
 	return description;
 }
@@ -179,10 +184,23 @@ json_t* ParamQuantity::toJson() {
 void ParamQuantity::fromJson(json_t* rootJ) {
 	json_t* valueJ = json_object_get(rootJ, "value");
 	if (valueJ)
-		setValue(json_number_value(valueJ));
+		setImmediateValue(json_number_value(valueJ));
 }
 
 
+void ParamQuantity::setSmoothValue(float value) {
+	setValue(value);
+}
+
+
+float ParamQuantity::getSmoothValue() {
+	return getValue();
+}
+
+
+// SwitchQuantity
+
+
 std::string SwitchQuantity::getDisplayValueString() {
 	int index = (int) std::floor(getValue() - getMinValue());
 	if (!(0 <= index && index < (int) labels.size()))
@@ -190,6 +208,7 @@ std::string SwitchQuantity::getDisplayValueString() {
 	return labels[index];
 }
 
+
 void SwitchQuantity::setDisplayValueString(std::string s) {
 	// Find label that matches string, case insensitive.
 	auto it = std::find_if(labels.begin(), labels.end(), [&](const std::string& a) {
@@ -198,7 +217,7 @@ void SwitchQuantity::setDisplayValueString(std::string s) {
 	if (it == labels.end())
 		return;
 	int index = std::distance(labels.begin(), it);
-	setValue(getMinValue() + index);
+	setImmediateValue(getMinValue() + index);
 }