pdmaudioifs.h@ 68077

Last change on this file since 68077 was 68077, checked in by vboxsync, 8 years ago
vmm/pdmaudioifs.h: Documentation.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 48.5 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2017 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_vmm_pdmaudioifs_h
27	#define ___VBox_vmm_pdmaudioifs_h
28
29	#include <iprt/circbuf.h>
30	#include <iprt/list.h>
31
32	#include <VBox/types.h>
33	#ifdef VBOX_WITH_STATISTICS
34	# include <VBox/vmm/stam.h>
35	#endif
36
37	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
38	* @ingroup grp_pdm_interfaces
39	* @{
40	*/
41
42	/** PDM audio driver instance flags. */
43	typedef uint32_t PDMAUDIODRVFLAGS;
44
45	/** No flags set. */
46	#define PDMAUDIODRVFLAGS_NONE 0
47	/** Marks a primary audio driver which is critical
48	* when running the VM. */
49	#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
50
51	/**
52	* Audio format in signed or unsigned variants.
53	*/
54	typedef enum PDMAUDIOFMT
55	{
56	/** Invalid format, do not use. */
57	PDMAUDIOFMT_INVALID,
58	/** 8-bit, unsigned. */
59	PDMAUDIOFMT_U8,
60	/** 8-bit, signed. */
61	PDMAUDIOFMT_S8,
62	/** 16-bit, unsigned. */
63	PDMAUDIOFMT_U16,
64	/** 16-bit, signed. */
65	PDMAUDIOFMT_S16,
66	/** 32-bit, unsigned. */
67	PDMAUDIOFMT_U32,
68	/** 32-bit, signed. */
69	PDMAUDIOFMT_S32,
70	/** Hack to blow the type up to 32-bit. */
71	PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
72	} PDMAUDIOFMT;
73
74	/**
75	* Audio direction.
76	*/
77	typedef enum PDMAUDIODIR
78	{
79	/** Unknown direction. */
80	PDMAUDIODIR_UNKNOWN = 0,
81	/** Input. */
82	PDMAUDIODIR_IN = 1,
83	/** Output. */
84	PDMAUDIODIR_OUT = 2,
85	/** Duplex handling. */
86	PDMAUDIODIR_ANY = 3,
87	/** Hack to blow the type up to 32-bit. */
88	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
89	} PDMAUDIODIR;
90
91	/** Device latency spec in milliseconds (ms). */
92	typedef uint32_t PDMAUDIODEVLATSPECMS;
93
94	/** Device latency spec in seconds (s). */
95	typedef uint32_t PDMAUDIODEVLATSPECSEC;
96
97	/** Audio device flags. Use with PDMAUDIODEV_FLAG_ flags. */
98	typedef uint32_t PDMAUDIODEVFLAG;
99
100	/** No flags set. */
101	#define PDMAUDIODEV_FLAGS_NONE 0
102	/** The device marks the default device within the host OS. */
103	#define PDMAUDIODEV_FLAGS_DEFAULT RT_BIT(0)
104	/** The device can be removed at any time and we have to deal with it. */
105	#define PDMAUDIODEV_FLAGS_HOTPLUG RT_BIT(1)
106	/** The device is known to be buggy and needs special treatment. */
107	#define PDMAUDIODEV_FLAGS_BUGGY RT_BIT(2)
108	/** Ignore the device, no matter what. */
109	#define PDMAUDIODEV_FLAGS_IGNORE RT_BIT(3)
110	/** The device is present but marked as locked by some other application. */
111	#define PDMAUDIODEV_FLAGS_LOCKED RT_BIT(4)
112	/** The device is present but not in an alive state (dead). */
113	#define PDMAUDIODEV_FLAGS_DEAD RT_BIT(5)
114
115	/**
116	* Audio device type.
117	*/
118	typedef enum PDMAUDIODEVICETYPE
119	{
120	/** Unknown device type. This is the default. */
121	PDMAUDIODEVICETYPE_UNKNOWN = 0,
122	/** Dummy device; for backends which are not able to report
123	* actual device information (yet). */
124	PDMAUDIODEVICETYPE_DUMMY,
125	/** The device is built into the host (non-removable). */
126	PDMAUDIODEVICETYPE_BUILTIN,
127	/** The device is an (external) USB device. */
128	PDMAUDIODEVICETYPE_USB,
129	/** Hack to blow the type up to 32-bit. */
130	PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
131	} PDMAUDIODEVICETYPE;
132
133	/**
134	* Audio device instance data.
135	*/
136	typedef struct PDMAUDIODEVICE
137	{
138	/** List node. */
139	RTLISTNODE Node;
140	/** Friendly name of the device, if any. */
141	char szName[64];
142	/** The device type. */
143	PDMAUDIODEVICETYPE enmType;
144	/** Reference count indicating how many audio streams currently are relying on this device. */
145	uint8_t cRefCount;
146	/** Usage of the device. */
147	PDMAUDIODIR enmUsage;
148	/** Device flags. */
149	PDMAUDIODEVFLAG fFlags;
150	/** Maximum number of input audio channels the device supports. */
151	uint8_t cMaxInputChannels;
152	/** Maximum number of output audio channels the device supports. */
153	uint8_t cMaxOutputChannels;
154	/** Additional data which might be relevant for the current context. */
155	void *pvData;
156	/** Size of the additional data. */
157	size_t cbData;
158	/** Device type union, based on enmType. */
159	union
160	{
161	/** USB type specifics. */
162	struct
163	{
164	/** Vendor ID. */
165	int16_t VID;
166	/** Product ID. */
167	int16_t PID;
168	} USB;
169	} Type;
170	} PDMAUDIODEVICE, *PPDMAUDIODEVICE;
171
172	/**
173	* Structure for keeping an audio device enumeration.
174	*/
175	typedef struct PDMAUDIODEVICEENUM
176	{
177	/** Number of audio devices in the list. */
178	uint16_t cDevices;
179	/** List of audio devices. */
180	RTLISTANCHOR lstDevices;
181	} PDMAUDIODEVICEENUM, *PPDMAUDIODEVICEENUM;
182
183	/**
184	* Audio (static) configuration of an audio host backend.
185	*/
186	typedef struct PDMAUDIOBACKENDCFG
187	{
188	/** Size (in bytes) of the host backend's audio output stream structure. */
189	size_t cbStreamOut;
190	/** Size (in bytes) of the host backend's audio input stream structure. */
191	size_t cbStreamIn;
192	/** Number of concurrent output streams supported on the host.
193	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
194	uint32_t cMaxStreamsOut;
195	/** Number of concurrent input streams supported on the host.
196	* UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
197	uint32_t cMaxStreamsIn;
198	} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
199
200	/**
201	* A single audio sample, representing left and right channels (stereo).
202	*/
203	typedef struct PDMAUDIOSAMPLE
204	{
205	/** Left channel. */
206	int64_t i64LSample;
207	/** Right channel. */
208	int64_t i64RSample;
209	} PDMAUDIOSAMPLE;
210	/** Pointer to a single (stereo) audio sample. */
211	typedef PDMAUDIOSAMPLE *PPDMAUDIOSAMPLE;
212	/** Pointer to a const single (stereo) audio sample. */
213	typedef PDMAUDIOSAMPLE const *PCPDMAUDIOSAMPLE;
214
215	typedef enum PDMAUDIOENDIANNESS
216	{
217	/** The usual invalid endian. */
218	PDMAUDIOENDIANNESS_INVALID,
219	/** Little endian. */
220	PDMAUDIOENDIANNESS_LITTLE,
221	/** Bit endian. */
222	PDMAUDIOENDIANNESS_BIG,
223	/** Endianness doesn't have a meaning in the context. */
224	PDMAUDIOENDIANNESS_NA,
225	/** The end of the valid endian values (exclusive). */
226	PDMAUDIOENDIANNESS_END,
227	/** Hack to blow the type up to 32-bit. */
228	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
229	} PDMAUDIOENDIANNESS;
230
231	/**
232	* Audio playback destinations.
233	*/
234	typedef enum PDMAUDIOPLAYBACKDEST
235	{
236	/** Unknown destination. */
237	PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
238	/** Front channel. */
239	PDMAUDIOPLAYBACKDEST_FRONT,
240	/** Center / LFE (Subwoofer) channel. */
241	PDMAUDIOPLAYBACKDEST_CENTER_LFE,
242	/** Rear channel. */
243	PDMAUDIOPLAYBACKDEST_REAR,
244	/** Hack to blow the type up to 32-bit. */
245	PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
246	} PDMAUDIOPLAYBACKDEST;
247
248	/**
249	* Audio recording sources.
250	*/
251	typedef enum PDMAUDIORECSOURCE
252	{
253	/** Unknown recording source. */
254	PDMAUDIORECSOURCE_UNKNOWN = 0,
255	/** Microphone-In. */
256	PDMAUDIORECSOURCE_MIC,
257	/** CD. */
258	PDMAUDIORECSOURCE_CD,
259	/** Video-In. */
260	PDMAUDIORECSOURCE_VIDEO,
261	/** AUX. */
262	PDMAUDIORECSOURCE_AUX,
263	/** Line-In. */
264	PDMAUDIORECSOURCE_LINE,
265	/** Phone-In. */
266	PDMAUDIORECSOURCE_PHONE,
267	/** Hack to blow the type up to 32-bit. */
268	PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
269	} PDMAUDIORECSOURCE;
270
271	/**
272	* Audio stream (data) layout.
273	*/
274	typedef enum PDMAUDIOSTREAMLAYOUT
275	{
276	/** Unknown access type; do not use. */
277	PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
278	/** Non-interleaved access, that is, consecutive
279	* access to the data. */
280	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
281	/** Interleaved access, where the data can be
282	* mixed together with data of other audio streams. */
283	PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
284	/** Complex layout, which does not fit into the
285	* interleaved / non-interleaved layouts. */
286	PDMAUDIOSTREAMLAYOUT_COMPLEX,
287	/** Raw (pass through) data, with no data layout processing done.
288	*
289	* This means that this stream will operate on PDMAUDIOSAMPLE data
290	* directly. Don't use this if you don't have to. */
291	PDMAUDIOSTREAMLAYOUT_RAW,
292	/** Hack to blow the type up to 32-bit. */
293	PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
294	} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
295
296	/** No stream channel data flags defined. */
297	#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
298
299	/**
300	* Structure for keeping a stream channel data block around.
301	*/
302	typedef struct PDMAUDIOSTREAMCHANNELDATA
303	{
304	/** Circular buffer for the channel data. */
305	PRTCIRCBUF pCircBuf;
306	size_t cbAcq;
307	/** Channel data flags. */
308	uint32_t fFlags;
309	} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
310
311	/**
312	* Structure for a single channel of an audio stream.
313	* An audio stream consists of one or multiple channels,
314	* depending on the configuration.
315	*/
316	typedef struct PDMAUDIOSTREAMCHANNEL
317	{
318	/** Channel ID. */
319	uint8_t uChannel;
320	/** Step size (in bytes) to the channel's next frame. */
321	size_t cbStep;
322	/** Frame size (in bytes) of this channel. */
323	size_t cbFrame;
324	/** Offset (in bytes) to first sample in the data block. */
325	size_t cbFirst;
326	/** Currente offset (in bytes) in the data stream. */
327	size_t cbOff;
328	/** Associated data buffer. */
329	PDMAUDIOSTREAMCHANNELDATA Data;
330	} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
331
332	/**
333	* Union for keeping an audio stream destination or source.
334	*/
335	typedef union PDMAUDIODESTSOURCE
336	{
337	/** Desired playback destination (for an output stream). */
338	PDMAUDIOPLAYBACKDEST Dest;
339	/** Desired recording source (for an input stream). */
340	PDMAUDIORECSOURCE Source;
341	} PDMAUDIODESTSOURCE, *PPDMAUDIODESTSOURCE;
342
343	/**
344	* Properties of audio streams for host/guest
345	* for in or out directions.
346	*/
347	typedef struct PDMAUDIOPCMPROPS
348	{
349	/** Sample width. Bits per sample. */
350	uint8_t cBits;
351	/** Signed or unsigned sample. */
352	bool fSigned;
353	/** Number of audio channels. */
354	uint8_t cChannels;
355	/** Sample frequency in Hertz (Hz). */
356	uint32_t uHz;
357	/** Shift count used for faster calculation of various
358	* values, such as the alignment, bytes to samples and so on.
359	* Depends on number of stream channels and the stream format
360	* being used.
361	*
362	** @todo Use some RTAsmXXX functions instead?
363	*/
364	uint8_t cShift;
365	/** Whether the endianness is swapped or not. */
366	bool fSwapEndian;
367	} PDMAUDIOPCMPROPS, *PPDMAUDIOPCMPROPS;
368
369	/** Calculates the cShift value of given samples bits and audio channels.
370	* Note: Does only support mono/stereo channels for now. */
371	#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBits, cChannels) ((cChannels == 2) + (cBits / 16))
372	/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure.
373	* Note: Does only support mono/stereo channels for now. */
374	#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cChannels == 2) + (pProps)->cBits / 16)
375	/** Converts (audio) samples to bytes.
376	* Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
377	#define PDMAUDIOPCMPROPS_S2B(pProps, samples) ((samples) << (pProps)->cShift)
378	/** Converts bytes to (audio) samples.
379	* Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
380	#define PDMAUDIOPCMPROPS_B2S(pProps, cb) (cb >> (pProps)->cShift)
381
382	/**
383	* Structure for keeping an audio stream configuration.
384	*/
385	typedef struct PDMAUDIOSTREAMCFG
386	{
387	/** Friendly name of the stream. */
388	char szName[64];
389	/** Direction of the stream. */
390	PDMAUDIODIR enmDir;
391	/** Destination / source indicator, depending on enmDir. */
392	PDMAUDIODESTSOURCE DestSource;
393	/** The stream's PCM properties. */
394	PDMAUDIOPCMPROPS Props;
395	/** The stream's audio data layout.
396	* This indicates how the audio data buffers to/from the backend is being layouted.
397	*
398	* Currently, the following layouts are supported by the audio connector:
399	*
400	* PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
401	* One stream at once. The consecutive audio data is exactly in the format and sample width
402	* like defined in the PCM properties. This is the default.
403	*
404	* PDMAUDIOSTREAMLAYOUT_RAW:
405	* Can be one or many streams at once, depending on the stream's mixing buffer setup.
406	* The audio data will get handled as PDMAUDIOSAMPLE samples without any modification done. */
407	PDMAUDIOSTREAMLAYOUT enmLayout;
408	/** Hint about the optimal sample buffer size (in audio samples).
409	* 0 if no hint is given. */
410	uint32_t cSampleBufferHint;
411	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
412
413	/** Converts (audio) samples to bytes. */
414	#define PDMAUDIOSTREAMCFG_S2B(pCfg, samples) ((samples) << (pCfg->Props).cShift)
415	/** Converts bytes to (audio) samples. */
416	#define PDMAUDIOSTREAMCFG_B2S(pCfg, cb) (cb >> (pCfg->Props).cShift)
417
418	#if defined(RT_LITTLE_ENDIAN)
419	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
420	#elif defined(RT_BIG_ENDIAN)
421	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
422	#else
423	# error "Port me!"
424	#endif
425
426	/**
427	* Audio mixer controls.
428	*/
429	typedef enum PDMAUDIOMIXERCTL
430	{
431	/** Unknown mixer control. */
432	PDMAUDIOMIXERCTL_UNKNOWN = 0,
433	/** Master volume. */
434	PDMAUDIOMIXERCTL_VOLUME_MASTER,
435	/** Front. */
436	PDMAUDIOMIXERCTL_FRONT,
437	/** Center / LFE (Subwoofer). */
438	PDMAUDIOMIXERCTL_CENTER_LFE,
439	/** Rear. */
440	PDMAUDIOMIXERCTL_REAR,
441	/** Line-In. */
442	PDMAUDIOMIXERCTL_LINE_IN,
443	/** Microphone-In. */
444	PDMAUDIOMIXERCTL_MIC_IN,
445	/** Hack to blow the type up to 32-bit. */
446	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
447	} PDMAUDIOMIXERCTL;
448
449	/**
450	* Audio stream commands. Used in the audio connector
451	* as well as in the actual host backends.
452	*/
453	typedef enum PDMAUDIOSTREAMCMD
454	{
455	/** Unknown command, do not use. */
456	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
457	/** Enables the stream. */
458	PDMAUDIOSTREAMCMD_ENABLE,
459	/** Disables the stream. */
460	PDMAUDIOSTREAMCMD_DISABLE,
461	/** Pauses the stream. */
462	PDMAUDIOSTREAMCMD_PAUSE,
463	/** Resumes the stream. */
464	PDMAUDIOSTREAMCMD_RESUME,
465	/** Hack to blow the type up to 32-bit. */
466	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
467	} PDMAUDIOSTREAMCMD;
468
469	/**
470	* Audio volume parameters.
471	*/
472	typedef struct PDMAUDIOVOLUME
473	{
474	/** Set to @c true if this stream is muted, @c false if not. */
475	bool fMuted;
476	/** Left channel volume.
477	* Range is from [0 ... 255], whereas 0 specifies
478	* the most silent and 255 the loudest value. */
479	uint8_t uLeft;
480	/** Right channel volume.
481	* Range is from [0 ... 255], whereas 0 specifies
482	* the most silent and 255 the loudest value. */
483	uint8_t uRight;
484	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
485
486	/** Defines the minimum volume allowed. */
487	#define PDMAUDIO_VOLUME_MIN (0)
488	/** Defines the maximum volume allowed. */
489	#define PDMAUDIO_VOLUME_MAX (255)
490
491	/**
492	* Structure for holding rate processing information
493	* of a source + destination audio stream. This is needed
494	* because both streams can differ regarding their rates
495	* and therefore need to be treated accordingly.
496	*/
497	typedef struct PDMAUDIOSTRMRATE
498	{
499	/** Current (absolute) offset in the output
500	* (destination) stream. */
501	uint64_t dstOffset;
502	/** Increment for moving dstOffset for the
503	* destination stream. This is needed because the
504	* source <-> destination rate might be different. */
505	uint64_t dstInc;
506	/** Current (absolute) offset in the input
507	* stream. */
508	uint32_t srcOffset;
509	/** Last processed sample of the input stream.
510	* Needed for interpolation. */
511	PDMAUDIOSAMPLE srcSampleLast;
512	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
513
514	/**
515	* Structure for holding mixing buffer volume parameters.
516	* The volume values are in fixed point style and must
517	* be converted to/from before using with e.g. PDMAUDIOVOLUME.
518	*/
519	typedef struct PDMAUDMIXBUFVOL
520	{
521	/** Set to @c true if this stream is muted, @c false if not. */
522	bool fMuted;
523	/** Left volume to apply during conversion. Pass 0
524	* to convert the original values. May not apply to
525	* all conversion functions. */
526	uint32_t uLeft;
527	/** Right volume to apply during conversion. Pass 0
528	* to convert the original values. May not apply to
529	* all conversion functions. */
530	uint32_t uRight;
531	} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
532
533	/**
534	* Structure for holding sample conversion parameters for
535	* the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
536	*/
537	typedef struct PDMAUDMIXBUFCONVOPTS
538	{
539	/** Number of audio samples to convert. */
540	uint32_t cSamples;
541	union
542	{
543	struct
544	{
545	/** Volume to use for conversion. */
546	PDMAUDMIXBUFVOL Volume;
547	} From;
548	};
549	} PDMAUDMIXBUFCONVOPTS;
550	/** Pointer to conversion parameters for the audio mixer. */
551	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
552	/** Pointer to const conversion parameters for the audio mixer. */
553	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
554
555	/**
556	* Note: All internal handling is done in samples,
557	* not in bytes!
558	*/
559	typedef uint32_t PDMAUDIOMIXBUFFMT;
560	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
561
562	/**
563	* Convertion-from function used by the PDM audio buffer mixer.
564	*
565	* @returns Number of samples returned.
566	* @param paDst Where to return the converted samples.
567	* @param pvSrc The source samples bytes.
568	* @param cbSrc Number of bytes to convert.
569	* @param pOpts Conversion options.
570	*/
571	typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOSAMPLE paDst, const void *pvSrc, uint32_t cbSrc,
572	PCPDMAUDMIXBUFCONVOPTS pOpts);
573	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
574	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
575
576	/**
577	* Convertion-to function used by the PDM audio buffer mixer.
578	*
579	* @param pvDst Output buffer.
580	* @param paSrc The input samples.
581	* @param pOpts Conversion options.
582	*/
583	typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOSAMPLE paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
584	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
585	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
586
587	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
588	typedef struct PDMAUDIOMIXBUF
589	{
590	RTLISTNODE Node;
591	/** Name of the buffer. */
592	char *pszName;
593	/** Sample buffer. */
594	PPDMAUDIOSAMPLE pSamples;
595	/** Size of the sample buffer (in samples). */
596	uint32_t cSamples;
597	/** The current read position (in samples). */
598	uint32_t offRead;
599	/** The current write position (in samples). */
600	uint32_t offWrite;
601	/**
602	* Total samples already mixed down to the parent buffer (if any). Always starting at
603	* the parent's offRead position.
604	*
605	* Note: Count always is specified in parent samples, as the sample count can differ between parent
606	* and child.
607	*/
608	uint32_t cMixed;
609	/** How much audio samples are currently being used
610	* in this buffer.
611	* Note: This also is known as the distance in ring buffer terms. */
612	uint32_t cUsed;
613	/** Pointer to parent buffer (if any). */
614	PPDMAUDIOMIXBUF pParent;
615	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
616	RTLISTANCHOR lstChildren;
617	/** Number of children mix buffers kept in lstChildren. */
618	uint32_t cChildren;
619	/** Intermediate structure for buffer conversion tasks. */
620	PPDMAUDIOSTRMRATE pRate;
621	/** Internal representation of current volume used for mixing. */
622	PDMAUDMIXBUFVOL Volume;
623	/** This buffer's audio format. */
624	PDMAUDIOMIXBUFFMT AudioFmt;
625	/** Standard conversion-to function for set AudioFmt. */
626	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
627	/** Standard conversion-from function for set AudioFmt. */
628	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
629	/**
630	* Ratio of the associated parent stream's frequency by this stream's
631	* frequency (1<<32), represented as a signed 64 bit integer.
632	*
633	* For example, if the parent stream has a frequency of 44 khZ, and this
634	* stream has a frequency of 11 kHz, the ration then would be
635	* (44/11 * (1 << 32)).
636	*
637	* Currently this does not get changed once assigned.
638	*/
639	int64_t iFreqRatio;
640	/** For quickly converting samples <-> bytes and vice versa. */
641	uint8_t cShift;
642	} PDMAUDIOMIXBUF;
643
644	typedef uint32_t PDMAUDIOFILEFLAGS;
645
646	/* No flags defined. */
647	#define PDMAUDIOFILEFLAG_NONE 0
648
649	/**
650	* Audio file types.
651	*/
652	typedef enum PDMAUDIOFILETYPE
653	{
654	/** Unknown type, do not use. */
655	PDMAUDIOFILETYPE_UNKNOWN = 0,
656	/** Wave (.WAV) file. */
657	PDMAUDIOFILETYPE_WAV,
658	/** Hack to blow the type up to 32-bit. */
659	PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
660	} PDMAUDIOFILETYPE;
661
662	/**
663	* Structure for an audio file handle.
664	*/
665	typedef struct PDMAUDIOFILE
666	{
667	/** Type of the audio file. */
668	PDMAUDIOFILETYPE enmType;
669	/** File name. */
670	char szName[255];
671	/** Actual file handle. */
672	RTFILE hFile;
673	/** Data needed for the specific audio file type implemented.
674	* Optional, can be NULL. */
675	void *pvData;
676	/** Data size (in bytes). */
677	size_t cbData;
678	} PDMAUDIOFILE, *PPDMAUDIOFILE;
679
680	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
681	typedef uint32_t PDMAUDIOSTRMSTS;
682
683	/** No flags being set. */
684	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
685	/** Whether this stream has been initialized by the
686	* backend or not. */
687	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
688	/** Whether this stream is enabled or disabled. */
689	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
690	/** Whether this stream has been paused or not. This also implies
691	* that this is an enabled stream! */
692	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
693	/** Whether this stream was marked as being disabled
694	* but there are still associated guest output streams
695	* which rely on its data. */
696	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
697	/** Whether this stream is in re-initialization phase.
698	* All other bits remain untouched to be able to restore
699	* the stream's state after the re-initialization bas been
700	* finished. */
701	#define PDMAUDIOSTRMSTS_FLAG_PENDING_REINIT RT_BIT_32(4)
702	/** Validation mask. */
703	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000001F)
704
705	/**
706	* Enumeration presenting a backend's current status.
707	*/
708	typedef enum PDMAUDIOBACKENDSTS
709	{
710	/** Unknown/invalid status. */
711	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
712	/** The backend is in its initialization phase.
713	* Not all backends support this status. */
714	PDMAUDIOBACKENDSTS_INITIALIZING,
715	/** The backend has stopped its operation. */
716	PDMAUDIOBACKENDSTS_STOPPED,
717	/** The backend is up and running. */
718	PDMAUDIOBACKENDSTS_RUNNING,
719	/** The backend ran into an error and is unable to recover.
720	* A manual re-initialization might help. */
721	PDMAUDIOBACKENDSTS_ERROR,
722	/** Hack to blow the type up to 32-bit. */
723	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
724	} PDMAUDIOBACKENDSTS;
725
726	/**
727	* Audio stream context.
728	*/
729	typedef enum PDMAUDIOSTREAMCTX
730	{
731	/** No context set / invalid. */
732	PDMAUDIOSTREAMCTX_UNKNOWN = 0,
733	/** Host stream, connected to a backend. */
734	PDMAUDIOSTREAMCTX_HOST,
735	/** Guest stream, connected to the device emulation. */
736	PDMAUDIOSTREAMCTX_GUEST,
737	/** Hack to blow the type up to 32-bit. */
738	PDMAUDIOSTREAMCTX_32BIT_HACK = 0x7fffffff
739	} PDMAUDIOSTREAMCTX;
740
741	/**
742	* Structure for keeping audio input stream specifics.
743	* Do not use directly. Instead, use PDMAUDIOSTREAM.
744	*/
745	typedef struct PDMAUDIOSTREAMIN
746	{
747	/** Timestamp (in ms) since last read. */
748	uint64_t tsLastReadMS;
749	#ifdef VBOX_WITH_STATISTICS
750	STAMCOUNTER StatBytesElapsed;
751	STAMCOUNTER StatBytesTotalRead;
752	STAMCOUNTER StatSamplesCaptured;
753	#endif
754	} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
755
756	/**
757	* Structure for keeping audio output stream specifics.
758	* Do not use directly. Instead, use PDMAUDIOSTREAM.
759	*/
760	typedef struct PDMAUDIOSTREAMOUT
761	{
762	/** Timestamp (in ms) since last write. */
763	uint64_t tsLastWriteMS;
764	#ifdef VBOX_WITH_STATISTICS
765	STAMCOUNTER StatBytesElapsed;
766	STAMCOUNTER StatBytesTotalWritten;
767	STAMCOUNTER StatSamplesPlayed;
768	#endif
769	} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
770
771	struct PDMAUDIOSTREAM;
772	typedef PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
773
774	/**
775	* Structure for maintaining an nput/output audio stream.
776	*/
777	typedef struct PDMAUDIOSTREAM
778	{
779	/** List node. */
780	RTLISTNODE Node;
781	/** Pointer to the other pair of this stream.
782	* This might be the host or guest side. */
783	PPDMAUDIOSTREAM pPair;
784	/** Name of this stream. */
785	char szName[64];
786	/** Number of references to this stream. Only can be
787	* destroyed if the reference count is reaching 0. */
788	uint32_t cRefs;
789	/** The stream's audio configuration. */
790	PDMAUDIOSTREAMCFG Cfg;
791	/** Stream status flag. */
792	PDMAUDIOSTRMSTS fStatus;
793	/** This stream's mixing buffer. */
794	PDMAUDIOMIXBUF MixBuf;
795	/** Audio direction of this stream. */
796	PDMAUDIODIR enmDir;
797	/** Context of this stream. */
798	PDMAUDIOSTREAMCTX enmCtx;
799	/** Timestamp (in ms) since last iteration. */
800	uint64_t tsLastIterateMS;
801	/** Union for input/output specifics. */
802	union
803	{
804	PDMAUDIOSTREAMIN In;
805	PDMAUDIOSTREAMOUT Out;
806	};
807	/** Data to backend-specific stream data.
808	* This data block will be casted by the backend to access its backend-dependent data.
809	*
810	* That way the backends do not have access to the audio connector's data. */
811	void *pvBackend;
812	/** Size (in bytes) of the backend-specific stream data. */
813	size_t cbBackend;
814	} PDMAUDIOSTREAM, *PPDMAUDIOSTREAM;
815
816	/** Pointer to a audio connector interface. */
817	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
818
819	/**
820	* Audio callback types.
821	* Those callbacks are being sent from the backends to the audio connector.
822	*/
823	typedef enum PDMAUDIOCBTYPE
824	{
825	/** Invalid, do not use. */
826	PDMAUDIOCBTYPE_INVALID = 0,
827	/** The backend's status has changed. */
828	PDMAUDIOCBTYPE_STATUS,
829	/** One or more host audio devices have changed. */
830	PDMAUDIOCBTYPE_DEVICES_CHANGED,
831	/** Data is availabe as input for passing to the device emulation. */
832	PDMAUDIOCBTYPE_DATA_INPUT,
833	/** Free data for the device emulation to write to the backend. */
834	PDMAUDIOCBTYPE_DATA_OUTPUT
835	} PDMAUDIOCBTYPE;
836
837	/**
838	* Callback data for audio input.
839	*/
840	typedef struct PDMAUDIOCBDATA_DATA_INPUT
841	{
842	/** Input: How many bytes are availabe as input for passing
843	* to the device emulation. */
844	uint32_t cbInAvail;
845	/** Output: How many bytes have been read. */
846	uint32_t cbOutRead;
847	} PDMAUDIOCBDATA_DATA_INPUT, *PPDMAUDIOCBDATA_DATA_INPUT;
848
849	/**
850	* Callback data for audio output.
851	*/
852	typedef struct PDMAUDIOCBDATA_DATA_OUTPUT
853	{
854	/** Input: How many bytes are free for the device emulation to write. */
855	uint32_t cbInFree;
856	/** Output: How many bytes were written by the device emulation. */
857	uint32_t cbOutWritten;
858	} PDMAUDIOCBDATA_DATA_OUTPUT, *PPDMAUDIOCBDATA_DATA_OUTPUT;
859
860	/** Pointer to a host audio interface. */
861	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
862
863	/**
864	* Host audio (backend) callback function.
865	*
866	* @returns IPRT status code.
867	* @param pDrvIns Pointer to driver instance which called us.
868	* @param enmType Callback type.
869	* @param pvUser User argument.
870	* @param cbUser Size (in bytes) of user argument.
871	*/
872	typedef DECLCALLBACK(int) FNPDMHOSTAUDIOCALLBACK(PPDMDRVINS pDrvIns, PDMAUDIOCBTYPE enmType, void *pvUser, size_t cbUser);
873	/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
874	typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
875
876	#ifdef VBOX_WITH_AUDIO_DEVICE_CALLBACKS
877	/**
878	* Structure for keeping a registered audio callback around.
879	*/
880	typedef struct PDMAUDIOCALLBACK
881	{
882	/** List node. */
883	RTLISTANCHOR Node;
884	/** Callback type. */
885	PDMAUDIOCBTYPE enmType;
886	/** Pointer to context data. Optional. */
887	void *pvCtx;
888	/** Size (in bytes) of context data.
889	* Must be 0 if pvCtx is NULL. */
890	size_t cbCtx;
891	/** Actual callback function to call. */
892	PFNPDMAUDIOCALLBACK pFn;
893	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
894	#endif /* VBOX_WITH_AUDIO_DEVICE_CALLBACKS */
895
896	#define PPDMAUDIOBACKENDSTREAM void *
897
898	/**
899	* Audio connector interface (up).
900	*/
901	typedef struct PDMIAUDIOCONNECTOR
902	{
903	/**
904	* Retrieves the current configuration of the host audio backend.
905	*
906	* @returns VBox status code.
907	* @param pInterface Pointer to the interface structure containing the called function pointer.
908	* @param pCfg Where to store the host audio backend configuration data.
909	*/
910	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
911
912	/**
913	* Retrieves the current status of the host audio backend.
914	*
915	* @returns Status of the host audio backend.
916	* @param pInterface Pointer to the interface structure containing the called function pointer.
917	* @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_ANY for the overall
918	* backend status.
919	*/
920	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
921
922	/**
923	* Creates an audio stream.
924	*
925	* @returns VBox status code.
926	* @param pInterface Pointer to the interface structure containing the called function pointer.
927	* @param pCfgHost Stream configuration for host side.
928	* @param pCfgGuest Stream configuration for guest side.
929	* @param ppStream Pointer where to return the created audio stream on success.
930	*/
931	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
932
933	/**
934	* Destroys an audio stream.
935	*
936	* @param pInterface Pointer to the interface structure containing the called function pointer.
937	* @param pStream Pointer to audio stream.
938	*/
939	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
940
941	/**
942	* Adds a reference to the specified audio stream.
943	*
944	* @returns New reference count. UINT32_MAX on error.
945	* @param pInterface Pointer to the interface structure containing the called function pointer.
946	* @param pStream Pointer to audio stream adding the reference to.
947	*/
948	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
949
950	/**
951	* Releases a reference from the specified stream.
952	*
953	* @returns New reference count. UINT32_MAX on error.
954	* @param pInterface Pointer to the interface structure containing the called function pointer.
955	* @param pStream Pointer to audio stream releasing a reference from.
956	*/
957	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
958
959	/**
960	* Reads PCM audio data from the host (input).
961	*
962	* @returns VBox status code.
963	* @param pInterface Pointer to the interface structure containing the called function pointer.
964	* @param pStream Pointer to audio stream to write to.
965	* @param pvBuf Where to store the read data.
966	* @param cbBuf Number of bytes to read.
967	* @param pcbRead Bytes of audio data read. Optional.
968	*/
969	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
970
971	/**
972	* Writes PCM audio data to the host (output).
973	*
974	* @returns VBox status code.
975	* @param pInterface Pointer to the interface structure containing the called function pointer.
976	* @param pStream Pointer to audio stream to read from.
977	* @param pvBuf Audio data to be written.
978	* @param cbBuf Number of bytes to be written.
979	* @param pcbWritten Bytes of audio data written. Optional.
980	*/
981	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
982
983	/**
984	* Controls a specific audio stream.
985	*
986	* @returns VBox status code.
987	* @param pInterface Pointer to the interface structure containing the called function pointer.
988	* @param pStream Pointer to audio stream.
989	* @param enmStreamCmd The stream command to issue.
990	*/
991	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
992
993	/**
994	* Processes stream data.
995	*
996	* @param pInterface Pointer to the interface structure containing the called function pointer.
997	* @param pStream Pointer to audio stream.
998	*/
999	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1000
1001	/**
1002	* Returns the number of readable data (in bytes) of a specific audio input stream.
1003	*
1004	* @returns Number of readable data (in bytes).
1005	* @param pInterface Pointer to the interface structure containing the called function pointer.
1006	* @param pStream Pointer to audio stream.
1007	*/
1008	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1009
1010	/**
1011	* Returns the number of writable data (in bytes) of a specific audio output stream.
1012	*
1013	* @returns Number of writable data (in bytes).
1014	* @param pInterface Pointer to the interface structure containing the called function pointer.
1015	* @param pStream Pointer to audio stream.
1016	*/
1017	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1018
1019	/**
1020	* Returns the status of a specific audio stream.
1021	*
1022	* @returns Audio stream status
1023	* @param pInterface Pointer to the interface structure containing the called function pointer.
1024	* @param pStream Pointer to audio stream.
1025	*/
1026	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1027
1028	/**
1029	* Sets the audio volume of a specific audio stream.
1030	*
1031	* @returns VBox status code.
1032	* @param pInterface Pointer to the interface structure containing the called function pointer.
1033	* @param pStream Pointer to audio stream.
1034	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1035	*/
1036	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1037
1038	/**
1039	* Plays (transfers) available audio samples via the host backend. Only works with output streams.
1040	*
1041	* @returns VBox status code.
1042	* @param pInterface Pointer to the interface structure containing the called function pointer.
1043	* @param pStream Pointer to audio stream.
1044	* @param pcSamplesPlayed Number of samples played. Optional.
1045	*/
1046	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
1047
1048	/**
1049	* Captures (transfers) available audio samples from the host backend. Only works with input streams.
1050	*
1051	* @returns VBox status code.
1052	* @param pInterface Pointer to the interface structure containing the called function pointer.
1053	* @param pStream Pointer to audio stream.
1054	* @param pcSamplesCaptured Number of samples captured. Optional.
1055	*/
1056	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
1057
1058	#ifdef VBOX_WITH_AUDIO_DEVICE_CALLBACKS
1059	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
1060	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCBTYPE enmType, void *pvUser, size_t cbUser));
1061	#endif
1062
1063	} PDMIAUDIOCONNECTOR;
1064
1065	/** PDMIAUDIOCONNECTOR interface ID. */
1066	#define PDMIAUDIOCONNECTOR_IID "FF2044D1-F8D9-4F42-BE9E-0E9AD14F4552"
1067
1068	/**
1069	* Assigns all needed interface callbacks for an audio backend.
1070	*
1071	* @param a_Prefix The function name prefix.
1072	*/
1073	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_Prefix) \
1074	do { \
1075	pThis->IHostAudio.pfnInit = RT_CONCAT(a_Prefix,Init); \
1076	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_Prefix,Shutdown); \
1077	pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_Prefix,GetConfig); \
1078	/** @todo Add pfnGetDevices here as soon as supported by all backends. */ \
1079	pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_Prefix,GetStatus); \
1080	/** @todo Ditto for pfnSetCallback. */ \
1081	pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_Prefix,StreamCreate); \
1082	pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_Prefix,StreamDestroy); \
1083	pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_Prefix,StreamControl); \
1084	pThis->IHostAudio.pfnStreamGetReadable = RT_CONCAT(a_Prefix,StreamGetReadable); \
1085	pThis->IHostAudio.pfnStreamGetWritable = RT_CONCAT(a_Prefix,StreamGetWritable); \
1086	pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_Prefix,StreamGetStatus); \
1087	pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_Prefix,StreamIterate); \
1088	pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_Prefix,StreamPlay); \
1089	pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_Prefix,StreamCapture); \
1090	} while (0)
1091
1092	/**
1093	* PDM host audio interface.
1094	*/
1095	typedef struct PDMIHOSTAUDIO
1096	{
1097	/**
1098	* Initializes the host backend (driver).
1099	*
1100	* @returns VBox status code.
1101	* @param pInterface Pointer to the interface structure containing the called function pointer.
1102	*/
1103	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1104
1105	/**
1106	* Shuts down the host backend (driver).
1107	*
1108	* @returns VBox status code.
1109	* @param pInterface Pointer to the interface structure containing the called function pointer.
1110	*/
1111	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1112
1113	/**
1114	* Returns the host backend's configuration (backend).
1115	*
1116	* @returns VBox status code.
1117	* @param pInterface Pointer to the interface structure containing the called function pointer.
1118	* @param pBackendCfg Where to store the backend audio configuration to.
1119	*/
1120	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1121
1122	/**
1123	* Returns (enumerates) host audio device information.
1124	*
1125	* @returns VBox status code.
1126	* @param pInterface Pointer to the interface structure containing the called function pointer.
1127	* @param pDeviceEnum Where to return the enumerated audio devices.
1128	*/
1129	DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIODEVICEENUM pDeviceEnum));
1130
1131	/**
1132	* Returns the current status from the audio backend.
1133	*
1134	* @returns PDMAUDIOBACKENDSTS enum.
1135	* @param pInterface Pointer to the interface structure containing the called function pointer.
1136	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
1137	*/
1138	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1139
1140	/**
1141	* Sets a callback the audio backend can call. Optional.
1142	*
1143	* @returns VBox status code.
1144	* @param pInterface Pointer to the interface structure containing the called function pointer.
1145	* @param pfnCallback The callback function to use, or NULL when unregistering.
1146	*/
1147	DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1148
1149	/**
1150	* Creates an audio stream using the requested stream configuration.
1151	* If a backend is not able to create this configuration, it will return its best match in the acquired configuration
1152	* structure on success.
1153	*
1154	* @returns VBox status code.
1155	* @param pInterface Pointer to the interface structure containing the called function pointer.
1156	* @param pStream Pointer to audio stream.
1157	* @param pCfgReq Pointer to requested stream configuration.
1158	* @param pCfgAcq Pointer to acquired stream configuration.
1159	*/
1160	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1161
1162	/**
1163	* Destroys an audio stream.
1164	*
1165	* @returns VBox status code.
1166	* @param pInterface Pointer to the interface structure containing the called function pointer.
1167	* @param pStream Pointer to audio stream.
1168	*/
1169	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1170
1171	/**
1172	* Controls an audio stream.
1173	*
1174	* @returns VBox status code.
1175	* @param pInterface Pointer to the interface structure containing the called function pointer.
1176	* @param pStream Pointer to audio stream.
1177	* @param enmStreamCmd The stream command to issue.
1178	*/
1179	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1180
1181	/**
1182	* Returns the amount which is readable from the audio (input) stream.
1183	*
1184	* @returns For non-raw layout streams: Number of readable bytes.
1185	* for raw layout streams : Number of readable audio samples.
1186	* @param pInterface Pointer to the interface structure containing the called function pointer.
1187	* @param pStream Pointer to audio stream.
1188	*/
1189	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1190
1191	/**
1192	* Returns the amount which is writable to the audio (output) stream.
1193	*
1194	* @returns For non-raw layout streams: Number of writable bytes.
1195	* for raw layout streams : Number of writable audio samples.
1196	* @param pInterface Pointer to the interface structure containing the called function pointer.
1197	* @param pStream Pointer to audio stream.
1198	*/
1199	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1200
1201	/**
1202	* Returns whether the specified audio direction in the backend is enabled or not.
1203	*
1204	* @returns PDMAUDIOSTRMSTS
1205	* @param pInterface Pointer to the interface structure containing the called function pointer.
1206	* @param pStream Pointer to audio stream.
1207	*/
1208	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1209
1210	/**
1211	* Gives the host backend the chance to do some (necessary) iteration work.
1212	*
1213	* @returns VBox status code.
1214	* @param pInterface Pointer to the interface structure containing the called function pointer.
1215	* @param pStream Pointer to audio stream.
1216	*/
1217	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1218
1219	/**
1220	* Signals the backend that the host wants to begin playing for this iteration. Optional.
1221	*
1222	* @param pInterface Pointer to the interface structure containing the called function pointer.
1223	* @param pStream Pointer to audio stream.
1224	*/
1225	DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1226
1227	/**
1228	* Plays (writes to) an audio (output) stream.
1229	*
1230	* @returns VBox status code.
1231	* @param pInterface Pointer to the interface structure containing the called function pointer.
1232	* @param pStream Pointer to audio stream.
1233	* @param pvBuf Pointer to audio data buffer to play.
1234	* @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1235	* for raw layout streams : Size (in audio samples) of audio data buffer.
1236	* @param pcxWritten For non-raw layout streams: Returns number of bytes written. Optional.
1237	* for raw layout streams : Returns number of samples written. Optional.
1238	*/
1239	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, const void pvBuf, uint32_t cxBuf, uint32_t pcxWritten));
1240
1241	/**
1242	* Signals the backend that the host finished playing for this iteration. Optional.
1243	*
1244	* @param pInterface Pointer to the interface structure containing the called function pointer.
1245	* @param pStream Pointer to audio stream.
1246	*/
1247	DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1248
1249	/**
1250	* Signals the backend that the host wants to begin capturing for this iteration. Optional.
1251	*
1252	* @param pInterface Pointer to the interface structure containing the called function pointer.
1253	* @param pStream Pointer to audio stream.
1254	*/
1255	DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1256
1257	/**
1258	* Captures (reads from) an audio (input) stream.
1259	*
1260	* @returns VBox status code.
1261	* @param pInterface Pointer to the interface structure containing the called function pointer.
1262	* @param pStream Pointer to audio stream.
1263	* @param pvBuf Buffer where to store read audio data.
1264	* @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1265	* for raw layout streams : Size (in audio samples) of audio data buffer.
1266	* @param pcxRead For non-raw layout streams: Returns number of bytes read. Optional.
1267	* for raw layout streams : Returns number of samples read. Optional.
1268	*/
1269	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, void pvBuf, uint32_t cxBuf, uint32_t pcxRead));
1270
1271	/**
1272	* Signals the backend that the host finished capturing for this iteration. Optional.
1273	*
1274	* @param pInterface Pointer to the interface structure containing the called function pointer.
1275	* @param pStream Pointer to audio stream.
1276	*/
1277	DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1278
1279	} PDMIHOSTAUDIO;
1280
1281	/** PDMIHOSTAUDIO interface ID. */
1282	#define PDMIHOSTAUDIO_IID "378A5C7F-A45A-4B8B-C1DA-CB49E84894AA"
1283
1284	/** @} */
1285
1286	#endif /* !___VBox_vmm_pdmaudioifs_h */
1287

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/vmm/pdmaudioifs.h@ 68077

Download in other formats: