Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[FR] Add 'rates' tag to UGen arguments in help docs #4303

Open
mtmccrea opened this Issue Feb 11, 2019 · 5 comments

Comments

Projects
None yet
3 participants
@mtmccrea
Copy link
Contributor

mtmccrea commented Feb 11, 2019

Motivation

This is a concrete strategy to begin to address #3723, #3825.

UGens support a variety or rates for argument inputs, but support for various rates across all of the UGens is inconsistent and undocumented for the most part. Adding a tag to the help docs could promote documenting supported argument rates.

A tangential benefit would be that if existing UGens are documented over time, it would put more eyes on source code to identify where UGens don't fully support all reasonable input rates, and bugs in the rates that are supported.

Description of Proposed Feature

In addition to the argument:: tag, there would also be a rates:: tag that could support values like ar, k2a, kr, ir (are there other possibilities). k2a would indicate that control-rate inputs are interpolated to audio-rate over the control period. Alternatively this behavior would be designated by the default kr rate, and control-rate arguments that aren't interpolated could be something like kr-no-interp.

Something else to consider as a part of this would be other possible values for triggered inputs, specifying whether the trigger will affect the current sample/block output, the next, or is interpolated for inter-sample accuracy. This addition would take a bit more consideration...

Plan for Implementation

In addition to supporting this tag in the help renderer, an important aid to adoption would be to include these tags in the auto-generated help template for undocumented classes. This would need to detect ar and kr methods, and include rates:: ar, k2a, kr, ir after the argument:: description.

I would imagine the already-existing UGen docs would remain as they are, but could be populated with this new field over time. It's relatively easy to identify supported rates by looking at the source, but there are many to document and would have to just be knocked out in batches, perhaps one source file at a time. I'm happy to contribute to this effort.

@telephon

This comment has been minimized.

Copy link
Member

telephon commented Feb 21, 2019

Thank you, a good idea!

The specification itself should then not be in the help system, but in the class library. You'd want to check the rates through introspection. I'd suggest:

UGen {
    inputRates {
        ^this.subclassResponsibility(thisMethod)
    }

}
@muellmusik

This comment has been minimized.

Copy link
Contributor

muellmusik commented Feb 21, 2019

Nice idea! I agree with Julian that it should be class side, not doc side as this would be useful elsewhere.

Does it need to return an array for each arg? I wonder as ar does not necessarily mean that kr is okay or interpolated. This could also be done with the spec, i.e. ar-no-kr-interp or whatever

@telephon

This comment has been minimized.

Copy link
Member

telephon commented Feb 21, 2019

I think all should be done with a single symbol per slot. Then we have a good overview of what is unsystematic.

I'm not sure if we should add information of whether kr is interpolated. This is up to the UGen to decide, and in the end it gets complicated if we want to describe what UGens do with their inputs.
But you are right that it makes a difference if I plug an audio rate UGen into a control rate input whether this will be sampled or interpolated. Any ideas?

Also maybe there can be labels like all: could imply that kr and ir is ok. And dr could imply "all+demand rate", but maybe there are cases of incorrect implementation, which could be marked by dr-no-ar.

There are some cases where ar is permitted, but may not work correctly (Env.asr().kr(audio-rate-trigger)).

@mtmccrea

This comment has been minimized.

Copy link
Contributor Author

mtmccrea commented Feb 23, 2019

Thanks for considering this.

The specification itself should then not be in the help system, but in the class library.

This is a great idea!

I think all should be done with a single symbol per slot. Then we have a good overview of what is unsystematic.

I'm not sure it's possible to capture all supported rated with a single Symbol per argument. This depends on the implementation and number of calculation functions in the UGen. I could be overlooking other uses for the rate specs which may be made more complicated by arrays, but arrays would be more precise in describing the functionality.

I think the following would cover most cases.

Supported argument rate Symbol Behavior with ar method Behavior with kr method
'a' every ar sample is used the first ar sample in the block is used
'k' kr sample is held over the block output updates with each sample
'k2a' value is interpolated between the previous kr sample and the current one, over the block output updates with each sample
'i' initial value is held for the life of the UGen initial value is held for the life of the UGen
'tc' trigger effects the current output sample trigger effects the current output sample
'tn' trigger effects the next output sample trigger effects the next output sample
'ti' trigger location is interpolated between the previous and current sample trigger location is interpolated between the previous and current sample

Am I missing any cases?

Rendering into the help file might look something like this (just a quick mockup in an image editor):

I'm not sold on these particular symbols, I chose these to avoid confusion with the rate methods. Other suggestions?

I'm not all that familiar with demand-rate. My understanding is that demand rate UGens only ever update at one rate, so there is no variation to document. Is this the case?

There would need to be clarification in the UGen spec for outliers, like the case of a UGen running at kr supplied with an audio-rate argument. In that case, the ar definition above should still be accurate if it's supported. If an audio-rate argument rate isn't supported when running at control-rate, this should be caught with rate checking in the class implementation.

There are some cases where ar is permitted, but may not work correctly (Env.asr().kr(audio-rate-trigger)).

Exceptional and broken cases can be documented in the argument description.

I see one of the goals of this feature is to work toward a UGen spec for proper rate handling. I like Julian's suggestion of a Ugen:-inputRates in particular because by requiring authors to list supported rates it would remind them that they need to handle all possible input rates, and be intentional about which they choose to support or not. Having combed through a number of UGens recently, it seems rate support varies either because of rushed implementations, assumptions of common use cases, or authors trying to consolidate the number of calculation functions at the expense of robust rate handling.

@telephon

This comment has been minimized.

Copy link
Member

telephon commented Feb 24, 2019

My understanding is that demand rate UGens only ever update at one rate, so there is no variation to document. Is this the case?

When documenting the UGen's inputs, we need to also account for:

  • how the demand ugens use the values from their inputs (they should usually be taking exactly the right sample in the block when it is audio rate, but this need to be checked. If there is some missing it is easier to change the implementation)
  • how non-demand ugens use a demand input. Some actually pull a value, like the granular ugens. It would be nice if triggered ugens would do this in general, but well...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.