pdmaudioifs.h@ 65624

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

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

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

Download in other formats: