VirtualBox

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

最後變更 在這個檔案從60177是 59987,由 vboxsync 提交於 9 年 前

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

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette