pdmaudioifs.h@ 63687

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

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

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

Download in other formats: