From a1bf7ca25f24780ced5b72bf0438caa5eccb2298 Mon Sep 17 00:00:00 2001
From: vlazzarini <victor.lazzarini@mu.ie>
Date: Wed, 20 Mar 2024 09:48:18 +0000
Subject: [PATCH] added undersample page and corrected oversample text

---
 manual.xml              |  1 +
 opcodes/oversample.xml  | 19 ++++++------
 opcodes/top.xml         |  3 +-
 opcodes/undersample.xml | 69 +++++++++++++++++++++++++++++++++++++++++
 4 files changed, 82 insertions(+), 10 deletions(-)
 create mode 100644 opcodes/undersample.xml

diff --git a/manual.xml b/manual.xml
index fb4e16712f..05b46f62ee 100644
--- a/manual.xml
+++ b/manual.xml
@@ -1027,6 +1027,7 @@
 <!ENTITY opcodesoutx SYSTEM "opcodes/outx.xml">
 <!ENTITY opcodesoutz SYSTEM "opcodes/outz.xml">
 <!ENTITY opcodesoversample SYSTEM "opcodes/oversample.xml">
+<!ENTITY opcodesundersample SYSTEM "opcodes/undersample.xml">
 <!ENTITY opcodesp5gconnect SYSTEM "opcodes/p5gconnect.xml">
 <!ENTITY opcodesp5gdata SYSTEM "opcodes/p5gdata.xml">
 <!ENTITY opcodespan SYSTEM "opcodes/pan.xml">
diff --git a/opcodes/oversample.xml b/opcodes/oversample.xml
index 249fb39e82..bdcf80f409 100644
--- a/opcodes/oversample.xml
+++ b/opcodes/oversample.xml
@@ -9,14 +9,14 @@
   <refnamediv>
     <refname>oversample</refname>
     <refpurpose>
-      Sets a local sampling rate based on an oversampling factor.
+      Sets a higher local sampling rate based on an oversampling factor.
     </refpurpose>
   </refnamediv>
 
   <refsect1>
     <title>Description</title>
     <para>
-      Sets the local ksmps value in an instrument or user-defined opcode block.
+      Sets the local sampling rate value in a user-defined opcode block.
     </para>
   </refsect1>
 
@@ -30,23 +30,24 @@
     <para>
       <emphasis>ifactor</emphasis> -- sets the oversampling factor. It
       needs to be a positive integer > 1. A factor of 1 is a non-op,
-      zero or negative factors are illegal.
+      zero or negative factors are illegal. The local sampling rate is
+      set as ifactor * sr. The value of the sr variable is then
+      changed locally. Local kr is also changed accordingly, local
+      ksmps remains unchanged.
     </para>
     <para>
       <emphasis>imode</emphasis> -- oversampling mode: if Secret
       Rabbit Code is used, then 0 - best quality sync (default); 1 - medium
       quality sync; 2 - fast sync; 3 - zero-order hold; and  4 - linear.
     </para>
-    <para>
-      If <emphasis>iksmps</emphasis> is set to zero, the <emphasis>ksmps</emphasis> of the caller instrument or opcode is used (this is the default behavior).
-    </para>
 
     <note>
       <title>Note</title>
       <para>
-        Oversampling is not allowed with local ksmps. The opcode can
-        only be used in UDOs. Audio or control rate array arguments
-        are not allowed. Global variables or bus channels should not be used.
+        Calling this opcode in the same UDO as setksmps is not
+        allowed. The opcode can only be used in UDOs. Audio or control rate array arguments
+        are not allowed. Global variables or bus channels should not
+        be used. 
       </para>
     </note>
   </refsect1>
diff --git a/opcodes/top.xml b/opcodes/top.xml
index 3e9a42d394..77fab2ee6d 100644
--- a/opcodes/top.xml
+++ b/opcodes/top.xml
@@ -793,7 +793,7 @@
   &opcodesoutvalue;
   &opcodesoutx;
   &opcodesoutz;
-   &opcodesoversample;
+  &opcodesoversample;
   &opcodesp5gconnect;
   &opcodesp5gdata;
   &opcodesp;
@@ -1240,6 +1240,7 @@
   &opcodesturnoff3;
   &opcodesturnon;
   &opcodestvconv;
+  &opcodesundersample;
   &opcodesunirand;
   &opcodesuntil;
   &opcodesunwrap;
diff --git a/opcodes/undersample.xml b/opcodes/undersample.xml
new file mode 100644
index 0000000000..9c165873af
--- /dev/null
+++ b/opcodes/undersample.xml
@@ -0,0 +1,69 @@
+
+<refentry id="undersample">
+<indexterm id="IndexUndersample"><primary>undersample</primary></indexterm>
+  <refentryinfo><title>Signal I/O:Software Bus</title></refentryinfo>
+  <refmeta>
+    <refentrytitle>undersample</refentrytitle>
+  </refmeta>
+
+  <refnamediv>
+    <refname>undersample</refname>
+    <refpurpose>
+      Sets a lower local sampling rate based on an undersampling factor.
+    </refpurpose>
+  </refnamediv>
+
+  <refsect1>
+    <title>Description</title>
+    <para>
+      Sets the local sampling rate value in a user-defined opcode block.
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Syntax</title>
+    <synopsis><command>undersample</command> ifactor[,imode] </synopsis>
+  </refsect1>
+
+  <refsect1>
+    <title>Initialization</title>
+    <para>
+      <emphasis>ifactor</emphasis> -- sets the undersampling factor. It
+      needs to be a positive integer > 1. A factor of 1 is a non-op,
+      zero or negative factors are illegal. The local sampling rate is
+      set as (1/ifactor) * sr. The value of the sr variable is then
+      changed locally. Local ksmps is also changed accordingly.
+    </para>
+    <para>
+      <emphasis>imode</emphasis> -- resampling mode: if Secret
+      Rabbit Code is used, then 0 - best quality sync (default); 1 - medium
+      quality sync; 2 - fast sync; 3 - zero-order hold; and  4 - linear.
+    </para>
+
+    <note>
+      <title>Note</title>
+      <para>
+        Calling this opcode in the same UDO as setksmps is not
+        allowed.
+        The opcode can only be used in UDOs. Audio or control rate array arguments
+        are not allowed. Global variables or bus channels should not be used.
+      </para>
+    </note>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <link linkend="endop"><citetitle>endop</citetitle></link>, 
+      <link linkend="opcode"><citetitle>opcode</citetitle></link>, 
+      <link linkend="xin"><citetitle>xin</citetitle></link>, 
+      <link linkend="xout"><citetitle>xout</citetitle></link>
+    </para>
+  </refsect1>
+
+  <refsect1>
+    <title>Credits</title>
+    <para>Author: Victor Lazzarini</para>
+    <para>New in version 7.0</para>
+  </refsect1>
+</refentry>