pdmaudioifs.h@ 65572

Last change on this file since 65572 was 65565, checked in by vboxsync, 8 years ago
Audio: Make use of pvBuf/cbBuf parameters in PDMIHOSTAUDIO::pfnStreamPlay() and PDMIHOSTAUDIO::pfnStreamCapture() to further abstract the backends from the audio connector. The backends now won't be allowed to operate on the audio connector's mixing buffers directly anymore that way.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 43.2 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2016 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	/** Hack to blow the type up to 32-bit. */
288	PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
289	} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
290
291	/** No stream channel data flags defined. */
292	#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
293
294	/**
295	* Structure for keeping a stream channel data block around.
296	*/
297	typedef struct PDMAUDIOSTREAMCHANNELDATA
298	{
299	/** Circular buffer for the channel data. */
300	PRTCIRCBUF pCircBuf;
301	size_t cbAcq;
302	/** Channel data flags. */
303	uint32_t fFlags;
304	} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
305
306	/**
307	* Structure for a single channel of an audio stream.
308	* An audio stream consists of one or multiple channels,
309	* depending on the configuration.
310	*/
311	typedef struct PDMAUDIOSTREAMCHANNEL
312	{
313	/** Channel ID. */
314	uint8_t uChannel;
315	/** Step size (in bytes) to the channel's next frame. */
316	size_t cbStep;
317	/** Frame size (in bytes) of this channel. */
318	size_t cbFrame;
319	/** Offset (in bytes) to first sample in the data block. */
320	size_t cbFirst;
321	/** Currente offset (in bytes) in the data stream. */
322	size_t cbOff;
323	/** Associated data buffer. */
324	PDMAUDIOSTREAMCHANNELDATA Data;
325	} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
326
327	/**
328	* Union for keeping an audio stream destination or source.
329	*/
330	typedef union PDMAUDIODESTSOURCE
331	{
332	/** Desired playback destination (for an output stream). */
333	PDMAUDIOPLAYBACKDEST Dest;
334	/** Desired recording source (for an input stream). */
335	PDMAUDIORECSOURCE Source;
336	} PDMAUDIODESTSOURCE, *PPDMAUDIODESTSOURCE;
337
338	/**
339	* Structure for keeping an audio stream configuration.
340	*/
341	typedef struct PDMAUDIOSTREAMCFG
342	{
343	/** Friendly name of the stream. */
344	char szName[64];
345	/** Direction of the stream. */
346	PDMAUDIODIR enmDir;
347	/** Destination / source indicator, depending on enmDir. */
348	PDMAUDIODESTSOURCE DestSource;
349	/** Frequency in Hertz (Hz). */
350	uint32_t uHz;
351	/** Number of audio channels (2 for stereo, 1 for mono). */
352	uint8_t cChannels;
353	/** Audio format. */
354	PDMAUDIOFMT enmFormat;
355	/** @todo Use RT_LE2H_? /
356	PDMAUDIOENDIANNESS enmEndianness;
357	/** Hint about the optimal sample buffer size (in audio samples).
358	* 0 if no hint is given. */
359	uint32_t cSampleBufferSize;
360	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
361
362	#if defined(RT_LITTLE_ENDIAN)
363	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
364	#elif defined(RT_BIG_ENDIAN)
365	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
366	#else
367	# error "Port me!"
368	#endif
369
370	/**
371	* Audio mixer controls.
372	*/
373	typedef enum PDMAUDIOMIXERCTL
374	{
375	/** Unknown mixer control. */
376	PDMAUDIOMIXERCTL_UNKNOWN = 0,
377	/** Master volume. */
378	PDMAUDIOMIXERCTL_VOLUME_MASTER,
379	/** Front. */
380	PDMAUDIOMIXERCTL_FRONT,
381	/** Center / LFE (Subwoofer). */
382	PDMAUDIOMIXERCTL_CENTER_LFE,
383	/** Rear. */
384	PDMAUDIOMIXERCTL_REAR,
385	/** Line-In. */
386	PDMAUDIOMIXERCTL_LINE_IN,
387	/** Microphone-In. */
388	PDMAUDIOMIXERCTL_MIC_IN,
389	/** Hack to blow the type up to 32-bit. */
390	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
391	} PDMAUDIOMIXERCTL;
392
393	/**
394	* Audio stream commands. Used in the audio connector
395	* as well as in the actual host backends.
396	*/
397	typedef enum PDMAUDIOSTREAMCMD
398	{
399	/** Unknown command, do not use. */
400	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
401	/** Enables the stream. */
402	PDMAUDIOSTREAMCMD_ENABLE,
403	/** Disables the stream. */
404	PDMAUDIOSTREAMCMD_DISABLE,
405	/** Pauses the stream. */
406	PDMAUDIOSTREAMCMD_PAUSE,
407	/** Resumes the stream. */
408	PDMAUDIOSTREAMCMD_RESUME,
409	/** Hack to blow the type up to 32-bit. */
410	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
411	} PDMAUDIOSTREAMCMD;
412
413	/**
414	* Properties of audio streams for host/guest
415	* for in or out directions.
416	*/
417	typedef struct PDMAUDIOPCMPROPS
418	{
419	/** Sample width. Bits per sample. */
420	uint8_t cBits;
421	/** Signed or unsigned sample. */
422	bool fSigned;
423	/** Shift count used for faster calculation of various
424	* values, such as the alignment, bytes to samples and so on.
425	* Depends on number of stream channels and the stream format
426	* being used.
427	*
428	** @todo Use some RTAsmXXX functions instead?
429	*/
430	uint8_t cShift;
431	/** Number of audio channels. */
432	uint8_t cChannels;
433	/** Alignment mask. */
434	uint32_t uAlign;
435	/** Sample frequency in Hertz (Hz). */
436	uint32_t uHz;
437	/** Bitrate (in bytes/s). */
438	uint32_t cbBitrate;
439	/** Whether the endianness is swapped or not. */
440	bool fSwapEndian;
441	} PDMAUDIOPCMPROPS, *PPDMAUDIOPCMPROPS;
442
443	/** Converts (audio) samples to bytes. */
444	#define PDMAUDIOPCMPROPS_S2B(pProps, samples) ((samples) << (pProps)->cShift)
445	/** Converts bytes to (audio) samples. */
446	#define PDMAUDIOPCMPROPS_B2S(pProps, cb) (cb >> (pProps)->cShift)
447
448	/**
449	* Audio volume parameters.
450	*/
451	typedef struct PDMAUDIOVOLUME
452	{
453	/** Set to @c true if this stream is muted, @c false if not. */
454	bool fMuted;
455	/** Left channel volume.
456	* Range is from [0 ... 255], whereas 0 specifies
457	* the most silent and 255 the loudest value. */
458	uint8_t uLeft;
459	/** Right channel volume.
460	* Range is from [0 ... 255], whereas 0 specifies
461	* the most silent and 255 the loudest value. */
462	uint8_t uRight;
463	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
464
465	/** Defines the minimum volume allowed. */
466	#define PDMAUDIO_VOLUME_MIN (0)
467	/** Defines the maximum volume allowed. */
468	#define PDMAUDIO_VOLUME_MAX (255)
469
470	/**
471	* Structure for holding rate processing information
472	* of a source + destination audio stream. This is needed
473	* because both streams can differ regarding their rates
474	* and therefore need to be treated accordingly.
475	*/
476	typedef struct PDMAUDIOSTRMRATE
477	{
478	/** Current (absolute) offset in the output
479	* (destination) stream. */
480	uint64_t dstOffset;
481	/** Increment for moving dstOffset for the
482	* destination stream. This is needed because the
483	* source <-> destination rate might be different. */
484	uint64_t dstInc;
485	/** Current (absolute) offset in the input
486	* stream. */
487	uint32_t srcOffset;
488	/** Last processed sample of the input stream.
489	* Needed for interpolation. */
490	PDMAUDIOSAMPLE srcSampleLast;
491	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
492
493	/**
494	* Structure for holding mixing buffer volume parameters.
495	* The volume values are in fixed point style and must
496	* be converted to/from before using with e.g. PDMAUDIOVOLUME.
497	*/
498	typedef struct PDMAUDMIXBUFVOL
499	{
500	/** Set to @c true if this stream is muted, @c false if not. */
501	bool fMuted;
502	/** Left volume to apply during conversion. Pass 0
503	* to convert the original values. May not apply to
504	* all conversion functions. */
505	uint32_t uLeft;
506	/** Right volume to apply during conversion. Pass 0
507	* to convert the original values. May not apply to
508	* all conversion functions. */
509	uint32_t uRight;
510	} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
511
512	/**
513	* Structure for holding sample conversion parameters for
514	* the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
515	*/
516	typedef struct PDMAUDMIXBUFCONVOPTS
517	{
518	/** Number of audio samples to convert. */
519	uint32_t cSamples;
520	union
521	{
522	struct
523	{
524	/** Volume to use for conversion. */
525	PDMAUDMIXBUFVOL Volume;
526	} From;
527	};
528	} PDMAUDMIXBUFCONVOPTS;
529	/** Pointer to conversion parameters for the audio mixer. */
530	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
531	/** Pointer to const conversion parameters for the audio mixer. */
532	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
533
534	/**
535	* Note: All internal handling is done in samples,
536	* not in bytes!
537	*/
538	typedef uint32_t PDMAUDIOMIXBUFFMT;
539	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
540
541	/**
542	* Convertion-from function used by the PDM audio buffer mixer.
543	*
544	* @returns Number of samples returned.
545	* @param paDst Where to return the converted samples.
546	* @param pvSrc The source samples bytes.
547	* @param cbSrc Number of bytes to convert.
548	* @param pOpts Conversion options.
549	*/
550	typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOSAMPLE paDst, const void *pvSrc, uint32_t cbSrc,
551	PCPDMAUDMIXBUFCONVOPTS pOpts);
552	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
553	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
554
555	/**
556	* Convertion-to function used by the PDM audio buffer mixer.
557	*
558	* @param pvDst Output buffer.
559	* @param paSrc The input samples.
560	* @param pOpts Conversion options.
561	*/
562	typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOSAMPLE paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
563	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
564	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
565
566	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
567	typedef struct PDMAUDIOMIXBUF
568	{
569	RTLISTNODE Node;
570	/** Name of the buffer. */
571	char *pszName;
572	/** Sample buffer. */
573	PPDMAUDIOSAMPLE pSamples;
574	/** Size of the sample buffer (in samples). */
575	uint32_t cSamples;
576	/** The current read position (in samples). */
577	uint32_t offRead;
578	/** The current write position (in samples). */
579	uint32_t offWrite;
580	/**
581	* Total samples already mixed down to the parent buffer (if any). Always starting at
582	* the parent's offRead position.
583	*
584	* Note: Count always is specified in parent samples, as the sample count can differ between parent
585	* and child.
586	*/
587	uint32_t cMixed;
588	/** How much audio samples are currently being used
589	* in this buffer.
590	* Note: This also is known as the distance in ring buffer terms. */
591	uint32_t cUsed;
592	/** Pointer to parent buffer (if any). */
593	PPDMAUDIOMIXBUF pParent;
594	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
595	RTLISTANCHOR lstChildren;
596	/** Intermediate structure for buffer conversion tasks. */
597	PPDMAUDIOSTRMRATE pRate;
598	/** Internal representation of current volume used for mixing. */
599	PDMAUDMIXBUFVOL Volume;
600	/** This buffer's audio format. */
601	PDMAUDIOMIXBUFFMT AudioFmt;
602	/** Standard conversion-to function for set AudioFmt. */
603	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
604	/** Standard conversion-from function for set AudioFmt. */
605	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
606	/**
607	* Ratio of the associated parent stream's frequency by this stream's
608	* frequency (1<<32), represented as a signed 64 bit integer.
609	*
610	* For example, if the parent stream has a frequency of 44 khZ, and this
611	* stream has a frequency of 11 kHz, the ration then would be
612	* (44/11 * (1 << 32)).
613	*
614	* Currently this does not get changed once assigned.
615	*/
616	int64_t iFreqRatio;
617	/** For quickly converting samples <-> bytes and vice versa. */
618	uint8_t cShift;
619	} PDMAUDIOMIXBUF;
620
621	typedef uint32_t PDMAUDIOFILEFLAGS;
622
623	/* No flags defined. */
624	#define PDMAUDIOFILEFLAG_NONE 0
625
626	/**
627	* Audio file types.
628	*/
629	typedef enum PDMAUDIOFILETYPE
630	{
631	/** Unknown type, do not use. */
632	PDMAUDIOFILETYPE_UNKNOWN = 0,
633	/** Wave (.WAV) file. */
634	PDMAUDIOFILETYPE_WAV,
635	/** Hack to blow the type up to 32-bit. */
636	PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
637	} PDMAUDIOFILETYPE;
638
639	/**
640	* Structure for an audio file handle.
641	*/
642	typedef struct PDMAUDIOFILE
643	{
644	/** Type of the audio file. */
645	PDMAUDIOFILETYPE enmType;
646	/** File name. */
647	char szName[255];
648	/** Actual file handle. */
649	RTFILE hFile;
650	/** Data needed for the specific audio file type implemented.
651	* Optional, can be NULL. */
652	void *pvData;
653	/** Data size (in bytes). */
654	size_t cbData;
655	} PDMAUDIOFILE, *PPDMAUDIOFILE;
656
657	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
658	typedef uint32_t PDMAUDIOSTRMSTS;
659
660	/** No flags being set. */
661	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
662	/** Whether this stream has been initialized by the
663	* backend or not. */
664	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
665	/** Whether this stream is enabled or disabled. */
666	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
667	/** Whether this stream has been paused or not. This also implies
668	* that this is an enabled stream! */
669	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
670	/** Whether this stream was marked as being disabled
671	* but there are still associated guest output streams
672	* which rely on its data. */
673	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
674	/** Data can be read from the stream. */
675	#define PDMAUDIOSTRMSTS_FLAG_DATA_READABLE RT_BIT_32(4)
676	/** Data can be written to the stream. */
677	#define PDMAUDIOSTRMSTS_FLAG_DATA_WRITABLE RT_BIT_32(5)
678	/** Whether this stream is in re-initialization phase.
679	* All other bits remain untouched to be able to restore
680	* the stream's state after the re-initialization bas been
681	* finished. */
682	#define PDMAUDIOSTRMSTS_FLAG_PENDING_REINIT RT_BIT_32(6)
683	/** Validation mask. */
684	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000007F)
685
686	/**
687	* Enumeration presenting a backend's current status.
688	*/
689	typedef enum PDMAUDIOBACKENDSTS
690	{
691	/** Unknown/invalid status. */
692	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
693	/** The backend is in its initialization phase.
694	* Not all backends support this status. */
695	PDMAUDIOBACKENDSTS_INITIALIZING,
696	/** The backend has stopped its operation. */
697	PDMAUDIOBACKENDSTS_STOPPED,
698	/** The backend is up and running. */
699	PDMAUDIOBACKENDSTS_RUNNING,
700	/** The backend ran into an error and is unable to recover.
701	* A manual re-initialization might help. */
702	PDMAUDIOBACKENDSTS_ERROR,
703	/** Hack to blow the type up to 32-bit. */
704	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
705	} PDMAUDIOBACKENDSTS;
706
707	/**
708	* Audio stream context.
709	*/
710	typedef enum PDMAUDIOSTREAMCTX
711	{
712	/** No context set / invalid. */
713	PDMAUDIOSTREAMCTX_UNKNOWN = 0,
714	/** Host stream, connected to a backend. */
715	PDMAUDIOSTREAMCTX_HOST,
716	/** Guest stream, connected to the device emulation. */
717	PDMAUDIOSTREAMCTX_GUEST,
718	/** Hack to blow the type up to 32-bit. */
719	PDMAUDIOSTREAMCTX_32BIT_HACK = 0x7fffffff
720	} PDMAUDIOSTREAMCTX;
721
722	/**
723	* Structure for keeping audio input stream specifics.
724	* Do not use directly. Instead, use PDMAUDIOSTREAM.
725	*/
726	typedef struct PDMAUDIOSTREAMIN
727	{
728	/** Timestamp (in ms) since last read. */
729	uint64_t tsLastReadMS;
730	#ifdef VBOX_WITH_STATISTICS
731	STAMCOUNTER StatBytesElapsed;
732	STAMCOUNTER StatBytesTotalRead;
733	STAMCOUNTER StatSamplesCaptured;
734	#endif
735	} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
736
737	/**
738	* Structure for keeping audio output stream specifics.
739	* Do not use directly. Instead, use PDMAUDIOSTREAM.
740	*/
741	typedef struct PDMAUDIOSTREAMOUT
742	{
743	/** Timestamp (in ms) since last write. */
744	uint64_t tsLastWriteMS;
745	#ifdef VBOX_WITH_STATISTICS
746	STAMCOUNTER StatBytesElapsed;
747	STAMCOUNTER StatBytesTotalWritten;
748	STAMCOUNTER StatSamplesPlayed;
749	#endif
750	} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
751
752	struct PDMAUDIOSTREAM;
753	typedef PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
754
755	/**
756	* Structure for maintaining an nput/output audio stream.
757	*/
758	typedef struct PDMAUDIOSTREAM
759	{
760	/** List node. */
761	RTLISTNODE Node;
762	/** Pointer to the other pair of this stream.
763	* This might be the host or guest side. */
764	PPDMAUDIOSTREAM pPair;
765	/** Name of this stream. */
766	char szName[64];
767	/** Number of references to this stream. Only can be
768	* destroyed if the reference count is reaching 0. */
769	uint32_t cRefs;
770	/** The stream's audio configuration. */
771	PDMAUDIOSTREAMCFG Cfg;
772	/** Stream status flag. */
773	PDMAUDIOSTRMSTS fStatus;
774	/** This stream's mixing buffer. */
775	PDMAUDIOMIXBUF MixBuf;
776	/** Audio direction of this stream. */
777	PDMAUDIODIR enmDir;
778	/** Context of this stream. */
779	PDMAUDIOSTREAMCTX enmCtx;
780	/** Timestamp (in ms) since last iteration. */
781	uint64_t tsLastIterateMS;
782	/** Union for input/output specifics. */
783	union
784	{
785	PDMAUDIOSTREAMIN In;
786	PDMAUDIOSTREAMOUT Out;
787	};
788	} PDMAUDIOSTREAM, *PPDMAUDIOSTREAM;
789
790	/** Pointer to a audio connector interface. */
791	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
792
793	/**
794	* Audio callback types.
795	* Those callbacks are being sent from the backends to the audio connector.
796	*/
797	typedef enum PDMAUDIOCBTYPE
798	{
799	/** Invalid, do not use. */
800	PDMAUDIOCBTYPE_INVALID = 0,
801	/** The backend's status has changed. */
802	PDMAUDIOCBTYPE_STATUS,
803	/** One or more host audio devices have changed. */
804	PDMAUDIOCBTYPE_DEVICES_CHANGED,
805	/** Data is availabe as input for passing to the device emulation. */
806	PDMAUDIOCBTYPE_DATA_INPUT,
807	/** Free data for the device emulation to write to the backend. */
808	PDMAUDIOCBTYPE_DATA_OUTPUT
809	} PDMAUDIOCBTYPE;
810
811	/**
812	* Callback data for audio input.
813	*/
814	typedef struct PDMAUDIOCBDATA_DATA_INPUT
815	{
816	/** Input: How many bytes are availabe as input for passing
817	* to the device emulation. */
818	uint32_t cbInAvail;
819	/** Output: How many bytes have been read. */
820	uint32_t cbOutRead;
821	} PDMAUDIOCBDATA_DATA_INPUT, *PPDMAUDIOCBDATA_DATA_INPUT;
822
823	/**
824	* Callback data for audio output.
825	*/
826	typedef struct PDMAUDIOCBDATA_DATA_OUTPUT
827	{
828	/** Input: How many bytes are free for the device emulation to write. */
829	uint32_t cbInFree;
830	/** Output: How many bytes were written by the device emulation. */
831	uint32_t cbOutWritten;
832	} PDMAUDIOCBDATA_DATA_OUTPUT, *PPDMAUDIOCBDATA_DATA_OUTPUT;
833
834	/** Pointer to a host audio interface. */
835	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
836
837	/**
838	* Host audio (backend) callback function.
839	*
840	* @returns IPRT status code.
841	* @param pDrvIns Pointer to driver instance which called us.
842	* @param enmType Callback type.
843	* @param pvUser User argument.
844	* @param cbUser Size (in bytes) of user argument.
845	*/
846	typedef DECLCALLBACK(int) FNPDMHOSTAUDIOCALLBACK(PPDMDRVINS pDrvIns, PDMAUDIOCBTYPE enmType, void *pvUser, size_t cbUser);
847	/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
848	typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
849
850	#ifdef VBOX_WITH_AUDIO_DEVICE_CALLBACKS
851	/**
852	* Structure for keeping a registered audio callback around.
853	*/
854	typedef struct PDMAUDIOCALLBACK
855	{
856	/** List node. */
857	RTLISTANCHOR Node;
858	/** Callback type. */
859	PDMAUDIOCBTYPE enmType;
860	/** Pointer to context data. Optional. */
861	void *pvCtx;
862	/** Size (in bytes) of context data.
863	* Must be 0 if pvCtx is NULL. */
864	size_t cbCtx;
865	/** Actual callback function to call. */
866	PFNPDMAUDIOCALLBACK pFn;
867	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
868	#endif /* VBOX_WITH_AUDIO_DEVICE_CALLBACKS */
869
870	/**
871	* Audio connector interface (up).
872	*/
873	typedef struct PDMIAUDIOCONNECTOR
874	{
875	/**
876	* Retrieves the current configuration of the host audio backend.
877	*
878	* @returns VBox status code.
879	* @param pInterface Pointer to the interface structure containing the called function pointer.
880	* @param pCfg Where to store the host audio backend configuration data.
881	*/
882	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
883
884	/**
885	* Retrieves the current status of the host audio backend.
886	*
887	* @returns Status of the host audio backend.
888	* @param pInterface Pointer to the interface structure containing the called function pointer.
889	* @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_ANY for the overall
890	* backend status.
891	*/
892	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
893
894	/**
895	* Creates an audio stream.
896	*
897	* @returns VBox status code.
898	* @param pInterface Pointer to the interface structure containing the called function pointer.
899	* @param pCfgHost Stream configuration for host side.
900	* @param pCfgGuest Stream configuration for guest side.
901	* @param ppStream Pointer where to return the created audio stream on success.
902	*/
903	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
904
905	/**
906	* Destroys an audio stream.
907	*
908	* @param pInterface Pointer to the interface structure containing the called function pointer.
909	* @param pStream Pointer to audio stream.
910	*/
911	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
912
913	/**
914	* Adds a reference to the specified audio stream.
915	*
916	* @returns New reference count. UINT32_MAX on error.
917	* @param pInterface Pointer to the interface structure containing the called function pointer.
918	* @param pStream Pointer to audio stream adding the reference to.
919	*/
920	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
921
922	/**
923	* Releases a reference from the specified stream.
924	*
925	* @returns New reference count. UINT32_MAX on error.
926	* @param pInterface Pointer to the interface structure containing the called function pointer.
927	* @param pStream Pointer to audio stream releasing a reference from.
928	*/
929	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
930
931	/**
932	* Reads PCM audio data from the host (input).
933	*
934	* @returns VBox status code.
935	* @param pInterface Pointer to the interface structure containing the called function pointer.
936	* @param pStream Pointer to audio stream to write to.
937	* @param pvBuf Where to store the read data.
938	* @param cbBuf Number of bytes to read.
939	* @param pcbRead Bytes of audio data read. Optional.
940	*/
941	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
942
943	/**
944	* Writes PCM audio data to the host (output).
945	*
946	* @returns VBox status code.
947	* @param pInterface Pointer to the interface structure containing the called function pointer.
948	* @param pStream Pointer to audio stream to read from.
949	* @param pvBuf Audio data to be written.
950	* @param cbBuf Number of bytes to be written.
951	* @param pcbWritten Bytes of audio data written. Optional.
952	*/
953	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
954
955	/**
956	* Controls a specific audio stream.
957	*
958	* @returns VBox status code.
959	* @param pInterface Pointer to the interface structure containing the called function pointer.
960	* @param pStream Pointer to audio stream.
961	* @param enmStreamCmd The stream command to issue.
962	*/
963	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
964
965	/**
966	* Processes stream data.
967	*
968	* @param pInterface Pointer to the interface structure containing the called function pointer.
969	* @param pStream Pointer to audio stream.
970	*/
971	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
972
973	/**
974	* Returns the number of readable data (in bytes) of a specific audio input stream.
975	*
976	* @returns Number of readable data (in bytes).
977	* @param pInterface Pointer to the interface structure containing the called function pointer.
978	* @param pStream Pointer to audio stream.
979	*/
980	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
981
982	/**
983	* Returns the number of writable data (in bytes) of a specific audio output stream.
984	*
985	* @returns Number of writable data (in bytes).
986	* @param pInterface Pointer to the interface structure containing the called function pointer.
987	* @param pStream Pointer to audio stream.
988	*/
989	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
990
991	/**
992	* Returns the status of a specific audio stream.
993	*
994	* @returns Audio stream status
995	* @param pInterface Pointer to the interface structure containing the called function pointer.
996	* @param pStream Pointer to audio stream.
997	*/
998	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
999
1000	/**
1001	* Sets the audio volume of a specific audio stream.
1002	*
1003	* @returns VBox status code.
1004	* @param pInterface Pointer to the interface structure containing the called function pointer.
1005	* @param pStream Pointer to audio stream.
1006	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1007	*/
1008	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1009
1010	/**
1011	* Plays (transfers) available audio samples via the host backend. Only works with output streams.
1012	*
1013	* @returns VBox status code.
1014	* @param pInterface Pointer to the interface structure containing the called function pointer.
1015	* @param pStream Pointer to audio stream.
1016	* @param pcSamplesPlayed Number of samples played. Optional.
1017	*/
1018	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
1019
1020	/**
1021	* Captures (transfers) available audio samples from the host backend. Only works with input streams.
1022	*
1023	* @returns VBox status code.
1024	* @param pInterface Pointer to the interface structure containing the called function pointer.
1025	* @param pStream Pointer to audio stream.
1026	* @param pcSamplesCaptured Number of samples captured. Optional.
1027	*/
1028	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
1029
1030	#ifdef VBOX_WITH_AUDIO_DEVICE_CALLBACKS
1031	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
1032	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCBTYPE enmType, void *pvUser, size_t cbUser));
1033	#endif
1034
1035	} PDMIAUDIOCONNECTOR;
1036
1037	/** PDMIAUDIOCONNECTOR interface ID. */
1038	#define PDMIAUDIOCONNECTOR_IID "FF2044D1-F8D9-4F42-BE9E-0E9AD14F4552"
1039
1040	/**
1041	* Assigns all needed interface callbacks for an audio backend.
1042	*
1043	* @param a_Prefix The function name prefix.
1044	*/
1045	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_Prefix) \
1046	do { \
1047	pThis->IHostAudio.pfnInit = RT_CONCAT(a_Prefix,Init); \
1048	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_Prefix,Shutdown); \
1049	pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_Prefix,GetConfig); \
1050	/** @todo Add pfnGetDevices here as soon as supported by all backends. */ \
1051	pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_Prefix,GetStatus); \
1052	/** @todo Ditto for pfnSetCallback. */ \
1053	pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_Prefix,StreamCreate); \
1054	pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_Prefix,StreamDestroy); \
1055	pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_Prefix,StreamControl); \
1056	pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_Prefix,StreamGetStatus); \
1057	pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_Prefix,StreamIterate); \
1058	pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_Prefix,StreamPlay); \
1059	pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_Prefix,StreamCapture); \
1060	} while (0)
1061
1062	/**
1063	* PDM host audio interface.
1064	*/
1065	typedef struct PDMIHOSTAUDIO
1066	{
1067	/**
1068	* Initializes the host backend (driver).
1069	*
1070	* @returns VBox status code.
1071	* @param pInterface Pointer to the interface structure containing the called function pointer.
1072	*/
1073	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1074
1075	/**
1076	* Shuts down the host backend (driver).
1077	*
1078	* @returns VBox status code.
1079	* @param pInterface Pointer to the interface structure containing the called function pointer.
1080	*/
1081	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1082
1083	/**
1084	* Returns the host backend's configuration (backend).
1085	*
1086	* @returns VBox status code.
1087	* @param pInterface Pointer to the interface structure containing the called function pointer.
1088	* @param pBackendCfg Where to store the backend audio configuration to.
1089	*/
1090	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1091
1092	/**
1093	* Returns (enumerates) host audio device information.
1094	*
1095	* @returns VBox status code.
1096	* @param pInterface Pointer to the interface structure containing the called function pointer.
1097	* @param pDeviceEnum Where to return the enumerated audio devices.
1098	*/
1099	DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIODEVICEENUM pDeviceEnum));
1100
1101	/**
1102	* Returns the current status from the audio backend.
1103	*
1104	* @returns PDMAUDIOBACKENDSTS enum.
1105	* @param pInterface Pointer to the interface structure containing the called function pointer.
1106	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
1107	*/
1108	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1109
1110	/**
1111	* Sets a callback the audio backend can call. Optional.
1112	*
1113	* @returns VBox status code.
1114	* @param pInterface Pointer to the interface structure containing the called function pointer.
1115	* @param pfnCallback The callback function to use, or NULL when unregistering.
1116	*/
1117	DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1118
1119	/**
1120	* Creates an audio stream using the requested stream configuration.
1121	* If a backend is not able to create this configuration, it will return its best match in the acquired configuration
1122	* structure on success.
1123	*
1124	* @returns VBox status code.
1125	* @param pInterface Pointer to the interface structure containing the called function pointer.
1126	* @param pStream Pointer to audio stream.
1127	* @param pCfgReq Pointer to requested stream configuration.
1128	* @param pCfgAcq Pointer to acquired stream configuration.
1129	*/
1130	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1131
1132	/**
1133	* Destroys an audio stream.
1134	*
1135	* @returns VBox status code.
1136	* @param pInterface Pointer to the interface structure containing the called function pointer.
1137	* @param pStream Pointer to audio stream.
1138	*/
1139	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1140
1141	/**
1142	* Controls an audio stream.
1143	*
1144	* @returns VBox status code.
1145	* @param pInterface Pointer to the interface structure containing the called function pointer.
1146	* @param pStream Pointer to audio stream.
1147	* @param enmStreamCmd The stream command to issue.
1148	*/
1149	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1150
1151	/**
1152	* Returns whether the specified audio direction in the backend is enabled or not.
1153	*
1154	* @returns PDMAUDIOSTRMSTS
1155	* @param pInterface Pointer to the interface structure containing the called function pointer.
1156	* @param pStream Pointer to audio stream.
1157	*/
1158	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1159
1160	/**
1161	* Gives the host backend the chance to do some (necessary) iteration work.
1162	*
1163	* @returns VBox status code.
1164	* @param pInterface Pointer to the interface structure containing the called function pointer.
1165	* @param pStream Pointer to audio stream.
1166	*/
1167	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1168
1169	/**
1170	* Plays (writes to) an audio (output) stream.
1171	*
1172	* @returns VBox status code.
1173	* @param pInterface Pointer to the interface structure containing the called function pointer.
1174	* @param pStream Pointer to audio stream.
1175	* @param pvBuf Pointer to audio data buffer to play.
1176	* @param cbBuf Size (in bytes) of audio data buffer.
1177	* @param pcbWritten Returns number of bytes written. Optional.
1178	*/
1179	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1180
1181	/**
1182	* Captures (reads from) an audio (input) stream.
1183	*
1184	* @returns VBox status code.
1185	* @param pInterface Pointer to the interface structure containing the called function pointer.
1186	* @param pStream Pointer to audio stream.
1187	* @param pvBuf Buffer where to store read audio data.
1188	* @param cbBuf Size (in bytes) of buffer.
1189	* @param pcbRead Returns number of bytes read. Optional.
1190	*/
1191	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1192
1193	} PDMIHOSTAUDIO;
1194
1195	/** PDMIHOSTAUDIO interface ID. */
1196	#define PDMIHOSTAUDIO_IID "C45550DE-03C0-4A45-9A96-C5EB956F806D"
1197
1198	/** @} */
1199
1200	#endif /* !___VBox_vmm_pdmaudioifs_h */
1201

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

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

Download in other formats: