whitespace change to test commit hook

[ardour-manual] / include / osc58-querying-ardour.html

diff --git a/include/osc58-querying-ardour.html b/include/osc58-querying-ardour.html
index d112a2f6ad45ea61e6f42c84364495c59815ba89..c94ec1009810981b6beec4a83cc4d69253bc033f 100644 (file)
--- a/include/osc58-querying-ardour.html
+++ b/include/osc58-querying-ardour.html
@@ -5,7 +5,7 @@
   information. These set of commands are for smarter control surfaces
   That have the logic to figure out what to do with the information.
   These are not of value for mapped controllers like touchOSC and
-  friends. The controller will need to send these queries to ardour
+  friends. The controller will need to send these queries to Ardour
   as often as it needs this information. It may well make sense to use
   regular feedback for things that need to be updated often such as
   position or metering.
@@ -25,6 +25,8 @@
   <td>Asks for a list of descriptors for plug-in <em>piid</em> on strip <em>ssid</em></td></tr>
   <tr><th><kbd class="osc">/set_surface</kbd></th>
   <td>Ask for the current surface setting. Reply is in the same form as setting the surface would be.</td></tr>
+  <tr><th><kbd class="osc">/surface/list</kbd></th>
+  <td>Print a list of known surfaces and Link Sets to the log window.</td></tr>
 </table>
 
 <h3>A list of strips</h3>
@@ -40,7 +42,7 @@
                <li>MT - MIDI Track</li>
                <li>B - Audio Bus</li>
                <li>MB - MIDI bus</li>
-               <li>AX - Aux bus</li>
+               <li>FB - Foldback bus</li>
                <li>V - VCA</li>
     </ul>
     <li>Strip name</li>
@@ -70,11 +72,11 @@
   if the strips have changed. This would be true if a strip gets moved, created or
   deleted. When this happens Ardour sends <code>/strip/list</code> to the surfaces
   that have previously requested a <code>/strip/list</code>. This lets the
-  surface know that it's list of strips is no longer valid.
+  surface know that its list of strips is no longer valid.
 </p>
 <p class="note">A bus will not have a record enable and so a bus message
   will have one less parameter than a track. It is the controllers
-  responsability to deal with this.
+  responsibility to deal with this.
 </p>
 
 <h3>A list of sends</h3>
@@ -89,7 +91,7 @@
       <li>The send's target bus ssid</li>
       <li>The send's target bus name</li>
       <li>The send id for this strip</li>
-      <li>The send gain as a fader possition</li>
+      <li>The send gain as a fader position</li>
       <li>The Send's enable state</li>
     </ul>
   </ul>
@@ -104,13 +106,13 @@
 <p>
   <code>/strip/receives <em>ssid</em></code> will return a list of
   tracks that have sends to the bus at the ssid. The reply will
-  contain the following information for each track conntected to this
+  contain the following information for each track connected to this
   bus:
   <ul>
     <li>The ssid of the track sending</li>
     <li>The name of the sending track</li>
     <li>The id of the send at that track</li>
-    <li>It's gain in fader possition</li>
+    <li>It's gain in fader position</li>
     <li>The send's enable state</li>
   </ul>
 </p>
@@ -132,17 +134,17 @@
 
 <h3>A list of a plug-in's parameters</h3>
 <p>
-  <code>/plugin/descriptor <em>ssid</em> <em>piid</em></code> will
+  <code>/strip/plugin/descriptor <em>ssid</em> <em>piid</em></code> will
   return the plug-in parameters for ppid plug-in on the ssid strip. The
-  reply will contain the following information:
+  reply will be sent as a number of messages, one for each parameter.
+  Each message will contain the following information:
   <ul>
     <li>Ssid of the strip the plug-in is in</li>
     <li>The plug-in id for the plug-in</li>
-    <li>The plug-in's name</li>
-    <li>Information about each parameter</li>
+    <li>The plug-in parameter id for the plug-in</li>
+    <li>The plug-in parameter's name</li>
+    <li>Information about that parameter:</li>
     <ul>
-      <li>The parameter id</li>
-      <li>The parameter's name</li>
       <li>A bitset of flags (see below)</li>
       <li>Data type</li>
       <li>Minimum value</li>
@@ -153,18 +155,27 @@
     </ul>
   </ul>
 </p>
+<p>
+       After all the parameters have been sent this way, one final message"
+       <code>/strip/plugin/descriptor_end</code> is sent with these parameters:
+       <ul>
+         <li>Ssid of the strip the plugin is in</li>
+         <li>The plug-in id for the plug-in</li>
+       </ul>
+</p>
 <p>
   The flag bitset above has been defined as (from lsb):
   <ul>
     <li>0&mdash;enumeration</li>
     <li>1&mdash;integer step</li>
     <li>2&mdash;logarithmic</li>
-    <li>3&mdash;max unbound</li>
-    <li>4&mdash;min unbound</li>
     <li>5&mdash;sample rate dependent</li>
     <li>6&mdash;toggled</li>
     <li>7&mdash;controllable</li>
+    <li>8&mdash;hidden</li>
   </ul>
+  Bits 3 and 4 are not used, they were max unbound and min unbound in
+  previous versions and always zero.
 </p>
 <p>
        While this seems complex, it is really not that bad. Minimum,
@@ -172,4 +183,21 @@
        access to plug-ins, the /select/plugin/ set of commands will handle most
        needs.
 </p>
+<h3>Obtaining a list of surfaces Ardour knows about</h3>
+<p>
+       Ardour can work with more than one OSC control surface at a time.
+       Sometimes it is useful to know the information stored about all
+       surfaces. Sending <code>/surface/list</code> from any surface or selecting:
+       <kbd class="menu">Print surface information to Log window</kbd> from
+       the <kbd class="menu">Debug</kbd> dropdown in the OSC setup dialog,
+       will list all the information Ardour uses to calculate the feedback
+       it sends. The Log window can be opened from the menu with
+       <kbd class="option">Window &gt; Log</kbd>.
+       This would be useful information to include with any OSC
+       related Bug report. The output is printed in this format:
+</p>
+<p>
+<img alt="Surface Output"
+     src="/images/osc-surface-log.png">
+</p>