Preparatori per COUP-01. No canvia comportament: només mou les
definicions inline de jail_audio.hpp a un jail_audio.cpp nou, deixant
el .hpp amb declaracions + tipus + constants.
Efectes col·laterals que es tanquen gratis:
- COUP-02: jail_audio deixa de ser header-only. Abans cada TU que
l'incloïa compilava 650 línies inline (amb stb_vorbis.c en mode
HEADER_ONLY). Ara el .hpp té ~130 línies de declaracions.
- PATCH-03: #include "external/stb_vorbis.c" + #undef L/C/R/PLAYBACK_*
viu només al final de jail_audio.cpp. audio.cpp perd el workaround
dels undefs.
Estat intern (current_music, channels[], audio_spec, music_volume,
sound_volume[], music_enabled, sound_enabled, sdl_audio_device,
outgoing_music, incoming_fade) baixa al .cpp dins d'un namespace
anònim (internal linkage). Els helpers privats (feedMusicChunk,
pumpMusic, preFillOutgoing, fadeProgress, update*Fade, updateCurrent*,
stealCurrentIntoOutgoing, forEachTargetChannel) també viuen a
l'anonymous namespace.
Ja::Music i Ja::Sound són públics; el .hpp forward-declara
`struct stb_vorbis` perquè els callers només els agafen per punter.
NOLINT(readability-identifier-naming) al forward-decl perquè el nom
l'imposa stb_vorbis.
jail_audio.cpp s'afegeix a APP_SOURCES al CMakeLists.txt.
.clang-tidy: desactivat clang-analyzer-core.UndefinedBinaryOperatorResult
globalment. Fals positiu conegut a external/stb_vorbis.c que abans no es
disparava (no hi havia TU que cridés directament stb_vorbis_seek_start
des del mateix fitxer on la funció està inlined); ara que jail_audio.cpp
sí que fa aquestes crides directes, el path d'anàlisi passa pel .c i el
check dispara. HeaderFilterRegex no aplica a clang-analyzer-*.
Preparació per COUP-01 (introduir Ja::Engine al commit següent).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Els comentaris d'audio.hpp i audio.cpp barrejaven castellà i català —
"Reproduce la música", "Detener", "Estado de la música"... conviven amb
"Reproduir", "Aturar", "Estat". Unifico tot a català, incloent-hi:
- Comentaris d'includes ("Para X" → "Per a X").
- Secció headers ("// --- Configuración general ---" → "// --- Configuració
general ---").
- Descripcions de mètodes i membres.
- Comentaris de l'enum Group/MusicState.
Els comentaris que ja estaven en català (els afegits a la mateixa
auditoria i els preexistents) no es toquen.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
jail_audio.hpp és un header inline que arrossegava <iostream> a cada
TU que l'incloïa, només per a std::cout de missatges d'error. <iostream>
és un include pesat i aquí no aporta res: estem fent logging simple.
Passem a <cstdio> + std::fprintf(stderr, ...) als dos fitxers (jail_audio
i audio.cpp). Missatges prefixats "Ja::funció:" / "Audio:" seguint la
convenció "Module: message" que ja fan servir director.cpp, options.cpp,
resource_cache.cpp, etc.
Efecte col·lateral: stderr és l'stream correcte per als errors (abans
anaven a stdout).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
L'overload playMusic(Ja::Music*, ...) buidava music_.name a cegues, així
que getCurrentMusicName() mentia després d'aquest camí tot i que el
Ja::Music que li passaves podia portar filename (Ja::loadMusic té un
overload que l'accepta).
Ara copiem music->filename — si el caller va usar l'overload amb
filename, el nom es conserva; si no, queda buit i el contracte és
explícit al comentari.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
music_.state era una cache d'estat que podia divergir del real —
precisament per això existia getRealMusicState() com a "consulta honesta".
Es descarta la cache:
- music_.state deixa d'existir; el struct privat Music només manté
name i loop.
- getMusicState() passa a ser static i consulta Ja::getMusicState(),
projectant INVALID/DISABLED al STOPPED que exposa Audio::MusicState.
- getRealMusicState() desapareix (getMusicState ja fa la consulta real).
- update() ja no necessita el bloc de sincronització.
- playMusicInternal/pauseMusic/resumeMusic/stopMusic/fadeOutMusic
llegeixen getMusicState() en comptes de music_.state i deixen de
reassignar-lo — Ja ja ho fa.
Externament: cap caller usa getMusicState/getRealMusicState, així que
canviar a static és segur (Audio::get()->getMusicState() continua
funcionant).
pauseMusic/resumeMusic/stopMusic es marquen amb NOLINT per
readability-make-member-function-const pel mateix motiu que INCONS-01
(muten globals de Ja::* que clang-tidy no veu).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
playSound (x2), stopAllSounds, fadeOutMusic, setSoundVolume i
setMusicVolume es declaraven const però mutaven l'estat global de Ja::*
(channels[], outgoing_music, music_volume, sound_volume[]). El const no
protegia res: el compilador no detectava les mutacions perquè anaven a
globals, no a membres, i podia induir a error a qui llegia el header.
Els callers externs van via Audio* (no Audio const*), així que el canvi
és source-compatible.
Clang-tidy falla amb readability-make-member-function-const perquè
tampoc veu la mutació — és exactament el símptoma que motiva el
hallazgo. S'afegeix NOLINT localitzat a cada mètode amb la raó. Quan
s'executi COUP-01 (encapsular Ja::* en classe membre) els NOLINT
cauran sols perquè la mutació serà visible al compilador.
effectiveVolume es queda const — és un càlcul pur sobre els membres.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
setSoundVolume i setMusicVolume repetien la mateixa lògica de clamp +
gate (enabled_ && channel_enabled_) + multiplicació pel master
config_.volume. S'extreu effectiveVolume(volume, channel_enabled) privat
i els dos setters es limiten a la crida Ja::*.
Any canvi futur a la política (p.ex. una corba logarítmica) queda en un
sol lloc.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Els dos playMusic compartien el dispatch crossfade-vs-stop+play i
l'actualització de music_.state/loop. S'extreu playMusicInternal privat
que rep el Ja::Music* ja resolt i fa el camí comú.
Cada overload es queda només amb el seu gating propi: la variant per
nom fa early-return si ja sona la mateixa pista i posa music_.name; la
variant per punter buida el nom (PATCH-02 recuperarà el filename del
propi Ja::Music).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Abans, toggleEnabled/toggleSound/toggleMusic i les variants sense bool
només flipaven el flag intern; els canals actius no notaven el canvi
fins a la pròxima crida explícita a setSoundVolume/setMusicVolume —
silenciós i fàcil de perdre.
Ara:
- toggleEnabled passa per enable(bool), que ja reaplicava els volums.
- enableSound(bool) i enableMusic(bool) es mouen a audio.cpp i
reapliquen el volum gated cap a Ja::*.
- Les variants enableSound()/disableSound()/enableMusic()/disableMusic()
i els toggles passen per aquestes dues funcions, així que qualsevol
camí d'activació produeix el mateix efecte sobre l'estat sonor.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ja::MAX_SIMULTANEOUS_CHANNELS i Ja::MAX_GROUPS són límits interns del
motor. La proposta inicial era moure'ls a Defaults::Audio, però jail_audio
és reutilitzable entre projectes (no depèn d'Options ni d'utils/); moure
els límits trencaria aquesta independència.
El valor real del hallazgo era la invariant Audio::Group ↔ MAX_GROUPS,
que cap codi protegia. S'afegeix un static_assert a audio.cpp que falla
en compilació si s'afegeix una entrada nova a Group sense tocar
MAX_GROUPS.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
{SDL_AUDIO_S16, 2, 48000} apareixia com a literal a tres llocs de
jail_audio (Sound/Music/audio_spec) i audio.cpp:208 passava SDL_AUDIO_S16LE
i 2 canals per separat — dues convencions de format conviuen i els 2
canals eren número màgic.
Defaults::Audio guanya FORMAT (SDL_AUDIO_S16) i CHANNELS (2). Audio::
initSDLAudio passa ambdós junts a Ja::init. jail_audio obté un fallback
local Ja::DEFAULT_SPEC que consolida les tres instàncies; es queda
independent del projecte (no inclou utils/defaults.hpp) perquè l'engine
és reutilitzable.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
VOLUME_STEP, FREQUENCY i DEFAULT_CROSSFADE_MS vivien com a membres
constexpr d'Audio. Eren valors de configuració — no invariants de la
classe — i la convenció del projecte és que tots els paràmetres
ajustables visquin a utils/defaults.hpp.
Passen a Defaults::Audio::{VOLUME_STEP, FREQUENCY, CROSSFADE_MS}. L'únic
ús intern (Ja::init al constructor d'Audio) es reapunta al Defaults. Cap
ús extern dels tres símbols.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
JailDesignerandClaude Opus 4.7