<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=us-ascii">
<meta name=Generator content="Microsoft Word 12 (filtered medium)">
<style>
<!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri","sans-serif";}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
span.EmailStyle17
{mso-style-type:personal-compose;
font-family:"Calibri","sans-serif";
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;}
@page Section1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.Section1
{page:Section1;}
-->
</style>
<!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang=EN-US link=blue vlink=purple>
<div class=Section1>
<p class=MsoNormal>Hi,<o:p></o:p></p>
<p class=MsoNormal> A while ago the concept of a low-level pure
PCM-output library to facilitate porting to new platforms was proposed.
Enthusiastic for the concept, and having done some similar work earlier, I made
a header file with the proposed API, and I was wondering if anyone would like
to comment on it so far. I’m interested in hearing, and responding to,
any questions you might have. The proposed header is as follows:<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>//Copyright 2008 Sherief N. Farouk - sherief 'at' mganin
'dot' com<o:p></o:p></p>
<p class=MsoNormal>//This source code is released under the MIT license.<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>// The following ifdef block is the standard way of creating
macros which make exporting <o:p></o:p></p>
<p class=MsoNormal>// from a DLL simpler. All files within this DLL are
compiled with the PCMOUT_EXPORTS<o:p></o:p></p>
<p class=MsoNormal>// symbol defined on the command line. this symbol should
not be defined on any project<o:p></o:p></p>
<p class=MsoNormal>// that uses this DLL. This way any other project whose
source files include this file see <o:p></o:p></p>
<p class=MsoNormal>// PCMOUT_API functions as being imported from a DLL,
whereas this DLL sees symbols<o:p></o:p></p>
<p class=MsoNormal>// defined with this macro as being exported.<o:p></o:p></p>
<p class=MsoNormal>#ifdef PCMOUT_EXPORTS<o:p></o:p></p>
<p class=MsoNormal>#define PCMOUT_API __declspec(dllexport)<o:p></o:p></p>
<p class=MsoNormal>#else<o:p></o:p></p>
<p class=MsoNormal>#define PCMOUT_API __declspec(dllimport)<o:p></o:p></p>
<p class=MsoNormal>#endif<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>#ifdef __cplusplus<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>extern "C"<o:p></o:p></p>
<p class=MsoNormal>{<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>#endif<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Used to query a device capabilities<o:p></o:p></p>
<p class=MsoNormal>struct pcmout_device_info<o:p></o:p></p>
<p class=MsoNormal>{<o:p></o:p></p>
<p class=MsoNormal> ///Minimum number of channels supported by
this device<o:p></o:p></p>
<p class=MsoNormal> unsigned int channel_count_min;<o:p></o:p></p>
<p class=MsoNormal> ///Maximum number of channels supported by
this device<o:p></o:p></p>
<p class=MsoNormal> unsigned int channel_count_max;<o:p></o:p></p>
<p class=MsoNormal> ///Best number of channels to use with this
device<o:p></o:p></p>
<p class=MsoNormal> unsigned int channel_count_best;<o:p></o:p></p>
<p class=MsoNormal> //Minimum sample rate supported by this
device<o:p></o:p></p>
<p class=MsoNormal> unsigned int sample_rate_min;<o:p></o:p></p>
<p class=MsoNormal> //Maximum sample rate supported by this
device<o:p></o:p></p>
<p class=MsoNormal> unsigned int sample_rate_max;<o:p></o:p></p>
<p class=MsoNormal> ///Best sample rate to use with this device<o:p></o:p></p>
<p class=MsoNormal> unsigned int sample_rate_best;<o:p></o:p></p>
<p class=MsoNormal> ///The number of formats this device
supports<o:p></o:p></p>
<p class=MsoNormal> int supported_format_count;<o:p></o:p></p>
<p class=MsoNormal> ///An array of size supported_format_count,
each element being a format this device supports<o:p></o:p></p>
<p class=MsoNormal> int* supported_formats;<o:p></o:p></p>
<p class=MsoNormal> ///Minimum buffer size supported by this
device<o:p></o:p></p>
<p class=MsoNormal> unsigned int buffer_size_min;<o:p></o:p></p>
<p class=MsoNormal> ///Maximum buffer size supported by this
device<o:p></o:p></p>
<p class=MsoNormal> unsigned int buffer_size_max;<o:p></o:p></p>
<p class=MsoNormal> ///Best buffer size to use with this device<o:p></o:p></p>
<p class=MsoNormal> unsigned int buffer_size_best;<o:p></o:p></p>
<p class=MsoNormal> ///A mask that is bitwise AND-ed with the
any requested buffer size.<o:p></o:p></p>
<p class=MsoNormal> unsigned int buffer_size_mask;<o:p></o:p></p>
<p class=MsoNormal>};<o:p></o:p></p>
<p class=MsoNormal>//<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>//for C<o:p></o:p></p>
<p class=MsoNormal>typedef void* pcmout_device;<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Initializes the library. MUST BE CALLED before any other
functions.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int pcmout_initialize();<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Returns the number of available devices.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int pcmout_device_count();<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Returns the name of a device. <o:p></o:p></p>
<p class=MsoNormal>///\param DeviceNumber The requested device. Lies between
[0, device_count() - 1].<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API const char* const pcmout_device_name(const int
DeviceNumber);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Returns a pointer to the pcmout_device_info structure
corresponding to a device.<o:p></o:p></p>
<p class=MsoNormal>///\param DeviceNumber The requested device. Lies between
[0, device_count() - 1].<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API const pcmout_device_info* const
query_device_info(const int DeviceNumber);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Opens a requested device with the specified parameters.<o:p></o:p></p>
<p class=MsoNormal>///\param DeviceNumber The requested device. Lies between
[0, device_count() - 1].<o:p></o:p></p>
<p class=MsoNormal>///\param ChannelCount The requested number of channels.<o:p></o:p></p>
<p class=MsoNormal>///\param SampleRate The requested sample rate in Hz.<o:p></o:p></p>
<p class=MsoNormal>///\param SampleFormat The requested sample format.<o:p></o:p></p>
<p class=MsoNormal>///\param BufferSizeInBytes The requested buffer size in
bytes.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API pcmout_device pcmout_open_device(const int
DeviceNumber, <o:p></o:p></p>
<p class=MsoNormal> const
int ChannelCount, <o:p></o:p></p>
<p class=MsoNormal> const
int SampleRate, <o:p></o:p></p>
<p class=MsoNormal> const
int SampleFormat, <o:p></o:p></p>
<p class=MsoNormal> const
int BufferSizeInBytes);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>//Experimental<o:p></o:p></p>
<p class=MsoNormal>///Write to a specific channel in a device<o:p></o:p></p>
<p class=MsoNormal>///\param Device The requested device.<o:p></o:p></p>
<p class=MsoNormal>///\param Channel The target channel.<o:p></o:p></p>
<p class=MsoNormal>///\param Data A pointer to the beginning of the data block.<o:p></o:p></p>
<p class=MsoNormal>///\param ElementSize The size of each data element to copy,
in bytes.<o:p></o:p></p>
<p class=MsoNormal>///\param SampleCount The number of data samples to copy.<o:p></o:p></p>
<p class=MsoNormal>///\param Stride The spacing between each element and the
other.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int pcmout_write_channel(pcmout_device Device, <o:p></o:p></p>
<p class=MsoNormal> const
unsigned int Channel, <o:p></o:p></p>
<p class=MsoNormal> const
void* Data, <o:p></o:p></p>
<p class=MsoNormal> //const
unsigned int ElementSize, //Deduced from device and channel properties.<o:p></o:p></p>
<p class=MsoNormal> const
unsigned int SampleCount,<o:p></o:p></p>
<p class=MsoNormal> const
unsigned int Stride);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Similar to performing ChannelCount calls to
pcmout_write_channel, each with Channels[i], Data[i], ElementSize[i],
SampleCount[i] and Stride[i].<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int pcmout_write_channels(pcmout_device Device, <o:p></o:p></p>
<p class=MsoNormal> const
unsigned int ChannelCount, <o:p></o:p></p>
<p class=MsoNormal> const
unsigned int* Channels, <o:p></o:p></p>
<p class=MsoNormal> const
void** Data, <o:p></o:p></p>
<p class=MsoNormal> //const
unsigned int* ElementSize, //Deduced from device and channel properties.<o:p></o:p></p>
<p class=MsoNormal> const
unsigned int* SampleCount,<o:p></o:p></p>
<p class=MsoNormal> const
unsigned int* Stride);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Writes an interleaved buffer to all the channels in the
device, in increasing order.<o:p></o:p></p>
<p class=MsoNormal>///[This needs a better writeup.]<o:p></o:p></p>
<p class=MsoNormal>///Requires (Size / SampleSize) % ChannelCount == 0.
Otherwise results are undefined.<o:p></o:p></p>
<p class=MsoNormal>///\param Device The requested device.<o:p></o:p></p>
<p class=MsoNormal>///\param Data A pointer to the beginning of the data block.<o:p></o:p></p>
<p class=MsoNormal>///\param Size Size of the data, in bytes.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int
pcmout_write_channels_interleaved(pcmout_device Device, <o:p></o:p></p>
<p class=MsoNormal> const
void* Data, <o:p></o:p></p>
<p class=MsoNormal> const
unsigned int Size);<o:p></o:p></p>
<p class=MsoNormal>//End experimental<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Closes a specified device.<o:p></o:p></p>
<p class=MsoNormal>///\param Device The desired device. Must've been opened via
a call to pcmout_open_device() and not closed since.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API int pcmout_close_device(pcmout_device Device);<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>///Uninitializes the library and provides cleanup services.
No further calls can be made after calling uninitialize.<o:p></o:p></p>
<p class=MsoNormal>PCMOUT_API void pcmout_uninitialize();<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>#ifdef __cplusplus<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>} //extern "C"<o:p></o:p></p>
<p class=MsoNormal><o:p> </o:p></p>
<p class=MsoNormal>#endif<o:p></o:p></p>
</div>
</body>
</html>