From 4cfccb078542ae09bb614632605c5e95487a9903 Mon Sep 17 00:00:00 2001
From: MotoLegacy <motolegacy@proton.me>
Date: Sat, 10 May 2025 11:55:02 -0700
Subject: [PATCH] Document and explicitly declare right analog stick input;
 display right analog stick in controller sample

---
 Doxyfile                            |  2 +-
 src/ctrl/pspctrl.h                  | 23 +++++++++++++++++++++--
 src/samples/controller/basic/main.c | 17 +++++++++++++++--
 3 files changed, 37 insertions(+), 5 deletions(-)

diff --git a/Doxyfile b/Doxyfile
index 948cc9fa..b888471d 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -2373,7 +2373,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = __attribute__(x)=
+PREDEFINED             = DOXYGEN_SHOULD_SKIP_THIS __attribute__(x)=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
diff --git a/src/ctrl/pspctrl.h b/src/ctrl/pspctrl.h
index 80d3150a..149c87a9 100644
--- a/src/ctrl/pspctrl.h
+++ b/src/ctrl/pspctrl.h
@@ -134,8 +134,27 @@ typedef struct SceCtrlData {
 	unsigned char 	Lx;
 	/** Y-axis value of the Analog Stick.*/
 	unsigned char 	Ly;
-	/** Reserved. */
-	unsigned char 	Rsrv[6];
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+	union {
+		struct {
+#endif // DOXYGEN_SHOULD_SKIP_THIS
+			/** X-axis value of the right Analog Stick, valid when using DualShock 3 on PSP GO, 
+			 * 	a PS VITA system, through hardware/software hacking, or system emulation. */
+			unsigned char Rx;
+			/** Y-axis value of the right Analog Stick, valid when using DualShock 3 on PSP GO, 
+			 * 	a PS VITA system, through hardware/software hacking, or system emulation. */
+			unsigned char Ry;
+			/** Reserved bytes unused by the firmware. */
+			unsigned char Reserved[4];
+		};
+		/** 
+		 * @private
+		 * Reserved bytes. This is deprecated with the implementation of Rx and Ry and only here for backwards compatibility. 
+		 */
+		unsigned char Rsrv[6];
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+	};
+#endif // DOXYGEN_SHOULD_SKIP_THIS
 } SceCtrlData;
 
 /** 
diff --git a/src/samples/controller/basic/main.c b/src/samples/controller/basic/main.c
index 1ea8f72f..e1a95749 100644
--- a/src/samples/controller/basic/main.c
+++ b/src/samples/controller/basic/main.c
@@ -75,8 +75,21 @@ int main(void)
 
 		sceCtrlReadBufferPositive(&pad, 1);
 
-		pspDebugScreenPrintf("Analog X = %3d ", pad.Lx);
-		pspDebugScreenPrintf("Analog Y = %3d \n", pad.Ly);
+		// 10 May 2025
+		// ---
+		// Depending on the configuration of the device the
+		// sample is being ran on, it may support a second
+		// analog stick. Known instances of this are:
+		// 1. On a PSP GO system with a connected DualShock 3
+		// 2. On a PS VITA system
+		// 3. On the PPSSPP emulator if bound in configuration settings
+		// 4. Through hardware or software modification (see https://github.com/operation-ditto)
+		// Due to these instances we should also report the second
+		// stick to the screen.
+		pspDebugScreenPrintf("L Analog X = %3d \n", pad.Lx);
+		pspDebugScreenPrintf("L Analog Y = %3d \n", pad.Ly);
+		pspDebugScreenPrintf("R Analog X = %3d \n", pad.Rx);
+		pspDebugScreenPrintf("R Analog Y = %3d \n", pad.Ry);
 
 		if (pad.Buttons != 0){
 			if (pad.Buttons & PSP_CTRL_SQUARE){