===============
controller_hidd
===============

.. This document is automatically generated. Don't edit it!

`Index <index>`_

----------

Classes
-------

+ `CLID_Hidd_Controller`_
+ `CLID_HW_Controller`_

----------

CLID_Hidd_Controller
--------------------

========================================== ========================================== ========================================== ========================================== 
`--background_subsystem--`_                `aoHidd_Controller_AxisCount`_             `aoHidd_Controller_ButtonCount`_           `aoHidd_Controller_Capabilities`_          
`aoHidd_Controller_Extended`_              `aoHidd_Controller_HatCount`_              `aoHidd_Controller_RelativeCoords`_        `aoHidd_Controller_State`_                 
`Controller`_                              
========================================== ========================================== ========================================== ========================================== 

-----------

--background_subsystem--
========================

Notes
~~~~~
::

     This class represents a "hub" for collecting input from various
     pointing devices (mice, tablets, touchscreens, etc) in the
     system. Events from all pointing devices are merged into a
     single stream and propagated to all clients.

     In order to get an access to pointing input subsystem you need to
     create an object of CLID_HW_Controller class. The actual returned
     object is a singletone, so disposal is not neccessary.  Every
     call will return the same object pointer. After retrieving the object
     you can, for example, register your driver using moHW_AddDriver
     method, or enumerate drivers using moHW_EnumDrivers.

     If you wish to receive controller events, use objects of CLID_Hidd_Controller
     class. This class implements the same interface as driver class, but
     represents receiver's side and is responsible for registering user's
     interrupt handler in the listeners chain. These objects are not real
     drivers and do not need to be registered within the subsystem.



----------

aoHidd_Controller_AxisCount
===========================

Synopsis
~~~~~~~~
::

     [..G], ULONG


Function
~~~~~~~~
::

     Returns the number of analog axes exposed by this controller.  
     Axis indices in events range from 0 to (AxisCount - 1).


Notes
~~~~~
::

     Axis values are signed 16-bit integers, typically in the range -32768..32767.  
     The interpretation (X/Y stick, throttle, trigger, wheel) depends on the driver
     or higher-level mapping.



See also
~~~~~~~~

`pHidd_Controller_State`_ 

----------

aoHidd_Controller_ButtonCount
=============================

Synopsis
~~~~~~~~
::

     [..G], ULONG


Function
~~~~~~~~
::

     Returns the number of buttons physically supported by this controller.  
     Button indices in events range from 0 to (ButtonCount - 1).


Notes
~~~~~
::

     Button codes are device-specific; higher-level code should not assume
     semantic meaning (e.g. "A button") from index values.



See also
~~~~~~~~

`pHidd_Controller_State`_ 

----------

aoHidd_Controller_Capabilities
==============================

Synopsis
~~~~~~~~
::

     [..G], ULONG (bitmask)


Function
~~~~~~~~
::

     Returns a bitmask describing what types of controls this device provides.  
     Capability flags may include:
         vHidd_Controller_Cap_Buttons   one or more buttons are present  
         vHidd_Controller_Cap_Axes      one or more analog axes are present  
         vHidd_Controller_Cap_Hats      one or more hat switches are present  


Notes
~~~~~
::

     This attribute can be used to quickly filter devices before querying their
     detailed counts.



See also
~~~~~~~~

`aoHidd_Controller_ButtonCount`_ `aoHidd_Controller_AxisCount`_ `aoHidd_Controller_HatCount`_ 

----------

aoHidd_Controller_Extended
==========================

Synopsis
~~~~~~~~
::

     [..G], BOOL


Function
~~~~~~~~
::

     Queries whether the driver provides the extended event descriptor structure
     (struct pHidd_Controller_ExtEvent).

     If the value of this attribute is FALSE, the event passed to the handler is
     a struct pHidd_Controller_Event and does not contain timestamp or device_id.
     If TRUE, handlers receive a struct pHidd_Controller_ExtEvent instead.

     CLID_Hidd_Controller class always returns TRUE for this attribute.



See also
~~~~~~~~

`aoHidd_Input_IrqHandler`_ 

----------

aoHidd_Controller_HatCount
==========================

Synopsis
~~~~~~~~
::

     [..G], ULONG


Function
~~~~~~~~
::

     Returns the number of directional hat switches (POV hats) exposed by this
     controller.  
     Hat indices in events range from 0 to (HatCount - 1).


Notes
~~~~~
::

     Hat values are usually encoded as 07 for the eight cardinal/diagonal
     directions, with 0xFFFF meaning "centered".



See also
~~~~~~~~

`pHidd_Controller_State`_ 

----------

aoHidd_Controller_RelativeCoords
================================

Synopsis
~~~~~~~~
::

     [..G], BOOL


Function
~~~~~~~~
::

     Queries whether the device reports relative (like a controller or steering wheel)
     or absolute (like a touchscreen or analog stick with fixed range) coordinates.

     Drivers which provide extended event structures may not implement this attribute
     if they generate a mixed set of events. In that case, the coordinate type must
     be determined from the flags member of struct pHidd_Controller_Event or
     pHidd_Controller_ExtEvent.

     CLID_Hidd_Controller class does not implement this attribute itself since it
     merges a mixed stream of events.



See also
~~~~~~~~

`aoHidd_Input_IrqHandler`_ `aoHidd_Controller_Extended`_ 

----------

aoHidd_Controller_State
=======================

Synopsis
~~~~~~~~
::

     [..G], struct pHidd_Controller_State


Function
~~~~~~~~
::

     Obtains the current controller state. This is a snapshot structure containing
     button bitmasks, axis values, and hat values.


Notes
~~~~~
::

     Reading state directly is optional; normally you will track state using the
     event stream instead.



See also
~~~~~~~~

`pHidd_Controller_Event`_ `pHidd_Controller_ExtEvent`_ 

----------

Controller
==========

Notes
~~~~~
::

     Instances of this class are virtual devices representing game controllers,
     joysticks, pads, wheels, or other generic input controllers. To receive
     controller input events, create an object of this class and supply a callback
     using aoHidd_Input_IrqHandler. After that, your callback will be called
     whenever controller input is received until you dispose of the object.

     Every client receives events from all controllers merged into a single stream.
     If you need to distinguish between physical devices, check the device_id field
     of the extended event structure (struct pHidd_Controller_ExtEvent).



CLID_HW_Controller
------------------

========================================== ========================================== ========================================== ========================================== 
`--hardware_drivers--`_                    
========================================== ========================================== ========================================== ========================================== 

-----------

--hardware_drivers--
====================

Notes
~~~~~
::

     A hardware driver should be a subclass of CLID_Hidd_Controller, and implement IID_Hidd_Controller
     interface according to the following rules:

     1. A single object of driver class represents a single hardware unit.
     2. A single driver object maintains a single callback address (passed to it
        using aoHidd_Input_IrqHandler). Under normal conditions this callback is
        supplied by CLID_HW_Controller class.



