server plugins: Unify panning behavior of granular ugens #2136

nhthn · 2016-05-28T19:36:34Z

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 · 2016-05-28T19:55:57Z

server/plugins/DelayUGens.cpp

@@ -6210,7 +6210,7 @@ void TGrains_next(TGrains *unit, int inNumSamples)
 				if (grain->chan >= (int)numOutputs) grain->chan -= numOutputs;
 			} else {
 				grain->chan = 0;
-				pan = sc_wrap(pan * 0.5f + 0.5f, 0.f, 1.f);
+				pan = sc_clip(pan * 0.5f + 0.5f, 0.f, 1.f);


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?

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 · 2016-05-28T21:00:09Z

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 · 2016-05-28T21:18:23Z

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 · 2016-05-28T21:33:07Z

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 · 2016-05-28T21:40:28Z

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 · 2016-05-29T00:00:33Z

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 · 2016-05-29T10:00:15Z

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 · 2016-06-27T18:42:01Z

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

nhthn · 2016-07-14T05:55:54Z

On second thought, I think this can be salvaged

nhthn · 2016-08-07T00:52:31Z

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 · 2016-08-23T13:24:52Z

Before:

With this fix:

grainfm:

grainbuf:

grainsin:

crucialfelix · 2016-08-23T13:30:38Z

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 · 2016-08-23T19:03:23Z

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

vivid-synth · 2016-09-12T14:21:41Z

@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 · 2016-09-12T16:35:48Z

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

Nathan Ho added 3 commits May 28, 2016 12:27

TGrains: use clip instead of wrap for stereo

2d8564f

TGrains: document stereo pan behavior

204619f

fix a typo in GrainBuf while we're at it

1b43e0d

timblechmann reviewed May 28, 2016
View reviewed changes

nhthn added waiting for consensus comp: server plugins labels May 28, 2016

crucialfelix added this to the 3.8 milestone May 30, 2016

nhthn added Work In Progress (WIP) - don't merge yet and removed waiting for consensus labels Jun 27, 2016

nhthn closed this Jun 27, 2016

nhthn mentioned this pull request Jul 14, 2016

Inconsistent panning behavior of Grain ugens #2230

Closed

nhthn reopened this Jul 14, 2016

nhthn changed the title ~~Fix documentation and behavior of TGrains when numChannels = 2~~ Unify panning behavior of granular ugens Jul 14, 2016

nhthn changed the title ~~Unify panning behavior of granular ugens~~ server plugins: Unify panning behavior of granular ugens Jul 14, 2016

Nathan Ho added 3 commits July 13, 2016 23:35

server plugins: GrainUGens: handle numChannels == 2 correctly

722dbef

server plugins: TGrains: allow numChannels == 1

f35a3f7

help: TGrains: add info about mono support

4c6c26f

nhthn removed the Work In Progress (WIP) - don't merge yet label Aug 7, 2016

crucialfelix added the API change label Aug 23, 2016

crucialfelix merged commit aa77ac7 into supercollider:master Aug 23, 2016

nhthn mentioned this pull request Aug 23, 2016

BhobUGens: use standard panning behavior for TGrains2, TGrains3 supercollider/sc3-plugins#111

Merged

This was referenced Mar 21, 2017

TGrains amp argument has no effect #2807

Closed

Fix broken TGrains amp handling #2809

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

server plugins: Unify panning behavior of granular ugens #2136

server plugins: Unify panning behavior of granular ugens #2136

nhthn commented May 28, 2016 •

edited by crucialfelix

Loading

timblechmann May 28, 2016

nhthn May 28, 2016 via email

nhthn commented May 28, 2016 •

edited

Loading

telephon commented May 28, 2016

timblechmann commented May 28, 2016

nhthn commented May 28, 2016

nhthn commented May 29, 2016 via email

timblechmann commented May 29, 2016

nhthn commented Jun 27, 2016

nhthn commented Jul 14, 2016

nhthn commented Aug 7, 2016 •

edited

Loading

crucialfelix commented Aug 23, 2016

crucialfelix commented Aug 23, 2016

nhthn commented Aug 23, 2016 •

edited

Loading

vivid-synth commented Sep 12, 2016

nhthn commented Sep 12, 2016

server plugins: Unify panning behavior of granular ugens #2136

server plugins: Unify panning behavior of granular ugens #2136

Conversation

nhthn commented May 28, 2016 • edited by crucialfelix Loading

timblechmann May 28, 2016

Choose a reason for hiding this comment

nhthn May 28, 2016 via email

Choose a reason for hiding this comment

nhthn commented May 28, 2016 • edited Loading

telephon commented May 28, 2016

timblechmann commented May 28, 2016

nhthn commented May 28, 2016

nhthn commented May 29, 2016 via email

timblechmann commented May 29, 2016

nhthn commented Jun 27, 2016

nhthn commented Jul 14, 2016

nhthn commented Aug 7, 2016 • edited Loading

crucialfelix commented Aug 23, 2016

crucialfelix commented Aug 23, 2016

nhthn commented Aug 23, 2016 • edited Loading

vivid-synth commented Sep 12, 2016

nhthn commented Sep 12, 2016

nhthn commented May 28, 2016 •

edited by crucialfelix

Loading

nhthn commented May 28, 2016 •

edited

Loading

nhthn commented Aug 7, 2016 •

edited

Loading

nhthn commented Aug 23, 2016 •

edited

Loading