Clarify process status and tail extension docs

[Quant1um]

Clarify process status related documentation in process.h and ext/tail.h, based on #486.

Unresolved questions:

• Should tail be latency-aware or not? This PR defines the tail as the amount of time in samples since last variation in the input, which implies latency-unaware-ness. This seems to be consistent with definitions given in Some ambiguities in the CLAP standard to discuss #414. A different comment left in Clarify the meaning of some process statuses #486 seems to imply that you have to wait for M+N (where M is latency and N is tail) samples until the output is silent.

Corrections are appreciated!

[CLAassistant]

All committers have signed the CLA.

[defiantnerd]

Tail never contains the latency. Those are separete values. If they would be intertwened, communication with the host about it would be a mess.

[defiantnerd]

Can you please stop this slop?

[Quant1um]

Tail never contains the latency. Those are separete values. If they would be intertwened, communication with the host about it would be a mess.

Got it! That is my understanding as well, that tail is just the number of samples from an event/non-zero audio sample to the point where it is safe to stop processing, and I wrote the docs from the point of view of that assumption. The thing I got confused by is the comment left in #486

[edwloef]

I think it would be good to add a short note specifying whether the host should "forget" about previous inputs when the plugin's reset function is called, wrt. deciding whether to send a plugin to sleep in response to CLAP_PROCESS_TAIL. Maybe something like it is safe to stop processing if the last input event/variation (see CLAP_PROCESS_SLEEP for resume conditions) has occurred at least clap_plugin_tail.get samples ago, or the last input event/variation occured before the last call to plugin->reset?

[edwloef]

Oh, while we're here, could we also get some clarification on what main-thread,audio-thread means for clap_plugin_tail->get? Should that mean or be changed to thread-safe or active ? audio-thread : main-thread? In general, what does the return value represent when the plugin is deactivated, or should that also be a disallowed scenario, like with the latency extension?

[Quant1um]

Oh, while we're here, could we also get some clarification on what main-thread,audio-thread means for clap_plugin_tail->get? Should that mean or be changed to thread-safe or active ? audio-thread : main-thread? In general, what does the return value represent when the plugin is deactivated, or should that also be a disallowed scenario, like with the latency extension?

I agree that [main-thread,audio-thread] is a bit weird and it should probably be changed to [thread-safe] or, even better, [audio-thread] or even [active & audio-thread], I am not sure what the right choice would be and changing it could result in breakage with existing plugins/hosts. More discussion is needed probably.

[edwloef]

Does/should a plugin calling clap_host.request_process count as a change in input for the tail extension? I.e. when a plugin calls clap_host.request_process and returns CLAP_PROCESS_TAIL, should the host keep calling process for clap_plugin_tail.get samples? The added documentation for CLAP_PROCESS_SLEEP explicitly mentions clap_host.request_process, but the added documentation for CLAP_PROCESS_TAIL does not.

[Quant1um]

Does/should a plugin calling clap_host.request_process count as a change in input for the tail extension? I.e. when a plugin calls clap_host.request_process and returns CLAP_PROCESS_TAIL, should the host keep calling process for clap_plugin_tail.get samples? The added documentation for CLAP_PROCESS_SLEEP explicitly mentions clap_host.request_process, but the added documentation for CLAP_PROCESS_TAIL does not.

I'd say it should count as a resume condition for tail as well (for consistency with SLEEP), I agree that the docs should be clearer.

[Quant1um]

Also I think tail->get should be changed to [thread-safe & active], it should be a relatively safe change as it already doesn't make sense to call tail->get before sample rate is available. Thoughts?

[edwloef]

Perhaps CLAP_PROCESS_CONTINUE_IF_NOT_QUIET should also explicitly mention whether it's latency-aware. i.e. whether when the host should keep processing for at least latency more samples to determine whether "quiet" has been achieved, or whether the plugin should keep track of that.