swgysnd.3

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
.Dd $Mdocdate: December 25, 2024 $
.Dt SWGYSND 3
.Os
.Sh NAME
.Nm swgysnd_version_str ,
.Nm swgysnd_init ,
.Nm swgysnd_loadwav ,
.Nm swgysnd_freewav ,
.Nm swgysnd_playwav ,
.Nm swgysnd_shutdown
.Nd load and play WAV sounds with stereo panning
.Sh LIBRARY
.Lb libswgysnd
.Sh SYNOPSIS
.In swgysnd.h
.Ft const char *
.Fn swgysnd_version_str void
.Ft int
.Fn swgysnd_init void
.Ft int
.Fn swgysnd_loadwav "const char *path" "int *handle_out"
.Ft int
.Fn swgysnd_freewav "int handle"
.Ft int
.Fn swgysnd_playwav "int handle" "double balance"
.Ft int
.Fn swgysnd_shutdown void
.Sh DESCRIPTION
The
.Nm swgysnd
library wraps
.Xr SDL2 3
audio to load WAV files and play them with stereo panning.
Multiple sounds are mixed together in software and played through a single
audio device.
.Pp
The
.Fn swgysnd_version_str
function returns a static, NUL-terminated string describing the library
version.
The returned pointer must not be modified or freed.
.Pp
The
.Fn swgysnd_init
function initializes the library and the underlying SDL audio subsystem.
It must be called before any other function.
.Pp
The
.Fn swgysnd_loadwav
function loads the WAV file at
.Fa path
and stores a handle for it in the integer pointed to by
.Fa handle_out .
The handle is later passed to
.Fn swgysnd_playwav
and
.Fn swgysnd_freewav .
The sample is converted to signed 16-bit stereo on load.
The first successful call also opens and starts the audio device, using the
sample rate of that file; therefore at least one
.Fn swgysnd_loadwav
call must succeed before
.Fn swgysnd_playwav
may be used.
At most 128 WAVs may be loaded at once.
.Pp
The
.Fn swgysnd_freewav
function releases the resources associated with
.Fa handle ,
freeing its slot for reuse.
.Pp
The
.Fn swgysnd_playwav
function begins playback of the WAV referenced by
.Fa handle .
The
.Fa balance
argument controls the left-right balance: a value of
.Ar 0
is centered,
.Ar -1
is full left, and
.Ar 1
is full right.
Values outside this range are clamped to
.Ar -1
or
.Ar 1 .
Each call occupies one of eight playback channels; the sound plays to
completion and then frees its channel.
A WAV may be played on several channels simultaneously.
.Pp
The
.Fn swgysnd_shutdown
function stops all playback, frees every loaded WAV, closes the audio
device, and shuts down the SDL audio subsystem.
.Sh RETURN VALUES
.Fn swgysnd_version_str
returns a pointer to the version string and cannot fail.
.Pp
.Fn swgysnd_init ,
.Fn swgysnd_freewav ,
.Fn swgysnd_playwav ,
and
.Fn swgysnd_shutdown
return 0 on success and \-1 on failure.
.Pp
.Fn swgysnd_loadwav
returns 0 on success.
On failure it returns a positive value for most errors, or \-1 if the audio
device could not be opened; in either error case the value written to
.Fa handle_out
is unusable.
.Sh DIAGNOSTICS
Diagnostic messages are written to standard error.
The amount of output is controlled by the global
.Va verbose
variable, an
.Vt int
that the program linking the library is expected to define; higher values
produce more detail.
.Sh AUTHORS
.An Ron Dahlgren
.Aq Mt ron@sw.gy