Re: Purpose of fswapin

On Sun, Apr 25, 2021 at 12:39:24PM -0700, Hydro Flask wrote:
> Hello,
> 
> I stumbled across midish while needing a quick and dirty way to split my
> MIDI keyboard into two channels live. I found it linked from this site: https://askubuntu.com/questions/675470/how-to-do-advanced-midi-keyboard-routing
> 
> Since then I've been using it for increasingly more tasks and it's been
> delightful. I usually go to Python for these types of tasks but when it
> comes to routing MIDI events in real-time, I like the idea that the main
> loop is native code.
> 

Hi,

Yeah, that's its main purpose

> Anyway, my question concerns fswapin. What is the purpose of this function?
> I did not understand the blurb in the documentation:
> 
>     Similar to fchgin but swap ``evspec1'' and ``evspec2'' in the source
> events set of each rule.
> 
> So I dug into the source and found the essential difference between fswapin
> and fchgin here:
> 
>     /* in filt_chgin() */
>     if (evspec_in(&s->es, from)) {
>         evspec_map(&s->es, from, to, &newspec);
>     } else if (swap && evspec_in(&s->es, to)) {
>         evspec_map(&s->es, to, from, &newspec);
>     } else {
>         newspec = s->es;
>     }
> 
> What it seems like on cursory glance is that it's intending to be like
> fchgin except it interprets the arguments in reverse order. On its own that
> doesn't seem like justification enough to add a new function. Indeed it
> doesn't just do that, it first checks that the source evspec of the filter
> rules is contained in the "from" evspec of the function, just like fchgin,
> and then maps in that direction.
> 
> So I understand what it's doing but now my question is why would one need
> that? Thank you.


Basically, its the filter equivalent of swapping two integers: to swap
x and y we need a temporary variable and 3 steps:

	t = x
	x = y
	y = t 

The purpose of fswapin is to do it in a signle step for filters. It's
to swap (exchange) two input patterns of a filter. For instance,
consider this very simple filter:

	any {1 0} > any {0 4}
	any {2 0} > any {0 5}

it routes channel 0 of two devices to channels 4 and 5 of another. To
excange the inputs you need to replace "any {1 0}" by "any {2 0}"
*AND* replace "any {2 0}" by "any {1 0}". Without fswapin we'd need a
temporary (unused) input and 3 steps:

	fchgin {any {1 0}} {any {9 0}}
	fchgin {any {2 0}} {any {1 0}}
	fchgin {any {9 0}} {any {2 0}}

With fswapin it's done in a single step, without having to use a
temporary (unused) channel:

	fswapin {any {1 0}} {any {2 0}}

This command is practical when swapping MIDI cables or opening an old
midish project that's using different MIDI device/channel/controller
setup.

The doc (and help strings) need some love, definetely.