lib/sdl2/mixer.nit

   1 # This file is part of NIT ( http://www.nitlanguage.org ).
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #     http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 # SDL2 mixer with sample/sounds and music
  16 #
  17 # C API documentation: https://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer.html
  18 module mixer is pkgconfig "SDL2_mixer"
  19
  20 import sdl2_base
  21
  22 `{
  23         #include "SDL2/SDL_mixer.h"
  24 `}
  25
  26 redef class Sys
  27         # SDL2 mixer services
  28         var mix = new Mix is lazy
  29 end
  30
  31 # SDL2 mixer services
  32 class Mix
  33         # Initialize supports for loading formats in `flags`
  34         #
  35         # Returns the initialized supports.
  36         fun initialize(flags: MixInitFlags): MixInitFlags `{
  37                 return Mix_Init(flags);
  38         `}
  39
  40         # FLAC format support, for `initialize`
  41         fun flac: MixInitFlags `{ return MIX_INIT_FLAC; `}
  42
  43         # MOD format support, for `initialize`
  44         fun mod: MixInitFlags `{ return MIX_INIT_MOD; `}
  45
  46         # MP3 format support, for `initialize`
  47         fun mp3: MixInitFlags `{ return MIX_INIT_MP3; `}
  48
  49         # OGG format support, for `initialize`
  50         fun ogg: MixInitFlags `{ return MIX_INIT_OGG; `}
  51
  52         # Clean up all dynamically loaded library handles
  53         #
  54         # May be called after loading all the sounds.
  55         fun quit `{ Mix_Quit(); `}
  56
  57         # Initialize and configure the mixer API
  58         #
  59         # Playback is configured with:
  60         # * The output sample `frequency`, in samples per second (Hz).
  61         # * The output sample `format`, may be `mix_default_format`.
  62         # * The number of sound `channels`, 1 for mono or 2 for stereo.
  63         # * The number of bytes used by output sample size as `chunk_size`.
  64         fun open_audio(frequency: Int, format: MixFormat, channels, chunk_size: Int): Bool `{
  65                 return Mix_OpenAudio(frequency, format, channels, chunk_size) == 0;
  66         `}
  67
  68         # Default frequency for `open_audio` (22050)
  69         fun default_frequency: Int `{ return MIX_DEFAULT_FREQUENCY; `}
  70
  71         # Default format for `open_audio`
  72         fun default_format: MixFormat `{ return MIX_DEFAULT_FORMAT; `}
  73         # TODO other formats: AUDIO_U8, AUDIO_S8, etc.
  74
  75         # Shutdown and cleanup the mixer API
  76         fun close_audio `{ Mix_CloseAudio(); `}
  77
  78         # Last error produced by the mixer API
  79         fun error: CString `{ return (char*)Mix_GetError(); `}
  80
  81         # ---
  82         # Chunks/sounds
  83
  84         # Load `file` for use as a sample
  85         #
  86         # Returns a null pointer on error.
  87         #
  88         # Can load WAVE, AIFF, RIFF, OGG and VOC files.
  89         fun load_wav(file: CString): MixChunk `{ return Mix_LoadWAV(file); `}
  90
  91         # Play `chunk` on `channel`
  92         #
  93         # If `channel == -1` the first unreserved channel is used.
  94         # The sound is repeated `loops` times, `loops == 0` plays it once,
  95         # `loops == 1` plays it twice and `loops == -1` loops infinitely.
  96         #
  97         # Returns the channel used, or `-1` on error.
  98         fun play_channel(channel: Int, chunk: MixChunk, loops: Int): Int `{
  99                 return Mix_PlayChannel(channel, chunk, loops);
 100         `}
 101
 102         # Play `chunk` on `channel`
 103         #
 104         # If `channel == -1` the first unreserved channel is used.
 105         # The sound is repeated `loops` times, `loops == 0` plays it once,
 106         # `loops == 1` plays it twice and `loops == -1` loops infinitely.
 107         # If `ticks != -1`, the sample plays for at most `ticks` milliseconds.
 108         fun play_channel_timed(channel: Int, chunk: MixChunk, loops, ticks: Int): Int `{
 109                 return Mix_PlayChannelTimed(channel, chunk, loops, ticks);
 110         `}
 111
 112         # Halt/stop `channel` playback
 113         #
 114         # If `channel == -1`, halt all channels.
 115         fun halt_channel(channel: Int) `{
 116                 Mix_HaltChannel(channel);
 117         `}
 118
 119         # Halt `channel` in `ticks` milliseconds and return the number of channels set to expire
 120         #
 121         # If `channel == -1`, halt all channels.
 122         fun expire_channel(channel, ticks: Int): Int `{
 123                 return Mix_ExpireChannel(channel, ticks);
 124         `}
 125
 126         # Reserve `num` channels from being used by `play_channel(-1...)`
 127         #
 128         # Returns the number of of channels reserved.
 129         fun reserve_channels(num: Int): Int `{
 130                 return Mix_ReserveChannels(num);
 131         `}
 132
 133         # Set the `volume` of `channel`, out of `mix.max_volume`
 134         #
 135         # If `channel == -1`, set the volume of all channels.
 136         #
 137         # Returns the current volume of the channel, or if `channel == -1` the average volume.
 138         fun volume(channel, volume: Int): Int `{
 139                 return Mix_Volume(channel, volume);
 140         `}
 141
 142         # Set the `volume` for `chunk`, out of `mix.max_volume`
 143         #
 144         # If `volume == -1`, only read the previous value.
 145         #
 146         # Returns the previous volume value.
 147         fun volume_chunk(chunk: MixChunk, volume: Int) `{
 148                 Mix_VolumeChunk(chunk, volume);
 149         `}
 150
 151         # Pause `channel`, or all playing channels if -1
 152         fun pause(channel: Int) `{
 153                 Mix_Pause(channel);
 154         `}
 155
 156         # Unpause `channel`, or all paused channels if -1
 157         fun resume(channel: Int) `{
 158                 Mix_Resume(channel);
 159         `}
 160
 161         # ---
 162         # Music
 163
 164         # Load music from `file`
 165         #
 166         # Returns a null pointer on error.
 167         #
 168         # WAVE, MOD, MIDI, OGG, MP3, FLAC VOC files
 169         fun load_mus(file: CString): MixMusic `{ return Mix_LoadMUS(file); `}
 170
 171         # Play `music` `loops` times
 172         #
 173         # The music is plays once if `loops == 1` and repeats infinitely if `loops == -1`.
 174         fun play_music(music: MixMusic, loops: Int): Bool `{
 175                 return Mix_PlayMusic(music, loops) == 0;
 176         `}
 177
 178         # Pause music playback
 179         fun pause_music `{ Mix_PauseMusic(); `}
 180
 181         # Resume music playback
 182         fun resume_music `{ Mix_ResumeMusic(); `}
 183
 184         # Set the music volume out of `mix.max_volume` and return the previous value
 185         #
 186         # Use `volume = -1` to only read the previous value.
 187         fun volume_music(volume: Int): Int `{
 188                 return Mix_VolumeMusic(volume);
 189         `}
 190
 191         # Maximum volume value for `volume_music` and `volume_chunk`
 192         fun max_volume: Int `{ return MIX_MAX_VOLUME; `}
 193 end
 194
 195 # Chunk/sound handle, loaded by `mix.load_wav`
 196 extern class MixChunk
 197         redef fun free `{ Mix_FreeChunk(self); `}
 198 end
 199
 200 # Music handle, loaded by `mix.load_mus`
 201 extern class MixMusic
 202         redef fun free `{ Mix_FreeMusic(self); `}
 203 end
 204
 205 # ---
 206 # Flags & enums
 207
 208 # Flags for `mix.initialize`
 209 extern class MixInitFlags `{ int `}
 210
 211         # Binary OR
 212         fun | (other: MixInitFlags): MixInitFlags `{ return self | other; `}
 213
 214         private fun to_i: Int `{ return self; `}
 215
 216         redef fun ==(o) do return o isa MixInitFlags and o.to_i == to_i
 217 end
 218
 219 # Sample format for `mix.open_audio`
 220 extern class MixFormat `{ int `}
 221 end