diff --git a/.github/workflows/vmactions.yml b/.github/workflows/vmactions.yml index f701c8dbb0ea6..e24f9d0ad1df2 100644 --- a/.github/workflows/vmactions.yml +++ b/.github/workflows/vmactions.yml @@ -52,6 +52,7 @@ jobs: cmake -S . -B build -GNinja \ -Wdeprecated -Wdev -Werror \ -DCMAKE_BUILD_TYPE=Release \ + -DSDL_HIDAPI_LIBUSB=OFF \ -DSDL_CHECK_REQUIRED_INCLUDES="/usr/local/include" \ -DSDL_CHECK_REQUIRED_LINK_OPTIONS="-L/usr/local/lib" cmake --build build/ --config Release --verbose -- -j`sysctl -n hw.ncpu` diff --git a/CMakeLists.txt b/CMakeLists.txt index 76211e19bd73f..1a992935cac03 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -570,32 +570,6 @@ if(USE_GCC OR USE_CLANG OR USE_INTELCC OR USE_QCC) target_compile_options(sdl-global-options INTERFACE "-fno-strict-aliasing") endif() - # command-line option ‘-Wdeclaration-after-statement’ is valid for C/ObjC but not for C++ - check_c_compiler_flag(-Wdeclaration-after-statement HAVE_GCC_WDECLARATION_AFTER_STATEMENT) - if(HAVE_GCC_WDECLARATION_AFTER_STATEMENT) - if(SDL_WERROR) - check_c_compiler_flag(-Werror=declaration-after-statement HAVE_GCC_WERROR_DECLARATION_AFTER_STATEMENT) - if(HAVE_GCC_WERROR_DECLARATION_AFTER_STATEMENT) - if(CMAKE_VERSION VERSION_LESS 3.3) - target_compile_options(sdl-global-options INTERFACE "-Werror=declaration-after-statement") - else() - target_compile_options(sdl-global-options INTERFACE "$<$:-Werror=declaration-after-statement>") - if(CMAKE_OBJC_COMPILER) - target_compile_options(sdl-global-options INTERFACE "$<$:-Werror=declaration-after-statement>") - endif() - endif() - endif() - endif() - if(CMAKE_VERSION VERSION_LESS 3.3) - target_compile_options(sdl-global-options INTERFACE "-Wdeclaration-after-statement") - else() - target_compile_options(sdl-global-options INTERFACE "$<$:-Wdeclaration-after-statement>") - if(CMAKE_OBJC_COMPILER) - target_compile_options(sdl-global-options INTERFACE "$<$:-Wdeclaration-after-statement>") - endif() - endif() - endif() - check_c_compiler_flag(-Wdocumentation HAVE_GCC_WDOCUMENTATION) if(HAVE_GCC_WDOCUMENTATION) if(SDL_WERROR) @@ -1132,16 +1106,7 @@ if(SDL_LIBC) set(${_HAVE_H} 1) endforeach() set(HAVE_SIGNAL_H 1) - foreach(_FN - malloc calloc realloc free bsearch qsort abs memset memcpy memmove memcmp - wcslen _wcsdup wcsdup wcsstr wcscmp wcsncmp _wcsicmp _wcsnicmp - strlen _strrev _strupr _strlwr strchr strrchr strstr itoa _ltoa - _ultoa strtol strtoul strtoll strtod atoi atof strcmp strncmp - _stricmp _strnicmp sscanf - acos acosf asin asinf atan atanf atan2 atan2f ceil ceilf - copysign copysignf cos cosf exp expf fabs fabsf floor floorf fmod fmodf - log logf log10 log10f lround lroundf modf modff pow powf round roundf - scalbn scalbnf sin sinf sqrt sqrtf tan tanf trunc truncf) + foreach(_FN abs acos acosf asin asinf atan atan2 atan2f atanf atof atoi bsearch calloc ceil ceilf copysign copysignf cos cosf exp expf fabs fabsf floor floorf fmod fmodf free itoa log log10 log10f logf lround lroundf _ltoa malloc memcmp memcpy memmove memset modf modff pow powf qsort realloc round roundf scalbn scalbnf sin sinf sqrt sqrtf sscanf strchr strcmp _stricmp strlen _strlwr strncmp _strnicmp strrchr _strrev strstr strtod strtol strtoll strtoul _strupr tan tanf trunc truncf _ultoa wcscmp _wcsdup wcsdup _wcsicmp wcslen wcsncmp _wcsnicmp wcsstr wcstol) string(TOUPPER ${_FN} _UPPER) set(HAVE_${_UPPER} 1) endforeach() @@ -1185,16 +1150,7 @@ if(SDL_LIBC) check_c_source_compiles("#include #include int main(void) { return 0; }" HAVE_MPROTECT) - foreach(_FN - strtod malloc calloc realloc free getenv setenv putenv unsetenv - bsearch qsort abs bcopy memset memcpy memmove memcmp strlen strlcpy strlcat - _strrev _strupr _strlwr index rindex strchr strrchr strstr strtok_r - itoa _ltoa _uitoa _ultoa strtol strtoul _i64toa _ui64toa strtoll strtoull - atoi atof strcmp strncmp _stricmp strcasecmp _strnicmp strncasecmp strcasestr - wcscmp _wcsdup wcsdup wcslcat wcslcpy wcslen wcsncmp wcsstr - wcscasecmp _wcsicmp wcsncasecmp _wcsnicmp - sscanf vsscanf vsnprintf fopen64 fseeko fseeko64 _Exit - ) + foreach(_FN abs atof atoi bcopy bsearch calloc _Exit fopen64 free fseeko fseeko64 getenv _i64toa index itoa _ltoa malloc memcmp memcpy memmove memset putenv qsort realloc rindex setenv sscanf strcasecmp strcasestr strchr strcmp _stricmp strlcat strlcpy strlen _strlwr strncasecmp strncmp _strnicmp strrchr _strrev strstr strtod strtok_r strtol strtoll strtoul strtoull _strupr _ui64toa _uitoa _ultoa unsetenv vsnprintf vsscanf wcscasecmp wcscmp _wcsdup wcsdup _wcsicmp wcslcat wcslcpy wcslen wcsncasecmp wcsncmp _wcsnicmp wcsstr wcstol) string(TOUPPER ${_FN} _UPPER) set(LIBC_HAS_VAR "LIBC_HAS_${_UPPER}") check_symbol_exists("${_FN}" "${STDC_HEADER_NAMES}" ${LIBC_HAS_VAR}) diff --git a/android-project/app/src/main/java/org/libsdl/app/HIDDevice.java b/android-project/app/src/main/java/org/libsdl/app/HIDDevice.java index 955df5d14c088..f96095324b858 100644 --- a/android-project/app/src/main/java/org/libsdl/app/HIDDevice.java +++ b/android-project/app/src/main/java/org/libsdl/app/HIDDevice.java @@ -13,9 +13,8 @@ interface HIDDevice public String getProductName(); public UsbDevice getDevice(); public boolean open(); - public int sendFeatureReport(byte[] report); - public int sendOutputReport(byte[] report); - public boolean getFeatureReport(byte[] report); + public int writeReport(byte[] report, boolean feature); + public boolean readReport(byte[] report, boolean feature); public void setFrozen(boolean frozen); public void close(); public void shutdown(); diff --git a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceBLESteamController.java b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceBLESteamController.java index ee5521fd5e3fe..a7b85d0cf8575 100644 --- a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceBLESteamController.java +++ b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceBLESteamController.java @@ -457,7 +457,7 @@ public void onCharacteristicRead(BluetoothGatt gatt, BluetoothGattCharacteristic //Log.v(TAG, "onCharacteristicRead status=" + status + " uuid=" + characteristic.getUuid()); if (characteristic.getUuid().equals(reportCharacteristic) && !mFrozen) { - mManager.HIDDeviceFeatureReport(getId(), characteristic.getValue()); + mManager.HIDDeviceReportResponse(getId(), characteristic.getValue()); } finishCurrentGattOperation(); @@ -575,50 +575,45 @@ public boolean open() { } @Override - public int sendFeatureReport(byte[] report) { + public int writeReport(byte[] report, boolean feature) { if (!isRegistered()) { - Log.e(TAG, "Attempted sendFeatureReport before Steam Controller is registered!"); + Log.e(TAG, "Attempted writeReport before Steam Controller is registered!"); if (mIsConnected) { probeService(this); } return -1; } - // We need to skip the first byte, as that doesn't go over the air - byte[] actual_report = Arrays.copyOfRange(report, 1, report.length - 1); - //Log.v(TAG, "sendFeatureReport " + HexDump.dumpHexString(actual_report)); - writeCharacteristic(reportCharacteristic, actual_report); - return report.length; - } - - @Override - public int sendOutputReport(byte[] report) { - if (!isRegistered()) { - Log.e(TAG, "Attempted sendOutputReport before Steam Controller is registered!"); - if (mIsConnected) { - probeService(this); - } - return -1; + if (feature) { + // We need to skip the first byte, as that doesn't go over the air + byte[] actual_report = Arrays.copyOfRange(report, 1, report.length - 1); + //Log.v(TAG, "writeFeatureReport " + HexDump.dumpHexString(actual_report)); + writeCharacteristic(reportCharacteristic, actual_report); + return report.length; + } else { + //Log.v(TAG, "writeOutputReport " + HexDump.dumpHexString(report)); + writeCharacteristic(reportCharacteristic, report); + return report.length; } - - //Log.v(TAG, "sendFeatureReport " + HexDump.dumpHexString(report)); - writeCharacteristic(reportCharacteristic, report); - return report.length; } @Override - public boolean getFeatureReport(byte[] report) { + public boolean readReport(byte[] report, boolean feature) { if (!isRegistered()) { - Log.e(TAG, "Attempted getFeatureReport before Steam Controller is registered!"); + Log.e(TAG, "Attempted readReport before Steam Controller is registered!"); if (mIsConnected) { probeService(this); } return false; } - //Log.v(TAG, "getFeatureReport"); - readCharacteristic(reportCharacteristic); - return true; + if (feature) { + readCharacteristic(reportCharacteristic); + return true; + } else { + // Not implemented + return false; + } } @Override diff --git a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceManager.java b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceManager.java index 4054bd73e3da9..f79bf1862ce17 100644 --- a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceManager.java +++ b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceManager.java @@ -599,9 +599,9 @@ public boolean openDevice(int deviceID) { return false; } - public int sendOutputReport(int deviceID, byte[] report) { + public int writeReport(int deviceID, byte[] report, boolean feature) { try { - //Log.v(TAG, "sendOutputReport deviceID=" + deviceID + " length=" + report.length); + //Log.v(TAG, "writeReport deviceID=" + deviceID + " length=" + report.length); HIDDevice device; device = getDevice(deviceID); if (device == null) { @@ -609,33 +609,16 @@ public int sendOutputReport(int deviceID, byte[] report) { return -1; } - return device.sendOutputReport(report); + return device.writeReport(report, feature); } catch (Exception e) { Log.e(TAG, "Got exception: " + Log.getStackTraceString(e)); } return -1; } - public int sendFeatureReport(int deviceID, byte[] report) { + public boolean readReport(int deviceID, byte[] report, boolean feature) { try { - //Log.v(TAG, "sendFeatureReport deviceID=" + deviceID + " length=" + report.length); - HIDDevice device; - device = getDevice(deviceID); - if (device == null) { - HIDDeviceDisconnected(deviceID); - return -1; - } - - return device.sendFeatureReport(report); - } catch (Exception e) { - Log.e(TAG, "Got exception: " + Log.getStackTraceString(e)); - } - return -1; - } - - public boolean getFeatureReport(int deviceID, byte[] report) { - try { - //Log.v(TAG, "getFeatureReport deviceID=" + deviceID); + //Log.v(TAG, "readReport deviceID=" + deviceID); HIDDevice device; device = getDevice(deviceID); if (device == null) { @@ -643,7 +626,7 @@ public boolean getFeatureReport(int deviceID, byte[] report) { return false; } - return device.getFeatureReport(report); + return device.readReport(report, feature); } catch (Exception e) { Log.e(TAG, "Got exception: " + Log.getStackTraceString(e)); } @@ -680,5 +663,5 @@ public void closeDevice(int deviceID) { native void HIDDeviceDisconnected(int deviceID); native void HIDDeviceInputReport(int deviceID, byte[] report); - native void HIDDeviceFeatureReport(int deviceID, byte[] report); + native void HIDDeviceReportResponse(int deviceID, byte[] report); } diff --git a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceUSB.java b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceUSB.java index bfe0cf954d95b..5b5d201f78778 100644 --- a/android-project/app/src/main/java/org/libsdl/app/HIDDeviceUSB.java +++ b/android-project/app/src/main/java/org/libsdl/app/HIDDeviceUSB.java @@ -153,49 +153,48 @@ public boolean open() { } @Override - public int sendFeatureReport(byte[] report) { - int res = -1; - int offset = 0; - int length = report.length; - boolean skipped_report_id = false; - byte report_number = report[0]; - - if (report_number == 0x0) { - ++offset; - --length; - skipped_report_id = true; - } - - res = mConnection.controlTransfer( - UsbConstants.USB_TYPE_CLASS | 0x01 /*RECIPIENT_INTERFACE*/ | UsbConstants.USB_DIR_OUT, - 0x09/*HID set_report*/, - (3/*HID feature*/ << 8) | report_number, - mInterface, - report, offset, length, - 1000/*timeout millis*/); - - if (res < 0) { - Log.w(TAG, "sendFeatureReport() returned " + res + " on device " + getDeviceName()); - return -1; - } + public int writeReport(byte[] report, boolean feature) { + if (feature) { + int res = -1; + int offset = 0; + int length = report.length; + boolean skipped_report_id = false; + byte report_number = report[0]; + + if (report_number == 0x0) { + ++offset; + --length; + skipped_report_id = true; + } - if (skipped_report_id) { - ++length; - } - return length; - } + res = mConnection.controlTransfer( + UsbConstants.USB_TYPE_CLASS | 0x01 /*RECIPIENT_INTERFACE*/ | UsbConstants.USB_DIR_OUT, + 0x09/*HID set_report*/, + (3/*HID feature*/ << 8) | report_number, + mInterface, + report, offset, length, + 1000/*timeout millis*/); + + if (res < 0) { + Log.w(TAG, "writeFeatureReport() returned " + res + " on device " + getDeviceName()); + return -1; + } - @Override - public int sendOutputReport(byte[] report) { - int r = mConnection.bulkTransfer(mOutputEndpoint, report, report.length, 1000); - if (r != report.length) { - Log.w(TAG, "sendOutputReport() returned " + r + " on device " + getDeviceName()); + if (skipped_report_id) { + ++length; + } + return length; + } else { + int res = mConnection.bulkTransfer(mOutputEndpoint, report, report.length, 1000); + if (res != report.length) { + Log.w(TAG, "writeOutputReport() returned " + res + " on device " + getDeviceName()); + } + return res; } - return r; } @Override - public boolean getFeatureReport(byte[] report) { + public boolean readReport(byte[] report, boolean feature) { int res = -1; int offset = 0; int length = report.length; @@ -213,7 +212,7 @@ public boolean getFeatureReport(byte[] report) { res = mConnection.controlTransfer( UsbConstants.USB_TYPE_CLASS | 0x01 /*RECIPIENT_INTERFACE*/ | UsbConstants.USB_DIR_IN, 0x01/*HID get_report*/, - (3/*HID feature*/ << 8) | report_number, + ((feature ? 3/*HID feature*/ : 1/*HID Input*/) << 8) | report_number, mInterface, report, offset, length, 1000/*timeout millis*/); @@ -234,7 +233,7 @@ public boolean getFeatureReport(byte[] report) { } else { data = Arrays.copyOfRange(report, 0, res); } - mManager.HIDDeviceFeatureReport(mDeviceId, data); + mManager.HIDDeviceReportResponse(mDeviceId, data); return true; } diff --git a/include/SDL3/SDL_hidapi.h b/include/SDL3/SDL_hidapi.h index 987621b6abd73..87673255e6ae1 100644 --- a/include/SDL3/SDL_hidapi.h +++ b/include/SDL3/SDL_hidapi.h @@ -76,6 +76,37 @@ extern "C" { struct SDL_hid_device_; typedef struct SDL_hid_device_ SDL_hid_device; /**< opaque hidapi structure */ +/** + * \brief HID underlying bus types. + */ +typedef enum { + /** Unknown bus type */ + SDL_HID_API_BUS_UNKNOWN = 0x00, + + /** USB bus + Specifications: + https://usb.org/hid */ + SDL_HID_API_BUS_USB = 0x01, + + /** Bluetooth or Bluetooth LE bus + Specifications: + https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/ + https://www.bluetooth.com/specifications/specs/hid-service-1-0/ + https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */ + SDL_HID_API_BUS_BLUETOOTH = 0x02, + + /** I2C bus + Specifications: + https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */ + SDL_HID_API_BUS_I2C = 0x03, + + /** SPI bus + Specifications: + https://www.microsoft.com/download/details.aspx?id=103325 */ + SDL_HID_API_BUS_SPI = 0x04, + +} SDL_hid_bus_type; + /** hidapi info structure */ /** * \brief Information about a connected HID device @@ -98,17 +129,17 @@ typedef struct SDL_hid_device_info /** Product string */ wchar_t *product_string; /** Usage Page for this Device/Interface - (Windows/Mac only). */ + (Windows/Mac/hidraw only) */ unsigned short usage_page; /** Usage for this Device/Interface - (Windows/Mac only).*/ + (Windows/Mac/hidraw only) */ unsigned short usage; /** The USB interface which this logical device represents. - * Valid on both Linux implementations in all cases. - * Valid on the Windows implementation only if the device - contains more than one interface. */ + Valid only if the device is a USB HID device. + Set to -1 in all other cases. + */ int interface_number; /** Additional information about the USB interface. @@ -117,8 +148,12 @@ typedef struct SDL_hid_device_info int interface_subclass; int interface_protocol; + /** Underlying bus type */ + SDL_hid_bus_type bus_type; + /** Pointer to the next device */ struct SDL_hid_device_info *next; + } SDL_hid_device_info; @@ -187,8 +222,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_hid_device_change_count(void); * matches. If `vendor_id` and `product_id` are both set to 0, then all HID * devices will be returned. * - * \param vendor_id The Vendor ID (VID) of the types of device to open. - * \param product_id The Product ID (PID) of the types of device to open. + * \param vendor_id The Vendor ID (VID) of the types of device to open, or 0 to match any vendor. + * \param product_id The Product ID (PID) of the types of device to open, or 0 to match any product. * \returns a pointer to a linked list of type SDL_hid_device_info, containing * information about the HID devices attached to the system, or NULL * in the case of failure. Free this linked list by calling @@ -237,13 +272,12 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). * * \param path The path name of the device to open - * \param bExclusive Open device in exclusive mode (Windows only) * \returns a pointer to a SDL_hid_device object on success or NULL on * failure. * * \since This function is available since SDL 3.0.0. */ -extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int bExclusive /* = false */); +extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path); /** * Write an Output report to a HID device. @@ -377,6 +411,28 @@ extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, con */ extern DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev, unsigned char *data, size_t length); +/** + * Get an input report from a HID device. + * + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. + * + * \param dev A device handle returned from SDL_hid_open(). + * \param data A buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length The number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on error. + * + * \since This function is available since SDL 3.0.0. +*/ +extern DECLSPEC int SDLCALL SDL_hid_get_input_report(SDL_hid_device *dev, unsigned char *data, size_t length); + /** * Close a HID device. * @@ -441,6 +497,26 @@ extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev */ extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int string_index, wchar_t *string, size_t maxlen); +/** + * Get the device info from a HID device. + * + * \param dev A device handle returned from SDL_hid_open(). + * \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL in the case of failure; call SDL_GetError() for more information. This struct is valid until the device is closed with SDL_hid_close(). + */ +extern DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hid_device *dev); + +/** + * Get a report descriptor from a HID device. + * + * User has to provide a preallocated buffer where descriptor will be copied to. The recommended size for a preallocated buffer is 4096 bytes. + * + * \param dev A device handle returned from SDL_hid_open(). + * \param buf The buffer to copy descriptor into. + * \param buf_size The size of the buffer in bytes. + * \returns the number of bytes actually copied, or -1 on error; call SDL_GetError() for more information. + */ +extern DECLSPEC int SDLCALL SDL_hid_get_report_descriptor(SDL_hid_device *dev, unsigned char *buf, size_t buf_size); + /** * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers * diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 404e77920afbb..7f82956d3fa59 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -286,6 +286,8 @@ typedef uint64_t Uint64; #define SDL_SCANF_FORMAT_STRING #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) #else #if defined(_MSC_VER) && (_MSC_VER >= 1600) /* VS 2010 and above */ #include @@ -312,9 +314,13 @@ typedef uint64_t Uint64; #ifdef __GNUC__ #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ +#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wscanf__, fmtargnumber, fmtargnumber+1 ))) */ #else #define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) #define SDL_SCANF_VARARG_FUNC( fmtargnumber ) +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) +#define SDL_WSCANF_VARARG_FUNC( fmtargnumber ) #endif #endif /* SDL_DISABLE_ANALYZE_MACROS */ @@ -536,6 +542,7 @@ extern DECLSPEC int SDLCALL SDL_wcscmp(const wchar_t *str1, const wchar_t *str2) extern DECLSPEC int SDLCALL SDL_wcsncmp(const wchar_t *str1, const wchar_t *str2, size_t maxlen); extern DECLSPEC int SDLCALL SDL_wcscasecmp(const wchar_t *str1, const wchar_t *str2); extern DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar_t *str2, size_t len); +extern DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, int base); extern DECLSPEC size_t SDLCALL SDL_strlen(const char *str); extern DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); @@ -576,7 +583,9 @@ extern DECLSPEC int SDLCALL SDL_strncasecmp(const char *str1, const char *str2, extern DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); extern DECLSPEC int SDLCALL SDL_vsscanf(const char *text, const char *fmt, va_list ap); extern DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ... ) SDL_PRINTF_VARARG_FUNC(3); +extern DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ... ) SDL_WPRINTF_VARARG_FUNC(3); extern DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, va_list ap); +extern DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, const wchar_t *fmt, va_list ap); extern DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, const char *fmt, va_list ap); diff --git a/include/build_config/SDL_build_config.h.cmake b/include/build_config/SDL_build_config.h.cmake index 13005525cb045..928360fdd3f58 100644 --- a/include/build_config/SDL_build_config.h.cmake +++ b/include/build_config/SDL_build_config.h.cmake @@ -102,6 +102,7 @@ #cmakedefine HAVE__WCSICMP 1 #cmakedefine HAVE_WCSNCASECMP 1 #cmakedefine HAVE__WCSNICMP 1 +#cmakedefine HAVE_WCSTOL 1 #cmakedefine HAVE_STRLEN 1 #cmakedefine HAVE_STRLCPY 1 #cmakedefine HAVE_STRLCAT 1 diff --git a/src/audio/coreaudio/SDL_coreaudio.m b/src/audio/coreaudio/SDL_coreaudio.m index f740961ee111f..1628c2c49f244 100644 --- a/src/audio/coreaudio/SDL_coreaudio.m +++ b/src/audio/coreaudio/SDL_coreaudio.m @@ -291,7 +291,7 @@ static OSStatus device_list_changed(AudioObjectID systemObj, UInt32 num_addr, co static BOOL session_active = NO; -static void pause_audio_devices() +static void pause_audio_devices(void) { int i; @@ -307,7 +307,7 @@ static void pause_audio_devices() } } -static void resume_audio_devices() +static void resume_audio_devices(void) { int i; diff --git a/src/core/linux/SDL_udev.c b/src/core/linux/SDL_udev.c index 973e2da9dacc0..73d3e74735994 100644 --- a/src/core/linux/SDL_udev.c +++ b/src/core/linux/SDL_udev.c @@ -64,6 +64,7 @@ static int SDL_UDEV_load_syms(void) SDL_UDEV_SYM(udev_device_get_action); SDL_UDEV_SYM(udev_device_get_devnode); + SDL_UDEV_SYM(udev_device_get_syspath); SDL_UDEV_SYM(udev_device_get_subsystem); SDL_UDEV_SYM(udev_device_get_parent_with_subsystem_devtype); SDL_UDEV_SYM(udev_device_get_property_value); diff --git a/src/core/linux/SDL_udev.h b/src/core/linux/SDL_udev.h index f5e831410f6e8..2f44e929452c0 100644 --- a/src/core/linux/SDL_udev.h +++ b/src/core/linux/SDL_udev.h @@ -56,6 +56,7 @@ typedef struct SDL_UDEV_Symbols { const char *(*udev_device_get_action)(struct udev_device *); const char *(*udev_device_get_devnode)(struct udev_device *); + const char *(*udev_device_get_syspath)(struct udev_device *); const char *(*udev_device_get_subsystem)(struct udev_device *); struct udev_device *(*udev_device_get_parent_with_subsystem_devtype)(struct udev_device *udev_device, const char *subsystem, const char *devtype); const char *(*udev_device_get_property_value)(struct udev_device *, const char *); diff --git a/src/dynapi/SDL_dynapi.c b/src/dynapi/SDL_dynapi.c index cc97d232fc3b6..d09fe9e6ef088 100644 --- a/src/dynapi/SDL_dynapi.c +++ b/src/dynapi/SDL_dynapi.c @@ -123,6 +123,16 @@ static void SDL_InitDynamicAPI(void); va_end(ap); \ return retval; \ } \ + _static int SDLCALL SDL_swprintf##name(SDL_OUT_Z_CAP(maxlen) wchar_t *buf, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) \ + { \ + int retval; \ + va_list ap; \ + initcall; \ + va_start(ap, fmt); \ + retval = jump_table.SDL_vswprintf(buf, maxlen, fmt, ap); \ + va_end(ap); \ + return retval; \ + } \ _static int SDLCALL SDL_asprintf##name(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) \ { \ int retval; \ diff --git a/src/dynapi/SDL_dynapi.sym b/src/dynapi/SDL_dynapi.sym index 816913e4ed2dc..4956c8411e844 100644 --- a/src/dynapi/SDL_dynapi.sym +++ b/src/dynapi/SDL_dynapi.sym @@ -858,6 +858,12 @@ SDL3_0.0.0 { SDL_GetDisplayContentScale; SDL_GetWindowDisplayScale; SDL_GetWindowPixelDensity; + SDL_wcstol; + SDL_swprintf; + SDL_vswprintf; + SDL_hid_get_input_report; + SDL_hid_get_device_info; + SDL_hid_get_report_descriptor; # extra symbols go here (don't modify this line) local: *; }; diff --git a/src/dynapi/SDL_dynapi_overrides.h b/src/dynapi/SDL_dynapi_overrides.h index 020eecc5c8b38..ebd6a45d85a9d 100644 --- a/src/dynapi/SDL_dynapi_overrides.h +++ b/src/dynapi/SDL_dynapi_overrides.h @@ -884,3 +884,9 @@ #define SDL_GetDisplayContentScale SDL_GetDisplayContentScale_REAL #define SDL_GetWindowDisplayScale SDL_GetWindowDisplayScale_REAL #define SDL_GetWindowPixelDensity SDL_GetWindowPixelDensity_REAL +#define SDL_wcstol SDL_wcstol_REAL +#define SDL_swprintf SDL_swprintf_REAL +#define SDL_vswprintf SDL_vswprintf_REAL +#define SDL_hid_get_input_report SDL_hid_get_input_report_REAL +#define SDL_hid_get_device_info SDL_hid_get_device_info_REAL +#define SDL_hid_get_report_descriptor SDL_hid_get_report_descriptor_REAL diff --git a/src/dynapi/SDL_dynapi_procs.h b/src/dynapi/SDL_dynapi_procs.h index fa6e6b6f43c11..8d65e1febd873 100644 --- a/src/dynapi/SDL_dynapi_procs.h +++ b/src/dynapi/SDL_dynapi_procs.h @@ -41,6 +41,7 @@ SDL_DYNAPI_PROC(void,SDL_LogWarn,(int a, SDL_PRINTF_FORMAT_STRING const char *b, SDL_DYNAPI_PROC(int,SDL_SetError,(SDL_PRINTF_FORMAT_STRING const char *a, ...),(a),return) SDL_DYNAPI_PROC(int,SDL_asprintf,(char **a, SDL_PRINTF_FORMAT_STRING const char *b, ...),(a,b),return) SDL_DYNAPI_PROC(int,SDL_snprintf,(SDL_OUT_Z_CAP(b) char *a, size_t b, SDL_PRINTF_FORMAT_STRING const char *c, ...),(a,b,c),return) +SDL_DYNAPI_PROC(int,SDL_swprintf,(SDL_OUT_Z_CAP(b) wchar_t *a, size_t b, SDL_PRINTF_FORMAT_STRING const wchar_t *c, ...),(a,b,c),return) SDL_DYNAPI_PROC(int,SDL_sscanf,(const char *a, SDL_SCANF_FORMAT_STRING const char *b, ...),(a,b),return) #endif @@ -796,7 +797,7 @@ SDL_DYNAPI_PROC(int,SDL_hid_get_product_string,(SDL_hid_device *a, wchar_t *b, s SDL_DYNAPI_PROC(int,SDL_hid_get_serial_number_string,(SDL_hid_device *a, wchar_t *b, size_t c),(a,b,c),return) SDL_DYNAPI_PROC(int,SDL_hid_init,(void),(),return) SDL_DYNAPI_PROC(SDL_hid_device*,SDL_hid_open,(unsigned short a, unsigned short b, const wchar_t *c),(a,b,c),return) -SDL_DYNAPI_PROC(SDL_hid_device*,SDL_hid_open_path,(const char *a, int b),(a,b),return) +SDL_DYNAPI_PROC(SDL_hid_device*,SDL_hid_open_path,(const char *a),(a),return) SDL_DYNAPI_PROC(int,SDL_hid_read,(SDL_hid_device *a, unsigned char *b, size_t c),(a,b,c),return) SDL_DYNAPI_PROC(int,SDL_hid_read_timeout,(SDL_hid_device *a, unsigned char *b, size_t c, int d),(a,b,c,d),return) SDL_DYNAPI_PROC(int,SDL_hid_send_feature_report,(SDL_hid_device *a, const unsigned char *b, size_t c),(a,b,c),return) @@ -929,3 +930,8 @@ SDL_DYNAPI_PROC(char*,SDL_GetPath,(SDL_Folder a),(a),return) SDL_DYNAPI_PROC(float,SDL_GetDisplayContentScale,(SDL_DisplayID a),(a),return) SDL_DYNAPI_PROC(float,SDL_GetWindowDisplayScale,(SDL_Window *a),(a),return) SDL_DYNAPI_PROC(float,SDL_GetWindowPixelDensity,(SDL_Window *a),(a),return) +SDL_DYNAPI_PROC(long,SDL_wcstol,(const wchar_t *a, wchar_t **b, int c),(a,b,c),return) +SDL_DYNAPI_PROC(int,SDL_vswprintf,(wchar_t *a, size_t b, const wchar_t *c, va_list d),(a,b,c,d),return) +SDL_DYNAPI_PROC(int,SDL_hid_get_input_report,(SDL_hid_device *a, unsigned char *b, size_t c),(a,b,c),return) +SDL_DYNAPI_PROC(SDL_hid_device_info*,SDL_hid_get_device_info,(SDL_hid_device *a),(a),return) +SDL_DYNAPI_PROC(int,SDL_hid_get_report_descriptor,(SDL_hid_device *a, unsigned char *b, size_t c),(a,b,c),return) diff --git a/src/dynapi/gendynapi.py b/src/dynapi/gendynapi.py index ada149a826f3e..0f6284ab268e5 100755 --- a/src/dynapi/gendynapi.py +++ b/src/dynapi/gendynapi.py @@ -144,6 +144,7 @@ def main(): func = func.replace("SDL_PRINTF_VARARG_FUNC(1)", ""); func = func.replace("SDL_PRINTF_VARARG_FUNC(2)", ""); func = func.replace("SDL_PRINTF_VARARG_FUNC(3)", ""); + func = func.replace("SDL_WPRINTF_VARARG_FUNC(3)", ""); func = func.replace("SDL_SCANF_VARARG_FUNC(2)", ""); func = func.replace("__attribute__((analyzer_noreturn))", ""); func = func.replace("SDL_MALLOC", ""); diff --git a/src/hidapi/.appveyor.yml b/src/hidapi/.appveyor.yml new file mode 100644 index 0000000000000..210b3fa4636ff --- /dev/null +++ b/src/hidapi/.appveyor.yml @@ -0,0 +1,31 @@ +environment: + matrix: + - BUILD_ENV: msbuild + arch: x64 + - BUILD_ENV: msbuild + arch: Win32 + - BUILD_ENV: cygwin + +for: + - + matrix: + only: + - BUILD_ENV: msbuild + + os: Visual Studio 2015 + + build_script: + - cmd: msbuild .\windows\hidapi.sln /p:Configuration=Release /p:Platform=%arch% /logger:"C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll" + + - + matrix: + only: + - BUILD_ENV: cygwin + + os: Visual Studio 2022 + + install: + - cmd: C:\cygwin64\setup-x86_64.exe --quiet-mode --no-shortcuts --upgrade-also --packages autoconf,automake + + build_script: + - cmd: C:\cygwin64\bin\bash -exlc "cd $APPVEYOR_BUILD_FOLDER; ./bootstrap; ./configure; make" diff --git a/src/hidapi/.builds/freebsd.yml b/src/hidapi/.builds/freebsd.yml new file mode 100644 index 0000000000000..1679b03c386b4 --- /dev/null +++ b/src/hidapi/.builds/freebsd.yml @@ -0,0 +1,34 @@ +image: freebsd/latest +packages: +- autoconf +- automake +- gmake +- libiconv +- libtool +- pkgconf +- cmake +- ninja +sources: +- https://github.com/libusb/hidapi +tasks: +- configure: | + cd hidapi + echo Configure Autotools build + ./bootstrap + ./configure + echo Configure CMake build + mkdir -p build install_cmake + cmake -GNinja -B build -S . -DCMAKE_INSTALL_PREFIX=install_cmake +- build-autotools: | + cd hidapi + make + make DESTDIR=$PWD/root install + make clean +- build-cmake: | + cd hidapi/build + ninja + ninja install + ninja clean +- build-manual: | + cd hidapi/libusb + gmake -f Makefile-manual diff --git a/src/hidapi/.builds/netbsd.yml b/src/hidapi/.builds/netbsd.yml new file mode 100644 index 0000000000000..413d91c020163 --- /dev/null +++ b/src/hidapi/.builds/netbsd.yml @@ -0,0 +1,18 @@ +image: netbsd/latest +packages: +- cmake +- pkgconf +- libusb1 +- libiconv +sources: +- https://github.com/libusb/hidapi +tasks: +- configure: | + cd hidapi + mkdir -p build install + cmake -B build -S . -DCMAKE_INSTALL_PREFIX=install +- build: | + cd hidapi/build + make + make install + make clean diff --git a/src/hidapi/.builds/openbsd.yml b/src/hidapi/.builds/openbsd.yml new file mode 100644 index 0000000000000..780df7f661a4c --- /dev/null +++ b/src/hidapi/.builds/openbsd.yml @@ -0,0 +1,19 @@ +image: openbsd/latest +packages: +- cmake +- pkgconf +- libusb1-- +- libiconv +- ninja +sources: +- https://github.com/libusb/hidapi +tasks: +- configure: | + cd hidapi + mkdir -p build install + cmake -GNinja -B build -S . -DCMAKE_INSTALL_PREFIX=install +- build: | + cd hidapi/build + ninja + ninja install + ninja clean diff --git a/src/hidapi/.cirrus.yml b/src/hidapi/.cirrus.yml new file mode 100644 index 0000000000000..b4cf201667fe8 --- /dev/null +++ b/src/hidapi/.cirrus.yml @@ -0,0 +1,33 @@ +alpine_task: + container: + image: alpine:latest + install_script: apk add autoconf automake g++ gcc libusb-dev libtool linux-headers eudev-dev make musl-dev + script: + - ./bootstrap + - ./configure || { cat config.log; exit 1; } + - make + - make install + +freebsd11_task: + freebsd_instance: + image: freebsd-11-2-release-amd64 + install_script: + - pkg install -y + autoconf automake libiconv libtool pkgconf + script: + - ./bootstrap + - ./configure || { cat config.log; exit 1; } + - make + - make install + +freebsd12_task: + freebsd_instance: + image: freebsd-12-1-release-amd64 + install_script: + - pkg install -y + autoconf automake libiconv libtool pkgconf + script: + - ./bootstrap + - ./configure || { cat config.log; exit 1; } + - make + - make install diff --git a/src/hidapi/.gitattributes b/src/hidapi/.gitattributes new file mode 100644 index 0000000000000..edb79febc569b --- /dev/null +++ b/src/hidapi/.gitattributes @@ -0,0 +1,7 @@ +* text=auto + +*.sln text eol=crlf +*.vcproj text eol=crlf + +bootstrap text eol=lf +configure.ac text eol=lf diff --git a/src/hidapi/.github/workflows/builds.yml b/src/hidapi/.github/workflows/builds.yml new file mode 100644 index 0000000000000..056df2cc08c81 --- /dev/null +++ b/src/hidapi/.github/workflows/builds.yml @@ -0,0 +1,540 @@ +name: GitHub Builds + +on: [push, pull_request] + +env: + NIX_COMPILE_FLAGS: -Wall -Wextra -pedantic -Werror + MSVC_COMPILE_FLAGS: /W4 /WX + +jobs: + macos-automake: + + runs-on: macos-latest + + steps: + - uses: actions/checkout@v3 + - name: Install build tools + run: brew install autoconf automake libtool + - name: Configure Automake + run: | + ./bootstrap + ./configure --prefix=$(pwd)/install + - name: Build Automake + run: | + make + make install + - name: Clean build + run: make clean + - name: Build Manual makefile + working-directory: mac + run: make -f Makefile-manual + + + macos-cmake: + + runs-on: macos-latest + + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: brew install meson ninja + - name: Configure CMake + run: | + rm -rf build install + cmake -B build/shared -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install/shared -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cmake -B build/static -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install/static -DBUILD_SHARED_LIBS=FALSE -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cmake -B build/framework -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install/framework -DCMAKE_FRAMEWORK=ON -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + - name: Build CMake Shared + working-directory: build/shared + run: make install + - name: Build CMake Static + working-directory: build/static + run: make install + - name: Build CMake Framework + working-directory: build/framework + run: make install + - name: Check artifacts + uses: andstor/file-existence-action@v2 + with: + files: "install/shared/lib/libhidapi.dylib, \ + install/shared/include/hidapi/hidapi.h, \ + install/shared/include/hidapi/hidapi_darwin.h, \ + install/static/lib/libhidapi.a, \ + install/static/include/hidapi/hidapi.h, \ + install/static/include/hidapi/hidapi_darwin.h, \ + install/framework/lib/hidapi.framework/hidapi, \ + install/framework/lib/hidapi.framework/Headers/hidapi.h, \ + install/framework/lib/hidapi.framework/Headers/hidapi_darwin.h" + fail: true + - name: Check CMake Export Package Shared + run: | + cmake \ + -B build/shared_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/shared \ + -DCMAKE_INSTALL_PREFIX=install/shared_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/shared_test + make install + - name: Check CMake Export Package Static + run: | + cmake \ + -B build/static_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/static \ + -DCMAKE_INSTALL_PREFIX=install/static_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/static_test + make install + + - name: Check Meson build + run: | + meson setup build_meson hidapisrc + cd build_meson + ninja + + + ubuntu-cmake: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: | + sudo apt update + sudo apt install libudev-dev libusb-1.0-0-dev python3-pip ninja-build + sudo -H pip3 install meson + - name: Configure CMake + run: | + rm -rf build install + cmake -B build/shared -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install/shared -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cmake -B build/static -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install/static -DBUILD_SHARED_LIBS=FALSE -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + - name: Build CMake Shared + working-directory: build/shared + run: make install + - name: Build CMake Static + working-directory: build/static + run: make install + - name: Check artifacts + uses: andstor/file-existence-action@v2 + with: + files: "install/shared/lib/libhidapi-libusb.so, \ + install/shared/lib/libhidapi-hidraw.so, \ + install/shared/include/hidapi/hidapi.h, \ + install/shared/include/hidapi/hidapi_libusb.h, \ + install/static/lib/libhidapi-libusb.a, \ + install/static/lib/libhidapi-hidraw.a, \ + install/static/include/hidapi/hidapi.h, \ + install/static/include/hidapi/hidapi_libusb.h" + fail: true + - name: Check CMake Export Package Shared + run: | + cmake \ + -B build/shared_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/shared \ + -DCMAKE_INSTALL_PREFIX=install/shared_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/shared_test + make install + - name: Check CMake Export Package Static + run: | + cmake \ + -B build/static_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/static \ + -DCMAKE_INSTALL_PREFIX=install/static_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/static_test + make install + + - name: Check Meson build + run: | + meson setup build_meson hidapisrc + cd build_meson + ninja + + + windows-cmake: + + runs-on: windows-latest + + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: | + choco install ninja + pip3 install meson + refreshenv + - name: Configure CMake MSVC + shell: cmd + run: | + cmake -B build\msvc -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_PP_DATA_DUMP=ON -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install\msvc -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=%MSVC_COMPILE_FLAGS%" + - name: Build CMake MSVC + working-directory: build/msvc + run: cmake --build . --config RelWithDebInfo --target install + - name: Check artifacts MSVC + uses: andstor/file-existence-action@v2 + with: + files: "install/msvc/lib/hidapi.lib, \ + install/msvc/bin/hidapi.dll, \ + install/msvc/include/hidapi/hidapi.h, \ + install/msvc/include/hidapi/hidapi_winapi.h" + fail: true + - name: Check CMake Export Package + shell: cmd + run: | + cmake ^ + -B build\msvc_test ^ + -S hidapisrc\hidtest ^ + -Dhidapi_ROOT=install\msvc ^ + -DCMAKE_INSTALL_PREFIX=install\msvc_test ^ + "-DCMAKE_C_FLAGS=%MSVC_COMPILE_FLAGS%" + cd build\msvc_test + cmake --build . --target install + - name: Run CTest MSVC + shell: cmd + working-directory: build/msvc + run: ctest -C RelWithDebInfo --rerun-failed --output-on-failure + + - name: Configure CMake NMake + shell: cmd + run: | + call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat" + cmake -G"NMake Makefiles" -B build\nmake -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_PP_DATA_DUMP=ON -DHIDAPI_ENABLE_ASAN=ON -DCMAKE_INSTALL_PREFIX=install\nmake -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=%MSVC_COMPILE_FLAGS%" + - name: Build CMake NMake + working-directory: build\nmake + shell: cmd + run: | + call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat" + nmake install + - name: Check artifacts NMake + uses: andstor/file-existence-action@v2 + with: + files: "install/nmake/lib/hidapi.lib, \ + install/nmake/bin/hidapi.dll, \ + install/nmake/include/hidapi/hidapi.h, \ + install/nmake/include/hidapi/hidapi_winapi.h" + fail: true + - name: Check CMake Export Package NMake + shell: cmd + run: | + call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat" + cmake ^ + -G"NMake Makefiles" ^ + -B build\nmake_test ^ + -S hidapisrc\hidtest ^ + -Dhidapi_ROOT=install\nmake ^ + -DCMAKE_INSTALL_PREFIX=install\nmake_test ^ + "-DCMAKE_C_FLAGS=%MSVC_COMPILE_FLAGS%" + cd build\nmake_test + nmake install + - name: Run CTest NMake + working-directory: build\nmake + run: ctest --rerun-failed --output-on-failure + + - name: Configure CMake MinGW + shell: cmd + run: | + cmake -G"MinGW Makefiles" -B build\mingw -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_PP_DATA_DUMP=ON -DCMAKE_INSTALL_PREFIX=install\mingw -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=%NIX_COMPILE_FLAGS%" + - name: Build CMake MinGW + working-directory: build\mingw + run: cmake --build . --target install + - name: Check artifacts MinGW + uses: andstor/file-existence-action@v2 + with: + files: "install/mingw/lib/libhidapi.dll.a, \ + install/mingw/bin/libhidapi.dll, \ + install/mingw/include/hidapi/hidapi.h, \ + install/mingw/include/hidapi/hidapi_winapi.h" + fail: true + - name: Check CMake Export Package MinGW + shell: cmd + run: | + cmake ^ + -G"MinGW Makefiles" ^ + -B build\mingw_test ^ + -S hidapisrc\hidtest ^ + -Dhidapi_ROOT=install\mingw ^ + -DCMAKE_INSTALL_PREFIX=install\mingw_test ^ + "-DCMAKE_C_FLAGS=%NIX_COMPILE_FLAGS%" + cd build\mingw_test + cmake --build . --target install + - name: Run CTest MinGW + working-directory: build\mingw + run: ctest --rerun-failed --output-on-failure + + - name: Check Meson build + shell: cmd + run: | + call "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Auxiliary\Build\vcvars64.bat" + meson setup build_meson hidapisrc + cd build_meson + ninja + + + windows-msbuild: + + runs-on: windows-latest + + steps: + - uses: actions/checkout@v3 + - uses: microsoft/setup-msbuild@v1.1 + - name: MSBuild x86 + run: msbuild windows\hidapi.sln /p:Configuration=Release /p:Platform=Win32 + - name: Check artifacts x86 + uses: andstor/file-existence-action@v2 + with: + files: "windows/Release/hidapi.dll, windows/Release/hidapi.lib, windows/Release/hidapi.pdb" + fail: true + - name: MSBuild x64 + run: msbuild windows\hidapi.sln /p:Configuration=Release /p:Platform=x64 + - name: Check artifacts x64 + uses: andstor/file-existence-action@v2 + with: + files: "windows/x64/Release/hidapi.dll, windows/x64/Release/hidapi.lib, windows/x64/Release/hidapi.pdb" + fail: true + - name: Gather artifacts + run: | + md artifacts + md artifacts\x86 + md artifacts\x64 + md artifacts\include + Copy-Item "windows\Release\hidapi.dll","windows\Release\hidapi.lib","windows\Release\hidapi.pdb" -Destination "artifacts\x86" + Copy-Item "windows\x64\Release\hidapi.dll","windows\x64\Release\hidapi.lib","windows\x64\Release\hidapi.pdb" -Destination "artifacts\x64" + Copy-Item "hidapi\hidapi.h","windows\hidapi_winapi.h" -Destination "artifacts\include" + - name: Upload artifacts + uses: actions/upload-artifact@v3 + with: + name: hidapi-win + path: artifacts/ + retention-days: ${{ (github.event_name == 'pull_request' || github.ref_name != 'master') && 7 || 90 }} + + + fedora-mingw: + + runs-on: ubuntu-latest + container: fedora:latest + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: sudo dnf install -y autoconf automake libtool mingw64-gcc cmake ninja-build make + - name: Configure CMake + run: | + rm -rf build install + mingw64-cmake -B build/shared-cmake -S hidapisrc -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/shared-cmake -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + mingw64-cmake -B build/static-cmake -S hidapisrc -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/static-cmake -DBUILD_SHARED_LIBS=FALSE -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + - name: Configure Automake + working-directory: hidapisrc + run: | + ./bootstrap + mingw64-configure + - name: Build CMake Shared + working-directory: build/shared-cmake + run: ninja install + - name: Build CMake Static + working-directory: build/static-cmake + run: ninja install + - name: Build Automake + working-directory: hidapisrc + run: | + make + make DESTDIR=$PWD/../install/automake install + make clean + - name: Build manual Makefile + working-directory: hidapisrc/windows + run: make -f Makefile-manual OS=MINGW CC=x86_64-w64-mingw32-gcc + - name: Check artifacts + uses: andstor/file-existence-action@v2 + with: + files: "install/shared-cmake/bin/libhidapi.dll, \ + install/shared-cmake/lib/libhidapi.dll.a, \ + install/shared-cmake/include/hidapi/hidapi.h, \ + install/shared-cmake/include/hidapi/hidapi_winapi.h, \ + install/static-cmake/lib/libhidapi.a, \ + install/static-cmake/include/hidapi/hidapi.h, \ + install/static-cmake/include/hidapi/hidapi_winapi.h" + fail: true + - name: Check CMake Export Package Shared + run: | + mingw64-cmake \ + -GNinja \ + -B build/shared_test \ + -S hidapisrc/hidtest \ + -Dhidapi_DIR=$PWD/install/shared-cmake/lib/cmake/hidapi \ + -DCMAKE_INSTALL_PREFIX=install/shared_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/shared_test + ninja install + - name: Check CMake Export Package Static + run: | + mingw64-cmake \ + -GNinja \ + -B build/static_test \ + -S hidapisrc/hidtest \ + -Dhidapi_DIR=$PWD/install/static-cmake/lib/cmake/hidapi \ + -DCMAKE_INSTALL_PREFIX=install/static_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/static_test + ninja install + + + archlinux: + + runs-on: ubuntu-latest + container: archlinux:latest + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: | + pacman -Sy + pacman -S --noconfirm gcc pkg-config autoconf automake libtool libusb libudev0 cmake make + - name: Configure CMake + run: | + rm -rf build install + cmake -B build/shared-cmake -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/shared-cmake -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cmake -B build/static-cmake -S hidapisrc -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/static-cmake -DBUILD_SHARED_LIBS=FALSE -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + - name: Configure Automake + working-directory: hidapisrc + run: | + ./bootstrap + ./configure + - name: Build CMake Shared + working-directory: build/shared-cmake + run: make install + - name: Build CMake Static + working-directory: build/static-cmake + run: make install + - name: Build Automake + working-directory: hidapisrc + run: | + make + make DESTDIR=$PWD/../install/automake install + make clean + - name: Build manual Makefile + run: | + cd hidapisrc/linux + make -f Makefile-manual + cd ../libusb + make -f Makefile-manual + - name: Check artifacts + uses: andstor/file-existence-action@v2 + with: + files: "install/shared-cmake/lib/libhidapi-libusb.so, \ + install/shared-cmake/lib/libhidapi-hidraw.so, \ + install/shared-cmake/include/hidapi/hidapi.h, \ + install/shared-cmake/include/hidapi/hidapi_libusb.h, \ + install/static-cmake/lib/libhidapi-libusb.a, \ + install/static-cmake/lib/libhidapi-hidraw.a, \ + install/static-cmake/include/hidapi/hidapi.h, \ + install/static-cmake/include/hidapi/hidapi_libusb.h" + fail: true + - name: Check CMake Export Package Shared + run: | + cmake \ + -B build/shared_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/shared-cmake \ + -DCMAKE_INSTALL_PREFIX=install/shared_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/shared_test + make install + - name: Check CMake Export Package Static + run: | + cmake \ + -B build/static_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/static-cmake \ + -DCMAKE_INSTALL_PREFIX=install/static_test \ + "-DCMAKE_C_FLAGS=${NIX_COMPILE_FLAGS}" + cd build/static_test + make install + + + alpine: + + runs-on: ubuntu-latest + container: alpine:edge + env: + # A bug in musl: https://www.openwall.com/lists/musl/2020/01/20/2 + ALPINE_COMPILE_FLAGS: ${NIX_COMPILE_FLAGS} -Wno-overflow + steps: + - uses: actions/checkout@v3 + with: + path: hidapisrc + - name: Install dependencies + run: | + apk add gcc musl-dev autoconf automake libtool eudev-dev libusb-dev linux-headers cmake ninja make + - name: Configure CMake + run: | + rm -rf build install + cmake -B build/shared-cmake -S hidapisrc -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/shared-cmake -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${ALPINE_COMPILE_FLAGS}" + cmake -B build/static-cmake -S hidapisrc -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DCMAKE_INSTALL_PREFIX=install/static-cmake -DBUILD_SHARED_LIBS=FALSE -DHIDAPI_BUILD_HIDTEST=ON "-DCMAKE_C_FLAGS=${ALPINE_COMPILE_FLAGS}" + - name: Configure Automake + working-directory: hidapisrc + run: | + ./bootstrap + ./configure + - name: Build CMake Shared + working-directory: build/shared-cmake + run: ninja install + - name: Build CMake Static + working-directory: build/static-cmake + run: ninja install + - name: Build Automake + working-directory: hidapisrc + run: | + make + make DESTDIR=$PWD/../install/automake install + make clean + - name: Build manual Makefile + run: | + cd hidapisrc/linux + make -f Makefile-manual + cd ../libusb + make -f Makefile-manual + - name: Check artifacts + uses: andstor/file-existence-action@v2 + with: + files: "install/shared-cmake/lib/libhidapi-libusb.so, \ + install/shared-cmake/lib/libhidapi-hidraw.so, \ + install/shared-cmake/include/hidapi/hidapi.h, \ + install/shared-cmake/include/hidapi/hidapi_libusb.h, \ + install/static-cmake/lib/libhidapi-libusb.a, \ + install/static-cmake/lib/libhidapi-hidraw.a, \ + install/static-cmake/include/hidapi/hidapi.h, \ + install/static-cmake/include/hidapi/hidapi_libusb.h" + fail: true + - name: Check CMake Export Package Shared + run: | + cmake \ + -GNinja \ + -B build/shared_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/shared-cmake \ + -DCMAKE_INSTALL_PREFIX=install/shared_test \ + "-DCMAKE_C_FLAGS=${ALPINE_COMPILE_FLAGS}" + cd build/shared_test + ninja install + - name: Check CMake Export Package Static + run: | + cmake \ + -GNinja \ + -B build/static_test \ + -S hidapisrc/hidtest \ + -Dhidapi_ROOT=install/static-cmake \ + -DCMAKE_INSTALL_PREFIX=install/static_test \ + "-DCMAKE_C_FLAGS=${ALPINE_COMPILE_FLAGS}" + cd build/static_test + ninja install diff --git a/src/hidapi/.github/workflows/checks.yml b/src/hidapi/.github/workflows/checks.yml new file mode 100644 index 0000000000000..e03dc66ee20e0 --- /dev/null +++ b/src/hidapi/.github/workflows/checks.yml @@ -0,0 +1,196 @@ +name: Checks +run-name: Code checks for '${{ github.ref_name }}' + +# General comment: +# Coverity doesn't support merging or including reports from multible machine/platforms (at least not officially). +# But otherwise there is no good way to keep the issues from all platforms at Coverity Scans at once. +# This script uses undocumented (but appears to be working) hack: +# The build logs from one machine/platform gets moved to a next once, +# and "fixed" so that cov-build can append logs from the next platform. +# The "fix" is based on the fact, that Coverity perfectly allows appending logs from multiple builds +# that are done *on the same host* machine. + +on: + # On-demand run + workflow_dispatch: + # Weekly run + schedule: + - cron: '30 5 * * 0' + +jobs: + coverity-windows: + runs-on: windows-latest + + steps: + - uses: actions/checkout@v3 + with: + path: src + - name: Setup MSVC + uses: TheMrMilchmann/setup-msvc-dev@v2.0.0 + with: + arch: x64 + - name: Configure + run: | + cmake -B build -S src -G"NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_HIDTEST=ON + - name: Lookup Coverity Build Tool hash + id: coverity-cache-lookup + run: | + $coverity_hash=Invoke-RestMethod -Uri https://scan.coverity.com/download/cxx/win64 -Method Post -Body @{token='${{ secrets.COVERITY_SCAN_TOKEN }}';project='hidapi';md5=1} + echo "coverity_hash=$coverity_hash" >> $Env:GITHUB_OUTPUT + - name: Get cached Coverity Build Tool + id: cov-build-cache + uses: actions/cache@v3 + with: + path: cov-root + key: cov-root-cxx-win64-${{ steps.coverity-cache-lookup.outputs.coverity_hash }} + - name: Get and configure Coverity + if: steps.cov-build-cache.outputs.cache-hit != 'true' + run: | + Invoke-WebRequest -Uri https://scan.coverity.com/download/cxx/win64 -OutFile coverity.zip -Method Post -Body @{token='${{ secrets.COVERITY_SCAN_TOKEN }}';project='hidapi'} + Remove-Item 'cov-root' -Recurse -Force -ErrorAction SilentlyContinue + Expand-Archive coverity.zip -DestinationPath cov-root + + $cov_root=Get-ChildItem -Path 'cov-root' + $Env:PATH += ";$($cov_root.FullName)\bin" + cov-configure -msvc + - name: Make Coverity available in PATH + run: | + $cov_root=Get-ChildItem -Path 'cov-root' + echo "$($cov_root.FullName)\bin" >> $Env:GITHUB_PATH + - name: Build with Coverity + working-directory: build + run: | + cov-build --dir cov-int nmake + Rename-Item ".\cov-int\emit\$(hostname)" hostname + - name: Backup Coverity logs + uses: actions/upload-artifact@v3 + with: + name: coverity-logs-windows + path: build/cov-int + retention-days: 7 + + + coverity-macos: + runs-on: macos-latest + needs: [coverity-windows] + + steps: + - uses: actions/checkout@v3 + with: + path: src + - name: Install dependencies + run: brew install ninja + - name: Configure + run: | + cmake -B build -S src -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_HIDTEST=ON -DCMAKE_C_COMPILER=clang + - uses: actions/download-artifact@v3 + with: + name: coverity-logs-windows + path: build/cov-int + - name: Fixup cov-int + run: | + rm -f build/cov-int/emit/hostname/emit-db.lock build/cov-int/emit/hostname/emit-db.write-lock + mv build/cov-int/emit/hostname build/cov-int/emit/$(hostname) + - name: Lookup Coverity Build Tool hash + id: coverity-cache-lookup + shell: bash + run: | + hash=$(curl https://scan.coverity.com/download/cxx/Darwin --data "token=${{ secrets.COVERITY_SCAN_TOKEN }}&project=hidapi&md5=1") + echo "coverity_hash=${hash}" >> $GITHUB_OUTPUT + - name: Get cached Coverity Build Tool + id: cov-build-cache + uses: actions/cache@v3 + with: + path: cov-root + key: cov-root-cxx-Darwin-${{ steps.coverity-cache-lookup.outputs.coverity_hash }} + - name: Get and configure Coverity + if: steps.cov-build-cache.outputs.cache-hit != 'true' + run: | + curl https://scan.coverity.com/download/cxx/Darwin --output coverity.dmg --data "token=${{ secrets.COVERITY_SCAN_TOKEN }}&project=hidapi" + hdiutil attach coverity.dmg -mountroot coverity + export COV_DIR_NAME=$(ls -1 --color=never coverity) + rm -rf cov-root + mkdir cov-root + cp ./coverity/${COV_DIR_NAME}/${COV_DIR_NAME}.sh cov-root/ + cd cov-root/ + ./${COV_DIR_NAME}.sh + ./bin/cov-configure --clang + - name: Make Coverity available in PATH + run: echo "$(pwd)/cov-root/bin" >> $GITHUB_PATH + - name: Build with Coverity + working-directory: build + run: | + cov-build --dir cov-int --append-log ninja + mv cov-int/emit/$(hostname) cov-int/emit/hostname + - name: Backup Coverity logs + uses: actions/upload-artifact@v3 + with: + name: coverity-logs-windows-macos + path: build/cov-int + retention-days: 7 + + + coverity-ubuntu: + runs-on: ubuntu-latest + needs: [coverity-macos] + + steps: + - uses: actions/checkout@v3 + with: + path: src + - name: Install dependencies + run: sudo apt install libudev-dev libusb-1.0-0-dev ninja-build + - name: Configure + run: | + cmake -B build -S src -GNinja -DCMAKE_BUILD_TYPE=RelWithDebInfo -DHIDAPI_WITH_TESTS=ON -DHIDAPI_BUILD_HIDTEST=ON -DCMAKE_C_COMPILER=gcc + - uses: actions/download-artifact@v3 + with: + name: coverity-logs-windows-macos + path: build/cov-int + - name: Fixup cov-int + run: | + rm -f build/cov-int/emit/hostname/emit-db.lock build/cov-int/emit/hostname/emit-db.write-lock + mv build/cov-int/emit/hostname build/cov-int/emit/$(hostname) + - name: Lookup Coverity Build Tool hash + id: coverity-cache-lookup + shell: bash + run: | + hash=$(curl https://scan.coverity.com/download/cxx/linux64 --data "token=${{ secrets.COVERITY_SCAN_TOKEN }}&project=hidapi&md5=1") + echo "coverity_hash=${hash}" >> $GITHUB_OUTPUT + - name: Get cached Coverity Build Tool + id: cov-build-cache + uses: actions/cache@v3 + with: + path: cov-root + key: cov-root-cxx-linux64-${{ steps.coverity-cache-lookup.outputs.coverity_hash }} + - name: Get and configure Coverity + if: steps.cov-build-cache.outputs.cache-hit != 'true' + run: | + curl https://scan.coverity.com/download/cxx/linux64 --output coverity.tar.gz --data "token=${{ secrets.COVERITY_SCAN_TOKEN }}&project=hidapi" + rm -rf cov-root + mkdir cov-root + tar -xzf coverity.tar.gz --strip 1 -C cov-root + ./cov-root/bin/cov-configure --gcc + - name: Make Coverity available in PATH + run: echo "$(pwd)/cov-root/bin" >> $GITHUB_PATH + - name: Build with Coverity + working-directory: build + run: | + cov-build --dir cov-int --append-log ninja + - name: Submit results to Coverity Scan + working-directory: build + run: | + tar -czf cov-int.tar.gz cov-int + curl --form token=${{ secrets.COVERITY_SCAN_TOKEN }} \ + --form email=${{ secrets.COVERITY_SCAN_EMAIL }} \ + --form file=@cov-int.tar.gz \ + --form version="$GITHUB_SHA" \ + --form description="Automatic HIDAPI build" \ + https://scan.coverity.com/builds?project=hidapi + mv cov-int/emit/$(hostname) cov-int/emit/hostname + - name: Backup Coverity logs + uses: actions/upload-artifact@v3 + with: + name: coverity-logs-windows-macos-linux + path: build/cov-int + retention-days: 7 diff --git a/src/hidapi/.github/workflows/docs.yaml b/src/hidapi/.github/workflows/docs.yaml new file mode 100644 index 0000000000000..4ec09a502ef96 --- /dev/null +++ b/src/hidapi/.github/workflows/docs.yaml @@ -0,0 +1,58 @@ +name: Docs + +on: + push: + branches: [master] + pull_request: + branches: [master] + +jobs: + build: + runs-on: ubuntu-latest + steps: + + - name: Install Doxygen static libclang deps + run: sudo apt-get install libclang1-12 libclang-cpp12 + + - name: Install Doxygen from SF binary archives + env: + DOXYGEN_VERSION: '1.9.6' + run: | + mkdir .doxygen && cd .doxygen + curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz + gunzip doxygen.tar.gz + tar xf doxygen.tar + cd doxygen-$DOXYGEN_VERSION + sudo make install + + - uses: actions/checkout@v3 + + - run: doxygen + working-directory: doxygen + + - name: Save doxygen docs as artifact + uses: actions/upload-artifact@v3 + with: + name: HIDAPI_doxygen_docs + path: ${{ github.workspace }}/doxygen/html + + deploy-docs: + runs-on: ubuntu-latest + needs: [build] + if: github.ref_type == 'branch' && github.ref_name == 'master' + concurrency: + group: "github-pages-deploy" + cancel-in-progress: true + steps: + - name: downlod artifact + uses: actions/download-artifact@v3 + with: + name: HIDAPI_doxygen_docs + path: docs + + - name: upload to github pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs + force_orphan: true diff --git a/src/hidapi/.gitignore b/src/hidapi/.gitignore new file mode 100644 index 0000000000000..048900e287b5c --- /dev/null +++ b/src/hidapi/.gitignore @@ -0,0 +1,32 @@ + +# Autotools-added generated files +Makefile.in +aclocal.m4 +ar-lib +autom4te.cache/ +config.* +configure +configure~ +compile +depcomp +install-sh +libusb/Makefile.in +linux/Makefile.in +ltmain.sh +mac/Makefile.in +missing +testgui/Makefile.in +windows/Makefile.in + +Makefile +stamp-h1 +libtool + +# macOS +.DS_Store + +# Qt Creator +CMakeLists.txt.user + +# doxgen output +doxygen/html/ diff --git a/src/hidapi/AUTHORS.txt b/src/hidapi/AUTHORS.txt index f311978d3333d..7193d71e0b0fe 100644 --- a/src/hidapi/AUTHORS.txt +++ b/src/hidapi/AUTHORS.txt @@ -10,7 +10,9 @@ Ludovic Rousseau : Bug fixes Correctness fixes +libusb/hidapi Team: + Development/maintainance since June 4th 2019 For a comprehensive list of contributions, see the commit list at github: - https://github.com/libusb/hidapi/commits/master + https://github.com/libusb/hidapi/graphs/contributors diff --git a/src/hidapi/BUILD.autotools.md b/src/hidapi/BUILD.autotools.md new file mode 100644 index 0000000000000..24b20a5af2b94 --- /dev/null +++ b/src/hidapi/BUILD.autotools.md @@ -0,0 +1,114 @@ +# Building HIDAPI using Autotools (deprecated) + +--- +**NOTE**: for all intentions and purposes the Autotools build scripts for HIDAPI are _deprecated_ and going to be obsolete in the future. +HIDAPI Team recommends using CMake build for HIDAPI. +If you are already using Autotools build scripts provided by HIDAPI, +consider switching to CMake build scripts as soon as possible. + +--- + +To be able to use Autotools to build HIDAPI, it has to be [installed](#installing-autotools)/available in the system. + +Make sure you've checked [prerequisites](BUILD.md#prerequisites) and installed all required dependencies. + +## Installing Autotools + +HIDAPI uses few specific tools/packages from Autotools: `autoconf`, `automake`, `libtool`. + +On different platforms or package managers, those could be named a bit differently or packaged together. +You'll have to check the documentation/package list for your specific package manager. + +### Linux + +On Ubuntu the tools are available via APT: + +```sh +sudo apt install autoconf automake libtool +``` + +### FreeBSD + +FreeBSD Autotools can be installed as: + +```sh +pkg_add -r autotools +``` + +Additionally, on FreeBSD you will need to install GNU make: +```sh +pkg_add -r gmake +``` + +## Building HIDAPI with Autotools + +A simple command list, to build HIDAPI with Autotools as a _shared library_ and install in into your system: + +```sh +./bootstrap # this prepares the configure script +./configure +make # build the library +make install # as root, or using sudo, this will install hidapi into your system +``` + +`./configure` can take several arguments which control the build. A few commonly used options: +```sh + --enable-testgui + # Enable the build of Foxit-based Test GUI. This requires Fox toolkit to + # be installed/available. See README.md#test-gui for remarks. + + --prefix=/usr + # Specify where you want the output headers and libraries to + # be installed. The example above will put the headers in + # /usr/include and the binaries in /usr/lib. The default is to + # install into /usr/local which is fine on most systems. + + --disable-shared + # By default, both shared and static libraries are going to be built/installed. + # This option disables shared library build, if only static library is required. +``` + + +## Cross Compiling + +This section talks about cross compiling HIDAPI for Linux using Autotools. +This is useful for using HIDAPI on embedded Linux targets. These +instructions assume the most raw kind of embedded Linux build, where all +prerequisites will need to be built first. This process will of course vary +based on your embedded Linux build system if you are using one, such as +OpenEmbedded or Buildroot. + +For the purpose of this section, it will be assumed that the following +environment variables are exported. +```sh +$ export STAGING=$HOME/out +$ export HOST=arm-linux +``` + +`STAGING` and `HOST` can be modified to suit your setup. + +### Prerequisites + +Depending on what backend you want to cross-compile, you also need to prepare the dependencies: +`libusb` for libusb HIDAPI backend, or `libudev` for hidraw HIDAPI backend. + +An example of cross-compiling `libusb`. From `libusb` source directory, run: +```sh +./configure --host=$HOST --prefix=$STAGING +make +make install +``` + +An example of cross-comping `libudev` is not covered by this section. +Check `libudev`'s documentation for details. + +### Building HIDAPI + +Build HIDAPI: +```sh +PKG_CONFIG_DIR= \ +PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ +PKG_CONFIG_SYSROOT_DIR=$STAGING \ +./configure --host=$HOST --prefix=$STAGING +# make / make install - same as for a regular build +``` diff --git a/src/hidapi/BUILD.cmake.md b/src/hidapi/BUILD.cmake.md new file mode 100644 index 0000000000000..9c51d0ce0b207 --- /dev/null +++ b/src/hidapi/BUILD.cmake.md @@ -0,0 +1,280 @@ +# Building HIDAPI using CMake + +To build HIDAPI with CMake, it has to be [installed](#installing-cmake)/available in the system. + +Make sure you've checked [prerequisites](BUILD.md#prerequisites) and installed all required dependencies. + +HIDAPI CMake build system allows you to build HIDAPI in two generally different ways: +1) As a [standalone package/library](#standalone-package-build); +2) As [part of a larger CMake project](#hidapi-as-a-subdirectory). + +**TL;DR**: if you're experienced developer and have been working with CMake projects or have been written some of your own - +most of this document may not be of interest for you; just check variables names, its default values and the target names. + +## Installing CMake + +CMake can be installed either using your system's package manager, +or by downloading an installer/prebuilt version from the [official website](https://cmake.org/download/). + +On most \*nix systems, the prefered way to install CMake is via package manager, +e.g. `sudo apt install cmake`. + +On Windows CMake could be provided by your development environment (e.g. by Visual Studio Installer or MinGW installer), +or you may install it system-wise using the installer from the official website. + +On macOS CMake may be installed by Homebrew/MacPorts or using the installer from the official website. + +## Standalone package build + +To build HIDAPI as a standalone package, you follow [general steps](https://cmake.org/runningcmake/) of building any CMake project. + +An example of building HIDAPI with CMake: +```sh +# precondition: create a somewhere on the filesystem (preferably outside of the HIDAPI source) +# this is the place where all intermediate/build files are going to be located +cd +# configure the build +cmake +# build it! +cmake --build . +# install library; by default installs into /usr/local/ +cmake --build . --target install +# NOTE: you need to run install command as root, to be able to install into /usr/local/ +``` +Such invocation will use the default (as per CMake magic) compiler/build environment available in your system. + +You may pass some additional CMake variables to control the build configuration as `-D=value`. +E.g.: +```sh +# install command now would install things into /usr +cmake -DCMAKE_INSTALL_PREFIX=/usr +``` + +
+ Using a specific CMake generator + +An example of using `Ninja` as a CMake generator: + +```sh +cd +# configure the build +cmake -GNinja +# we know, that CMake has generated build files for Ninja, +# so we can use `ninja` directly, instead of `cmake --build .` +ninja +# install library +ninja install +``` + +`-G` here specifies a native build system CMake would generate build files for. +Check [CMake Documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for a list of available generators (system-specific). + +

+ +Some of the [standard](https://cmake.org/cmake/help/latest/manual/cmake-variables.7.html) CMake variables you may want to use to configure a build: + +- [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) - prefix where `install` target would install the library(ies); +- [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) - standard possible values: `Debug`, `Release`, `RelWithDebInfo`, `MinSizeRel`; Defaults to `Release` for HIDAPI, if not specified; +- [`BUILD_SHARED_LIBS`](https://cmake.org/cmake/help/latest/variable/BUILD_SHARED_LIBS.html) - when set to TRUE, HIDAPI is built as a shared library, otherwise build statically; Defaults to `TRUE` for HIDAPI, if not specified; + +
+ macOS-specific variables + + - [`CMAKE_FRAMEWORK`](https://cmake.org/cmake/help/latest/variable/CMAKE_FRAMEWORK.html) - (since CMake 3.15) when set to TRUE, HIDAPI is built as a framework library, otherwise build as a regular static/shared library; Defaults to `FALSE` for HIDAPI, if not specified; + - [`CMAKE_OSX_DEPLOYMENT_TARGET`](https://cmake.org/cmake/help/latest/variable/CMAKE_OSX_DEPLOYMENT_TARGET.html) - minimum version of the target platform (e.g. macOS or iOS) on which the target binaries are to be deployed; defaults to a maximum supported target platform by currently used XCode/Toolchain; + +

+ +HIDAPI-specific CMake variables: + +- `HIDAPI_BUILD_HIDTEST` - when set to TRUE, build a small test application `hidtest`; +- `HIDAPI_WITH_TESTS` - when set to TRUE, build all (unit-)tests; +currently this option is only available on Windows, since only Windows backend has tests; + +
+ Linux-specific variables + + - `HIDAPI_WITH_HIDRAW` - when set to TRUE, build HIDRAW-based implementation of HIDAPI (`hidapi-hidraw`), otherwise don't build it; defaults to TRUE; + - `HIDAPI_WITH_LIBUSB` - when set to TRUE, build LIBUSB-based implementation of HIDAPI (`hidapi-libusb`), otherwise don't build it; defaults to TRUE; + + **NOTE**: at least one of `HIDAPI_WITH_HIDRAW` or `HIDAPI_WITH_LIBUSB` has to be set to TRUE. + +

+ +To see all most-useful CMake variables available for HIDAPI, one of the most convenient ways is too use [`cmake-gui`](https://cmake.org/cmake/help/latest/manual/cmake-gui.1.html) tool ([example](https://cmake.org/runningcmake/)). + +_NOTE_: HIDAPI packages built by CMake can be used with `pkg-config`, as if built with [Autotools](BUILD.autotools.md). + +### MSVC and Ninja +It is possible to build a CMake project (including HIDAPI) using MSVC compiler and Ninja (for medium and larger projects it is so much faster than msbuild). + +For that: +1) Open cmd.exe; +2) Setup MSVC build environment variables, e.g.: `vcvarsall.bat x64`, where: + - `vcvarsall.bat` is an environment setup script of your MSVC toolchain installation;
For MSVC 2019 Community edition it is located at: `C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\`; + - `x64` -a target architecture to build; +3) Follow general build steps, and use `Ninja` as a generator. + +### Using HIDAPI in a CMake project + +When HIDAPI is used as a standalone package (either installed into the system or built manually and installed elsewhere), the simplest way to use it is as showed in the example: + +```cmake +project(my_application) + +add_executable(my_application main.c) + +find_package(hidapi REQUIRED) +target_link_libraries(my_application PRIVATE hidapi::hidapi) +``` + +If HIDAPI isn't installed in your system, or `find_package` cannot find HIDAPI by default for any other reasons, +the recommended way manually specify which HIDAPI package to use is via `hidapi_ROOT` CMake variable, e.g.: +`-Dhidapi_ROOT=`. + +_NOTE_: usage of `hidapi_ROOT` is only possible (and recommended) with CMake 3.12 and higher. For older versions of CMake you'd need to specify [`CMAKE_PREFIX_PATH`](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html#variable:CMAKE_PREFIX_PATH) instead. + +Check with [`find_package`](https://cmake.org/cmake/help/latest/command/find_package.html) documentation if you need more details. + +Available CMake targets after successful `find_package(hidapi)`: +- `hidapi::hidapi` - indented to be used in most cases; +- `hidapi::include` - if you need only to include `` but not link against the library; +- `hidapi::winapi` - same as `hidapi::hidapi` on Windows; available only on Windows; +- `hidapi::darwin` - same as `hidapi::hidapi` on macOS; available only on macOS; +- `hidapi::libusb` - available when libusb backend is used/available; +- `hidapi::hidraw` - available when hidraw backend is used/available on Linux; + +**NOTE**: on Linux often both `hidapi::libusb` and `hidapi::hidraw` backends are available; in that case `hidapi::hidapi` is an alias for **`hidapi::hidraw`**. The motivation is that `hidraw` backend is a native Linux kernel implementation of HID protocol, and supports various HID devices (USB, Bluetooth, I2C, etc.). If `hidraw` backend isn't built at all (`hidapi::libusb` is the only target) - `hidapi::hidapi` is an alias for `hidapi::libusb`. +If you're developing a cross-platform application and you are sure you need to use `libusb` backend on Linux, the simple way to achieve this is: +```cmake +if(TARGET hidapi::libusb) + target_link_libraries(my_project PRIVATE hidapi::libusb) +else() + target_link_libraries(my_project PRIVATE hidapi::hidapi) +endif() +``` + +## HIDAPI as a subdirectory + +HIDAPI can be easily used as a subdirectory of a larger CMake project: +```cmake +# root CMakeLists.txt +cmake_minimum_required(VERSION 3.4.3 FATAL_ERROR) + +add_subdirectory(hidapi) +add_subdirectory(my_application) + +# my_application/CMakeLists.txt +project(my_application) + +add_executable(my_application main.c) + +# NOTE: no `find_package` is required, since HIDAPI targets are already a part of the project tree +target_link_libraries(my_application PRIVATE hidapi::hidapi) +``` +Lets call this "larger project" a "host project". + +All of the variables described in [standalone build](#standalone-package-build) section can be used to control HIDAPI build in case of a subdirectory, e.g.: +```cmake +set(HIDAPI_WITH_LIBUSB FALSE) # surely will be used only on Linux +set(BUILD_SHARED_LIBS FALSE) # HIDAPI as static library on all platforms +add_subdirectory(hidapi) +``` + +
+ NOTE + + If you project happen to use `BUILD_SHARED_LIBS` as a `CACHE` variable globally for you project, setting it as simple variable, as showed above _will have not affect_ up until _CMake 3.13_. See [CMP0077](https://cmake.org/cmake/help/latest/policy/CMP0077.html) for details. +

+ +There are several important differences in the behavior of HIDAPI CMake build system when CMake is built as standalone package vs subdirectory build: + +1) In _standalone build_ a number of standard and HIDAPI-specific variables are marked as _cache variables_ or _options_. +This is done for convenience: when you're building HIDAPI as a standalone package and using tools like `cmake-gui` - those are highlighted as variables that can be changed and has some short description/documentation. E.g.: +![an example of highlighted variables in cmake-gui](documentation/cmake-gui-highlights.png "cmake-gui highlighted variables")
+E.g.2:
+![an example of drop-down menu in cmake-gui](documentation/cmake-gui-drop-down.png "cmake-gui drop-down menu")
+When HIDAPI is built as a _subdirectory_ - **_none of the variables are marked for cache or as options_** by HIDAPI. +This is done to let the host project's developer decide what is important (what needs to be highlighted) and what's not. + +2) The default behavior/default value for some of the variables is a bit different: + - by default, none of HIDAPI targets are [installed](https://cmake.org/cmake/help/latest/command/install.html); if required, HIDAPI targets can be installed by host project _after_ including HIDAPI subdirectory (requires CMake 3.13 or later); **or**, the default installation can be enabled by setting `HIDAPI_INSTALL_TARGETS` variable _before_ including HIDAPI subdirectory. + HIDAPI uses [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) to specify install locations. Variables like `CMAKE_INSTALL_LIBDIR` can be used to control HIDAPI's installation locations. E.g.: + ```cmake + # enable the installation if you need it + set(HIDAPI_INSTALL_TARGETS ON) + # (optionally) change default installation locations if it makes sense for your target platform, etc. + set(CMAKE_INSTALL_LIBDIR "lib64") + add_subdirectory(hidapi) + ``` + - HIDAPI prints its version during the configuration when built as a standalone package; to enable this for subdirectory builds - set `HIDAPI_PRINT_VERSION` to TRUE before including HIDAPI; + +3) In a subdirectory build, HIDAPI _doesn't modify or set any of the CMake variables_ that may change the build behavior. + For instance, in a _standalone build_, if CMAKE_BUILD_TYPE or BUILD_SHARED_LIBS variables are not set, those are defaulted to "Release" and "TRUE" explicitly. + In a _subdirectory build_, even if not set, those variables remain unchanged, so a host project's developer has a full control over the HIDAPI build configuration. + +Available CMake targets after `add_subdirectory(hidapi)` _are the same as in case of [standalone build](#standalone-package-build)_, and a few additional ones: +- `hidapi_include` - the interface library; `hidapi::hidapi` is an alias of it; +- `hidapi_winapi` - library target on Windows; `hidapi::winapi` is an alias of it; +- `hidapi_darwin` - library target on macOS; `hidapi::darwin` is an alias of it; +- `hidapi_libusb` - library target for libusb backend; `hidapi::libusb` is an alias of it; +- `hidapi_hidraw` - library target for hidraw backend; `hidapi::hidraw` is an alias of it; +- `hidapi-libusb` - an alias of `hidapi_libusb` for compatibility with raw library name; +- `hidapi-hidraw` - an alias of `hidapi_hidraw` for compatibility with raw library name; +- `hidapi` - an alias of `hidapi_winapi` or `hidapi_darwin` on Windows or macOS respectfully. + +Advanced: +- Why would I need additional targets described in this section above, if I already have alias targets compatible with `find_package`? + - an example: + ```cmake + add_subdirectory(hidapi) + if(TARGET hidapi_libusb) + # see libusb/hid.c for usage of `NO_ICONV` + target_compile_definitions(hidapi_libusb PRIVATE NO_ICONV) + endif() + ``` + +## Both Shared and Static build + +If you're a former (or present) user of Autotools build scripts for HIDAPI, or you're a package manager maintainer and you're often working with those - you're likely asking how to build HIDAPI with CMake and get both Shared and Static libraries (as would be done by Autotools: `./configure --enable-static --enable-shared ...`). + +CMake doesn't have such option of-the-box and it is decided not to introduce any manual CMake-level workarounds for HIDAPI on this matter. + +If you want to mimic the Autotools behavior, it is possible by building/installing first the static version of the library and then shared version of the library. The installation folder (`CMAKE_INSTALL_PREFIX`) should point to the same directory for both variants, that way: +- both static and shared library binaries will be available and usable; +- a single header file(s) for both of them; +- Autotools/pkg-config (`.pc`) files will be generated and usable _as if_ generated by Autotools natively and build configured with both `-enable-static --enable-shared` options; +- CMake package scripts will be generated and fully usable, but _only the last build installed_, i.e. if the last was installed Shared version of the binary - CMake targets found by `find_package(hidapi)` would point to a Shared binaries. + +There is a historical discussion, why such solution is simplest/preferable: https://github.com/libusb/hidapi/issues/424 + +#### TL;DR/Sample + +```sh +# First - configure/build + +# Static libraries +cmake -S -B "/static" -DCMAKE_INSTALL_PREFIX= -DBUILD_SHARED_LIBS=FALSE +cmake --build "/static" +# Shared libraries +cmake -S -B "/shared" -DCMAKE_INSTALL_PREFIX= -DBUILD_SHARED_LIBS=TRUE +cmake --build "/shared" + +# (Optionally) change the installation destination. +# NOTE1: this is supported by CMake only on UNIX platforms +# See https://cmake.org/cmake/help/latest/envvar/DESTDIR.html +# NOTE2: this is not the same as `CMAKE_INSTALL_PREFIX` set above +# NOTE3: this is only required if you have a staging dir other than the final runtime dir, +# e.g. during cross-compilation +export DESTDIR="$STAGING_DIR" + +# +# Install the libraries +# NOTE: order of installation matters - install Shared variant *the last* + +# Static libraries +cmake --install "/static" +# Shared libraries +cmake --install "/shared" + +``` diff --git a/src/hidapi/BUILD.md b/src/hidapi/BUILD.md new file mode 100644 index 0000000000000..d7a3546f6a9f6 --- /dev/null +++ b/src/hidapi/BUILD.md @@ -0,0 +1,127 @@ +# Building HIDAPI from Source + +## Table of content + +* [Intro](#intro) +* [Prerequisites](#prerequisites) + * [Linux](#linux) + * [FreeBSD](#freebsd) + * [Mac](#mac) + * [Windows](#windows) +* [Embedding HIDAPI directly into your source tree](#embedding-hidapi-directly-into-your-source-tree) +* [Building the manual way on Unix platforms](#building-the-manual-way-on-unix-platforms) +* [Building on Windows](#building-on-windows) + +## Intro + +For various reasons, you may need to build HIDAPI on your own. + +It can be done in several different ways: +- using [CMake](BUILD.cmake.md); +- using [Autotools](BUILD.autotools.md) (deprecated); +- using [manual makefiles](#building-the-manual-way-on-unix-platforms); +- using `Meson` (requires CMake); + +**Autotools** build system is historically the first mature build system for +HIDAPI. The most common usage of it is in its separate README: [BUILD.autotools.md](BUILD.autotools.md).
+NOTE: for all intentions and purposes the Autotools build scripts for HIDAPI are _deprecated_ and going to be obsolete in the future. +HIDAPI Team recommends using CMake build for HIDAPI. + +**CMake** build system is de facto an industry standard for many open-source and proprietary projects and solutions. +HIDAPI is one of the projects which use the power of CMake to its advantage. +More documentation is available in its separate README: [BUILD.cmake.md](BUILD.cmake.md). + +**Meson** build system for HIDAPI is designed as a [wrapper](https://mesonbuild.com/CMake-module.html) over CMake build script. +It is present for the convenience of Meson users who need to use HIDAPI and need to be sure HIDAPI is built in accordance with officially supported build scripts.
+In the Meson script of your project you need a `hidapi = subproject('hidapi')` subproject, and `hidapi.get_variable('hidapi_dep')` as your dependency. +There are also backend/platform-specific dependencies available: `hidapi_winapi`, `hidapi_darwin`, `hidapi_hidraw`, `hidapi_libusb`. + +If you don't know where to start to build HIDAPI, we recommend starting with [CMake](BUILD.cmake.md) build. + +## Prerequisites: + +Regardless of what build system you choose to use, there are specific dependencies for each platform/backend. + +### Linux: + +Depending on which backend you're going to build, you'll need to install +additional development packages. For `linux/hidraw` backend, you need a +development package for `libudev`. For `libusb` backend, naturally, you need +`libusb` development package. + +On Debian/Ubuntu systems these can be installed by running: +```sh +# required only by hidraw backend +sudo apt install libudev-dev +# required only by libusb backend +sudo apt install libusb-1.0-0-dev +``` + +### FreeBSD: + +On FreeBSD, you will need to install libiconv. This is done by running +the following: +```sh +pkg_add -r libiconv +``` + +### Mac: + +Make sure you have XCode installed and its Command Line Tools. + +### Windows: + +You just need a compiler. You may use Visual Studio or Cygwin/MinGW, +depending on which environment is best for your needs. + +## Embedding HIDAPI directly into your source tree + +Instead of using one of the provided standalone build systems, +you may want to integrate HIDAPI directly into your source tree. + +--- +If your project uses CMake as a build system, it is safe to add HIDAPI as a [subdirectory](BUILD.cmake.md#hidapi-as-a-subdirectory). + +--- +If _the only option_ that works for you is adding HIDAPI sources directly +to your project's build system, then you need: +- include a _single source file_ into your project's build system, +depending on your platform and the backend you want to use: + - [`windows\hid.c`](windows/hid.c); + - [`linux/hid.c`](linux/hid.c); + - [`libusb/hid.c`](libusb/hid.c); + - [`mac/hid.c`](mac/hid.c); +- add a [`hidapi`](hidapi) folder to the include path when building `hid.c`; +- make the platform/backend specific [dependencies](#prerequisites) available during the compilation/linking, when building `hid.c`; + +NOTE: the above doesn't guarantee that having a copy of `/hid.c` and `hidapi/hidapi.h` is enough to build HIDAPI. +The only guarantee that `/hid.c` includes all necessary sources to compile it as a single file. + +Check the manual makefiles for a simple example/reference of what are the dependencies of each specific backend. + +## Building the manual way on Unix platforms + +Manual Makefiles are provided mostly to give the user an idea what it takes +to build a program which embeds HIDAPI directly inside of it. These should +really be used as examples only. If you want to build a system-wide shared +library, use one of the build systems mentioned above. + +To build HIDAPI using the manual Makefiles, change the directory +of your platform and run make. For example, on Linux run: +```sh +cd linux/ +make -f Makefile-manual +``` + +## Building on Windows + +To build the HIDAPI DLL on Windows using Visual Studio, build the `.sln` file +in the `windows/` directory. + +To build HIDAPI using MinGW or Cygwin using Autotools, use general Autotools + [instruction](BUILD.autotools.md). + +Any windows builds (MSVC or MinGW/Cygwin) are also supported by [CMake](BUILD.cmake.md). + +If you are looking for information regarding DDK build of HIDAPI: +- the build has been broken for a while and now the support files are obsolete. diff --git a/src/hidapi/CMakeLists.txt b/src/hidapi/CMakeLists.txt new file mode 100644 index 0000000000000..e18ee23be848b --- /dev/null +++ b/src/hidapi/CMakeLists.txt @@ -0,0 +1,105 @@ +cmake_minimum_required(VERSION 3.1.3 FATAL_ERROR) + +if(NOT CMAKE_SOURCE_DIR STREQUAL CMAKE_CURRENT_SOURCE_DIR) + add_subdirectory(src) + # compatibility with find_package() vs add_subdirectory + set(hidapi_VERSION "${hidapi_VERSION}" PARENT_SCOPE) + return() +endif() +# All of the below in this file is meant for a standalone build. +# When building as a subdirectory of a larger project, most of the options may not make sense for it, +# so it is up to developer to configure those, e.g.: +# +# # a subfolder of a master project, e.g.: 3rdparty/hidapi/CMakeLists.txt +# +# set(HIDAPI_WITH_HIDRAW OFF) +# set(CMAKE_FRAMEWORK ON) +# # and keep everything else to their defaults +# add_subdirectory(hidapi) +# + +set(DEFAULT_CMAKE_BUILD_TYPES "Debug" "Release" "MinSizeRel" "RelWithDebInfo") +if(NOT DEFINED CMAKE_BUILD_TYPE OR NOT CMAKE_BUILD_TYPE) + set(CMAKE_BUILD_TYPE "Release" CACHE STRING "${DEFAULT_CMAKE_BUILD_TYPES}" FORCE) +endif() +# This part is for convenience, when used one of the standard build types with cmake-gui +list(FIND DEFAULT_CMAKE_BUILD_TYPES "${CMAKE_BUILD_TYPE}" _build_type_index) +if(${_build_type_index} GREATER -1) + # set it optionally, so a custom CMAKE_BUILD_TYPE can be used as well, if needed + set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS ${DEFAULT_CMAKE_BUILD_TYPES}) +endif() +unset(_build_type_index) +# + +project(hidapi LANGUAGES C) + +if(APPLE) + if(NOT CMAKE_VERSION VERSION_LESS "3.15") + option(CMAKE_FRAMEWORK "Build macOS/iOS Framework version of the library" OFF) + endif() +elseif(NOT WIN32) + if(CMAKE_SYSTEM_NAME MATCHES "Linux") + option(HIDAPI_WITH_HIDRAW "Build HIDRAW-based implementation of HIDAPI" ON) + option(HIDAPI_WITH_LIBUSB "Build LIBUSB-based implementation of HIDAPI" ON) + endif() +endif() + +option(BUILD_SHARED_LIBS "Build shared version of the libraries, otherwise build statically" ON) + +set(HIDAPI_INSTALL_TARGETS ON) +set(HIDAPI_PRINT_VERSION ON) + +set(IS_DEBUG_BUILD OFF) +if(CMAKE_BUILD_TYPE STREQUAL "Debug") + set(IS_DEBUG_BUILD ON) +endif() + +option(HIDAPI_ENABLE_ASAN "Build HIDAPI with ASAN address sanitizer instrumentation" OFF) + +if(HIDAPI_ENABLE_ASAN) + set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fsanitize=address") + if(MSVC) + # the default is to have "/INCREMENTAL" which causes a warning when "-fsanitize=address" is present + set(CMAKE_EXE_LINKER_FLAGS_DEBUG "${CMAKE_EXE_LINKER_FLAGS_DEBUG} /INCREMENTAL:NO") + set(CMAKE_SHARED_LINKER_FLAGS_DEBUG "${CMAKE_SHARED_LINKER_FLAGS_DEBUG} /INCREMENTAL:NO") + set(CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO "${CMAKE_EXE_LINKER_FLAGS_RELWITHDEBINFO} /INCREMENTAL:NO") + set(CMAKE_SHARED_LINKER_FLAGS_RELWITHDEBINFO "${CMAKE_SHARED_LINKER_FLAGS_RELWITHDEBINFO} /INCREMENTAL:NO") + endif() +endif() + +if(WIN32) + # so far only Windows has tests + option(HIDAPI_WITH_TESTS "Build HIDAPI (unit-)tests" ${IS_DEBUG_BUILD}) +else() + set(HIDAPI_WITH_TESTS OFF) +endif() + +if(HIDAPI_WITH_TESTS) + enable_testing() +endif() + +if(WIN32) + option(HIDAPI_BUILD_PP_DATA_DUMP "Build small Windows console application pp_data_dump.exe" ${IS_DEBUG_BUILD}) +endif() + +add_subdirectory(src) + +option(HIDAPI_BUILD_HIDTEST "Build small console test application hidtest" ${IS_DEBUG_BUILD}) +if(HIDAPI_BUILD_HIDTEST) + add_subdirectory(hidtest) +endif() + +if(HIDAPI_ENABLE_ASAN) + if(NOT MSVC) + # MSVC doesn't recognize those options, other compilers - requiring it + foreach(HIDAPI_TARGET hidapi_winapi hidapi_darwin hidapi_hidraw hidapi_libusb hidtest_hidraw hidtest_libusb hidtest) + if(TARGET ${HIDAPI_TARGET}) + if(BUILD_SHARED_LIBS) + target_link_options(${HIDAPI_TARGET} PRIVATE -fsanitize=address) + else() + target_link_options(${HIDAPI_TARGET} PUBLIC -fsanitize=address) + endif() + endif() + endforeach() + endif() +endif() diff --git a/src/hidapi/HACKING.txt b/src/hidapi/HACKING.txt index 761d4b6550284..e06b533aa0ae7 100644 --- a/src/hidapi/HACKING.txt +++ b/src/hidapi/HACKING.txt @@ -1,15 +1,19 @@ This file is mostly for the maintainer. -1. Build hidapi.dll -2. Build hidtest.exe in DEBUG and RELEASE -3. Commit all +Updating a Version: +1. Update VERSION file. +2. HID_API_VERSION_MAJOR/HID_API_VERSION_MINOR/HID_API_VERSION_PATCH in hidapi.h. -4. Run the Following - export VERSION=0.1.0 - export TAG_NAME=hidapi-$VERSION - git tag $TAG_NAME - git archive --format zip --prefix $TAG_NAME/ $TAG_NAME >../$TAG_NAME.zip -5. Test the zip file. -6. Run the following: - git push origin $TAG_NAME +Before firing a new release: +1. Run the "Checks" Githtub Action +2. Make sure no defects are found at: https://scan.coverity.com/projects/hidapi +3. Fix if any +Firing a new release: +1. Update the Version (if not yet updated). +2. Prepare the Release Notes. +3. Store the Release Notes into a file. +4. Create locally an annotated git tag with release notes attached, e.g.: `git tag -aF ../hidapi_release_notes hidapi-` +5. Push newly created tag: `git push origin hidapi-` +6. Grab the hidapi-win.zip from Summary page of "GitHub Builds" Action for latest master build. +7. Create a Github Release with hidapi-win.zip attached, for newly created tag. diff --git a/src/hidapi/Makefile.am b/src/hidapi/Makefile.am index 3382a1f040bcd..00bcb73cf4119 100644 --- a/src/hidapi/Makefile.am +++ b/src/hidapi/Makefile.am @@ -23,10 +23,6 @@ if OS_DARWIN SUBDIRS += mac endif -if OS_IOS -SUBDIRS += ios -endif - if OS_FREEBSD SUBDIRS += libusb endif @@ -35,6 +31,10 @@ if OS_KFREEBSD SUBDIRS += libusb endif +if OS_HAIKU +SUBDIRS += libusb +endif + if OS_WINDOWS SUBDIRS += windows endif @@ -48,7 +48,7 @@ endif EXTRA_DIST = udev doxygen dist_doc_DATA = \ - README.txt \ + README.md \ AUTHORS.txt \ LICENSE-bsd.txt \ LICENSE-gpl3.txt \ diff --git a/src/hidapi/README.md b/src/hidapi/README.md new file mode 100644 index 0000000000000..257b9f340a579 --- /dev/null +++ b/src/hidapi/README.md @@ -0,0 +1,196 @@ +## HIDAPI library for Windows, Linux, FreeBSD and macOS + +| CI instance | Status | +|----------------------|--------| +| `Linux/macOS/Windows (master)` | [![GitHub Builds](https://github.com/libusb/hidapi/workflows/GitHub%20Builds/badge.svg?branch=master)](https://github.com/libusb/hidapi/actions/workflows/builds.yml?query=branch%3Amaster) | +| `Windows (master)` | [![Build status](https://ci.appveyor.com/api/projects/status/xfmr5fo8w0re8ded/branch/master?svg=true)](https://ci.appveyor.com/project/libusb/hidapi/branch/master) | +| `BSD, last build (branch/PR)` | [![builds.sr.ht status](https://builds.sr.ht/~z3ntu/hidapi.svg)](https://builds.sr.ht/~z3ntu/hidapi) | +| `Coverity Scan (last)` | ![Coverity Scan](https://scan.coverity.com/projects/583/badge.svg) | + +HIDAPI is a multi-platform library which allows an application to interface +with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS. +HIDAPI can be either built as a shared library (`.so`, `.dll` or `.dylib`) or +can be embedded directly into a target application by adding a _single source_ +file (per platform) and a single header.
+See [remarks](BUILD.md#embedding-hidapi-directly-into-your-source-tree) on embedding _directly_ into your build system. + +HIDAPI library was originally developed by Alan Ott ([signal11](https://github.com/signal11)). + +It was moved to [libusb/hidapi](https://github.com/libusb/hidapi) on June 4th, 2019, in order to merge important bugfixes and continue development of the library. + +## Table of Contents + +* [About](#about) + * [Test GUI](#test-gui) + * [Console Test App](#console-test-app) +* [What Does the API Look Like?](#what-does-the-api-look-like) +* [License](#license) +* [Installing HIDAPI](#installing-hidapi) +* [Build from Source](#build-from-source) + + +## About + +### HIDAPI has four back-ends: +* Windows (using `hid.dll`) +* Linux/hidraw (using the Kernel's hidraw driver) +* libusb (using libusb-1.0 - Linux/BSD/other UNIX-like systems) +* macOS (using IOHidManager) + +On Linux, either the hidraw or the libusb back-end can be used. There are +tradeoffs, and the functionality supported is slightly different. Both are +built by default. It is up to the application linking to hidapi to choose +the backend at link time by linking to either `libhidapi-libusb` or +`libhidapi-hidraw`. + +Note that you will need to install an udev rule file with your application +for unprivileged users to be able to access HID devices with hidapi. Refer +to the [69-hid.rules](udev/69-hid.rules) file in the `udev` directory +for an example. + +#### __Linux/hidraw__ (`linux/hid.c`): + +This back-end uses the hidraw interface in the Linux kernel, and supports +both USB and Bluetooth HID devices. It requires kernel version at least 2.6.39 +to build. In addition, it will only communicate with devices which have hidraw +nodes associated with them. +Keyboards, mice, and some other devices which are blacklisted from having +hidraw nodes will not work. Fortunately, for nearly all the uses of hidraw, +this is not a problem. + +#### __Linux/FreeBSD/libusb__ (`libusb/hid.c`): + +This back-end uses libusb-1.0 to communicate directly to a USB device. This +back-end will of course not work with Bluetooth devices. + +### Test GUI + +HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses +Fox Toolkit . It will build on every platform +which HIDAPI supports. Since it relies on a 3rd party library, building it +is optional but it is useful when debugging hardware. + +NOTE: Test GUI based on Fox Toolkit is not actively developed nor supported +by HIDAPI team. It is kept as a historical artifact. It may even work sometime +or on some platforms, but it is not going to get any new features or bugfixes. + +Instructions for installing Fox-Toolkit on each platform is not provided. +Make sure to use Fox-Toolkit v1.6 if you choose to use it. + +### Console Test App + +If you want to play around with your HID device before starting +any development with HIDAPI and using a GUI app is not an option for you, you may try [`hidapitester`](https://github.com/todbot/hidapitester). + +This app has a console interface for most of the features supported +by HIDAPI library. + +## What Does the API Look Like? + +The API provides the most commonly used HID functions including sending +and receiving of input, output, and feature reports. The sample program, +which communicates with a heavily hacked up version of the Microchip USB +Generic HID sample looks like this (with error checking removed for +simplicity): + +**Warning: Only run the code you understand, and only when it conforms to the +device spec. Writing data (`hid_write`) at random to your HID devices can break them.** + +```c +#include // printf +#include // wchar_t + +#include + +#define MAX_STR 255 + +int main(int argc, char* argv[]) +{ + int res; + unsigned char buf[65]; + wchar_t wstr[MAX_STR]; + hid_device *handle; + int i; + + // Initialize the hidapi library + res = hid_init(); + + // Open the device using the VID, PID, + // and optionally the Serial number. + handle = hid_open(0x4d8, 0x3f, NULL); + if (!handle) { + printf("Unable to open device\n"); + hid_exit(); + return 1; + } + + // Read the Manufacturer String + res = hid_get_manufacturer_string(handle, wstr, MAX_STR); + printf("Manufacturer String: %ls\n", wstr); + + // Read the Product String + res = hid_get_product_string(handle, wstr, MAX_STR); + printf("Product String: %ls\n", wstr); + + // Read the Serial Number String + res = hid_get_serial_number_string(handle, wstr, MAX_STR); + printf("Serial Number String: (%d) %ls\n", wstr[0], wstr); + + // Read Indexed String 1 + res = hid_get_indexed_string(handle, 1, wstr, MAX_STR); + printf("Indexed String 1: %ls\n", wstr); + + // Toggle LED (cmd 0x80). The first byte is the report number (0x0). + buf[0] = 0x0; + buf[1] = 0x80; + res = hid_write(handle, buf, 65); + + // Request state (cmd 0x81). The first byte is the report number (0x0). + buf[0] = 0x0; + buf[1] = 0x81; + res = hid_write(handle, buf, 65); + + // Read requested state + res = hid_read(handle, buf, 65); + + // Print out the returned buffer. + for (i = 0; i < 4; i++) + printf("buf[%d]: %d\n", i, buf[i]); + + // Close the device + hid_close(handle); + + // Finalize the hidapi library + res = hid_exit(); + + return 0; +} +``` + +You can also use [hidtest/test.c](hidtest/test.c) +as a starting point for your applications. + + +## License + +HIDAPI may be used by one of three licenses as outlined in [LICENSE.txt](LICENSE.txt). + +## Installing HIDAPI + +If you want to build your own application that uses HID devices with HIDAPI, +you need to get HIDAPI development package. + +Depending on what your development environment is, HIDAPI likely to be provided +by your package manager. + +For instance on Ubuntu, HIDAPI is available via APT: +```sh +sudo apt install libhidapi-dev +``` + +HIDAPI package name for other systems/package managers may differ. +Check the documentation/package list of your package manager. + +## Build from Source + +Check [BUILD.md](BUILD.md) for details. diff --git a/src/hidapi/README.txt b/src/hidapi/README.txt deleted file mode 100644 index 756901ec52efe..0000000000000 --- a/src/hidapi/README.txt +++ /dev/null @@ -1,339 +0,0 @@ - HIDAPI library for Windows, Linux, FreeBSD and Mac OS X - ========================================================= - -About -====== - -HIDAPI is a multi-platform library which allows an application to interface -with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and Mac -OS X. HIDAPI can be either built as a shared library (.so or .dll) or -can be embedded directly into a target application by adding a single source -file (per platform) and a single header. - -HIDAPI has four back-ends: - * Windows (using hid.dll) - * Linux/hidraw (using the Kernel's hidraw driver) - * Linux/libusb (using libusb-1.0) - * FreeBSD (using libusb-1.0) - * Mac (using IOHidManager) - -On Linux, either the hidraw or the libusb back-end can be used. There are -tradeoffs, and the functionality supported is slightly different. - -Linux/hidraw (linux/hid.c): -This back-end uses the hidraw interface in the Linux kernel. While this -back-end will support both USB and Bluetooth, it has some limitations on -kernels prior to 2.6.39, including the inability to send or receive feature -reports. In addition, it will only communicate with devices which have -hidraw nodes associated with them. Keyboards, mice, and some other devices -which are blacklisted from having hidraw nodes will not work. Fortunately, -for nearly all the uses of hidraw, this is not a problem. - -Linux/FreeBSD/libusb (libusb/hid.c): -This back-end uses libusb-1.0 to communicate directly to a USB device. This -back-end will of course not work with Bluetooth devices. - -HIDAPI also comes with a Test GUI. The Test GUI is cross-platform and uses -Fox Toolkit (http://www.fox-toolkit.org). It will build on every platform -which HIDAPI supports. Since it relies on a 3rd party library, building it -is optional but recommended because it is so useful when debugging hardware. - -What Does the API Look Like? -============================= -The API provides the the most commonly used HID functions including sending -and receiving of input, output, and feature reports. The sample program, -which communicates with a heavily hacked up version of the Microchip USB -Generic HID sample looks like this (with error checking removed for -simplicity): - -#ifdef WIN32 -#include -#endif -#include -#include -#include "hidapi.h" - -#define MAX_STR 255 - -int main(int argc, char* argv[]) -{ - int res; - unsigned char buf[65]; - wchar_t wstr[MAX_STR]; - hid_device *handle; - int i; - - // Initialize the hidapi library - res = hid_init(); - - // Open the device using the VID, PID, - // and optionally the Serial number. - handle = hid_open(0x4d8, 0x3f, NULL); - - // Read the Manufacturer String - res = hid_get_manufacturer_string(handle, wstr, MAX_STR); - wprintf(L"Manufacturer String: %s\n", wstr); - - // Read the Product String - res = hid_get_product_string(handle, wstr, MAX_STR); - wprintf(L"Product String: %s\n", wstr); - - // Read the Serial Number String - res = hid_get_serial_number_string(handle, wstr, MAX_STR); - wprintf(L"Serial Number String: (%d) %s\n", wstr[0], wstr); - - // Read Indexed String 1 - res = hid_get_indexed_string(handle, 1, wstr, MAX_STR); - wprintf(L"Indexed String 1: %s\n", wstr); - - // Toggle LED (cmd 0x80). The first byte is the report number (0x0). - buf[0] = 0x0; - buf[1] = 0x80; - res = hid_write(handle, buf, 65); - - // Request state (cmd 0x81). The first byte is the report number (0x0). - buf[0] = 0x0; - buf[1] = 0x81; - res = hid_write(handle, buf, 65); - - // Read requested state - res = hid_read(handle, buf, 65); - - // Print out the returned buffer. - for (i = 0; i < 4; i++) - printf("buf[%d]: %d\n", i, buf[i]); - - // Finalize the hidapi library - res = hid_exit(); - - return 0; -} - -If you have your own simple test programs which communicate with standard -hardware development boards (such as those from Microchip, TI, Atmel, -FreeScale and others), please consider sending me something like the above -for inclusion into the HIDAPI source. This will help others who have the -same hardware as you do. - -License -======== -HIDAPI may be used by one of three licenses as outlined in LICENSE.txt. - -Download -========= -HIDAPI can be downloaded from github - git clone git://github.com/libusb/hidapi.git - -Build Instructions -=================== - -This section is long. Don't be put off by this. It's not long because it's -complicated to build HIDAPI; it's quite the opposite. This section is long -because of the flexibility of HIDAPI and the large number of ways in which -it can be built and used. You will likely pick a single build method. - -HIDAPI can be built in several different ways. If you elect to build a -shared library, you will need to build it from the HIDAPI source -distribution. If you choose instead to embed HIDAPI directly into your -application, you can skip the building and look at the provided platform -Makefiles for guidance. These platform Makefiles are located in linux/ -libusb/ mac/ and windows/ and are called Makefile-manual. In addition, -Visual Studio projects are provided. Even if you're going to embed HIDAPI -into your project, it is still beneficial to build the example programs. - - -Prerequisites: ---------------- - - Linux: - ------- - On Linux, you will need to install development packages for libudev, - libusb and optionally Fox-toolkit (for the test GUI). On - Debian/Ubuntu systems these can be installed by running: - sudo apt-get install libudev-dev libusb-1.0-0-dev libfox-1.6-dev - - If you downloaded the source directly from the git repository (using - git clone), you'll need Autotools: - sudo apt-get install autotools-dev autoconf automake libtool - - FreeBSD: - --------- - On FreeBSD you will need to install GNU make, libiconv, and - optionally Fox-Toolkit (for the test GUI). This is done by running - the following: - pkg_add -r gmake libiconv fox16 - - If you downloaded the source directly from the git repository (using - git clone), you'll need Autotools: - pkg_add -r autotools - - Mac: - ----- - On Mac, you will need to install Fox-Toolkit if you wish to build - the Test GUI. There are two ways to do this, and each has a slight - complication. Which method you use depends on your use case. - - If you wish to build the Test GUI just for your own testing on your - own computer, then the easiest method is to install Fox-Toolkit - using ports: - sudo port install fox - - If you wish to build the TestGUI app bundle to redistribute to - others, you will need to install Fox-toolkit from source. This is - because the version of fox that gets installed using ports uses the - ports X11 libraries which are not compatible with the Apple X11 - libraries. If you install Fox with ports and then try to distribute - your built app bundle, it will simply fail to run on other systems. - To install Fox-Toolkit manually, download the source package from - http://www.fox-toolkit.org, extract it, and run the following from - within the extracted source: - ./configure && make && make install - - Windows: - --------- - On Windows, if you want to build the test GUI, you will need to get - the hidapi-externals.zip package from the download site. This - contains pre-built binaries for Fox-toolkit. Extract - hidapi-externals.zip just outside of hidapi, so that - hidapi-externals and hidapi are on the same level, as shown: - - Parent_Folder - | - +hidapi - +hidapi-externals - - Again, this step is not required if you do not wish to build the - test GUI. - - -Building HIDAPI into a shared library on Unix Platforms: ---------------------------------------------------------- - -On Unix-like systems such as Linux, FreeBSD, Mac, and even Windows, using -Mingw or Cygwin, the easiest way to build a standard system-installed shared -library is to use the GNU Autotools build system. If you checked out the -source from the git repository, run the following: - - ./bootstrap - ./configure - make - make install <----- as root, or using sudo - -If you downloaded a source package (ie: if you did not run git clone), you -can skip the ./bootstrap step. - -./configure can take several arguments which control the build. The two most -likely to be used are: - --enable-testgui - Enable build of the Test GUI. This requires Fox toolkit to - be installed. Instructions for installing Fox-Toolkit on - each platform are in the Prerequisites section above. - - --prefix=/usr - Specify where you want the output headers and libraries to - be installed. The example above will put the headers in - /usr/include and the binaries in /usr/lib. The default is to - install into /usr/local which is fine on most systems. - -Building the manual way on Unix platforms: -------------------------------------------- - -Manual Makefiles are provided mostly to give the user and idea what it takes -to build a program which embeds HIDAPI directly inside of it. These should -really be used as examples only. If you want to build a system-wide shared -library, use the Autotools method described above. - - To build HIDAPI using the manual makefiles, change to the directory - of your platform and run make. For example, on Linux run: - cd linux/ - make -f Makefile-manual - - To build the Test GUI using the manual makefiles: - cd testgui/ - make -f Makefile-manual - -Building on Windows: ---------------------- - -To build the HIDAPI DLL on Windows using Visual Studio, build the .sln file -in the windows/ directory. - -To build the Test GUI on windows using Visual Studio, build the .sln file in -the testgui/ directory. - -To build HIDAPI using MinGW or Cygwin using Autotools, use the instructions -in the section titled "Building HIDAPI into a shared library on Unix -Platforms" above. Note that building the Test GUI with MinGW or Cygwin will -require the Windows procedure in the Prerequisites section above (ie: -hidapi-externals.zip). - -To build HIDAPI using MinGW using the Manual Makefiles, see the section -"Building the manual way on Unix platforms" above. - -HIDAPI can also be built using the Windows DDK (now also called the Windows -Driver Kit or WDK). This method was originally required for the HIDAPI build -but not anymore. However, some users still prefer this method. It is not as -well supported anymore but should still work. Patches are welcome if it does -not. To build using the DDK: - - 1. Install the Windows Driver Kit (WDK) from Microsoft. - 2. From the Start menu, in the Windows Driver Kits folder, select Build - Environments, then your operating system, then the x86 Free Build - Environment (or one that is appropriate for your system). - 3. From the console, change directory to the windows/ddk_build/ directory, - which is part of the HIDAPI distribution. - 4. Type build. - 5. You can find the output files (DLL and LIB) in a subdirectory created - by the build system which is appropriate for your environment. On - Windows XP, this directory is objfre_wxp_x86/i386. - -Cross Compiling -================ - -This section talks about cross compiling HIDAPI for Linux using autotools. -This is useful for using HIDAPI on embedded Linux targets. These -instructions assume the most raw kind of embedded Linux build, where all -prerequisites will need to be built first. This process will of course vary -based on your embedded Linux build system if you are using one, such as -OpenEmbedded or Buildroot. - -For the purpose of this section, it will be assumed that the following -environment variables are exported. - - $ export STAGING=$HOME/out - $ export HOST=arm-linux - -STAGING and HOST can be modified to suit your setup. - -Prerequisites --------------- - -Note that the build of libudev is the very basic configuration. - -Build Libusb. From the libusb source directory, run: - ./configure --host=$HOST --prefix=$STAGING - make - make install - -Build libudev. From the libudev source directory, run: - ./configure --disable-gudev --disable-introspection --disable-hwdb \ - --host=$HOST --prefix=$STAGING - make - make install - -Building HIDAPI ----------------- - -Build HIDAPI: - - PKG_CONFIG_DIR= \ - PKG_CONFIG_LIBDIR=$STAGING/lib/pkgconfig:$STAGING/share/pkgconfig \ - PKG_CONFIG_SYSROOT_DIR=$STAGING \ - ./configure --host=$HOST --prefix=$STAGING - - -Signal 11 Software - 2010-04-11 - 2010-07-28 - 2011-09-10 - 2012-05-01 - 2012-07-03 diff --git a/src/hidapi/SDL_hidapi.c b/src/hidapi/SDL_hidapi.c index 3cc01f5d8003a..701280243c2ba 100644 --- a/src/hidapi/SDL_hidapi.c +++ b/src/hidapi/SDL_hidapi.c @@ -31,6 +31,10 @@ #include "SDL_hidapi_c.h" +/* Initial type declarations */ +#define HID_API_NO_EXPORT_DEFINE /* do not export hidapi procedures */ +#include "hidapi/hidapi.h" + #ifndef SDL_HIDAPI_DISABLED #if defined(__WIN32__) || defined(__WINGDK__) @@ -524,105 +528,90 @@ static void HIDAPI_ShutdownDiscovery(void) /* Platform HIDAPI Implementation */ +#define HIDAPI_IGNORE_DEVICE(VID, PID) SDL_HIDAPI_ShouldIgnoreDevice(VID, PID) + +struct PLATFORM_hid_device_; +typedef struct PLATFORM_hid_device_ PLATFORM_hid_device; + +#define api_version PLATFORM_api_version +#define create_device_info_for_device PLATFORM_create_device_info_for_device +#define free_hid_device PLATFORM_free_hid_device +#define hid_close PLATFORM_hid_close #define hid_device PLATFORM_hid_device #define hid_device_ PLATFORM_hid_device_ -#define hid_init PLATFORM_hid_init -#define hid_exit PLATFORM_hid_exit #define hid_enumerate PLATFORM_hid_enumerate +#define hid_error PLATFORM_hid_error +#define hid_exit PLATFORM_hid_exit #define hid_free_enumeration PLATFORM_hid_free_enumeration -#define hid_open PLATFORM_hid_open -#define hid_open_path PLATFORM_hid_open_path -#define hid_write PLATFORM_hid_write -#define hid_read_timeout PLATFORM_hid_read_timeout -#define hid_read PLATFORM_hid_read -#define hid_set_nonblocking PLATFORM_hid_set_nonblocking -#define hid_send_feature_report PLATFORM_hid_send_feature_report +#define hid_get_device_info PLATFORM_hid_get_device_info #define hid_get_feature_report PLATFORM_hid_get_feature_report -#define hid_close PLATFORM_hid_close +#define hid_get_indexed_string PLATFORM_hid_get_indexed_string +#define hid_get_input_report PLATFORM_hid_get_input_report #define hid_get_manufacturer_string PLATFORM_hid_get_manufacturer_string #define hid_get_product_string PLATFORM_hid_get_product_string +#define hid_get_report_descriptor PLATFORM_hid_get_report_descriptor #define hid_get_serial_number_string PLATFORM_hid_get_serial_number_string -#define hid_get_indexed_string PLATFORM_hid_get_indexed_string -#define hid_error PLATFORM_hid_error -#define new_hid_device PLATFORM_new_hid_device -#define free_hid_device PLATFORM_free_hid_device +#define hid_init PLATFORM_hid_init +#define hid_open_path PLATFORM_hid_open_path +#define hid_open PLATFORM_hid_open +#define hid_read PLATFORM_hid_read +#define hid_read_timeout PLATFORM_hid_read_timeout +#define hid_send_feature_report PLATFORM_hid_send_feature_report +#define hid_set_nonblocking PLATFORM_hid_set_nonblocking +#define hid_version PLATFORM_hid_version +#define hid_version_str PLATFORM_hid_version_str +#define hid_write PLATFORM_hid_write #define input_report PLATFORM_input_report -#define return_data PLATFORM_return_data #define make_path PLATFORM_make_path +#define new_hid_device PLATFORM_new_hid_device #define read_thread PLATFORM_read_thread +#define return_data PLATFORM_return_data -#undef HIDAPI_H__ #ifdef __LINUX__ - -#ifdef SDL_USE_LIBUDEV -static const SDL_UDEV_Symbols *udev_ctx = NULL; - -#define udev_device_get_sysattr_value udev_ctx->udev_device_get_sysattr_value -#define udev_new udev_ctx->udev_new -#define udev_unref udev_ctx->udev_unref -#define udev_device_new_from_devnum udev_ctx->udev_device_new_from_devnum -#define udev_device_get_parent_with_subsystem_devtype udev_ctx->udev_device_get_parent_with_subsystem_devtype -#define udev_device_unref udev_ctx->udev_device_unref -#define udev_enumerate_new udev_ctx->udev_enumerate_new -#define udev_enumerate_add_match_subsystem udev_ctx->udev_enumerate_add_match_subsystem -#define udev_enumerate_scan_devices udev_ctx->udev_enumerate_scan_devices -#define udev_enumerate_get_list_entry udev_ctx->udev_enumerate_get_list_entry -#define udev_list_entry_get_name udev_ctx->udev_list_entry_get_name -#define udev_device_new_from_syspath udev_ctx->udev_device_new_from_syspath -#define udev_device_get_devnode udev_ctx->udev_device_get_devnode -#define udev_list_entry_get_next udev_ctx->udev_list_entry_get_next -#define udev_enumerate_unref udev_ctx->udev_enumerate_unref - -#include "linux/hid.c" -#define HAVE_PLATFORM_BACKEND 1 -#endif /* SDL_USE_LIBUDEV */ - +#include "SDL_hidapi_linux.h" #elif defined(__MACOS__) -#include "mac/hid.c" -#define HAVE_PLATFORM_BACKEND 1 -#define udev_ctx 1 +#include "SDL_hidapi_mac.h" #elif defined(__WINDOWS__) || defined(__WINGDK__) -#include "windows/hid.c" -#define HAVE_PLATFORM_BACKEND 1 -#define udev_ctx 1 +#include "SDL_hidapi_windows.h" #elif defined(__ANDROID__) -/* The implementation for Android is in a separate .cpp file */ -#include "hidapi/hidapi.h" -#define HAVE_PLATFORM_BACKEND 1 -#define udev_ctx 1 +#include "SDL_hidapi_android.h" #elif defined(__IOS__) || defined(__TVOS__) -/* The implementation for iOS and tvOS is in a separate .m file */ -#include "hidapi/hidapi.h" -#define HAVE_PLATFORM_BACKEND 1 -#define udev_ctx 1 +#include "SDL_hidapi_ios.h" #endif +#undef api_version +#undef create_device_info_for_device +#undef free_hid_device +#undef hid_close #undef hid_device #undef hid_device_ -#undef hid_init -#undef hid_exit #undef hid_enumerate +#undef hid_error +#undef hid_exit #undef hid_free_enumeration -#undef hid_open -#undef hid_open_path -#undef hid_write -#undef hid_read_timeout -#undef hid_read -#undef hid_set_nonblocking -#undef hid_send_feature_report +#undef hid_get_device_info #undef hid_get_feature_report -#undef hid_close +#undef hid_get_indexed_string +#undef hid_get_input_report #undef hid_get_manufacturer_string #undef hid_get_product_string +#undef hid_get_report_descriptor #undef hid_get_serial_number_string -#undef hid_get_indexed_string -#undef hid_error -#undef new_hid_device -#undef free_hid_device +#undef hid_init +#undef hid_open +#undef hid_open_path +#undef hid_read +#undef hid_read_timeout +#undef hid_send_feature_report +#undef hid_set_nonblocking +#undef hid_version +#undef hid_version_str +#undef hid_write #undef input_report -#undef return_data #undef make_path +#undef new_hid_device #undef read_thread +#undef return_data #ifdef SDL_JOYSTICK_HIDAPI_STEAMXBOX #define HAVE_DRIVER_BACKEND 1 @@ -632,54 +621,62 @@ static const SDL_UDEV_Symbols *udev_ctx = NULL; /* DRIVER HIDAPI Implementation */ +struct DRIVER_hid_device_; +typedef struct DRIVER_hid_device_ DRIVER_hid_device; + +#define hid_close DRIVER_hid_close #define hid_device DRIVER_hid_device #define hid_device_ DRIVER_hid_device_ -#define hid_init DRIVER_hid_init -#define hid_exit DRIVER_hid_exit #define hid_enumerate DRIVER_hid_enumerate +#define hid_error DRIVER_hid_error +#define hid_exit DRIVER_hid_exit #define hid_free_enumeration DRIVER_hid_free_enumeration -#define hid_open DRIVER_hid_open -#define hid_open_path DRIVER_hid_open_path -#define hid_write DRIVER_hid_write -#define hid_read_timeout DRIVER_hid_read_timeout -#define hid_read DRIVER_hid_read -#define hid_set_nonblocking DRIVER_hid_set_nonblocking -#define hid_send_feature_report DRIVER_hid_send_feature_report +#define hid_get_device_info DRIVER_hid_device_info #define hid_get_feature_report DRIVER_hid_get_feature_report -#define hid_close DRIVER_hid_close +#define hid_get_indexed_string DRIVER_hid_get_indexed_string +#define hid_get_input_report DRIVER_hid_get_input_report #define hid_get_manufacturer_string DRIVER_hid_get_manufacturer_string #define hid_get_product_string DRIVER_hid_get_product_string +#define hid_get_report_descriptor DRIVER_hid_get_report_descriptor #define hid_get_serial_number_string DRIVER_hid_get_serial_number_string -#define hid_get_indexed_string DRIVER_hid_get_indexed_string -#define hid_error DRIVER_hid_error +#define hid_init DRIVER_hid_init +#define hid_open DRIVER_hid_open +#define hid_open_path DRIVER_hid_open_path +#define hid_read DRIVER_hid_read +#define hid_read_timeout DRIVER_hid_read_timeout +#define hid_send_feature_report DRIVER_hid_send_feature_report +#define hid_set_nonblocking DRIVER_hid_set_nonblocking +#define hid_write DRIVER_hid_write #ifdef SDL_JOYSTICK_HIDAPI_STEAMXBOX -#undef HIDAPI_H__ -#include "steamxbox/hid.c" +#include "SDL_hidapi_steamxbox.h" #else #error Need a driver hid.c for this platform! #endif +#undef hid_close #undef hid_device #undef hid_device_ -#undef hid_init -#undef hid_exit #undef hid_enumerate +#undef hid_error +#undef hid_exit #undef hid_free_enumeration -#undef hid_open -#undef hid_open_path -#undef hid_write -#undef hid_read_timeout -#undef hid_read -#undef hid_set_nonblocking -#undef hid_send_feature_report +#undef hid_get_device_info #undef hid_get_feature_report -#undef hid_close +#undef hid_get_indexed_string +#undef hid_get_input_report #undef hid_get_manufacturer_string #undef hid_get_product_string +#undef hid_get_report_descriptor #undef hid_get_serial_number_string -#undef hid_get_indexed_string -#undef hid_error +#undef hid_init +#undef hid_open +#undef hid_open_path +#undef hid_read +#undef hid_read_timeout +#undef hid_send_feature_report +#undef hid_set_nonblocking +#undef hid_write #endif /* HAVE_DRIVER_BACKEND */ @@ -707,9 +704,12 @@ static struct ); void (LIBUSB_CALL *free_config_descriptor)(struct libusb_config_descriptor *config); uint8_t (LIBUSB_CALL *get_bus_number)(libusb_device *dev); + int (LIBUSB_CALL *get_port_numbers)(libusb_device *dev, uint8_t *port_numbers, int port_numbers_len); uint8_t (LIBUSB_CALL *get_device_address)(libusb_device *dev); + int (LIBUSB_CALL *wrap_sys_device)(libusb_context *ctx, intptr_t sys_dev, libusb_device_handle **dev_handle); int (LIBUSB_CALL *open)(libusb_device *dev, libusb_device_handle **dev_handle); void (LIBUSB_CALL *close)(libusb_device_handle *dev_handle); + libusb_device *(LIBUSB_CALL *get_device)(libusb_device_handle *dev_handle); int (LIBUSB_CALL *claim_interface)(libusb_device_handle *dev_handle, int interface_number); int (LIBUSB_CALL *release_interface)(libusb_device_handle *dev_handle, int interface_number); int (LIBUSB_CALL *kernel_driver_active)(libusb_device_handle *dev_handle, int interface_number); @@ -754,9 +754,12 @@ static struct #define libusb_get_config_descriptor libusb_ctx.get_config_descriptor #define libusb_free_config_descriptor libusb_ctx.free_config_descriptor #define libusb_get_bus_number libusb_ctx.get_bus_number +#define libusb_get_port_numbers libusb_ctx.get_port_numbers #define libusb_get_device_address libusb_ctx.get_device_address +#define libusb_wrap_sys_device libusb_ctx.wrap_sys_device #define libusb_open libusb_ctx.open #define libusb_close libusb_ctx.close +#define libusb_get_device libusb_ctx.get_device #define libusb_claim_interface libusb_ctx.claim_interface #define libusb_release_interface libusb_ctx.release_interface #define libusb_kernel_driver_active libusb_ctx.kernel_driver_active @@ -773,48 +776,40 @@ static struct #define libusb_handle_events_completed libusb_ctx.handle_events_completed #define libusb_error_name libusb_ctx.error_name +struct LIBUSB_hid_device_; +typedef struct LIBUSB_hid_device_ LIBUSB_hid_device; + +#define free_hid_device LIBUSB_free_hid_device +#define hid_close LIBUSB_hid_close #define hid_device LIBUSB_hid_device #define hid_device_ LIBUSB_hid_device_ -#define hid_init LIBUSB_hid_init -#define hid_exit LIBUSB_hid_exit #define hid_enumerate LIBUSB_hid_enumerate +#define hid_error LIBUSB_hid_error +#define hid_exit LIBUSB_hid_exit #define hid_free_enumeration LIBUSB_hid_free_enumeration -#define hid_open LIBUSB_hid_open -#define hid_open_path LIBUSB_hid_open_path -#define hid_write LIBUSB_hid_write -#define hid_read_timeout LIBUSB_hid_read_timeout -#define hid_read LIBUSB_hid_read -#define hid_set_nonblocking LIBUSB_hid_set_nonblocking -#define hid_send_feature_report LIBUSB_hid_send_feature_report +#define hid_get_device_info LIBUSB_hid_get_device_info #define hid_get_feature_report LIBUSB_hid_get_feature_report -#define hid_close LIBUSB_hid_close +#define hid_get_indexed_string LIBUSB_hid_get_indexed_string +#define hid_get_input_report LIBUSB_hid_get_input_report #define hid_get_manufacturer_string LIBUSB_hid_get_manufacturer_string #define hid_get_product_string LIBUSB_hid_get_product_string +#define hid_get_report_descriptor LIBUSB_hid_get_report_descriptor #define hid_get_serial_number_string LIBUSB_hid_get_serial_number_string -#define hid_get_indexed_string LIBUSB_hid_get_indexed_string -#define hid_error LIBUSB_hid_error -#define new_hid_device LIBUSB_new_hid_device -#define free_hid_device LIBUSB_free_hid_device +#define hid_init LIBUSB_hid_init +#define hid_open LIBUSB_hid_open +#define hid_open_path LIBUSB_hid_open_path +#define hid_read LIBUSB_hid_read +#define hid_read_timeout LIBUSB_hid_read_timeout +#define hid_send_feature_report LIBUSB_hid_send_feature_report +#define hid_set_nonblocking LIBUSB_hid_set_nonblocking +#define hid_write LIBUSB_hid_write #define input_report LIBUSB_input_report -#define return_data LIBUSB_return_data #define make_path LIBUSB_make_path +#define new_hid_device LIBUSB_new_hid_device #define read_thread LIBUSB_read_thread +#define return_data LIBUSB_return_data -#ifndef __FreeBSD__ -/* this is awkwardly inlined, so we need to re-implement it here - * so we can override the libusb_control_transfer call */ -static int SDL_libusb_get_string_descriptor(libusb_device_handle *dev, - uint8_t descriptor_index, uint16_t lang_id, - unsigned char *data, int length) -{ - return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN | 0x0, LIBUSB_REQUEST_GET_DESCRIPTOR, (LIBUSB_DT_STRING << 8) | descriptor_index, lang_id, - data, (uint16_t)length, 1000); /* Endpoint 0 IN */ -} -#define libusb_get_string_descriptor SDL_libusb_get_string_descriptor -#endif /* __FreeBSD__ */ - -#undef HIDAPI_H__ -#include "libusb/hid.c" +#include "SDL_hidapi_libusb.h" #undef libusb_init #undef libusb_exit @@ -825,9 +820,12 @@ static int SDL_libusb_get_string_descriptor(libusb_device_handle *dev, #undef libusb_get_config_descriptor #undef libusb_free_config_descriptor #undef libusb_get_bus_number +#undef libusb_get_port_numbers #undef libusb_get_device_address +#undef libusb_wrap_sys_device #undef libusb_open #undef libusb_close +#undef libusb_get_device #undef libusb_claim_interface #undef libusb_release_interface #undef libusb_kernel_driver_active @@ -844,32 +842,35 @@ static int SDL_libusb_get_string_descriptor(libusb_device_handle *dev, #undef libusb_handle_events_completed #undef libusb_error_name +#undef free_hid_device +#undef hid_close #undef hid_device #undef hid_device_ -#undef hid_init -#undef hid_exit #undef hid_enumerate +#undef hid_error +#undef hid_exit #undef hid_free_enumeration -#undef hid_open -#undef hid_open_path -#undef hid_write -#undef hid_read_timeout -#undef hid_read -#undef hid_set_nonblocking -#undef hid_send_feature_report +#undef hid_get_device_info #undef hid_get_feature_report -#undef hid_close +#undef hid_get_indexed_string +#undef hid_get_input_report #undef hid_get_manufacturer_string #undef hid_get_product_string +#undef hid_get_report_descriptor #undef hid_get_serial_number_string -#undef hid_get_indexed_string -#undef hid_error -#undef new_hid_device -#undef free_hid_device +#undef hid_init +#undef hid_open +#undef hid_open_path +#undef hid_read +#undef hid_read_timeout +#undef hid_send_feature_report +#undef hid_set_nonblocking +#undef hid_write #undef input_report -#undef return_data #undef make_path +#undef new_hid_device #undef read_thread +#undef return_data #endif /* HAVE_LIBUSB */ @@ -885,11 +886,14 @@ struct hidapi_backend int (*hid_set_nonblocking)(void *device, int nonblock); int (*hid_send_feature_report)(void *device, const unsigned char *data, size_t length); int (*hid_get_feature_report)(void *device, unsigned char *data, size_t length); + int (*hid_get_input_report)(void *device, unsigned char *data, size_t length); void (*hid_close)(void *device); int (*hid_get_manufacturer_string)(void *device, wchar_t *string, size_t maxlen); int (*hid_get_product_string)(void *device, wchar_t *string, size_t maxlen); int (*hid_get_serial_number_string)(void *device, wchar_t *string, size_t maxlen); int (*hid_get_indexed_string)(void *device, int string_index, wchar_t *string, size_t maxlen); + struct hid_device_info *(*hid_get_device_info)(void *device); + int (*hid_get_report_descriptor)(void *device, unsigned char *buf, size_t buf_size); const wchar_t *(*hid_error)(void *device); }; @@ -901,11 +905,14 @@ static const struct hidapi_backend PLATFORM_Backend = { (void *)PLATFORM_hid_set_nonblocking, (void *)PLATFORM_hid_send_feature_report, (void *)PLATFORM_hid_get_feature_report, + (void *)PLATFORM_hid_get_input_report, (void *)PLATFORM_hid_close, (void *)PLATFORM_hid_get_manufacturer_string, (void *)PLATFORM_hid_get_product_string, (void *)PLATFORM_hid_get_serial_number_string, (void *)PLATFORM_hid_get_indexed_string, + (void *)PLATFORM_hid_get_device_info, + (void *)PLATFORM_hid_get_report_descriptor, (void *)PLATFORM_hid_error }; #endif /* HAVE_PLATFORM_BACKEND */ @@ -918,11 +925,14 @@ static const struct hidapi_backend DRIVER_Backend = { (void *)DRIVER_hid_set_nonblocking, (void *)DRIVER_hid_send_feature_report, (void *)DRIVER_hid_get_feature_report, + (void *)DRIVER_hid_get_input_report, (void *)DRIVER_hid_close, (void *)DRIVER_hid_get_manufacturer_string, (void *)DRIVER_hid_get_product_string, (void *)DRIVER_hid_get_serial_number_string, (void *)DRIVER_hid_get_indexed_string, + (void *)DRIVER_hid_get_device_info, + (void *)DRIVER_hid_get_report_descriptor, (void *)DRIVER_hid_error }; #endif /* HAVE_DRIVER_BACKEND */ @@ -935,11 +945,14 @@ static const struct hidapi_backend LIBUSB_Backend = { (void *)LIBUSB_hid_set_nonblocking, (void *)LIBUSB_hid_send_feature_report, (void *)LIBUSB_hid_get_feature_report, + (void *)LIBUSB_hid_get_input_report, (void *)LIBUSB_hid_close, (void *)LIBUSB_hid_get_manufacturer_string, (void *)LIBUSB_hid_get_product_string, (void *)LIBUSB_hid_get_serial_number_string, (void *)LIBUSB_hid_get_indexed_string, + (void *)LIBUSB_hid_get_device_info, + (void *)LIBUSB_hid_get_report_descriptor, (void *)LIBUSB_hid_error }; #endif /* HAVE_LIBUSB */ @@ -949,6 +962,7 @@ struct SDL_hid_device_ const void *magic; void *device; const struct hidapi_backend *backend; + SDL_hid_device_info info; }; static char device_magic; @@ -960,15 +974,19 @@ static SDL_hid_device *CreateHIDDeviceWrapper(void *device, const struct hidapi_ wrapper->magic = &device_magic; wrapper->device = device; wrapper->backend = backend; + SDL_zero(wrapper->info); return wrapper; } #endif /* HAVE_PLATFORM_BACKEND || HAVE_DRIVER_BACKEND || HAVE_LIBUSB */ -static void -DeleteHIDDeviceWrapper(SDL_hid_device *device) +static void DeleteHIDDeviceWrapper(SDL_hid_device *device) { device->magic = NULL; + SDL_free(device->info.path); + SDL_free(device->info.serial_number); + SDL_free(device->info.manufacturer_string); + SDL_free(device->info.product_string); SDL_free(device); } @@ -978,9 +996,6 @@ DeleteHIDDeviceWrapper(SDL_hid_device *device) return retval; \ } -#ifndef SDL_HIDAPI_DISABLED -#if defined(HAVE_PLATFORM_BACKEND) || defined(HAVE_DRIVER_BACKEND) || defined(HAVE_LIBUSB) - #define COPY_IF_EXISTS(var) \ if (pSrc->var != NULL) { \ pDst->var = SDL_strdup(pSrc->var); \ @@ -994,8 +1009,7 @@ DeleteHIDDeviceWrapper(SDL_hid_device *device) pDst->var = NULL; \ } -static void -CopyHIDDeviceInfo(struct SDL_hid_device_info *pSrc, struct SDL_hid_device_info *pDst) +static void CopyHIDDeviceInfo(struct hid_device_info *pSrc, struct SDL_hid_device_info *pDst) { COPY_IF_EXISTS(path) pDst->vendor_id = pSrc->vendor_id; @@ -1010,16 +1024,15 @@ CopyHIDDeviceInfo(struct SDL_hid_device_info *pSrc, struct SDL_hid_device_info * pDst->interface_class = pSrc->interface_class; pDst->interface_subclass = pSrc->interface_subclass; pDst->interface_protocol = pSrc->interface_protocol; + pDst->bus_type = (SDL_hid_bus_type)pSrc->bus_type; pDst->next = NULL; } #undef COPY_IF_EXISTS #undef WCOPY_IF_EXISTS -#endif /* HAVE_PLATFORM_BACKEND || HAVE_DRIVER_BACKEND || HAVE_LIBUSB */ -#endif /* !SDL_HIDAPI_DISABLED */ - static int SDL_hidapi_refcount = 0; +static char *SDL_hidapi_ignored_devices = NULL; static void SDL_SetHIDAPIError(const wchar_t *error) { @@ -1032,6 +1045,33 @@ static void SDL_SetHIDAPIError(const wchar_t *error) } } +static void SDLCALL IgnoredDevicesChanged(void *userdata, const char *name, const char *oldValue, const char *hint) +{ + if (SDL_hidapi_ignored_devices) { + SDL_free(SDL_hidapi_ignored_devices); + } + if (hint && *hint) { + SDL_hidapi_ignored_devices = SDL_strdup(hint); + } else { + SDL_hidapi_ignored_devices = NULL; + } +} + +SDL_bool SDL_HIDAPI_ShouldIgnoreDevice(Uint16 vendor_id, Uint16 product_id) +{ + /* See if there are any devices we should skip in enumeration */ + if (SDL_hidapi_ignored_devices) { + char vendor_match[16], product_match[16]; + SDL_snprintf(vendor_match, sizeof(vendor_match), "0x%.4x/0x0000", vendor_id); + SDL_snprintf(product_match, sizeof(product_match), "0x%.4x/0x%.4x", vendor_id, product_id); + if (SDL_strcasestr(SDL_hidapi_ignored_devices, vendor_match) || + SDL_strcasestr(SDL_hidapi_ignored_devices, product_match)) { + return SDL_TRUE; + } + } + return SDL_FALSE; +} + int SDL_hid_init(void) { int attempts = 0, success = 0; @@ -1041,6 +1081,8 @@ int SDL_hid_init(void) return 0; } + SDL_AddHintCallback(SDL_HINT_HIDAPI_IGNORE_DEVICES, IgnoredDevicesChanged, NULL); + #ifdef SDL_USE_LIBUDEV if (SDL_getenv("SDL_HIDAPI_JOYSTICK_DISABLE_UDEV") != NULL) { SDL_LogDebug(SDL_LOG_CATEGORY_INPUT, @@ -1089,9 +1131,12 @@ int SDL_hid_init(void) LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device *, uint8_t, struct libusb_config_descriptor **), get_config_descriptor) LOAD_LIBUSB_SYMBOL(void (LIBUSB_CALL *)(struct libusb_config_descriptor *), free_config_descriptor) LOAD_LIBUSB_SYMBOL(uint8_t (LIBUSB_CALL *)(libusb_device *), get_bus_number) + LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device *dev, uint8_t *port_numbers, int port_numbers_len), get_port_numbers) LOAD_LIBUSB_SYMBOL(uint8_t (LIBUSB_CALL *)(libusb_device *), get_device_address) + LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_context *ctx, intptr_t sys_dev, libusb_device_handle **dev_handle), wrap_sys_device) LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device *, libusb_device_handle **), open) LOAD_LIBUSB_SYMBOL(void (LIBUSB_CALL *)(libusb_device_handle *), close) + LOAD_LIBUSB_SYMBOL(libusb_device * (LIBUSB_CALL *)(libusb_device_handle *dev_handle), get_device) LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device_handle *, int), claim_interface) LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device_handle *, int), release_interface) LOAD_LIBUSB_SYMBOL(int (LIBUSB_CALL *)(libusb_device_handle *, int), kernel_driver_active) @@ -1181,6 +1226,13 @@ int SDL_hid_exit(void) } #endif /* HAVE_LIBUSB */ + SDL_DelHintCallback(SDL_HINT_HIDAPI_IGNORE_DEVICES, IgnoredDevicesChanged, NULL); + + if (SDL_hidapi_ignored_devices) { + SDL_free(SDL_hidapi_ignored_devices); + SDL_hidapi_ignored_devices = NULL; + } + return result; } @@ -1210,16 +1262,16 @@ struct SDL_hid_device_info *SDL_hid_enumerate(unsigned short vendor_id, unsigned { #if defined(HAVE_PLATFORM_BACKEND) || defined(HAVE_DRIVER_BACKEND) || defined(HAVE_LIBUSB) #ifdef HAVE_LIBUSB - struct SDL_hid_device_info *usb_devs = NULL; - struct SDL_hid_device_info *usb_dev; + struct hid_device_info *usb_devs = NULL; + struct hid_device_info *usb_dev; #endif #ifdef HAVE_DRIVER_BACKEND - struct SDL_hid_device_info *driver_devs = NULL; - struct SDL_hid_device_info *driver_dev; + struct hid_device_info *driver_devs = NULL; + struct hid_device_info *driver_dev; #endif #ifdef HAVE_PLATFORM_BACKEND - struct SDL_hid_device_info *raw_devs = NULL; - struct SDL_hid_device_info *raw_dev; + struct hid_device_info *raw_devs = NULL; + struct hid_device_info *raw_dev; #endif struct SDL_hid_device_info *devs = NULL, *last = NULL, *new_dev; @@ -1398,7 +1450,7 @@ SDL_hid_device *SDL_hid_open(unsigned short vendor_id, unsigned short product_id return NULL; } -SDL_hid_device *SDL_hid_open_path(const char *path, int bExclusive /* = false */) +SDL_hid_device *SDL_hid_open_path(const char *path) { #if defined(HAVE_PLATFORM_BACKEND) || defined(HAVE_DRIVER_BACKEND) || defined(HAVE_LIBUSB) void *pDevice = NULL; @@ -1409,7 +1461,7 @@ SDL_hid_device *SDL_hid_open_path(const char *path, int bExclusive /* = false */ #ifdef HAVE_PLATFORM_BACKEND if (udev_ctx) { - pDevice = PLATFORM_hid_open_path(path, bExclusive); + pDevice = PLATFORM_hid_open_path(path); if (pDevice != NULL) { return CreateHIDDeviceWrapper(pDevice, &PLATFORM_Backend); } @@ -1417,7 +1469,7 @@ SDL_hid_device *SDL_hid_open_path(const char *path, int bExclusive /* = false */ #endif /* HAVE_PLATFORM_BACKEND */ #ifdef HAVE_DRIVER_BACKEND - pDevice = DRIVER_hid_open_path(path, bExclusive); + pDevice = DRIVER_hid_open_path(path); if (pDevice != NULL) { return CreateHIDDeviceWrapper(pDevice, &DRIVER_Backend); } @@ -1425,7 +1477,7 @@ SDL_hid_device *SDL_hid_open_path(const char *path, int bExclusive /* = false */ #ifdef HAVE_LIBUSB if (libusb_ctx.libhandle != NULL) { - pDevice = LIBUSB_hid_open_path(path, bExclusive); + pDevice = LIBUSB_hid_open_path(path); if (pDevice != NULL) { return CreateHIDDeviceWrapper(pDevice, &LIBUSB_Backend); } @@ -1515,6 +1567,19 @@ int SDL_hid_get_feature_report(SDL_hid_device *device, unsigned char *data, size return result; } +int SDL_hid_get_input_report(SDL_hid_device *device, unsigned char *data, size_t length) +{ + int result; + + CHECK_DEVICE_MAGIC(device, -1); + + result = device->backend->hid_get_input_report(device->device, data, length); + if (result < 0) { + SDL_SetHIDAPIError(device->backend->hid_error(device->device)); + } + return result; +} + int SDL_hid_close(SDL_hid_device *device) { CHECK_DEVICE_MAGIC(device, -1); @@ -1576,9 +1641,39 @@ int SDL_hid_get_indexed_string(SDL_hid_device *device, int string_index, wchar_t return result; } +SDL_hid_device_info *SDL_hid_get_device_info(SDL_hid_device *device) +{ + struct hid_device_info *info; + + CHECK_DEVICE_MAGIC(device, NULL); + + info = device->backend->hid_get_device_info(device->device); + if (info) { + CopyHIDDeviceInfo(info, &device->info); + return &device->info; + } else { + SDL_SetHIDAPIError(device->backend->hid_error(device->device)); + return NULL; + } +} + +int SDL_hid_get_report_descriptor(SDL_hid_device *device, unsigned char *buf, size_t buf_size) +{ + int result; + + CHECK_DEVICE_MAGIC(device, -1); + + result = device->backend->hid_get_report_descriptor(device->device, buf, buf_size); + if (result < 0) { + SDL_SetHIDAPIError(device->backend->hid_error(device->device)); + } + return result; +} + void SDL_hid_ble_scan(SDL_bool active) { #if !defined(SDL_HIDAPI_DISABLED) && (defined(__IOS__) || defined(__TVOS__)) + extern void hid_ble_scan(int bStart); hid_ble_scan(active); #endif } diff --git a/src/hidapi/SDL_hidapi_android.h b/src/hidapi/SDL_hidapi_android.h new file mode 100644 index 0000000000000..4fe554c7e57b8 --- /dev/null +++ b/src/hidapi/SDL_hidapi_android.h @@ -0,0 +1,26 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* The implementation for Android is in a separate .cpp file */ +#undef HIDAPI_H__ +#include "hidapi/hidapi.h" +#define HAVE_PLATFORM_BACKEND 1 +#define udev_ctx 1 diff --git a/src/hidapi/SDL_hidapi_c.h b/src/hidapi/SDL_hidapi_c.h index 2b9b7d21c6962..8f69cba4c5bfb 100644 --- a/src/hidapi/SDL_hidapi_c.h +++ b/src/hidapi/SDL_hidapi_c.h @@ -20,8 +20,11 @@ */ #include "SDL_internal.h" -#ifdef SDL_JOYSTICK_HIDAPI +/* Return true if the HIDAPI should ignore a device during enumeration */ +extern SDL_bool SDL_HIDAPI_ShouldIgnoreDevice(Uint16 vendor_id, Uint16 product_id); + +#ifdef SDL_JOYSTICK_HIDAPI #ifdef HAVE_LIBUSB #define HAVE_ENABLE_GAMECUBE_ADAPTORS #endif @@ -29,5 +32,4 @@ #ifdef HAVE_ENABLE_GAMECUBE_ADAPTORS extern void SDL_EnableGameCubeAdaptors(void); #endif - #endif /* SDL_JOYSTICK_HIDAPI */ diff --git a/src/hidapi/SDL_hidapi_ios.h b/src/hidapi/SDL_hidapi_ios.h new file mode 100644 index 0000000000000..c921fde332b16 --- /dev/null +++ b/src/hidapi/SDL_hidapi_ios.h @@ -0,0 +1,26 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* The implementation for iOS and tvOS is in a separate .m file */ +#undef HIDAPI_H__ +#include "hidapi/hidapi.h" +#define HAVE_PLATFORM_BACKEND 1 +#define udev_ctx 1 diff --git a/src/hidapi/SDL_hidapi_libusb.h b/src/hidapi/SDL_hidapi_libusb.h new file mode 100644 index 0000000000000..e0a1248338344 --- /dev/null +++ b/src/hidapi/SDL_hidapi_libusb.h @@ -0,0 +1,238 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* Define standard library functions in terms of SDL */ +#define HIDAPI_USING_SDL_RUNTIME +#define free SDL_free +#define iconv_t SDL_iconv_t +#define ICONV_CONST +#define iconv(a,b,c,d,e) SDL_iconv(a, (const char **)b, c, d, e) +#define iconv_open SDL_iconv_open +#define iconv_close SDL_iconv_close +#define malloc SDL_malloc +#define realloc SDL_realloc +#define setlocale(X, Y) NULL +#define snprintf SDL_snprintf +#define strcmp SDL_strcmp +#define strdup SDL_strdup +#define strncpy SDL_strlcpy +#ifdef tolower +#undef tolower +#endif +#define tolower SDL_tolower +#define wcsdup SDL_wcsdup + + +#ifndef __FreeBSD__ +/* this is awkwardly inlined, so we need to re-implement it here + * so we can override the libusb_control_transfer call */ +static int SDL_libusb_get_string_descriptor(libusb_device_handle *dev, + uint8_t descriptor_index, uint16_t lang_id, + unsigned char *data, int length) +{ + return libusb_control_transfer(dev, LIBUSB_ENDPOINT_IN | 0x0, LIBUSB_REQUEST_GET_DESCRIPTOR, (LIBUSB_DT_STRING << 8) | descriptor_index, lang_id, + data, (uint16_t)length, 1000); /* Endpoint 0 IN */ +} +#define libusb_get_string_descriptor SDL_libusb_get_string_descriptor +#endif /* __FreeBSD__ */ + +#define HIDAPI_THREAD_STATE_DEFINED + +/* Barrier implementation because Android/Bionic don't have pthread_barrier. + This implementation came from Brent Priddy and was posted on + StackOverflow. It is used with his permission. */ + +typedef struct _SDL_ThreadBarrier +{ + SDL_Mutex *mutex; + SDL_Condition *cond; + Uint32 count; + Uint32 trip_count; +} SDL_ThreadBarrier; + +static int SDL_CreateThreadBarrier(SDL_ThreadBarrier *barrier, Uint32 count) +{ + SDL_assert(barrier != NULL); + SDL_assert(count != 0); + + barrier->mutex = SDL_CreateMutex(); + if (barrier->mutex == NULL) { + return -1; /* Error set by CreateMutex */ + } + barrier->cond = SDL_CreateCondition(); + if (barrier->cond == NULL) { + return -1; /* Error set by CreateCond */ + } + + barrier->trip_count = count; + barrier->count = 0; + + return 0; +} + +static void SDL_DestroyThreadBarrier(SDL_ThreadBarrier *barrier) +{ + SDL_DestroyCondition(barrier->cond); + SDL_DestroyMutex(barrier->mutex); +} + +static int SDL_WaitThreadBarrier(SDL_ThreadBarrier *barrier) +{ + SDL_LockMutex(barrier->mutex); + barrier->count += 1; + if (barrier->count >= barrier->trip_count) { + barrier->count = 0; + SDL_BroadcastCondition(barrier->cond); + SDL_UnlockMutex(barrier->mutex); + return 1; + } + SDL_WaitCondition(barrier->cond, barrier->mutex); + SDL_UnlockMutex(barrier->mutex); + return 0; +} + +#include "../thread/SDL_systhread.h" + +#define THREAD_STATE_WAIT_TIMED_OUT SDL_MUTEX_TIMEDOUT + +typedef struct +{ + SDL_Thread *thread; + SDL_Mutex *mutex; /* Protects input_reports */ + SDL_Condition *condition; + SDL_ThreadBarrier barrier; /* Ensures correct startup sequence */ + +} hid_device_thread_state; + +static void thread_state_init(hid_device_thread_state *state) +{ + state->mutex = SDL_CreateMutex(); + state->condition = SDL_CreateCondition(); + SDL_CreateThreadBarrier(&state->barrier, 2); +} + +static void thread_state_free(hid_device_thread_state *state) +{ + SDL_DestroyThreadBarrier(&state->barrier); + SDL_DestroyCondition(state->condition); + SDL_DestroyMutex(state->mutex); +} + +static void thread_state_push_cleanup(void (*routine)(void *), void *arg) +{ + /* There isn't an equivalent in SDL, and it's only useful for threads calling hid_read_timeout() */ +} + +static void thread_state_pop_cleanup(int execute) +{ +} + +static void thread_state_lock(hid_device_thread_state *state) +{ + SDL_LockMutex(state->mutex); +} + +static void thread_state_unlock(hid_device_thread_state *state) +{ + SDL_UnlockMutex(state->mutex); +} + +static void thread_state_wait_condition(hid_device_thread_state *state) +{ + SDL_WaitCondition(state->condition, state->mutex); +} + +static int thread_state_wait_condition_timeout(hid_device_thread_state *state, struct timespec *ts) +{ + Uint64 end_time; + Sint64 timeout_ns; + Sint32 timeout_ms; + + end_time = ts->tv_sec; + end_time *= 1000000000L; + end_time += ts->tv_nsec; + timeout_ns = (Sint64)(end_time - SDL_GetTicksNS()); + if (timeout_ns <= 0) { + timeout_ms = 0; + } else { + timeout_ms = (Sint32)SDL_NS_TO_MS(timeout_ns); + } + return SDL_WaitConditionTimeout(state->condition, state->mutex, timeout_ms); +} + +static void thread_state_signal_condition(hid_device_thread_state *state) +{ + SDL_SignalCondition(state->condition); +} + +static void thread_state_broadcast_condition(hid_device_thread_state *state) +{ + SDL_BroadcastCondition(state->condition); +} + +static void thread_state_wait_barrier(hid_device_thread_state *state) +{ + SDL_WaitThreadBarrier(&state->barrier); +} + +typedef struct +{ + void *(*func)(void*); + void *func_arg; + +} RunInputThreadParam; + +static int RunInputThread(void *param) +{ + RunInputThreadParam *data = (RunInputThreadParam *)param; + void *(*func)(void*) = data->func; + void *func_arg = data->func_arg; + SDL_free(data); + func(func_arg); + return 0; +} + +static void thread_state_create_thread(hid_device_thread_state *state, void *(*func)(void*), void *func_arg) +{ + RunInputThreadParam *param = (RunInputThreadParam *)malloc(sizeof(*param)); + /* Note that the hidapi code didn't check for thread creation failure. + * We'll crash if malloc() fails + */ + param->func = func; + param->func_arg = func_arg; + state->thread = SDL_CreateThreadInternal(RunInputThread, "libusb", 0, param); +} + +static void thread_state_join_thread(hid_device_thread_state *state) +{ + SDL_WaitThread(state->thread, NULL); +} + +static void thread_state_get_current_time(struct timespec *ts) +{ + Uint64 ns = SDL_GetTicksNS(); + + ts->tv_sec = ns / 1000000000L; + ts->tv_nsec = ns % 1000000000L; +} + +#undef HIDAPI_H__ +#include "libusb/hid.c" diff --git a/src/hidapi/SDL_hidapi_linux.h b/src/hidapi/SDL_hidapi_linux.h new file mode 100644 index 0000000000000..f06627608092d --- /dev/null +++ b/src/hidapi/SDL_hidapi_linux.h @@ -0,0 +1,46 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#ifdef SDL_USE_LIBUDEV +static const SDL_UDEV_Symbols *udev_ctx = NULL; + +#define udev_device_get_devnode udev_ctx->udev_device_get_devnode +#define udev_device_get_parent_with_subsystem_devtype udev_ctx->udev_device_get_parent_with_subsystem_devtype +#define udev_device_get_sysattr_value udev_ctx->udev_device_get_sysattr_value +#define udev_device_get_syspath udev_ctx->udev_device_get_syspath +#define udev_device_new_from_devnum udev_ctx->udev_device_new_from_devnum +#define udev_device_new_from_syspath udev_ctx->udev_device_new_from_syspath +#define udev_device_unref udev_ctx->udev_device_unref +#define udev_enumerate_add_match_subsystem udev_ctx->udev_enumerate_add_match_subsystem +#define udev_enumerate_get_list_entry udev_ctx->udev_enumerate_get_list_entry +#define udev_enumerate_new udev_ctx->udev_enumerate_new +#define udev_enumerate_scan_devices udev_ctx->udev_enumerate_scan_devices +#define udev_enumerate_unref udev_ctx->udev_enumerate_unref +#define udev_list_entry_get_name udev_ctx->udev_list_entry_get_name +#define udev_list_entry_get_next udev_ctx->udev_list_entry_get_next +#define udev_new udev_ctx->udev_new +#define udev_unref udev_ctx->udev_unref + +#undef HIDAPI_H__ +#include "linux/hid.c" +#define HAVE_PLATFORM_BACKEND 1 + +#endif /* SDL_USE_LIBUDEV */ diff --git a/src/hidapi/SDL_hidapi_mac.h b/src/hidapi/SDL_hidapi_mac.h new file mode 100644 index 0000000000000..d7c0f50044a40 --- /dev/null +++ b/src/hidapi/SDL_hidapi_mac.h @@ -0,0 +1,25 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#undef HIDAPI_H__ +#include "mac/hid.c" +#define HAVE_PLATFORM_BACKEND 1 +#define udev_ctx 1 diff --git a/src/hidapi/SDL_hidapi_steamxbox.h b/src/hidapi/SDL_hidapi_steamxbox.h new file mode 100644 index 0000000000000..0570acb38d87f --- /dev/null +++ b/src/hidapi/SDL_hidapi_steamxbox.h @@ -0,0 +1,23 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +#undef HIDAPI_H__ +#include "steamxbox/hid.c" diff --git a/src/hidapi/SDL_hidapi_windows.h b/src/hidapi/SDL_hidapi_windows.h new file mode 100644 index 0000000000000..b09b0457eaade --- /dev/null +++ b/src/hidapi/SDL_hidapi_windows.h @@ -0,0 +1,40 @@ +/* + Simple DirectMedia Layer + Copyright (C) 1997-2023 Sam Lantinga + + This software is provided 'as-is', without any express or implied + warranty. In no event will the authors be held liable for any damages + arising from the use of this software. + + Permission is granted to anyone to use this software for any purpose, + including commercial applications, and to alter it and redistribute it + freely, subject to the following restrictions: + + 1. The origin of this software must not be misrepresented; you must not + claim that you wrote the original software. If you use this software + in a product, an acknowledgment in the product documentation would be + appreciated but is not required. + 2. Altered source versions must be plainly marked as such, and must not be + misrepresented as being the original software. + 3. This notice may not be removed or altered from any source distribution. +*/ + +/* Define standard library functions in terms of SDL */ +#define HIDAPI_USING_SDL_RUNTIME +#define calloc SDL_calloc +#define free SDL_free +#define malloc SDL_malloc +#define memcmp SDL_memcmp +#define swprintf SDL_swprintf +#define towupper SDL_toupper +#define wcscmp SDL_wcscmp +#define _wcsdup SDL_wcsdup +#define wcslen SDL_wcslen +#define wcsncpy SDL_wcslcpy +#define wcsstr SDL_wcsstr +#define wcstol SDL_wcstol + +#undef HIDAPI_H__ +#include "windows/hid.c" +#define HAVE_PLATFORM_BACKEND 1 +#define udev_ctx 1 diff --git a/src/hidapi/VERSION b/src/hidapi/VERSION new file mode 100644 index 0000000000000..0548fb4e9b2f2 --- /dev/null +++ b/src/hidapi/VERSION @@ -0,0 +1 @@ +0.14.0 \ No newline at end of file diff --git a/src/hidapi/android/hid.cpp b/src/hidapi/android/hid.cpp index 450cab2084043..6a8dac407db73 100644 --- a/src/hidapi/android/hid.cpp +++ b/src/hidapi/android/hid.cpp @@ -51,26 +51,36 @@ #ifndef SDL_HIDAPI_DISABLED +extern "C" { +#include "../SDL_hidapi_c.h" +} #include "../../core/android/SDL_android.h" -#define hid_init PLATFORM_hid_init -#define hid_exit PLATFORM_hid_exit -#define hid_enumerate PLATFORM_hid_enumerate -#define hid_free_enumeration PLATFORM_hid_free_enumeration -#define hid_open PLATFORM_hid_open -#define hid_open_path PLATFORM_hid_open_path -#define hid_write PLATFORM_hid_write -#define hid_read_timeout PLATFORM_hid_read_timeout -#define hid_read PLATFORM_hid_read -#define hid_set_nonblocking PLATFORM_hid_set_nonblocking -#define hid_send_feature_report PLATFORM_hid_send_feature_report -#define hid_get_feature_report PLATFORM_hid_get_feature_report -#define hid_close PLATFORM_hid_close -#define hid_get_manufacturer_string PLATFORM_hid_get_manufacturer_string -#define hid_get_product_string PLATFORM_hid_get_product_string -#define hid_get_serial_number_string PLATFORM_hid_get_serial_number_string -#define hid_get_indexed_string PLATFORM_hid_get_indexed_string -#define hid_error PLATFORM_hid_error +#define hid_close PLATFORM_hid_close +#define hid_device PLATFORM_hid_device +#define hid_device_ PLATFORM_hid_device_ +#define hid_enumerate PLATFORM_hid_enumerate +#define hid_error PLATFORM_hid_error +#define hid_exit PLATFORM_hid_exit +#define hid_free_enumeration PLATFORM_hid_free_enumeration +#define hid_get_device_info PLATFORM_hid_get_device_info +#define hid_get_feature_report PLATFORM_hid_get_feature_report +#define hid_get_indexed_string PLATFORM_hid_get_indexed_string +#define hid_get_input_report PLATFORM_hid_get_input_report +#define hid_get_manufacturer_string PLATFORM_hid_get_manufacturer_string +#define hid_get_product_string PLATFORM_hid_get_product_string +#define hid_get_report_descriptor PLATFORM_hid_get_report_descriptor +#define hid_get_serial_number_string PLATFORM_hid_get_serial_number_string +#define hid_init PLATFORM_hid_init +#define hid_open_path PLATFORM_hid_open_path +#define hid_open PLATFORM_hid_open +#define hid_read PLATFORM_hid_read +#define hid_read_timeout PLATFORM_hid_read_timeout +#define hid_send_feature_report PLATFORM_hid_send_feature_report +#define hid_set_nonblocking PLATFORM_hid_set_nonblocking +#define hid_version PLATFORM_hid_version +#define hid_version_str PLATFORM_hid_version_str +#define hid_write PLATFORM_hid_write #include #include // For ETIMEDOUT and ECONNRESET @@ -381,9 +391,8 @@ static jclass g_HIDDeviceManagerCallbackClass; static jobject g_HIDDeviceManagerCallbackHandler; static jmethodID g_midHIDDeviceManagerInitialize; static jmethodID g_midHIDDeviceManagerOpen; -static jmethodID g_midHIDDeviceManagerSendOutputReport; -static jmethodID g_midHIDDeviceManagerSendFeatureReport; -static jmethodID g_midHIDDeviceManagerGetFeatureReport; +static jmethodID g_midHIDDeviceManagerWriteReport; +static jmethodID g_midHIDDeviceManagerReadReport; static jmethodID g_midHIDDeviceManagerClose; static bool g_initialized = false; @@ -469,7 +478,7 @@ class CHIDDevice return m_nId; } - const hid_device_info *GetDeviceInfo() + hid_device_info *GetDeviceInfo() { return m_pInfo; } @@ -599,7 +608,7 @@ class CHIDDevice return (int)nDataLen; } - int SendOutputReport( const unsigned char *pData, size_t nDataLen ) + int WriteReport( const unsigned char *pData, size_t nDataLen, bool bFeature ) { // Make sure thread is attached to JVM/env JNIEnv *env; @@ -610,53 +619,31 @@ class CHIDDevice if ( g_HIDDeviceManagerCallbackHandler ) { jbyteArray pBuf = NewByteArray( env, pData, nDataLen ); - nRet = env->CallIntMethod( g_HIDDeviceManagerCallbackHandler, g_midHIDDeviceManagerSendOutputReport, m_nId, pBuf ); - ExceptionCheck( env, "SendOutputReport" ); + nRet = env->CallIntMethod( g_HIDDeviceManagerCallbackHandler, g_midHIDDeviceManagerWriteReport, m_nId, pBuf, bFeature ); + ExceptionCheck( env, "WriteReport" ); env->DeleteLocalRef( pBuf ); } else { - LOGV( "SendOutputReport without callback handler" ); + LOGV( "WriteReport without callback handler" ); } return nRet; } - int SendFeatureReport( const unsigned char *pData, size_t nDataLen ) - { - // Make sure thread is attached to JVM/env - JNIEnv *env; - g_JVM->AttachCurrentThread( &env, NULL ); - pthread_setspecific( g_ThreadKey, (void*)env ); - - int nRet = -1; - if ( g_HIDDeviceManagerCallbackHandler ) - { - jbyteArray pBuf = NewByteArray( env, pData, nDataLen ); - nRet = env->CallIntMethod( g_HIDDeviceManagerCallbackHandler, g_midHIDDeviceManagerSendFeatureReport, m_nId, pBuf ); - ExceptionCheck( env, "SendFeatureReport" ); - env->DeleteLocalRef( pBuf ); - } - else - { - LOGV( "SendFeatureReport without callback handler" ); - } - return nRet; - } - - void ProcessFeatureReport( const uint8_t *pBuf, size_t nBufSize ) + void ProcessReportResponse( const uint8_t *pBuf, size_t nBufSize ) { hid_mutex_guard cvl( &m_cvLock ); - if ( m_bIsWaitingForFeatureReport ) + if ( m_bIsWaitingForReportResponse ) { - m_featureReport.assign( pBuf, nBufSize ); + m_reportResponse.assign( pBuf, nBufSize ); - m_bIsWaitingForFeatureReport = false; - m_nFeatureReportError = 0; + m_bIsWaitingForReportResponse = false; + m_nReportResponseError = 0; pthread_cond_signal( &m_cv ); } } - int GetFeatureReport( unsigned char *pData, size_t nDataLen ) + int ReadReport( unsigned char *pData, size_t nDataLen, bool bFeature ) { // Make sure thread is attached to JVM/env JNIEnv *env; @@ -665,34 +652,34 @@ class CHIDDevice if ( !g_HIDDeviceManagerCallbackHandler ) { - LOGV( "GetFeatureReport without callback handler" ); + LOGV( "ReadReport without callback handler" ); return -1; } { hid_mutex_guard cvl( &m_cvLock ); - if ( m_bIsWaitingForFeatureReport ) + if ( m_bIsWaitingForReportResponse ) { LOGV( "Get feature report already ongoing... bail" ); return -1; // Read already ongoing, we currently do not serialize, TODO } - m_bIsWaitingForFeatureReport = true; + m_bIsWaitingForReportResponse = true; } jbyteArray pBuf = NewByteArray( env, pData, nDataLen ); - int nRet = env->CallBooleanMethod( g_HIDDeviceManagerCallbackHandler, g_midHIDDeviceManagerGetFeatureReport, m_nId, pBuf ) ? 0 : -1; - ExceptionCheck( env, "GetFeatureReport" ); + int nRet = env->CallBooleanMethod( g_HIDDeviceManagerCallbackHandler, g_midHIDDeviceManagerReadReport, m_nId, pBuf, bFeature ) ? 0 : -1; + ExceptionCheck( env, "ReadReport" ); env->DeleteLocalRef( pBuf ); if ( nRet < 0 ) { - LOGV( "GetFeatureReport failed" ); - m_bIsWaitingForFeatureReport = false; + LOGV( "ReadReport failed" ); + m_bIsWaitingForReportResponse = false; return -1; } { hid_mutex_guard cvl( &m_cvLock ); - if ( m_bIsWaitingForFeatureReport ) + if ( m_bIsWaitingForReportResponse ) { LOGV("=== Going to sleep" ); // Wait in CV until we are no longer waiting for a feature report. @@ -708,24 +695,24 @@ class CHIDDevice break; } } - while ( m_bIsWaitingForFeatureReport && get_timespec_ms( ts ) < get_timespec_ms( endtime ) ); + while ( m_bIsWaitingForReportResponse && get_timespec_ms( ts ) < get_timespec_ms( endtime ) ); // We are back - if ( m_bIsWaitingForFeatureReport ) + if ( m_bIsWaitingForReportResponse ) { - m_nFeatureReportError = -ETIMEDOUT; - m_bIsWaitingForFeatureReport = false; + m_nReportResponseError = -ETIMEDOUT; + m_bIsWaitingForReportResponse = false; } - LOGV( "=== Got feature report err=%d", m_nFeatureReportError ); - if ( m_nFeatureReportError != 0 ) + LOGV( "=== Got feature report err=%d", m_nReportResponseError ); + if ( m_nReportResponseError != 0 ) { - return m_nFeatureReportError; + return m_nReportResponseError; } } - size_t uBytesToCopy = m_featureReport.size() > nDataLen ? nDataLen : m_featureReport.size(); - SDL_memcpy( pData, m_featureReport.data(), uBytesToCopy ); - m_featureReport.clear(); + size_t uBytesToCopy = m_reportResponse.size() > nDataLen ? nDataLen : m_reportResponse.size(); + SDL_memcpy( pData, m_reportResponse.data(), uBytesToCopy ); + m_reportResponse.clear(); LOGV( "=== Got %u bytes", uBytesToCopy ); return (int)uBytesToCopy; @@ -750,9 +737,9 @@ class CHIDDevice // Clean and release pending feature report reads hid_mutex_guard cvLock( &m_cvLock ); - m_featureReport.clear(); - m_bIsWaitingForFeatureReport = false; - m_nFeatureReportError = -ECONNRESET; + m_reportResponse.clear(); + m_bIsWaitingForReportResponse = false; + m_nReportResponseError = -ECONNRESET; pthread_cond_broadcast( &m_cv ); if ( bDeleteDevice ) @@ -778,9 +765,9 @@ class CHIDDevice pthread_cond_t m_cv = PTHREAD_COND_INITIALIZER; bool m_bIsWaitingForOpen = false; bool m_bOpenResult = false; - bool m_bIsWaitingForFeatureReport = false; - int m_nFeatureReportError = 0; - hid_buffer m_featureReport; + bool m_bIsWaitingForReportResponse = false; + int m_nReportResponseError = 0; + hid_buffer m_reportResponse; public: hid_device_ref next; @@ -839,7 +826,7 @@ extern "C" JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceInputReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); extern "C" -JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceFeatureReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); +JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceReportResponse)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); extern "C" @@ -880,18 +867,13 @@ JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceRegisterCallba { __android_log_print(ANDROID_LOG_ERROR, TAG, "HIDDeviceRegisterCallback: callback class missing openDevice" ); } - g_midHIDDeviceManagerSendOutputReport = env->GetMethodID( g_HIDDeviceManagerCallbackClass, "sendOutputReport", "(I[B)I" ); - if ( !g_midHIDDeviceManagerSendOutputReport ) + g_midHIDDeviceManagerWriteReport = env->GetMethodID( g_HIDDeviceManagerCallbackClass, "writeReport", "(I[BZ)I" ); + if ( !g_midHIDDeviceManagerWriteReport ) { - __android_log_print(ANDROID_LOG_ERROR, TAG, "HIDDeviceRegisterCallback: callback class missing sendOutputReport" ); + __android_log_print(ANDROID_LOG_ERROR, TAG, "HIDDeviceRegisterCallback: callback class missing writeReport" ); } - g_midHIDDeviceManagerSendFeatureReport = env->GetMethodID( g_HIDDeviceManagerCallbackClass, "sendFeatureReport", "(I[B)I" ); - if ( !g_midHIDDeviceManagerSendFeatureReport ) - { - __android_log_print(ANDROID_LOG_ERROR, TAG, "HIDDeviceRegisterCallback: callback class missing sendFeatureReport" ); - } - g_midHIDDeviceManagerGetFeatureReport = env->GetMethodID( g_HIDDeviceManagerCallbackClass, "getFeatureReport", "(I[B)Z" ); - if ( !g_midHIDDeviceManagerGetFeatureReport ) + g_midHIDDeviceManagerReadReport = env->GetMethodID( g_HIDDeviceManagerCallbackClass, "readReport", "(I[BZ)Z" ); + if ( !g_midHIDDeviceManagerReadReport ) { __android_log_print(ANDROID_LOG_ERROR, TAG, "HIDDeviceRegisterCallback: callback class missing getFeatureReport" ); } @@ -1025,16 +1007,16 @@ JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceInputReport)(J } extern "C" -JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceFeatureReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value) +JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceReportResponse)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value) { jbyte *pBuf = env->GetByteArrayElements(value, NULL); jsize nBufSize = env->GetArrayLength(value); - LOGV( "HIDDeviceFeatureReport() id=%d len=%u\n", nDeviceID, nBufSize ); + LOGV( "HIDDeviceReportResponse() id=%d len=%u\n", nDeviceID, nBufSize ); hid_device_ref pDevice = FindDevice( nDeviceID ); if ( pDevice ) { - pDevice->ProcessFeatureReport( reinterpret_cast< const uint8_t* >( pBuf ), nBufSize ); + pDevice->ProcessReportResponse( reinterpret_cast< const uint8_t* >( pBuf ), nBufSize ); } env->ReleaseByteArrayElements(value, pBuf, 0); @@ -1085,7 +1067,6 @@ int hid_init(void) struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned short vendor_id, unsigned short product_id) { struct hid_device_info *root = NULL; - const char *hint = SDL_GetHint(SDL_HINT_HIDAPI_IGNORE_DEVICES); hid_mutex_guard l( &g_DevicesMutex ); for ( hid_device_ref pDevice = g_Devices; pDevice; pDevice = pDevice->next ) @@ -1093,13 +1074,8 @@ struct hid_device_info HID_API_EXPORT * HID_API_CALL hid_enumerate(unsigned shor const hid_device_info *info = pDevice->GetDeviceInfo(); /* See if there are any devices we should skip in enumeration */ - if (hint) { - char vendor_match[16], product_match[16]; - SDL_snprintf(vendor_match, sizeof(vendor_match), "0x%.4x/0x0000", info->vendor_id); - SDL_snprintf(product_match, sizeof(product_match), "0x%.4x/0x%.4x", info->vendor_id, info->product_id); - if (SDL_strcasestr(hint, vendor_match) || SDL_strcasestr(hint, product_match)) { - continue; - } + if (SDL_HIDAPI_ShouldIgnoreDevice(info->vendor_id, info->product_id)) { + continue; } if ( ( vendor_id == 0x0 || info->vendor_id == vendor_id ) && @@ -1129,7 +1105,7 @@ HID_API_EXPORT hid_device * HID_API_CALL hid_open(unsigned short vendor_id, unsi return NULL; } -HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path, int bExclusive) +HID_API_EXPORT hid_device * HID_API_CALL hid_open_path(const char *path) { LOGV( "hid_open_path( %s )", path ); @@ -1170,7 +1146,7 @@ int HID_API_EXPORT HID_API_CALL hid_write(hid_device *device, const unsigned ch hid_device_ref pDevice = FindDevice( device->m_nId ); if ( pDevice ) { - return pDevice->SendOutputReport( data, length ); + return pDevice->WriteReport( data, length, false ); } } return -1; // Controller was disconnected @@ -1248,7 +1224,7 @@ int HID_API_EXPORT HID_API_CALL hid_send_feature_report(hid_device *device, cons hid_device_ref pDevice = FindDevice( device->m_nId ); if ( pDevice ) { - return pDevice->SendFeatureReport( data, length ); + return pDevice->WriteReport( data, length, true ); } } return -1; // Controller was disconnected @@ -1264,7 +1240,23 @@ int HID_API_EXPORT HID_API_CALL hid_get_feature_report(hid_device *device, unsig hid_device_ref pDevice = FindDevice( device->m_nId ); if ( pDevice ) { - return pDevice->GetFeatureReport( data, length ); + return pDevice->ReadReport( data, length, true ); + } + } + return -1; // Controller was disconnected +} + + +// Synchronous operation. Will block until completed. +int HID_API_EXPORT HID_API_CALL hid_get_input_report(hid_device *device, unsigned char *data, size_t length) +{ + if ( device ) + { + LOGV( "hid_get_input_report id=%d length=%u", device->m_nId, length ); + hid_device_ref pDevice = FindDevice( device->m_nId ); + if ( pDevice ) + { + return pDevice->ReadReport( data, length, false ); } } return -1; // Controller was disconnected @@ -1341,6 +1333,25 @@ int HID_API_EXPORT_CALL hid_get_indexed_string(hid_device *device, int string_in return -1; } +struct hid_device_info *hid_get_device_info(hid_device *device) +{ + if ( device ) + { + hid_device_ref pDevice = FindDevice( device->m_nId ); + if ( pDevice ) + { + return pDevice->GetDeviceInfo(); + } + } + return NULL; +} + +int hid_get_report_descriptor(hid_device *device, unsigned char *buf, size_t buf_size) +{ + // Not implemented + return -1; +} + HID_API_EXPORT const wchar_t* HID_API_CALL hid_error(hid_device *device) { return NULL; @@ -1377,7 +1388,7 @@ extern "C" JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceInputReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); extern "C" -JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceFeatureReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); +JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceReportResponse)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value); extern "C" @@ -1423,9 +1434,9 @@ JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceInputReport)(J } extern "C" -JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceFeatureReport)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value) +JNIEXPORT void JNICALL HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceReportResponse)(JNIEnv *env, jobject thiz, int nDeviceID, jbyteArray value) { - LOGV("Stub HIDDeviceFeatureReport() id=%d len=%u\n", nDeviceID, nBufSize); + LOGV("Stub HIDDeviceReportResponse() id=%d len=%u\n", nDeviceID, nBufSize); } #endif /* SDL_HIDAPI_DISABLED */ @@ -1439,5 +1450,5 @@ JNINativeMethod HIDDeviceManager_tab[8] = { { "HIDDeviceOpenResult", "(IZ)V", (void*)HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceOpenResult) }, { "HIDDeviceDisconnected", "(I)V", (void*)HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceDisconnected) }, { "HIDDeviceInputReport", "(I[B)V", (void*)HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceInputReport) }, - { "HIDDeviceFeatureReport", "(I[B)V", (void*)HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceFeatureReport) } + { "HIDDeviceReportResponse", "(I[B)V", (void*)HID_DEVICE_MANAGER_JAVA_INTERFACE(HIDDeviceReportResponse) } }; diff --git a/src/hidapi/android/jni/Android.mk b/src/hidapi/android/jni/Android.mk deleted file mode 100644 index 4462e88bf3ddd..0000000000000 --- a/src/hidapi/android/jni/Android.mk +++ /dev/null @@ -1,16 +0,0 @@ -LOCAL_PATH:= $(call my-dir) - -HIDAPI_ROOT_REL:= ../.. -HIDAPI_ROOT_ABS:= $(LOCAL_PATH)/../.. - -include $(CLEAR_VARS) - -LOCAL_CPPFLAGS += -std=c++11 - -LOCAL_SRC_FILES := \ - $(HIDAPI_ROOT_REL)/android/hid.cpp - -LOCAL_MODULE := libhidapi -LOCAL_LDLIBS := -llog - -include $(BUILD_SHARED_LIBRARY) diff --git a/src/hidapi/android/jni/Application.mk b/src/hidapi/android/jni/Application.mk deleted file mode 100644 index 4fc6ba50642f9..0000000000000 --- a/src/hidapi/android/jni/Application.mk +++ /dev/null @@ -1,2 +0,0 @@ -APP_STL := gnustl_static -APP_ABI := armeabi-v7a diff --git a/src/hidapi/android/project.properties b/src/hidapi/android/project.properties deleted file mode 100644 index 6e18427a424c3..0000000000000 --- a/src/hidapi/android/project.properties +++ /dev/null @@ -1,14 +0,0 @@ -# This file is automatically generated by Android Tools. -# Do not modify this file -- YOUR CHANGES WILL BE ERASED! -# -# This file must be checked in Version Control Systems. -# -# To customize properties used by the Ant build system edit -# "ant.properties", and override values to adapt the script to your -# project structure. -# -# To enable ProGuard to shrink and obfuscate your code, uncomment this (available properties: sdk.dir, user.home): -#proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt - -# Project target. -target=android-21 diff --git a/src/hidapi/configure.ac b/src/hidapi/configure.ac index c6747f906ac48..cc7ceaca00a94 100644 --- a/src/hidapi/configure.ac +++ b/src/hidapi/configure.ac @@ -1,13 +1,9 @@ AC_PREREQ(2.63) -# Version number. This is currently the only place. -m4_define([HIDAPI_MAJOR], 0) -m4_define([HIDAPI_MINOR], 8) -m4_define([HIDAPI_RELEASE], 0) -m4_define([HIDAPI_RC], -rc1) -m4_define([VERSION_STRING], HIDAPI_MAJOR[.]HIDAPI_MINOR[.]HIDAPI_RELEASE[]HIDAPI_RC) +AC_INIT([hidapi],[m4_normalize(m4_builtin([include], VERSION))],[https://github.com/libusb/hidapi/issues]) -AC_INIT([hidapi],[VERSION_STRING],[alan@signal11.us]) +echo "This build script for HIDAPI is deprecated." +echo "Consider using CMake instead." # Library soname version # Follow the following rules (particularly the ones in the second link): @@ -20,7 +16,6 @@ LTLDFLAGS="-version-info ${lt_current}:${lt_revision}:${lt_age}" AC_CONFIG_MACRO_DIR([m4]) AM_INIT_AUTOMAKE([foreign -Wall -Werror]) -AC_CONFIG_MACRO_DIR([m4]) m4_ifdef([AM_PROG_AR], [AM_PROG_AR]) LT_INIT @@ -63,14 +58,14 @@ case $host in # HIDAPI/hidraw libs PKG_CHECK_MODULES([libudev], [libudev], true, [hidapi_lib_error libudev]) - LIBS_HIDRAW_PR+=" $libudev_LIBS" - CFLAGS_HIDRAW+=" $libudev_CFLAGS" + LIBS_HIDRAW_PR="${LIBS_HIDRAW_PR} $libudev_LIBS" + CFLAGS_HIDRAW="${CFLAGS_HIDRAW} $libudev_CFLAGS" # HIDAPI/libusb libs - AC_CHECK_LIB([rt], [clock_gettime], [LIBS_LIBUSB_PRIVATE+=" -lrt"], [hidapi_lib_error librt]) + AC_CHECK_LIB([rt], [clock_gettime], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -lrt"], [hidapi_lib_error librt]) PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0]) - LIBS_LIBUSB_PRIVATE+=" $libusb_LIBS" - CFLAGS_LIBUSB+=" $libusb_CFLAGS" + LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS" + CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS" ;; *-darwin*) AC_MSG_RESULT([ (Mac OS X back-end)]) @@ -79,7 +74,7 @@ case $host in backend="mac" os="darwin" threads="pthreads" - LIBS="${LIBS} -framework IOKit -framework CoreFoundation" + LIBS="${LIBS} -framework IOKit -framework CoreFoundation -framework AppKit" ;; *-freebsd*) AC_MSG_RESULT([ (FreeBSD back-end)]) @@ -92,9 +87,10 @@ case $host in CFLAGS="$CFLAGS -I/usr/local/include" LDFLAGS="$LDFLAGS -L/usr/local/lib" LIBS="${LIBS}" - AC_CHECK_LIB([usb], [libusb_init], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -lusb"], [hidapi_lib_error libusb]) + PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0]) + LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS" + CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS" AC_CHECK_LIB([iconv], [iconv_open], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -liconv"], [hidapi_lib_error libiconv]) - echo libs_priv: $LIBS_LIBUSB_PRIVATE ;; *-kfreebsd*) AC_MSG_RESULT([ (kFreeBSD back-end)]) @@ -104,8 +100,22 @@ case $host in os="kfreebsd" threads="pthreads" - AC_CHECK_LIB([usb], [libusb_init], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -lusb"], [hidapi_lib_error libusb]) - echo libs_priv: $LIBS_LIBUSB_PRIVATE + PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0]) + LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS" + CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS" + ;; +*-*-haiku) + AC_MSG_RESULT([ (Haiku back-end)]) + AC_DEFINE(OS_HAIKU, 1, [Haiku implementation]) + AC_SUBST(OS_HAIKU) + backend="libusb" + os="haiku" + threads="pthreads" + + PKG_CHECK_MODULES([libusb], [libusb-1.0 >= 1.0.9], true, [hidapi_lib_error libusb-1.0]) + LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} $libusb_LIBS" + CFLAGS_LIBUSB="${CFLAGS_LIBUSB} $libusb_CFLAGS" + AC_CHECK_LIB([iconv], [libiconv_open], [LIBS_LIBUSB_PRIVATE="${LIBS_LIBUSB_PRIVATE} -liconv"], [hidapi_lib_error libiconv]) ;; *-mingw*) AC_MSG_RESULT([ (Windows back-end, using MinGW)]) @@ -113,6 +123,15 @@ case $host in os="windows" threads="windows" win_implementation="mingw" + LDFLAGS="${LDFLAGS} -static-libgcc" + ;; +*-msys*) + AC_MSG_RESULT([ (Windows back-end, using MSYS2)]) + backend="windows" + os="windows" + threads="windows" + win_implementation="mingw" + LDFLAGS="${LDFLAGS} -static-libgcc" ;; *-cygwin*) AC_MSG_RESULT([ (Windows back-end, using Cygwin)]) @@ -136,7 +155,7 @@ if test "x$os" = xwindows; then AC_DEFINE(OS_WINDOWS, 1, [Windows implementations]) AC_SUBST(OS_WINDOWS) LDFLAGS="${LDFLAGS} -no-undefined" - LIBS="${LIBS} -lsetupapi" + LIBS="${LIBS}" fi if test "x$threads" = xpthreads; then @@ -175,15 +194,15 @@ mkdir testgui/TestGUI.app/Contents/MacOS/ if test "x$testgui_enabled" != "xno"; then if test "x$os" = xdarwin; then - # On Mac OS, don't use pkg-config. + # On Mac OS, do not use pkg-config. AC_CHECK_PROG([foxconfig], [fox-config], [fox-config], false) if test "x$foxconfig" = "xfalse"; then hidapi_prog_error fox-config "FOX Toolkit" fi - LIBS_TESTGUI+=`$foxconfig --libs` - LIBS_TESTGUI+=" -framework Cocoa -L/usr/X11R6/lib" - CFLAGS_TESTGUI+=`$foxconfig --cflags` - OBJCFLAGS+=" -x objective-c++" + LIBS_TESTGUI="${LIBS_TESTGUI} `$foxconfig --libs`" + LIBS_TESTGUI="${LIBS_TESTGUI} -framework Cocoa -L/usr/X11R6/lib" + CFLAGS_TESTGUI="${CFLAGS_TESTGUI} `$foxconfig --cflags`" + OBJCFLAGS="${OBJCFLAGS} -x objective-c++" elif test "x$os" = xwindows; then # On Windows, just set the paths for Fox toolkit if test "x$win_implementation" = xmingw; then @@ -213,6 +232,7 @@ AM_CONDITIONAL(OS_LINUX, test "x$os" = xlinux) AM_CONDITIONAL(OS_DARWIN, test "x$os" = xdarwin) AM_CONDITIONAL(OS_FREEBSD, test "x$os" = xfreebsd) AM_CONDITIONAL(OS_KFREEBSD, test "x$os" = xkfreebsd) +AM_CONDITIONAL(OS_HAIKU, test "x$os" = xhaiku) AM_CONDITIONAL(OS_WINDOWS, test "x$os" = xwindows) AC_CONFIG_HEADERS([config.h]) diff --git a/src/hidapi/dist/hidapi.podspec b/src/hidapi/dist/hidapi.podspec new file mode 100644 index 0000000000000..74642ef632e24 --- /dev/null +++ b/src/hidapi/dist/hidapi.podspec @@ -0,0 +1,31 @@ +Pod::Spec.new do |spec| + + spec.name = "hidapi" + spec.version = File.read('../VERSION') + spec.summary = "A Simple library for communicating with USB and Bluetooth HID devices on Linux, Mac and Windows." + + spec.description = <<-DESC + HIDAPI is a multi-platform library which allows an application to interface with USB and Bluetooth HID-Class devices on Windows, Linux, FreeBSD, and macOS. HIDAPI can be either built as a shared library (.so, .dll or .dylib) or can be embedded directly into a target application by adding a single source file (per platform) and a single header. + DESC + + spec.homepage = "https://github.com/libusb/hidapi" + + spec.license = { :type=> "GNU GPLv3 or BSD or HIDAPI original", :file => "LICENSE.txt" } + + spec.authors = { "Alan Ott" => "alan@signal11.us", + "Ludovic Rousseau" => "rousseau@debian.org", + "libusb/hidapi Team" => "https://github.com/libusb/hidapi/blob/master/AUTHORS.txt", + } + + spec.platform = :osx + spec.osx.deployment_target = "10.7" + + spec.source = { :git => "https://github.com/libusb/hidapi.git", :tag => "hidapi-#{spec.version}" } + + spec.source_files = "mac/hid.c", "hidapi/hidapi.h", "mac/hidapi_darwin.h" + + spec.public_header_files = "hidapi/hidapi.h", "mac/hidapi_darwin.h" + + spec.frameworks = "IOKit", "CoreFoundation", "AppKit" + +end diff --git a/src/hidapi/documentation/cmake-gui-drop-down.png b/src/hidapi/documentation/cmake-gui-drop-down.png new file mode 100644 index 0000000000000..548abe8c1ea29 Binary files /dev/null and b/src/hidapi/documentation/cmake-gui-drop-down.png differ diff --git a/src/hidapi/documentation/cmake-gui-highlights.png b/src/hidapi/documentation/cmake-gui-highlights.png new file mode 100644 index 0000000000000..228838ff7cf84 Binary files /dev/null and b/src/hidapi/documentation/cmake-gui-highlights.png differ diff --git a/src/hidapi/doxygen/Doxyfile b/src/hidapi/doxygen/Doxyfile index 9d983e9f27edc..4e01360e09ce7 100644 --- a/src/hidapi/doxygen/Doxyfile +++ b/src/hidapi/doxygen/Doxyfile @@ -1,96 +1,151 @@ -# Doxyfile 1.7.1 +# Doxyfile 1.9.6 # This file describes the settings to be used by the documentation system -# doxygen (www.doxygen.org) for a project +# doxygen (www.doxygen.org) for a project. # -# All text after a hash (#) is considered a comment and will be ignored +# All text after a double hash (##) is considered a comment and is placed in +# front of the TAG it is preceding. +# +# All text after a single hash (#) is considered a comment and will be ignored. # The format is: -# TAG = value [value, ...] -# For lists items can also be appended using: -# TAG += value [value, ...] -# Values that contain spaces should be placed between quotes (" ") +# TAG = value [value, ...] +# For lists, items can also be appended using: +# TAG += value [value, ...] +# Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables or CMake type +# replacement variables: +# doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options #--------------------------------------------------------------------------- -# This tag specifies the encoding used for all characters in the config file -# that follow. The default is UTF-8 which is also the encoding used for all +# This tag specifies the encoding used for all characters in the configuration +# file that follow. The default is UTF-8 which is also the encoding used for all # text before the first occurrence of this tag. Doxygen uses libiconv (or the # iconv built into libc) for the transcoding. See -# http://www.gnu.org/software/libiconv for the list of possible encodings. +# https://www.gnu.org/software/libiconv/ for the list of possible encodings. +# The default value is: UTF-8. DOXYFILE_ENCODING = UTF-8 -# The PROJECT_NAME tag is a single word (or a sequence of words surrounded -# by quotes) that should identify the project. +# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by +# double-quotes, unless you are using Doxywizard) that should identify the +# project for which the documentation is generated. This name is used in the +# title of most generated pages and in a few other places. +# The default value is: My Project. PROJECT_NAME = hidapi -# The PROJECT_NUMBER tag can be used to enter a project or revision number. -# This could be handy for archiving the generated documentation or -# if some version control system is used. +# The PROJECT_NUMBER tag can be used to enter a project or revision number. This +# could be handy for archiving the generated documentation or if some version +# control system is used. PROJECT_NUMBER = -# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) -# base path where the generated documentation will be put. -# If a relative path is entered, it will be relative to the location -# where doxygen was started. If left blank the current directory will be used. +# Using the PROJECT_BRIEF tag one can provide an optional one line description +# for a project that appears at the top of each page and should give viewer a +# quick idea about the purpose of the project. Keep the description short. + +PROJECT_BRIEF = + +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. + +PROJECT_LOGO = + +# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path +# into which the generated documentation will be written. If a relative path is +# entered, it will be relative to the location where doxygen was started. If +# left blank the current directory will be used. OUTPUT_DIRECTORY = -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create -# 4096 sub-directories (in 2 levels) under the output directory of each output -# format and will distribute the generated files over these directories. -# Enabling this option can be useful when feeding doxygen a huge amount of -# source files, where putting all generated files in the same directory would -# otherwise cause performance problems for the file system. +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096 +# sub-directories (in 2 levels) under the output directory of each output format +# and will distribute the generated files over these directories. Enabling this +# option can be useful when feeding doxygen a huge amount of source files, where +# putting all generated files in the same directory would otherwise causes +# performance problems for the file system. Adapt CREATE_SUBDIRS_LEVEL to +# control the number of sub-directories. +# The default value is: NO. CREATE_SUBDIRS = NO +# Controls the number of sub-directories that will be created when +# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every +# level increment doubles the number of directories, resulting in 4096 +# directories at level 8 which is the default and also the maximum value. The +# sub-directories are organized in 2 levels, the first level always has a fixed +# number of 16 directories. +# Minimum value: 0, maximum value: 8, default value: 8. +# This tag requires that the tag CREATE_SUBDIRS is set to YES. + +CREATE_SUBDIRS_LEVEL = 8 + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. -# The default language is English, other supported languages are: -# Afrikaans, Arabic, Brazilian, Catalan, Chinese, Chinese-Traditional, -# Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, -# Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English -# messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, -# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, -# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. +# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Bulgarian, +# Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch, English +# (United States), Esperanto, Farsi (Persian), Finnish, French, German, Greek, +# Hindi, Hungarian, Indonesian, Italian, Japanese, Japanese-en (Japanese with +# English messages), Korean, Korean-en (Korean with English messages), Latvian, +# Lithuanian, Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, +# Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, +# Swedish, Turkish, Ukrainian and Vietnamese. +# The default value is: English. OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will -# include brief member descriptions after the members that are listed in -# the file and class documentation (similar to JavaDoc). -# Set to NO to disable this. +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member +# descriptions after the members that are listed in the file and class +# documentation (similar to Javadoc). Set to NO to disable this. +# The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend -# the brief description of a member or function before the detailed description. -# Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief +# description of a member or function before the detailed description +# +# Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. +# The default value is: YES. REPEAT_BRIEF = YES -# This tag implements a quasi-intelligent brief description abbreviator -# that is used to form the text in various listings. Each string -# in this list, if found as the leading text of the brief description, will be -# stripped from the text and the result after processing the whole list, is -# used as the annotated text. Otherwise, the brief description is used as-is. -# If left blank, the following values are used ("$name" is automatically -# replaced with the name of the entity): "The $name class" "The $name widget" -# "The $name file" "is" "provides" "specifies" "contains" -# "represents" "a" "an" "the" +# This tag implements a quasi-intelligent brief description abbreviator that is +# used to form the text in various listings. Each string in this list, if found +# as the leading text of the brief description, will be stripped from the text +# and the result, after processing the whole list, is used as the annotated +# text. Otherwise, the brief description is used as-is. If left blank, the +# following values are used ($name is automatically replaced with the name of +# the entity):The $name class, The $name widget, The $name file, is, provides, +# specifies, contains, represents, a, an and the. ABBREVIATE_BRIEF = # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then -# Doxygen will generate a detailed section even if there is only a brief +# doxygen will generate a detailed section even if there is only a brief # description. +# The default value is: NO. ALWAYS_DETAILED_SEC = NO @@ -98,531 +153,831 @@ ALWAYS_DETAILED_SEC = NO # inherited members of a class in the documentation of that class as if those # members were ordinary class members. Constructors, destructors and assignment # operators of the base classes will not be shown. +# The default value is: NO. INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full -# path before files name in the file list and in the header files. If set -# to NO the shortest path that makes the file name unique will be used. +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path +# before files name in the file list and in the header files. If set to NO the +# shortest path that makes the file name unique will be used +# The default value is: YES. FULL_PATH_NAMES = YES -# If the FULL_PATH_NAMES tag is set to YES then the STRIP_FROM_PATH tag -# can be used to strip a user-defined part of the path. Stripping is -# only done if one of the specified strings matches the left-hand part of -# the path. The tag can be used to show relative paths in the file list. -# If left blank the directory from which doxygen is run is used as the -# path to strip. +# The STRIP_FROM_PATH tag can be used to strip a user-defined part of the path. +# Stripping is only done if one of the specified strings matches the left-hand +# part of the path. The tag can be used to show relative paths in the file list. +# If left blank the directory from which doxygen is run is used as the path to +# strip. +# +# Note that you can specify absolute paths here, but also relative paths, which +# will be relative from the directory where doxygen is started. +# This tag requires that the tag FULL_PATH_NAMES is set to YES. -STRIP_FROM_PATH = +STRIP_FROM_PATH = ../ -# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of -# the path mentioned in the documentation of a class, which tells -# the reader which header file to include in order to use a class. -# If left blank only the name of the header file containing the class -# definition is used. Otherwise one should specify the include paths that -# are normally passed to the compiler using the -I flag. +# The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the +# path mentioned in the documentation of a class, which tells the reader which +# header file to include in order to use a class. If left blank only the name of +# the header file containing the class definition is used. Otherwise one should +# specify the list of include paths that are normally passed to the compiler +# using the -I flag. STRIP_FROM_INC_PATH = -# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter -# (but less readable) file names. This can be useful is your file systems -# doesn't support long names like on DOS, Mac, or CD-ROM. +# If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but +# less readable) file names. This can be useful is your file systems doesn't +# support long names like on DOS, Mac, or CD-ROM. +# The default value is: NO. SHORT_NAMES = NO -# If the JAVADOC_AUTOBRIEF tag is set to YES then Doxygen -# will interpret the first line (until the first dot) of a JavaDoc-style -# comment as the brief description. If set to NO, the JavaDoc -# comments will behave just like regular Qt-style comments -# (thus requiring an explicit @brief command for a brief description.) +# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the +# first line (until the first dot) of a Javadoc-style comment as the brief +# description. If set to NO, the Javadoc-style will behave just like regular Qt- +# style comments (thus requiring an explicit @brief command for a brief +# description.) +# The default value is: NO. JAVADOC_AUTOBRIEF = NO -# If the QT_AUTOBRIEF tag is set to YES then Doxygen will -# interpret the first line (until the first dot) of a Qt-style -# comment as the brief description. If set to NO, the comments -# will behave just like regular Qt-style comments (thus requiring -# an explicit \brief command for a brief description.) +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + +# If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first +# line (until the first dot) of a Qt-style comment as the brief description. If +# set to NO, the Qt-style will behave just like regular Qt-style comments (thus +# requiring an explicit \brief command for a brief description.) +# The default value is: NO. QT_AUTOBRIEF = NO -# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen -# treat a multi-line C++ special comment block (i.e. a block of //! or /// -# comments) as a brief description. This used to be the default behaviour. -# The new default is to treat a multi-line C++ comment block as a detailed -# description. Set this tag to YES if you prefer the old behaviour instead. +# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a +# multi-line C++ special comment block (i.e. a block of //! or /// comments) as +# a brief description. This used to be the default behavior. The new default is +# to treat a multi-line C++ comment block as a detailed description. Set this +# tag to YES if you prefer the old behavior instead. +# +# Note that setting this tag to YES also means that rational rose comments are +# not recognized any more. +# The default value is: NO. MULTILINE_CPP_IS_BRIEF = NO -# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented -# member inherits the documentation from any documented member that it -# re-implements. +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + +# If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the +# documentation from any documented member that it re-implements. +# The default value is: YES. INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce -# a new page for each member. If set to NO, the documentation of a member will -# be part of the file/class/namespace that contains it. +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. +# The default value is: NO. SEPARATE_MEMBER_PAGES = NO -# The TAB_SIZE tag can be used to set the number of spaces in a tab. -# Doxygen uses this value to replace tabs by spaces in code fragments. +# The TAB_SIZE tag can be used to set the number of spaces in a tab. Doxygen +# uses this value to replace tabs by spaces in code fragments. +# Minimum value: 1, maximum value: 16, default value: 4. TAB_SIZE = 8 -# This tag can be used to specify a number of aliases that acts -# as commands in the documentation. An alias has the form "name=value". -# For example adding "sideeffect=\par Side Effects:\n" will allow you to -# put the command \sideeffect (or @sideeffect) in the documentation, which -# will result in a user-defined paragraph with heading "Side Effects:". -# You can put \n's in the value part of an alias to insert newlines. +# This tag can be used to specify a number of aliases that act as commands in +# the documentation. An alias has the form: +# name=value +# For example adding +# "sideeffect=@par Side Effects:^^" +# will allow you to put the command \sideeffect (or @sideeffect) in the +# documentation, which will result in a user-defined paragraph with heading +# "Side Effects:". Note that you cannot put \n's in the value part of an alias +# to insert newlines (in the resulting output). You can put ^^ in the value part +# of an alias to insert a newline as if a physical newline was in the original +# file. When you need a literal { or } or , in the value part of an alias you +# have to escape them by means of a backslash (\), this can lead to conflicts +# with the commands \{ and \} for these it is advised to use the version @{ and +# @} or use a double escape (\\{ and \\}) ALIASES = -# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C -# sources only. Doxygen will then generate output that is more tailored for C. -# For instance, some of the names that are used will be different. The list -# of all members will be omitted, etc. +# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources +# only. Doxygen will then generate output that is more tailored for C. For +# instance, some of the names that are used will be different. The list of all +# members will be omitted, etc. +# The default value is: NO. OPTIMIZE_OUTPUT_FOR_C = YES -# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java -# sources only. Doxygen will then generate output that is more tailored for -# Java. For instance, namespaces will be presented as packages, qualified -# scopes will look different, etc. +# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or +# Python sources only. Doxygen will then generate output that is more tailored +# for that language. For instance, namespaces will be presented as packages, +# qualified scopes will look different, etc. +# The default value is: NO. OPTIMIZE_OUTPUT_JAVA = NO # Set the OPTIMIZE_FOR_FORTRAN tag to YES if your project consists of Fortran -# sources only. Doxygen will then generate output that is more tailored for -# Fortran. +# sources. Doxygen will then generate output that is tailored for Fortran. +# The default value is: NO. OPTIMIZE_FOR_FORTRAN = NO # Set the OPTIMIZE_OUTPUT_VHDL tag to YES if your project consists of VHDL -# sources. Doxygen will then generate output that is tailored for -# VHDL. +# sources. Doxygen will then generate output that is tailored for VHDL. +# The default value is: NO. OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + # Doxygen selects the parser to use depending on the extension of the files it -# parses. With this tag you can assign which parser to use for a given extension. -# Doxygen has a built-in mapping, but you can override or extend it using this -# tag. The format is ext=language, where ext is a file extension, and language -# is one of the parsers supported by doxygen: IDL, Java, Javascript, CSharp, C, -# C++, D, PHP, Objective-C, Python, Fortran, VHDL, C, C++. For instance to make -# doxygen treat .inc files as Fortran files (default is PHP), and .f files as C -# (default is Fortran), use: inc=Fortran f=C. Note that for custom extensions -# you also need to set FILE_PATTERNS otherwise the files are not read by doxygen. +# parses. With this tag you can assign which parser to use for a given +# extension. Doxygen has a built-in mapping, but you can override or extend it +# using this tag. The format is ext=language, where ext is a file extension, and +# language is one of the parsers supported by doxygen: IDL, Java, JavaScript, +# Csharp (C#), C, C++, Lex, D, PHP, md (Markdown), Objective-C, Python, Slice, +# VHDL, Fortran (fixed format Fortran: FortranFixed, free formatted Fortran: +# FortranFree, unknown formatted Fortran: Fortran. In the later case the parser +# tries to guess whether the code is fixed or free formatted code, this is the +# default for Fortran type files). For instance to make doxygen treat .inc files +# as Fortran files (default is PHP), and .f files as C (default is Fortran), +# use: inc=Fortran f=C. +# +# Note: For files without extension you can use no_extension as a placeholder. +# +# Note that for custom extensions you also need to set FILE_PATTERNS otherwise +# the files are not read by doxygen. When specifying no_extension you should add +# * to the FILE_PATTERNS. +# +# Note see also the list of default file extension mappings. EXTENSION_MAPPING = +# If the MARKDOWN_SUPPORT tag is enabled then doxygen pre-processes all comments +# according to the Markdown format, which allows for more readable +# documentation. See https://daringfireball.net/projects/markdown/ for details. +# The output of markdown processing is further processed by doxygen, so you can +# mix doxygen, HTML, and XML commands with Markdown formatting. Disable only in +# case of backward compatibilities issues. +# The default value is: YES. + +MARKDOWN_SUPPORT = NO + +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + +# When enabled doxygen tries to link words that correspond to documented +# classes, or namespaces to their corresponding documentation. Such a link can +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. +# The default value is: YES. + +AUTOLINK_SUPPORT = YES + # If you use STL classes (i.e. std::string, std::vector, etc.) but do not want -# to include (a tag file for) the STL sources as input, then you should -# set this tag to YES in order to let doxygen match functions declarations and -# definitions whose arguments contain STL classes (e.g. func(std::string); v.s. -# func(std::string) {}). This also make the inheritance and collaboration +# to include (a tag file for) the STL sources as input, then you should set this +# tag to YES in order to let doxygen match functions declarations and +# definitions whose arguments contain STL classes (e.g. func(std::string); +# versus func(std::string) {}). This also make the inheritance and collaboration # diagrams that involve STL classes more complete and accurate. +# The default value is: NO. BUILTIN_STL_SUPPORT = NO # If you use Microsoft's C++/CLI language, you should set this option to YES to # enable parsing support. +# The default value is: NO. CPP_CLI_SUPPORT = NO -# Set the SIP_SUPPORT tag to YES if your project consists of sip sources only. -# Doxygen will parse them like normal C++ but will assume all classes use public -# instead of private inheritance when no explicit protection keyword is present. +# Set the SIP_SUPPORT tag to YES if your project consists of sip (see: +# https://www.riverbankcomputing.com/software/sip/intro) sources only. Doxygen +# will parse them like normal C++ but will assume all classes use public instead +# of private inheritance when no explicit protection keyword is present. +# The default value is: NO. SIP_SUPPORT = NO -# For Microsoft's IDL there are propget and propput attributes to indicate getter -# and setter methods for a property. Setting this option to YES (the default) -# will make doxygen to replace the get and set methods by a property in the -# documentation. This will only work if the methods are indeed getting or -# setting a simple type. If this is not the case, or you want to show the -# methods anyway, you should set this option to NO. +# For Microsoft's IDL there are propget and propput attributes to indicate +# getter and setter methods for a property. Setting this option to YES will make +# doxygen to replace the get and set methods by a property in the documentation. +# This will only work if the methods are indeed getting or setting a simple +# type. If this is not the case, or you want to show the methods anyway, you +# should set this option to NO. +# The default value is: YES. IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first +# tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. +# The default value is: NO. DISTRIBUTE_GROUP_DOC = NO -# Set the SUBGROUPING tag to YES (the default) to allow class member groups of -# the same type (for instance a group of public functions) to be put as a -# subgroup of that type (e.g. under the Public Functions section). Set it to -# NO to prevent subgrouping. Alternatively, this can be done per class using -# the \nosubgrouping command. +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + +# Set the SUBGROUPING tag to YES to allow class member groups of the same type +# (for instance a group of public functions) to be put as a subgroup of that +# type (e.g. under the Public Functions section). Set it to NO to prevent +# subgrouping. Alternatively, this can be done per class using the +# \nosubgrouping command. +# The default value is: YES. SUBGROUPING = YES -# When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum -# is documented as struct, union, or enum with the name of the typedef. So +# When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions +# are shown inside the group in which they are included (e.g. using \ingroup) +# instead of on a separate page (for HTML and Man pages) or section (for LaTeX +# and RTF). +# +# Note that this feature does not work in combination with +# SEPARATE_MEMBER_PAGES. +# The default value is: NO. + +INLINE_GROUPED_CLASSES = NO + +# When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions +# with only public data fields or simple typedef fields will be shown inline in +# the documentation of the scope in which they are defined (i.e. file, +# namespace, or group documentation), provided this scope is documented. If set +# to NO, structs, classes, and unions are shown on a separate page (for HTML and +# Man pages) or section (for LaTeX and RTF). +# The default value is: NO. + +INLINE_SIMPLE_STRUCTS = NO + +# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or +# enum is documented as struct, union, or enum with the name of the typedef. So # typedef struct TypeS {} TypeT, will appear in the documentation as a struct # with name TypeT. When disabled the typedef will appear as a member of a file, -# namespace, or class. And the struct will be named TypeS. This can typically -# be useful for C code in case the coding convention dictates that all compound +# namespace, or class. And the struct will be named TypeS. This can typically be +# useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. +# The default value is: NO. TYPEDEF_HIDES_STRUCT = NO -# The SYMBOL_CACHE_SIZE determines the size of the internal cache use to -# determine which symbols to keep in memory and which to flush to disk. -# When the cache is full, less often used symbols will be written to disk. -# For small to medium size projects (<1000 input files) the default value is -# probably good enough. For larger projects a too small cache size can cause -# doxygen to be busy swapping symbols to and from disk most of the time -# causing a significant performance penality. -# If the system has enough physical memory increasing the cache will improve the -# performance by keeping more symbols in memory. Note that the value works on -# a logarithmic scale so increasing the size by one will rougly double the -# memory usage. The cache size is given by this formula: -# 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, -# corresponding to a cache size of 2^16 = 65536 symbols - -SYMBOL_CACHE_SIZE = 0 +# The size of the symbol lookup cache can be set using LOOKUP_CACHE_SIZE. This +# cache is used to resolve symbols given their name and scope. Since this can be +# an expensive process and often the same symbol appears multiple times in the +# code, doxygen keeps a cache of pre-resolved symbols. If the cache is too small +# doxygen will become slower. If the cache is too large, memory is wasted. The +# cache size is given by this formula: 2^(16+LOOKUP_CACHE_SIZE). The valid range +# is 0..9, the default is 0, corresponding to a cache size of 2^16=65536 +# symbols. At the end of a run doxygen will report the cache usage and suggest +# the optimal cache size from a speed point of view. +# Minimum value: 0, maximum value: 9, default value: 0. + +LOOKUP_CACHE_SIZE = 0 + +# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which effectively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in -# documentation are documented, even if no documentation was available. -# Private class members and static file members will be hidden unless -# the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in +# documentation are documented, even if no documentation was available. Private +# class members and static file members will be hidden unless the +# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. +# Note: This will also disable the warnings about undocumented members that are +# normally produced when WARNINGS is set to YES. +# The default value is: NO. EXTRACT_ALL = NO -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class -# will be included in the documentation. +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will +# be included in the documentation. +# The default value is: NO. EXTRACT_PRIVATE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file -# will be included in the documentation. +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal +# scope will be included in the documentation. +# The default value is: NO. + +EXTRACT_PACKAGE = NO + +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be +# included in the documentation. +# The default value is: NO. EXTRACT_STATIC = NO -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) -# defined locally in source files will be included in the documentation. -# If set to NO only classes defined in header files are included. +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, +# only classes defined in header files are included. Does not have any effect +# for Java sources. +# The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local -# methods, which are defined in the implementation section but not in -# the interface are included in the documentation. -# If set to NO (the default) only methods in the interface are included. +# This flag is only useful for Objective-C code. If set to YES, local methods, +# which are defined in the implementation section but not in the interface are +# included in the documentation. If set to NO, only methods in the interface are +# included. +# The default value is: NO. EXTRACT_LOCAL_METHODS = NO # If this flag is set to YES, the members of anonymous namespaces will be # extracted and appear in the documentation as a namespace called -# 'anonymous_namespace{file}', where file will be replaced with the base -# name of the file that contains the anonymous namespace. By default -# anonymous namespace are hidden. +# 'anonymous_namespace{file}', where file will be replaced with the base name of +# the file that contains the anonymous namespace. By default anonymous namespace +# are hidden. +# The default value is: NO. EXTRACT_ANON_NSPACES = NO -# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all -# undocumented members of documented classes, files or namespaces. -# If set to NO (the default) these members will be included in the -# various overviews, but no documentation section is generated. -# This option has no effect if EXTRACT_ALL is enabled. +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + +# If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all +# undocumented members inside documented classes or files. If set to NO these +# members will be included in the various overviews, but no documentation +# section is generated. This option has no effect if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_MEMBERS = NO -# If the HIDE_UNDOC_CLASSES tag is set to YES, Doxygen will hide all -# undocumented classes that are normally visible in the class hierarchy. -# If set to NO (the default) these classes will be included in the various -# overviews. This option has no effect if EXTRACT_ALL is enabled. +# If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all +# undocumented classes that are normally visible in the class hierarchy. If set +# to NO, these classes will be included in the various overviews. This option +# will also hide undocumented C++ concepts if enabled. This option has no effect +# if EXTRACT_ALL is enabled. +# The default value is: NO. HIDE_UNDOC_CLASSES = NO -# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all -# friend (class|struct|union) declarations. -# If set to NO (the default) these declarations will be included in the +# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend +# declarations. If set to NO, these declarations will be included in the # documentation. +# The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO -# If the HIDE_IN_BODY_DOCS tag is set to YES, Doxygen will hide any -# documentation blocks found inside the body of a function. -# If set to NO (the default) these blocks will be appended to the -# function's detailed documentation block. +# If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any +# documentation blocks found inside the body of a function. If set to NO, these +# blocks will be appended to the function's detailed documentation block. +# The default value is: NO. HIDE_IN_BODY_DOCS = NO -# The INTERNAL_DOCS tag determines if documentation -# that is typed after a \internal command is included. If the tag is set -# to NO (the default) then the documentation will be excluded. -# Set it to YES to include the internal documentation. +# The INTERNAL_DOCS tag determines if documentation that is typed after a +# \internal command is included. If the tag is set to NO then the documentation +# will be excluded. Set it to YES to include the internal documentation. +# The default value is: NO. INTERNAL_DOCS = NO -# If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate -# file names in lower-case letters. If set to YES upper-case letters are also -# allowed. This is useful if you have classes or files whose names only differ -# in case and if your file system supports case sensitive file names. Windows -# and Mac users are advised to set this option to NO. +# With the correct setting of option CASE_SENSE_NAMES doxygen will better be +# able to match the capabilities of the underlying filesystem. In case the +# filesystem is case sensitive (i.e. it supports files in the same directory +# whose names only differ in casing), the option must be set to YES to properly +# deal with such files in case they appear in the input. For filesystems that +# are not case sensitive the option should be set to NO to properly deal with +# output files written for symbols that only differ in casing, such as for two +# classes, one named CLASS and the other named Class, and to also support +# references to files without having to specify the exact matching casing. On +# Windows (including Cygwin) and MacOS, users should typically set this option +# to NO, whereas on Linux or other Unix flavors it should typically be set to +# YES. +# Possible values are: SYSTEM, NO and YES. +# The default value is: SYSTEM. CASE_SENSE_NAMES = YES -# If the HIDE_SCOPE_NAMES tag is set to NO (the default) then Doxygen -# will show members with their full class and namespace scopes in the -# documentation. If set to YES the scope will be hidden. +# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with +# their full class and namespace scopes in the documentation. If set to YES, the +# scope will be hidden. +# The default value is: NO. HIDE_SCOPE_NAMES = NO -# If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen -# will put a list of the files that are included by a file in the documentation -# of that file. +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +SHOW_HEADERFILE = YES + +# If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of +# the files that are included by a file in the documentation of that file. +# The default value is: YES. SHOW_INCLUDE_FILES = YES -# If the FORCE_LOCAL_INCLUDES tag is set to YES then Doxygen -# will list include files with double quotes in the documentation -# rather than with sharp brackets. +# If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each +# grouped member an include statement to the documentation, telling the reader +# which file to include in order to use the member. +# The default value is: NO. + +SHOW_GROUPED_MEMB_INC = NO + +# If the FORCE_LOCAL_INCLUDES tag is set to YES then doxygen will list include +# files with double quotes in the documentation rather than with sharp brackets. +# The default value is: NO. FORCE_LOCAL_INCLUDES = NO -# If the INLINE_INFO tag is set to YES (the default) then a tag [inline] -# is inserted in the documentation for inline members. +# If the INLINE_INFO tag is set to YES then a tag [inline] is inserted in the +# documentation for inline members. +# The default value is: YES. INLINE_INFO = YES -# If the SORT_MEMBER_DOCS tag is set to YES (the default) then doxygen -# will sort the (detailed) documentation of file and class members -# alphabetically by member name. If set to NO the members will appear in -# declaration order. +# If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the +# (detailed) documentation of file and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. +# The default value is: YES. SORT_MEMBER_DOCS = YES -# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the -# brief documentation of file, namespace and class members alphabetically -# by member name. If set to NO (the default) the members will appear in -# declaration order. +# If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief +# descriptions of file, namespace and class members alphabetically by member +# name. If set to NO, the members will appear in declaration order. Note that +# this will also influence the order of the classes in the class list. +# The default value is: NO. SORT_BRIEF_DOCS = NO -# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen -# will sort the (brief and detailed) documentation of class members so that -# constructors and destructors are listed first. If set to NO (the default) -# the constructors will appear in the respective orders defined by -# SORT_MEMBER_DOCS and SORT_BRIEF_DOCS. -# This tag will be ignored for brief docs if SORT_BRIEF_DOCS is set to NO -# and ignored for detailed docs if SORT_MEMBER_DOCS is set to NO. +# If the SORT_MEMBERS_CTORS_1ST tag is set to YES then doxygen will sort the +# (brief and detailed) documentation of class members so that constructors and +# destructors are listed first. If set to NO the constructors will appear in the +# respective orders defined by SORT_BRIEF_DOCS and SORT_MEMBER_DOCS. +# Note: If SORT_BRIEF_DOCS is set to NO this option is ignored for sorting brief +# member documentation. +# Note: If SORT_MEMBER_DOCS is set to NO this option is ignored for sorting +# detailed member documentation. +# The default value is: NO. SORT_MEMBERS_CTORS_1ST = NO -# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the -# hierarchy of group names into alphabetical order. If set to NO (the default) -# the group names will appear in their defined order. +# If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy +# of group names into alphabetical order. If set to NO the group names will +# appear in their defined order. +# The default value is: NO. SORT_GROUP_NAMES = NO -# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be -# sorted by fully-qualified names, including namespaces. If set to -# NO (the default), the class list will be sorted only by class name, -# not including the namespace part. +# If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by +# fully-qualified names, including namespaces. If set to NO, the class list will +# be sorted only by class name, not including the namespace part. # Note: This option is not very useful if HIDE_SCOPE_NAMES is set to YES. -# Note: This option applies only to the class list, not to the -# alphabetical list. +# Note: This option applies only to the class list, not to the alphabetical +# list. +# The default value is: NO. SORT_BY_SCOPE_NAME = NO -# The GENERATE_TODOLIST tag can be used to enable (YES) or -# disable (NO) the todo list. This list is created by putting \todo -# commands in the documentation. +# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to do proper +# type resolution of all parameters of a function it will reject a match between +# the prototype and the implementation of a member function even if there is +# only one candidate or it is obvious which candidate to choose by doing a +# simple string match. By disabling STRICT_PROTO_MATCHING doxygen will still +# accept a match between prototype and implementation in such cases. +# The default value is: NO. + +STRICT_PROTO_MATCHING = NO + +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. +# The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable (YES) or -# disable (NO) the test list. This list is created by putting \test -# commands in the documentation. +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. +# The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable (YES) or -# disable (NO) the bug list. This list is created by putting \bug -# commands in the documentation. +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug +# list. This list is created by putting \bug commands in the documentation. +# The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or -# disable (NO) the deprecated list. This list is created by putting -# \deprecated commands in the documentation. +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) +# the deprecated list. This list is created by putting \deprecated commands in +# the documentation. +# The default value is: YES. GENERATE_DEPRECATEDLIST= YES -# The ENABLED_SECTIONS tag can be used to enable conditional -# documentation sections, marked by \if sectionname ... \endif. +# The ENABLED_SECTIONS tag can be used to enable conditional documentation +# sections, marked by \if ... \endif and \cond +# ... \endcond blocks. ENABLED_SECTIONS = -# The MAX_INITIALIZER_LINES tag determines the maximum number of lines -# the initial value of a variable or define consists of for it to appear in -# the documentation. If the initializer consists of more lines than specified -# here it will be hidden. Use a value of 0 to hide initializers completely. -# The appearance of the initializer of individual variables and defines in the -# documentation can be controlled using \showinitializer or \hideinitializer -# command in the documentation regardless of this setting. +# The MAX_INITIALIZER_LINES tag determines the maximum number of lines that the +# initial value of a variable or macro / define can have for it to appear in the +# documentation. If the initializer consists of more lines than specified here +# it will be hidden. Use a value of 0 to hide initializers completely. The +# appearance of the value of individual variables and macros / defines can be +# controlled using \showinitializer or \hideinitializer command in the +# documentation regardless of this setting. +# Minimum value: 0, maximum value: 10000, default value: 30. MAX_INITIALIZER_LINES = 30 -# Set the SHOW_USED_FILES tag to NO to disable the list of files generated -# at the bottom of the documentation of classes and structs. If set to YES the +# Set the SHOW_USED_FILES tag to NO to disable the list of files generated at +# the bottom of the documentation of classes and structs. If set to YES, the # list will mention the files that were used to generate the documentation. +# The default value is: YES. SHOW_USED_FILES = YES -# If the sources in your project are distributed over multiple directories -# then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy -# in the documentation. The default is NO. - -SHOW_DIRECTORIES = NO - -# Set the SHOW_FILES tag to NO to disable the generation of the Files page. -# This will remove the Files entry from the Quick Index and from the -# Folder Tree View (if specified). The default is YES. +# Set the SHOW_FILES tag to NO to disable the generation of the Files page. This +# will remove the Files entry from the Quick Index and from the Folder Tree View +# (if specified). +# The default value is: YES. SHOW_FILES = YES -# Set the SHOW_NAMESPACES tag to NO to disable the generation of the -# Namespaces page. -# This will remove the Namespaces entry from the Quick Index -# and from the Folder Tree View (if specified). The default is YES. +# Set the SHOW_NAMESPACES tag to NO to disable the generation of the Namespaces +# page. This will remove the Namespaces entry from the Quick Index and from the +# Folder Tree View (if specified). +# The default value is: YES. SHOW_NAMESPACES = YES # The FILE_VERSION_FILTER tag can be used to specify a program or script that # doxygen should invoke to get the current version for each file (typically from # the version control system). Doxygen will invoke the program by executing (via -# popen()) the command , where is the value of -# the FILE_VERSION_FILTER tag, and is the name of an input file -# provided by doxygen. Whatever the program writes to standard output -# is used as the file version. See the manual for examples. +# popen()) the command command input-file, where command is the value of the +# FILE_VERSION_FILTER tag, and input-file is the name of an input file provided +# by doxygen. Whatever the program writes to standard output is used as the file +# version. For an example see the documentation. FILE_VERSION_FILTER = # The LAYOUT_FILE tag can be used to specify a layout file which will be parsed # by doxygen. The layout file controls the global structure of the generated -# output files in an output format independent way. The create the layout file -# that represents doxygen's defaults, run doxygen with the -l option. -# You can optionally specify a file name after the option, if omitted -# DoxygenLayout.xml will be used as the name of the layout file. +# output files in an output format independent way. To create the layout file +# that represents doxygen's defaults, run doxygen with the -l option. You can +# optionally specify a file name after the option, if omitted DoxygenLayout.xml +# will be used as the name of the layout file. See also section "Changing the +# layout of pages" for information. +# +# Note that if you run doxygen from a directory containing a file called +# DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE +# tag is left empty. LAYOUT_FILE = +# The CITE_BIB_FILES tag can be used to specify one or more bib files containing +# the reference definitions. This must be a list of .bib files. The .bib +# extension is automatically appended if omitted. This requires the bibtex tool +# to be installed. See also https://en.wikipedia.org/wiki/BibTeX for more info. +# For LaTeX the style of the bibliography can be controlled using +# LATEX_BIB_STYLE. To use this feature you need bibtex and perl available in the +# search path. See also \cite for info how to create references. + +CITE_BIB_FILES = + #--------------------------------------------------------------------------- -# configuration options related to warning and progress messages +# Configuration options related to warning and progress messages #--------------------------------------------------------------------------- -# The QUIET tag can be used to turn on/off the messages that are generated -# by doxygen. Possible values are YES and NO. If left blank NO is used. +# The QUIET tag can be used to turn on/off the messages that are generated to +# standard output by doxygen. If QUIET is set to YES this implies that the +# messages are off. +# The default value is: NO. QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated by doxygen. Possible values are YES and NO. If left blank -# NO is used. +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES +# this implies that the warnings are on. +# +# Tip: Turn warnings on while writing the documentation. +# The default value is: YES. WARNINGS = YES -# If WARN_IF_UNDOCUMENTED is set to YES, then doxygen will generate warnings -# for undocumented members. If EXTRACT_ALL is set to YES then this flag will -# automatically be disabled. +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate +# warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: YES. WARN_IF_UNDOCUMENTED = YES -# If WARN_IF_DOC_ERROR is set to YES, doxygen will generate warnings for -# potential errors in the documentation, such as not documenting some -# parameters in a documented function, or documenting parameters that -# don't exist or using markup commands wrongly. +# If the WARN_IF_DOC_ERROR tag is set to YES, doxygen will generate warnings for +# potential errors in the documentation, such as documenting some parameters in +# a documented function twice, or documenting parameters that don't exist or +# using markup commands wrongly. +# The default value is: YES. WARN_IF_DOC_ERROR = YES -# This WARN_NO_PARAMDOC option can be abled to get warnings for -# functions that are documented, but have no documentation for their parameters -# or return value. If set to NO (the default) doxygen will only warn about -# wrong or incomplete parameter documentation, but not about the absence of -# documentation. +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +WARN_IF_INCOMPLETE_DOC = YES + +# This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that +# are documented, but have no documentation for their parameters or return +# value. If set to NO, doxygen will only warn about wrong parameter +# documentation, but not about the absence of documentation. If EXTRACT_ALL is +# set to YES then this flag will automatically be disabled. See also +# WARN_IF_INCOMPLETE_DOC +# The default value is: NO. WARN_NO_PARAMDOC = NO -# The WARN_FORMAT tag determines the format of the warning messages that -# doxygen can produce. The string should contain the $file, $line, and $text -# tags, which will be replaced by the file and line number from which the -# warning originated and the warning text. Optionally the format may contain -# $version, which will be replaced by the version of the file (if it could -# be obtained via FILE_VERSION_FILTER) +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about +# undocumented enumeration values. If set to NO, doxygen will accept +# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: NO. + +WARN_IF_UNDOC_ENUM_VAL = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# The default value is: NO. + +WARN_AS_ERROR = NO + +# The WARN_FORMAT tag determines the format of the warning messages that doxygen +# can produce. The string should contain the $file, $line, and $text tags, which +# will be replaced by the file and line number from which the warning originated +# and the warning text. Optionally the format may contain $version, which will +# be replaced by the version of the file (if it could be obtained via +# FILE_VERSION_FILTER) +# See also: WARN_LINE_FORMAT +# The default value is: $file:$line: $text. WARN_FORMAT = "$file:$line: $text" -# The WARN_LOGFILE tag can be used to specify a file to which warning -# and error messages should be written. If left blank the output is written -# to stderr. +# In the $text part of the WARN_FORMAT command it is possible that a reference +# to a more specific place is given. To make it easier to jump to this place +# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# Example: +# WARN_LINE_FORMAT = "'vi $file +$line'" +# See also: WARN_FORMAT +# The default value is: at line $line of file $file. + +WARN_LINE_FORMAT = "at line $line of file $file" + +# The WARN_LOGFILE tag can be used to specify a file to which warning and error +# messages should be written. If left blank the output is written to standard +# error (stderr). In case the file specified cannot be opened for writing the +# warning and error messages are written to standard error. When as file - is +# specified the warning and error messages are written to standard output +# (stdout). WARN_LOGFILE = #--------------------------------------------------------------------------- -# configuration options related to the input files +# Configuration options related to the input files #--------------------------------------------------------------------------- -# The INPUT tag can be used to specify the files and/or directories that contain -# documented source files. You may enter file names like "myfile.cpp" or -# directories like "/usr/src/myproject". Separate the files or directories -# with spaces. +# The INPUT tag is used to specify the files and/or directories that contain +# documented source files. You may enter file names like myfile.cpp or +# directories like /usr/src/myproject. Separate the files or directories with +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING +# Note: If this tag is empty the current directory is searched. -INPUT = ../hidapi +INPUT = ../hidapi \ + ./main_page.md # This tag can be used to specify the character encoding of the source files -# that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is -# also the default input encoding. Doxygen uses libiconv (or the iconv built -# into libc) for the transcoding. See http://www.gnu.org/software/libiconv for -# the list of possible encodings. +# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses +# libiconv (or the iconv built into libc) for the transcoding. See the libiconv +# documentation (see: +# https://www.gnu.org/software/libiconv/) for the list of possible encodings. +# See also: INPUT_FILE_ENCODING +# The default value is: UTF-8. INPUT_ENCODING = UTF-8 +# This tag can be used to specify the character encoding of the source files +# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# character encoding on a per file pattern basis. Doxygen will compare the file +# name with each pattern and apply the encoding instead of the default +# INPUT_ENCODING) if there is a match. The character encodings are a list of the +# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding +# "INPUT_ENCODING" for further information on supported encodings. + +INPUT_FILE_ENCODING = + # If the value of the INPUT tag contains directories, you can use the -# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank the following patterns are tested: -# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx -# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90 +# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# Note the list of default checked file patterns might differ from the list of +# default file extension mappings. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.l, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, +# *.inc, *.m, *.markdown, *.md, *.mm, *.dox (to be provided as doxygen C +# comment), *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, *.f18, *.f, *.for, *.vhd, +# *.vhdl, *.ucf, *.qsf and *.ice. FILE_PATTERNS = -# The RECURSIVE tag can be used to turn specify whether or not subdirectories -# should be searched for input files as well. Possible values are YES and NO. -# If left blank NO is used. +# The RECURSIVE tag can be used to specify whether or not subdirectories should +# be searched for input files as well. +# The default value is: NO. RECURSIVE = NO -# The EXCLUDE tag can be used to specify files and/or directories that should +# The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a # subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. EXCLUDE = -# The EXCLUDE_SYMLINKS tag can be used select whether or not files or -# directories that are symbolic links (a Unix filesystem feature) are excluded +# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or +# directories that are symbolic links (a Unix file system feature) are excluded # from the input. +# The default value is: NO. EXCLUDE_SYMLINKS = NO # If the value of the INPUT tag contains directories, you can use the # EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude -# certain files from those directories. Note that the wildcards are matched -# against the file with absolute path, so to exclude all test directories -# for example use the pattern */test/* +# certain files from those directories. +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories for example use the pattern */test/* EXCLUDE_PATTERNS = @@ -630,689 +985,1278 @@ EXCLUDE_PATTERNS = # (namespaces, classes, functions, etc.) that should be excluded from the # output. The symbol name can be a fully qualified name, a word, or if the # wildcard * is used, a substring. Examples: ANamespace, AClass, -# AClass::ANamespace, ANamespace::*Test +# ANamespace::AClass, ANamespace::*Test +# +# Note that the wildcards are matched against the file with absolute path, so to +# exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = HID_API_AS_STR_IMPL \ + HID_API_AS_STR \ + HID_API_TO_VERSION_STR -# The EXAMPLE_PATH tag can be used to specify one or more files or -# directories that contain example code fragments that are included (see -# the \include command). +# The EXAMPLE_PATH tag can be used to specify one or more files or directories +# that contain example code fragments that are included (see the \include +# command). -EXAMPLE_PATH = +EXAMPLE_PATH = ../hidtest # If the value of the EXAMPLE_PATH tag contains directories, you can use the -# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp -# and *.h) to filter out the source-files in the directories. If left -# blank all files are included. +# EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and +# *.h) to filter out the source-files in the directories. If left blank all +# files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = *.c # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be -# searched for input files to be used with the \include or \dontinclude -# commands irrespective of the value of the RECURSIVE tag. -# Possible values are YES and NO. If left blank NO is used. +# searched for input files to be used with the \include or \dontinclude commands +# irrespective of the value of the RECURSIVE tag. +# The default value is: NO. EXAMPLE_RECURSIVE = NO -# The IMAGE_PATH tag can be used to specify one or more files or -# directories that contain image that are included in the documentation (see -# the \image command). +# The IMAGE_PATH tag can be used to specify one or more files or directories +# that contain images that are to be included in the documentation (see the +# \image command). IMAGE_PATH = # The INPUT_FILTER tag can be used to specify a program that doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program -# by executing (via popen()) the command , where -# is the value of the INPUT_FILTER tag, and is the name of an -# input file. Doxygen will then use the output that the filter program writes -# to standard output. -# If FILTER_PATTERNS is specified, this tag will be -# ignored. +# by executing (via popen()) the command: +# +# +# +# where is the value of the INPUT_FILTER tag, and is the +# name of an input file. Doxygen will then use the output that the filter +# program writes to standard output. If FILTER_PATTERNS is specified, this tag +# will be ignored. +# +# Note that the filter must not add or remove lines; it is applied before the +# code is scanned, but not when the output code is generated. If lines are added +# or removed, the anchors will not be placed correctly. +# +# Note that doxygen will use the data processed and written to standard output +# for further processing, therefore nothing else, like debug statements or used +# commands (so in case of a Windows batch file always use @echo OFF), should be +# written to standard output. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. INPUT_FILTER = # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern -# basis. -# Doxygen will compare the file name with each pattern and apply the -# filter if there is a match. -# The filters are a list of the form: -# pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further -# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER -# is applied to all files. +# basis. Doxygen will compare the file name with each pattern and apply the +# filter if there is a match. The filters are a list of the form: pattern=filter +# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how +# filters are used. If the FILTER_PATTERNS tag is empty or if none of the +# patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER) will be used to filter the input files when producing source -# files to browse (i.e. when SOURCE_BROWSER is set to YES). +# INPUT_FILTER) will also be used to filter the input files that are used for +# producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). +# The default value is: NO. FILTER_SOURCE_FILES = NO +# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file +# pattern. A pattern will override the setting for FILTER_PATTERN (if any) and +# it is also possible to disable source filtering for a specific pattern using +# *.ext= (so without naming a filter). +# This tag requires that the tag FILTER_SOURCE_FILES is set to YES. + +FILTER_SOURCE_PATTERNS = + +# If the USE_MDFILE_AS_MAINPAGE tag refers to the name of a markdown file that +# is part of the input, its contents will be placed on the main page +# (index.html). This can be useful if you have a project on for instance GitHub +# and want to reuse the introduction page also for the doxygen output. + +USE_MDFILE_AS_MAINPAGE = main_page.md + +# The Fortran standard specifies that for fixed formatted Fortran code all +# characters from position 72 are to be considered as comment. A common +# extension is to allow longer lines before the automatic comment starts. The +# setting FORTRAN_COMMENT_AFTER will also make it possible that longer lines can +# be processed before the automatic comment starts. +# Minimum value: 7, maximum value: 10000, default value: 72. + +FORTRAN_COMMENT_AFTER = 72 + #--------------------------------------------------------------------------- -# configuration options related to source browsing +# Configuration options related to source browsing #--------------------------------------------------------------------------- -# If the SOURCE_BROWSER tag is set to YES then a list of source files will -# be generated. Documented entities will be cross-referenced with these sources. -# Note: To get rid of all source code in the generated output, make sure also -# VERBATIM_HEADERS is set to NO. +# If the SOURCE_BROWSER tag is set to YES then a list of source files will be +# generated. Documented entities will be cross-referenced with these sources. +# +# Note: To get rid of all source code in the generated output, make sure that +# also VERBATIM_HEADERS is set to NO. +# The default value is: NO. SOURCE_BROWSER = NO -# Setting the INLINE_SOURCES tag to YES will include the body -# of functions and classes directly in the documentation. +# Setting the INLINE_SOURCES tag to YES will include the body of functions, +# classes and enums directly into the documentation. +# The default value is: NO. INLINE_SOURCES = NO -# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct -# doxygen to hide any special comment blocks from generated source code -# fragments. Normal C and C++ comments will always remain visible. +# Setting the STRIP_CODE_COMMENTS tag to YES will instruct doxygen to hide any +# special comment blocks from generated source code fragments. Normal C, C++ and +# Fortran comments will always remain visible. +# The default value is: YES. STRIP_CODE_COMMENTS = YES -# If the REFERENCED_BY_RELATION tag is set to YES -# then for each documented function all documented -# functions referencing it will be listed. +# If the REFERENCED_BY_RELATION tag is set to YES then for each documented +# entity all documented functions referencing it will be listed. +# The default value is: NO. REFERENCED_BY_RELATION = NO -# If the REFERENCES_RELATION tag is set to YES -# then for each documented function all documented entities -# called/used by that function will be listed. +# If the REFERENCES_RELATION tag is set to YES then for each documented function +# all documented entities called/used by that function will be listed. +# The default value is: NO. REFERENCES_RELATION = NO -# If the REFERENCES_LINK_SOURCE tag is set to YES (the default) -# and SOURCE_BROWSER tag is set to YES, then the hyperlinks from -# functions in REFERENCES_RELATION and REFERENCED_BY_RELATION lists will -# link to the source code. -# Otherwise they will link to the documentation. +# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set +# to YES then the hyperlinks from functions in REFERENCES_RELATION and +# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will +# link to the documentation. +# The default value is: YES. REFERENCES_LINK_SOURCE = YES -# If the USE_HTAGS tag is set to YES then the references to source code -# will point to the HTML generated by the htags(1) tool instead of doxygen -# built-in source browser. The htags tool is part of GNU's global source -# tagging system (see http://www.gnu.org/software/global/global.html). You -# will need version 4.8.6 or higher. +# If SOURCE_TOOLTIPS is enabled (the default) then hovering a hyperlink in the +# source code will show a tooltip with additional information such as prototype, +# brief description and links to the definition and documentation. Since this +# will make the HTML file larger and loading of large files a bit slower, you +# can opt to disable this feature. +# The default value is: YES. +# This tag requires that the tag SOURCE_BROWSER is set to YES. + +SOURCE_TOOLTIPS = YES + +# If the USE_HTAGS tag is set to YES then the references to source code will +# point to the HTML generated by the htags(1) tool instead of doxygen built-in +# source browser. The htags tool is part of GNU's global source tagging system +# (see https://www.gnu.org/software/global/global.html). You will need version +# 4.8.6 or higher. +# +# To use it do the following: +# - Install the latest version of global +# - Enable SOURCE_BROWSER and USE_HTAGS in the configuration file +# - Make sure the INPUT points to the root of the source tree +# - Run doxygen as normal +# +# Doxygen will invoke htags (and that will in turn invoke gtags), so these +# tools must be available from the command line (i.e. in the search path). +# +# The result: instead of the source browser generated by doxygen, the links to +# source code will now point to the output of htags. +# The default value is: NO. +# This tag requires that the tag SOURCE_BROWSER is set to YES. USE_HTAGS = NO -# If the VERBATIM_HEADERS tag is set to YES (the default) then Doxygen -# will generate a verbatim copy of the header file for each class for -# which an include is specified. Set to NO to disable this. +# If the VERBATIM_HEADERS tag is set the YES then doxygen will generate a +# verbatim copy of the header file for each class for which an include is +# specified. Set to NO to disable this. +# See also: Section \class. +# The default value is: YES. VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- -# configuration options related to the alphabetical class index +# Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- -# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index -# of all compounds will be generated. Enable this if the project -# contains a lot of classes, structs, unions or interfaces. +# If the ALPHABETICAL_INDEX tag is set to YES, an alphabetical index of all +# compounds will be generated. Enable this if the project contains a lot of +# classes, structs, unions or interfaces. +# The default value is: YES. ALPHABETICAL_INDEX = YES -# If the alphabetical index is enabled (see ALPHABETICAL_INDEX) then -# the COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns -# in which this list will be split (can be a number in the range [1..20]) - -COLS_IN_ALPHA_INDEX = 5 - -# In case all classes in a project start with a common prefix, all -# classes will be put under the same header in the alphabetical index. -# The IGNORE_PREFIX tag can be used to specify one or more prefixes that -# should be ignored while generating the index headers. +# The IGNORE_PREFIX tag can be used to specify a prefix (or a list of prefixes) +# that should be ignored while generating the index headers. The IGNORE_PREFIX +# tag works for classes, function and member names. The entity will be placed in +# the alphabetical list under the first letter of the entity name that remains +# after removing the prefix. +# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. IGNORE_PREFIX = #--------------------------------------------------------------------------- -# configuration options related to the HTML output +# Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES (the default) Doxygen will -# generate HTML output. +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output +# The default value is: YES. GENERATE_HTML = YES -# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. -# If a relative path is entered the value of OUTPUT_DIRECTORY will be -# put in front of it. If left blank `html' will be used as the default path. +# The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a +# relative path is entered the value of OUTPUT_DIRECTORY will be put in front of +# it. +# The default directory is: html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_OUTPUT = html -# The HTML_FILE_EXTENSION tag can be used to specify the file extension for -# each generated HTML page (for example: .htm,.php,.asp). If it is left blank -# doxygen will generate files with .html extension. +# The HTML_FILE_EXTENSION tag can be used to specify the file extension for each +# generated HTML page (for example: .htm, .php, .asp). +# The default value is: .html. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FILE_EXTENSION = .html -# The HTML_HEADER tag can be used to specify a personal HTML header for -# each generated HTML page. If it is left blank doxygen will generate a +# The HTML_HEADER tag can be used to specify a user-defined HTML header file for +# each generated HTML page. If the tag is left blank doxygen will generate a # standard header. +# +# To get valid HTML the header file that includes any scripts and style sheets +# that doxygen needs, which is dependent on the configuration options used (e.g. +# the setting GENERATE_TREEVIEW). It is highly recommended to start with a +# default header using +# doxygen -w html new_header.html new_footer.html new_stylesheet.css +# YourConfigFile +# and then modify the file new_header.html. See also section "Doxygen usage" +# for information on how to generate the default header that doxygen normally +# uses. +# Note: The header is subject to change so you typically have to regenerate the +# default header when upgrading to a newer version of doxygen. For a description +# of the possible markers and block names see the documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_HEADER = -# The HTML_FOOTER tag can be used to specify a personal HTML footer for -# each generated HTML page. If it is left blank doxygen will generate a -# standard footer. +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_FOOTER = -# The HTML_STYLESHEET tag can be used to specify a user-defined cascading -# style sheet that is used by each HTML page. It can be used to -# fine-tune the look of the HTML output. If the tag is left blank doxygen -# will generate a default style sheet. Note that doxygen will try to copy -# the style sheet file to the HTML output directory, so don't put your own -# stylesheet in the HTML output directory as well, or it will be erased! +# The HTML_STYLESHEET tag can be used to specify a user-defined cascading style +# sheet that is used by each HTML page. It can be used to fine-tune the look of +# the HTML output. If left blank doxygen will generate a default style sheet. +# See also section "Doxygen usage" for information on how to generate the style +# sheet that doxygen normally uses. +# Note: It is recommended to use HTML_EXTRA_STYLESHEET instead of this tag, as +# it is more robust and this tag (HTML_STYLESHEET) will in the future become +# obsolete. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_STYLESHEET = -# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. -# Doxygen will adjust the colors in the stylesheet and background images -# according to this color. Hue is specified as an angle on a colorwheel, -# see http://en.wikipedia.org/wiki/Hue for more information. -# For instance the value 0 represents red, 60 is yellow, 120 is green, -# 180 is cyan, 240 is blue, 300 purple, and 360 is red again. -# The allowed range is 0 to 359. +# The HTML_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# cascading style sheets that are included after the standard style sheets +# created by doxygen. Using this option one can overrule certain style aspects. +# This is preferred over using HTML_STYLESHEET since it does not replace the +# standard style sheet and is therefore more robust against future updates. +# Doxygen will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# Note: Since the styling of scrollbars can currently not be overruled in +# Webkit/Chromium, the styling will be left out of the default doxygen.css if +# one or more extra stylesheets have been specified. So if scrollbar +# customization is desired it has to be added explicitly. For an example see the +# documentation. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_STYLESHEET = + +# The HTML_EXTRA_FILES tag can be used to specify one or more extra images or +# other source files which should be copied to the HTML output directory. Note +# that these files will be copied to the base HTML output directory. Use the +# $relpath^ marker in the HTML_HEADER and/or HTML_FOOTER files to load these +# files. In the HTML_STYLESHEET file, use the file name only. Also note that the +# files will be copied as-is; there are no commands or markers available. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_EXTRA_FILES = + +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. +# The default value is: AUTO_LIGHT. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE = AUTO_LIGHT + +# The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen +# will adjust the colors in the style sheet and background images according to +# this color. Hue is specified as an angle on a color-wheel, see +# https://en.wikipedia.org/wiki/Hue for more information. For instance the value +# 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 +# purple, and 360 is red again. +# Minimum value: 0, maximum value: 359, default value: 220. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_HUE = 220 -# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of -# the colors in the HTML output. For a value of 0 the output will use -# grayscales only. A value of 255 will produce the most vivid colors. +# The HTML_COLORSTYLE_SAT tag controls the purity (or saturation) of the colors +# in the HTML output. For a value of 0 the output will use gray-scales only. A +# value of 255 will produce the most vivid colors. +# Minimum value: 0, maximum value: 255, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_SAT = 100 -# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to -# the luminance component of the colors in the HTML output. Values below -# 100 gradually make the output lighter, whereas values above 100 make -# the output darker. The value divided by 100 is the actual gamma applied, -# so 80 represents a gamma of 0.8, The value 220 represents a gamma of 2.2, -# and 100 does not change the gamma. +# The HTML_COLORSTYLE_GAMMA tag controls the gamma correction applied to the +# luminance component of the colors in the HTML output. Values below 100 +# gradually make the output lighter, whereas values above 100 make the output +# darker. The value divided by 100 is the actual gamma applied, so 80 represents +# a gamma of 0.8, The value 220 represents a gamma of 2.2, and 100 does not +# change the gamma. +# Minimum value: 40, maximum value: 240, default value: 80. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML -# page will contain the date and time when the page was generated. Setting -# this to NO can help when comparing the output of multiple runs. +# page will contain the date and time when the page was generated. Setting this +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = YES -# If the HTML_ALIGN_MEMBERS tag is set to YES, the members of classes, -# files or namespaces will be aligned in HTML using tables. If set to -# NO a bullet list will be used. +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. -HTML_ALIGN_MEMBERS = YES +HTML_DYNAMIC_MENUS = YES # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the -# page has loaded. For this to work a browser that supports -# JavaScript and DHTML is required (for instance Mozilla 1.0+, Firefox -# Netscape 6.0+, Internet explorer 5.0+, Konqueror, or Safari). +# page has loaded. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. HTML_DYNAMIC_SECTIONS = NO -# If the GENERATE_DOCSET tag is set to YES, additional index files -# will be generated that can be used as input for Apple's Xcode 3 -# integrated development environment, introduced with OSX 10.5 (Leopard). -# To create a documentation set, doxygen will generate a Makefile in the -# HTML output directory. Running make will produce the docset in that -# directory and running "make install" will install the docset in -# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find -# it at startup. -# See http://developer.apple.com/tools/creatingdocsetswithdoxygen.html -# for more information. +# With HTML_INDEX_NUM_ENTRIES one can control the preferred number of entries +# shown in the various tree structured indices initially; the user can expand +# and collapse entries dynamically later on. Doxygen will expand the tree to +# such a level that at most the specified number of entries are visible (unless +# a fully collapsed tree already exceeds this amount). So setting the number of +# entries 1 will produce a full collapsed tree by default. 0 is a special value +# representing an infinite number of entries and will result in a full expanded +# tree by default. +# Minimum value: 0, maximum value: 9999, default value: 100. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_INDEX_NUM_ENTRIES = 100 + +# If the GENERATE_DOCSET tag is set to YES, additional index files will be +# generated that can be used as input for Apple's Xcode 3 integrated development +# environment (see: +# https://developer.apple.com/xcode/), introduced with OSX 10.5 (Leopard). To +# create a documentation set, doxygen will generate a Makefile in the HTML +# output directory. Running make will produce the docset in that directory and +# running make install will install the docset in +# ~/Library/Developer/Shared/Documentation/DocSets so that Xcode will find it at +# startup. See https://developer.apple.com/library/archive/featuredarticles/Doxy +# genXcode/_index.html for more information. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_DOCSET = NO -# When GENERATE_DOCSET tag is set to YES, this tag determines the name of the -# feed. A documentation feed provides an umbrella under which multiple -# documentation sets from a single provider (such as a company or product suite) -# can be grouped. +# This tag determines the name of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# The default value is: Doxygen generated docs. +# This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_FEEDNAME = "Doxygen generated docs" -# When GENERATE_DOCSET tag is set to YES, this tag specifies a string that -# should uniquely identify the documentation set bundle. This should be a -# reverse domain-name style string, e.g. com.mycompany.MyDocSet. Doxygen -# will append .docset to the name. +# This tag determines the URL of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDURL = + +# This tag specifies a string that should uniquely identify the documentation +# set bundle. This should be a reverse domain-name style string, e.g. +# com.mycompany.MyDocSet. Doxygen will append .docset to the name. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_BUNDLE_ID = org.doxygen.Project -# When GENERATE_PUBLISHER_ID tag specifies a string that should uniquely identify +# The DOCSET_PUBLISHER_ID tag specifies a string that should uniquely identify # the documentation publisher. This should be a reverse domain-name style # string, e.g. com.mycompany.MyDocSet.documentation. +# The default value is: org.doxygen.Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_ID = org.doxygen.Publisher -# The GENERATE_PUBLISHER_NAME tag identifies the documentation publisher. +# The DOCSET_PUBLISHER_NAME tag identifies the documentation publisher. +# The default value is: Publisher. +# This tag requires that the tag GENERATE_DOCSET is set to YES. DOCSET_PUBLISHER_NAME = Publisher -# If the GENERATE_HTMLHELP tag is set to YES, additional index files -# will be generated that can be used as input for tools like the -# Microsoft HTML help workshop to generate a compiled HTML help file (.chm) -# of the generated HTML documentation. +# If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three +# additional HTML index files: index.hhp, index.hhc, and index.hhk. The +# index.hhp is a project file that can be read by Microsoft's HTML Help Workshop +# on Windows. In the beginning of 2021 Microsoft took the original page, with +# a.o. the download links, offline the HTML help workshop was already many years +# in maintenance mode). You can download the HTML help workshop from the web +# archives at Installation executable (see: +# http://web.archive.org/web/20160201063255/http://download.microsoft.com/downlo +# ad/0/A/9/0A939EF6-E31C-430F-A3DF-DFAE7960D564/htmlhelp.exe). +# +# The HTML Help Workshop contains a compiler that can convert all HTML output +# generated by doxygen into a single compiled HTML file (.chm). Compiled HTML +# files are now used as the Windows 98 help format, and will replace the old +# Windows help format (.hlp) on all Windows platforms in the future. Compressed +# HTML files also contain an index, a table of contents, and you can search for +# words in the documentation. The HTML workshop also contains a viewer for +# compressed HTML files. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_HTMLHELP = NO -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can -# be used to specify the file name of the resulting .chm file. You -# can add a path in front of the file if the result should not be +# The CHM_FILE tag can be used to specify the file name of the resulting .chm +# file. You can add a path in front of the file if the result should not be # written to the html output directory. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_FILE = -# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can -# be used to specify the location (absolute path including file name) of -# the HTML help compiler (hhc.exe). If non-empty doxygen will try to run -# the HTML help compiler on the generated index.hhp. +# The HHC_LOCATION tag can be used to specify the location (absolute path +# including file name) of the HTML help compiler (hhc.exe). If non-empty, +# doxygen will try to run the HTML help compiler on the generated index.hhp. +# The file has to be specified with full path. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = -# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag -# controls if a separate .chi index file is generated (YES) or that -# it should be included in the master .chm file (NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the main .chm file (NO). +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# If the GENERATE_HTMLHELP tag is set to YES, the CHM_INDEX_ENCODING -# is used to encode HtmlHelp index (hhk), content (hhc) and project file -# content. +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) +# and project file content. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = -# If the GENERATE_HTMLHELP tag is set to YES, the BINARY_TOC flag -# controls whether a binary table of contents is generated (YES) or a -# normal table of contents (NO) in the .chm file. +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it +# enables the Previous and Next buttons. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. BINARY_TOC = NO -# The TOC_EXPAND flag can be set to YES to add extra items for group members -# to the contents of the HTML help documentation and to the tree view. +# The TOC_EXPAND flag can be set to YES to add extra items for group members to +# the table of contents of the HTML help documentation and to the tree view. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTMLHELP is set to YES. TOC_EXPAND = NO # If the GENERATE_QHP tag is set to YES and both QHP_NAMESPACE and -# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated -# that can be used as input for Qt's qhelpgenerator to generate a -# Qt Compressed Help (.qch) of the generated HTML documentation. +# QHP_VIRTUAL_FOLDER are set, an additional index file will be generated that +# can be used as input for Qt's qhelpgenerator to generate a Qt Compressed Help +# (.qch) of the generated HTML documentation. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_QHP = NO -# If the QHG_LOCATION tag is specified, the QCH_FILE tag can -# be used to specify the file name of the resulting .qch file. -# The path specified is relative to the HTML output folder. +# If the QHG_LOCATION tag is specified, the QCH_FILE tag can be used to specify +# the file name of the resulting .qch file. The path specified is relative to +# the HTML output folder. +# This tag requires that the tag GENERATE_QHP is set to YES. QCH_FILE = -# The QHP_NAMESPACE tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#namespace +# The QHP_NAMESPACE tag specifies the namespace to use when generating Qt Help +# Project output. For more information please see Qt Help Project / Namespace +# (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#namespace). +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_QHP is set to YES. QHP_NAMESPACE = org.doxygen.Project -# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating -# Qt Help Project output. For more information please see -# http://doc.trolltech.com/qthelpproject.html#virtual-folders +# The QHP_VIRTUAL_FOLDER tag specifies the namespace to use when generating Qt +# Help Project output. For more information please see Qt Help Project / Virtual +# Folders (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#virtual-folders). +# The default value is: doc. +# This tag requires that the tag GENERATE_QHP is set to YES. QHP_VIRTUAL_FOLDER = doc -# If QHP_CUST_FILTER_NAME is set, it specifies the name of a custom filter to -# add. For more information please see -# http://doc.trolltech.com/qthelpproject.html#custom-filters +# If the QHP_CUST_FILTER_NAME tag is set, it specifies the name of a custom +# filter to add. For more information please see Qt Help Project / Custom +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_NAME = -# The QHP_CUST_FILT_ATTRS tag specifies the list of the attributes of the -# custom filter to add. For more information please see -# -# Qt Help Project / Custom Filters. +# The QHP_CUST_FILTER_ATTRS tag specifies the list of the attributes of the +# custom filter to add. For more information please see Qt Help Project / Custom +# Filters (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#custom-filters). +# This tag requires that the tag GENERATE_QHP is set to YES. QHP_CUST_FILTER_ATTRS = # The QHP_SECT_FILTER_ATTRS tag specifies the list of the attributes this -# project's -# filter section matches. -# -# Qt Help Project / Filter Attributes. +# project's filter section matches. Qt Help Project / Filter Attributes (see: +# https://doc.qt.io/archives/qt-4.8/qthelpproject.html#filter-attributes). +# This tag requires that the tag GENERATE_QHP is set to YES. QHP_SECT_FILTER_ATTRS = -# If the GENERATE_QHP tag is set to YES, the QHG_LOCATION tag can -# be used to specify the location of Qt's qhelpgenerator. -# If non-empty doxygen will try to run qhelpgenerator on the generated -# .qhp file. +# The QHG_LOCATION tag can be used to specify the location (absolute path +# including file name) of Qt's qhelpgenerator. If non-empty doxygen will try to +# run qhelpgenerator on the generated .qhp file. +# This tag requires that the tag GENERATE_QHP is set to YES. QHG_LOCATION = -# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files -# will be generated, which together with the HTML files, form an Eclipse help -# plugin. To install this plugin and make it available under the help contents -# menu in Eclipse, the contents of the directory containing the HTML and XML -# files needs to be copied into the plugins directory of eclipse. The name of -# the directory within the plugins directory should be the same as -# the ECLIPSE_DOC_ID value. After copying Eclipse needs to be restarted before -# the help appears. +# If the GENERATE_ECLIPSEHELP tag is set to YES, additional index files will be +# generated, together with the HTML files, they form an Eclipse help plugin. To +# install this plugin and make it available under the help contents menu in +# Eclipse, the contents of the directory containing the HTML and XML files needs +# to be copied into the plugins directory of eclipse. The name of the directory +# within the plugins directory should be the same as the ECLIPSE_DOC_ID value. +# After copying Eclipse needs to be restarted before the help appears. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_ECLIPSEHELP = NO -# A unique identifier for the eclipse help plugin. When installing the plugin -# the directory name containing the HTML and XML files should also have -# this name. +# A unique identifier for the Eclipse help plugin. When installing the plugin +# the directory name containing the HTML and XML files should also have this +# name. Each documentation set should have its own identifier. +# The default value is: org.doxygen.Project. +# This tag requires that the tag GENERATE_ECLIPSEHELP is set to YES. ECLIPSE_DOC_ID = org.doxygen.Project -# The DISABLE_INDEX tag can be used to turn on/off the condensed index at -# top of each HTML page. The value NO (the default) enables the index and -# the value YES disables it. +# If you want full control over the layout of the generated HTML pages it might +# be necessary to disable the index and replace it with your own. The +# DISABLE_INDEX tag can be used to turn on/off the condensed index (tabs) at top +# of each HTML page. A value of NO enables the index and the value YES disables +# it. Since the tabs in the index contain the same information as the navigation +# tree, you can set this option to YES if you also set GENERATE_TREEVIEW to YES. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. DISABLE_INDEX = NO -# This tag can be used to set the number of enum values (range [1..20]) -# that doxygen will group on one line in the generated HTML documentation. - -ENUM_VALUES_PER_LINE = 4 - # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index -# structure should be generated to display hierarchical information. -# If the tag value is set to YES, a side panel will be generated -# containing a tree-like index structure (just like the one that -# is generated for HTML Help). For this to work a browser that supports -# JavaScript, DHTML, CSS and frames is required (i.e. any modern browser). -# Windows users are probably better off using the HTML help feature. +# structure should be generated to display hierarchical information. If the tag +# value is set to YES, a side panel will be generated containing a tree-like +# index structure (just like the one that is generated for HTML Help). For this +# to work a browser that supports JavaScript, DHTML, CSS and frames is required +# (i.e. any modern browser). Windows users are probably better off using the +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can +# further fine tune the look of the index (see "Fine-tuning the output"). As an +# example, the default style sheet generated by doxygen has an example that +# shows how to put an image at the root of the tree instead of the PROJECT_NAME. +# Since the tree basically has the same information as the tab index, you could +# consider setting DISABLE_INDEX to YES when enabling this option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. GENERATE_TREEVIEW = NO -# By enabling USE_INLINE_TREES, doxygen will generate the Groups, Directories, -# and Class Hierarchy pages using a tree view instead of an ordered list. +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATE_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FULL_SIDEBAR = NO -USE_INLINE_TREES = NO +# The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that +# doxygen will group on one line in the generated HTML documentation. +# +# Note that a value of 0 will completely suppress the enum values from appearing +# in the overview section. +# Minimum value: 0, maximum value: 20, default value: 4. +# This tag requires that the tag GENERATE_HTML is set to YES. + +ENUM_VALUES_PER_LINE = 4 -# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be -# used to set the initial width (in pixels) of the frame in which the tree -# is shown. +# If the treeview is enabled (see GENERATE_TREEVIEW) then this tag can be used +# to set the initial width (in pixels) of the frame in which the tree is shown. +# Minimum value: 0, maximum value: 1500, default value: 250. +# This tag requires that the tag GENERATE_HTML is set to YES. TREEVIEW_WIDTH = 250 -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open -# links to external symbols imported via tag files in a separate window. +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to +# external symbols imported via tag files in a separate window. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. EXT_LINKS_IN_WINDOW = NO -# Use this tag to change the font size of Latex formulas included -# as images in the HTML documentation. The default is 10. Note that -# when you change the font size after a successful doxygen run you need -# to manually remove any form_*.png images from the HTML output directory -# to force them to be regenerated. +# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# addresses. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. -FORMULA_FONTSIZE = 10 +OBFUSCATE_EMAILS = YES + +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are -# not supported properly for IE 6.0, but are supported on all modern browsers. -# Note that when changing this option you need to delete any form_*.png files -# in the HTML output before the changes have effect. +HTML_FORMULA_FORMAT = png -FORMULA_TRANSPARENT = YES +# Use this tag to change the font size of LaTeX formulas included as images in +# the HTML documentation. When you change the font size after a successful +# doxygen run you need to manually remove any form_*.png images from the HTML +# output directory to force them to be regenerated. +# Minimum value: 8, maximum value: 50, default value: 10. +# This tag requires that the tag GENERATE_HTML is set to YES. -# When the SEARCHENGINE tag is enabled doxygen will generate a search box -# for the HTML output. The underlying search engine uses javascript -# and DHTML and should work on any modern browser. Note that when using -# HTML help (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets -# (GENERATE_DOCSET) there is already a search function so this one should -# typically be disabled. For large projects the javascript based search engine -# can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. +FORMULA_FONTSIZE = 10 + +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. + +FORMULA_MACROFILE = + +# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see +# https://www.mathjax.org) which uses client side JavaScript for the rendering +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX +# installed or if you want to formulas look prettier in the HTML output. When +# enabled you may also need to install MathJax separately and configure the path +# to it using the MATHJAX_RELPATH option. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +USE_MATHJAX = NO + +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + +# When MathJax is enabled you can set the default output format to be used for +# the MathJax output. For more details about the output format see MathJax +# version 2 (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) and MathJax version 3 +# (see: +# http://docs.mathjax.org/en/latest/web/components/output.html). +# Possible values are: HTML-CSS (which is slower, but has the best +# compatibility. This is the name for Mathjax version 2, for MathJax version 3 +# this will be translated into chtml), NativeMML (i.e. MathML. Only supported +# for NathJax 2. For MathJax version 3 chtml will be used instead.), chtml (This +# is the name for Mathjax version 3, for MathJax version 2 this will be +# translated into HTML-CSS) and SVG. +# The default value is: HTML-CSS. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_FORMAT = HTML-CSS + +# When MathJax is enabled you need to specify the location relative to the HTML +# output directory using the MATHJAX_RELPATH option. The destination directory +# should contain the MathJax.js script. For instance, if the mathjax directory +# is located at the same level as the HTML output directory, then +# MATHJAX_RELPATH should be ../mathjax. The default value points to the MathJax +# Content Delivery Network so you can quickly see the result without installing +# MathJax. However, it is strongly recommended to install a local copy of +# MathJax from https://www.mathjax.org before deployment. The default value is: +# - in case of MathJax version 2: https://cdn.jsdelivr.net/npm/mathjax@2 +# - in case of MathJax version 3: https://cdn.jsdelivr.net/npm/mathjax@3 +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_RELPATH = https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/ + +# The MATHJAX_EXTENSIONS tag can be used to specify one or more MathJax +# extension names that should be enabled during MathJax rendering. For example +# for MathJax version 2 (see +# https://docs.mathjax.org/en/v2.7-latest/tex.html#tex-and-latex-extensions): +# MATHJAX_EXTENSIONS = TeX/AMSmath TeX/AMSsymbols +# For example for MathJax version 3 (see +# http://docs.mathjax.org/en/latest/input/tex/extensions/index.html): +# MATHJAX_EXTENSIONS = ams +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_EXTENSIONS = + +# The MATHJAX_CODEFILE tag can be used to specify a file with javascript pieces +# of code that will be used on startup of the MathJax code. See the MathJax site +# (see: +# http://docs.mathjax.org/en/v2.7-latest/output.html) for more details. For an +# example see the documentation. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_CODEFILE = + +# When the SEARCHENGINE tag is enabled doxygen will generate a search box for +# the HTML output. The underlying search engine uses javascript and DHTML and +# should work on any modern browser. Note that when using HTML help +# (GENERATE_HTMLHELP), Qt help (GENERATE_QHP), or docsets (GENERATE_DOCSET) +# there is already a search function so this one should typically be disabled. +# For large projects the javascript based search engine can be slow, then +# enabling SERVER_BASED_SEARCH may provide a better solution. It is possible to +# search using the keyboard; to jump to the search box use + S +# (what the is depends on the OS and browser, but it is typically +# , /