From f003ea48707d93a52ba7205f6d181670b867d529 Mon Sep 17 00:00:00 2001
From: Marek Ossowski <marek0ossowski@gmail.com>
Date: Sun, 3 Aug 2025 20:58:48 +0200
Subject: [PATCH] Added some comments

---
 app/src/main/java/xdsopl/robot36/Decoder.java |  3 ++
 .../main/java/xdsopl/robot36/Demodulator.java |  5 ++-
 app/src/main/java/xdsopl/robot36/Mode.java    | 34 +++++++++++++++++++
 .../java/xdsopl/robot36/Robot_72_Color.java   |  6 ++++
 4 files changed, 47 insertions(+), 1 deletion(-)

diff --git a/app/src/main/java/xdsopl/robot36/Decoder.java b/app/src/main/java/xdsopl/robot36/Decoder.java
index caeccd6..e131e52 100644
--- a/app/src/main/java/xdsopl/robot36/Decoder.java
+++ b/app/src/main/java/xdsopl/robot36/Decoder.java
@@ -405,6 +405,9 @@ public class Decoder {
 		return true;
 	}
 
+	/**
+	@return true if new lines present
+	 */
 	public boolean process(float[] recordBuffer, int channelSelect) {
 		boolean syncPulseDetected = demodulator.process(recordBuffer, channelSelect);
 		int syncPulseIndex = currentSample + demodulator.syncPulseOffset;
diff --git a/app/src/main/java/xdsopl/robot36/Demodulator.java b/app/src/main/java/xdsopl/robot36/Demodulator.java
index 2bf882a..a758472 100644
--- a/app/src/main/java/xdsopl/robot36/Demodulator.java
+++ b/app/src/main/java/xdsopl/robot36/Demodulator.java
@@ -66,7 +66,7 @@ public class Demodulator {
 		double centerFrequency = (lowestFrequency + highestFrequency) / 2;
 		baseBandOscillator = new Phasor(-centerFrequency, sampleRate);
 		double syncPulseFrequency = 1200;
-		syncPulseFrequencyValue = (float) ((syncPulseFrequency - centerFrequency) * 2 / scanLineBandwidth);
+		syncPulseFrequencyValue = (float) ((syncPulseFrequency - centerFrequency) * 2 / scanLineBandwidth); //converts to range from -1 to 1
 		syncPulseFrequencyTolerance = (float) (50 * 2 / scanLineBandwidth);
 		double syncPorchFrequency = 1500;
 		double syncHighFrequency = (syncPulseFrequency + syncPorchFrequency) / 2;
@@ -77,6 +77,9 @@ public class Demodulator {
 		baseBand = new Complex();
 	}
 
+	/**
+	 * @return true if sync pulse detected
+	 */
 	public boolean process(float[] buffer, int channelSelect) {
 		boolean syncPulseDetected = false;
 		int channels = channelSelect > 0 ? 2 : 1;
diff --git a/app/src/main/java/xdsopl/robot36/Mode.java b/app/src/main/java/xdsopl/robot36/Mode.java
index 3614711..36ae102 100644
--- a/app/src/main/java/xdsopl/robot36/Mode.java
+++ b/app/src/main/java/xdsopl/robot36/Mode.java
@@ -7,21 +7,55 @@ Copyright 2024 Ahmet Inan <xdsopl@gmail.com>
 package xdsopl.robot36;
 
 public interface Mode {
+	/**
+	 * @return mode name
+	 */
 	String getName();
 
+	/**
+	 * @return VIS code
+	 */
 	int getCode();
 
+	/**
+	 * @return image width
+	 */
 	int getWidth();
 
+	/**
+	 * @return image height
+	 */
 	int getHeight();
 
+	/**
+	 * @return number of samples from sync pulse to start of image data
+	 */
 	int getBegin();
 
+	/**
+	 * @return number of samples from start of scanline to sync pulse??? nonzero for Scottie only?
+	 */
 	int getFirstSyncPulseIndex();
 
+	/**
+	 * @return number of samples in a scanline
+	 */
 	int getScanLineSamples();
 
+	/**
+	 * Reset internal state.
+	 */
 	void reset();
 
+	/**
+	 * @param pixelBuffer buffer to store decoded pixels
+	 * @param scratchBuffer buffer for temporary data
+	 * @param scanLineBuffer raw samples to be decoded, can contain more than one scanline
+	 * @param scopeBufferWidth ??? used in RawDecoder, initializes width?
+	 * @param syncPulseIndex number of samples from array start to sync pulse
+	 * @param scanLineSamples number of samples per scanline
+	 * @param frequencyOffset correction of frequency of expected vs actual sync pulse (normalized to range (-1, 1))
+	 * @return true if scanline was decoded
+	 */
 	boolean decodeScanLine(PixelBuffer pixelBuffer, float[] scratchBuffer, float[] scanLineBuffer, int scopeBufferWidth, int syncPulseIndex, int scanLineSamples, float frequencyOffset);
 }
diff --git a/app/src/main/java/xdsopl/robot36/Robot_72_Color.java b/app/src/main/java/xdsopl/robot36/Robot_72_Color.java
index 88a9786..4374937 100644
--- a/app/src/main/java/xdsopl/robot36/Robot_72_Color.java
+++ b/app/src/main/java/xdsopl/robot36/Robot_72_Color.java
@@ -47,6 +47,12 @@ public class Robot_72_Color implements Mode {
 		lowPassFilter = new ExponentialMovingAverage();
 	}
 
+	/**
+	 * FIXME same in other modes (copy&paste)
+	 * @param frequency frequency, range (-1,1)
+	 * @param offset correction, range (-1,1)
+	 * @return pixel value, range (0,1)
+	 */
 	private float freqToLevel(float frequency, float offset) {
 		return 0.5f * (frequency - offset + 1.f);
 	}