From feccde41bf4975932dee619e361502652d6fdc9e Mon Sep 17 00:00:00 2001
From: unknown <rmacri@users.noreply.github.com>
Date: Mon, 30 Mar 2015 17:27:51 +0900
Subject: [PATCH] rename SAM to DAC functions

---
 source/Memory.cpp |  2 +-
 source/SAM.cpp    | 48 +++++++++++++++++++++++++++++------------------
 source/SAM.h      |  2 +-
 3 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/source/Memory.cpp b/source/Memory.cpp
index 6de3a3c7..128ed68b 100644
--- a/source/Memory.cpp
+++ b/source/Memory.cpp
@@ -1297,7 +1297,7 @@ void MemInitialize()
 	}
         else
          if (g_Slot5 == CT_SAM)
-          ConfigureDAC(pCxRomPeripheral, 5);		// $C500 : Z80 card
+          ConfigureSAM(pCxRomPeripheral, 5);		// $C500 : Z80 card
 
 	DiskLoadRom(pCxRomPeripheral, 6);				// $C600 : Disk][ f/w
 	HD_Load_Rom(pCxRomPeripheral, 7);				// $C700 : HDD f/w
diff --git a/source/SAM.cpp b/source/SAM.cpp
index 23db1dc2..eb2d9790 100644
--- a/source/SAM.cpp
+++ b/source/SAM.cpp
@@ -42,13 +42,21 @@
 //
 
 
-static BYTE __stdcall IOWrite_DAC(WORD pc,  WORD addr, BYTE bWrite, BYTE d, ULONG nCyclesLeft)
+static BYTE __stdcall IOWrite_SAM(WORD pc,  WORD addr, BYTE bWrite, BYTE d, ULONG nCyclesLeft)
 {
- // Emulate audio from an 8 bit DAC
- // only if using wave data
- // uses the existing speaker for the timing but then
- // substitutes the analog data which gets subsequently
- // sent to audio out
+ // Emulate audio from a SAM / 8 bit DAC card
+ // Only supportable if AppleWin is using WAVE output
+ //
+ // This works by using the existing speaker handling but then 
+ // replacing the speaker audio with the 8 bit samples from the DAC
+ // before they get sent out to the soundcard buffer, whilst
+ // audio samples are being written to the SAM.
+ //
+ // Whilst very unusual, it is possible to intermingle use of SAM and the apple
+ // speaker. This is crudely supported with g_quieterSpeaker making the Apple
+ // speaker produce quieter clicks which will be crudely intermingled
+ // with the SAM data. The mute gets reset after the speaker code detects
+ // silence.
 
  byte mb_res;
 
@@ -57,20 +65,24 @@ static BYTE __stdcall IOWrite_DAC(WORD pc,  WORD addr, BYTE bWrite, BYTE d, ULON
    // use existing speaker code to bring timing up to date
    mb_res = SpkrToggle(pc, addr, bWrite, d, nCyclesLeft);
 
-   // 8 bit card      WAV driver (scaled by 256)
-   //  0xFF 255       0x7f  127
-   //  0x80 128       0x00    0
-   //  0x7f 127       0xFF   -1
-   //  0x00  0        0x80 -128
-   
-   // replace regular speaker output with 8 bit DAC value
-   // regular speaker data still audible but quieter until speaker
-   // goes idle (so both work simultaneously)
+   // The DAC in the SAM uses unsigned 8 bit samples
+   // The WAV data that g_nSpeakerData is loaded into is a signed short
+   //
+   // We convert unsigned 8 bit to signed by toggling the most significant bit
+   // 
+   //  SAM card     WAV driver           SAM WAV
+   //  0xFF 255     0x7f  127      _      FF  7F 
+   //  0x81 129     0x01    1     / \
+   //  0x80 128     0x00    0    /   \   /80  00
+   //  0x7f 127     0xFF   -1         \_/
+   //  0x00   0     0x80 -128             00  80
+   //                                                        
+   // SAM is 8 bit, PC WAV is 16 so shift audio to the MSB (<< 8)
 
    g_nSpeakerData = (d ^ 0x80) << 8;
 
    // make speaker quieter so eg: a metronome click through the
-   // Apple speaker is softer vs. the analogue SAM output
+   // Apple speaker is softer vs. the analogue SAM output.
    g_quieterSpeaker = 1;
   }
  else
@@ -79,7 +91,7 @@ static BYTE __stdcall IOWrite_DAC(WORD pc,  WORD addr, BYTE bWrite, BYTE d, ULON
  return mb_res;
 }
 
-void ConfigureDAC(LPBYTE pCxRomPeripheral, UINT uSlot)
+void ConfigureSAM(LPBYTE pCxRomPeripheral, UINT uSlot)
 {	
- RegisterIoHandler(uSlot,IO_Null,IOWrite_DAC,IO_Null,IO_Null, NULL, NULL);
+ RegisterIoHandler(uSlot,IO_Null,IOWrite_SAM,IO_Null,IO_Null, NULL, NULL);
 }
diff --git a/source/SAM.h b/source/SAM.h
index ffaa6f33..3c980edb 100644
--- a/source/SAM.h
+++ b/source/SAM.h
@@ -1,2 +1,2 @@
 // SAM speech card (8 bit DAC):
-void ConfigureDAC(LPBYTE pCxRomPeripheral, UINT uSlot);
+void ConfigureSAM(LPBYTE pCxRomPeripheral, UINT uSlot);