63 lines
3.0 KiB
Markdown
63 lines
3.0 KiB
Markdown
---
|
|
name: audio_play
|
|
kind: function
|
|
lang: cpp
|
|
domain: gamedev
|
|
version: "0.1.0"
|
|
purity: impure
|
|
signature: "sound_load(Engine&, const char*) -> Sound; sound_play/stop/set_volume/destroy(Sound&); play_sound_oneshot(Engine&, const char*, float)"
|
|
description: "Reproduccion de audio sobre fn::audio::Engine: carga sonidos con streaming desde disco (wav/mp3/flac/ogg), play/stop/volumen por sonido, y helper fire-and-forget para one-shots sin handle. Cross-platform via miniaudio. Issue 0072b — runtime gamedev nucleo."
|
|
tags: [gamedev, audio, miniaudio]
|
|
uses_functions: ["audio_engine_cpp_gamedev"]
|
|
uses_types: []
|
|
returns: []
|
|
returns_optional: false
|
|
error_type: "error_go_core"
|
|
imports: []
|
|
example: |
|
|
fn::audio::Engine eng = fn::audio::engine_init();
|
|
fn::audio::Sound bgm = fn::audio::sound_load(eng, "assets/bgm.ogg");
|
|
fn::audio::sound_set_volume(bgm, 0.5f);
|
|
fn::audio::sound_play(bgm);
|
|
// SFX one-shot:
|
|
fn::audio::play_sound_oneshot(eng, "assets/jump.wav");
|
|
// ...
|
|
fn::audio::sound_destroy(bgm);
|
|
fn::audio::engine_shutdown(eng);
|
|
tested: false
|
|
tests: []
|
|
test_file_path: ""
|
|
file_path: "cpp/functions/gamedev/audio_play.cpp"
|
|
params:
|
|
- name: e
|
|
desc: "Engine inicializado por audio_engine_cpp_gamedev. Si e.ok=false, todas las operaciones son no-op."
|
|
- name: path
|
|
desc: "Ruta al archivo de audio (relativa al cwd o absoluta). Formatos: wav/mp3/flac/ogg via decoders integrados de miniaudio."
|
|
- name: s
|
|
desc: "Sound handle. ok=true tras sound_load exitoso. Operaciones tras destroy son no-op."
|
|
- name: v
|
|
desc: "Volumen 0..1 lineal, multiplicativo con el master del Engine."
|
|
- name: volume
|
|
desc: "Volumen sugerido para play_sound_oneshot (actualmente delega al master via ma_engine_play_sound; reservado para futura implementacion per-instance)."
|
|
output: "Sound con impl=ma_sound* y ok=true en sound_load exitoso; ok=false ante cualquier fallo (engine no listo, malloc, decoder). play_sound_oneshot no devuelve handle — el sonido se gestiona internamente por el engine."
|
|
---
|
|
|
|
# audio_play
|
|
|
|
Reproduccion de audio one-shot y streaming sobre `fn::audio::Engine`. Wrapper minimo de la API `ma_sound` de miniaudio.
|
|
|
|
## Estructura `Sound`
|
|
|
|
Handle opaco con `impl` (apunta a `ma_sound`) y `ok` (bool). Gestion explicita: cada `sound_load` requiere `sound_destroy` para liberar (no hay RAII porque mantenemos `-fno-exceptions` y compat con structs trivial).
|
|
|
|
## Patrones de uso
|
|
|
|
- **BGM / loops largos:** `sound_load` + `sound_play`. Por defecto miniaudio hace streaming desde disco (no carga todo a memoria).
|
|
- **SFX cortos:** `play_sound_oneshot` — fire-and-forget, sin handle, ideal para clicks, jumps, hits.
|
|
- **SFX repetidos con control:** `sound_load` + `sound_play` cada vez. Para concurrent voices del mismo sample, considerar `ma_sound_init_copy` (no expuesto aun).
|
|
|
|
## Notas
|
|
|
|
- `play_sound_oneshot` recibe `volume` como hint pero actualmente delega al master del engine. Iterar si el caller real lo necesita.
|
|
- `sound_load` con `path=NULL` o engine no listo devuelve `Sound{nullptr, false}` — siempre comprobar `ok` antes de operar.
|