pdmaudioifs.h@ 61050

Last change on this file since 61050 was 61050, checked in by vboxsync, 9 years ago
Audio: Update.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 34.2 KB

Line
1	/** @file
2	* PDM - Pluggable Device Manager, audio interfaces.
3	*/
4
5	/*
6	* Copyright (C) 2006-2016 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_vmm_pdmaudioifs_h
27	#define ___VBox_vmm_pdmaudioifs_h
28
29	#include <VBox/types.h>
30	#include <iprt/circbuf.h>
31	#include <iprt/critsect.h>
32	#include <iprt/list.h>
33
34
35	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
36	* @ingroup grp_pdm_interfaces
37	* @{
38	*/
39
40	/** @todo r=bird: Don't be lazy with documentation! */
41	typedef uint32_t PDMAUDIODRVFLAGS;
42
43	/** No flags set. */
44	/** @todo r=bird: s/PDMAUDIODRVFLAG/PDMAUDIODRV_FLAGS/g */
45	#define PDMAUDIODRVFLAG_NONE 0
46	/** Marks a primary audio driver which is critical
47	* when running the VM. */
48	#define PDMAUDIODRVFLAG_PRIMARY RT_BIT(0)
49
50	/**
51	* Audio format in signed or unsigned variants.
52	*/
53	typedef enum PDMAUDIOFMT
54	{
55	PDMAUDIOFMT_INVALID,
56	PDMAUDIOFMT_U8,
57	PDMAUDIOFMT_S8,
58	PDMAUDIOFMT_U16,
59	PDMAUDIOFMT_S16,
60	PDMAUDIOFMT_U32,
61	PDMAUDIOFMT_S32,
62	/** Hack to blow the type up to 32-bit. */
63	PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
64	} PDMAUDIOFMT;
65
66	/**
67	* Audio configuration of a certain host backend.
68	*/
69	typedef struct PDMAUDIOBACKENDCFG
70	{
71	/** Size (in bytes) of the host backend's audio output stream structure. */
72	size_t cbStreamOut;
73	/** Size (in bytes) of the host backend's audio input stream structure. */
74	size_t cbStreamIn;
75	/** Number of valid output sinks found on the host. */
76	uint8_t cSinks;
77	/** Number of valid input sources found on the host. */
78	uint8_t cSources;
79	/** Number of concurrent output streams supported on the host.
80	* UINT32_MAX for unlimited concurrent streams. */
81	uint32_t cMaxStreamsOut;
82	/** Number of concurrent input streams supported on the host.
83	* UINT32_MAX for unlimited concurrent streams. */
84	uint32_t cMaxStreamsIn;
85	} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
86
87	/**
88	* A single audio sample, representing left and right channels (stereo).
89	*/
90	typedef struct PDMAUDIOSAMPLE
91	{
92	int64_t i64LSample;
93	int64_t i64RSample;
94	} PDMAUDIOSAMPLE, *PPDMAUDIOSAMPLE;
95
96	typedef enum PDMAUDIOENDIANNESS
97	{
98	/** The usual invalid endian. */
99	PDMAUDIOENDIANNESS_INVALID,
100	/** Little endian. */
101	PDMAUDIOENDIANNESS_LITTLE,
102	/** Bit endian. */
103	PDMAUDIOENDIANNESS_BIG,
104	/** Endianness doesn't have a meaning in the context. */
105	PDMAUDIOENDIANNESS_NA,
106	/** The end of the valid endian values (exclusive). */
107	PDMAUDIOENDIANNESS_END,
108	/** Hack to blow the type up to 32-bit. */
109	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
110	} PDMAUDIOENDIANNESS;
111
112	/**
113	* Audio direction.
114	*/
115	typedef enum PDMAUDIODIR
116	{
117	PDMAUDIODIR_UNKNOWN = 0,
118	PDMAUDIODIR_IN = 1,
119	PDMAUDIODIR_OUT = 2,
120	PDMAUDIODIR_DUPLEX = 3,
121	/** Hack to blow the type up to 32-bit. */
122	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
123	} PDMAUDIODIR;
124
125	/**
126	* Audio playback destinations.
127	*/
128	typedef enum PDMAUDIOPLAYBACKDEST
129	{
130	PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
131	PDMAUDIOPLAYBACKDEST_FRONT,
132	PDMAUDIOPLAYBACKDEST_CENTER_LFE,
133	PDMAUDIOPLAYBACKDEST_REAR,
134	/** Hack to blow the type up to 32-bit. */
135	PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
136	} PDMAUDIOPLAYBACKDEST;
137
138	/**
139	* Audio recording sources.
140	*/
141	typedef enum PDMAUDIORECSOURCE
142	{
143	PDMAUDIORECSOURCE_UNKNOWN = 0,
144	PDMAUDIORECSOURCE_MIC,
145	PDMAUDIORECSOURCE_CD,
146	PDMAUDIORECSOURCE_VIDEO,
147	PDMAUDIORECSOURCE_AUX,
148	PDMAUDIORECSOURCE_LINE,
149	PDMAUDIORECSOURCE_PHONE,
150	/** Hack to blow the type up to 32-bit. */
151	PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
152	} PDMAUDIORECSOURCE;
153
154	/**
155	* Audio stream (data) layout.
156	*/
157	typedef enum PDMAUDIOSTREAMLAYOUT
158	{
159	/** Unknown access type; do not use. */
160	PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
161	/** Non-interleaved access, that is, consecutive
162	* access to the data. */
163	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
164	/** Interleaved access, where the data can be
165	* mixed together with data of other audio streams. */
166	PDMAUDIOSTREAMLAYOUT_INTERLEAVED
167	} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
168
169	/** No stream channel data flags defined. */
170	#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
171
172	/**
173	* Structure for keeping a stream channel data block around.
174	*/
175	typedef struct PDMAUDIOSTREAMCHANNELDATA
176	{
177	/** Circular buffer for the channel data. */
178	PRTCIRCBUF pCircBuf;
179	size_t cbAcq;
180	/** Channel data flags. */
181	uint32_t fFlags;
182	} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
183
184	/**
185	* Structure for a single channel of an audio stream.
186	* An audio stream consists of one or multiple channels,
187	* depending on the configuration.
188	*/
189	typedef struct PDMAUDIOSTREAMCHANNEL
190	{
191	/** Channel ID. */
192	uint8_t uChannel;
193	/** Step size (in bytes) to the channel's next frame. */
194	size_t cbStep;
195	/** Frame size (in bytes) of this channel. */
196	size_t cbFrame;
197	/** Offset (in bytes) to first sample in the data block. */
198	size_t cbFirst;
199	/** Currente offset (in bytes) in the data stream. */
200	size_t cbOff;
201	/** Associated data buffer. */
202	PDMAUDIOSTREAMCHANNELDATA Data;
203	} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
204
205	/**
206	* Structure for keeping an audio stream configuration.
207	*/
208	typedef struct PDMAUDIOSTREAMCFG
209	{
210	/** Friendly name of the stream. */
211	char szName[64];
212	/** Direction of the stream. */
213	PDMAUDIODIR enmDir;
214	union
215	{
216	/** Desired playback destination (for an output stream). */
217	PDMAUDIOPLAYBACKDEST Dest;
218	/** Desired recording source (for an input stream). */
219	PDMAUDIORECSOURCE Source;
220	} DestSource;
221	/** Frequency in Hertz (Hz). */
222	uint32_t uHz;
223	/** Number of audio channels (2 for stereo, 1 for mono). */
224	uint8_t cChannels;
225	/** Audio format. */
226	PDMAUDIOFMT enmFormat;
227	/** @todo Use RT_LE2H_? /
228	PDMAUDIOENDIANNESS enmEndianness;
229	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
230
231	#if defined(RT_LITTLE_ENDIAN)
232	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
233	#elif defined(RT_BIG_ENDIAN)
234	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
235	#else
236	# error "Port me!"
237	#endif
238
239	/**
240	* Audio mixer controls.
241	*/
242	typedef enum PDMAUDIOMIXERCTL
243	{
244	PDMAUDIOMIXERCTL_UNKNOWN = 0,
245	PDMAUDIOMIXERCTL_VOLUME,
246	PDMAUDIOMIXERCTL_FRONT,
247	PDMAUDIOMIXERCTL_CENTER_LFE,
248	PDMAUDIOMIXERCTL_REAR,
249	PDMAUDIOMIXERCTL_LINE_IN,
250	PDMAUDIOMIXERCTL_MIC_IN,
251	/** Hack to blow the type up to 32-bit. */
252	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
253	} PDMAUDIOMIXERCTL;
254
255	/**
256	* Audio stream commands. Used in the audio connector
257	* as well as in the actual host backends.
258	*/
259	typedef enum PDMAUDIOSTREAMCMD
260	{
261	/** Unknown command, do not use. */
262	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
263	/** Enables the stream. */
264	PDMAUDIOSTREAMCMD_ENABLE,
265	/** Disables the stream. */
266	PDMAUDIOSTREAMCMD_DISABLE,
267	/** Pauses the stream. */
268	PDMAUDIOSTREAMCMD_PAUSE,
269	/** Resumes the stream. */
270	PDMAUDIOSTREAMCMD_RESUME,
271	/** Hack to blow the type up to 32-bit. */
272	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
273	} PDMAUDIOSTREAMCMD;
274
275	/**
276	* Properties of audio streams for host/guest
277	* for in or out directions.
278	*/
279	typedef struct PDMPCMPROPS
280	{
281	/** Sample width. Bits per sample. */
282	uint8_t cBits;
283	/** Signed or unsigned sample. */
284	bool fSigned;
285	/** Shift count used for faster calculation of various
286	* values, such as the alignment, bytes to samples and so on.
287	* Depends on number of stream channels and the stream format
288	* being used.
289	*
290	** @todo Use some RTAsmXXX functions instead?
291	*/
292	uint8_t cShift;
293	/** Number of audio channels. */
294	uint8_t cChannels;
295	/** Alignment mask. */
296	uint32_t uAlign;
297	/** Sample frequency in Hertz (Hz). */
298	uint32_t uHz;
299	/** Bandwidth (bytes/s). */
300	uint32_t cbPerSec;
301	/** Whether the endianness is swapped or not. */
302	bool fSwapEndian;
303	} PDMPCMPROPS, *PPDMPCMPROPS;
304
305	/**
306	* Structure keeping an audio volume level.
307	*/
308	typedef struct PDMAUDIOVOLUME
309	{
310	/** Set to @c true if this stream is muted, @c false if not. */
311	bool fMuted;
312	/** Left channel volume. */
313	uint32_t uLeft;
314	/** Right channel volume. */
315	uint32_t uRight;
316	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
317
318	/**
319	* Structure for holding rate processing information
320	* of a source + destination audio stream. This is needed
321	* because both streams can differ regarding their rates
322	* and therefore need to be treated accordingly.
323	*/
324	typedef struct PDMAUDIOSTRMRATE
325	{
326	/** Current (absolute) offset in the output
327	* (destination) stream. */
328	uint64_t dstOffset;
329	/** Increment for moving dstOffset for the
330	* destination stream. This is needed because the
331	* source <-> destination rate might be different. */
332	uint64_t dstInc;
333	/** Current (absolute) offset in the input
334	* stream. */
335	uint32_t srcOffset;
336	/** Last processed sample of the input stream.
337	* Needed for interpolation. */
338	PDMAUDIOSAMPLE srcSampleLast;
339	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
340
341	/**
342	* Note: All internal handling is done in samples,
343	* not in bytes!
344	*/
345	typedef uint32_t PDMAUDIOMIXBUFFMT;
346	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
347
348	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
349	typedef struct PDMAUDIOMIXBUF
350	{
351	RTLISTNODE Node;
352	/** Name of the buffer. */
353	char *pszName;
354	/** Sample buffer. */
355	PPDMAUDIOSAMPLE pSamples;
356	/** Size of the sample buffer (in samples). */
357	uint32_t cSamples;
358	/** The current read/write position (in samples)
359	* in the samples buffer. */
360	uint32_t offReadWrite;
361	/**
362	* Total samples already mixed down to the parent buffer (if any). Always starting at
363	* the parent's offReadWrite position.
364	*
365	* Note: Count always is specified in parent samples, as the sample count can differ between parent
366	* and child.
367	*/
368	uint32_t cMixed;
369	uint32_t cProcessed;
370	/** Pointer to parent buffer (if any). */
371	PPDMAUDIOMIXBUF pParent;
372	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
373	RTLISTANCHOR lstBuffers;
374	/** Intermediate structure for buffer conversion tasks. */
375	PPDMAUDIOSTRMRATE pRate;
376	/** Current volume used for mixing. */
377	PDMAUDIOVOLUME Volume;
378	/** This buffer's audio format. */
379	PDMAUDIOMIXBUFFMT AudioFmt;
380	/**
381	* Ratio of the associated parent stream's frequency by this stream's
382	* frequency (1<<32), represented as a signed 64 bit integer.
383	*
384	* For example, if the parent stream has a frequency of 44 khZ, and this
385	* stream has a frequency of 11 kHz, the ration then would be
386	* (44/11 * (1 << 32)).
387	*
388	* Currently this does not get changed once assigned.
389	*/
390	int64_t iFreqRatio;
391	/** For quickly converting samples <-> bytes and vice versa. */
392	uint8_t cShift;
393	} PDMAUDIOMIXBUF;
394
395	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
396	typedef uint32_t PDMAUDIOSTRMSTS;
397
398	/** No flags being set. */
399	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
400	/** Whether this stream has been initialized by the
401	* backend or not. */
402	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
403	/** Whether this stream is enabled or disabled. */
404	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
405	/** Whether this stream has been paused or not. This also implies
406	* that this is an enabled stream! */
407	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
408	/** Whether this stream was marked as being disabled
409	* but there are still associated guest output streams
410	* which rely on its data. */
411	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
412	/** Validation mask. */
413	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000000F)
414
415	/**
416	* Represents an audio input on the host of a certain
417	* backend (e.g. DirectSound, PulseAudio etc).
418	*
419	* One host audio input is assigned to exactly one parent
420	* guest input stream.
421	*/
422	struct PDMAUDIOGSTSTRMIN;
423	typedef PDMAUDIOGSTSTRMIN *PPDMAUDIOGSTSTRMIN;
424
425	typedef struct PDMAUDIOHSTSTRMIN
426	{
427	/** List node. */
428	RTLISTNODE Node;
429	/** PCM properties. */
430	PDMPCMPROPS Props;
431	/** Stream status flag. */
432	PDMAUDIOSTRMSTS fStatus;
433	/** Critical section for serializing access. */
434	RTCRITSECT CritSect;
435	/** This stream's mixing buffer. */
436	PDMAUDIOMIXBUF MixBuf;
437	/** Pointer to (parent) guest stream. */
438	PPDMAUDIOGSTSTRMIN pGstStrmIn;
439	} PDMAUDIOHSTSTRMIN, *PPDMAUDIOHSTSTRMIN;
440
441	/*
442	* Represents an audio output on the host through a certain
443	* backend (e.g. DirectSound, PulseAudio etc).
444	*
445	* One host audio output can have multiple (1:N) guest outputs
446	* assigned.
447	*/
448	typedef struct PDMAUDIOHSTSTRMOUT
449	{
450	/** List node. */
451	RTLISTNODE Node;
452	/** Stream properites. */
453	PDMPCMPROPS Props;
454	/** Stream status flag. */
455	PDMAUDIOSTRMSTS fStatus;
456	/** Critical section for serializing access. */
457	RTCRITSECT CritSect;
458	/** This stream's mixing buffer. */
459	PDMAUDIOMIXBUF MixBuf;
460	/** Associated guest output streams. */
461	RTLISTANCHOR lstGstStrmOut;
462	} PDMAUDIOHSTSTRMOUT, *PPDMAUDIOHSTSTRMOUT;
463
464	/**
465	* Guest audio stream state.
466	*/
467	typedef struct PDMAUDIOGSTSTRMSTATE
468	{
469	/** Guest audio out stream active or not. */
470	bool fActive;
471	/** Guest audio output stream has some samples or not. */
472	bool fEmpty;
473	/** Name of this stream. */
474	char szName[64];
475	/** Number of references to this stream. Only can be
476	* destroyed if the reference count is reaching 0. */
477	uint32_t cRefs;
478	} PDMAUDIOGSTSTRMSTATE, *PPDMAUDIOGSTSTRMSTATE;
479
480	/**
481	* Represents an audio input from the guest (that is, from the
482	* emulated device, e.g. Intel HDA).
483	*
484	* Each guest input can have multiple host input streams.
485	*/
486	typedef struct PDMAUDIOGSTSTRMIN
487	{
488	/** Guest stream properites. */
489	PDMPCMPROPS Props;
490	/** Current stream state. */
491	PDMAUDIOGSTSTRMSTATE State;
492	/** This stream's mixing buffer. */
493	PDMAUDIOMIXBUF MixBuf;
494	/** Pointer to associated host input stream. */
495	PPDMAUDIOHSTSTRMIN pHstStrmIn;
496	} PDMAUDIOGSTSTRMIN, *PPDMAUDIOGSTSTRMIN;
497
498	/**
499	* Represents an audio output from the guest (that is, from the
500	* emulated device, e.g. Intel HDA).
501	*
502	* Each guest output is assigned to a single host output.
503	*/
504	typedef struct PDMAUDIOGSTSTRMOUT
505	{
506	/** List node. */
507	RTLISTNODE Node;
508	/** Guest output stream properites. */
509	PDMPCMPROPS Props;
510	/** Current stream state. */
511	PDMAUDIOGSTSTRMSTATE State;
512	/** This stream's mixing buffer. */
513	PDMAUDIOMIXBUF MixBuf;
514	/** Pointer to the associated host output stream. */
515	PPDMAUDIOHSTSTRMOUT pHstStrmOut;
516	} PDMAUDIOGSTSTRMOUT, *PPDMAUDIOGSTSTRMOUT;
517
518	/** Pointer to a audio connector interface. */
519	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
520
521	#ifdef VBOX_WITH_AUDIO_CALLBACKS
522	/**
523	* Audio callback types. These are all kept generic as those
524	* are used by all device emulations across all backends.
525	*/
526	typedef enum PDMAUDIOCALLBACKTYPE
527	{
528	PDMAUDIOCALLBACKTYPE_GENERIC = 0,
529	PDMAUDIOCALLBACKTYPE_INPUT,
530	PDMAUDIOCALLBACKTYPE_OUTPUT
531	} PDMAUDIOCALLBACKTYPE;
532
533	/**
534	* Callback data for audio input.
535	*/
536	typedef struct PDMAUDIOCALLBACKDATAIN
537	{
538	/** Input: How many bytes are availabe as input for passing
539	* to the device emulation. */
540	uint32_t cbInAvail;
541	/** Output: How many bytes have been read. */
542	uint32_t cbOutRead;
543	} PDMAUDIOCALLBACKDATAIN, *PPDMAUDIOCALLBACKDATAIN;
544
545	/**
546	* Callback data for audio output.
547	*/
548	typedef struct PDMAUDIOCALLBACKDATAOUT
549	{
550	/** Input: How many bytes are free for the device emulation to write. */
551	uint32_t cbInFree;
552	/** Output: How many bytes were written by the device emulation. */
553	uint32_t cbOutWritten;
554	} PDMAUDIOCALLBACKDATAOUT, *PPDMAUDIOCALLBACKDATAOUT;
555
556	/**
557	* Structure for keeping an audio callback.
558	*/
559	typedef struct PDMAUDIOCALLBACK
560	{
561	RTLISTANCHOR Node;
562	PDMAUDIOCALLBACKTYPE enmType;
563	void *pvCtx;
564	size_t cbCtx;
565	DECLR3CALLBACKMEMBER(int, pfnCallback, (PDMAUDIOCALLBACKTYPE enmType, void pvCtx, size_t cbCtx, void pvUser, size_t cbUser));
566	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
567	#endif
568
569	/**
570	* Audio connector interface (up).
571	** @todo Get rid of the separate XXXIn and XXXOut methods and unify the In/Out structs with a union,
572	** so that we only have one guest and one host stream ultimately.
573	*/
574	typedef struct PDMIAUDIOCONNECTOR
575	{
576	/**
577	* Adds a reference to the specified input stream.
578	*
579	* @returns New reference count.
580	* @param pInterface Pointer to the interface structure containing the called function pointer.
581	* @param pGstStrmIn Pointer to guest input stream adding the reference to.
582	*/
583	DECLR3CALLBACKMEMBER(uint32_t, pfnAddRefIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
584
585	/**
586	* Adds a reference to the specified output stream.
587	*
588	* @returns New reference count.
589	* @param pInterface Pointer to the interface structure containing the called function pointer.
590	* @param pGstStrmOut Pointer to guest output stream adding the reference to.
591	*/
592	DECLR3CALLBACKMEMBER(uint32_t, pfnAddRefOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
593
594	/**
595	* Releases a reference from the input specified stream.
596	*
597	* @returns New reference count.
598	* @param pInterface Pointer to the interface structure containing the called function pointer.
599	* @param pGstStrmIn Pointer to guest input stream releasing a reference from.
600	*/
601	DECLR3CALLBACKMEMBER(uint32_t, pfnReleaseIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
602
603	/**
604	* Releases a reference from the output specified stream.
605	*
606	* @returns New reference count.
607	* @param pInterface Pointer to the interface structure containing the called function pointer.
608	* @param pGstStrmOut Pointer to guest output stream releasing a reference from.
609	*/
610	DECLR3CALLBACKMEMBER(uint32_t, pfnReleaseOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
611
612	/**
613	* Reads PCM audio data from the host (input).
614	*
615	* @returns VBox status code.
616	* @param pInterface Pointer to the interface structure containing the called function pointer.
617	* @param pGstStrmIn Pointer to guest input stream to write to.
618	* @param pvBuf Where to store the read data.
619	* @param cbBuf Number of bytes to read.
620	* @param pcbRead Bytes of audio data read. Optional.
621	*/
622	DECLR3CALLBACKMEMBER(int, pfnRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
623
624	/**
625	* Writes PCM audio data to the host (output).
626	*
627	* @returns VBox status code.
628	* @param pInterface Pointer to the interface structure containing the called function pointer.
629	* @param pGstStrmOut Pointer to guest output stream to read from.
630	* @param pvBuf Audio data to be written.
631	* @param cbBuf Number of bytes to be written.
632	* @param pcbWritten Bytes of audio data written. Optional.
633	*/
634	DECLR3CALLBACKMEMBER(int, pfnWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
635
636	/**
637	* Retrieves the current configuration of the host audio backend.
638	*
639	* @returns VBox status code.
640	*
641	* @param pInterface Pointer to the interface structure containing the called function pointer.
642	* @param pCfg Where to store the host audio backend configuration data.
643	*/
644	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
645
646	/**
647	* Processes input stream data and optionally returns its current status.
648	*
649	* @param pInterface Pointer to the interface structure containing the called function pointer.
650	* @param pcbAvail Count (in bytes) of available input data. Optional.
651	*/
652	DECLR3CALLBACKMEMBER(int, pfnGetDataIn, (PPDMIAUDIOCONNECTOR pInterface, uint32_t *pcbAvail));
653
654	/**
655	* Processes output stream data and optionally returns its current status.
656	*
657	* @param pInterface Pointer to the interface structure containing the called function pointer.
658	* @param pcbFree How much data (in bytes) is free for processing output data. Optional.
659	* @param pcSamplesLive How much audio live data (in audio samples) is present. Optional.
660	*/
661	DECLR3CALLBACKMEMBER(int, pfnGetDataOut, (PPDMIAUDIOCONNECTOR pInterface, uint32_t pcbFree, uint32_t pcSamplesLive));
662
663	/**
664	* Checks whether a specific guest input stream is active or not.
665	*
666	* @returns Whether the specified stream is active or not.
667	* @param pInterface Pointer to the interface structure containing the called function pointer.
668	* @param pGstStrmIn Pointer to guest input stream.
669	*/
670	DECLR3CALLBACKMEMBER(bool, pfnIsActiveIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
671
672	/**
673	* Checks whether a specific guest output stream is active or not.
674	*
675	* @returns Whether the specified stream is active or not.
676	* @param pInterface Pointer to the interface structure containing the called function pointer.
677	* @param pGstStrmOut Pointer to guest output stream.
678	*/
679	DECLR3CALLBACKMEMBER(bool, pfnIsActiveOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
680
681	/**
682	* Checks whether the specified guest input stream is in a valid (working) state.
683	*
684	* @returns True if a host voice in is available, false if not.
685	* @param pInterface Pointer to the interface structure containing the called function pointer.
686	* @param pGstStrmIn Pointer to guest input stream to check.
687	*/
688	DECLR3CALLBACKMEMBER(bool, pfnIsValidIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
689
690	/**
691	* Checks whether the specified guest output stream is in a valid (working) state.
692	*
693	* @returns True if a host voice out is available, false if not.
694	* @param pInterface Pointer to the interface structure containing the called function pointer.
695	* @param pGstStrmOut Pointer to guest output stream to check.
696	*/
697	DECLR3CALLBACKMEMBER(bool, pfnIsValidOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
698
699	/**
700	* Enables a specific guest output stream and starts the audio device.
701	*
702	* @returns VBox status code.
703	* @param pInterface Pointer to the interface structure containing the called function pointer.
704	* @param pGstStrmOut Pointer to guest output stream.
705	* @param fEnable Whether to enable or disable the specified output stream.
706	*/
707	DECLR3CALLBACKMEMBER(int, pfnEnableOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, bool fEnable));
708
709	/**
710	* Enables a specific guest input stream and starts the audio device.
711	*
712	* @returns VBox status code.
713	* @param pInterface Pointer to the interface structure containing the called function pointer.
714	* @param pGstStrmIn Pointer to guest input stream.
715	* @param fEnable Whether to enable or disable the specified input stream.
716	*/
717	DECLR3CALLBACKMEMBER(int, pfnEnableIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, bool fEnable));
718
719	/**
720	* Creates a guest input stream.
721	*
722	* @returns VBox status code.
723	* @param pInterface Pointer to the interface structure containing the called function pointer.
724	* @param pszName Friendly name of this input stream.
725	* @param ppGstStrmIn Pointer where to return the guest guest input stream on success.
726	*/
727	DECLR3CALLBACKMEMBER(int, pfnCreateIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfg,
728	PPDMAUDIOGSTSTRMIN *ppGstStrmIn));
729	/**
730	* Creates a guest output stream.
731	*
732	* @returns VBox status code.
733	* @param pInterface Pointer to the interface structure containing the called function pointer.
734	* @param pCfg Pointer to PDMAUDIOSTREAMCFG to use.
735	* @param ppGstStrmOut Pointer where to return the guest guest input stream on success.
736	*/
737	DECLR3CALLBACKMEMBER(int, pfnCreateOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfg,
738	PPDMAUDIOGSTSTRMOUT *ppGstStrmOut));
739	/**
740	* Destroys a guest input stream.
741	*
742	* @param pInterface Pointer to the interface structure containing the called function pointer.
743	* @param pGstStrmIn Pointer to guest input stream.
744	*/
745	DECLR3CALLBACKMEMBER(void, pfnDestroyIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
746
747	/**
748	* Destroys a guest output stream.
749	*
750	* @param pInterface Pointer to the interface structure containing the called function pointer.
751	* @param pGstStrmOut Pointer to guest output stream.
752	*/
753	DECLR3CALLBACKMEMBER(void, pfnDestroyOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
754
755	/**
756	* Plays (transfers) all available samples via the connected host backend.
757	*
758	* @returns VBox status code.
759	* @param pInterface Pointer to the interface structure containing the called function pointer.
760	* @param pcSamplesPlayed Number of samples played. Optional.
761	*/
762	DECLR3CALLBACKMEMBER(int, pfnPlayOut, (PPDMIAUDIOCONNECTOR pInterface, uint32_t *pcSamplesPlayed));
763
764	#ifdef VBOX_WITH_AUDIO_CALLBACKS
765	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
766	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType, void *pvUser, size_t cbUser));
767	#endif
768
769	} PDMIAUDIOCONNECTOR;
770
771	/** PDMIAUDIOCONNECTOR interface ID. */
772	#define PDMIAUDIOCONNECTOR_IID "20FC7EE1-46DC-8CB0-4C45-30B236155653"
773
774
775
776	/**
777	* Assigns all needed interface callbacks for an audio backend.
778	*
779	* @param a_NamePrefix The function name prefix.
780	*/
781	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_NamePrefix) \
782	do { \
783	pThis->IHostAudio.pfnInit = RT_CONCAT(a_NamePrefix,Init); \
784	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_NamePrefix,Shutdown); \
785	pThis->IHostAudio.pfnInitIn = RT_CONCAT(a_NamePrefix,InitIn); \
786	pThis->IHostAudio.pfnInitOut = RT_CONCAT(a_NamePrefix,InitOut); \
787	pThis->IHostAudio.pfnControlOut = RT_CONCAT(a_NamePrefix,ControlOut); \
788	pThis->IHostAudio.pfnControlIn = RT_CONCAT(a_NamePrefix,ControlIn); \
789	pThis->IHostAudio.pfnFiniIn = RT_CONCAT(a_NamePrefix,FiniIn); \
790	pThis->IHostAudio.pfnFiniOut = RT_CONCAT(a_NamePrefix,FiniOut); \
791	pThis->IHostAudio.pfnIsEnabled = RT_CONCAT(a_NamePrefix,IsEnabled); \
792	pThis->IHostAudio.pfnPlayOut = RT_CONCAT(a_NamePrefix,PlayOut); \
793	pThis->IHostAudio.pfnCaptureIn = RT_CONCAT(a_NamePrefix,CaptureIn); \
794	pThis->IHostAudio.pfnGetConf = RT_CONCAT(a_NamePrefix,GetConf); \
795	} while (0)
796
797	/** Pointer to a host audio interface. */
798	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
799	/**
800	* PDM host audio interface.
801	*/
802	typedef struct PDMIHOSTAUDIO
803	{
804	/**
805	* Initialize the host-specific audio device.
806	*
807	* @returns VBox status code.
808	* @param pInterface Pointer to the interface structure containing the called function pointer.
809	*/
810	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
811
812	/**
813	* Shuts down the host-specific audio device.
814	*
815	* @returns VBox status code.
816	* @param pInterface Pointer to the interface structure containing the called function pointer.
817	*/
818	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
819
820	/**
821	* Initialize the host-specific audio device for input stream.
822	*
823	* @returns VBox status code.
824	* @param pInterface Pointer to the interface structure containing the called function pointer.
825	* @param pHstStrmIn Pointer to host input stream.
826	* @param pStreamCfg Pointer to stream configuration.
827	* @param enmRecSource Specifies the type of recording source to be initialized.
828	* @param pcSamples Returns how many samples the backend can handle. Optional.
829	*/
830	DECLR3CALLBACKMEMBER(int, pfnInitIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PPDMAUDIOSTREAMCFG pStreamCfg, PDMAUDIORECSOURCE enmRecSource, uint32_t *pcSamples));
831
832	/**
833	* Initialize the host-specific output device for output stream.
834	*
835	* @returns VBox status code.
836	* @param pInterface Pointer to the interface structure containing the called function pointer.
837	* @param pHstStrmOut Pointer to host output stream.
838	* @param pStreamCfg Pointer to stream configuration.
839	* @param pcSamples Returns how many samples the backend can handle. Optional.
840	*/
841	DECLR3CALLBACKMEMBER(int, pfnInitOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PPDMAUDIOSTREAMCFG pStreamCfg, uint32_t *pcSamples));
842
843	/**
844	* Control the host audio device for an input stream.
845	*
846	* @returns VBox status code.
847	* @param pInterface Pointer to the interface structure containing the called function pointer.
848	* @param pHstStrmOut Pointer to host output stream.
849	* @param enmStreamCmd The stream command to issue.
850	*/
851	DECLR3CALLBACKMEMBER(int, pfnControlOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PDMAUDIOSTREAMCMD enmStreamCmd));
852
853	/**
854	* Control the host audio device for an output stream.
855	*
856	* @returns VBox status code.
857	* @param pInterface Pointer to the interface structure containing the called function pointer.
858	* @param pHstStrmOut Pointer to host output stream.
859	* @param enmStreamCmd The stream command to issue.
860	*/
861	DECLR3CALLBACKMEMBER(int, pfnControlIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PDMAUDIOSTREAMCMD enmStreamCmd));
862
863	/**
864	* Ends the host audio input streamm.
865	*
866	* @returns VBox status code.
867	* @param pInterface Pointer to the interface structure containing the called function pointer.
868	* @param pHstStrmIn Pointer to host input stream.
869	*/
870	DECLR3CALLBACKMEMBER(int, pfnFiniIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn));
871
872	/**
873	* Ends the host output stream.
874	*
875	* @returns VBox status code.
876	* @param pInterface Pointer to the interface structure containing the called function pointer.
877	* @param pHstStrmOut Pointer to host output stream.
878	*/
879	DECLR3CALLBACKMEMBER(int, pfnFiniOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut));
880
881	/**
882	* Returns whether the specified audio direction in the backend is enabled or not.
883	*
884	* @param pInterface Pointer to the interface structure containing the called function pointer.
885	* @param enmDir Audio direction to check status for.
886	*/
887	DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
888
889	/**
890	* Plays a host audio stream.
891	*
892	* @returns VBox status code.
893	* @param pInterface Pointer to the interface structure containing the called function pointer.
894	* @param pHstStrmOut Pointer to host output stream.
895	* @param pcSamplesPlayed Pointer to number of samples captured.
896	*/
897	DECLR3CALLBACKMEMBER(int, pfnPlayOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, uint32_t *pcSamplesPlayed));
898
899	/**
900	* Records audio to input stream.
901	*
902	* @returns VBox status code.
903	* @param pInterface Pointer to the interface structure containing the called function pointer.
904	* @param pHstStrmIn Pointer to host input stream.
905	* @param pcSamplesCaptured Pointer to number of samples captured.
906	*/
907	DECLR3CALLBACKMEMBER(int, pfnCaptureIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, uint32_t *pcSamplesCaptured));
908
909	/**
910	* Gets the configuration from the host audio (backend) driver.
911	*
912	* @returns VBox status code.
913	* @param pInterface Pointer to the interface structure containing the called function pointer.
914	* @param pBackendCfg Pointer where to store the backend audio configuration to.
915	*/
916	DECLR3CALLBACKMEMBER(int, pfnGetConf, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
917
918	} PDMIHOSTAUDIO;
919
920	/** PDMIHOSTAUDIO interface ID. */
921	#define PDMIHOSTAUDIO_IID "39feea4f-c824-4197-bcff-7d4a6ede7420"
922
923	/** @} */
924
925	#endif /* !___VBox_vmm_pdmaudioifs_h */
926

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

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

Download in other formats: