/*
  Copyright (c) 2019 Alex Diener
  
  This software is provided 'as-is', without any express or implied
  warranty. In no event will the authors be held liable for any damages
  arising from the use of this software.
  
  Permission is granted to anyone to use this software for any purpose,
  including commercial applications, and to alter it and redistribute it
  freely, subject to the following restrictions:
  
  1. The origin of this software must not be misrepresented; you must not
     claim that you wrote the original software. If you use this software
     in a product, an acknowledgment in the product documentation would be
     appreciated but is not required.
  2. Altered source versions must be plainly marked as such, and must not be
     misrepresented as being the original software.
  3. This notice may not be removed or altered from any source distribution.
  
  Alex Diener alex@ludobloom.com
*/

#ifndef __AudioOut_H__
#define __AudioOut_H__
#ifdef __cplusplus
extern "C" {
#endif

#include <stdbool.h>
#include <stdint.h>

// Use frameCount for timing, and keep track yourself. Use a 64-bit integer to track accumulated frame time if it needs to be able to go for over 27 hours.
typedef void (* AudioOutCallback)(void * outSamples, unsigned int frameCount, void * context);

// 1, 2, or 3 bytes per sample = integer, 4 bytes = float
typedef struct AudioOut_sampleFormat {
	unsigned int channelCount;
	unsigned int sampleRate;
	unsigned int bytesPerSample;
} AudioOut_sampleFormat;

// Call to initialize audio output before calling other AudioOut functions other than AudioOut_setHostFormat() and
// AudioOut_setFileOutput(). If the host API (such as pulseaudio) supports it, processName will be used to identify
// the running application in any system audio mixer that can show processes by name.
void AudioOut_init(const char * processName);

// Explicitly tears down anything initialized by AudioOut_init(). May be advisable to call on clean exit for some
// host APIs.
void AudioOut_shutdown(void);

// Returns sample format used by host API. Return value is not affected by AudioOut_setTransportFormat().
AudioOut_sampleFormat AudioOut_getHostFormat(void);

// Sets a sample format to be used by the host API. Can be called before AudioOut_init() to specify the format to
// initially request. Calling after AudioOut_init() will reinitialize the host API with the new format, if
// possible. Not all formats will be accepted by all host APIs; call AudioOut_getHostFormat() after calling this
// function (and after AudioOut_init() if it was called before) to retrieve the actual values used.
void AudioOut_setHostFormat(AudioOut_sampleFormat format);

// Returns sample format used by AudioOutCallback. If different from the host format, AudioOut will automatically
// translate between formats at a relatively small performance cost. On initialization, this will match the return
// value of AudioOut_getHostFormat(). It's recommended to call AudioOut_setTransportFormat() to set this to a known
// value rather than try to handle all possible values of AudioOut_getHostFormat().
AudioOut_sampleFormat AudioOut_getTransportFormat(void);

// Sets format of sample data to be used by AudioOutCallback. If set to something different from host format, audio
// data will be converted in real time, which may impact performance and/or audio quality. If called while audio is
// playing, output may be interrupted for a short time.
void AudioOut_setTransportFormat(AudioOut_sampleFormat format);

// If set, audio data being sent to the speakers will also be written to the specified file path, in host format.
// Can be called before AudioOut_init().
void AudioOut_setFileOutput(const char * filePath);

// Activates audio output thread, causing the specified callback to be called periodically to provide linear PCM
// data to send to the speakers. The call interval is implementation-defined. The implementation of callback should
// not do any expensive operations, as it runs in real time to deliver data at low latency.
void AudioOut_startOutput(AudioOutCallback callback, void * context);

// Ceases audio output thread. The callback specified to AudioOut_startOutput will stop being called, and audio data
// will no longer be sent to the speakers.
void AudioOut_stopOutput(void);

#ifdef __cplusplus
}
#endif
#endif