Merge pull request #1 from nefarius/friendly-names

Added friendly product names for well-known hardware IDs

Author: nefarius

src/dinput_backend.cpp

@@ -1,5 +1,6 @@
 #include "dinput_backend.h"
 #include "sony_layout.h"
+#include "usb_names.h"
 #include <algorithm>
 #include <ranges>
 #include <utility>
@@ -124,9 +125,39 @@ const GamepadState& DInputBackend::GetState(int slot) const
 	return states_[slot];
 }
 
+/**
+ * Retrieve the backend's short name.
+ *
+ * @return Pointer to a null-terminated C-string with the backend name.
+ */
 const char* DInputBackend::GetName() const { return Name; }
 
-// ── device enumeration ───────────────────────────────────────
+/**
+ * @brief Retrieve a human-friendly display name for the device occupying a slot.
+ *
+ * @param slot Device slot index (valid range: 0..kMaxDevices-1).
+ * @return const char* Null-terminated display name for the device, or `nullptr` if the slot is out of range or no device is present.
+ */
+const char* DInputBackend::GetSlotDisplayName(int slot) const
+{
+	if (slot < 0 || slot >= kMaxDevices) return nullptr;
+	const auto it = std::ranges::find_if(devices_, [slot](const DeviceInfo& d) { return d.slot == slot; });
+	if (it == devices_.end()) return nullptr;
+	return GetFriendlyName(it->vendorId, it->productId);
+}
+
+/**
+ * @brief Callback invoked for each DirectInput device during enumeration.
+ *
+ * Marks an already-known device as found or attempts to create and register a new
+ * DeviceInfo for the discovered device. When SetupDevice succeeds, the new device
+ * is appended to the backend's device list and marked as found.
+ *
+ * @param inst Pointer to the enumerated device instance information.
+ * @param ctx  User context passed to the enumerator; expected to be a pointer to
+ *             the DInputBackend instance.
+ * @return BOOL Always returns DIENUM_CONTINUE to continue device enumeration.
+ */
 
 BOOL CALLBACK DInputBackend::EnumCallback(
 	const DIDEVICEINSTANCEW* inst, VOID* ctx)

src/dinput_backend.h

@@ -17,10 +17,37 @@ class DInputBackend final : public IInputBackend
 
 	~DInputBackend() override;
 	void Init(HWND hwnd) override;
+	/**
+	 * Poll connected devices and update internal input states.
+	 */
+	 
+	/**
+	 * Maximum number of input slots supported by this backend.
+	 * @returns The maximum slot count.
+	 */
+	
+	/**
+	 * Retrieve the current gamepad state for a given slot.
+	 * @param slot Index of the input slot to query.
+	 * @returns Reference to the `GamepadState` for the specified slot.
+	 */
+	
+	/**
+	 * Name identifying this input backend.
+	 * @returns Pointer to a null-terminated string with the backend name.
+	 */
+	
+	/**
+	 * Human-readable display name for a specific slot.
+	 * @param slot Index of the input slot to query.
+	 * @returns Pointer to a null-terminated string describing the slot or its assigned device.
+	 *          May return nullptr when no slot/device mapping exists or when no name is available.
+	 */
 	void Poll() override;
 	[[nodiscard]] int GetMaxSlots() const override;
 	[[nodiscard]] const GamepadState& GetState(int slot) const override;
 	[[nodiscard]] const char* GetName() const override;
+	[[nodiscard]] const char* GetSlotDisplayName(int slot) const override;
 
 private:
 	struct DeviceInfo

src/gamepad_renderer.cpp

@@ -149,25 +149,53 @@ static void DrawSmallButton(ImDrawList* dl, const Layout& L,
     dl->AddText(ImVec2(center.x - ts.x * 0.5f, center.y - ts.y * 0.5f), tc, label);
 }
 
-// ── main entry point ─────────────────────────────────────────
+/**
+ * @brief Render a controller panel that visualizes a gamepad's layout and state.
+ *
+ * Renders a framed panel at the given position/size containing a header (built from the player
+ * slot, optional display name, and backend name), a connection-status pill, and a scaled
+ * representation of the controller showing body, D-pad, face buttons, thumbsticks, bumpers,
+ * triggers, and small buttons. When the gamepad is not connected, displays a centered
+ * "No controller detected" message instead of the controls.
+ *
+ * @param dl ImGui draw list to use for low-level drawing operations.
+ * @param panelPos Top-left corner of the panel in screen coordinates.
+ * @param panelSize Width and height of the panel in screen coordinates.
+ * @param gs Current gamepad state (buttons, sticks, triggers, connection).
+ * @param slotIndex Zero-based player slot index used in the header label.
+ * @param backendName Null-terminated string identifying the input backend (shown in header).
+ * @param displayName Optional null-terminated display name for the controller; when non-empty
+ *                    it is included in the header as "Player N - DisplayName  [backend]".
+ */
 
 void DrawGamepad(ImDrawList* dl, ImVec2 panelPos, ImVec2 panelSize,
-                 const GamepadState& gs, int slotIndex, const char* backendName) {
+                 const GamepadState& gs, int slotIndex, const char* backendName,
+                 const char* displayName) {
     dl->AddRectFilled(panelPos,
         ImVec2(panelPos.x + panelSize.x, panelPos.y + panelSize.y),
         BgDim(), 8.0f);
 
-    auto header = std::format("Player {}  [{}]", slotIndex + 1, backendName);
+    std::string header;
+    if (displayName && displayName[0] != '\0')
+        header = std::format("Player {} - {}  [{}]", slotIndex + 1, displayName, backendName);
+    else
+        header = std::format("Player {}  [{}]", slotIndex + 1, backendName);
     ImVec2 hts = ImGui::CalcTextSize(header.c_str());
     float headerH = hts.y + 10.0f;
+
+    const char* status = gs.connected ? "Connected" : "Not Connected";
+    ImVec2 sts = ImGui::CalcTextSize(status);
+    const float pillLeft = panelPos.x + panelSize.x - sts.x - 18 - 4;
+    const float headerClipRight = pillLeft;
+    dl->PushClipRect(ImVec2(panelPos.x + 10, panelPos.y),
+                     ImVec2(headerClipRight, panelPos.y + headerH), true);
     dl->AddText(ImVec2(panelPos.x + 10, panelPos.y + 5),
                 gs.connected ? IM_COL32(220, 220, 220, 255)
                              : IM_COL32(100, 100, 100, 255),
                 header.c_str());
+    dl->PopClipRect();
 
     {
-        const char* status = gs.connected ? "Connected" : "Not Connected";
-        ImVec2 sts = ImGui::CalcTextSize(status);
         float px = panelPos.x + panelSize.x - sts.x - 18;
         float py = panelPos.y + 5;
         ImU32 pillCol = gs.connected ? IM_COL32(50, 180, 80, 200)

src/gamepad_renderer.h

@@ -3,7 +3,27 @@
 #include "imgui.h"
 #include <algorithm>
 
-namespace GamepadRenderer
+/**
+	 * Layout for mapping logical gamepad coordinates to screen space.
+	 *
+	 * Encapsulates an origin and separate X/Y scale factors used to transform
+	 * positions and sizes from the layout's logical coordinate system into
+	 * screen coordinates.
+	 */
+	 
+	/**
+	 * Transform a logical point into screen coordinates by applying the layout origin and scaling.
+	 * @param x X coordinate in the layout's logical coordinate space.
+	 * @param y Y coordinate in the layout's logical coordinate space.
+	 * @returns The transformed point in screen coordinates.
+	 */
+	 
+	/**
+	 * Scale a scalar value using the layout's uniform scale (the smaller of sx and sy).
+	 * @param v Value in the layout's logical units.
+	 * @returns The value scaled into screen units.
+	 */
+	namespace GamepadRenderer
 {
 	struct Layout
 	{
@@ -19,5 +39,6 @@ namespace GamepadRenderer
 	};
 
 	void DrawGamepad(ImDrawList* dl, ImVec2 panelPos, ImVec2 panelSize,
-	                 const GamepadState& gs, int slotIndex, const char* backendName);
+	                 const GamepadState& gs, int slotIndex, const char* backendName,
+	                 const char* displayName = nullptr);
 } // namespace GamepadRenderer

src/hidapi_backend.cpp

@@ -1,5 +1,6 @@
 #include "hidapi_backend.h"
 #include "sony_layout.h"
+#include "usb_names.h"
 #include <algorithm>
 #include <ranges>
 #include <utility>
@@ -105,9 +106,36 @@ const GamepadState& HidApiBackend::GetState(const int slot) const
 	return states_[slot];
 }
 
+/**
+ * @brief Returns the backend's identifier string.
+ *
+ * @return const char* Null-terminated name of this HID backend.
+ */
 const char* HidApiBackend::GetName() const { return Name; }
 
-// ── device enumeration ───────────────────────────────────────
+/**
+ * @brief Retrieve the user-facing display name for a device assigned to a slot.
+ *
+ * @param slot Slot index to query (valid range: 0 to kMaxDevices - 1).
+ * @return const char* Pointer to a friendly name derived from the device's vendor and product IDs,
+ *         or `nullptr` if the slot is out of range or no device is assigned to that slot.
+ */
+const char* HidApiBackend::GetSlotDisplayName(int slot) const
+{
+	if (slot < 0 || slot >= kMaxDevices) return nullptr;
+	const auto it = std::ranges::find_if(devices_, [slot](const std::unique_ptr<DeviceInfo>& d) { return d->slot == slot; });
+	if (it == devices_.end()) return nullptr;
+	return GetFriendlyName((*it)->vendorId, (*it)->productId);
+}
+
+/**
+ * @brief Enumerates connected HID devices and synchronizes the backend's device list.
+ *
+ * @details Scans the system for present HID device interfaces, marks previously-known
+ * devices that remain present, attempts to open and initialize newly discovered devices,
+ * and removes (and closes) devices that are no longer present. Updates the internal
+ * devices_ container and associated per-slot state as devices are added or removed.
+ */
 
 void HidApiBackend::EnumerateDevices()
 {

src/hidapi_backend.h

@@ -18,10 +18,44 @@ class HidApiBackend final : public IInputBackend
 	static constexpr int kMaxDevices = 16;
 
 	~HidApiBackend() override;
+	/**
+	 * Poll HID devices, process incoming reports, and update internal gamepad states.
+	 */
+	 
+	/**
+	 * Return the maximum number of device slots supported by this backend.
+	 * @returns The maximum number of slots.
+	 */
+	 
+	/**
+	 * Retrieve the current gamepad state for a given slot.
+	 * @param slot Index of the slot to query; valid range is 0 .. GetMaxSlots()-1.
+	 * @returns Reference to the GamepadState for the specified slot.
+	 */
+	 
+	/**
+	 * Get the backend name identifier.
+	 * @returns Null-terminated string identifying this backend.
+	 */
+	 
+	/**
+	 * Get a human-readable display name for the device assigned to a slot.
+	 * @param slot Index of the slot to query; valid range is 0 .. GetMaxSlots()-1.
+	 * @returns A null-terminated display name for the slot, or nullptr when no name is available.
+	 */
+	 
+	/**
+	 * Per-device runtime information and resources used to manage a HID device.
+	 *
+	 * Contains device path, OS handle and overlapped I/O state, read buffer,
+	 * HID preparsed data and capability descriptors, assigned slot index, flags
+	 * tracking discovery and read state, and the device's vendor/product IDs.
+	 */
 	void Poll() override;
 	[[nodiscard]] int GetMaxSlots() const override;
 	[[nodiscard]] const GamepadState& GetState(int slot) const override;
 	[[nodiscard]] const char* GetName() const override;
+	[[nodiscard]] const char* GetSlotDisplayName(int slot) const override;
 
 private:
 	struct DeviceInfo

src/input_backend.h

@@ -2,6 +2,52 @@
 #include "gamepad_state.h"
 #include <Windows.h>
 
+/**
+ * Abstract interface for input backends that provide per-slot gamepad state.
+ */
+ 
+/**
+ * Virtual destructor to allow proper cleanup of derived implementations.
+ */
+
+/**
+ * Initialize the backend with an optional window handle.
+ * @param hwnd Window handle used for backend initialization (may be ignored).
+ */
+
+/**
+ * Handle a window message.
+ * @param msg The window message identifier.
+ * @param wParam The message wParam.
+ * @param lParam The message lParam.
+ * @returns `true` if the message was handled, `false` otherwise.
+ */
+
+/**
+ * Update the backend's input state for all slots.
+ */
+
+/**
+ * Get the maximum number of input slots supported by this backend.
+ * @returns The maximum number of supported input slots.
+ */
+
+/**
+ * Get the current gamepad state for a specific slot.
+ * @param slot Index of the input slot.
+ * @returns A const reference to the GamepadState for the specified slot.
+ */
+
+/**
+ * Get the name of this backend.
+ * @returns A null-terminated C-string identifying the backend.
+ */
+
+/**
+ * Get a display name for a specific slot, if available.
+ * @param slot Index of the input slot.
+ * @returns A null-terminated C-string containing the slot display name, or `nullptr` if none is available.
+ */
 class IInputBackend
 {
 public:
@@ -16,4 +62,5 @@ class IInputBackend
 	[[nodiscard]] virtual int GetMaxSlots() const = 0;
 	[[nodiscard]] virtual const GamepadState& GetState(int slot) const = 0;
 	[[nodiscard]] virtual const char* GetName() const = 0;
+	[[nodiscard]] virtual const char* GetSlotDisplayName([[maybe_unused]] int slot) const { return nullptr; }
 };

src/main.cpp

@@ -214,6 +214,17 @@ static LRESULT WINAPI WndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)
 	return DefWindowProc(hWnd, msg, wParam, lParam);
 }
 
+/**
+ * @brief Application entry point that initializes subsystems, runs the main event and render loop, and performs cleanup on exit.
+ *
+ * Initializes DPI awareness, registers the main window class, loads persisted preferences, creates the main window and Direct3D/ImGui backends, constructs input backends, and enters the primary message/poll/render loop that drives UI and input visualization. On exit it shuts down ImGui and Direct3D, saves state as needed, and unregisters the window class.
+ *
+ * @param hInstance Handle to the current application instance.
+ * @param hPrevInstance Reserved; typically unused.
+ * @param lpCmdLine Command line for the application as a Unicode string.
+ * @param nCmdShow Controls how the window is to be shown.
+ * @return int `0` on normal exit, non-zero on initialization failure (e.g., Direct3D creation failure).
+ */
 int APIENTRY wWinMain(
 	_In_ HINSTANCE hInstance,
 	_In_opt_ HINSTANCE,
@@ -354,11 +365,12 @@ int APIENTRY wWinMain(
 						const GamepadState* state;
 						int slotIndex;
 						const char* backendName;
+						const char* displayName;
 					};
 					std::vector<SlotInfo> slots;
 					for (int i = 0; i < b->GetMaxSlots(); ++i)
 						if (b->GetState(i).connected)
-							slots.push_back({&b->GetState(i), i, b->GetName()});
+							slots.push_back({&b->GetState(i), i, b->GetName(), b->GetSlotDisplayName(i)});
 
 					ImDrawList* dl = ImGui::GetWindowDrawList();
 					ImVec2 origin = ImGui::GetCursorScreenPos();
@@ -393,7 +405,7 @@ int APIENTRY wWinMain(
 
 							GamepadRenderer::DrawGamepad(dl, pos, size,
 							                             *slots[i].state, slots[i].slotIndex,
-							                             slots[i].backendName);
+							                             slots[i].backendName, slots[i].displayName);
 						}
 					}