pdmaudioifs.h@ 59420

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

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

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

Download in other formats: