pdmaudioifs.h@ 63597

Last change on this file since 63597 was 63597, checked in by vboxsync, 9 years ago
Audio/pdmaudioifs.h: Blow up PDMAUDIOBACKENDSTS and PDMAUDIOSTREAMCTX to 32-bit.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 37.5 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	/** Hint about the optimal sample buffer size (in audio samples).
265	* 0 if no hint is given. */
266	uint32_t cSampleBufferSize;
267	} PDMAUDIOSTREAMCFG, *PPDMAUDIOSTREAMCFG;
268
269	#if defined(RT_LITTLE_ENDIAN)
270	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
271	#elif defined(RT_BIG_ENDIAN)
272	# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
273	#else
274	# error "Port me!"
275	#endif
276
277	/**
278	* Audio mixer controls.
279	*/
280	typedef enum PDMAUDIOMIXERCTL
281	{
282	/** Unknown mixer control. */
283	PDMAUDIOMIXERCTL_UNKNOWN = 0,
284	/** Master volume. */
285	PDMAUDIOMIXERCTL_VOLUME_MASTER,
286	/** Front. */
287	PDMAUDIOMIXERCTL_FRONT,
288	/** Center / LFE (Subwoofer). */
289	PDMAUDIOMIXERCTL_CENTER_LFE,
290	/** Rear. */
291	PDMAUDIOMIXERCTL_REAR,
292	/** Line-In. */
293	PDMAUDIOMIXERCTL_LINE_IN,
294	/** Microphone-In. */
295	PDMAUDIOMIXERCTL_MIC_IN,
296	/** Hack to blow the type up to 32-bit. */
297	PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
298	} PDMAUDIOMIXERCTL;
299
300	/**
301	* Audio stream commands. Used in the audio connector
302	* as well as in the actual host backends.
303	*/
304	typedef enum PDMAUDIOSTREAMCMD
305	{
306	/** Unknown command, do not use. */
307	PDMAUDIOSTREAMCMD_UNKNOWN = 0,
308	/** Enables the stream. */
309	PDMAUDIOSTREAMCMD_ENABLE,
310	/** Disables the stream. */
311	PDMAUDIOSTREAMCMD_DISABLE,
312	/** Pauses the stream. */
313	PDMAUDIOSTREAMCMD_PAUSE,
314	/** Resumes the stream. */
315	PDMAUDIOSTREAMCMD_RESUME,
316	/** Hack to blow the type up to 32-bit. */
317	PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
318	} PDMAUDIOSTREAMCMD;
319
320	/**
321	* Properties of audio streams for host/guest
322	* for in or out directions.
323	*/
324	typedef struct PDMAUDIOPCMPROPS
325	{
326	/** Sample width. Bits per sample. */
327	uint8_t cBits;
328	/** Signed or unsigned sample. */
329	bool fSigned;
330	/** Shift count used for faster calculation of various
331	* values, such as the alignment, bytes to samples and so on.
332	* Depends on number of stream channels and the stream format
333	* being used.
334	*
335	** @todo Use some RTAsmXXX functions instead?
336	*/
337	uint8_t cShift;
338	/** Number of audio channels. */
339	uint8_t cChannels;
340	/** Alignment mask. */
341	uint32_t uAlign;
342	/** Sample frequency in Hertz (Hz). */
343	uint32_t uHz;
344	/** Bitrate (in bytes/s). */
345	uint32_t cbBitrate;
346	/** Whether the endianness is swapped or not. */
347	bool fSwapEndian;
348	} PDMAUDIOPCMPROPS, *PPDMAUDIOPCMPROPS;
349
350	/**
351	* Audio volume parameters.
352	*/
353	typedef struct PDMAUDIOVOLUME
354	{
355	/** Set to @c true if this stream is muted, @c false if not. */
356	bool fMuted;
357	/** Left channel volume.
358	* Range is from [0 ... 255], whereas 0 specifies
359	* the most silent and 255 the loudest value. */
360	uint8_t uLeft;
361	/** Right channel volume.
362	* Range is from [0 ... 255], whereas 0 specifies
363	* the most silent and 255 the loudest value. */
364	uint8_t uRight;
365	} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
366
367	/** Defines the minimum volume allowed. */
368	#define PDMAUDIO_VOLUME_MIN (0)
369	/** Defines the maximum volume allowed. */
370	#define PDMAUDIO_VOLUME_MAX (255)
371
372	/**
373	* Structure for holding rate processing information
374	* of a source + destination audio stream. This is needed
375	* because both streams can differ regarding their rates
376	* and therefore need to be treated accordingly.
377	*/
378	typedef struct PDMAUDIOSTRMRATE
379	{
380	/** Current (absolute) offset in the output
381	* (destination) stream. */
382	uint64_t dstOffset;
383	/** Increment for moving dstOffset for the
384	* destination stream. This is needed because the
385	* source <-> destination rate might be different. */
386	uint64_t dstInc;
387	/** Current (absolute) offset in the input
388	* stream. */
389	uint32_t srcOffset;
390	/** Last processed sample of the input stream.
391	* Needed for interpolation. */
392	PDMAUDIOSAMPLE srcSampleLast;
393	} PDMAUDIOSTRMRATE, *PPDMAUDIOSTRMRATE;
394
395	/**
396	* Structure for holding mixing buffer volume parameters.
397	* The volume values are in fixed point style and must
398	* be converted to/from before using with e.g. PDMAUDIOVOLUME.
399	*/
400	typedef struct PDMAUDMIXBUFVOL
401	{
402	/** Set to @c true if this stream is muted, @c false if not. */
403	bool fMuted;
404	/** Left volume to apply during conversion. Pass 0
405	* to convert the original values. May not apply to
406	* all conversion functions. */
407	uint32_t uLeft;
408	/** Right volume to apply during conversion. Pass 0
409	* to convert the original values. May not apply to
410	* all conversion functions. */
411	uint32_t uRight;
412	} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
413
414	/**
415	* Structure for holding sample conversion parameters for
416	* the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
417	*/
418	typedef struct PDMAUDMIXBUFCONVOPTS
419	{
420	/** Number of audio samples to convert. */
421	uint32_t cSamples;
422	union
423	{
424	struct
425	{
426	/** Volume to use for conversion. */
427	PDMAUDMIXBUFVOL Volume;
428	} From;
429	};
430	} PDMAUDMIXBUFCONVOPTS;
431	/** Pointer to conversion parameters for the audio mixer. */
432	typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
433	/** Pointer to const conversion parameters for the audio mixer. */
434	typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
435
436	/**
437	* Note: All internal handling is done in samples,
438	* not in bytes!
439	*/
440	typedef uint32_t PDMAUDIOMIXBUFFMT;
441	typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
442
443	/**
444	* Convertion-from function used by the PDM audio buffer mixer.
445	*
446	* @returns Number of samples returned.
447	* @param paDst Where to return the converted samples.
448	* @param pvSrc The source samples bytes.
449	* @param cbSrc Number of bytes to convert.
450	* @param pOpts Conversion options.
451	*/
452	typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOSAMPLE paDst, const void *pvSrc, uint32_t cbSrc,
453	PCPDMAUDMIXBUFCONVOPTS pOpts);
454	/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
455	typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
456
457	/**
458	* Convertion-to function used by the PDM audio buffer mixer.
459	*
460	* @param pvDst Output buffer.
461	* @param paSrc The input samples.
462	* @param pOpts Conversion options.
463	*/
464	typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOSAMPLE paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
465	/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
466	typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
467
468	typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
469	typedef struct PDMAUDIOMIXBUF
470	{
471	RTLISTNODE Node;
472	/** Name of the buffer. */
473	char *pszName;
474	/** Sample buffer. */
475	PPDMAUDIOSAMPLE pSamples;
476	/** Size of the sample buffer (in samples). */
477	uint32_t cSamples;
478	/** The current read position (in samples). */
479	uint32_t offRead;
480	/** The current write position (in samples). */
481	uint32_t offWrite;
482	/**
483	* Total samples already mixed down to the parent buffer (if any). Always starting at
484	* the parent's offRead position.
485	*
486	* Note: Count always is specified in parent samples, as the sample count can differ between parent
487	* and child.
488	*/
489	uint32_t cMixed;
490	/** How much audio samples are currently being used
491	* in this buffer.
492	* Note: This also is known as the distance in ring buffer terms. */
493	uint32_t cUsed;
494	/** Pointer to parent buffer (if any). */
495	PPDMAUDIOMIXBUF pParent;
496	/** List of children mix buffers to keep in sync with (if being a parent buffer). */
497	RTLISTANCHOR lstChildren;
498	/** Intermediate structure for buffer conversion tasks. */
499	PPDMAUDIOSTRMRATE pRate;
500	/** Internal representation of current volume used for mixing. */
501	PDMAUDMIXBUFVOL Volume;
502	/** This buffer's audio format. */
503	PDMAUDIOMIXBUFFMT AudioFmt;
504	/** Standard conversion-to function for set AudioFmt. */
505	PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
506	/** Standard conversion-from function for set AudioFmt. */
507	PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
508	/**
509	* Ratio of the associated parent stream's frequency by this stream's
510	* frequency (1<<32), represented as a signed 64 bit integer.
511	*
512	* For example, if the parent stream has a frequency of 44 khZ, and this
513	* stream has a frequency of 11 kHz, the ration then would be
514	* (44/11 * (1 << 32)).
515	*
516	* Currently this does not get changed once assigned.
517	*/
518	int64_t iFreqRatio;
519	/** For quickly converting samples <-> bytes and vice versa. */
520	uint8_t cShift;
521	} PDMAUDIOMIXBUF;
522
523	typedef uint32_t PDMAUDIOFILEFLAGS;
524
525	/* No flags defined. */
526	#define PDMAUDIOFILEFLAG_NONE 0
527
528	/**
529	* Audio file types.
530	*/
531	typedef enum PDMAUDIOFILETYPE
532	{
533	/** Unknown type, do not use. */
534	PDMAUDIOFILETYPE_UNKNOWN = 0,
535	/** Wave (.WAV) file. */
536	PDMAUDIOFILETYPE_WAV
537	} PDMAUDIOFILETYPE;
538
539	/**
540	* Structure for an audio file handle.
541	*/
542	typedef struct PDMAUDIOFILE
543	{
544	/** Type of the audio file. */
545	PDMAUDIOFILETYPE enmType;
546	/** File name. */
547	char szName[255];
548	/** Actual file handle. */
549	RTFILE hFile;
550	/** Data needed for the specific audio file type implemented.
551	* Optional, can be NULL. */
552	void *pvData;
553	/** Data size (in bytes). */
554	size_t cbData;
555	} PDMAUDIOFILE, *PPDMAUDIOFILE;
556
557	/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
558	typedef uint32_t PDMAUDIOSTRMSTS;
559
560	/** No flags being set. */
561	#define PDMAUDIOSTRMSTS_FLAG_NONE 0
562	/** Whether this stream has been initialized by the
563	* backend or not. */
564	#define PDMAUDIOSTRMSTS_FLAG_INITIALIZED RT_BIT_32(0)
565	/** Whether this stream is enabled or disabled. */
566	#define PDMAUDIOSTRMSTS_FLAG_ENABLED RT_BIT_32(1)
567	/** Whether this stream has been paused or not. This also implies
568	* that this is an enabled stream! */
569	#define PDMAUDIOSTRMSTS_FLAG_PAUSED RT_BIT_32(2)
570	/** Whether this stream was marked as being disabled
571	* but there are still associated guest output streams
572	* which rely on its data. */
573	#define PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
574	/** Data can be read from the stream. */
575	#define PDMAUDIOSTRMSTS_FLAG_DATA_READABLE RT_BIT_32(4)
576	/** Data can be written to the stream. */
577	#define PDMAUDIOSTRMSTS_FLAG_DATA_WRITABLE RT_BIT_32(5)
578	/** Whether this stream is in re-initialization phase.
579	* All other bits remain untouched to be able to restore
580	* the stream's state after the re-initialization bas been
581	* finished. */
582	#define PDMAUDIOSTRMSTS_FLAG_PENDING_REINIT RT_BIT_32(6)
583	/** Validation mask. */
584	#define PDMAUDIOSTRMSTS_VALID_MASK UINT32_C(0x0000007F)
585
586	/**
587	* Enumeration presenting a backend's current status.
588	*/
589	typedef enum PDMAUDIOBACKENDSTS
590	{
591	/** Unknown/invalid status. */
592	PDMAUDIOBACKENDSTS_UNKNOWN = 0,
593	/** The backend is in its initialization phase.
594	* Not all backends support this status. */
595	PDMAUDIOBACKENDSTS_INITIALIZING,
596	/** The backend has stopped its operation. */
597	PDMAUDIOBACKENDSTS_STOPPED,
598	/** The backend is up and running. */
599	PDMAUDIOBACKENDSTS_RUNNING,
600	/** The backend ran into an error and is unable to recover.
601	* A manual re-initialization might help. */
602	PDMAUDIOBACKENDSTS_ERROR,
603	/** Hack to blow the type up to 32-bit. */
604	PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
605	} PDMAUDIOBACKENDSTS;
606
607	/**
608	* Audio stream context.
609	*/
610	typedef enum PDMAUDIOSTREAMCTX
611	{
612	/** No context set / invalid. */
613	PDMAUDIOSTREAMCTX_UNKNOWN = 0,
614	/** Host stream, connected to a backend. */
615	PDMAUDIOSTREAMCTX_HOST,
616	/** Guest stream, connected to the device emulation. */
617	PDMAUDIOSTREAMCTX_GUEST,
618	/** Hack to blow the type up to 32-bit. */
619	PDMAUDIOSTREAMCTX_32BIT_HACK = 0x7fffffff
620	} PDMAUDIOSTREAMCTX;
621
622	/**
623	* Structure for keeping audio input stream specifics.
624	* Do not use directly. Instead, use PDMAUDIOSTREAM.
625	*/
626	typedef struct PDMAUDIOSTREAMIN
627	{
628	/** Timestamp (in ms) since last read. */
629	uint64_t tsLastReadMS;
630	#ifdef VBOX_WITH_STATISTICS
631	STAMCOUNTER StatBytesElapsed;
632	STAMCOUNTER StatBytesTotalRead;
633	STAMCOUNTER StatSamplesCaptured;
634	#endif
635	} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
636
637	/**
638	* Structure for keeping audio output stream specifics.
639	* Do not use directly. Instead, use PDMAUDIOSTREAM.
640	*/
641	typedef struct PDMAUDIOSTREAMOUT
642	{
643	/** Timestamp (in ms) since last write. */
644	uint64_t tsLastWriteMS;
645	#ifdef VBOX_WITH_STATISTICS
646	STAMCOUNTER StatBytesElapsed;
647	STAMCOUNTER StatBytesTotalWritten;
648	STAMCOUNTER StatSamplesPlayed;
649	#endif
650	} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
651
652	struct PDMAUDIOSTREAM;
653	typedef PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
654
655	/**
656	* Structure for maintaining an nput/output audio stream.
657	*/
658	typedef struct PDMAUDIOSTREAM
659	{
660	/** List node. */
661	RTLISTNODE Node;
662	/** Pointer to the other pair of this stream.
663	* This might be the host or guest side. */
664	PPDMAUDIOSTREAM pPair;
665	/** Name of this stream. */
666	char szName[64];
667	/** Number of references to this stream. Only can be
668	* destroyed if the reference count is reaching 0. */
669	uint32_t cRefs;
670	/** The stream's audio configuration. */
671	PDMAUDIOSTREAMCFG Cfg;
672	/** Stream status flag. */
673	PDMAUDIOSTRMSTS fStatus;
674	/** This stream's mixing buffer. */
675	PDMAUDIOMIXBUF MixBuf;
676	/** Audio direction of this stream. */
677	PDMAUDIODIR enmDir;
678	/** Context of this stream. */
679	PDMAUDIOSTREAMCTX enmCtx;
680	/** Timestamp (in ms) since last iteration. */
681	uint64_t tsLastIterateMS;
682	/** Union for input/output specifics. */
683	union
684	{
685	PDMAUDIOSTREAMIN In;
686	PDMAUDIOSTREAMOUT Out;
687	};
688	} PDMAUDIOSTREAM, *PPDMAUDIOSTREAM;
689
690	/** Pointer to a audio connector interface. */
691	typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
692
693	#ifdef VBOX_WITH_AUDIO_CALLBACKS
694	/**
695	* Audio callback types. These are all kept generic as those
696	* are used by all device emulations across all backends.
697	*/
698	typedef enum PDMAUDIOCALLBACKTYPE
699	{
700	PDMAUDIOCALLBACKTYPE_GENERIC = 0,
701	PDMAUDIOCALLBACKTYPE_INPUT,
702	PDMAUDIOCALLBACKTYPE_OUTPUT
703	} PDMAUDIOCALLBACKTYPE;
704
705	/**
706	* Callback data for audio input.
707	*/
708	typedef struct PDMAUDIOCALLBACKDATAIN
709	{
710	/** Input: How many bytes are availabe as input for passing
711	* to the device emulation. */
712	uint32_t cbInAvail;
713	/** Output: How many bytes have been read. */
714	uint32_t cbOutRead;
715	} PDMAUDIOCALLBACKDATAIN, *PPDMAUDIOCALLBACKDATAIN;
716
717	/**
718	* Callback data for audio output.
719	*/
720	typedef struct PDMAUDIOCALLBACKDATAOUT
721	{
722	/** Input: How many bytes are free for the device emulation to write. */
723	uint32_t cbInFree;
724	/** Output: How many bytes were written by the device emulation. */
725	uint32_t cbOutWritten;
726	} PDMAUDIOCALLBACKDATAOUT, *PPDMAUDIOCALLBACKDATAOUT;
727
728	/**
729	* Structure for keeping an audio callback.
730	*/
731	typedef struct PDMAUDIOCALLBACK
732	{
733	RTLISTANCHOR Node;
734	PDMAUDIOCALLBACKTYPE enmType;
735	void *pvCtx;
736	size_t cbCtx;
737	DECLR3CALLBACKMEMBER(int, pfnCallback, (PDMAUDIOCALLBACKTYPE enmType, void pvCtx, size_t cbCtx, void pvUser, size_t cbUser));
738	} PDMAUDIOCALLBACK, *PPDMAUDIOCALLBACK;
739	#endif
740
741	/**
742	* Audio connector interface (up).
743	*/
744	typedef struct PDMIAUDIOCONNECTOR
745	{
746	/**
747	* Retrieves the current configuration of the host audio backend.
748	*
749	* @returns VBox status code.
750	* @param pInterface Pointer to the interface structure containing the called function pointer.
751	* @param pCfg Where to store the host audio backend configuration data.
752	*/
753	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
754
755	/**
756	* @todo Docs!
757	*/
758	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
759
760	/**
761	* Creates an audio stream.
762	*
763	* @returns VBox status code.
764	* @param pInterface Pointer to the interface structure containing the called function pointer.
765	* @param pCfgHost Stream configuration for host side.
766	* @param pCfgGuest Stream configuration for guest side.
767	* @param ppStream Pointer where to return the created audio stream on success.
768	*/
769	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
770
771	/**
772	* Destroys an audio stream.
773	*
774	* @param pInterface Pointer to the interface structure containing the called function pointer.
775	* @param pStream Pointer to audio stream.
776	*/
777	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
778
779	/**
780	* Adds a reference to the specified audio stream.
781	*
782	* @returns New reference count. UINT32_MAX on error.
783	* @param pInterface Pointer to the interface structure containing the called function pointer.
784	* @param pStream Pointer to audio stream adding the reference to.
785	*/
786	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
787
788	/**
789	* Releases a reference from the specified stream.
790	*
791	* @returns New reference count. UINT32_MAX on error.
792	* @param pInterface Pointer to the interface structure containing the called function pointer.
793	* @param pStream Pointer to audio stream releasing a reference from.
794	*/
795	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
796
797	/**
798	* Reads PCM audio data from the host (input).
799	*
800	* @returns VBox status code.
801	* @param pInterface Pointer to the interface structure containing the called function pointer.
802	* @param pStream Pointer to audio stream to write to.
803	* @param pvBuf Where to store the read data.
804	* @param cbBuf Number of bytes to read.
805	* @param pcbRead Bytes of audio data read. Optional.
806	*/
807	DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
808
809	/**
810	* Writes PCM audio data to the host (output).
811	*
812	* @returns VBox status code.
813	* @param pInterface Pointer to the interface structure containing the called function pointer.
814	* @param pStream Pointer to audio stream to read from.
815	* @param pvBuf Audio data to be written.
816	* @param cbBuf Number of bytes to be written.
817	* @param pcbWritten Bytes of audio data written. Optional.
818	*/
819	DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
820
821	/**
822	* Controls a specific audio stream.
823	*
824	* @returns VBox status code.
825	* @param pInterface Pointer to the interface structure containing the called function pointer.
826	* @param pStream Pointer to audio stream.
827	* @param enmStreamCmd The stream command to issue.
828	*/
829	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
830
831	/**
832	* Processes stream data.
833	*
834	* @param pInterface Pointer to the interface structure containing the called function pointer.
835	* @param pStream Pointer to audio stream.
836	* @param pcData Data (in audio samples) available. Optional.
837	*/
838	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
839
840	/**
841	* Returns the number of readable data (in bytes) of a specific audio input stream.
842	*
843	* @returns Number of readable data (in bytes).
844	* @param pInterface Pointer to the interface structure containing the called function pointer.
845	* @param pStream Pointer to audio stream.
846	*/
847	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
848
849	/**
850	* Returns the number of writable data (in bytes) of a specific audio output stream.
851	*
852	* @returns Number of writable data (in bytes).
853	* @param pInterface Pointer to the interface structure containing the called function pointer.
854	* @param pStream Pointer to audio stream.
855	*/
856	DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
857
858	/**
859	* Returns the status of a specific audio stream.
860	*
861	* @returns Audio stream status
862	* @param pInterface Pointer to the interface structure containing the called function pointer.
863	* @param pStream Pointer to audio stream.
864	*/
865	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
866
867	/**
868	* Sets the audio volume of a specific audio stream.
869	*
870	* @returns VBox status code.
871	* @param pInterface Pointer to the interface structure containing the called function pointer.
872	* @param pStream Pointer to audio stream.
873	* @param pVol Pointer to audio volume structure to set the stream's audio volume to.
874	*/
875	DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
876
877	/**
878	* Plays (transfers) available audio samples via the host backend. Only works with output streams.
879	*
880	* @returns VBox status code.
881	* @param pInterface Pointer to the interface structure containing the called function pointer.
882	* @param pcSamplesPlayed Number of samples played. Optional.
883	*/
884	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed));
885
886	/**
887	* Captures (transfers) available audio samples from the host backend. Only works with input streams.
888	*
889	* @returns VBox status code.
890	* @param pInterface Pointer to the interface structure containing the called function pointer.
891	* @param pcSamplesCaptured Number of samples captured. Optional.
892	*/
893	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured));
894
895	#ifdef VBOX_WITH_AUDIO_CALLBACKS
896	DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks));
897	DECLR3CALLBACKMEMBER(int, pfnCallback, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType, void *pvUser, size_t cbUser));
898	#endif
899
900	} PDMIAUDIOCONNECTOR;
901
902	/** PDMIAUDIOCONNECTOR interface ID. */
903	#define PDMIAUDIOCONNECTOR_IID "C850CCE0-C5F4-42AB-BFC5-BACB41A8284D"
904
905
906
907	/**
908	* Assigns all needed interface callbacks for an audio backend.
909	*
910	* @param a_Prefix The function name prefix.
911	*/
912	#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_Prefix) \
913	do { \
914	pThis->IHostAudio.pfnInit = RT_CONCAT(a_Prefix,Init); \
915	pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_Prefix,Shutdown); \
916	pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_Prefix,GetConfig); \
917	pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_Prefix,GetStatus); \
918	pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_Prefix,StreamCreate); \
919	pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_Prefix,StreamDestroy); \
920	pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_Prefix,StreamControl); \
921	pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_Prefix,StreamGetStatus); \
922	pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_Prefix,StreamIterate); \
923	pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_Prefix,StreamPlay); \
924	pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_Prefix,StreamCapture); \
925	} while (0)
926
927	/** Pointer to a host audio interface. */
928	typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
929	/**
930	* PDM host audio interface.
931	*/
932	typedef struct PDMIHOSTAUDIO
933	{
934	/**
935	* Initialize the host-specific audio device.
936	*
937	* @returns VBox status code.
938	* @param pInterface Pointer to the interface structure containing the called function pointer.
939	*/
940	DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
941
942	/**
943	* Shuts down the host-specific audio device.
944	*
945	* @returns VBox status code.
946	* @param pInterface Pointer to the interface structure containing the called function pointer.
947	*/
948	DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
949
950	/**
951	* Returns the configuration from the host audio (backend) driver.
952	*
953	* @returns VBox status code.
954	* @param pInterface Pointer to the interface structure containing the called function pointer.
955	* @param pBackendCfg Pointer where to store the backend audio configuration to.
956	*/
957	DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
958
959	/**
960	* Returns the current status from the host audio (backend) driver.
961	*
962	* @returns PDMAUDIOBACKENDSTS enum.
963	* @param pInterface Pointer to the interface structure containing the called function pointer.
964	* @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
965	*/
966	DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
967
968	/**
969	* Creates an audio stream using the requested stream configuration.
970	* If a backend is not able to create this configuration, it will return its best match in the acquired configuration
971	* structure on success.
972	*
973	* @returns VBox status code.
974	* @param pInterface Pointer to the interface structure containing the called function pointer.
975	* @param pStream Pointer to audio stream.
976	* @param pCfgReq Pointer to requested stream configuration.
977	* @param pCfgAcq Pointer to acquired stream configuration.
978	*/
979	DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
980
981	/**
982	* Destroys an audio stream.
983	*
984	* @returns VBox status code.
985	* @param pInterface Pointer to the interface structure containing the called function pointer.
986	* @param pStream Pointer to audio stream.
987	*/
988	DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
989
990	/**
991	* Controls an audio stream.
992	*
993	* @returns VBox status code.
994	* @param pInterface Pointer to the interface structure containing the called function pointer.
995	* @param pStream Pointer to audio stream.
996	* @param enmStreamCmd The stream command to issue.
997	*/
998	DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
999
1000	/**
1001	* Returns whether the specified audio direction in the backend is enabled or not.
1002	*
1003	* @returns PDMAUDIOSTRMSTS
1004	* @param pInterface Pointer to the interface structure containing the called function pointer.
1005	* @param enmDir Audio direction to check status for.
1006	*/
1007	DECLR3CALLBACKMEMBER(PDMAUDIOSTRMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1008
1009	/**
1010	* Gives the host backend the chance to do some (necessary) iteration work.
1011	*
1012	* @returns VBox status code.
1013	* @param pInterface Pointer to the interface structure containing the called function pointer.
1014	* @param pStream Pointer to audio stream.
1015	*/
1016	DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream));
1017
1018	/**
1019	* Plays (writes to) an audio (output) stream.
1020	*
1021	* @returns VBox status code.
1022	* @param pInterface Pointer to the interface structure containing the called function pointer.
1023	* @param pStream Pointer to audio stream.
1024	* @param pvBuf Pointer to audio data buffer to play. Currently not used and must be NULL.
1025	* @param cbBuf Size (in bytes) of audio data buffer. Currently not used and must be 0.
1026	* @param pcbWritten Returns number of bytes written. Optional.
1027	*/
1028	DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, const void pvBuf, uint32_t cbBuf, uint32_t pcbWritten));
1029
1030	/**
1031	* Captures (reads from) an audio (input) stream.
1032	*
1033	* @returns VBox status code.
1034	* @param pInterface Pointer to the interface structure containing the called function pointer.
1035	* @param pStream Pointer to audio stream.
1036	* @param pvBuf Buffer where to store read audio data. Currently not used and must be NULL.
1037	* @param cbBuf Size (in bytes) of buffer. Currently not used and must be 0.
1038	* @param pcbRead Returns number of bytes read. Optional.
1039	*/
1040	DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOSTREAM pStream, void pvBuf, uint32_t cbBuf, uint32_t pcbRead));
1041
1042	} PDMIHOSTAUDIO;
1043
1044	/** PDMIHOSTAUDIO interface ID. */
1045	#define PDMIHOSTAUDIO_IID "2922C325-79D3-4E66-B60F-0082878522FE"
1046
1047	/** @} */
1048
1049	#endif /* !___VBox_vmm_pdmaudioifs_h */
1050

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

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

Download in other formats: