qmlGamepadInputDevice.h

Go to the documentation of this file.

/******************************************************************************
** Copyright (c) 2025 MAK Technologies, Inc.
** All rights reserved.
******************************************************************************/
//! \file qmlGamepadInputDevice.h
//! \brief Custom input device integration example for VR-Engage input system
//!
//! DtQmlGamepadInputDevice demonstrates the complete pattern for integrating a
//! non-standard input device (not using HID protocols) with VR-Engage's input
//! mapping system. This example uses a QML-based virtual gamepad as the device,
//! but the pattern applies to any custom input source: serial devices, network
//! protocols, motion capture systems, or proprietary hardware.
//!
//! Key Patterns Demonstrated:
//! - Deriving from DtInputDevice for custom input sources
//! - Event collection and queuing between device and framework
//! - Transformation of device-specific data into DtInputData structures
//! - Integration with VR-Engage's input mapping configuration system
//! - Device lifecycle management (init, tick, shutdown)
 
#pragma once
 
#include "export.h"
 
#include "vreInput/inputDevice.h"
#include "vreInput/inputData.h"
 
#include "qmlGamepad.h"
 
#include <list>
 
//! \brief Custom input device adapter for VR-Engage's input mapping system
//!
//! PATTERN: Custom Input Device Integration
//! To integrate a non-standard input device with VR-Engage:
//!
//! 1. Derive from DtInputDevice base class
//! 2. Implement init(), tick(), and shutdown() lifecycle methods
//! 3. Gather device input asynchronously (callbacks, polling, events)
//! 4. Queue input events as DtInputData structures
//! 5. During tick(), pass queued events to DtVreInputManager::processInput()
//!
//! DtInputDevice Integration:
//! Once registered with the input device factory (in plugin.cxx), this class
//! is automatically instantiated and ticked by the input manager. The tick()
//! method is called once per frame, providing the opportunity to process any
//! input gathered since the last frame.
//!
//! Input Mapping Configuration:
//! After device input is transformed into DtInputData structures and passed to
//! the input manager, VR-Engage's input mapping system (configured via XML files)
//! matches the input to player actions. For example, "Virtual Gamepad button 0"
//! can be mapped to "FireWeapon" action in the input mapping configuration.
//!
//! REUSABLE: This class serves as a template for integrating any custom input
//! device. Replace DtQmlGamepad with your device's API and adapt the event
//! collection mechanism, but keep the overall structure:
//!   init() → register for device events
//!   tick() → process queued events → call myManager->processInput()
//!   shutdown() → unregister from device events
//!
//! Device-Specific vs Generic Patterns:
//! - Device-specific: myVirtualGamepad and its event callback (lines 60-65)
//! - Generic/reusable: DtInputDevice lifecycle, event queue, DtInputData creation
//!
class INPUTDEVICE_DLL DtQmlGamepadInputDevice : public makVre::DtInputDevice
{
public:
   DtQmlGamepadInputDevice();
   virtual ~DtQmlGamepadInputDevice();
 
   // Inherited framework functions:
   // ------------------------------
 
   //! \brief Initialize input device and register for device events
   //!
   //! Called once on application startup after the input manager is initialized.
   //! Custom devices should:
   //! 1. Store the input manager pointer for later use
   //! 2. Initialize device-specific hardware/connections
   //! 3. Register callbacks/handlers to receive device events
   //!
   //! PATTERN: Device Event Registration
   //! Custom input devices often use callbacks to receive asynchronous input
   //! rather than polling. Register callbacks during init() to start receiving
   //! device events. Events should be queued (not processed immediately) and
   //! processed during tick() to ensure frame-synchronous input handling.
   //!
   //! \param mgr Reference to VR-Engage's input manager for event submission
   //! \return true if initialization succeeded, false on failure
   //!
   virtual bool init(makVre::DtVreInputManager& mgr) override;
 
   //! \brief Clean up device resources and unregister event handlers
   //!
   //! Called once during application shutdown. Custom devices should:
   //! 1. Unregister all event callbacks to prevent callbacks to destroyed objects
   //! 2. Close device connections/hardware
   //! 3. Free device-specific resources
   //!
   virtual void shutdown() override;
 
   //! \brief Process queued input events and submit to input manager
   //!
   //! Called once per frame by the input manager. This is where queued device
   //! events are transformed into DtInputData structures and submitted for
   //! input mapping processing.
   //!
   //! PATTERN: Event Queue Processing
   //! Custom input devices typically use a two-phase approach:
   //! 1. Asynchronously collect input events (callbacks/polling) and queue them
   //! 2. During tick(), iterate through queue and call myManager->processInput()
   //!
   //! This ensures all input is processed at a consistent point in the frame
   //! rather than at random times when device events occur.
   //!
   //! Frame Timing:
   //! The dt parameter provides time elapsed since last frame in seconds.
   //! Most input devices don't need this (events have their own timestamps),
   //! but it's useful for devices that require time-based accumulation or
   //! filtering (e.g., motion smoothing, button debouncing).
   //!
   //! \param dt Time elapsed since previous frame in seconds
   //!
   virtual void tick(double dt) override;
 
   //! \brief Report current device state (required by base class, not used)
   //!
   //! Some input device implementations use this for state debugging or
   //! diagnostics. Not currently utilized by this example.
   //!
   void reportCurrentState() {};
 
   // Custom device interface:
   // ------------------------
 
   //! \brief Callback receiving events from the virtual gamepad device
   //!
   //! This callback function receives events from the example device (virtual
   //! gamepad UI). When a user interacts with the on-screen gamepad, the
   //! DtQmlGamepad invokes this callback with event details.
   //!
   //! PATTERN: Device Event Callback
   //! Events are received asynchronously (triggered by user interaction with QML UI)
   //! but must be processed synchronously during tick(). This function creates a
   //! DtInputData structure for each event and pushes it into myEventQueue for
   //! processing in the next tick() call.
   //!
   //! REUSABLE: For a different custom device, replace this callback with your
   //! device's event notification mechanism. The pattern remains the same:
   //! receive event → create DtInputData → queue for processing in tick().
   //!
   //! \param eventType Device-specific event type string (e.g., "axis", "button")
   //! \param eventId Control identifier within that type (button 0, axis 1, etc.)
   //! \param eventValue Event value (button: 0.0/1.0, axis: -1.0 to +1.0)
   //!
   void deviceEventCallback(std::string eventType, int eventId, double eventValue);
 
protected:
   //! Event queue to gather device events between tick calls
   //! Events received via callbacks are queued here, then processed in tick()
   std::list<makVre::DtInputData> myEventQueue;
 
   //! The custom device instance (virtual on-screen gamepad in this example)
   //! For a real hardware device, this would be replaced with your device's
   //! API interface (serial port, USB, network connection, etc.)
   makVre::DtQmlGampad myVirtualGamepad;
};