pdmaudioifs.h@ 58920

Last change on this file since 58920 was 58600, checked in by vboxsync, 9 years ago
Audio: Introduced reference counting for guest audio streams; this should prevent that the audio connector interface is destroying streams which still are being used by other parties, e.g. the audio mixer (bugref:8054).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 26.8 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2015 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 <VBox/types.h>
30	#include <iprt/list.h>
31
32
33	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
34	* @ingroup grp_pdm_interfaces
35	* @{
36	*/
37
38	/** @todo r=bird: Don't be lazy with documentation! */
39	typedef uint32_t PDMAUDIODRVFLAGS;
40
41	/** No flags set. */
42	/** @todo r=bird: s/PDMAUDIODRVFLAG/PDMAUDIODRV_FLAGS/g */
43	#define PDMAUDIODRVFLAG_NONE 0
44	/** Marks a primary audio driver which is critical
45	* when running the VM. */
46	#define PDMAUDIODRVFLAG_PRIMARY RT_BIT(0)
47
48	/**
49	* Audio format in signed or unsigned variants.
50	*/
51	typedef enum PDMAUDIOFMT
52	{
53	AUD_FMT_INVALID,
54	AUD_FMT_U8,
55	AUD_FMT_S8,
56	AUD_FMT_U16,
57	AUD_FMT_S16,
58	AUD_FMT_U32,
59	AUD_FMT_S32,
60	/** Hack to blow the type up to 32-bit. */
61	AUD_FMT_32BIT_HACK = 0x7fffffff
62	} PDMAUDIOFMT;
63
64	/**
65	* Audio configuration of a certain backend.
66	*/
67	typedef struct PDMAUDIOBACKENDCFG
68	{
69	uint32_t cbStreamOut;
70	uint32_t cbStreamIn;
71	uint32_t cMaxHstStrmsOut;
72	uint32_t cMaxHstStrmsIn;
73	} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
74
75	/**
76	* An audio sample. At the moment stereo (left + right channels) only.
77	* @todo Replace this with a more generic union
78	* which then also could handle 2.1 or 5.1 sound.
79	*/
80	typedef struct PDMAUDIOSAMPLE
81	{
82	int64_t i64LSample;
83	int64_t i64RSample;
84	} PDMAUDIOSAMPLE, *PPDMAUDIOSAMPLE;
85
86	typedef enum PDMAUDIOENDIANNESS
87	{
88	/** The usual invalid endian. */
89	PDMAUDIOENDIANNESS_INVALID,
90	/** Little endian. */
91	PDMAUDIOENDIANNESS_LITTLE,
92	/** Bit endian. */
93	PDMAUDIOENDIANNESS_BIG,
94	/** Endianness doesn't have a meaning in the context. */
95	PDMAUDIOENDIANNESS_NA,
96	/** The end of the valid endian values (exclusive). */
97	PDMAUDIOENDIANNESS_END,
98	/** Hack to blow the type up to 32-bit. */
99	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
100	} PDMAUDIOENDIANNESS;
101
102	typedef struct PDMAUDIOSTREAMCFG
103	{
104	/** Frequency in Hertz (Hz). */
105	uint32_t uHz;
106	/** Number of channels (2 for stereo). */
107	uint8_t cChannels;
108	/** Audio format. */
109	PDMAUDIOFMT enmFormat;
110	/** @todo Use RT_LE2H_? /
111	PDMAUDIOENDIANNESS enmEndianness;
112	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
113
114	#if defined(RT_LITTLE_ENDIAN)
115	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
116	#elif defined(RT_BIG_ENDIAN)
117	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
118	#else
119	# error "Port me!"
120	#endif
121
122	/**
123	* Audio direction.
124	*/
125	typedef enum PDMAUDIODIR
126	{
127	PDMAUDIODIR_UNKNOWN = 0,
128	PDMAUDIODIR_IN = 1,
129	PDMAUDIODIR_OUT = 2,
130	PDMAUDIODIR_DUPLEX = 3,
131	/** Hack to blow the type up to 32-bit. */
132	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
133	} PDMAUDIODIR;
134
135	/**
136	* Audio mixer controls.
137	*/
138	typedef enum PDMAUDIOMIXERCTL
139	{
140	PDMAUDIOMIXERCTL_UNKNOWN = 0,
141	PDMAUDIOMIXERCTL_VOLUME,
142	PDMAUDIOMIXERCTL_PCM,
143	PDMAUDIOMIXERCTL_LINE_IN,
144	PDMAUDIOMIXERCTL_MIC_IN,
145	/** Hack to blow the type up to 32-bit. */
146	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
147	} PDMAUDIOMIXERCTL;
148
149	/**
150	* Audio recording sources.
151	*/
152	typedef enum PDMAUDIORECSOURCE
153	{
154	PDMAUDIORECSOURCE_UNKNOWN = 0,
155	PDMAUDIORECSOURCE_MIC,
156	PDMAUDIORECSOURCE_CD,
157	PDMAUDIORECSOURCE_VIDEO,
158	PDMAUDIORECSOURCE_AUX,
159	PDMAUDIORECSOURCE_LINE_IN,
160	PDMAUDIORECSOURCE_PHONE,
161	/** Hack to blow the type up to 32-bit. */
162	PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
163	} PDMAUDIORECSOURCE;
164
165	/**
166	* Audio stream commands. Used in the audio connector
167	* as well as in the actual host backends.
168	*/
169	typedef enum PDMAUDIOSTREAMCMD
170	{
171	/** Unknown command, do not use. */
172	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
173	/** Enables the stream. */
174	PDMAUDIOSTREAMCMD_ENABLE,
175	/** Disables the stream. */
176	PDMAUDIOSTREAMCMD_DISABLE,
177	/** Pauses the stream. */
178	PDMAUDIOSTREAMCMD_PAUSE,
179	/** Resumes the stream. */
180	PDMAUDIOSTREAMCMD_RESUME,
181	/** Hack to blow the type up to 32-bit. */
182	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
183	} PDMAUDIOSTREAMCMD;
184
185	/**
186	* Properties of audio streams for host/guest
187	* for in or out directions.
188	*/
189	typedef struct PDMPCMPROPS
190	{
191	/** Sample width. Bits per sample. */
192	uint8_t cBits;
193	/** Signed or unsigned sample. */
194	bool fSigned;
195	/** Shift count used for faster calculation of various
196	* values, such as the alignment, bytes to samples and so on.
197	* Depends on number of stream channels and the stream format
198	* being used.
199	*
200	** @todo Use some RTAsmXXX functions instead?
201	*/
202	uint8_t cShift;
203	/** Number of audio channels. */
204	uint8_t cChannels;
205	/** Alignment mask. */
206	uint32_t uAlign;
207	/** Sample frequency in Hertz (Hz). */
208	uint32_t uHz;
209	/** Bandwidth (bytes/s). */
210	uint32_t cbPerSec;
211	/** Whether the endianness is swapped or not. */
212	bool fSwapEndian;
213	} PDMPCMPROPS, *PPDMPCMPROPS;
214
215	/**
216	* Structure keeping an audio volume level.
217	*/
218	typedef struct PDMAUDIOVOLUME
219	{
220	/** Set to @c true if this stream is muted, @c false if not. */
221	bool fMuted;
222	/** Left channel volume. */
223	uint32_t uLeft;
224	/** Right channel volume. */
225	uint32_t uRight;
226	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
227
228	/**
229	* Structure for holding rate processing information
230	* of a source + destination audio stream. This is needed
231	* because both streams can differ regarding their rates
232	* and therefore need to be treated accordingly.
233	*/
234	typedef struct PDMAUDIOSTRMRATE
235	{
236	/** Current (absolute) offset in the output
237	* (destination) stream. */
238	uint64_t dstOffset;
239	/** Increment for moving dstOffset for the
240	* destination stream. This is needed because the
241	* source <-> destination rate might be different. */
242	uint64_t dstInc;
243	/** Current (absolute) offset in the input
244	* stream. */
245	uint32_t srcOffset;
246	/** Last processed sample of the input stream.
247	* Needed for interpolation. */
248	PDMAUDIOSAMPLE srcSampleLast;
249	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
250
251	/**
252	* Note: All internal handling is done in samples,
253	* not in bytes!
254	*/
255	typedef uint32_t PDMAUDIOMIXBUFFMT;
256	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
257
258	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
259	typedef struct PDMAUDIOMIXBUF
260	{
261	RTLISTNODE Node;
262	/** Name of the buffer. */
263	char *pszName;
264	/** Sample buffer. */
265	PPDMAUDIOSAMPLE pSamples;
266	/** Size of the sample buffer (in samples). */
267	uint32_t cSamples;
268	/** The current read/write position (in samples)
269	* in the samples buffer. */
270	uint32_t offReadWrite;
271	/**
272	* Total samples already mixed down to the parent buffer (if any). Always starting at
273	* the parent's offReadWrite position.
274	*
275	* Note: Count always is specified in parent samples, as the sample count can differ between parent
276	* and child.
277	*/
278	uint32_t cMixed;
279	uint32_t cProcessed;
280	/** Pointer to parent buffer (if any). */
281	PPDMAUDIOMIXBUF pParent;
282	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
283	RTLISTANCHOR lstBuffers;
284	/** Intermediate structure for buffer conversion tasks. */
285	PPDMAUDIOSTRMRATE pRate;
286	/** Current volume used for mixing. */
287	PDMAUDIOVOLUME Volume;
288	/** This buffer's audio format. */
289	PDMAUDIOMIXBUFFMT AudioFmt;
290	/**
291	* Ratio of the associated parent stream's frequency by this stream's
292	* frequency (1<<32), represented as a signed 64 bit integer.
293	*
294	* For example, if the parent stream has a frequency of 44 khZ, and this
295	* stream has a frequency of 11 kHz, the ration then would be
296	* (44/11 * (1 << 32)).
297	*
298	* Currently this does not get changed once assigned.
299	*/
300	int64_t iFreqRatio;
301	/* For quickly converting samples <-> bytes and
302	* vice versa. */
303	uint8_t cShift;
304	} PDMAUDIOMIXBUF;
305
306	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
307	typedef uint32_t PDMAUDIOSTRMSTS;
308
309	/** No flags being set. */
310	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
311	/** Whether this stream General Enabled or disabled flag. */
312	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(0)
313	/** Whether this stream has been paused or not. This also implies
314	* that this is an enabled stream! */
315	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(1)
316	/** Whether this stream was marked as being disabled
317	* but there are still associated guest output streams
318	* which rely on its data. */
319	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(2)
320	/** Validation mask. */
321	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x00000007)
322
323	/**
324	* Represents an audio input on the host of a certain
325	* backend (e.g. DirectSound, PulseAudio etc).
326	*
327	* One host audio input is assigned to exactly one parent
328	* guest input stream.
329	*/
330	struct PDMAUDIOGSTSTRMIN;
331	typedef PDMAUDIOGSTSTRMIN *PPDMAUDIOGSTSTRMIN;
332
333	typedef struct PDMAUDIOHSTSTRMIN
334	{
335	/** List node. */
336	RTLISTNODE Node;
337	/** PCM properties. */
338	PDMPCMPROPS Props;
339	/** Stream status flag. */
340	PDMAUDIOSTRMSTS fStatus;
341	/** This stream's mixing buffer. */
342	PDMAUDIOMIXBUF MixBuf;
343	/** Pointer to (parent) guest stream. */
344	PPDMAUDIOGSTSTRMIN pGstStrmIn;
345	} PDMAUDIOHSTSTRMIN, *PPDMAUDIOHSTSTRMIN;
346
347	/*
348	* Represents an audio output on the host through a certain
349	* backend (e.g. DirectSound, PulseAudio etc).
350	*
351	* One host audio output can have multiple (1:N) guest outputs
352	* assigned.
353	*/
354	typedef struct PDMAUDIOHSTSTRMOUT
355	{
356	/** List node. */
357	RTLISTNODE Node;
358	/** Stream properites. */
359	PDMPCMPROPS Props;
360	/** Stream status flag. */
361	PDMAUDIOSTRMSTS fStatus;
362	/** This stream's mixing buffer. */
363	PDMAUDIOMIXBUF MixBuf;
364	/** Associated guest output streams. */
365	RTLISTANCHOR lstGstStrmOut;
366	} PDMAUDIOHSTSTRMOUT, *PPDMAUDIOHSTSTRMOUT;
367
368	/**
369	* Guest audio stream state.
370	*/
371	typedef struct PDMAUDIOGSTSTRMSTATE
372	{
373	/** Guest audio out stream active or not. */
374	bool fActive;
375	/** Guest audio output stream has some samples or not. */
376	bool fEmpty;
377	/** Name of this stream. */
378	char *pszName;
379	/** Number of references to this stream. Only can be
380	* destroyed if the reference count is reaching 0. */
381	uint8_t cRefs;
382	} PDMAUDIOGSTSTRMSTATE, *PPDMAUDIOGSTSTRMSTATE;
383
384	/**
385	* Represents an audio input from the guest (that is, from the
386	* emulated device, e.g. Intel HDA).
387	*
388	* Each guest input can have multiple host input streams.
389	*/
390	typedef struct PDMAUDIOGSTSTRMIN
391	{
392	/** Guest stream properites. */
393	PDMPCMPROPS Props;
394	/** Current stream state. */
395	PDMAUDIOGSTSTRMSTATE State;
396	/** This stream's mixing buffer. */
397	PDMAUDIOMIXBUF MixBuf;
398	/** Pointer to associated host input stream. */
399	PPDMAUDIOHSTSTRMIN pHstStrmIn;
400	} PDMAUDIOGSTSTRMIN, *PPDMAUDIOGSTSTRMIN;
401
402	/**
403	* Represents an audio output from the guest (that is, from the
404	* emulated device, e.g. Intel HDA).
405	*
406	* Each guest output is assigned to a single host output.
407	*/
408	typedef struct PDMAUDIOGSTSTRMOUT
409	{
410	/** List node. */
411	RTLISTNODE Node;
412	/** Guest output stream properites. */
413	PDMPCMPROPS Props;
414	/** Current stream state. */
415	PDMAUDIOGSTSTRMSTATE State;
416	/** This stream's mixing buffer. */
417	PDMAUDIOMIXBUF MixBuf;
418	/** Pointer to the associated host output stream. */
419	PPDMAUDIOHSTSTRMOUT pHstStrmOut;
420	} PDMAUDIOGSTSTRMOUT, *PPDMAUDIOGSTSTRMOUT;
421
422	/** Pointer to a audio connector interface. */
423	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
424	/**
425	* Audio connector interface (up).
426	*/
427	typedef struct PDMIAUDIOCONNECTOR
428	{
429	DECLR3CALLBACKMEMBER(int, pfnQueryStatus, (PPDMIAUDIOCONNECTOR pInterface, uint32_t pcbAvailIn, uint32_t pcbFreeOut, uint32_t *pcSamplesLive));
430
431	/**
432	* Reads PCM audio data from the host (input).
433	*
434	* @returns VBox status code.
435	* @param pInterface Pointer to the interface structure containing the called function pointer.
436	* @param pGstStrmIn Pointer to guest input stream to write to.
437	* @param pvBuf Where to store the read data.
438	* @param cbSize Number of bytes to read.
439	* @param pcbRead Bytes of audio data read. Optional.
440	*/
441	DECLR3CALLBACKMEMBER(int, pfnRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, void pvBuf, uint32_t cbSize, uint32_t pcbRead));
442
443	/**
444	* Writes PCM audio data to the host (output).
445	*
446	* @returns VBox status code.
447	* @param pInterface Pointer to the interface structure containing the called function pointer.
448	* @param pGstStrmOut Pointer to guest output stream to read from.
449	* @param pvBuf Audio data to be written.
450	* @param cbSize Number of bytes to be written.
451	* @param pcbWritten Bytes of audio data written. Optional.
452	*/
453	DECLR3CALLBACKMEMBER(int, pfnWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, const void pvBuf, uint32_t cbSize, uint32_t pcbWritten));
454
455	/**
456	* Checks whether a specific guest input stream is active or not.
457	*
458	* @returns Whether the specified stream is active or not.
459	* @param pInterface Pointer to the interface structure containing the called function pointer.
460	* @param pGstStrmIn Pointer to guest input stream.
461	*/
462	DECLR3CALLBACKMEMBER(bool, pfnIsActiveIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
463
464	/**
465	* Checks whether a specific guest output stream is active or not.
466	*
467	* @returns Whether the specified stream is active or not.
468	* @param pInterface Pointer to the interface structure containing the called function pointer.
469	* @param pGstStrmOut Pointer to guest output stream.
470	*/
471	DECLR3CALLBACKMEMBER(bool, pfnIsActiveOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
472
473	/**
474	* Checks whether the specified guest input stream is in a working state.
475	*
476	* @returns True if a host voice in is available, false if not.
477	* @param pInterface Pointer to the interface structure containing the called function pointer.
478	* @param pGstStrmIn Pointer to guest input stream to check.
479	*/
480	DECLR3CALLBACKMEMBER(bool, pfnIsInputOK, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
481
482	/**
483	* Checks whether the specified guest output stream is in a working state.
484	*
485	* @returns True if a host voice out is available, false if not.
486	* @param pInterface Pointer to the interface structure containing the called function pointer.
487	* @param pGstStrmOut Pointer to guest output stream to check.
488	*/
489	DECLR3CALLBACKMEMBER(bool, pfnIsOutputOK, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
490
491	/**
492	* Initializes the NULL audio driver as a fallback in case no host backend is available.
493	*
494	* @returns VBox status code.
495	* @param pInterface Pointer to the interface structure containing the called function pointer.
496	*/
497	DECLR3CALLBACKMEMBER(int, pfnInitNull, (PPDMIAUDIOCONNECTOR pInterface));
498
499	/**
500	* Enables a specific guest output stream and starts the audio device.
501	*
502	* @returns VBox status code.
503	* @param pInterface Pointer to the interface structure containing the called function pointer.
504	* @param pGstStrmOut Pointer to guest output stream.
505	* @param fEnable Whether to enable or disable the specified output stream.
506	*/
507	DECLR3CALLBACKMEMBER(int, pfnEnableOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, bool fEnable));
508
509	/**
510	* Enables a specific guest input stream and starts the audio device.
511	*
512	* @returns VBox status code.
513	* @param pInterface Pointer to the interface structure containing the called function pointer.
514	* @param pGstStrmIn Pointer to guest input stream.
515	* @param fEnable Whether to enable or disable the specified input stream.
516	*/
517	DECLR3CALLBACKMEMBER(int, pfnEnableIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, bool fEnable));
518
519	/**
520	* Creates a guest input stream.
521	*
522	* @returns VBox status code.
523	* @param pInterface Pointer to the interface structure containing the called function pointer.
524	* @param pszName Name of the audio channel.
525	* @param enmRecSource Specifies the type of recording source to be opened.
526	* @param pCfg Pointer to PDMAUDIOSTREAMCFG to use.
527	* @param ppGstStrmIn Pointer where to return the guest guest input stream on success.
528	*/
529	DECLR3CALLBACKMEMBER(int, pfnCreateIn, (PPDMIAUDIOCONNECTOR pInterface, const char *pszName,
530	PDMAUDIORECSOURCE enmRecSource, PPDMAUDIOSTREAMCFG pCfg,
531	PPDMAUDIOGSTSTRMIN *ppGstStrmIn));
532
533	/**
534	* Creates a guest output stream.
535	*
536	* @returns VBox status code.
537	* @param pInterface Pointer to the interface structure containing the called function pointer.
538	* @param pszName Name of the audio channel.
539	* @param pCfg Pointer to PDMAUDIOSTREAMCFG to use.
540	* @param ppGstStrmOut Pointer where to return the guest guest input stream on success.
541	*/
542	DECLR3CALLBACKMEMBER(int, pfnCreateOut, (PPDMIAUDIOCONNECTOR pInterface, const char *pszName,
543	PPDMAUDIOSTREAMCFG pCfg, PPDMAUDIOGSTSTRMOUT *ppGstStrmOut));
544
545	/**
546	* Destroys a guest input stream.
547	*
548	* @param pInterface Pointer to the interface structure containing the called function pointer.
549	* @param pGstStrmIn Pointer to guest input stream.
550	*/
551	DECLR3CALLBACKMEMBER(void, pfnDestroyIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
552
553	/**
554	* Destroys a guest output stream.
555	*
556	* @param pInterface Pointer to the interface structure containing the called function pointer.
557	* @param pGstStrmOut Pointer to guest output stream.
558	*/
559	DECLR3CALLBACKMEMBER(void, pfnDestroyOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
560
561	/**
562	* Plays (transfers) all available samples via the connected host backend.
563	*
564	* @returns VBox status code.
565	* @param pInterface Pointer to the interface structure containing the called function pointer.
566	* @param pcSamplesPlayed Number of samples played. Optional.
567	*/
568	DECLR3CALLBACKMEMBER(int, pfnPlayOut, (PPDMIAUDIOCONNECTOR pInterface, uint32_t *pcSamplesPlayed));
569
570	} PDMIAUDIOCONNECTOR;
571
572	/** PDMIAUDIOCONNECTOR interface ID. */
573	#define PDMIAUDIOCONNECTOR_IID "7bbb9565-8dd2-4fab-81d6-4d78985e5daa"
574
575
576	/**
577	* Assign all needed interface callbacks for an audio backend.
578	*
579	* @param a_NamePrefix The function name prefix.
580	*/
581	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_NamePrefix) \
582	do { \
583	pThis->IHostAudio.pfnInit = RT_CONCAT(a_NamePrefix,Init); \
584	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_NamePrefix,Shutdown); \
585	pThis->IHostAudio.pfnInitIn = RT_CONCAT(a_NamePrefix,InitIn); \
586	pThis->IHostAudio.pfnInitOut = RT_CONCAT(a_NamePrefix,InitOut); \
587	pThis->IHostAudio.pfnControlOut = RT_CONCAT(a_NamePrefix,ControlOut); \
588	pThis->IHostAudio.pfnControlIn = RT_CONCAT(a_NamePrefix,ControlIn); \
589	pThis->IHostAudio.pfnFiniIn = RT_CONCAT(a_NamePrefix,FiniIn); \
590	pThis->IHostAudio.pfnFiniOut = RT_CONCAT(a_NamePrefix,FiniOut); \
591	pThis->IHostAudio.pfnIsEnabled = RT_CONCAT(a_NamePrefix,IsEnabled); \
592	pThis->IHostAudio.pfnPlayOut = RT_CONCAT(a_NamePrefix,PlayOut); \
593	pThis->IHostAudio.pfnCaptureIn = RT_CONCAT(a_NamePrefix,CaptureIn); \
594	pThis->IHostAudio.pfnGetConf = RT_CONCAT(a_NamePrefix,GetConf); \
595	} while (0)
596
597	/** Pointer to a host audio interface. */
598	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
599	/**
600	* PDM host audio interface.
601	*/
602	typedef struct PDMIHOSTAUDIO
603	{
604	/**
605	* Initialize the host-specific audio device.
606	*
607	* @returns VBox status code.
608	* @param pInterface Pointer to the interface structure containing the called function pointer.
609	*/
610	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
611
612	/**
613	* Shuts down the host-specific audio device.
614	*
615	* @returns VBox status code.
616	* @param pInterface Pointer to the interface structure containing the called function pointer.
617	*/
618	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
619
620	/**
621	* Initialize the host-specific audio device for input stream.
622	*
623	* @returns VBox status code.
624	* @param pInterface Pointer to the interface structure containing the called function pointer.
625	* @param pHstStrmIn Pointer to host input stream.
626	* @param pStreamCfg Pointer to stream configuration.
627	* @param enmRecSource Specifies the type of recording source to be initialized.
628	* @param pcSamples Returns how many samples the backend can handle. Optional.
629	*/
630	DECLR3CALLBACKMEMBER(int, pfnInitIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PPDMAUDIOSTREAMCFG pStreamCfg, PDMAUDIORECSOURCE enmRecSource, uint32_t *pcSamples));
631
632	/**
633	* Initialize the host-specific output device for output stream.
634	*
635	* @returns VBox status code.
636	* @param pInterface Pointer to the interface structure containing the called function pointer.
637	* @param pHstStrmOut Pointer to host output stream.
638	* @param pStreamCfg Pointer to stream configuration.
639	* @param pcSamples Returns how many samples the backend can handle. Optional.
640	*/
641	DECLR3CALLBACKMEMBER(int, pfnInitOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PPDMAUDIOSTREAMCFG pStreamCfg, uint32_t *pcSamples));
642
643	/**
644	* Control the host audio device for an input stream.
645	*
646	* @returns VBox status code.
647	* @param pInterface Pointer to the interface structure containing the called function pointer.
648	* @param pHstStrmOut Pointer to host output stream.
649	* @param enmStreamCmd The stream command to issue.
650	*/
651	DECLR3CALLBACKMEMBER(int, pfnControlOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PDMAUDIOSTREAMCMD enmStreamCmd));
652
653	/**
654	* Control the host audio device for an output stream.
655	*
656	* @returns VBox status code.
657	* @param pInterface Pointer to the interface structure containing the called function pointer.
658	* @param pHstStrmOut Pointer to host output stream.
659	* @param enmStreamCmd The stream command to issue.
660	*/
661	DECLR3CALLBACKMEMBER(int, pfnControlIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PDMAUDIOSTREAMCMD enmStreamCmd));
662
663	/**
664	* Ends the host audio input streamm.
665	*
666	* @returns VBox status code.
667	* @param pInterface Pointer to the interface structure containing the called function pointer.
668	* @param pHstStrmIn Pointer to host input stream.
669	*/
670	DECLR3CALLBACKMEMBER(int, pfnFiniIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn));
671
672	/**
673	* Ends the host output stream.
674	*
675	* @returns VBox status code.
676	* @param pInterface Pointer to the interface structure containing the called function pointer.
677	* @param pHstStrmOut Pointer to host output stream.
678	*/
679	DECLR3CALLBACKMEMBER(int, pfnFiniOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut));
680
681	/**
682	* Returns whether the specified audio direction in the backend is enabled or not.
683	*
684	* @param pInterface Pointer to the interface structure containing the called function pointer.
685	* @param enmDir Audio direction to check status for.
686	*/
687	DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
688
689	/**
690	* Plays a host audio stream.
691	*
692	* @returns VBox status code.
693	* @param pInterface Pointer to the interface structure containing the called function pointer.
694	* @param pHstStrmOut Pointer to host output stream.
695	* @param pcSamplesPlayed Pointer to number of samples captured.
696	*/
697	DECLR3CALLBACKMEMBER(int, pfnPlayOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, uint32_t *pcSamplesPlayed));
698
699	/**
700	* Records audio to input stream.
701	*
702	* @returns VBox status code.
703	* @param pInterface Pointer to the interface structure containing the called function pointer.
704	* @param pHstStrmIn Pointer to host input stream.
705	* @param pcSamplesCaptured Pointer to number of samples captured.
706	*/
707	DECLR3CALLBACKMEMBER(int, pfnCaptureIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, uint32_t *pcSamplesCaptured));
708
709	/**
710	* Gets the configuration from the host audio (backend) driver.
711	*
712	* @returns VBox status code.
713	* @param pInterface Pointer to the interface structure containing the called function pointer.
714	* @param pBackendCfg Pointer where to store the backend audio configuration to.
715	*/
716	DECLR3CALLBACKMEMBER(int, pfnGetConf, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
717
718	} PDMIHOSTAUDIO;
719
720	/** PDMIHOSTAUDIO interface ID. */
721	#define PDMIHOSTAUDIO_IID "39feea4f-c824-4197-bcff-7d4a6ede7420"
722
723	/** @} */
724
725	#endif /* !___VBox_vmm_pdmaudioifs_h */
726

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

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

Download in other formats: