Restore SoundPan / ChannelPan on the OpenAL audio backend#80
Merged
Conversation
SoundPan and ChannelPan are classic Blitz3D stereo-pan commands that BlitzForge
still ships docs/examples for, but the runtime no longer registered or implemented
them -- casualties of the DirectSound->OpenAL port (the impls/registrations were
commented out in bbaudio.cpp and the setPan virtual had been dropped from
gxChannel/gxSound). Legacy programs calling them failed to compile ("SoundPan not
found"); they're corpus-allowlist Class B entries. Restore them (INTENT #1 drop-in
compatibility + a docs-vs-reality fix).
- gxChannel/gxSound: add setPan() (pure-virtual on the bases; only SampleChannel/
StreamChannel + gxSoundSample/gxSoundStream implement these -- no macOS audio
backend exists).
- Channels implement constant-power stereo pan on a listener-relative source:
clamp pan in [-1,1], alSourcei(AL_SOURCE_RELATIVE,AL_TRUE),
alSource3f(AL_POSITION, pan, 0, -sqrt(1-pan^2)). Mutually exclusive with set3d
(last call wins, matching legacy semantics).
- Sounds store a default pan applied at play() (SoundPan sets the default for
subsequently-played channels).
- bbaudio: re-enable bbSoundPan (debugSound-guarded) and bbChannelPan
(verifyChannel-guarded, matching the other channel commands) + their rtSyms,
using the typed (BBSound)/(BBChannel) signatures.
Audible pan correctness is not headless-verifiable (no audio device in CI); the
OpenAL formula is standard and the relative-source setup is confirmed -- audible
verification is a manual Windows step.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add tests/AudioPanTest.bb: a headless-safe smoke test proving SoundPan/ChannelPan resolve and tolerate a Null sound/channel (CI has no audio device). With the commands restored, spider.bb compiles and is removed from the allowlist; aristoids.bb's SoundPan blocker is gone but it also uses PlayMusic (still disabled), so it stays allowlisted with its reason updated. Corpus sweep green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per-file plan, OpenAL constant-power pan mechanism, the spider-cleared/aristoids-now- PlayMusic outcome, and deferred follow-ups (gxsound short-filename crash, other Class B builtins, audible verification). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Non-technical summary
SoundPanandChannelPan— classic Blitz3D commands for placing a sound left/right in the stereo field — were lost when the audio backend moved from DirectSound to OpenAL, even though BlitzForge still ships their documentation and examples. Legacy games calling them failed to compile. This PR restores both commands, so those programs compile and run again (INTENT #1 drop-in compatibility, and it fixes a docs-vs-reality gap).Technical summary
gxChannel/gxSound: addedsetPan()(pure-virtual on the bases; the only implementers areSampleChannel/StreamChannelandgxSoundSample/gxSoundStream— no macOS audio backend exists, so no stub needed).pan∈[-1,1],AL_SOURCE_RELATIVE=AL_TRUE,alSource3f(AL_POSITION, pan, 0, -sqrt(1-pan²)). Mutually exclusive withset3d(last-call-wins, matching legacy pan/3D semantics).play()(soSoundPansets the default for subsequently-played channels).bbaudio: re-enabledbbSoundPan(debugSound-guarded) andbbChannelPan(verifyChannel-guarded, matching sibling channel commands) + theirrtSymregistrations, using the typed(BBSound)/(BBChannel)signatures.No compiler/codegen/front-end change. Windows OpenAL backend only.
Acceptance criteria + results
SoundPan/ChannelPanregistered.spider.bbnow compiles → removed fromscripts/corpus_compile_allowlist.txt; corpus sweep green.aristoids.bb's SoundPan blocker is resolved but it also usesPlayMusic(a separate, still-disabled builtin), so it stays allowlisted with its reason updated to PlayMusic.tests/AudioPanTest.bbpasses underblitzcc -t: the commands resolve and tolerate a Null sound/channel (incl. an out-of-range pan value) without crashing — headless-safe (no audio device in CI).test.batgreen; corpus sweep green.Trade-offs, deferred follow-ups
gxSoundSample::loadshort-filename crash —LoadSound("abc")→substr(filename.size()-4)underflows →std::out_of_range→ process kill. One-line guard atgxsound.cpp:25.PlayMusic/CreateListener/Load3DSound/StartNetGame); linkerloadImagehardening; TCP-socket UAF; GCreference_mapsoundness; contextual-keyword Phase 2; the manual audible-pan listen.🤖 Generated with Claude Code