Add header comments to the source files
Every source file in ui, app, game, formats, cli, audio and launch that had none now starts with a short English comment: what it implements, what state it owns and how it relates to its neighbours (request/acknowledge flow, pairs of files, random generator use). Comment lines only; the full build and the runnable tests are unchanged. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
aa6ec96305
commit
287b5a9251
324 files changed
+1186
No files matched your search
@@ -1,4 +1,9 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of container.hpp: parse_container() checks the FORM/ALPTRAUM header and
|
||||
// walks the adjacent little-endian chunks (no alignment byte) with bounds checks, filling
|
||||
// a Container of offsets; decode_sample() and decode_original_cue() convert the bounded
|
||||
// sample data to PCM. Pure functions on byte spans, no state; failures are reported through
|
||||
// the std::string& error argument and a false result.
|
||||
#include "container.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Reader for the original sound container (a FORM/ALPTRAUM chunk wrapper) and for the PCM
|
||||
// samples inside it. A Container only lists chunk ids and payload offsets; the payload bytes
|
||||
// stay in the caller's buffer, which must outlive any use of the offsets. decode_sample()
|
||||
// turns unsigned 8-bit samples into signed 16-bit mono PCM; decode_original_cue() resolves
|
||||
// only the PCM-backed effects (original ids 17..22). Pairs with container.cpp; the PCM types
|
||||
// are shared by mixer, playback, semantic cues and the music fallback.
|
||||
#pragma once
|
||||
|
||||
#include <cstddef>
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of Mixer (mixer.hpp). Incoming PCM is resampled to the output rate with
|
||||
// range and overflow checks and a total/per-voice byte ceiling (2 MiB overall, an eighth of
|
||||
// that per voice); mix_block() sums music and active voices into the output block, applies
|
||||
// the volume and advances the cursors (the music loops).
|
||||
#include "mixer.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Small PCM mixer used by the software (non-original) playback path: one looping music
|
||||
// buffer plus up to 8 one-shot voices, all converted to the output rate when added.
|
||||
// start_music_loop()/add_voice() may allocate; mix_block() only reads the prepared buffers
|
||||
// and writes into caller-owned storage, so it is safe to call from the audio path. Owned
|
||||
// by Playback (playback.hpp); the byte limits are in mixer.cpp.
|
||||
#pragma once
|
||||
|
||||
#include "container.hpp"
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of the synthetic matchday loop (music_fallback.hpp): a fixed 22050 Hz,
|
||||
// 108 bpm, 8-bar sequence of bass, chord and lead notes defined by constant MIDI tables,
|
||||
// rendered to mono PCM16. No game state or randomness is involved, so the output is the
|
||||
// same on every run.
|
||||
#include "music_fallback.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Synthetic fallback matchday music: a deterministic 8-bar loop generated in code. It is
|
||||
// presentation filler, not decoded original music and not tied to any original sound id.
|
||||
// The result is a PcmSample that Playback::start_music_loop() can play; implemented in
|
||||
// music_fallback.cpp.
|
||||
#pragma once
|
||||
|
||||
#include "container.hpp"
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of OriginalSynth (original.hpp). The hidden State holds the parsed
|
||||
// songs, tracks, channels, sample banks and the Nuked-OPL3 chip core (src/audio/third_party);
|
||||
// tick() runs one sequencer step of the original timer interrupt, render() produces output
|
||||
// samples from the chip and the PCM channel. load() validates every input and fails
|
||||
// cleanly on malformed data; the register and sample observers exist only for offline
|
||||
// validation (original_validation.cpp, sound_driver.cpp).
|
||||
#include "original.hpp"
|
||||
#include "container.hpp"
|
||||
#include "third_party/nuked-opl3/opl3.h"
|
||||
|
||||
@@ -1,4 +1,11 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Emulation of the original game's sound system (MIDI-style sequencer, OPL FM instruments
|
||||
// and one Sound Blaster PCM channel) as OriginalSynth. The application reads the sound
|
||||
// containers (S/2000..2003) and the frequency/operator tables from the user's executable
|
||||
// and hands them in as OriginalAssets; this module knows nothing about game state, file
|
||||
// layout, the simulation clock or random generators. command() takes the original sound ids
|
||||
// (0 title, 1 desk, 2 intro, 3 crowd, 8 stop, 10..22 effects); render() fills PCM blocks
|
||||
// without allocating. Implemented in original.cpp, driven by Playback and the audio tools.
|
||||
#pragma once
|
||||
|
||||
#include <array>
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Validation executable for the original-sound emulation (original.hpp, playback.hpp). It
|
||||
// needs the user's game data directory as its single argument, loads the executable tables
|
||||
// and sound containers from it, and runs oracle checks on song/effect output, transitions,
|
||||
// malformed input, option and mute handling, effect priorities and the audio callback
|
||||
// lifecycle. With an empty argument it prints SKIP and exits with 77 (test skipped).
|
||||
// Contains no game assets itself.
|
||||
#include "formats/executable_layout.hpp"
|
||||
#include "original.hpp"
|
||||
#include "playback.hpp"
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of Playback (playback.hpp): opens the SDL audio device, feeds either the
|
||||
// OriginalSynth from the SDL callback (original mode) or bounded blocks from the Mixer via
|
||||
// pump() (software mode), and maps original ids and semantic cues to sound played on the
|
||||
// device. Duplicate or out-of-order event ids are rejected before anything is played;
|
||||
// shutdown() releases the device.
|
||||
#include "playback.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Audio output device wrapper (SDL) and the single audio object the application uses.
|
||||
// Playback owns the SDL device, a software Mixer (PCM effects, optional music loop) and the
|
||||
// OriginalSynth (the full original driver, streamed from SDL's audio callback so modal
|
||||
// windows cannot starve it). Cue requests carry a session id and an increasing event id
|
||||
// chosen by the controller; submit() consumes each event once and returns a CueStatus.
|
||||
// Mute and volume apply to both paths. Pairs with playback.cpp and app/audio.hpp.
|
||||
#pragma once
|
||||
|
||||
#include "container.hpp"
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Implementation of synthesize_semantic_cue() (semantic_cues.hpp): builds each cue in code
|
||||
// (the whistles from frequency sweeps with attack and release shaping) at 22050 Hz and
|
||||
// clamps the result to 16-bit PCM. Pure and deterministic.
|
||||
#include "semantic_cues.hpp"
|
||||
|
||||
#include <algorithm>
|
||||
|
||||
@@ -1,4 +1,8 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Semantic sound cues (kickoff whistle, goal, full-time whistle) synthesized in code for
|
||||
// use when no verified original effect is available. They are labels of intent, never
|
||||
// original sound ids. The generator is deterministic mono PCM16 at 22050 Hz and has no
|
||||
// dependency on game state, randomness or rendering; implemented in semantic_cues.cpp.
|
||||
#pragma once
|
||||
|
||||
#include "container.hpp"
|
||||
|
||||
@@ -1,4 +1,10 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Command line tool openbmh_sound for the audio module. It works either on one sound
|
||||
// container file (play or export a sample, a test tone, or an original effect id as WAV) or,
|
||||
// with --original DATA_DIR, on the user's game data through OriginalSynth (export a song or
|
||||
// effect to WAV, or play ids through the real device). It also plays or exports the
|
||||
// synthetic semantic cues and the fallback music loop. Own state only: parsed arguments.
|
||||
// Bounds on seconds, loops and ids are checked before anything runs.
|
||||
#include "formats/executable_layout.hpp"
|
||||
#include "container.hpp"
|
||||
#include "music_fallback.hpp"
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
// SPDX-License-Identifier: GPL-3.0-only
|
||||
// Self-contained checks for the audio module that need no game data: container parsing
|
||||
// against authored fixtures, sample and cue decoding, the mixer, the playback request
|
||||
// rules and the synthetic music fallback. The fixtures are built in code and are not
|
||||
// copied from any game asset. Returns non-zero on the first failed CHECK; companion of
|
||||
// original_validation.cpp, which covers the original-driver emulation.
|
||||
#include "container.hpp"
|
||||
#include "music_fallback.hpp"
|
||||
#include "playback.hpp"
|
||||
|
||||
Reference in new issue
Block a user