{"id":30354549,"url":"https://github.com/alh477/idtech4-dsp-driver","last_synced_at":"2026-05-18T19:41:57.389Z","repository":{"id":309509547,"uuid":"1036541001","full_name":"ALH477/IDTECH4-DSP-DRIVER","owner":"ALH477","description":"This prototype integrates a Texas Instruments TMS320C674x DSP with the Doom 3 GPL codebase to offload real-time ray-traced audio computations for reverb, occlusion, diffraction, and absorption. It leverages libusb for low-latency data transfer and preserves compatibility with existing OSS/ALSA backends, targeting \u003c20ms latency.","archived":false,"fork":false,"pushed_at":"2025-08-12T08:32:01.000Z","size":48,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T10:20:54.542Z","etag":null,"topics":["audio-processing","c","cpp","doom3","dsp","dsplib","game-development","game-engine","idtech4","libusb","prey-2006","quake4","raytracing","stochastic-simulation","thedarkmod","tms320c6748","tms320c674x"],"latest_commit_sha":null,"homepage":"https://DeMoD.ltd","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ALH477.png","metadata":{"files":{"readme":"README.markdown","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-08-12T08:19:11.000Z","updated_at":"2025-08-12T08:35:45.000Z","dependencies_parsed_at":"2025-08-12T10:35:30.022Z","dependency_job_id":null,"html_url":"https://github.com/ALH477/IDTECH4-DSP-DRIVER","commit_stats":null,"previous_names":["alh477/idtech4-dsp-driver"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ALH477/IDTECH4-DSP-DRIVER","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FIDTECH4-DSP-DRIVER","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FIDTECH4-DSP-DRIVER/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FIDTECH4-DSP-DRIVER/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FIDTECH4-DSP-DRIVER/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ALH477","download_url":"https://codeload.github.com/ALH477/IDTECH4-DSP-DRIVER/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ALH477%2FIDTECH4-DSP-DRIVER/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271096757,"owners_count":24698717,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio-processing","c","cpp","doom3","dsp","dsplib","game-development","game-engine","idtech4","libusb","prey-2006","quake4","raytracing","stochastic-simulation","thedarkmod","tms320c6748","tms320c674x"],"created_at":"2025-08-19T03:37:24.629Z","updated_at":"2026-05-18T19:41:57.384Z","avatar_url":"https://github.com/ALH477.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# idTech4-DSP-Audio: Enhanced Audio Mod for idTech 4 (Dhewm3)\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Build Status](https://img.shields.io/badge/build-Alpha-brightgreen.svg)](https://github.com/dhewm/dhewm3)\n[![Contributors](https://img.shields.io/badge/contributors-1-orange.svg)](https://github.com/yourusername/idTech4-DSP-Audio/graphs/contributors)\n\n## Project Overview\n\n(NEW STANDARD ARCHITECTURE IS A SIMULATED DSP VM WITH 1.33ms)\n\nThis mod extends the idTech 4 engine (via the Dhewm3 port) to support hardware-accelerated audio processing using a USB-connected Digital Signal Processor (DSP, e.g., Texas Instruments TMS320C674x). It introduces real-time ray-traced audio effects (e.g., reverb, occlusion, distortion) and dynamic audio mode zones defined by in-game entities (`func_audio_mode`). Designed for single-player horror/cyberpunk mods like *Petabyte Madness*, it enhances immersion with spatial audio and dynamic effects while maintaining compatibility with idTech4’s sound system (e.g., OpenAL fallback). The mod is modder-friendly, with editor integration, debug tools, and extensive configuration via cVARs.\n\nKey features include:\n- DSP offload for low-latency audio processing (\u003c20ms target).\n- Entity-based audio modes for location-specific effects (e.g., combat distortion, lab reverb).\n- Smooth blending of modes in overlapping zones.\n- Hot-plug USB support and robust error handling.\n- Debug tools and cVARs for modders and players.\n\n**Note**: This is an alpha release (v1.0). Test thoroughly in large maps and profile performance (e.g., `com_showFPS 1`). Multiplayer is untested; focus on single-player.\n\n## Table of Contents\n- [Features](#features)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Architecture Overview](#architecture-overview)\n- [idTech4 Modifications](#idtech4-modifications)\n- [DSP Implementation](#dsp-implementation)\n- [Optimization and Edge Cases](#optimization-and-edge-cases)\n- [cVARs](#cvars)\n- [Debug Tools](#debug-tools)\n- [Contributing](#contributing)\n- [License](#license)\n- [Resources and References](#resources-and-references)\n\n## Features\n- **Hardware DSP Audio**:\n  - Offloads ray tracing, convolution, and effects (e.g., reverb, distortion) to a USB DSP (TMS320C674x or similar, VID:PID 0x0403:0x6010).\n  - Processes up to 1000 stochastic rays per sound source with 5 bounces for realistic occlusion/diffraction.\n  - Uses TI DSPLIB for efficient FIR filtering (convolution).\n- **Audio Mode Entities**:\n  - `func_audio_mode` entities define spatial zones with modes (0-10, e.g., 0=explore, 1=combat) and radii.\n  - Smooth blending (lerp) between overlapping zones based on distance; supports step transitions.\n  - Scriptable events (`onPlayerEnter`, `onPlayerExit`) for custom behaviors (e.g., play sound cues).\n- **Robust Integration**:\n  - Hot-plug support: Reconnects DSP every 5s if unplugged (via `s_dspReconnectInterval`).\n  - Fallback to OpenAL if DSP unavailable (`s_useDSP 0`).\n  - Batched USB transfers reduce overhead (e.g., single buffer for multiple emitters).\n- **Modder QoL**:\n  - Editor-friendly: Place zones in D3Edit, set keys (e.g., `\"mode\" \"1\" \"radius\" \"512\"`).\n  - Debug: `audioModesDebug 2` draws red spheres; `listAudioModes` dumps zone info.\n  - Extensible: Define mode-specific FX in DSP firmware; script events for dynamic effects.\n- **Player UX**:\n  - Smooth mode transitions (tunable via `s_audioModeBlendTime`).\n  - Accessibility: Toggle zones (`s_audioModesEnabled 0`) for reduced audio complexity.\n  - Audio cues on zone entry (e.g., faint sting via `snd_mode_enter`).\n\n## Installation\n\n### Prerequisites\n- **Engine**: Dhewm3 (modern idTech4 port): `git clone https://github.com/dhewm/dhewm3`.\n- **DSP Hardware**: TMS320C674x-based PCB (e.g., OMAP-L138) with USB interface.\n- **Dependencies**:\n  - libusb-1.0 (`sudo apt install libusb-1.0-0-dev` on Ubuntu; `vcpkg install libusb` on Windows).\n  - C++11+ compiler (e.g., GCC, MSVC).\n  - Code Composer Studio (CCS) for DSP firmware (download from TI website).\n  - TI DSPLIB for convolution functions.\n- **Tools**: CMake for Dhewm3 build; D3Edit for map editing.\n\n### Building Dhewm3 with Mod\n1. Clone Dhewm3: `git clone https://github.com/dhewm/dhewm3`.\n2. Copy mod files to Dhewm3 source:\n   - Sound: `neo/sound/snd_dsp.h`, `neo/sound/snd_dsp.cpp`, `neo/sound/snd_system.cpp`, `neo/sound/snd_world.cpp`.\n   - Game: `neo/game/AudioModeEntity.h`, `neo/game/AudioModeEntity.cpp`, `neo/game/AudioModeManager.h`, `neo/game/AudioModeManager.cpp`.\n   - Defs: `def/audio_modes.def`.\n3. Update `neo/CMakeLists.txt`:\n   - Add to game sources: `game/AudioModeEntity.cpp`, `game/AudioModeManager.cpp`.\n   - Add to sound sources: `sound/snd_dsp.cpp`.\n   - Link libusb: `target_link_libraries(dhewm3 PRIVATE usb-1.0)`.\n4. Build: `mkdir build \u0026\u0026 cd build \u0026\u0026 cmake .. \u0026\u0026 make -j4`.\n5. Install: Copy `build/dhewm3` to game directory.\n\n### DSP Firmware Build\n1. Create a CCS project for TMS320C674x.\n2. Implement firmware (see [DSP Implementation](#dsp-implementation)).\n3. Link TI DSPLIB and USB stack.\n4. Flash to DSP via CCS.\n\n## Usage\n\n### For Players\n1. Connect DSP via USB (ensure drivers installed).\n2. Launch game: `./dhewm3 +set s_useDSP 1`.\n3. Adjust settings in console or cfg:\n   - `s_audioModesEnabled 0`: Disable zones for simpler audio.\n   - `s_audioModeBlendTime 1.0`: Slower transitions.\n4. Hear dynamic effects (e.g., reverb in large rooms, distortion in combat zones).\n\nIf DSP disconnects, audio falls back to software (logged in console).\n\n### For Modders\n1. **Place Zones**: In D3Edit, spawn `func_audio_mode`. Set keys:\n   - `\"mode\" \"1\"` (combat FX), `\"radius\" \"512\"`, `\"priority\" \"1\"`, `\"blend_type\" \"0\"` (lerp).\n2. **Debug**:\n   - `audioModesDebug 2`: Draws red spheres for active zones.\n   - `listAudioModes`: Lists zone details (name, mode, radius, position).\n3. **Extend**:\n   - Define mode FX in DSP firmware (e.g., mode 1 = high distortion).\n   - Add scripts in map .script, e.g.:\n     ```\n     void onPlayerEnter(entity zone) {\n         sys.println(\"Entered mode \" + zone.getKey(\"mode\"));\n         sys.playSound(\"snd_custom_cue\");\n     }\n     ```\n4. **Tune**: Use cVARs (e.g., `s_audioMaxZones 10` for smaller maps).\n\n## Architecture Overview\n\nThe mod hooks into idTech4’s sound system (`idSoundSystemLocal`) and offloads processing to a DSP via libusb. Audio mode entities (`func_audio_mode`) define zones that apply mode-specific effects to nearby emitters. The `idAudioModeManager` class handles spatial queries and blending.\n\n### Data Flow\n```mermaid\ngraph TD\n    A[idSoundWorldLocal] --\u003e|Listener/Emitter Data| B[idAudioModeManager]\n    B --\u003e|Mode IDs| C[idSoundHardware_DSP]\n    C --\u003e|Scene Data, Audio| D[libusb Driver]\n    D --\u003e|Bulk Transfer| E[TMS320C674x DSP]\n    E --\u003e|Processed Audio| D --\u003e C --\u003e A\n    subgraph \"Game\"\n        A --\u003e F[MixLoop: Batch Emitters]\n        B --\u003e|Spatial Query| G[gameLocal.clip]\n    end\n    subgraph \"DSP\"\n        E --\u003e H[Stochastic Ray Tracing]\n        H --\u003e I[Convolution via DSPLIB]\n    end\n```\n\n## idTech4 Modifications\n- **snd_dsp.h/cpp**: Implements `idSoundHardware_DSP`, handling USB comms, threading, and buffer queues with `std::unique_ptr` for leak-free memory.\n- **AudioModeEntity.h/cpp**: Defines `func_audio_mode` entities with scriptable events and player entry cues.\n- **AudioModeManager.h/cpp**: Manages zone queries (using `gameLocal.clip`) and distance-based mode blending.\n- **snd_system.cpp**: Adds cVARs, hot-plug detection in `AsyncUpdate`.\n- **snd_world.cpp**: Integrates manager, batches emitter data for DSP.\n- **def/audio_modes.def**: Declares entity with editor-friendly keys.\n\n## DSP Implementation\n- **Target**: TMS320C674x with floating-point support.\n- **Tasks**:\n  - Parse scene data (listener/emitter positions, modes).\n  - Stochastic ray tracing (up to 1000 rays, 5 bounces).\n  - Convolution using DSPLIB’s `DSPF_sp_fir_gen`.\n- **USB**: TI USB stack for bulk endpoints (OUT for data, IN for results).\n- **Optimizations**:\n  - EDMA for buffer copies.\n  - Fixed-point (Q15) or inline assembly (e.g., `MPYSP`) if needed.\n- **Pseudo-Code**:\n  ```c\n  void main() {\n      init_usb();\n      while (1) {\n          receive_scene_data(\u0026listener, \u0026emitters, \u0026modes);\n          float ir[1024];\n          compute_ir(ir, 1024, listener, emitters); // Stochastic rays\n          convolve_audio(input, ir, output, 4096, 1024);\n          send_usb(output);\n      }\n  }\n  ```\n\n## Optimization and Edge Cases\n- **Optimizations**:\n  - Spatial queries use `gameLocal.clip` for O(log n) performance.\n  - Batched USB transfers (one per frame vs. per emitter).\n  - Cap zones (`s_audioMaxZones`) to limit overhead.\n  - Cache IRs for static emitters on DSP.\n- **Edge Cases**:\n  - DSP disconnect: Hot-plug retries; fallback to OpenAL.\n  - No emitters/zones: Skip DSP calls, use default mode.\n  - Overlapping zones: Lerp or step blending; priority resolves ties.\n  - Large maps: Cap zones, tune `s_audioModeSearchRadius`.\n\n## cVARs\nKey configuration variables (see `snd_system.cpp`):\n- `s_useDSP` (bool, 0): Enable DSP offload.\n- `s_dspLogLevel` (int, 0): Logging (0=errors, 1=init/shutdown, 2=verbose).\n- `s_dspReconnectInterval` (int, 5000): Hot-plug poll (ms).\n- `s_audioModesEnabled` (bool, 1): Enable zones.\n- `s_audioModeBlendTime` (float, 0.5): Blend duration (s).\n- `s_audioModeSearchRadius` (float, 1024): Zone search distance.\n- `s_audioModeDefault` (int, 0): Fallback mode.\n- `s_audioMaxZones` (int, 20): Max zones per update.\n\n## Debug Tools\n- `audioModesDebug [0/1/2]`: 0=off, 1=list zones, 2=draw red spheres (active zones).\n- `listAudioModes`: Dumps zone details (name, mode, radius, position).\n- Profile with `com_showFPS 1` for performance.\n\n## Contributing\nFork, create a feature branch, and submit PRs. Guidelines:\n- Follow idTech4 style (e.g., `id*` prefixes, no exceptions).\n- Test on Dhewm3; include unit tests for DSP math.\n- Report bugs via GitHub Issues.\n\n## License\nGNU General Public License v3.0 (GPL-3.0). See [LICENSE](LICENSE).\n\n## Resources and References\n- **Dhewm3**: [github.com/dhewm/dhewm3](https://github.com/dhewm/dhewm3).\n- **TI Documentation**: TMS320C674x DSP Reference (SPRUFE8B), DSPLIB.\n- **idTech4**: [Fabien Sanglard’s Doom 3 Code Review](https://fabiensanglard.net/doom3/).\n- **libusb**: [libusb.info](https://libusb.info/).\n- **Audio Ray Tracing**: Inspired by US Patent 8139780B2, vaRays concepts.\n\nFor support, open an issue or contact the maintainer.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Fidtech4-dsp-driver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falh477%2Fidtech4-dsp-driver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falh477%2Fidtech4-dsp-driver/lists"}