VirtualBox

source: vbox/trunk/include/VBox/vmm/pdmaudioifs_old.h@ 61648

Last change on this file since 61648 was 61413, checked in by vboxsync, 9 years ago

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

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