pdmaudioifs.h@ 62965

Last change on this file since 62965 was 62965, checked in by vboxsync, 8 years ago
Devices: warnings
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.4 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 <iprt/circbuf.h>
30	#include <iprt/critsect.h>
31	#include <iprt/list.h>
32
33	#include <VBox/types.h>
34	#ifdef VBOX_WITH_STATISTICS
35	# include <VBox/vmm/stam.h>
36	#endif
37
38	/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
39	* @ingroup grp_pdm_interfaces
40	* @{
41	*/
42
43	/** PDM audio driver instance flags. */
44	typedef uint32_t PDMAUDIODRVFLAGS;
45
46	/** No flags set. */
47	#define PDMAUDIODRVFLAGS_NONE 0
48	/** Marks a primary audio driver which is critical
49	* when running the VM. */
50	#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
51
52	/**
53	* Audio format in signed or unsigned variants.
54	*/
55	typedef enum PDMAUDIOFMT
56	{
57	/** Invalid format, do not use. */
58	PDMAUDIOFMT_INVALID,
59	/** 8-bit, unsigned. */
60	PDMAUDIOFMT_U8,
61	/** 8-bit, signed. */
62	PDMAUDIOFMT_S8,
63	/** 16-bit, unsigned. */
64	PDMAUDIOFMT_U16,
65	/** 16-bit, signed. */
66	PDMAUDIOFMT_S16,
67	/** 32-bit, unsigned. */
68	PDMAUDIOFMT_U32,
69	/** 32-bit, signed. */
70	PDMAUDIOFMT_S32,
71	/** Hack to blow the type up to 32-bit. */
72	PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
73	} PDMAUDIOFMT;
74
75	/**
76	* Audio configuration of a certain host backend.
77	*/
78	typedef struct PDMAUDIOBACKENDCFG
79	{
80	/** Size (in bytes) of the host backend's audio output stream structure. */
81	size_t cbStreamOut;
82	/** Size (in bytes) of the host backend's audio input stream structure. */
83	size_t cbStreamIn;
84	/** Number of valid output sinks found on the host. */
85	uint8_t cSinks;
86	/** Number of valid input sources found on the host. */
87	uint8_t cSources;
88	/** Number of concurrent output streams supported on the host.
89	* UINT32_MAX for unlimited concurrent streams. */
90	uint32_t cMaxStreamsOut;
91	/** Number of concurrent input streams supported on the host.
92	* UINT32_MAX for unlimited concurrent streams. */
93	uint32_t cMaxStreamsIn;
94	} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
95
96	/**
97	* A single audio sample, representing left and right channels (stereo).
98	*/
99	typedef struct PDMAUDIOSAMPLE
100	{
101	/** Left channel. */
102	int64_t i64LSample;
103	/** Right channel. */
104	int64_t i64RSample;
105	} PDMAUDIOSAMPLE;
106	/** Pointer to a single (stereo) audio sample. */
107	typedef PDMAUDIOSAMPLE *PPDMAUDIOSAMPLE;
108	/** Pointer to a const single (stereo) audio sample. */
109	typedef PDMAUDIOSAMPLE const *PCPDMAUDIOSAMPLE;
110
111	typedef enum PDMAUDIOENDIANNESS
112	{
113	/** The usual invalid endian. */
114	PDMAUDIOENDIANNESS_INVALID,
115	/** Little endian. */
116	PDMAUDIOENDIANNESS_LITTLE,
117	/** Bit endian. */
118	PDMAUDIOENDIANNESS_BIG,
119	/** Endianness doesn't have a meaning in the context. */
120	PDMAUDIOENDIANNESS_NA,
121	/** The end of the valid endian values (exclusive). */
122	PDMAUDIOENDIANNESS_END,
123	/** Hack to blow the type up to 32-bit. */
124	PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
125	} PDMAUDIOENDIANNESS;
126
127	/**
128	* Audio direction.
129	*/
130	typedef enum PDMAUDIODIR
131	{
132	/** Unknown direction. */
133	PDMAUDIODIR_UNKNOWN = 0,
134	/** Input. */
135	PDMAUDIODIR_IN = 1,
136	/** Output. */
137	PDMAUDIODIR_OUT = 2,
138	/** Duplex handling. */
139	PDMAUDIODIR_ANY = 3,
140	/** Hack to blow the type up to 32-bit. */
141	PDMAUDIODIR_32BIT_HACK = 0x7fffffff
142	} PDMAUDIODIR;
143
144	/**
145	* Audio playback destinations.
146	*/
147	typedef enum PDMAUDIOPLAYBACKDEST
148	{
149	/** Unknown destination. */
150	PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
151	/** Front channel. */
152	PDMAUDIOPLAYBACKDEST_FRONT,
153	/** Center / LFE (Subwoofer) channel. */
154	PDMAUDIOPLAYBACKDEST_CENTER_LFE,
155	/** Rear channel. */
156	PDMAUDIOPLAYBACKDEST_REAR,
157	/** Hack to blow the type up to 32-bit. */
158	PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
159	} PDMAUDIOPLAYBACKDEST;
160
161	/**
162	* Audio recording sources.
163	*/
164	typedef enum PDMAUDIORECSOURCE
165	{
166	/** Unknown recording source. */
167	PDMAUDIORECSOURCE_UNKNOWN = 0,
168	/** Microphone-In. */
169	PDMAUDIORECSOURCE_MIC,
170	/** CD. */
171	PDMAUDIORECSOURCE_CD,
172	/** Video-In. */
173	PDMAUDIORECSOURCE_VIDEO,
174	/** AUX. */
175	PDMAUDIORECSOURCE_AUX,
176	/** Line-In. */
177	PDMAUDIORECSOURCE_LINE,
178	/** Phone-In. */
179	PDMAUDIORECSOURCE_PHONE,
180	/** Hack to blow the type up to 32-bit. */
181	PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
182	} PDMAUDIORECSOURCE;
183
184	/**
185	* Audio stream (data) layout.
186	*/
187	typedef enum PDMAUDIOSTREAMLAYOUT
188	{
189	/** Unknown access type; do not use. */
190	PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
191	/** Non-interleaved access, that is, consecutive
192	* access to the data. */
193	PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
194	/** Interleaved access, where the data can be
195	* mixed together with data of other audio streams. */
196	PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
197	/** Complex layout, which does not fit into the
198	* interleaved / non-interleaved layouts. */
199	PDMAUDIOSTREAMLAYOUT_COMPLEX,
200	/** Hack to blow the type up to 32-bit. */
201	PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
202	} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
203
204	/** No stream channel data flags defined. */
205	#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
206
207	/**
208	* Structure for keeping a stream channel data block around.
209	*/
210	typedef struct PDMAUDIOSTREAMCHANNELDATA
211	{
212	/** Circular buffer for the channel data. */
213	PRTCIRCBUF pCircBuf;
214	size_t cbAcq;
215	/** Channel data flags. */
216	uint32_t fFlags;
217	} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
218
219	/**
220	* Structure for a single channel of an audio stream.
221	* An audio stream consists of one or multiple channels,
222	* depending on the configuration.
223	*/
224	typedef struct PDMAUDIOSTREAMCHANNEL
225	{
226	/** Channel ID. */
227	uint8_t uChannel;
228	/** Step size (in bytes) to the channel's next frame. */
229	size_t cbStep;
230	/** Frame size (in bytes) of this channel. */
231	size_t cbFrame;
232	/** Offset (in bytes) to first sample in the data block. */
233	size_t cbFirst;
234	/** Currente offset (in bytes) in the data stream. */
235	size_t cbOff;
236	/** Associated data buffer. */
237	PDMAUDIOSTREAMCHANNELDATA Data;
238	} PDMAUDIOSTREAMCHANNEL, *PPDMAUDIOSTREAMCHANNEL;
239
240	/**
241	* Structure for keeping an audio stream configuration.
242	*/
243	typedef struct PDMAUDIOSTREAMCFG
244	{
245	/** Friendly name of the stream. */
246	char szName[64];
247	/** Direction of the stream. */
248	PDMAUDIODIR enmDir;
249	union
250	{
251	/** Desired playback destination (for an output stream). */
252	PDMAUDIOPLAYBACKDEST Dest;
253	/** Desired recording source (for an input stream). */
254	PDMAUDIORECSOURCE Source;
255	} DestSource;
256	/** Frequency in Hertz (Hz). */
257	uint32_t uHz;
258	/** Number of audio channels (2 for stereo, 1 for mono). */
259	uint8_t cChannels;
260	/** Audio format. */
261	PDMAUDIOFMT enmFormat;
262	/** @todo Use RT_LE2H_? /
263	PDMAUDIOENDIANNESS enmEndianness;
264	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
265
266	#if defined(RT_LITTLE_ENDIAN)
267	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
268	#elif defined(RT_BIG_ENDIAN)
269	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
270	#else
271	# error "Port me!"
272	#endif
273
274	/**
275	* Audio mixer controls.
276	*/
277	typedef enum PDMAUDIOMIXERCTL
278	{
279	/** Unknown mixer control. */
280	PDMAUDIOMIXERCTL_UNKNOWN = 0,
281	/** Master volume. */
282	PDMAUDIOMIXERCTL_VOLUME_MASTER,
283	/** Front. */
284	PDMAUDIOMIXERCTL_FRONT,
285	/** Center / LFE (Subwoofer). */
286	PDMAUDIOMIXERCTL_CENTER_LFE,
287	/** Rear. */
288	PDMAUDIOMIXERCTL_REAR,
289	/** Line-In. */
290	PDMAUDIOMIXERCTL_LINE_IN,
291	/** Microphone-In. */
292	PDMAUDIOMIXERCTL_MIC_IN,
293	/** Hack to blow the type up to 32-bit. */
294	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
295	} PDMAUDIOMIXERCTL;
296
297	/**
298	* Audio stream commands. Used in the audio connector
299	* as well as in the actual host backends.
300	*/
301	typedef enum PDMAUDIOSTREAMCMD
302	{
303	/** Unknown command, do not use. */
304	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
305	/** Enables the stream. */
306	PDMAUDIOSTREAMCMD_ENABLE,
307	/** Disables the stream. */
308	PDMAUDIOSTREAMCMD_DISABLE,
309	/** Pauses the stream. */
310	PDMAUDIOSTREAMCMD_PAUSE,
311	/** Resumes the stream. */
312	PDMAUDIOSTREAMCMD_RESUME,
313	/** Hack to blow the type up to 32-bit. */
314	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
315	} PDMAUDIOSTREAMCMD;
316
317	/**
318	* Properties of audio streams for host/guest
319	* for in or out directions.
320	*/
321	typedef struct PDMPCMPROPS
322	{
323	/** Sample width. Bits per sample. */
324	uint8_t cBits;
325	/** Signed or unsigned sample. */
326	bool fSigned;
327	/** Shift count used for faster calculation of various
328	* values, such as the alignment, bytes to samples and so on.
329	* Depends on number of stream channels and the stream format
330	* being used.
331	*
332	** @todo Use some RTAsmXXX functions instead?
333	*/
334	uint8_t cShift;
335	/** Number of audio channels. */
336	uint8_t cChannels;
337	/** Alignment mask. */
338	uint32_t uAlign;
339	/** Sample frequency in Hertz (Hz). */
340	uint32_t uHz;
341	/** Bitrate (in bytes/s). */
342	uint32_t cbBitrate;
343	/** Whether the endianness is swapped or not. */
344	bool fSwapEndian;
345	} PDMPCMPROPS, *PPDMPCMPROPS;
346
347	/**
348	* Audio volume parameters.
349	*/
350	typedef struct PDMAUDIOVOLUME
351	{
352	/** Set to @c true if this stream is muted, @c false if not. */
353	bool fMuted;
354	/** Left channel volume.
355	* Range is from [0 ... 255], whereas 0 specifies
356	* the most silent and 255 the loudest value. */
357	uint8_t uLeft;
358	/** Right channel volume.
359	* Range is from [0 ... 255], whereas 0 specifies
360	* the most silent and 255 the loudest value. */
361	uint8_t uRight;
362	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
363
364	/** Defines the minimum volume allowed. */
365	#define PDMAUDIO_VOLUME_MIN (0)
366	/** Defines the maximum volume allowed. */
367	#define PDMAUDIO_VOLUME_MAX (255)
368
369	/**
370	* Structure for holding rate processing information
371	* of a source + destination audio stream. This is needed
372	* because both streams can differ regarding their rates
373	* and therefore need to be treated accordingly.
374	*/
375	typedef struct PDMAUDIOSTRMRATE
376	{
377	/** Current (absolute) offset in the output
378	* (destination) stream. */
379	uint64_t dstOffset;
380	/** Increment for moving dstOffset for the
381	* destination stream. This is needed because the
382	* source <-> destination rate might be different. */
383	uint64_t dstInc;
384	/** Current (absolute) offset in the input
385	* stream. */
386	uint32_t srcOffset;
387	/** Last processed sample of the input stream.
388	* Needed for interpolation. */
389	PDMAUDIOSAMPLE srcSampleLast;
390	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
391
392	/**
393	* Structure for holding mixing buffer volume parameters.
394	* The volume values are in fixed point style and must
395	* be converted to/from before using with e.g. PDMAUDIOVOLUME.
396	*/
397	typedef struct PDMAUDMIXBUFVOL
398	{
399	/** Set to @c true if this stream is muted, @c false if not. */
400	bool fMuted;
401	/** Left volume to apply during conversion. Pass 0
402	* to convert the original values. May not apply to
403	* all conversion functions. */
404	uint32_t uLeft;
405	/** Right volume to apply during conversion. Pass 0
406	* to convert the original values. May not apply to
407	* all conversion functions. */
408	uint32_t uRight;
409	} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
410
411	/**
412	* Structure for holding sample conversion parameters for
413	* the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
414	*/
415	typedef struct PDMAUDMIXBUFCONVOPTS
416	{
417	/** Number of audio samples to convert. */
418	uint32_t cSamples;
419	union
420	{
421	struct
422	{
423	/** Volume to use for conversion. */
424	PDMAUDMIXBUFVOL Volume;
425	} From;
426	};
427	} PDMAUDMIXBUFCONVOPTS;
428	/** Pointer to conversion parameters for the audio mixer. */
429	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
430	/** Pointer to const conversion parameters for the audio mixer. */
431	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
432
433	/**
434	* Note: All internal handling is done in samples,
435	* not in bytes!
436	*/
437	typedef uint32_t PDMAUDIOMIXBUFFMT;
438	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
439
440	/**
441	* Convertion-from function used by the PDM audio buffer mixer.
442	*
443	* @returns Number of samples returned.
444	* @param paDst Where to return the converted samples.
445	* @param pvSrc The source samples bytes.
446	* @param cbSrc Number of bytes to convert.
447	* @param pOpts Conversion options.
448	*/
449	typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOSAMPLE paDst, const void *pvSrc, uint32_t cbSrc,
450	PCPDMAUDMIXBUFCONVOPTS pOpts);
451	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
452	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
453
454	/**
455	* Convertion-to function used by the PDM audio buffer mixer.
456	*
457	* @param pvDst Output buffer.
458	* @param paSrc The input samples.
459	* @param pOpts Conversion options.
460	*/
461	typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOSAMPLE paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
462	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
463	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
464
465	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
466	typedef struct PDMAUDIOMIXBUF
467	{
468	RTLISTNODE Node;
469	/** Name of the buffer. */
470	char *pszName;
471	/** Sample buffer. */
472	PPDMAUDIOSAMPLE pSamples;
473	/** Size of the sample buffer (in samples). */
474	uint32_t cSamples;
475	/** The current read position (in samples). */
476	uint32_t offRead;
477	/** The current write position (in samples). */
478	uint32_t offWrite;
479	/**
480	* Total samples already mixed down to the parent buffer (if any). Always starting at
481	* the parent's offRead position.
482	*
483	* Note: Count always is specified in parent samples, as the sample count can differ between parent
484	* and child.
485	*/
486	uint32_t cMixed;
487	/** How much audio samples are currently being used
488	* in this buffer.
489	* Note: This also is known as the distance in ring buffer terms. */
490	uint32_t cUsed;
491	/** Pointer to parent buffer (if any). */
492	PPDMAUDIOMIXBUF pParent;
493	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
494	RTLISTANCHOR lstChildren;
495	/** Intermediate structure for buffer conversion tasks. */
496	PPDMAUDIOSTRMRATE pRate;
497	/** Internal representation of current volume used for mixing. */
498	PDMAUDMIXBUFVOL Volume;
499	/** This buffer's audio format. */
500	PDMAUDIOMIXBUFFMT AudioFmt;
501	/** Standard conversion-to function for set AudioFmt. */
502	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
503	/** Standard conversion-from function for set AudioFmt. */
504	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
505	/**
506	* Ratio of the associated parent stream's frequency by this stream's
507	* frequency (1<<32), represented as a signed 64 bit integer.
508	*
509	* For example, if the parent stream has a frequency of 44 khZ, and this
510	* stream has a frequency of 11 kHz, the ration then would be
511	* (44/11 * (1 << 32)).
512	*
513	* Currently this does not get changed once assigned.
514	*/
515	int64_t iFreqRatio;
516	/** For quickly converting samples <-> bytes and vice versa. */
517	uint8_t cShift;
518	} PDMAUDIOMIXBUF;
519
520	typedef uint32_t PDMAUDIOFILEFLAGS;
521
522	/* No flags defined. */
523	#define PDMAUDIOFILEFLAG_NONE 0
524
525	/**
526	* Audio file types.
527	*/
528	typedef enum PDMAUDIOFILETYPE
529	{
530	/** Unknown type, do not use. */
531	PDMAUDIOFILETYPE_UNKNOWN = 0,
532	/** Wave (.WAV) file. */
533	PDMAUDIOFILETYPE_WAV
534	} PDMAUDIOFILETYPE;
535
536	/**
537	* Structure for an audio file handle.
538	*/
539	typedef struct PDMAUDIOFILE
540	{
541	/** Type of the audio file. */
542	PDMAUDIOFILETYPE enmType;
543	/** File name. */
544	char szName[255];
545	/** Actual file handle. */
546	RTFILE hFile;
547	/** Data needed for the specific audio file type implemented.
548	* Optional, can be NULL. */
549	void *pvData;
550	/** Data size (in bytes). */
551	size_t cbData;
552	} PDMAUDIOFILE, *PPDMAUDIOFILE;
553
554	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
555	typedef uint32_t PDMAUDIOSTRMSTS;
556
557	/** No flags being set. */
558	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
559	/** Whether this stream has been initialized by the
560	* backend or not. */
561	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
562	/** Whether this stream is enabled or disabled. */
563	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
564	/** Whether this stream has been paused or not. This also implies
565	* that this is an enabled stream! */
566	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
567	/** Whether this stream was marked as being disabled
568	* but there are still associated guest output streams
569	* which rely on its data. */
570	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
571	/** Data can be read from the stream. */
572	#define PDMAUDIOSTRMSTS_FLAG_DATA_READABLE RT_BIT_32(4)
573	/** Data can be written to the stream. */
574	#define PDMAUDIOSTRMSTS_FLAG_DATA_WRITABLE RT_BIT_32(5)
575	/** Whether this stream is in re-initialization phase.
576	* All other bits remain untouched to be able to restore
577	* the stream's state after the re-initialization bas been
578	* finished. */
579	#define PDMAUDIOSTRMSTS_FLAG_PENDING_REINIT RT_BIT_32(6)
580	/** Validation mask. */
581	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000007F)
582
583	/**
584	* Enumeration presenting a backend's current status.
585	*/
586	typedef enum PDMAUDIOBACKENDSTS
587	{
588	/** Unknown/invalid status. */
589	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
590	/** The backend is in its initialization phase.
591	* Not all backends support this status. */
592	PDMAUDIOBACKENDSTS_INITIALIZING,
593	/** The backend has stopped its operation. */
594	PDMAUDIOBACKENDSTS_STOPPED,
595	/** The backend is up and running. */
596	PDMAUDIOBACKENDSTS_RUNNING,
597	/** The backend ran into an error and is unable to recover.
598	* A manual re-initialization might help. */
599	PDMAUDIOBACKENDSTS_ERROR
600	} PDMAUDIOBACKENDSTS;
601
602	/**
603	* Audio stream context.
604	*/
605	typedef enum PDMAUDIOSTREAMCTX
606	{
607	/** No context set / invalid. */
608	PDMAUDIOSTREAMCTX_UNKNOWN = 0,
609	/** Host stream, connected to a backend. */
610	PDMAUDIOSTREAMCTX_HOST,
611	/** Guest stream, connected to the device emulation. */
612	PDMAUDIOSTREAMCTX_GUEST
613	} PDMAUDIOSTREAMCTX;
614
615	/**
616	* Structure for keeping audio input stream specifics.
617	* Do not use directly. Instead, use PDMAUDIOSTREAM.
618	*/
619	typedef struct PDMAUDIOSTREAMIN
620	{
621	/** Timestamp (in ms) since last read. */
622	uint64_t tsLastReadMS;
623	#ifdef VBOX_WITH_STATISTICS
624	STAMCOUNTER StatBytesElapsed;
625	STAMCOUNTER StatBytesTotalRead;
626	STAMCOUNTER StatSamplesCaptured;
627	#endif
628	} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
629
630	/**
631	* Structure for keeping audio output stream specifics.
632	* Do not use directly. Instead, use PDMAUDIOSTREAM.
633	*/
634	typedef struct PDMAUDIOSTREAMOUT
635	{
636	/** Timestamp (in ms) since last write. */
637	uint64_t tsLastWriteMS;
638	#ifdef VBOX_WITH_STATISTICS
639	STAMCOUNTER StatBytesElapsed;
640	STAMCOUNTER StatBytesTotalWritten;
641	STAMCOUNTER StatSamplesPlayed;
642	#endif
643	} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
644
645	struct PDMAUDIOSTREAM;
646	typedef PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
647
648	/**
649	* Structure for maintaining an nput/output audio stream.
650	*/
651	typedef struct PDMAUDIOSTREAM
652	{
653	/** List node. */
654	RTLISTNODE Node;
655	/** Pointer to the other pair of this stream.
656	* This might be the host or guest side. */
657	PPDMAUDIOSTREAM pPair;
658	/** Name of this stream. */
659	char szName[64];
660	/** Number of references to this stream. Only can be
661	* destroyed if the reference count is reaching 0. */
662	uint32_t cRefs;
663	/** PCM properties. */
664	/** @todo Deprecated; remove. Use member Cfg instead. */
665	PDMPCMPROPS Props;
666	/** The stream's audio configuration. */
667	PDMAUDIOSTREAMCFG Cfg;
668	/** Stream status flag. */
669	PDMAUDIOSTRMSTS fStatus;
670	/** This stream's mixing buffer. */
671	PDMAUDIOMIXBUF MixBuf;
672	/** Audio direction of this stream. */
673	PDMAUDIODIR enmDir;
674	/** Context of this stream. */
675	PDMAUDIOSTREAMCTX enmCtx;
676	/** Timestamp (in ms) since last iteration. */
677	uint64_t tsLastIterateMS;
678	/** Union for input/output specifics. */
679	union
680	{
681	PDMAUDIOSTREAMIN In;
682	PDMAUDIOSTREAMOUT Out;
683	};
684	} PDMAUDIOSTREAM, *PPDMAUDIOSTREAM;
685
686	/** Pointer to a audio connector interface. */
687	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
688
689	#ifdef VBOX_WITH_AUDIO_CALLBACKS
690	/**
691	* Audio callback types. These are all kept generic as those
692	* are used by all device emulations across all backends.
693	*/
694	typedef enum PDMAUDIOCALLBACKTYPE
695	{
696	PDMAUDIOCALLBACKTYPE_GENERIC = 0,
697	PDMAUDIOCALLBACKTYPE_INPUT,
698	PDMAUDIOCALLBACKTYPE_OUTPUT
699	} PDMAUDIOCALLBACKTYPE;
700
701	/**
702	* Callback data for audio input.
703	*/
704	typedef struct PDMAUDIOCALLBACKDATAIN
705	{
706	/** Input: How many bytes are availabe as input for passing
707	* to the device emulation. */
708	uint32_t cbInAvail;
709	/** Output: How many bytes have been read. */
710	uint32_t cbOutRead;
711	} PDMAUDIOCALLBACKDATAIN, *PPDMAUDIOCALLBACKDATAIN;
712
713	/**
714	* Callback data for audio output.
715	*/
716	typedef struct PDMAUDIOCALLBACKDATAOUT
717	{
718	/** Input: How many bytes are free for the device emulation to write. */
719	uint32_t cbInFree;
720	/** Output: How many bytes were written by the device emulation. */
721	uint32_t cbOutWritten;
722	} PDMAUDIOCALLBACKDATAOUT, *PPDMAUDIOCALLBACKDATAOUT;
723
724	/**
725	* Structure for keeping an audio callback.
726	*/
727	typedef struct PDMAUDIOCALLBACK
728	{
729	RTLISTANCHOR Node;
730	PDMAUDIOCALLBACKTYPE enmType;
731	void *pvCtx;
732	size_t cbCtx;
733	DECLR3CALLBACKMEMBER(int, pfnCallback, (PDMAUDIOCALLBACKTYPE enmType, void pvCtx, size_t cbCtx, void pvUser, size_t cbUser));
734	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
735	#endif
736
737	/**
738	* Audio connector interface (up).
739	*/
740	typedef struct PDMIAUDIOCONNECTOR
741	{
742	/**
743	* Retrieves the current configuration of the host audio backend.
744	*
745	* @returns VBox status code.
746	* @param pInterface Pointer to the interface structure containing the called function pointer.
747	* @param pCfg Where to store the host audio backend configuration data.
748	*/
749	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
750
751	/**
752	* @todo Docs!
753	*/
754	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
755
756	/**
757	* Creates an audio stream.
758	*
759	* @returns VBox status code.
760	* @param pInterface Pointer to the interface structure containing the called function pointer.
761	* @param pCfgHost Stream configuration for host side.
762	* @param pCfgGuest Stream configuration for guest side.
763	* @param ppStream Pointer where to return the created audio stream on success.
764	*/
765	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
766
767	/**
768	* Destroys an audio stream.
769	*
770	* @param pInterface Pointer to the interface structure containing the called function pointer.
771	* @param pStream Pointer to audio stream.
772	*/
773	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
774
775	/**
776	* Adds a reference to the specified audio stream.
777	*
778	* @returns New reference count. UINT32_MAX on error.
779	* @param pInterface Pointer to the interface structure containing the called function pointer.
780	* @param pStream Pointer to audio stream adding the reference to.
781	*/
782	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
783
784	/**
785	* Releases a reference from the specified stream.
786	*
787	* @returns New reference count. UINT32_MAX on error.
788	* @param pInterface Pointer to the interface structure containing the called function pointer.
789	* @param pStream Pointer to audio stream releasing a reference from.
790	*/
791	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
792
793	/**
794	* Reads PCM audio data from the host (input).
795	*
796	* @returns VBox status code.
797	* @param pInterface Pointer to the interface structure containing the called function pointer.
798	* @param pStream Pointer to audio stream to write to.
799	* @param pvBuf Where to store the read data.
800	* @param cbBuf Number of bytes to read.
801	* @param pcbRead Bytes of audio data read. Optional.
802	*/
803	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
804
805	/**
806	* Writes PCM audio data to the host (output).
807	*
808	* @returns VBox status code.
809	* @param pInterface Pointer to the interface structure containing the called function pointer.
810	* @param pStream Pointer to audio stream to read from.
811	* @param pvBuf Audio data to be written.
812	* @param cbBuf Number of bytes to be written.
813	* @param pcbWritten Bytes of audio data written. Optional.
814	*/
815	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
816
817	/**
818	* Controls a specific audio stream.
819	*
820	* @returns VBox status code.
821	* @param pInterface Pointer to the interface structure containing the called function pointer.
822	* @param pStream Pointer to audio stream.
823	* @param enmStreamCmd The stream command to issue.
824	*/
825	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
826
827	/**
828	* Processes stream data.
829	*
830	* @param pInterface Pointer to the interface structure containing the called function pointer.
831	* @param pStream Pointer to audio stream.
832	* @param pcData Data (in audio samples) available. Optional.
833	*/
834	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
835
836	/**
837	* Returns the number of readable data (in bytes) of a specific audio input stream.
838	*
839	* @returns Number of readable data (in bytes).
840	* @param pInterface Pointer to the interface structure containing the called function pointer.
841	* @param pStream Pointer to audio stream.
842	*/
843	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
844
845	/**
846	* Returns the number of writable data (in bytes) of a specific audio output stream.
847	*
848	* @returns Number of writable data (in bytes).
849	* @param pInterface Pointer to the interface structure containing the called function pointer.
850	* @param pStream Pointer to audio stream.
851	*/
852	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
853
854	/**
855	* Returns the status of a specific audio stream.
856	*
857	* @returns Audio stream status
858	* @param pInterface Pointer to the interface structure containing the called function pointer.
859	* @param pStream Pointer to audio stream.
860	*/
861	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
862
863	/**
864	* Sets the audio volume of a specific audio stream.
865	*
866	* @returns VBox status code.
867	* @param pInterface Pointer to the interface structure containing the called function pointer.
868	* @param pStream Pointer to audio stream.
869	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
870	*/
871	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
872
873	/**
874	* Plays (transfers) available audio samples via the host backend. Only works with output streams.
875	*
876	* @returns VBox status code.
877	* @param pInterface Pointer to the interface structure containing the called function pointer.
878	* @param pcSamplesPlayed Number of samples played. Optional.
879	*/
880	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
881
882	/**
883	* Captures (transfers) available audio samples from the host backend. Only works with input streams.
884	*
885	* @returns VBox status code.
886	* @param pInterface Pointer to the interface structure containing the called function pointer.
887	* @param pcSamplesCaptured Number of samples captured. Optional.
888	*/
889	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
890
891	#ifdef VBOX_WITH_AUDIO_CALLBACKS
892	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
893	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType, void *pvUser, size_t cbUser));
894	#endif
895
896	} PDMIAUDIOCONNECTOR;
897
898	/** PDMIAUDIOCONNECTOR interface ID. */
899	#define PDMIAUDIOCONNECTOR_IID "C850CCE0-C5F4-42AB-BFC5-BACB41A8284D"
900
901
902
903	/**
904	* Assigns all needed interface callbacks for an audio backend.
905	*
906	* @param a_NamePrefix The function name prefix.
907	*/
908	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_NamePrefix) \
909	do { \
910	pThis->IHostAudio.pfnInit = RT_CONCAT(a_NamePrefix,Init); \
911	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_NamePrefix,Shutdown); \
912	pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_NamePrefix,GetConfig); \
913	pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_NamePrefix,GetStatus); \
914	pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_NamePrefix,StreamCreate); \
915	pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_NamePrefix,StreamDestroy); \
916	pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_NamePrefix,StreamControl); \
917	pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_NamePrefix,StreamGetStatus); \
918	pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_NamePrefix,StreamIterate); \
919	pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_NamePrefix,StreamPlay); \
920	pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_NamePrefix,StreamCapture); \
921	} while (0)
922
923	/** Pointer to a host audio interface. */
924	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
925	/**
926	* PDM host audio interface.
927	*/
928	typedef struct PDMIHOSTAUDIO
929	{
930	/**
931	* Initialize the host-specific audio device.
932	*
933	* @returns VBox status code.
934	* @param pInterface Pointer to the interface structure containing the called function pointer.
935	*/
936	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
937
938	/**
939	* Shuts down the host-specific audio device.
940	*
941	* @returns VBox status code.
942	* @param pInterface Pointer to the interface structure containing the called function pointer.
943	*/
944	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
945
946	/**
947	* Returns the configuration from the host audio (backend) driver.
948	*
949	* @returns VBox status code.
950	* @param pInterface Pointer to the interface structure containing the called function pointer.
951	* @param pBackendCfg Pointer where to store the backend audio configuration to.
952	*/
953	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
954
955	/**
956	* Returns the current status from the host audio (backend) driver.
957	*
958	* @returns PDMAUDIOBACKENDSTS enum.
959	* @param pInterface Pointer to the interface structure containing the called function pointer.
960	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
961	*/
962	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
963
964	/**
965	* Creates an audio stream.
966	*
967	* @returns VBox status code.
968	* @param pInterface Pointer to the interface structure containing the called function pointer.
969	* @param pStream Pointer to audio stream.
970	* @param pStreamCfg Pointer to stream configuration.
971	* @param pcSamples Returns how many samples the backend can handle. Optional.
972	*/
973	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfg, uint32_t *pcSamples));
974
975	/**
976	* Destroys an audio stream.
977	*
978	* @returns VBox status code.
979	* @param pInterface Pointer to the interface structure containing the called function pointer.
980	* @param pStream Pointer to audio stream.
981	*/
982	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
983
984	/**
985	* Controls an audio stream.
986	*
987	* @returns VBox status code.
988	* @param pInterface Pointer to the interface structure containing the called function pointer.
989	* @param pStream Pointer to audio stream.
990	* @param enmStreamCmd The stream command to issue.
991	*/
992	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
993
994	/**
995	* Returns whether the specified audio direction in the backend is enabled or not.
996	*
997	* @param pInterface Pointer to the interface structure containing the called function pointer.
998	* @param enmDir Audio direction to check status for.
999	*/
1000	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1001
1002	/**
1003	** @todo Docs!
1004	*/
1005	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1006
1007	/**
1008	* Plays an audio (output) stream.
1009	*
1010	* @returns VBox status code.
1011	* @param pInterface Pointer to the interface structure containing the called function pointer.
1012	* @param pStream Pointer to audio stream.
1013	* @param pcSamplesPlayed Pointer to number of samples captured.
1014	*/
1015	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
1016
1017	/**
1018	* Captures an audio (input) stream.
1019	*
1020	* @returns VBox status code.
1021	* @param pInterface Pointer to the interface structure containing the called function pointer.
1022	* @param pStream Pointer to audio stream.
1023	* @param pcSamplesCaptured Pointer to number of samples captured.
1024	*/
1025	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
1026
1027	} PDMIHOSTAUDIO;
1028
1029	/** PDMIHOSTAUDIO interface ID. */
1030	#define PDMIHOSTAUDIO_IID "96AC69D0-F301-42AC-8F1D-1E19BA808887"
1031
1032	/** @} */
1033
1034	#endif /* !___VBox_vmm_pdmaudioifs_h */
1035

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

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

Download in other formats: