pdmaudioifs.h@ 61386

Last change on this file since 61386 was 61386, 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: 30.8 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;
95	/** Pointer to a single (stereo) audio sample. */
96	typedef PDMAUDIOSAMPLE *PPDMAUDIOSAMPLE;
97	/** Pointer to a const single (stereo) audio sample. */
98	typedef PDMAUDIOSAMPLE const *PCPDMAUDIOSAMPLE;
99
100	typedef enum PDMAUDIOENDIANNESS
101	{
102	/** The usual invalid endian. */
103	PDMAUDIOENDIANNESS_INVALID,
104	/** Little endian. */
105	PDMAUDIOENDIANNESS_LITTLE,
106	/** Bit endian. */
107	PDMAUDIOENDIANNESS_BIG,
108	/** Endianness doesn't have a meaning in the context. */
109	PDMAUDIOENDIANNESS_NA,
110	/** The end of the valid endian values (exclusive). */
111	PDMAUDIOENDIANNESS_END,
112	/** Hack to blow the type up to 32-bit. */
113	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
114	} PDMAUDIOENDIANNESS;
115
116	/**
117	* Audio direction.
118	*/
119	typedef enum PDMAUDIODIR
120	{
121	PDMAUDIODIR_UNKNOWN = 0,
122	PDMAUDIODIR_IN = 1,
123	PDMAUDIODIR_OUT = 2,
124	/** Duplex handling. */
125	PDMAUDIODIR_ANY = 3,
126	/** Hack to blow the type up to 32-bit. */
127	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
128	} PDMAUDIODIR;
129
130	/**
131	* Audio playback destinations.
132	*/
133	typedef enum PDMAUDIOPLAYBACKDEST
134	{
135	PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
136	PDMAUDIOPLAYBACKDEST_FRONT,
137	PDMAUDIOPLAYBACKDEST_CENTER_LFE,
138	PDMAUDIOPLAYBACKDEST_REAR,
139	/** Hack to blow the type up to 32-bit. */
140	PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
141	} PDMAUDIOPLAYBACKDEST;
142
143	/**
144	* Audio recording sources.
145	*/
146	typedef enum PDMAUDIORECSOURCE
147	{
148	PDMAUDIORECSOURCE_UNKNOWN = 0,
149	PDMAUDIORECSOURCE_MIC,
150	PDMAUDIORECSOURCE_CD,
151	PDMAUDIORECSOURCE_VIDEO,
152	PDMAUDIORECSOURCE_AUX,
153	PDMAUDIORECSOURCE_LINE,
154	PDMAUDIORECSOURCE_PHONE,
155	/** Hack to blow the type up to 32-bit. */
156	PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
157	} PDMAUDIORECSOURCE;
158
159	/**
160	* Audio stream (data) layout.
161	*/
162	typedef enum PDMAUDIOSTREAMLAYOUT
163	{
164	/** Unknown access type; do not use. */
165	PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
166	/** Non-interleaved access, that is, consecutive
167	* access to the data. */
168	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
169	/** Interleaved access, where the data can be
170	* mixed together with data of other audio streams. */
171	PDMAUDIOSTREAMLAYOUT_INTERLEAVED
172	} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
173
174	/** No stream channel data flags defined. */
175	#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
176
177	/**
178	* Structure for keeping a stream channel data block around.
179	*/
180	typedef struct PDMAUDIOSTREAMCHANNELDATA
181	{
182	/** Circular buffer for the channel data. */
183	PRTCIRCBUF pCircBuf;
184	size_t cbAcq;
185	/** Channel data flags. */
186	uint32_t fFlags;
187	} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
188
189	/**
190	* Structure for a single channel of an audio stream.
191	* An audio stream consists of one or multiple channels,
192	* depending on the configuration.
193	*/
194	typedef struct PDMAUDIOSTREAMCHANNEL
195	{
196	/** Channel ID. */
197	uint8_t uChannel;
198	/** Step size (in bytes) to the channel's next frame. */
199	size_t cbStep;
200	/** Frame size (in bytes) of this channel. */
201	size_t cbFrame;
202	/** Offset (in bytes) to first sample in the data block. */
203	size_t cbFirst;
204	/** Currente offset (in bytes) in the data stream. */
205	size_t cbOff;
206	/** Associated data buffer. */
207	PDMAUDIOSTREAMCHANNELDATA Data;
208	} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
209
210	/**
211	* Structure for keeping an audio stream configuration.
212	*/
213	typedef struct PDMAUDIOSTREAMCFG
214	{
215	/** Friendly name of the stream. */
216	char szName[64];
217	/** Direction of the stream. */
218	PDMAUDIODIR enmDir;
219	union
220	{
221	/** Desired playback destination (for an output stream). */
222	PDMAUDIOPLAYBACKDEST Dest;
223	/** Desired recording source (for an input stream). */
224	PDMAUDIORECSOURCE Source;
225	} DestSource;
226	/** Frequency in Hertz (Hz). */
227	uint32_t uHz;
228	/** Number of audio channels (2 for stereo, 1 for mono). */
229	uint8_t cChannels;
230	/** Audio format. */
231	PDMAUDIOFMT enmFormat;
232	/** @todo Use RT_LE2H_? /
233	PDMAUDIOENDIANNESS enmEndianness;
234	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
235
236	#if defined(RT_LITTLE_ENDIAN)
237	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
238	#elif defined(RT_BIG_ENDIAN)
239	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
240	#else
241	# error "Port me!"
242	#endif
243
244	/**
245	* Audio mixer controls.
246	*/
247	typedef enum PDMAUDIOMIXERCTL
248	{
249	PDMAUDIOMIXERCTL_UNKNOWN = 0,
250	PDMAUDIOMIXERCTL_VOLUME,
251	PDMAUDIOMIXERCTL_FRONT,
252	PDMAUDIOMIXERCTL_CENTER_LFE,
253	PDMAUDIOMIXERCTL_REAR,
254	PDMAUDIOMIXERCTL_LINE_IN,
255	PDMAUDIOMIXERCTL_MIC_IN,
256	/** Hack to blow the type up to 32-bit. */
257	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
258	} PDMAUDIOMIXERCTL;
259
260	/**
261	* Audio stream commands. Used in the audio connector
262	* as well as in the actual host backends.
263	*/
264	typedef enum PDMAUDIOSTREAMCMD
265	{
266	/** Unknown command, do not use. */
267	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
268	/** Enables the stream. */
269	PDMAUDIOSTREAMCMD_ENABLE,
270	/** Disables the stream. */
271	PDMAUDIOSTREAMCMD_DISABLE,
272	/** Pauses the stream. */
273	PDMAUDIOSTREAMCMD_PAUSE,
274	/** Resumes the stream. */
275	PDMAUDIOSTREAMCMD_RESUME,
276	/** Hack to blow the type up to 32-bit. */
277	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
278	} PDMAUDIOSTREAMCMD;
279
280	/**
281	* Properties of audio streams for host/guest
282	* for in or out directions.
283	*/
284	typedef struct PDMPCMPROPS
285	{
286	/** Sample width. Bits per sample. */
287	uint8_t cBits;
288	/** Signed or unsigned sample. */
289	bool fSigned;
290	/** Shift count used for faster calculation of various
291	* values, such as the alignment, bytes to samples and so on.
292	* Depends on number of stream channels and the stream format
293	* being used.
294	*
295	** @todo Use some RTAsmXXX functions instead?
296	*/
297	uint8_t cShift;
298	/** Number of audio channels. */
299	uint8_t cChannels;
300	/** Alignment mask. */
301	uint32_t uAlign;
302	/** Sample frequency in Hertz (Hz). */
303	uint32_t uHz;
304	/** Bandwidth (bytes/s). */
305	uint32_t cbPerSec;
306	/** Whether the endianness is swapped or not. */
307	bool fSwapEndian;
308	} PDMPCMPROPS, *PPDMPCMPROPS;
309
310	/**
311	* Audio volume parameters.
312	*/
313	typedef struct PDMAUDIOVOLUME
314	{
315	/** Set to @c true if this stream is muted, @c false if not. */
316	bool fMuted;
317	/** Left channel volume. */
318	uint32_t uLeft;
319	/** Right channel volume. */
320	uint32_t uRight;
321	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
322
323	/**
324	* Structure for holding rate processing information
325	* of a source + destination audio stream. This is needed
326	* because both streams can differ regarding their rates
327	* and therefore need to be treated accordingly.
328	*/
329	typedef struct PDMAUDIOSTRMRATE
330	{
331	/** Current (absolute) offset in the output
332	* (destination) stream. */
333	uint64_t dstOffset;
334	/** Increment for moving dstOffset for the
335	* destination stream. This is needed because the
336	* source <-> destination rate might be different. */
337	uint64_t dstInc;
338	/** Current (absolute) offset in the input
339	* stream. */
340	uint32_t srcOffset;
341	/** Last processed sample of the input stream.
342	* Needed for interpolation. */
343	PDMAUDIOSAMPLE srcSampleLast;
344	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
345
346	/**
347	* Structure for holding sample conversion parameters for
348	* the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
349	*/
350	typedef struct PDMAUDMIXBUFCONVOPTS
351	{
352	/** Number of audio samples to convert. */
353	uint32_t cSamples;
354	/** Volume to apply during conversion. Pass 0
355	* to convert the original values. May not apply to
356	* all conversion functions. */
357	PDMAUDIOVOLUME Volume;
358	} PDMAUDMIXBUFCONVOPTS;
359	/** Pointer to conversion parameters for the audio mixer. */
360	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
361	/** Pointer to const conversion parameters for the audio mixer. */
362	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
363
364	/**
365	* Note: All internal handling is done in samples,
366	* not in bytes!
367	*/
368	typedef uint32_t PDMAUDIOMIXBUFFMT;
369	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
370
371	/**
372	* Convertion-from function used by the PDM audio buffer mixer.
373	*
374	* @returns Number of samples returned.
375	* @param paDst Where to return the converted samples.
376	* @param pvSrc The source samples bytes.
377	* @param cbSrc Number of bytes to convert.
378	* @param pOpts Conversion options.
379	*/
380	typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOSAMPLE paDst, const void *pvSrc, uint32_t cbSrc,
381	PCPDMAUDMIXBUFCONVOPTS pOpts);
382	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
383	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
384
385	/**
386	* Convertion-to function used by the PDM audio buffer mixer.
387	*
388	* @param pvDst Output buffer.
389	* @param paSrc The input samples.
390	* @param pOpts Conversion options.
391	*/
392	typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOSAMPLE paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
393	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
394	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
395
396	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
397	typedef struct PDMAUDIOMIXBUF
398	{
399	RTLISTNODE Node;
400	/** Name of the buffer. */
401	char *pszName;
402	/** Sample buffer. */
403	PPDMAUDIOSAMPLE pSamples;
404	/** Size of the sample buffer (in samples). */
405	uint32_t cSamples;
406	/** The current read position (in samples). */
407	uint32_t offRead;
408	/** The current write position (in samples). */
409	uint32_t offWrite;
410	/**
411	* Total samples already mixed down to the parent buffer (if any). Always starting at
412	* the parent's offRead position.
413	*
414	* Note: Count always is specified in parent samples, as the sample count can differ between parent
415	* and child.
416	*/
417	uint32_t cMixed;
418	/** How much audio samples are currently being used
419	* in this buffer.
420	* Note: This also is known as the distance in ring buffer terms. */
421	uint32_t cUsed;
422	/** Pointer to parent buffer (if any). */
423	PPDMAUDIOMIXBUF pParent;
424	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
425	RTLISTANCHOR lstChildren;
426	/** Intermediate structure for buffer conversion tasks. */
427	PPDMAUDIOSTRMRATE pRate;
428	/** Current volume used for mixing. */
429	PDMAUDIOVOLUME Volume;
430	/** This buffer's audio format. */
431	PDMAUDIOMIXBUFFMT AudioFmt;
432	/** Standard conversion-to function for set AudioFmt. */
433	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
434	/** Standard conversion-from function for set AudioFmt. */
435	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
436	/**
437	* Ratio of the associated parent stream's frequency by this stream's
438	* frequency (1<<32), represented as a signed 64 bit integer.
439	*
440	* For example, if the parent stream has a frequency of 44 khZ, and this
441	* stream has a frequency of 11 kHz, the ration then would be
442	* (44/11 * (1 << 32)).
443	*
444	* Currently this does not get changed once assigned.
445	*/
446	int64_t iFreqRatio;
447	/** For quickly converting samples <-> bytes and vice versa. */
448	uint8_t cShift;
449	} PDMAUDIOMIXBUF;
450
451	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
452	typedef uint32_t PDMAUDIOSTRMSTS;
453
454	/** No flags being set. */
455	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
456	/** Whether this stream has been initialized by the
457	* backend or not. */
458	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
459	/** Whether this stream is enabled or disabled. */
460	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
461	/** Whether this stream has been paused or not. This also implies
462	* that this is an enabled stream! */
463	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
464	/** Whether this stream was marked as being disabled
465	* but there are still associated guest output streams
466	* which rely on its data. */
467	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
468	/** Data can be read from the stream. */
469	#define PDMAUDIOSTRMSTS_FLAG_DATA_READABLE RT_BIT_32(4)
470	/** Data can be written to the stream. */
471	#define PDMAUDIOSTRMSTS_FLAG_DATA_WRITABLE RT_BIT_32(5)
472	/** Validation mask. */
473	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000003F)
474
475	/**
476	* Enumeration presenting a backend's current status.
477	*/
478	typedef enum PDMAUDIOBACKENDSTS
479	{
480	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
481	PDMAUDIOBACKENDSTS_INIT,
482	PDMAUDIOBACKENDSTS_RUNNING,
483	PDMAUDIOBACKENDSTS_SHUTDOWN
484	} PDMAUDIOBACKENDSTS;
485
486	/**
487	* Audio stream context.
488	*/
489	typedef enum PDMAUDIOSTREAMCTX
490	{
491	/** No context set / invalid. */
492	PDMAUDIOSTREAMCTX_UNKNOWN = 0,
493	/** Host stream, connected to a backend. */
494	PDMAUDIOSTREAMCTX_HOST,
495	/** Guest stream, connected to the device emulation. */
496	PDMAUDIOSTREAMCTX_GUEST
497	} PDMAUDIOSTREAMCTX;
498
499	typedef struct PDMAUDIOSTREAMIN
500	{
501
502	} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
503
504	typedef struct PDMAUDIOSTREAMOUT
505	{
506
507	} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
508
509	struct PDMAUDIOSTREAM;
510	typedef PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
511
512	typedef struct PDMAUDIOSTREAM
513	{
514	/** List node. */
515	RTLISTNODE Node;
516	/** Pointer to the other pair of this stream.
517	* This might be the host or guest side. */
518	PPDMAUDIOSTREAM pPair;
519	/** Name of this stream. */
520	char szName[64];
521	/** Number of references to this stream. Only can be
522	* destroyed if the reference count is reaching 0. */
523	uint32_t cRefs;
524	/** PCM properties. */
525	PDMPCMPROPS Props;
526	/** Stream status flag. */
527	PDMAUDIOSTRMSTS fStatus;
528	/** This stream's mixing buffer. */
529	PDMAUDIOMIXBUF MixBuf;
530	/** Audio direction of this stream. */
531	PDMAUDIODIR enmDir;
532	/** Context of this stream. */
533	PDMAUDIOSTREAMCTX enmCtx;
534	typedef union
535	{
536	PDMAUDIOSTREAMIN In;
537	PDMAUDIOSTREAMOUT Out;
538	} InOut;
539	} PDMAUDIOSTREAM, *PPDMAUDIOSTREAM;
540
541	/** Pointer to a audio connector interface. */
542	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
543
544	#ifdef VBOX_WITH_AUDIO_CALLBACKS
545	/**
546	* Audio callback types. These are all kept generic as those
547	* are used by all device emulations across all backends.
548	*/
549	typedef enum PDMAUDIOCALLBACKTYPE
550	{
551	PDMAUDIOCALLBACKTYPE_GENERIC = 0,
552	PDMAUDIOCALLBACKTYPE_INPUT,
553	PDMAUDIOCALLBACKTYPE_OUTPUT
554	} PDMAUDIOCALLBACKTYPE;
555
556	/**
557	* Callback data for audio input.
558	*/
559	typedef struct PDMAUDIOCALLBACKDATAIN
560	{
561	/** Input: How many bytes are availabe as input for passing
562	* to the device emulation. */
563	uint32_t cbInAvail;
564	/** Output: How many bytes have been read. */
565	uint32_t cbOutRead;
566	} PDMAUDIOCALLBACKDATAIN, *PPDMAUDIOCALLBACKDATAIN;
567
568	/**
569	* Callback data for audio output.
570	*/
571	typedef struct PDMAUDIOCALLBACKDATAOUT
572	{
573	/** Input: How many bytes are free for the device emulation to write. */
574	uint32_t cbInFree;
575	/** Output: How many bytes were written by the device emulation. */
576	uint32_t cbOutWritten;
577	} PDMAUDIOCALLBACKDATAOUT, *PPDMAUDIOCALLBACKDATAOUT;
578
579	/**
580	* Structure for keeping an audio callback.
581	*/
582	typedef struct PDMAUDIOCALLBACK
583	{
584	RTLISTANCHOR Node;
585	PDMAUDIOCALLBACKTYPE enmType;
586	void *pvCtx;
587	size_t cbCtx;
588	DECLR3CALLBACKMEMBER(int, pfnCallback, (PDMAUDIOCALLBACKTYPE enmType, void pvCtx, size_t cbCtx, void pvUser, size_t cbUser));
589	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
590	#endif
591
592	/**
593	* Audio connector interface (up).
594	** @todo Get rid of the separate XXXIn and XXXOut methods and unify the In/Out structs with a union,
595	** so that we only have one guest and one host stream ultimately.
596	*/
597	typedef struct PDMIAUDIOCONNECTOR
598	{
599	/**
600	* Retrieves the current configuration of the host audio backend.
601	*
602	* @returns VBox status code.
603	*
604	* @param pInterface Pointer to the interface structure containing the called function pointer.
605	* @param pCfg Where to store the host audio backend configuration data.
606	*/
607	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
608
609	/**
610	* @todo Docs!
611	*/
612	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
613
614	/**
615	* Creates an audio stream.
616	*
617	* @returns VBox status code.
618	* @param pInterface Pointer to the interface structure containing the called function pointer.
619	* @param pCfgHost Stream configuration for host side.
620	* @param pCfgGuest Stream configuration for guest side.
621	* @param ppStream Pointer where to return the created audio stream on success.
622	*/
623	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
624
625	/**
626	* Destroys an audio stream.
627	*
628	* @param pInterface Pointer to the interface structure containing the called function pointer.
629	* @param pStream Pointer to audio stream.
630	*/
631	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
632
633	/**
634	* Adds a reference to the specified audio stream.
635	*
636	* @returns New reference count.
637	* @param pInterface Pointer to the interface structure containing the called function pointer.
638	* @param pStream Pointer to audio stream adding the reference to.
639	*/
640	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamAddRef, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
641
642	/**
643	* Releases a reference from the specified stream.
644	*
645	* @returns New reference count.
646	* @param pInterface Pointer to the interface structure containing the called function pointer.
647	* @param pStream Pointer to audio stream releasing a reference from.
648	*/
649	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
650
651	/**
652	* Reads PCM audio data from the host (input).
653	*
654	* @returns VBox status code.
655	* @param pInterface Pointer to the interface structure containing the called function pointer.
656	* @param pStream Pointer to audio stream to write to.
657	* @param pvBuf Where to store the read data.
658	* @param cbBuf Number of bytes to read.
659	* @param pcbRead Bytes of audio data read. Optional.
660	*/
661	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
662
663	/**
664	* Writes PCM audio data to the host (output).
665	*
666	* @returns VBox status code.
667	* @param pInterface Pointer to the interface structure containing the called function pointer.
668	* @param pStream Pointer to audio stream to read from.
669	* @param pvBuf Audio data to be written.
670	* @param cbBuf Number of bytes to be written.
671	* @param pcbWritten Bytes of audio data written. Optional.
672	*/
673	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
674
675	/**
676	* Controls a specific audio stream.
677	*
678	* @returns VBox status code.
679	* @param pInterface Pointer to the interface structure containing the called function pointer.
680	* @param pStream Pointer to audio stream.
681	* @param enmStreamCmd The stream command to issue.
682	*/
683	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
684
685	/**
686	* Processes stream data.
687	*
688	* @param pInterface Pointer to the interface structure containing the called function pointer.
689	* @param pStream Pointer to audio stream.
690	* @param pcData Data (in audio samples) available. Optional.
691	*/
692	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
693
694	/**
695	* Retrieves the status of a specific audio stream.
696	*
697	* @returns Audio stream status
698	* @param pInterface Pointer to the interface structure containing the called function pointer.
699	* @param pStream Pointer to audio stream.
700	*/
701	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
702
703	/**
704	* Sets the audio volume of a specific audio stream.
705	*
706	* @returns VBox status code.
707	* @param pInterface Pointer to the interface structure containing the called function pointer.
708	* @param pStream Pointer to audio stream.
709	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
710	*/
711	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
712
713	/**
714	* Plays (transfers) all available audio samples of a an output stream via the connected host backend.
715	*
716	* @returns VBox status code.
717	* @param pInterface Pointer to the interface structure containing the called function pointer.
718	* @param pcSamplesPlayed Number of samples played. Optional.
719	*/
720	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
721
722	#ifdef VBOX_WITH_AUDIO_CALLBACKS
723	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
724	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType, void *pvUser, size_t cbUser));
725	#endif
726
727	} PDMIAUDIOCONNECTOR;
728
729	/** PDMIAUDIOCONNECTOR interface ID. */
730	#define PDMIAUDIOCONNECTOR_IID "9C097435-3276-4D88-A49A-A4FE671D86F8"
731
732
733
734	/**
735	* Assigns all needed interface callbacks for an audio backend.
736	*
737	* @param a_NamePrefix The function name prefix.
738	*/
739	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_NamePrefix) \
740	do { \
741	pThis->IHostAudio.pfnInit = RT_CONCAT(a_NamePrefix,Init); \
742	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_NamePrefix,Shutdown); \
743	pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_NamePrefix,GetConfig); \
744	pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_NamePrefix,GetStatus); \
745	pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_NamePrefix,StreamCreate); \
746	pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_NamePrefix,StreamDestroy); \
747	pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_NamePrefix,StreamControl); \
748	pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_NamePrefix,StreamGetStatus); \
749	pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_NamePrefix,StreamIterate); \
750	pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_NamePrefix,StreamPlay); \
751	pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_NamePrefix,StreamCapture); \
752	} while (0)
753
754	/** Pointer to a host audio interface. */
755	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
756	/**
757	* PDM host audio interface.
758	*/
759	typedef struct PDMIHOSTAUDIO
760	{
761	/**
762	* Initialize the host-specific audio device.
763	*
764	* @returns VBox status code.
765	* @param pInterface Pointer to the interface structure containing the called function pointer.
766	*/
767	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
768
769	/**
770	* Shuts down the host-specific audio device.
771	*
772	* @returns VBox status code.
773	* @param pInterface Pointer to the interface structure containing the called function pointer.
774	*/
775	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
776
777	/**
778	* Returns the configuration from the host audio (backend) driver.
779	*
780	* @returns VBox status code.
781	* @param pInterface Pointer to the interface structure containing the called function pointer.
782	* @param pBackendCfg Pointer where to store the backend audio configuration to.
783	*/
784	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
785
786	/**
787	* Returns the current status from the host audio (backend) driver.
788	*
789	* @returns PDMAUDIOBACKENDSTS enum.
790	* @param pInterface Pointer to the interface structure containing the called function pointer.
791	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
792	*/
793	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
794
795	/**
796	* Creates an audio stream.
797	*
798	* @returns VBox status code.
799	* @param pInterface Pointer to the interface structure containing the called function pointer.
800	* @param pStream Pointer to audio stream.
801	* @param pStreamCfg Pointer to stream configuration.
802	* @param pcSamples Returns how many samples the backend can handle. Optional.
803	*/
804	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfg, uint32_t *pcSamples));
805
806	/**
807	* Destroys an audio stream.
808	*
809	* @returns VBox status code.
810	* @param pInterface Pointer to the interface structure containing the called function pointer.
811	* @param pStream Pointer to audio stream.
812	*/
813	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
814
815	/**
816	* Controls an audio stream.
817	*
818	* @returns VBox status code.
819	* @param pInterface Pointer to the interface structure containing the called function pointer.
820	* @param pStream Pointer to audio stream.
821	* @param enmStreamCmd The stream command to issue.
822	*/
823	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
824
825	/**
826	* Returns whether the specified audio direction in the backend is enabled or not.
827	*
828	* @param pInterface Pointer to the interface structure containing the called function pointer.
829	* @param enmDir Audio direction to check status for.
830	*/
831	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
832
833	/**
834	** @todo Docs!
835	*/
836	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
837
838	/**
839	* Plays an audio (output) stream.
840	*
841	* @returns VBox status code.
842	* @param pInterface Pointer to the interface structure containing the called function pointer.
843	* @param pStream Pointer to audio stream.
844	* @param pcSamplesPlayed Pointer to number of samples captured.
845	*/
846	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
847
848	/**
849	* Captures an audio (input) stream.
850	*
851	* @returns VBox status code.
852	* @param pInterface Pointer to the interface structure containing the called function pointer.
853	* @param pStream Pointer to audio stream.
854	* @param pcSamplesCaptured Pointer to number of samples captured.
855	*/
856	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
857
858	} PDMIHOSTAUDIO;
859
860	/** PDMIHOSTAUDIO interface ID. */
861	#define PDMIHOSTAUDIO_IID "96AC69D0-F301-42AC-8F1D-1E19BA808887"
862
863	/** @} */
864
865	#endif /* !___VBox_vmm_pdmaudioifs_h */
866

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

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

Download in other formats: