[Openal-devel] A low-level pcmout library proposal

[Sherief N. Farouk]

Hi,

                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:

 

//Copyright 2008 Sherief N. Farouk - sherief 'at' mganin 'dot' com

//This source code is released under the MIT license.

 

// The following ifdef block is the standard way of creating macros which
make exporting 

// from a DLL simpler. All files within this DLL are compiled with the
PCMOUT_EXPORTS

// symbol defined on the command line. this symbol should not be defined on
any project

// that uses this DLL. This way any other project whose source files include
this file see 

// PCMOUT_API functions as being imported from a DLL, whereas this DLL sees
symbols

// defined with this macro as being exported.

#ifdef PCMOUT_EXPORTS

#define PCMOUT_API __declspec(dllexport)

#else

#define PCMOUT_API __declspec(dllimport)

#endif

 

 

 

#ifdef __cplusplus

 

extern "C"

{

 

#endif

 

///Used to query a device capabilities

struct pcmout_device_info

{

                ///Minimum number of channels supported by this device

                unsigned int channel_count_min;

                ///Maximum number of channels supported by this device

                unsigned int channel_count_max;

                ///Best number of channels to use with this device

                unsigned int channel_count_best;

                //Minimum sample rate supported by this device

                unsigned int sample_rate_min;

                //Maximum sample rate supported by this device

                unsigned int sample_rate_max;

                ///Best sample rate to use with this device

                unsigned int sample_rate_best;

                ///The number of formats this device supports

                int supported_format_count;

                ///An array of size supported_format_count, each element
being a format this device supports

                int* supported_formats;

                ///Minimum buffer size supported by this device

                unsigned int buffer_size_min;

                ///Maximum buffer size supported by this device

                unsigned int buffer_size_max;

                ///Best buffer size to use with this device

                unsigned int buffer_size_best;

                ///A mask that is bitwise AND-ed with the any requested
buffer size.

                unsigned int buffer_size_mask;

};

//

 

//for C

typedef void* pcmout_device;

 

///Initializes the library. MUST BE CALLED before any other functions.

PCMOUT_API int pcmout_initialize();

 

///Returns the number of available devices.

PCMOUT_API int pcmout_device_count();

 

///Returns the name of a device. 

///\param DeviceNumber The requested device. Lies between [0, device_count()
- 1].

PCMOUT_API const char* const pcmout_device_name(const int DeviceNumber);

 

///Returns a pointer to the pcmout_device_info structure corresponding to a
device.

///\param DeviceNumber The requested device. Lies between [0, device_count()
- 1].

PCMOUT_API const pcmout_device_info* const query_device_info(const int
DeviceNumber);

 

///Opens a requested device with the specified parameters.

///\param DeviceNumber The requested device. Lies between [0, device_count()
- 1].

///\param ChannelCount The requested number of channels.

///\param SampleRate The requested sample rate in Hz.

///\param SampleFormat The requested sample format.

///\param BufferSizeInBytes The requested buffer size in bytes.

PCMOUT_API pcmout_device pcmout_open_device(const int DeviceNumber, 

 
const int ChannelCount, 

 
const int SampleRate, 

 
const int SampleFormat, 

 
const int BufferSizeInBytes);

 

 

//Experimental

///Write to a specific channel in a device

///\param Device The requested device.

///\param Channel The target channel.

///\param Data A pointer to the beginning of the data block.

///\param ElementSize The size of each data element to copy, in bytes.

///\param SampleCount The number of data samples to copy.

///\param Stride The spacing between each element and the other.

PCMOUT_API int pcmout_write_channel(pcmout_device Device, 

 
const unsigned int Channel, 

 
const void* Data, 

 
//const unsigned int ElementSize, //Deduced from device and channel
properties.

 
const unsigned int SampleCount,

 
const unsigned int Stride);

 

///Similar to performing ChannelCount calls to pcmout_write_channel, each
with Channels[i], Data[i], ElementSize[i], SampleCount[i] and Stride[i].

PCMOUT_API int pcmout_write_channels(pcmout_device Device, 

 
const unsigned int ChannelCount, 

 
const unsigned int* Channels, 

 
const void** Data, 

 
//const unsigned int* ElementSize, //Deduced from device and channel
properties.

 
const unsigned int* SampleCount,

 
const unsigned int* Stride);

 

///Writes an interleaved buffer to all the channels in the device, in
increasing order.

///[This needs a better writeup.]

///Requires (Size / SampleSize) % ChannelCount == 0. Otherwise results are
undefined.

///\param Device The requested device.

///\param Data A pointer to the beginning of the data block.

///\param Size Size of the data, in bytes.

PCMOUT_API int pcmout_write_channels_interleaved(pcmout_device Device, 

 
const void* Data, 

 
const unsigned int Size);

//End experimental

 

///Closes a specified device.

///\param Device The desired device. Must've been opened via a call to
pcmout_open_device() and not closed since.

PCMOUT_API int pcmout_close_device(pcmout_device Device);

 

///Uninitializes the library and provides cleanup services. No further calls
can be made after calling uninitialize.

PCMOUT_API void pcmout_uninitialize();

 

#ifdef __cplusplus

 

} //extern "C"

 

#endif

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://opensource.creative.com/pipermail/openal-devel/attachments/20080512/8157bab7/attachment-0001.html