padscore: Add KPADSetSamplingCallback, WENCGetEncodeData and documentation improvements (#411)

* Add `WENCGetEncodeData`

* `const` and out

* WPADInfo changes

* WPADInfo changes

* Add `KPADSetSamplingCallback`

* Miscellaneous comment changes

include/padscore/kpad.h

@@ -338,6 +338,7 @@ WUT_CHECK_OFFSET(KPADUnifiedWpadStatus, 0x40, format);
 WUT_CHECK_SIZE(KPADUnifiedWpadStatus, 0x44);
 
 typedef WPADConnectCallback KPADConnectCallback;
+typedef WPADSamplingCallback KPADSamplingCallback;
 
 //! Callback used for `KPADSetControlMplsCallback()`.
 typedef void (*KPADControlMplsCallback)(KPADChan chan, KPADControlMplsStatus status);
@@ -461,6 +462,13 @@ KPADConnectCallback
 KPADSetConnectCallback(KPADChan chan,
                        KPADConnectCallback callback);
 
+/**
+ * Same usage as \link WPADSetSamplingCallback\endlink, except compatible with other KPAD functions
+ */
+KPADSamplingCallback
+KPADSetSamplingCallback(KPADChan channel,
+                        KPADSamplingCallback callback);
+
 /**
  * Returns the amount of memory needed for `KPADSetMplsWorkarea()`.
  */

include/padscore/wpad.h

@@ -34,6 +34,7 @@ typedef struct WPADStatusMotionPlus WPADStatusMotionPlus;
 typedef struct WPADStatusBalanceBoard WPADStatusBalanceBoard;
 typedef struct WPADStatusTrain WPADStatusTrain;
 typedef WPADStatusProController WPADStatusPro;
+typedef struct WENCParams WENCParams;
 
 typedef enum WPADError
 {
@@ -689,11 +690,11 @@ WUT_CHECK_SIZE(WPADStatusTrain, 0x2e);
 //! Controller status info
 struct WPADInfo
 {
-   uint32_t irEnabled;
-   uint32_t speakerEnabled;
-   uint32_t extensionAttached;
-   uint32_t batteryLow;
-   uint32_t batteryNearEmpty;
+   BOOL irEnabled;
+   BOOL speakerEnabled;
+   BOOL extensionAttached;
+   BOOL batteryLow;
+   BOOL speakerBufNearEmpty;
    uint8_t  batteryLevel;
    uint8_t  led;
    uint8_t  protocol;
@@ -703,7 +704,7 @@ WUT_CHECK_OFFSET(WPADInfo, 0x00, irEnabled);
 WUT_CHECK_OFFSET(WPADInfo, 0x04, speakerEnabled);
 WUT_CHECK_OFFSET(WPADInfo, 0x08, extensionAttached);
 WUT_CHECK_OFFSET(WPADInfo, 0x0c, batteryLow);
-WUT_CHECK_OFFSET(WPADInfo, 0x10, batteryNearEmpty);
+WUT_CHECK_OFFSET(WPADInfo, 0x10, speakerBufNearEmpty);
 WUT_CHECK_OFFSET(WPADInfo, 0x14, batteryLevel);
 WUT_CHECK_OFFSET(WPADInfo, 0x15, led);
 WUT_CHECK_OFFSET(WPADInfo, 0x16, protocol);
@@ -740,6 +741,13 @@ struct WPADAddress
 WUT_CHECK_OFFSET(WPADAddress, 0x00, btDeviceAddress);
 WUT_CHECK_SIZE(WPADAddress, 0x6);
 
+//! Continuation parameters for WENCGetEncodeData
+struct WENCParams
+{
+   WUT_UNKNOWN_BYTES(32);
+};
+WUT_CHECK_SIZE(WENCParams, 32);
+
 typedef void (*WPADCallback)(WPADChan channel, WPADError status);
 typedef WPADCallback WPADControlLedCallback;
 typedef WPADCallback WPADControlDpdCallback;
@@ -884,15 +892,37 @@ WPADCanSendStreamData(WPADChan channel);
  * make sure the data is in the format the speaker was initialized for,
  * (4-bit Yamaha ADPCM by default)
  * \param data audio encoded in initialized format
- * \param size number of bytes to send
+ * \param size number of bytes to send, up to 20 bytes may be sent per call
  * \return `WPAD_ERROR_NOT_READY`, if not possible to send data at this moment
- * \return `WPAD_ERROR_NO_CONTROLLER`, if channel is invalid, data is null or size is more than 20
+ * \return `WPAD_ERROR_NO_CONTROLLER`, if channel is invalid, data is NULL or size is more than 20
+ *
+ * \sa WPADControlSpeaker
+ * \sa WPADCanSendStreamData
+ * \sa WENCGetEncodeData
  */
 WPADError
 WPADSendStreamData(WPADChan channel,
-                   void *data,
+                   const void *data,
                    uint32_t size);
 
+/**
+ * Encode 16-bit LPCM as 4-bit Yamaha ADPCM
+ * \param params encoding continuation params, written on first call, and read and updated on each subsequent call
+ * \param continuing should be TRUE if continuing encoding stream with the params produced via a prior call
+ * \param samples 16-bit LPCM sample buffer
+ * \param sampleCount number of 16-bit LPCM samples
+ * \param outEncodedData buffer for the returned adpcm samples, buffer size should be equal to {(sampleCount + 1) / 2}
+ * \return Number of LPCM-16 samples
+ *
+ * \sa WPADSendStreamData
+ */
+uint32_t
+WENCGetEncodeData(WENCParams *params,
+                  BOOL continuing,
+                  const int16_t *samples,
+                  uint32_t sampleCount,
+                  uint8_t *outEncodedData);
+
 /**
  * Returns the global Wii Remote speaker volume
  */
@@ -900,19 +930,19 @@ uint8_t
 WPADGetSpeakerVolume(void);
 
 /**
- * Sets the global Wii Remote speaker volume
- * only applies to later initialized Wii Remote speakers
+ * Sets the global Wii Remote speaker volume.
+ * Only applies to Wii Remotes whose speakers are initialized after this call.
  */
 void
 WPADSetSpeakerVolume(uint8_t volume);
 
 /**
  * Gets whether MotionPlus is enabled for the WPAD
- * \param enabled is set if MotionPlus is enabled
+ * \param outEnabled is set to true if MotionPlus is enabled
  */
 int32_t
 WPADIsMplsAttached(WPADChan channel,
-                   BOOL *enabled,
+                   BOOL *outEnabled,
                    WPADCallback callback);
 
 /**
@@ -924,6 +954,8 @@ WPADIsMplsIntegrated(WPADChan channel);
 
 /**
  * Retrieves status info from the controller
+ * \return WPAD_ERROR_NO_CONTROLLER if info request fails
+ * \return WPAD_ERROR_NOT_READY if controller is not connected
  */
 WPADError
 WPADGetInfo(WPADChan channel,
@@ -931,6 +963,9 @@ WPADGetInfo(WPADChan channel,
 
 /**
  * Retrieves status info from the controller asynchronously
+ * \param callback pointer to function called when info is obtained
+ * \return WPAD_ERROR_NO_CONTROLLER if info request fails
+ * \return WPAD_ERROR_NOT_READY if controller is not connected
  */
 WPADError
 WPADGetInfoAsync(WPADChan channel,
@@ -941,11 +976,10 @@ WPADGetInfoAsync(WPADChan channel,
  * Reads from the device's memory
  * \param destination where the received data will be stored
  * \param size number of bytes to read
- * \param address
- * device memory address, see
+ * \param address device memory address, see
  * <a href="https://wiibrew.org/wiki/Wiimote#EEPROM_Memory">EEPROM Memory</a> and
  * <a href="https://wiibrew.org/wiki/Wiimote#Control_Registers">Control Registers</a>
- * \param completionCallback function to be called upon completion
+ * \param callback function to be called upon completion
  * \sa
  * - WPADWriteMemoryAsync()
  * - WPADReadExtReg()
@@ -961,8 +995,7 @@ WPADReadMemoryAsync(WPADChan channel,
  * Writes to the device's memory
  * \param source data to be written to the controller
  * \param size number of bytes to write
- * \param address
- * device memory address, see
+ * \param address device memory address, see
  * <a href="https://wiibrew.org/wiki/Wiimote#EEPROM_Memory">EEPROM Memory</a> and
  * <a href="https://wiibrew.org/wiki/Wiimote#Control_Registers">Control Registers</a>
  * \param callback function to be called upon completion
@@ -995,6 +1028,7 @@ WPADReadExtReg(WPADChan channel,
 /**
  * Writes to the registers of the Wii Remote's peripherals
  * \param address address within the peripheral's memory space
+ * \param peripheral target peripheral memory area
  * \sa
  * - WPADWriteMemoryAsync()
  * - WPADReadExtReg()
@@ -1002,8 +1036,7 @@ WPADReadExtReg(WPADChan channel,
  * Usage:
  * \code
  * // Setting speaker volume on specific controller
- * uint8_t volume;
- * volume = 0x40;
+ * uint8_t volume = 0x40;
  * WPADWriteExtReg(WPAD_CHAN_0, &volume, 1, WPAD_PERIPHERAL_SPACE_SPEAKER, 0x05, nullptr);
  * \endcode
  */
@@ -1102,8 +1135,8 @@ BOOL
 WPADStartSyncDevice(void);
 
 /**
- * Starts attempts to sync with a WPAD with the specified properties,
- * if unable to do so, starts a normal sync as with WPADStartSyncDevice
+ * Starts attempts to sync with a WPAD with the specified properties.
+ * If unable to find a device, does the same as \link WPADStartSyncDevice \endlink
  * \param deviceAddress Bluetooth address of the device to connect to.
  * \param deviceName Bluetooth name of the device to connect to (up to 24 characters)
  * \return TRUE if sync started
@@ -1112,8 +1145,8 @@ WPADStartSyncDevice(void);
  * \code
  * WPADAddress addr;
  * memset(&addr, 0x10, 6);
- * // Initially searches for device with address 10:10:10:10:10:10 and name "Nintendo"
- * WPADStartSyncDeviceEx(&addr, "Nintendo");
+ * // Initially searches for device with address 10:10:10:10:10:10 and name "Nintendo RVL-CNT-01" (Wii Remote)
+ * WPADStartSyncDeviceEx(&addr, "Nintendo RVL-CNT-01");
  * \endcode
  */
 BOOL
@@ -1126,6 +1159,8 @@ WPADStartSyncDeviceEx(WPADAddress* deviceAddress,
  *   - `WPAD_ERROR_NONE` when controller connects.
  *   - `WPAD_ERROR_NO_CONTROLLER` when controller disconnects.
  * \return the previously used callback
+ *
+ * \warning May overwrite callbacks used internally by KPAD. If using KPAD, \link KPADSetConnectCallback \endlink is preferable.
  */
 WPADConnectCallback
 WPADSetConnectCallback(WPADChan channel,
@@ -1167,6 +1202,8 @@ WPADGetLatestIndexInBuf(WPADChan channel);
  * Registers a callback to be invoked whenever new `WPADStatus*` data is stored in the
  * ring buffer.
  *
+ * \warning May overwrite callbacks used internally by KPAD. If using KPAD, \link KPADSetSamplingCallback \endlink is preferable.
+ *
  * \sa
  * - `WPADSetAutoSamplingBuf()`
  * - `WPADGetLatestIndexInBuf()`
@@ -1197,7 +1234,7 @@ WPADiIsAvailableCmdQueue(WPADiQueue *queue,
  */
 int32_t
 WPADiHIDParser(WPADChan channel,
-               uint8_t *hidData);
+               const uint8_t *hidData);
 
 
 /**
@@ -1261,8 +1298,8 @@ WPADiSendEnableDPDCSB(WPADiQueue *cmdQueue,
                       WPADCallback callback);
 
 /**
- * Queues HID Report for enabling speakers
- * used internally by \link WPADControlSpeaker \link
+ * Queues HID Report for enabling speakers.
+ * Used internally by \link WPADControlSpeaker \link
  * \return TRUE if successfully added to queue
  */
 BOOL
@@ -1302,7 +1339,7 @@ WPADiSendWriteDataCmd(WPADiQueue *cmdQueue,
 
 /**
  * Queues HID Report for a multi-byte memory write
- * used internally by \link WPADWriteMemory \endlink
+ * used internally by \link WPADWriteMemoryAsync \endlink
  * \return TRUE if successfully added to queue
  */
 BOOL
@@ -1314,7 +1351,7 @@ WPADiSendWriteData(WPADiQueue *cmdQueue,
 
 /**
  * Queues HID Report for a memory read
- * used internally by \link WPADReadMemory \endlink
+ * used internally by \link WPADReadMemoryAsync \endlink
  * \return TRUE if successfully added to queue
  */
 BOOL
@@ -1347,7 +1384,7 @@ WPADiGetGameType(void);
  * - WPADiWriteGameData
  */
 void
-WPADSetGameTitleUtf16(uint16_t *title);
+WPADSetGameTitleUtf16(const uint16_t *title);
 
 /**
  * Gets game title stored on specified controller
@@ -1367,7 +1404,7 @@ WPADGetGameTitleUtf16(WPADChan channel,
  */
 WPADError
 WPADGetGameDataTimestamp(WPADChan channel,
-                         OSTime *timestamp);
+                         OSTime *outTimestamp);
 
 /**
  * Write custom game data to the controller's EEPROM
@@ -1388,7 +1425,7 @@ WPADGetGameDataTimestamp(WPADChan channel,
  */
 WPADError
 WPADiWriteGameData(WPADChan channel,
-                   void *source,
+                   const void *source,
                    uint16_t size,
                    uint32_t offset,
                    WPADCallback callback);