{-|
ProteaAudio is a stereo audio mixer/playback library for

* Linux /(PusleAudio)/

* Macintosh OS X /(CoreAudio)/

* Windows /(DirectSound)/
-}
{-#LANGUAGE ForeignFunctionInterface#-}
#include "proteaaudio_binding.h"
module Sound.ProteaAudio (
    -- * Sample
    Sample(),

    -- * Audio System Setup
    initAudio,
    finishAudio,

    -- * Main Mixer
    volume,
    soundActive,
    soundStopAll,

    -- * Sample Loading
    loaderAvailable,
    sampleFromMemoryWav,
    sampleFromMemoryOgg,
    sampleFromFile,

    -- * Sample Palyback
    soundLoop,
    soundPlay,
    soundUpdate,
    soundStop
 ) where

import Foreign
import Foreign.C
import Data.ByteString (ByteString, useAsCStringLen)

-- | Audio sample handle
newtype Sample = Sample{ fromSample :: {#type sample_t#} }


-- | Initializes the audio system.
{#fun initAudio 
    { `Int' -- ^ the maximum number of sounds that are played parallely. Computation time is linearly correlated to this factor.
    , `Int' -- ^ sample frequency of the playback in Hz. 22050 corresponds to FM radio 44100 is CD quality. Computation time is linearly correlated to this factor.
    , `Int' -- ^ the number of bytes that are sent to the sound card at once. Low numbers lead to smaller latencies but need more computation time (thread switches). If a too small number is chosen, the sounds might not be played continuously. The default value 512 guarantees a good latency below 40 ms at 22050 Hz sample frequency.
    } -> `Bool' -- ^ returns True on success
#}

-- *

-- | Releases the audio device and cleans up resources.
{#fun finishAudio {} -> `()'#}

-- | Checks if loader for this file type is available.
{#fun loaderAvailable
  { `String' -- ^ file extension (e.g. ogg)
  } -> `Bool'
#}


-- | Loads wav sound sample from memory buffer.
{#fun _sampleFromMemoryWav
  { id `Ptr CChar' -- ^ memory buffer pointer
  , `Int' -- ^ memory buffer size in bytes
  , `Float' -- ^ volume
  } -> `Sample' Sample -- ^ returns handle
#}

-- | Loads ogg sound sample from memory buffer.
{#fun _sampleFromMemoryOgg
  { id `Ptr CChar' -- ^ memory buffer pointer
  , `Int' -- ^ memory buffer size in bytes
  , `Float' -- ^ volume
  } -> `Sample' Sample -- ^ returns handle
#}

-- | Loads wav sound sample from memory buffer.
sampleFromMemoryWav :: ByteString -- ^ wav sample data
                    -> Float -- ^ volume
                    -> IO Sample -- ^ return sample handle
sampleFromMemoryWav wavData volume = useAsCStringLen wavData $ \(ptr, size) -> _sampleFromMemoryWav ptr size volume

-- | Loads ogg sound sample from memory buffer.
sampleFromMemoryOgg :: ByteString -- ^ ogg sample data
                    -> Float -- ^ volume
                    -> IO Sample -- ^ return sample handle
sampleFromMemoryOgg oggData volume = useAsCStringLen oggData $ \(ptr, size) -> _sampleFromMemoryOgg ptr size volume

-- | Loads a sound sample from file.
{#fun sampleFromFile
  { `String' -- ^ sample filepath
  , `Float' -- ^ volume
  } -> `Sample' Sample -- ^ returns handle
#}

-- | Set main mixer volume.
{#fun volume
  { `Float' -- ^ left
  , `Float' -- ^ right
  } -> `()'
#}

-- | Return the number of currently active sounds.
{#fun soundActive {} -> `Int'#}

-- | Stops all sounds immediately.
{#fun soundStopAll {} -> `()'#}

-- | Plays a specified sound sample continuously and sets its parameters.
{#fun soundLoop
  { fromSample `Sample' -- ^ handle of a previously loaded sample
  , `Float' -- ^ left volume
  , `Float' -- ^ right volume
  , `Float' -- ^ time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right
  , `Float' -- ^ pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample
  } -> `()'
#}

-- | Plays a specified sound sample once and sets its parameters.
{#fun soundPlay
  { fromSample `Sample' -- ^ handle of a previously loaded sample
  , `Float' -- ^ left volume
  , `Float' -- ^ right volume
  , `Float' -- ^ time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right
  , `Float' -- ^ pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample
  } -> `()'
#}

-- | Updates parameters of a specified sound.
{#fun soundUpdate
  { fromSample `Sample' -- ^ handle of a currently active sound
  , `Float' -- ^ left volume
  , `Float' -- ^ right volume
  , `Float' -- ^ time difference between left and right channel in seconds. Use negative values to specify a delay for the left channel, positive for the right
  , `Float' -- ^ pitch factor for playback. 0.5 corresponds to one octave below, 2.0 to one above the original sample
  } -> `Bool' -- ^ return True in case the parameters have been updated successfully
#}

-- | Stops a specified sound immediately.
{#fun soundStop {fromSample `Sample'} -> `Bool'#}