XaudioPCMContext XaudioCreatePCMContext(Display *display, XaudioPCMDevice pcmdev);
void XaudioFreePCMContext(Display *display, XaudioPCMContext context);
int XaudioQueryChannelLayoutRange(Display *display, XaudioPCMContext context, unsigned int *nlayouts, unsigned int **layouts);
int XaudioQuerySampleRateRange(Display *display, XaudioPCMContext context, unsigned int *nrate_stops, unsigned int **rate_stops);
unsigned int XaudioQueryMinimumLatency(Display *display, XaudioPCMContext context);
unsigned int XaudioQueryMinimumTimeResolution(Display *display, XaudioPCMContext context);
void XaudioSetChannelLayout(Display *display, XaudioPCMContext context, unsigned int channel_layout);
void XaudioSetSampleRate(Display *display , XaudioPCMContext context, unsigned int sample_rate);
void XaudioSetLatency(Display *display, XaudioPCMContext context, unsigned int latency);
void XaudioSetTimeResolution(Display *display, XaudioPCMContext context, unsigned int time_resolution);
int XaudioGetPCMContextConfiguration(Display *display, XaudioPCMContext context, unsigned int *channel_layout, unsigned int *sample_rate, unsigned int *latency, unsigned int *time_resolution, XaudioSampleBuffer **buffers, unsigned int **positions);
void XaudioAssignChannel(Display *display, XaudioPCMContext context, unsigned int channel, XaudioSampleBuffer buffer, int index);
void XaudioStart(Display *display, XaudioPCMContext context, int start_time, int end_time);
void XaudioStop(Display *display, XaudioPCMContext context);
Before PCM contexts can be used for playback or capture of audio data they must be configured. The parameters that must be set are:
The XaudioQueryChannelLayoutRange will return a list of supported channel layouts in an malloc'd area (the caller is responsible for freeing the memory afterwards). Applications can configure a context for a specific channel layout through the XaudioSetChannelLayout function. Each channel layout is represented as a 32 bit integer, where the lower 8 bits always correspond to the number of channels. The following symbolic constants are predefined:
Applications should use the closest matching channel layout from the list of supported layouts.
The XaudioQuerySampleRatetRange will return the supported sample rate ranges in an malloc'd area (the caller is responsible for freeing the memory afterwards). Applications can configure a context for a sample rate through the XaudioSetSampleRate function. The sample rates returned by XaudioQuerySampleRatetRange are encoded in the following way:
Example: the set including the range 16000-48000 and the single value 96000 would be encoded as: 0x00003e80 0x8000bb80 0x0001770.
The XaudioQueryMinimumLatency function will return the minimum latency supported by the pcm context. Applications can configure a context for a specific latency through the XaudioSetLatency function. The latency is measured in terms of the sample rate. The exact interpretation depends on the type of context: For playback contexts the application must make sure that while the sample number n is playing, the sample numbered n+latency must already be available. For capture contexts the sample numbered n-latency is available for reading while the sample numbered n is being captured.
Applications have to schedule audio processing accordingly to take this latency into account.
The XaudioQueryMinimumTimeResolution function will return the minimum time resolution supported by the pcm context. Applications can configure a context for a specific time resolution through the XaudioSetTimeResolution function. The time resolution is measured in terms of the sample rate. Each pcm context can be used as a time source (see XtimeCreateScheduler(3) ), and the time resolution determines the temporal distance of ticks generated for this purpose. Applications must take the time resolution into account when scheduling operations (e.g. the validity interval of operations must not be shorter than the temporal distance of two ticks).
The XaudioAssignChannel function will assign a sample buffer to playback samples from/capture samples to. The index parameter identifies the first sample to read or write. The current position per channel will be updated as the PCM context progresses so that stopping and restarting a context will resume where it was stopped. Each individual channel used by a PCM context must individually be assigned a sample buffer (if no sample buffer is assigned then the channel is silenced), it is however permissible to assign the same sample buffer to multiple channels.
Reading samples from/writing samples to a sample buffer is subject to the access rules explained in XaudioSampleBuffer(3) - the base index of a sample buffer is not modified by the PCM context, it is the application's responsibility to update it in a timely fashion.
The XaudioGetPCMContextConfiguration returns the selected configuration of a pcm context. It may only be called after the context is fully configured. The function returns the sample buffer and index into the buffer for each channel as malloc'd arrays (the caller is responsible for freeing it afterwards). For channels were no buffer has been assigned zero is returned.
Applications can start playback or capture through the XaudioStart function. The start timestamp will be the initial time for the time source aspect of the pcm context (note that it does not in any way relate to the position within the sample buffers). Time will progress at the rate indicated by the sample rate. If the stop timestamp does not equal the start timestamp the context will implicitly stop at the given point in time.
Applications may stop playback or capture through the XaudioStop function.