diff --git a/doc/realearn/modules/ROOT/pages/best-practices.adoc b/doc/realearn/modules/ROOT/pages/best-practices.adoc index 12bc18661..9a52a1830 100644 --- a/doc/realearn/modules/ROOT/pages/best-practices.adoc +++ b/doc/realearn/modules/ROOT/pages/best-practices.adoc @@ -28,7 +28,7 @@ Describing your controller is optional but it brings benefits: * You can use xref:further-concepts/compartment-concepts.adoc#controller-preset[controller presets] either built-in ones or those made by other users ... and thereby save precious setup time. Or you can contribute them yourself! * You can make your xref:key-concepts.adoc#main-mapping[main mappings] independent of the actually used xref:key-concepts.adoc#controller[]. -This is done using xref:key-concepts.adoc#virtual-source[virtual sources] and xref:key-concepts.adoc#virtual-target[virtual targets]. +This is done using xref:further-concepts/source-concepts.adoc#virtual-source[virtual sources] and xref:further-concepts/target-concepts.adoc#virtual-target[virtual targets]. * It allows you to give your knobs, buttons etc. descriptive and friendly names instead of just e.g. "CC 15". * You don't need to learn your < again and again. Although the process of learning an element is easy in ReaLearn, it can take some time in case the xref:further-concepts/source-concepts.adoc#midi-source-character[] is not guessed correctly. @@ -39,14 +39,14 @@ If you want to make ReaLearn "learn" about your nice controller device, all you Let's first look at the "slow" way to do this - adding and editing each controller mapping one by one: . Press the xref:user-interface/main-panel/mappings-toolbar.adoc#add-one-button[]. -. Learn the xref:key-concepts.adoc#source[] by pressing the xref:user-interface/main-panel/mapping-row.adoc#row-learn-source-button[] and touching the control element. +. Learn the xref:key-concepts.adoc#source[] by pressing the xref:user-interface/main-panel/mapping-row.adoc#learn-source-button[] and touching the control element. . Press the xref:user-interface/main-panel/mapping-row.adoc#row-edit-button[]. . Enter a descriptive name for the xref:key-concepts.adoc#control-element[]. + TIP: This name will appear in many places so you want it to be short, clear and unique! -. Assign a unique xref:key-concepts.adoc#virtual-target[]. -** At this point we don't want to assign a xref:key-concepts.adoc#real-target[] yet. -The point of xref:further-concepts/compartment-concepts.adoc#controller-preset[controller presets] is to make them as reusable as possible, that's why we choose a xref:key-concepts.adoc#virtual-target[]. +. Assign a unique xref:further-concepts/target-concepts.adoc#virtual-target[]. +** At this point we don't want to assign a xref:further-concepts/target-concepts.adoc#real-target[] yet. +The point of xref:further-concepts/compartment-concepts.adoc#controller-preset[controller presets] is to make them as reusable as possible, that's why we choose a xref:further-concepts/target-concepts.adoc#virtual-target[]. ** In the _Category_ dropdown, choose _Virtual_. ** As _Type_, choose xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-button[] if your control element is a sort of button (something which you can press) or xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type-multi[] in all other cases. ** Use for each xref:key-concepts.adoc#control-element[] a unique combination of xref:further-concepts/compartment-concepts.adoc#virtual-control-element-type[] and xref:further-concepts/compartment-concepts.adoc#virtual-control-element-id[], starting with number *1* and counting. @@ -61,7 +61,7 @@ Or make an encoder generally slower or faster. Or you could simulate a rotary encoder by making two buttons on your controller act as -/+ buttons emitting relative values. This is possible by mapping them to the same xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] in xref:user-interface/mapping-panel/glue-section.adoc#incremental-button[]. -Before you go ahead and do that for each control element, you might want to check out what this is good for: Navigate back to the xref:key-concepts.adoc#main-compartment[], learn the xref:key-concepts.adoc#source[] of some xref:key-concepts.adoc#main-mapping[] and touch the xref:key-concepts.adoc#control-element[] that you have just mapped: Take note how ReaLearn will assign a xref:key-concepts.adoc#virtual-source[] this time, not a xref:source-types/category-midi.adoc[MIDI source]! +Before you go ahead and do that for each control element, you might want to check out what this is good for: Navigate back to the xref:key-concepts.adoc#main-compartment[], learn the xref:key-concepts.adoc#source[] of some xref:key-concepts.adoc#main-mapping[] and touch the xref:key-concepts.adoc#control-element[] that you have just mapped: Take note how ReaLearn will assign a xref:further-concepts/source-concepts.adoc#virtual-source[] this time, not a xref:source-types/category-midi.adoc[MIDI source]! It will also display the name of the xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] as source label. Now, let's say at some point you swap your xref:key-concepts.adoc#controller[] with another one that has a similar layout, all you need to do is to switch the xref:further-concepts/compartment-concepts.adoc#controller-preset[] and you are golden! diff --git a/doc/realearn/modules/ROOT/pages/further-concepts/compartment-concepts.adoc b/doc/realearn/modules/ROOT/pages/further-concepts/compartment-concepts.adoc index 83e8d5eac..0fafd7c64 100644 --- a/doc/realearn/modules/ROOT/pages/further-concepts/compartment-concepts.adoc +++ b/doc/realearn/modules/ROOT/pages/further-concepts/compartment-concepts.adoc @@ -1,4 +1,3 @@ - = Compartment concepts [[compartment-preset]] @@ -309,8 +308,8 @@ that can be reused with many different xref:key-concepts.adoc#controller[control The idea is simple: -1. You define a <> for a DAW controller, mapping each <> (e.g. its first fader, which emits MIDI CC7 messages) to a corresponding <> (e.g. named `ch1/fader`) by using a xref:key-concepts.adoc#virtual-target[]. -2. You define a <>, mapping each <> to some xref:key-concepts.adoc#real-target[] by using a xref:key-concepts.adoc#virtual-source[]. +1. You define a <> for a DAW controller, mapping each <> (e.g. its first fader, which emits MIDI CC7 messages) to a corresponding <> (e.g. named `ch1/fader`) by using a xref:further-concepts/target-concepts.adoc#virtual-target[]. +2. You define a <>, mapping each <> to some xref:further-concepts/target-concepts.adoc#real-target[] by using a xref:further-concepts/source-concepts.adoc#virtual-source[]. For example, you map `ch1/fader` to the xref:target-types/track-targets/track-set-volume.adoc#track-set-volume[] target. 3. ReaLearn creates a sort of wire between the xref:key-concepts.adoc#controller-compartment[] and the xref:key-concepts.adoc#main-compartment[]. So you can now control the track volume by moving the first fader. diff --git a/doc/realearn/modules/ROOT/pages/further-concepts/mapping-concepts.adoc b/doc/realearn/modules/ROOT/pages/further-concepts/mapping-concepts.adoc index 071cd36a3..8a77b06c1 100644 --- a/doc/realearn/modules/ROOT/pages/further-concepts/mapping-concepts.adoc +++ b/doc/realearn/modules/ROOT/pages/further-concepts/mapping-concepts.adoc @@ -1,4 +1,3 @@ - = Mapping concepts == Absolute vs. relative control @@ -179,7 +178,7 @@ Example: A track target can be invalid when it's using xref:further-concepts/tar In all other cases, mapping is *off* or *inactive*. In that case, it doesn't have any effect! -(Controller) mappings with xref:key-concepts.adoc#virtual-target[] are always considered active as long as the feedback checkbox is ticked. +(Controller) mappings with xref:further-concepts/target-concepts.adoc#virtual-target[] are always considered active as long as the feedback checkbox is ticked. [[mapping-signal-flow]] == Mapping signal flow @@ -263,7 +262,6 @@ Initially, they don't do anything at all. First, you need to give meaning to them by referring to them in activation conditions or `` selector expressions. ==== - === When modifiers on/off This mode is comparable to modifier keys on a computer keyboard. @@ -290,7 +288,6 @@ The beauty of this solution lies in how you can compose different ReaLearn featu For example, the _absolute mode_ of the mapping that controls the modifier parameter decides if the modifier button is momentary (has to be pressed all the time) or toggled (switches between on and off everytime you press it). You can also be more adventurous and let the modifier on/off state change over time, using REAPER's automation envelopes. - === When bank selected This is the correct activation mode if you want control surface "bank-style" mapping. @@ -326,7 +323,6 @@ With _Conditional activation_ you can do the same (and more) within just one Rea TIP: If you want to adjust the number of banks and improve bank handling in general, set a discrete value count for the corresponding bank parameter (see xref:further-concepts/compartment-concepts.adoc#compartment-parameter[]). - === When EEL met This is for experts. @@ -349,7 +345,6 @@ If you feel limited by the other activation modes, just use EEL. TIP: For most activation conditions which need this amount of freedom, the newer activation mode <> is a slightly better choice because it's easier to use and generally performs a bit better. [#expression-based-activation-condition] - === When expression met This is very similar to the previous EEL activation mode. @@ -360,7 +355,6 @@ The equivalent expression to above EEL example is: `p[0] > 0 && p[1] > 0` [#target-based-activation-condition] - === When target value met This is different from all the other activation condition types in that it doesn't look at ReaLearn's internal parameter values. diff --git a/doc/realearn/modules/ROOT/pages/further-concepts/source-concepts.adoc b/doc/realearn/modules/ROOT/pages/further-concepts/source-concepts.adoc index 83f4ba7b1..cec2f981d 100644 --- a/doc/realearn/modules/ROOT/pages/further-concepts/source-concepts.adoc +++ b/doc/realearn/modules/ROOT/pages/further-concepts/source-concepts.adoc @@ -1,5 +1,22 @@ = Source concepts +== Real vs. virtual sources + +We distinguish between _virtual_ and _real_ sources. + +[[virtual-source]] +=== Virtual source + +A _virtual_ source refers to a xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] and can only be used in the xref:key-concepts.adoc#main-compartment[]. + +Examples: `ch1/fader` + +[[real-source]] +=== Real source + +A _real_ source refers to a xref:further-concepts/compartment-concepts.adoc#real-control-element[]. + + [[midi-source-character]] == MIDI source character diff --git a/doc/realearn/modules/ROOT/pages/further-concepts/target-concepts.adoc b/doc/realearn/modules/ROOT/pages/further-concepts/target-concepts.adoc index 475542798..38933568f 100644 --- a/doc/realearn/modules/ROOT/pages/further-concepts/target-concepts.adoc +++ b/doc/realearn/modules/ROOT/pages/further-concepts/target-concepts.adoc @@ -1,6 +1,26 @@ = Target concepts +== Real vs. virtual targets + +We distinguish between _virtual_ and _real_ targets. + +[[virtual-target]] +=== Virtual target + +A _virtual_ target controls a xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] and can only be used in the xref:key-concepts.adoc#controller-compartment[]. + +Example: `ch1/fader` + +It's then picked up by a xref:further-concepts/source-concepts.adoc#virtual-source[]] in the xref:key-concepts.adoc#main-compartment[]. + +[[real-target]] +=== Real target + +All others targets are real. + +Examples: xref:target-types/track-targets/track-set-volume.adoc#track-set-volume[] + [[target-object-selectors]] == Target object selectors diff --git a/doc/realearn/modules/ROOT/pages/key-concepts.adoc b/doc/realearn/modules/ROOT/pages/key-concepts.adoc index dbbe6ba8f..0fbd7f38f 100644 --- a/doc/realearn/modules/ROOT/pages/key-concepts.adoc +++ b/doc/realearn/modules/ROOT/pages/key-concepts.adoc @@ -115,83 +115,44 @@ Each compartment contains a list of mappings. A _mapping_ connects a <> and/or <> on your <> with an action or parameter in REAPER. -=== Anatomy of a mapping - -Each mapping in ReaLearn consists of three elements: - -<>:: Describes the <> and/or <> on the <>. - -<>:: Something in REAPER that is to be controlled or provides feedback, such as track volume, cursor position or an action. - -<>:: A processor that sits between <> and <>, filtering and transforming <> and <> streams. +Each mapping consists of <>, <> and <>. [[source]] == Source -A _source_ is part of a <> and describes in most cases a <> and/or <> on a <>. -In a more general sense it can be anything that emits xref:further-concepts/mapping-concepts.adoc#control-value[control values]. - -We distinguish between <> and <>. - -[[virtual-source]] -=== Virtual source - -A _virtual_ source refers to a xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] and can only be used in the <>. - -Examples: `ch1/fader` - -[[real-source]] -=== Real source - -A _real_ source refers to a xref:further-concepts/compartment-concepts.adoc#real-control-element[]. +A _source_ is the part of a <> that typically describes a <> and/or <> on the <>. +More generally, it can be anything that emits xref:further-concepts/mapping-concepts.adoc#control-value[control values]. Examples: MIDI source, OSC source [[glue]] == Glue -A _glue_ is part of a <> and sits between the source and the target and filters or transforms control and feedback streams. +A _glue_ is the part of a <> that sits between <> and <>, filtering and transforming <> and <> streams. [[target]] == Target -A _target_ is part of a <> and represents something (mostly something in REAPER) that wants to be controlled and/or provides feedback. - -We distinguish between <> and <>. - -[[virtual-target]] -=== Virtual target - -A _virtual_ target controls a xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] and can only be used in the <>. - -Example: `ch1/fader` - -It's then picked up by a <> in the <>. - -[[real-target]] -=== Real target - -All others targets are real. +A _target_ is the part of the <> that describes the thing which should be controlled and/or provides feedback data. -Examples: xref:target-types/track-targets/track-set-volume.adoc#track-set-volume[] +Examples: Track volume, cursor position, REAPER action [[learning]] == Learning -This section can't be complete without mentioning the concept that inspired ReaLearn's name: _Learning_. -Learning simply means that you press a _Learn_ button instead of doing manual setup. -This can save a lot of time! +This section wouldn't be complete without mentioning the concept that inspired ReaLearn's name: _Learning_. +Learning simply means that you press a btn:[Learn] button instead of performing manual setup, saving you valuable time! In ReaLearn, you can learn <> and <>. [[learn-source]] === Learn source -Sources can be learned by pressing a source learn button and then touching a <> on your controller. +Sources can be learned by pressing the xref:user-interface/main-panel/mapping-row.adoc#learn-source-button[] and then touching a <> on your controller. This saves you from the tedious job of setting up MIDI or OSC sources manually. [[learn-target]] === Learn target -Targets can be learned by pressing a target learn button and then invoking a <> within REAPER. +Targets can be learned by pressing the xref:user-interface/main-panel/mapping-row.adoc#learn-target-button[] and then invoking a <> within REAPER. This saves you from choosing xref:further-concepts/target-concepts.adoc#target-object-selectors[] and other stuff manually. diff --git a/doc/realearn/modules/ROOT/pages/source-types/category-virtual.adoc b/doc/realearn/modules/ROOT/pages/source-types/category-virtual.adoc index 69c172955..0ec894388 100644 --- a/doc/realearn/modules/ROOT/pages/source-types/category-virtual.adoc +++ b/doc/realearn/modules/ROOT/pages/source-types/category-virtual.adoc @@ -1,6 +1,6 @@ = Virtual source -See xref:key-concepts.adoc#virtual-source[]. +See xref:further-concepts/source-concepts.adoc#virtual-source[]. == Type menu diff --git a/doc/realearn/modules/ROOT/pages/target-types/virtual-target.adoc b/doc/realearn/modules/ROOT/pages/target-types/virtual-target.adoc index 846fb69e5..55e4b8e2e 100644 --- a/doc/realearn/modules/ROOT/pages/target-types/virtual-target.adoc +++ b/doc/realearn/modules/ROOT/pages/target-types/virtual-target.adoc @@ -1,8 +1,8 @@ [[virtual-target-category]] = Virtual target -This is exactly the counterpart of the possible xref:key-concepts.adoc#virtual-source[virtual sources] in the xref:key-concepts.adoc#main-compartment[]. -Choosing a xref:key-concepts.adoc#virtual-target[] here is like placing cables between a xref:further-concepts/compartment-concepts.adoc#real-control-element[] and all corresponding main mappings that use this xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] as source. +This is exactly the counterpart of the possible xref:further-concepts/source-concepts.adoc#virtual-source[virtual sources] in the xref:key-concepts.adoc#main-compartment[]. +Choosing a xref:further-concepts/target-concepts.adoc#virtual-target[] here is like placing cables between a xref:further-concepts/compartment-concepts.adoc#real-control-element[] and all corresponding main mappings that use this xref:further-concepts/compartment-concepts.adoc#virtual-control-element[] as source. == Learnable checkbox diff --git a/doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-row.adoc b/doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-row.adoc index e26e806f2..3d49b975a 100644 --- a/doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-row.adoc +++ b/doc/realearn/modules/ROOT/pages/user-interface/main-panel/mapping-row.adoc @@ -41,12 +41,13 @@ Creates a new mapping just like this one right below. Removes this mapping from the list. -[[row-learn-source-button]] +[[learn-source-button]] == Learn source button Starts or stops learning the source of this mapping. See xref:key-concepts.adoc#learn-source[]. +[[learn-target-button]] == Learn target button Starts or stops learning the target of this mapping. diff --git a/doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/glue-section.adoc b/doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/glue-section.adoc index 71c6d3a41..1b5723015 100644 --- a/doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/glue-section.adoc +++ b/doc/realearn/modules/ROOT/pages/user-interface/mapping-panel/glue-section.adoc @@ -185,21 +185,19 @@ include::partial$glue/usage-dependent-effect.adoc[] |If min > 0 and <> is <>, button releases are ignored. Because this also affects {feedback}, it's usually better to use the <> instead! - |{velocity-sensitive-button} |{control} |Defines the observed velocity range, for example to react to only the lower velocity layer of a key press. - |{range-element} |{control} -|Defines the observed value range. For example to react only to the upper half of a fader. +|Defines the observed value range. +For example to react only to the upper half of a fader. |{led} |{feedback} |On many controllers which support colored LEDs, *Min* sets the *off* color and *Max* sets the *on* color. - |{value-indicator} |{feedback} |Sets the lowest/highest indicated value. @@ -293,7 +291,7 @@ It somewhat resembles takeover mode <> but has important - It's guaranteed that a full fader/knob swipe from 0% to 100% always results in a swipe over the full target range (assuming the target was at 0% initially). - It doesn't need to know the current target value. -Which means it also works for mappings with xref:key-concepts.adoc#virtual-target[virtual targets]. +Which means it also works for mappings with xref:further-concepts/target-concepts.adoc#virtual-target[virtual targets]. [[performance-control]] Performance control:: This mode emulates the behavior of a typical soft synth modulation matrix mapping: It uses the target value that has been set in REAPER (not via this ReaLearn mapping) as an offset and starts changing it from there. @@ -471,7 +469,6 @@ include::partial$glue/usage-dependent-effect.adoc[] |=== - [#speed-min-max] == Speed Min/Max controls