FxDynamicParameterAPI_v3::setAsDefaultsAtTime - API method is Missing ParameterID?

[belisoful]

Apple Feedback Assistant ID: MISSING

DESCRIBE THE BUG:
https://developer.apple.com/documentation/professional_video_applications/fxdynamicparameterapi_v3/setasdefaultsat(_:)?language=objc
Does this function set all the current parameter settings to the default? or this parameter settings to default? Which parameter ID?

I believe this is an API oversight. The point of this API class is to manipulate specific parameter properties, like name, min, max, etc. It makes no sense that the documentation would identify that one parameter settings are set as default, but then have no input for the Parameter ID.

---

TO REPRODUCE:
The API across the board

---

EXPECTED BEHAVIOUR:
I expect the method to accept a ParameterID to set its current setting(s) to the default for that specific parameter.

Either that or the API documentation shouldn't identify one parameter to be updated but specifically say all the parameters are getting their default values set to the current settings across the board.

---

SCREENSHOTS:
none.

---

SPECS:

• 2021 16-inch MacBook Pro (M1 Max, 32GB RAM, 2TB SSD)
• macOS Sonoma 15.1.1
• Final Cut Pro 11

---

ADDITIONAL COMMENTS:

Does this mean that FxDynamicParameterAPI_v3 is going to be FxDynamicParameterAPI_v4?
If this is the case, can you please also include a method
- (FxParameterType)parameterType:(UInt32)parameterID;

As a framework developer, it'd be nice to be able to access this information. We may not know what the developer using our FxPlug framework is doing with each parameter type. Tracking parameter type information is much more difficult than it needs to be. This is most necessary for plugins that are dynamic with their parameters, adding and removing them in real time.

[belisoful]

I believe this API oversight to be a bug rather than a feature request. The FxPlug API offhandedly suggests that there should be a ParameterID in the method. The end result of this comment and full resolution of the bug is a feature request. lol.

The Method currently is:

- (BOOL) setAsDefaultsAtTime:(CMTime) time withError:(NSError * *) error;

Which the documentation says...

"Tell the host app that the settings at the given time should be considered the default settings for this parameter."

This is a Bug in the documentation. A custom parameter can have multiple settings within one parameter, and "this parameter" is singular. The term "settings" is plural and suggests that all parameters have their defaults set (when not considering the Custom Parameter case). This contradiction and unclarity is unacceptable.

If the API is correct, then the bug is in the Documentation both online and in the header documentation. This would be much better:

"Tell the host app that the settings at the given time should be considered the default settings for all the parameters."

However, the entire Dynamic Parameter API is based around interacting with one parameter at a time. Together with the above comment about the documentation, it makes sense that this method does actually mean to specify an input parameterID, like this:

- (BOOL) setAsDefaults:(UInt32) parameterID  atTime:(CMTime) time withError:(NSError * *) error;
 //   or
- (BOOL) setAsDefault:(UInt32) parameterID  atTime:(CMTime) time withError:(NSError * *) error;

Either way, it's either a bug in the documentation or the API itself.

---

Secondarily, if it's the documentation is wrong and Apple meant to say "...all the parameters." only then would it be a feature request for the above methods. It makes more sense [to me] that the default[s] of one parameter are set in each call. However, "AtTime" is not ideal...

---

Setting the default linked to a time is also kind of weird. Almost sloppy. What does a particular time have to do with the value? Can we set different default values for different points of time? that makes Zero sense. The default of a parameter is independent of time, no? I see why this way of referencing values was chosen... no need to specify the actual value and the multitude of data types.

That time has nothing to do with the defaults but used to aid in identifying the values, should be documented as well. There is only one default, and the time is only used to identify the value.

From my perspective, what is sloppy is that setting the default of a parameter is independent of time. There is no time dependence for "default values."

And the bug? .... what if the default value I want to set a parameter to is not in the timeline? Do we need to set the value on the timeline for all parameters (to not overwrite some), then set all as default, and then restore the value on the timeline?

Setting defaults should technically mimic FxParameterSettingAPI_v5 but with Defaults and without time. like this:

FxParameterSetDefaultsAPI_v1
// like this
- (BOOL) setDefaultBoolValue:(BOOL) value toParameter:(UInt32) parameterID;
- (BOOL) setDefaultIntValue:(int)value toParameter:(UInt32) parameterID;
// etc.

Interestingly, there is no way to get the defaults either. this suggests the need for a
FxParameterGetDefaultsAPI_v1 as well.

[belisoful]

Can we have both labels? lol.