server plugins: Unify panning behavior of granular ugens

[nhthn]

The pan argument to TGrains has two problems, originally reported for TGrains2 in sc3-plugins. One of them is a documentation issue, which says that it behaves like PanAz. The intended behavior is more like GrainBuf, which behaves like Pan2 when the number of channels is 2, and like PanAz for 3 or more channels.

Furthermore, the math of the pan argument is not a correct emulation of Pan2. Here is a crude way to visualize the problem, by plotting a pan from -2 to 2:

b = Buffer.read(s, Platform.resourceDir +/+ "sounds/a11wlk01.wav");
{ Pan2.ar(SinOsc.ar(440), Line.kr(-2, 2, 1)) }.plot(1.0)
{ TGrains.ar(2, Impulse.ar(100), b, dur: 0.01, pan: Line.kr(-2, 2, 1)) }.plot(1.0)

TGrains wraps around at +-1. Pan2 clips.

This fixes both problems. I also couldn't resist fixing a typo in GrainBuf.

[timblechmann]

2-channel should clip, but more than 2 channel should wrap (line 6204)?

it is both inconsistent and may break existing pieces, relying on the behavior. maybe the documentation should reflect the wrap-around?

[nhthn]

There's a convention for granular ugens to mimic Pan2 for 2 channels and PanAz for more than 2. The way I see it, TGrains tried to implement that but flubbed the stereo math. Backward compatibility is, however, a valid concern.

[nhthn]

The inconsistency is deeper than I thought -- the GrainUGens (GrainIn, GrainFM, GrainSin, GrainBuf) also do not correctly emulate Pan2, since they fold around +-1 instead of wrapping or clipping.

[telephon]

In general, the two models of linear and circular panning are hard to resolve. Maybe someone has an idea what would be the clearest solution?

[timblechmann]

in general it is probably a good idea to unify the implementation, but the change should be communicated reasonably well.

cmake uses 'policies', so that the users can explicitly switch between old and new semantics in case of a breaking change. maybe supercollider could print a one-time warning from the class library (which could be silenced via a startup.scd file) for a few versions.

[nhthn]

Here's the behavior advertised in the GrainBuf helpfile:

• pan argument is ignored for 1 channel
• pan argument works exactly like Pan2 for 2 channels
• pan argument works exactly like PanAz for 3 or more channels

Even if it's not implemented correctly in any of the ugens in question, I think this is a good convention. (And while we're on the topic of mono, why does TGrains require at least 2 channels?)

[nhthn]

Overall the grain ugens are one of the sloppier areas in SC. I think we can aim for fixing them in the 3.9 milestone. (3.8 is cutting a little close IMO, especially for behavior changes.) Another problem that we might fix during this makeover is argument order. e.g. GrainBuf is numchannels, trigger, dur, bufnum, rate, pos, and TGrains is numchannels, trigger, bufnum, rate, pos. Might be too breaky though...

[timblechmann]

argument order will break a lot of code. might be better to introduce new classes, which only reorder the arguments. that allows a deprecation/transition period ... fwiw, a few years back there was a discussion about sc4, which could break compatibility and therefore allow fixing bugs/inconsistencies in the API of the class library ...

[nhthn]

I'm going to abandon this and work on another fix that unifies all the granular ugens.

[nhthn]

On second thought, I think this can be salvaged

[nhthn]

OK, this is ready to merge (after review of course). All the following ugens should now be working as described in #2230:

• GrainSin
• GrainBuf
• GrainIn
• GrainFM
• TGrains

and the docs have been updated as necessary.

[crucialfelix]

Before:

With this fix:

grainfm:

grainbuf:

grainsin:

[crucialfelix]

I agree with everybody else here that this is more correct.

This will break somebody's glitch masterpiece. I'm the kind of guy that would've had some noise that I had no idea how it got into that state, and then the update made it normal and I would get fussed about that.

We will make sure it's announced in the breaking changes.

[nhthn]

Thanks for taking the time to check my work. Where are we currently keeping track of all the breaking changes?

[vivid-synth]

@snappizz I don't know but I think that's an important question. We could start a file in this repo, a la Changelog

[nhthn]

This link is probably sufficient for tabulating the API changes: https://github.com/supercollider/supercollider/pulls?q=is%3Apr+label%3A%22API+change%22+is%3Aclosed