VirtualBox

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

Last change on this file since 76399 was 75962, checked in by vboxsync, 6 years ago

Forward ported r127158 (Audio/HDA: Implemented support for Windows 10 Build 1809 default surround speaker setup) + build fixes (r127159, r127160, r127162, r127165, r127167).
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 67.6 KB
Line 
1/** @file
2 * PDM - Pluggable Device Manager, audio interfaces.
3 */
4
5/*
6 * Copyright (C) 2006-2018 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/**
27 * == Audio architecture overview
28 *
29 * The audio architecture mainly consists of two PDM interfaces, PDMAUDIOCONNECTOR
30 * and PDMIHOSTAUDIO.
31 *
32 * The PDMAUDIOCONNECTOR interface is responsible of connecting a device emulation, such
33 * as SB16, AC'97 and HDA to one or multiple audio backend(s). Its API abstracts audio
34 * stream handling and I/O functions, device enumeration and so on.
35 *
36 * The PDMIHOSTAUDIO interface must be implemented by all audio backends to provide an
37 * abstract and common way of accessing needed functions, such as transferring output audio
38 * data for playing audio or recording input from the host.
39 *
40 * A device emulation can have one or more LUNs attached to it, whereas these LUNs in turn
41 * then all have their own PDMIAUDIOCONNECTOR, making it possible to connect multiple backends
42 * to a certain device emulation stream (multiplexing).
43 *
44 * An audio backend's job is to record and/or play audio data (depending on its capabilities).
45 * It highly depends on the host it's running on and needs very specific (host-OS-dependent) code.
46 * The backend itself only has very limited ways of accessing and/or communicating with the
47 * PDMIAUDIOCONNECTOR interface via callbacks, but never directly with the device emulation or
48 * other parts of the audio sub system.
49 *
50 *
51 * == Mixing
52 *
53 * The AUDIOMIXER API is optionally available to create and manage virtual audio mixers.
54 * Such an audio mixer in turn then can be used by the device emulation code to manage all
55 * the multiplexing to/from the connected LUN audio streams.
56 *
57 * Currently only input and output stream are supported. Duplex stream are not supported yet.
58 *
59 * This also is handy if certain LUN audio streams should be added or removed during runtime.
60 *
61 * To create a group of either input or output streams the AUDMIXSINK API can be used.
62 *
63 * For example: The device emulation has one hardware output stream (HW0), and that output
64 * stream shall be available to all connected LUN backends. For that to happen,
65 * an AUDMIXSINK sink has to be created and attached to the device's AUDIOMIXER object.
66 *
67 * As every LUN has its own AUDMIXSTREAM object, adding all those objects to the
68 * just created audio mixer sink will do the job.
69 *
70 * Note: The AUDIOMIXER API is purely optional and is not used by all currently implemented
71 * device emulations (e.g. SB16).
72 *
73 *
74 * == Data processing
75 *
76 * Audio input / output data gets handed-off to/from the device emulation in an unmodified
77 * - that is, raw - way. The actual audio frame / sample conversion is done via the PDMAUDIOMIXBUF API.
78 *
79 * This concentrates the audio data processing in one place and makes it easier to test / benchmark
80 * such code.
81 *
82 * A PDMAUDIOFRAME is the internal representation of a single audio frame, which consists of a single left
83 * and right audio sample in time. Only mono (1) and stereo (2) channel(s) currently are supported.
84 *
85 *
86 * == Timing
87 *
88 * Handling audio data in a virtual environment is hard, as the human perception is very sensitive
89 * to the slightest cracks and stutters in the audible data. This can happen if the VM's timing is
90 * lagging behind or not within the expected time frame.
91 *
92 * The two main components which unfortunately contradict each other is a) the audio device emulation
93 * and b) the audio backend(s) on the host. Those need to be served in a timely manner to function correctly.
94 * To make e.g. the device emulation rely on the pace the host backend(s) set - or vice versa - will not work,
95 * as the guest's audio system / drivers then will not be able to compensate this accordingly.
96 *
97 * So each component, the device emulation, the audio connector(s) and the backend(s) must do its thing
98 * *when* it needs to do it, independently of the others. For that we use various (small) ring buffers to
99 * (hopefully) serve all components with the amount of data *when* they need it.
100 *
101 * Additionally, the device emulation can run with a different audio frame size, while the backends(s) may
102 * require a different frame size (16 bit stereo -> 8 bit mono, for example).
103 *
104 * The device emulation can give the audio connector(s) a scheduling hint (optional), e.g. in which interval
105 * it expects any data processing.
106 *
107 * A data transfer for playing audio data from the guest on the host looks like this:
108 * (RB = Ring Buffer, MB = Mixing Buffer)
109 *
110 * (A) Device DMA -> (B) Device RB -> (C) Audio Connector Guest MB -> (D) Audio Connector Host MB -> \
111 * (E) Backend RB (optional, up to the backend) > (F) Backend audio framework
112 *
113 * For capturing audio data the above chain is similar, just in a different direction, of course.
114 *
115 * The audio connector hereby plays a key role when it comes to (pre-) buffering data to minimize any audio stutters
116 * and/or cracks. The following values, which also can be tweaked via CFGM / extra-data are available:
117 *
118 * - The pre-buffering time (in ms): Audio data which needs to be buffered before any playback (or capturing) can happen.
119 * - The actual buffer size (in ms): How big the mixing buffer (for C and D) will be.
120 * - The period size (in ms): How big a chunk of audio (often called period or fragment) for F must be to get handled correctly.
121 *
122 * The above values can be set on a per-driver level, whereas input and output streams for a driver also can be handled
123 * set independently. The verbose audio (release) log will tell about the (final) state of each audio stream.
124 *
125 *
126 * == Diagram
127 *
128 * +-------------------------+
129 * +-------------------------+ +-------------------------+ +-------------------+
130 * |PDMAUDIOSTREAM | |PDMAUDIOCONNECTOR | + ++|LUN |
131 * |-------------------------| |-------------------------| | |||-------------------|
132 * |PDMAUDIOMIXBUF |+------>|PDMAUDIOSTREAM Host |+---|-|||PDMIAUDIOCONNECTOR |
133 * |PDMAUDIOSTREAMCFG |+------>|PDMAUDIOSTREAM Guest | | |||AUDMIXSTREAM |
134 * | | |Device capabilities | | ||| |
135 * | | |Device configuration | | ||| |
136 * | | | | | ||| |
137 * | | +|PDMIHOSTAUDIO | | ||| |
138 * | | ||+-----------------------+| | ||+-------------------+
139 * +-------------------------+ |||Backend storage space || | ||
140 * ||+-----------------------+| | ||
141 * |+-------------------------+ | ||
142 * | | ||
143 * +---------------------+ | | ||
144 * |PDMIHOSTAUDIO | | | ||
145 * |+--------------+ | | +-------------------+ | || +-------------+
146 * ||DirectSound | | | |AUDMIXSINK | | || |AUDIOMIXER |
147 * |+--------------+ | | |-------------------| | || |-------------|
148 * | | | |AUDMIXSTREAM0 |+---|-||----->|AUDMIXSINK0 |
149 * |+--------------+ | | |AUDMIXSTREAM1 |+---|-||----->|AUDMIXSINK1 |
150 * ||PulseAudio | | | |AUDMIXSTREAMn |+---|-||----->|AUDMIXSINKn |
151 * |+--------------+ |+----------+ +-------------------+ | || +-------------+
152 * | | | ||
153 * |+--------------+ | | ||
154 * ||Core Audio | | | ||
155 * |+--------------+ | | ||
156 * | | | ||
157 * | | | ||+----------------------------------+
158 * | | | |||Device (SB16 / AC'97 / HDA) |
159 * | | | |||----------------------------------|
160 * +---------------------+ | |||AUDIOMIXER (Optional) |
161 * | |||AUDMIXSINK0 (Optional) |
162 * | |||AUDMIXSINK1 (Optional) |
163 * | |||AUDMIXSINKn (Optional) |
164 * | ||| |
165 * | |+|LUN0 |
166 * | ++|LUN1 |
167 * +--+|LUNn |
168 * | |
169 * | |
170 * | |
171 * +----------------------------------+
172 */
173
174#ifndef ___VBox_vmm_pdmaudioifs_h
175#define ___VBox_vmm_pdmaudioifs_h
176
177#include <iprt/assertcompile.h>
178#include <iprt/circbuf.h>
179#include <iprt/list.h>
180#include <iprt/path.h>
181
182#include <VBox/types.h>
183#ifdef VBOX_WITH_STATISTICS
184# include <VBox/vmm/stam.h>
185#endif
186
187/** @defgroup grp_pdm_ifs_audio PDM Audio Interfaces
188 * @ingroup grp_pdm_interfaces
189 * @{
190 */
191
192#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
193# ifdef RT_OS_WINDOWS
194# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
195# else
196# define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "/tmp/"
197# endif
198#endif
199
200/** PDM audio driver instance flags. */
201typedef uint32_t PDMAUDIODRVFLAGS;
202
203/** No flags set. */
204#define PDMAUDIODRVFLAGS_NONE 0
205/** Marks a primary audio driver which is critical
206 * when running the VM. */
207#define PDMAUDIODRVFLAGS_PRIMARY RT_BIT(0)
208
209/**
210 * Audio format in signed or unsigned variants.
211 */
212typedef enum PDMAUDIOFMT
213{
214 /** Invalid format, do not use. */
215 PDMAUDIOFMT_INVALID,
216 /** 8-bit, unsigned. */
217 PDMAUDIOFMT_U8,
218 /** 8-bit, signed. */
219 PDMAUDIOFMT_S8,
220 /** 16-bit, unsigned. */
221 PDMAUDIOFMT_U16,
222 /** 16-bit, signed. */
223 PDMAUDIOFMT_S16,
224 /** 32-bit, unsigned. */
225 PDMAUDIOFMT_U32,
226 /** 32-bit, signed. */
227 PDMAUDIOFMT_S32,
228 /** Hack to blow the type up to 32-bit. */
229 PDMAUDIOFMT_32BIT_HACK = 0x7fffffff
230} PDMAUDIOFMT;
231
232/**
233 * Audio direction.
234 */
235typedef enum PDMAUDIODIR
236{
237 /** Unknown direction. */
238 PDMAUDIODIR_UNKNOWN = 0,
239 /** Input. */
240 PDMAUDIODIR_IN = 1,
241 /** Output. */
242 PDMAUDIODIR_OUT = 2,
243 /** Duplex handling. */
244 PDMAUDIODIR_ANY = 3,
245 /** Hack to blow the type up to 32-bit. */
246 PDMAUDIODIR_32BIT_HACK = 0x7fffffff
247} PDMAUDIODIR;
248
249/** Device latency spec in milliseconds (ms). */
250typedef uint32_t PDMAUDIODEVLATSPECMS;
251
252/** Device latency spec in seconds (s). */
253typedef uint32_t PDMAUDIODEVLATSPECSEC;
254
255/** Audio device flags. Use with PDMAUDIODEV_FLAG_ flags. */
256typedef uint32_t PDMAUDIODEVFLAG;
257
258/** No flags set. */
259#define PDMAUDIODEV_FLAGS_NONE 0
260/** The device marks the default device within the host OS. */
261#define PDMAUDIODEV_FLAGS_DEFAULT RT_BIT(0)
262/** The device can be removed at any time and we have to deal with it. */
263#define PDMAUDIODEV_FLAGS_HOTPLUG RT_BIT(1)
264/** The device is known to be buggy and needs special treatment. */
265#define PDMAUDIODEV_FLAGS_BUGGY RT_BIT(2)
266/** Ignore the device, no matter what. */
267#define PDMAUDIODEV_FLAGS_IGNORE RT_BIT(3)
268/** The device is present but marked as locked by some other application. */
269#define PDMAUDIODEV_FLAGS_LOCKED RT_BIT(4)
270/** The device is present but not in an alive state (dead). */
271#define PDMAUDIODEV_FLAGS_DEAD RT_BIT(5)
272
273/**
274 * Audio device type.
275 */
276typedef enum PDMAUDIODEVICETYPE
277{
278 /** Unknown device type. This is the default. */
279 PDMAUDIODEVICETYPE_UNKNOWN = 0,
280 /** Dummy device; for backends which are not able to report
281 * actual device information (yet). */
282 PDMAUDIODEVICETYPE_DUMMY,
283 /** The device is built into the host (non-removable). */
284 PDMAUDIODEVICETYPE_BUILTIN,
285 /** The device is an (external) USB device. */
286 PDMAUDIODEVICETYPE_USB,
287 /** Hack to blow the type up to 32-bit. */
288 PDMAUDIODEVICETYPE_32BIT_HACK = 0x7fffffff
289} PDMAUDIODEVICETYPE;
290
291/**
292 * Audio device instance data.
293 */
294typedef struct PDMAUDIODEVICE
295{
296 /** List node. */
297 RTLISTNODE Node;
298 /** Friendly name of the device, if any. */
299 char szName[64];
300 /** The device type. */
301 PDMAUDIODEVICETYPE enmType;
302 /** Reference count indicating how many audio streams currently are relying on this device. */
303 uint8_t cRefCount;
304 /** Usage of the device. */
305 PDMAUDIODIR enmUsage;
306 /** Device flags. */
307 PDMAUDIODEVFLAG fFlags;
308 /** Maximum number of input audio channels the device supports. */
309 uint8_t cMaxInputChannels;
310 /** Maximum number of output audio channels the device supports. */
311 uint8_t cMaxOutputChannels;
312 /** Additional data which might be relevant for the current context. */
313 void *pvData;
314 /** Size of the additional data. */
315 size_t cbData;
316 /** Device type union, based on enmType. */
317 union
318 {
319 /** USB type specifics. */
320 struct
321 {
322 /** Vendor ID. */
323 int16_t VID;
324 /** Product ID. */
325 int16_t PID;
326 } USB;
327 } Type;
328} PDMAUDIODEVICE, *PPDMAUDIODEVICE;
329
330/**
331 * Structure for keeping an audio device enumeration.
332 */
333typedef struct PDMAUDIODEVICEENUM
334{
335 /** Number of audio devices in the list. */
336 uint16_t cDevices;
337 /** List of audio devices. */
338 RTLISTANCHOR lstDevices;
339} PDMAUDIODEVICEENUM, *PPDMAUDIODEVICEENUM;
340
341/**
342 * Audio (static) configuration of an audio host backend.
343 */
344typedef struct PDMAUDIOBACKENDCFG
345{
346 /** The backend's friendly name. */
347 char szName[32];
348 /** Size (in bytes) of the host backend's audio output stream structure. */
349 size_t cbStreamOut;
350 /** Size (in bytes) of the host backend's audio input stream structure. */
351 size_t cbStreamIn;
352 /** Number of concurrent output (playback) streams supported on the host.
353 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
354 uint32_t cMaxStreamsOut;
355 /** Number of concurrent input (recording) streams supported on the host.
356 * UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
357 uint32_t cMaxStreamsIn;
358} PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
359
360/**
361 * A single audio frame.
362 *
363 * Currently only two (2) channels, left and right, are supported.
364 *
365 * Note: When changing this structure, make sure to also handle
366 * VRDP's input / output processing in DrvAudioVRDE, as VRDP
367 * expects audio data in st_sample_t format (historical reasons)
368 * which happens to be the same as PDMAUDIOFRAME for now.
369 */
370typedef struct PDMAUDIOFRAME
371{
372 /** Left channel. */
373 int64_t i64LSample;
374 /** Right channel. */
375 int64_t i64RSample;
376} PDMAUDIOFRAME;
377/** Pointer to a single (stereo) audio frame. */
378typedef PDMAUDIOFRAME *PPDMAUDIOFRAME;
379/** Pointer to a const single (stereo) audio frame. */
380typedef PDMAUDIOFRAME const *PCPDMAUDIOFRAME;
381
382typedef enum PDMAUDIOENDIANNESS
383{
384 /** The usual invalid endian. */
385 PDMAUDIOENDIANNESS_INVALID,
386 /** Little endian. */
387 PDMAUDIOENDIANNESS_LITTLE,
388 /** Bit endian. */
389 PDMAUDIOENDIANNESS_BIG,
390 /** Endianness doesn't have a meaning in the context. */
391 PDMAUDIOENDIANNESS_NA,
392 /** The end of the valid endian values (exclusive). */
393 PDMAUDIOENDIANNESS_END,
394 /** Hack to blow the type up to 32-bit. */
395 PDMAUDIOENDIANNESS_32BIT_HACK = 0x7fffffff
396} PDMAUDIOENDIANNESS;
397
398/**
399 * Audio playback destinations.
400 */
401typedef enum PDMAUDIOPLAYBACKDEST
402{
403 /** Unknown destination. */
404 PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
405 /** Front channel. */
406 PDMAUDIOPLAYBACKDEST_FRONT,
407 /** Center / LFE (Subwoofer) channel. */
408 PDMAUDIOPLAYBACKDEST_CENTER_LFE,
409 /** Rear channel. */
410 PDMAUDIOPLAYBACKDEST_REAR,
411 /** Hack to blow the type up to 32-bit. */
412 PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
413} PDMAUDIOPLAYBACKDEST;
414
415/**
416 * Audio recording sources.
417 */
418typedef enum PDMAUDIORECSOURCE
419{
420 /** Unknown recording source. */
421 PDMAUDIORECSOURCE_UNKNOWN = 0,
422 /** Microphone-In. */
423 PDMAUDIORECSOURCE_MIC,
424 /** CD. */
425 PDMAUDIORECSOURCE_CD,
426 /** Video-In. */
427 PDMAUDIORECSOURCE_VIDEO,
428 /** AUX. */
429 PDMAUDIORECSOURCE_AUX,
430 /** Line-In. */
431 PDMAUDIORECSOURCE_LINE,
432 /** Phone-In. */
433 PDMAUDIORECSOURCE_PHONE,
434 /** Hack to blow the type up to 32-bit. */
435 PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
436} PDMAUDIORECSOURCE;
437
438/**
439 * Audio stream (data) layout.
440 */
441typedef enum PDMAUDIOSTREAMLAYOUT
442{
443 /** Unknown access type; do not use. */
444 PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
445 /** Non-interleaved access, that is, consecutive
446 * access to the data. */
447 PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED,
448 /** Interleaved access, where the data can be
449 * mixed together with data of other audio streams. */
450 PDMAUDIOSTREAMLAYOUT_INTERLEAVED,
451 /** Complex layout, which does not fit into the
452 * interleaved / non-interleaved layouts. */
453 PDMAUDIOSTREAMLAYOUT_COMPLEX,
454 /** Raw (pass through) data, with no data layout processing done.
455 *
456 * This means that this stream will operate on PDMAUDIOFRAME data
457 * directly. Don't use this if you don't have to. */
458 PDMAUDIOSTREAMLAYOUT_RAW,
459 /** Hack to blow the type up to 32-bit. */
460 PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
461} PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
462
463/** No stream channel data flags defined. */
464#define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE 0
465
466/**
467 * Structure for keeping a stream channel data block around.
468 */
469typedef struct PDMAUDIOSTREAMCHANNELDATA
470{
471 /** Circular buffer for the channel data. */
472 PRTCIRCBUF pCircBuf;
473 /** Amount of audio data (in bytes) acquired for reading. */
474 size_t cbAcq;
475 /** Channel data flags. */
476 uint32_t fFlags;
477} PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
478
479/**
480 * Enumeration for standard speaker channel IDs.
481 * This can cover up to 11.0 surround sound.
482 *
483 * Note: Any of those channels can be marked / used as the LFE channel (played through the subwoofer).
484 */
485typedef enum PDMAUDIOSTREAMCHANNELID
486{
487 /** Unknown / not set channel ID. */
488 PDMAUDIOSTREAMCHANNELID_UNKNOWN = 0,
489 /** Front left channel. */
490 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
491 /** Front right channel. */
492 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT,
493 /** Front center channel. */
494 PDMAUDIOSTREAMCHANNELID_FRONT_CENTER,
495 /** Low frequency effects (subwoofer) channel. */
496 PDMAUDIOSTREAMCHANNELID_LFE,
497 /** Rear left channel. */
498 PDMAUDIOSTREAMCHANNELID_REAR_LEFT,
499 /** Rear right channel. */
500 PDMAUDIOSTREAMCHANNELID_REAR_RIGHT,
501 /** Front left of center channel. */
502 PDMAUDIOSTREAMCHANNELID_FRONT_LEFT_OF_CENTER,
503 /** Front right of center channel. */
504 PDMAUDIOSTREAMCHANNELID_FRONT_RIGHT_OF_CENTER,
505 /** Rear center channel. */
506 PDMAUDIOSTREAMCHANNELID_REAR_CENTER,
507 /** Side left channel. */
508 PDMAUDIOSTREAMCHANNELID_SIDE_LEFT,
509 /** Side right channel. */
510 PDMAUDIOSTREAMCHANNELID_SIDE_RIGHT,
511 /** Left height channel. */
512 PDMAUDIOSTREAMCHANNELID_LEFT_HEIGHT,
513 /** Right height channel. */
514 PDMAUDIOSTREAMCHANNELID_RIGHT_HEIGHT,
515 /** Hack to blow the type up to 32-bit. */
516 PDMAUDIOSTREAMCHANNELID_32BIT_HACK = 0x7fffffff
517} PDMAUDIOSTREAMCHANNELID;
518
519/**
520 * Structure for mapping a single (mono) channel or dual (stereo) channels of an audio stream (aka stream profile).
521 *
522 * An audio stream consists of one or multiple channels (e.g. 1 for mono, 2 for stereo),
523 * depending on the configuration.
524 */
525typedef struct PDMAUDIOSTREAMMAP
526{
527 /** Array of channel IDs being handled.
528 * Note: The first (zero-based) index specifies the leftmost channel. */
529 PDMAUDIOSTREAMCHANNELID aID[2];
530 /** Step size (in bytes) to the channel's next frame. */
531 size_t cbSize;
532 /** Frame size (in bytes) of this channel. */
533 size_t cbFrame;
534 /** Offset (in bytes) to first frame in the data block. */
535 size_t cbFirst;
536 /** Offset (in bytes) to the next frame in the data block. */
537 size_t cbOff;
538 /** Associated data buffer. */
539 PDMAUDIOSTREAMCHANNELDATA Data;
540} PDMAUDIOSTREAMMAP, *PPDMAUDIOSTREAMMAP;
541
542/**
543 * Union for keeping an audio stream destination or source.
544 */
545typedef union PDMAUDIODESTSOURCE
546{
547 /** Desired playback destination (for an output stream). */
548 PDMAUDIOPLAYBACKDEST Dest;
549 /** Desired recording source (for an input stream). */
550 PDMAUDIORECSOURCE Source;
551} PDMAUDIODESTSOURCE, *PPDMAUDIODESTSOURCE;
552
553/**
554 * Properties of audio streams for host/guest for in or out directions.
555 */
556typedef struct PDMAUDIOPCMPROPS
557{
558 /** Sample width (in bytes). */
559 uint8_t cBytes;
560 /** Number of audio channels. */
561 uint8_t cChannels;
562 /** Shift count used for faster calculation of various
563 * values, such as the alignment, bytes to frames and so on.
564 * Depends on number of stream channels and the stream format
565 * being used.
566 *
567 ** @todo Use some RTAsmXXX functions instead?
568 */
569 uint8_t cShift;
570 /** Signed or unsigned sample. */
571 bool fSigned : 1;
572 /** Whether the endianness is swapped or not. */
573 bool fSwapEndian : 1;
574 /** Sample frequency in Hertz (Hz). */
575 uint32_t uHz;
576} PDMAUDIOPCMPROPS;
577AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
578/** Pointer to audio stream properties. */
579typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
580
581/** Initializor for PDMAUDIOPCMPROPS. */
582#define PDMAUDIOPCMPROPS_INITIALIZOR(a_cBytes, a_fSigned, a_cCannels, a_uHz, a_cShift, a_fSwapEndian) \
583 { a_cBytes, a_cCannels, a_cShift, a_fSigned, a_fSwapEndian, a_uHz }
584/** Calculates the cShift value of given sample bits and audio channels.
585 * Note: Does only support mono/stereo channels for now. */
586#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBytes, cChannels) ((cChannels == 2) + (cBytes / 2))
587/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
588#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps) PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cBytes, (pProps)->cChannels)
589/** Converts (audio) frames to bytes.
590 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
591#define PDMAUDIOPCMPROPS_F2B(pProps, frames) ((frames) << (pProps)->cShift)
592/** Converts bytes to (audio) frames.
593 * Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
594#define PDMAUDIOPCMPROPS_B2F(pProps, cb) (cb >> (pProps)->cShift)
595
596/**
597 * Structure for keeping an audio stream configuration.
598 */
599typedef struct PDMAUDIOSTREAMCFG
600{
601 /** Friendly name of the stream. */
602 char szName[64];
603 /** Direction of the stream. */
604 PDMAUDIODIR enmDir;
605 /** Destination / source indicator, depending on enmDir. */
606 PDMAUDIODESTSOURCE DestSource;
607 /** The stream's PCM properties. */
608 PDMAUDIOPCMPROPS Props;
609 /** The stream's audio data layout.
610 * This indicates how the audio data buffers to/from the backend is being layouted.
611 *
612 * Currently, the following layouts are supported by the audio connector:
613 *
614 * PDMAUDIOSTREAMLAYOUT_NON_INTERLEAVED:
615 * One stream at once. The consecutive audio data is exactly in the format and frame width
616 * like defined in the PCM properties. This is the default.
617 *
618 * PDMAUDIOSTREAMLAYOUT_RAW:
619 * Can be one or many streams at once, depending on the stream's mixing buffer setup.
620 * The audio data will get handled as PDMAUDIOFRAME frames without any modification done. */
621 PDMAUDIOSTREAMLAYOUT enmLayout;
622 /** Device emulation-specific data needed for the audio connector. */
623 struct
624 {
625 /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
626 * Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
627 uint32_t uSchedulingHintMs;
628 } Device;
629 /**
630 * Backend-specific data for the stream.
631 * On input (requested configuration) those values are set by the audio connector to let the backend know what we expect.
632 * On output (acquired configuration) those values reflect the values set and used by the backend.
633 * Set by the backend on return. Not all backends support all values / features.
634 */
635 struct
636 {
637 /** Period size of the stream (in audio frames).
638 * This value reflects the number of audio frames in between each hardware interrupt on the
639 * backend (host) side. 0 if not set / available by the backend. */
640 uint32_t cfPeriod;
641 /** (Ring) buffer size (in audio frames). Often is a multiple of cfPeriod.
642 * 0 if not set / available by the backend. */
643 uint32_t cfBufferSize;
644 /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
645 * The bigger this value is, the more latency for the stream will occur.
646 * 0 if not set / available by the backend. */
647 uint32_t cfPreBuf;
648 } Backend;
649} PDMAUDIOSTREAMCFG;
650AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
651/** Pointer to audio stream configuration keeper. */
652typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
653
654
655/** Converts (audio) frames to bytes. */
656#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) ((frames) << (pCfg->Props).cShift)
657/** Converts bytes to (audio) frames. */
658#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb) (cb >> (pCfg->Props).cShift)
659
660#if defined(RT_LITTLE_ENDIAN)
661# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
662#elif defined(RT_BIG_ENDIAN)
663# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
664#else
665# error "Port me!"
666#endif
667
668/**
669 * Audio mixer controls.
670 */
671typedef enum PDMAUDIOMIXERCTL
672{
673 /** Unknown mixer control. */
674 PDMAUDIOMIXERCTL_UNKNOWN = 0,
675 /** Master volume. */
676 PDMAUDIOMIXERCTL_VOLUME_MASTER,
677 /** Front. */
678 PDMAUDIOMIXERCTL_FRONT,
679 /** Center / LFE (Subwoofer). */
680 PDMAUDIOMIXERCTL_CENTER_LFE,
681 /** Rear. */
682 PDMAUDIOMIXERCTL_REAR,
683 /** Line-In. */
684 PDMAUDIOMIXERCTL_LINE_IN,
685 /** Microphone-In. */
686 PDMAUDIOMIXERCTL_MIC_IN,
687 /** Hack to blow the type up to 32-bit. */
688 PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
689} PDMAUDIOMIXERCTL;
690
691/**
692 * Audio stream commands. Used in the audio connector
693 * as well as in the actual host backends.
694 */
695typedef enum PDMAUDIOSTREAMCMD
696{
697 /** Unknown command, do not use. */
698 PDMAUDIOSTREAMCMD_UNKNOWN = 0,
699 /** Enables the stream. */
700 PDMAUDIOSTREAMCMD_ENABLE,
701 /** Disables the stream.
702 * For output streams this stops the stream after playing the remaining (buffered) audio data.
703 * For input streams this will deliver the remaining (captured) audio data and not accepting
704 * any new audio input data afterwards. */
705 PDMAUDIOSTREAMCMD_DISABLE,
706 /** Pauses the stream. */
707 PDMAUDIOSTREAMCMD_PAUSE,
708 /** Resumes the stream. */
709 PDMAUDIOSTREAMCMD_RESUME,
710 /** Tells the stream to drain itself.
711 * For output streams this plays all remaining (buffered) audio frames,
712 * for input streams this permits receiving any new audio frames.
713 * No supported by all backends. */
714 PDMAUDIOSTREAMCMD_DRAIN,
715 /** Tells the stream to drop all (buffered) audio data immediately.
716 * No supported by all backends. */
717 PDMAUDIOSTREAMCMD_DROP,
718 /** Hack to blow the type up to 32-bit. */
719 PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
720} PDMAUDIOSTREAMCMD;
721
722/**
723 * Audio volume parameters.
724 */
725typedef struct PDMAUDIOVOLUME
726{
727 /** Set to @c true if this stream is muted, @c false if not. */
728 bool fMuted;
729 /** Left channel volume.
730 * Range is from [0 ... 255], whereas 0 specifies
731 * the most silent and 255 the loudest value. */
732 uint8_t uLeft;
733 /** Right channel volume.
734 * Range is from [0 ... 255], whereas 0 specifies
735 * the most silent and 255 the loudest value. */
736 uint8_t uRight;
737} PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
738
739/** Defines the minimum volume allowed. */
740#define PDMAUDIO_VOLUME_MIN (0)
741/** Defines the maximum volume allowed. */
742#define PDMAUDIO_VOLUME_MAX (255)
743
744/**
745 * Structure for holding rate processing information
746 * of a source + destination audio stream. This is needed
747 * because both streams can differ regarding their rates
748 * and therefore need to be treated accordingly.
749 */
750typedef struct PDMAUDIOSTREAMRATE
751{
752 /** Current (absolute) offset in the output
753 * (destination) stream. */
754 uint64_t dstOffset;
755 /** Increment for moving dstOffset for the
756 * destination stream. This is needed because the
757 * source <-> destination rate might be different. */
758 uint64_t dstInc;
759 /** Current (absolute) offset in the input
760 * stream. */
761 uint32_t srcOffset;
762 /** Last processed frame of the input stream.
763 * Needed for interpolation. */
764 PDMAUDIOFRAME srcFrameLast;
765} PDMAUDIOSTREAMRATE, *PPDMAUDIOSTREAMRATE;
766
767/**
768 * Structure for holding mixing buffer volume parameters.
769 * The volume values are in fixed point style and must
770 * be converted to/from before using with e.g. PDMAUDIOVOLUME.
771 */
772typedef struct PDMAUDMIXBUFVOL
773{
774 /** Set to @c true if this stream is muted, @c false if not. */
775 bool fMuted;
776 /** Left volume to apply during conversion. Pass 0
777 * to convert the original values. May not apply to
778 * all conversion functions. */
779 uint32_t uLeft;
780 /** Right volume to apply during conversion. Pass 0
781 * to convert the original values. May not apply to
782 * all conversion functions. */
783 uint32_t uRight;
784} PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
785
786/**
787 * Structure for holding frame conversion parameters for
788 * the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
789 */
790typedef struct PDMAUDMIXBUFCONVOPTS
791{
792 /** Number of audio frames to convert. */
793 uint32_t cFrames;
794 union
795 {
796 struct
797 {
798 /** Volume to use for conversion. */
799 PDMAUDMIXBUFVOL Volume;
800 } From;
801 } RT_UNION_NM(u);
802} PDMAUDMIXBUFCONVOPTS;
803/** Pointer to conversion parameters for the audio mixer. */
804typedef PDMAUDMIXBUFCONVOPTS *PPDMAUDMIXBUFCONVOPTS;
805/** Pointer to const conversion parameters for the audio mixer. */
806typedef PDMAUDMIXBUFCONVOPTS const *PCPDMAUDMIXBUFCONVOPTS;
807
808/**
809 * Note: All internal handling is done in audio frames,
810 * not in bytes!
811 */
812typedef uint32_t PDMAUDIOMIXBUFFMT;
813typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
814
815/**
816 * Convertion-from function used by the PDM audio buffer mixer.
817 *
818 * @returns Number of audio frames returned.
819 * @param paDst Where to return the converted frames.
820 * @param pvSrc The source frame bytes.
821 * @param cbSrc Number of bytes to convert.
822 * @param pOpts Conversion options.
823 */
824typedef DECLCALLBACK(uint32_t) FNPDMAUDIOMIXBUFCONVFROM(PPDMAUDIOFRAME paDst, const void *pvSrc, uint32_t cbSrc,
825 PCPDMAUDMIXBUFCONVOPTS pOpts);
826/** Pointer to a convertion-from function used by the PDM audio buffer mixer. */
827typedef FNPDMAUDIOMIXBUFCONVFROM *PFNPDMAUDIOMIXBUFCONVFROM;
828
829/**
830 * Convertion-to function used by the PDM audio buffer mixer.
831 *
832 * @param pvDst Output buffer.
833 * @param paSrc The input frames.
834 * @param pOpts Conversion options.
835 */
836typedef DECLCALLBACK(void) FNPDMAUDIOMIXBUFCONVTO(void *pvDst, PCPDMAUDIOFRAME paSrc, PCPDMAUDMIXBUFCONVOPTS pOpts);
837/** Pointer to a convertion-to function used by the PDM audio buffer mixer. */
838typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
839
840typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
841typedef struct PDMAUDIOMIXBUF
842{
843 RTLISTNODE Node;
844 /** Name of the buffer. */
845 char *pszName;
846 /** Frame buffer. */
847 PPDMAUDIOFRAME pFrames;
848 /** Size of the frame buffer (in audio frames). */
849 uint32_t cFrames;
850 /** The current read position (in frames). */
851 uint32_t offRead;
852 /** The current write position (in frames). */
853 uint32_t offWrite;
854 /**
855 * Total frames already mixed down to the parent buffer (if any). Always starting at
856 * the parent's offRead position.
857 *
858 * Note: Count always is specified in parent frames, as the sample count can differ between parent
859 * and child.
860 */
861 uint32_t cMixed;
862 /** How much audio frames are currently being used
863 * in this buffer.
864 * Note: This also is known as the distance in ring buffer terms. */
865 uint32_t cUsed;
866 /** Pointer to parent buffer (if any). */
867 PPDMAUDIOMIXBUF pParent;
868 /** List of children mix buffers to keep in sync with (if being a parent buffer). */
869 RTLISTANCHOR lstChildren;
870 /** Number of children mix buffers kept in lstChildren. */
871 uint32_t cChildren;
872 /** Intermediate structure for buffer conversion tasks. */
873 PPDMAUDIOSTREAMRATE pRate;
874 /** Internal representation of current volume used for mixing. */
875 PDMAUDMIXBUFVOL Volume;
876 /** This buffer's audio format. */
877 PDMAUDIOMIXBUFFMT AudioFmt;
878 /** Standard conversion-to function for set AudioFmt. */
879 PFNPDMAUDIOMIXBUFCONVTO pfnConvTo;
880 /** Standard conversion-from function for set AudioFmt. */
881 PFNPDMAUDIOMIXBUFCONVFROM pfnConvFrom;
882 /**
883 * Ratio of the associated parent stream's frequency by this stream's
884 * frequency (1<<32), represented as a signed 64 bit integer.
885 *
886 * For example, if the parent stream has a frequency of 44 khZ, and this
887 * stream has a frequency of 11 kHz, the ration then would be
888 * (44/11 * (1 << 32)).
889 *
890 * Currently this does not get changed once assigned.
891 */
892 int64_t iFreqRatio;
893 /** For quickly converting frames <-> bytes and vice versa. */
894 uint8_t cShift;
895} PDMAUDIOMIXBUF;
896
897typedef uint32_t PDMAUDIOFILEFLAGS;
898
899/** No flags defined. */
900#define PDMAUDIOFILE_FLAG_NONE 0
901/** Keep the audio file even if it contains no audio data. */
902#define PDMAUDIOFILE_FLAG_KEEP_IF_EMPTY RT_BIT(0)
903/** Audio file flag validation mask. */
904#define PDMAUDIOFILE_FLAG_VALID_MASK 0x1
905
906/** Audio file default open flags. */
907#define PDMAUDIOFILE_DEFAULT_OPEN_FLAGS (RTFILE_O_OPEN_CREATE | RTFILE_O_APPEND | RTFILE_O_WRITE | RTFILE_O_DENY_WRITE)
908
909/**
910 * Audio file types.
911 */
912typedef enum PDMAUDIOFILETYPE
913{
914 /** Unknown type, do not use. */
915 PDMAUDIOFILETYPE_UNKNOWN = 0,
916 /** Raw (PCM) file. */
917 PDMAUDIOFILETYPE_RAW,
918 /** Wave (.WAV) file. */
919 PDMAUDIOFILETYPE_WAV,
920 /** Hack to blow the type up to 32-bit. */
921 PDMAUDIOFILETYPE_32BIT_HACK = 0x7fffffff
922} PDMAUDIOFILETYPE;
923
924typedef uint32_t PDMAUDIOFILENAMEFLAGS;
925
926/** No flags defined. */
927#define PDMAUDIOFILENAME_FLAG_NONE 0
928/** Adds an ISO timestamp to the file name. */
929#define PDMAUDIOFILENAME_FLAG_TS RT_BIT(0)
930
931/**
932 * Structure for an audio file handle.
933 */
934typedef struct PDMAUDIOFILE
935{
936 /** Type of the audio file. */
937 PDMAUDIOFILETYPE enmType;
938 /** Audio file flags. */
939 PDMAUDIOFILEFLAGS fFlags;
940 /** File name and path. */
941 char szName[RTPATH_MAX + 1];
942 /** Actual file handle. */
943 RTFILE hFile;
944 /** Data needed for the specific audio file type implemented.
945 * Optional, can be NULL. */
946 void *pvData;
947 /** Data size (in bytes). */
948 size_t cbData;
949} PDMAUDIOFILE, *PPDMAUDIOFILE;
950
951/** Stream status flag. To be used with PDMAUDIOSTRMSTS_FLAG_ flags. */
952typedef uint32_t PDMAUDIOSTREAMSTS;
953
954/** No flags being set. */
955#define PDMAUDIOSTREAMSTS_FLAG_NONE 0
956/** Whether this stream has been initialized by the
957 * backend or not. */
958#define PDMAUDIOSTREAMSTS_FLAG_INITIALIZED RT_BIT_32(0)
959/** Whether this stream is enabled or disabled. */
960#define PDMAUDIOSTREAMSTS_FLAG_ENABLED RT_BIT_32(1)
961/** Whether this stream has been paused or not. This also implies
962 * that this is an enabled stream! */
963#define PDMAUDIOSTREAMSTS_FLAG_PAUSED RT_BIT_32(2)
964/** Whether this stream was marked as being disabled
965 * but there are still associated guest output streams
966 * which rely on its data. */
967#define PDMAUDIOSTREAMSTS_FLAG_PENDING_DISABLE RT_BIT_32(3)
968/** Whether this stream is in re-initialization phase.
969 * All other bits remain untouched to be able to restore
970 * the stream's state after the re-initialization bas been
971 * finished. */
972#define PDMAUDIOSTREAMSTS_FLAG_PENDING_REINIT RT_BIT_32(4)
973/** Validation mask. */
974#define PDMAUDIOSTREAMSTS_VALID_MASK UINT32_C(0x0000001F)
975
976/**
977 * Enumeration presenting a backend's current status.
978 */
979typedef enum PDMAUDIOBACKENDSTS
980{
981 /** Unknown/invalid status. */
982 PDMAUDIOBACKENDSTS_UNKNOWN = 0,
983 /** No backend attached. */
984 PDMAUDIOBACKENDSTS_NOT_ATTACHED,
985 /** The backend is in its initialization phase.
986 * Not all backends support this status. */
987 PDMAUDIOBACKENDSTS_INITIALIZING,
988 /** The backend has stopped its operation. */
989 PDMAUDIOBACKENDSTS_STOPPED,
990 /** The backend is up and running. */
991 PDMAUDIOBACKENDSTS_RUNNING,
992 /** The backend ran into an error and is unable to recover.
993 * A manual re-initialization might help. */
994 PDMAUDIOBACKENDSTS_ERROR,
995 /** Hack to blow the type up to 32-bit. */
996 PDMAUDIOBACKENDSTS_32BIT_HACK = 0x7fffffff
997} PDMAUDIOBACKENDSTS;
998
999/**
1000 * Structure for keeping audio input stream specifics.
1001 * Do not use directly. Instead, use PDMAUDIOSTREAM.
1002 */
1003typedef struct PDMAUDIOSTREAMIN
1004{
1005#ifdef VBOX_WITH_STATISTICS
1006 struct
1007 {
1008 STAMCOUNTER BytesElapsed;
1009 STAMCOUNTER BytesTotalRead;
1010 STAMCOUNTER FramesCaptured;
1011 } Stats;
1012#endif
1013 struct
1014 {
1015 /** File for writing stream reads. */
1016 PPDMAUDIOFILE pFileStreamRead;
1017 /** File for writing non-interleaved captures. */
1018 PPDMAUDIOFILE pFileCaptureNonInterleaved;
1019 } Dbg;
1020} PDMAUDIOSTREAMIN, *PPDMAUDIOSTREAMIN;
1021
1022/**
1023 * Structure for keeping audio output stream specifics.
1024 * Do not use directly. Instead, use PDMAUDIOSTREAM.
1025 */
1026typedef struct PDMAUDIOSTREAMOUT
1027{
1028#ifdef VBOX_WITH_STATISTICS
1029 struct
1030 {
1031 STAMCOUNTER BytesElapsed;
1032 STAMCOUNTER BytesTotalWritten;
1033 STAMCOUNTER FramesPlayed;
1034 } Stats;
1035#endif
1036 struct
1037 {
1038#ifdef DEBUG
1039 /** Number of audio frames written since the last playback (transfer)
1040 * to the backend. */
1041 uint64_t cfWrittenSinceLastPlay;
1042#endif
1043 /** File for writing stream writes. */
1044 PPDMAUDIOFILE pFileStreamWrite;
1045 /** File for writing stream playback. */
1046 PPDMAUDIOFILE pFilePlayNonInterleaved;
1047 } Dbg;
1048} PDMAUDIOSTREAMOUT, *PPDMAUDIOSTREAMOUT;
1049
1050/** Pointer to an audio stream. */
1051typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAM;
1052
1053/**
1054 * Audio stream context.
1055 * Needed for separating data from the guest and host side (per stream).
1056 */
1057typedef struct PDMAUDIOSTREAMCTX
1058{
1059 /** The stream's audio configuration. */
1060 PDMAUDIOSTREAMCFG Cfg;
1061 /** This stream's mixing buffer. */
1062 PDMAUDIOMIXBUF MixBuf;
1063} PDMAUDIOSTREAMCTX;
1064
1065/** Pointer to an audio stream context. */
1066typedef struct PDMAUDIOSTREAM *PPDMAUDIOSTREAMCTX;
1067
1068/**
1069 * Structure for maintaining an input/output audio stream.
1070 */
1071typedef struct PDMAUDIOSTREAM
1072{
1073 /** List node. */
1074 RTLISTNODE Node;
1075 /** Name of this stream. */
1076 char szName[64];
1077 /** Number of references to this stream. Only can be
1078 * destroyed if the reference count is reaching 0. */
1079 uint32_t cRefs;
1080 /** Stream status flag. */
1081 PDMAUDIOSTREAMSTS fStatus;
1082 /** Audio direction of this stream. */
1083 PDMAUDIODIR enmDir;
1084 /** The guest side of the stream. */
1085 PDMAUDIOSTREAMCTX Guest;
1086 /** The host side of the stream. */
1087 PDMAUDIOSTREAMCTX Host;
1088 /** Union for input/output specifics (based on enmDir). */
1089 union
1090 {
1091 PDMAUDIOSTREAMIN In;
1092 PDMAUDIOSTREAMOUT Out;
1093 } RT_UNION_NM(u);
1094 /** Timestamp (in ns) since last iteration. */
1095 uint64_t tsLastIteratedNs;
1096 /** Timestamp (in ns) since last playback / capture. */
1097 uint64_t tsLastPlayedCapturedNs;
1098 /** Timestamp (in ns) since last read (input streams) or
1099 * write (output streams). */
1100 uint64_t tsLastReadWrittenNs;
1101 /** For output streams this indicates whether the stream has reached
1102 * its playback threshold, e.g. is playing audio.
1103 * For input streams this indicates whether the stream has enough input
1104 * data to actually start reading audio. */
1105 bool fThresholdReached;
1106 /** Data to backend-specific stream data.
1107 * This data block will be casted by the backend to access its backend-dependent data.
1108 *
1109 * That way the backends do not have access to the audio connector's data. */
1110 void *pvBackend;
1111 /** Size (in bytes) of the backend-specific stream data. */
1112 size_t cbBackend;
1113} PDMAUDIOSTREAM;
1114
1115/** Pointer to a audio connector interface. */
1116typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
1117
1118/**
1119 * Enumeration for an audio callback source.
1120 */
1121typedef enum PDMAUDIOCBSOURCE
1122{
1123 /** Invalid, do not use. */
1124 PDMAUDIOCBSOURCE_INVALID = 0,
1125 /** Device emulation. */
1126 PDMAUDIOCBSOURCE_DEVICE = 1,
1127 /** Audio connector interface. */
1128 PDMAUDIOCBSOURCE_CONNECTOR = 2,
1129 /** Backend (lower). */
1130 PDMAUDIOCBSOURCE_BACKEND = 3,
1131 /** Hack to blow the type up to 32-bit. */
1132 PDMAUDIOCBSOURCE_32BIT_HACK = 0x7fffffff
1133} PDMAUDIOCBSOURCE;
1134
1135/**
1136 * Audio device callback types.
1137 * Those callbacks are being sent from the audio connector -> device emulation.
1138 */
1139typedef enum PDMAUDIODEVICECBTYPE
1140{
1141 /** Invalid, do not use. */
1142 PDMAUDIODEVICECBTYPE_INVALID = 0,
1143 /** Data is availabe as input for passing to the device emulation. */
1144 PDMAUDIODEVICECBTYPE_DATA_INPUT,
1145 /** Free data for the device emulation to write to the backend. */
1146 PDMAUDIODEVICECBTYPE_DATA_OUTPUT,
1147 /** Hack to blow the type up to 32-bit. */
1148 PDMAUDIODEVICECBTYPE_32BIT_HACK = 0x7fffffff
1149} PDMAUDIODEVICECBTYPE;
1150
1151/**
1152 * Device callback data for audio input.
1153 */
1154typedef struct PDMAUDIODEVICECBDATA_DATA_INPUT
1155{
1156 /** Input: How many bytes are availabe as input for passing
1157 * to the device emulation. */
1158 uint32_t cbInAvail;
1159 /** Output: How many bytes have been read. */
1160 uint32_t cbOutRead;
1161} PDMAUDIODEVICECBDATA_DATA_INPUT, *PPDMAUDIODEVICECBDATA_DATA_INPUT;
1162
1163/**
1164 * Device callback data for audio output.
1165 */
1166typedef struct PDMAUDIODEVICECBDATA_DATA_OUTPUT
1167{
1168 /** Input: How many bytes are free for the device emulation to write. */
1169 uint32_t cbInFree;
1170 /** Output: How many bytes were written by the device emulation. */
1171 uint32_t cbOutWritten;
1172} PDMAUDIODEVICECBDATA_DATA_OUTPUT, *PPDMAUDIODEVICECBDATA_DATA_OUTPUT;
1173
1174/**
1175 * Audio backend callback types.
1176 * Those callbacks are being sent from the backend -> audio connector.
1177 */
1178typedef enum PDMAUDIOBACKENDCBTYPE
1179{
1180 /** Invalid, do not use. */
1181 PDMAUDIOBACKENDCBTYPE_INVALID = 0,
1182 /** The backend's status has changed. */
1183 PDMAUDIOBACKENDCBTYPE_STATUS,
1184 /** One or more host audio devices have changed. */
1185 PDMAUDIOBACKENDCBTYPE_DEVICES_CHANGED,
1186 /** Hack to blow the type up to 32-bit. */
1187 PDMAUDIOBACKENDCBTYPE_32BIT_HACK = 0x7fffffff
1188} PDMAUDIOBACKENDCBTYPE;
1189
1190/** Pointer to a host audio interface. */
1191typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
1192
1193/**
1194 * Host audio callback function.
1195 * This function will be called from a backend to communicate with the host audio interface.
1196 *
1197 * @returns IPRT status code.
1198 * @param pDrvIns Pointer to driver instance which called us.
1199 * @param enmType Callback type.
1200 * @param pvUser User argument.
1201 * @param cbUser Size (in bytes) of user argument.
1202 */
1203typedef DECLCALLBACK(int) FNPDMHOSTAUDIOCALLBACK(PPDMDRVINS pDrvIns, PDMAUDIOBACKENDCBTYPE enmType, void *pvUser, size_t cbUser);
1204/** Pointer to a FNPDMHOSTAUDIOCALLBACK(). */
1205typedef FNPDMHOSTAUDIOCALLBACK *PFNPDMHOSTAUDIOCALLBACK;
1206
1207/**
1208 * Audio callback registration record.
1209 */
1210typedef struct PDMAUDIOCBRECORD
1211{
1212 /** List node. */
1213 RTLISTANCHOR Node;
1214 /** Callback source. */
1215 PDMAUDIOCBSOURCE enmSource;
1216 /** Callback type, based on the given source. */
1217 union
1218 {
1219 /** Device callback stuff. */
1220 struct
1221 {
1222 PDMAUDIODEVICECBTYPE enmType;
1223 } Device;
1224 } RT_UNION_NM(u);
1225 /** Pointer to context data. Optional. */
1226 void *pvCtx;
1227 /** Size (in bytes) of context data.
1228 * Must be 0 if pvCtx is NULL. */
1229 size_t cbCtx;
1230} PDMAUDIOCBRECORD, *PPDMAUDIOCBRECORD;
1231
1232#define PPDMAUDIOBACKENDSTREAM void *
1233
1234/**
1235 * Audio connector interface (up).
1236 */
1237typedef struct PDMIAUDIOCONNECTOR
1238{
1239 /**
1240 * Enables or disables the given audio direction for this driver.
1241 *
1242 * When disabled, assiociated output streams consume written audio without passing them further down to the backends.
1243 * Associated input streams then return silence when read from those.
1244 *
1245 * @returns VBox status code.
1246 * @param pInterface Pointer to the interface structure containing the called function pointer.
1247 * @param enmDir Audio direction to enable or disable driver for.
1248 * @param fEnable Whether to enable or disable the specified audio direction.
1249 */
1250 DECLR3CALLBACKMEMBER(int, pfnEnable, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir, bool fEnable));
1251
1252 /**
1253 * Returns whether the given audio direction for this driver is enabled or not.
1254 *
1255 * @returns True if audio is enabled for the given direction, false if not.
1256 * @param pInterface Pointer to the interface structure containing the called function pointer.
1257 * @param enmDir Audio direction to retrieve enabled status for.
1258 */
1259 DECLR3CALLBACKMEMBER(bool, pfnIsEnabled, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1260
1261 /**
1262 * Retrieves the current configuration of the host audio backend.
1263 *
1264 * @returns VBox status code.
1265 * @param pInterface Pointer to the interface structure containing the called function pointer.
1266 * @param pCfg Where to store the host audio backend configuration data.
1267 */
1268 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg));
1269
1270 /**
1271 * Retrieves the current status of the host audio backend.
1272 *
1273 * @returns Status of the host audio backend.
1274 * @param pInterface Pointer to the interface structure containing the called function pointer.
1275 * @param enmDir Audio direction to check host audio backend for. Specify PDMAUDIODIR_ANY for the overall
1276 * backend status.
1277 */
1278 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir));
1279
1280 /**
1281 * Creates an audio stream.
1282 *
1283 * @returns VBox status code.
1284 * @param pInterface Pointer to the interface structure containing the called function pointer.
1285 * @param pCfgHost Stream configuration for host side.
1286 * @param pCfgGuest Stream configuration for guest side.
1287 * @param ppStream Pointer where to return the created audio stream on success.
1288 */
1289 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
1290
1291 /**
1292 * Destroys an audio stream.
1293 *
1294 * @param pInterface Pointer to the interface structure containing the called function pointer.
1295 * @param pStream Pointer to audio stream.
1296 */
1297 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1298
1299 /**
1300 * Adds a reference to the specified audio stream.
1301 *
1302 * @returns New reference count. UINT32_MAX on error.
1303 * @param pInterface Pointer to the interface structure containing the called function pointer.
1304 * @param pStream Pointer to audio stream adding the reference to.
1305 */
1306 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRetain, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1307
1308 /**
1309 * Releases a reference from the specified stream.
1310 *
1311 * @returns New reference count. UINT32_MAX on error.
1312 * @param pInterface Pointer to the interface structure containing the called function pointer.
1313 * @param pStream Pointer to audio stream releasing a reference from.
1314 */
1315 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamRelease, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1316
1317 /**
1318 * Reads PCM audio data from the host (input).
1319 *
1320 * @returns VBox status code.
1321 * @param pInterface Pointer to the interface structure containing the called function pointer.
1322 * @param pStream Pointer to audio stream to write to.
1323 * @param pvBuf Where to store the read data.
1324 * @param cbBuf Number of bytes to read.
1325 * @param pcbRead Bytes of audio data read. Optional.
1326 */
1327 DECLR3CALLBACKMEMBER(int, pfnStreamRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
1328
1329 /**
1330 * Writes PCM audio data to the host (output).
1331 *
1332 * @returns VBox status code.
1333 * @param pInterface Pointer to the interface structure containing the called function pointer.
1334 * @param pStream Pointer to audio stream to read from.
1335 * @param pvBuf Audio data to be written.
1336 * @param cbBuf Number of bytes to be written.
1337 * @param pcbWritten Bytes of audio data written. Optional.
1338 */
1339 DECLR3CALLBACKMEMBER(int, pfnStreamWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
1340
1341 /**
1342 * Controls a specific audio stream.
1343 *
1344 * @returns VBox status code.
1345 * @param pInterface Pointer to the interface structure containing the called function pointer.
1346 * @param pStream Pointer to audio stream.
1347 * @param enmStreamCmd The stream command to issue.
1348 */
1349 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1350
1351 /**
1352 * Processes stream data.
1353 *
1354 * @param pInterface Pointer to the interface structure containing the called function pointer.
1355 * @param pStream Pointer to audio stream.
1356 */
1357 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1358
1359 /**
1360 * Returns the number of readable data (in bytes) of a specific audio input stream.
1361 *
1362 * @returns Number of readable data (in bytes).
1363 * @param pInterface Pointer to the interface structure containing the called function pointer.
1364 * @param pStream Pointer to audio stream.
1365 */
1366 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1367
1368 /**
1369 * Returns the number of writable data (in bytes) of a specific audio output stream.
1370 *
1371 * @returns Number of writable data (in bytes).
1372 * @param pInterface Pointer to the interface structure containing the called function pointer.
1373 * @param pStream Pointer to audio stream.
1374 */
1375 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1376
1377 /**
1378 * Returns the status of a specific audio stream.
1379 *
1380 * @returns Audio stream status
1381 * @param pInterface Pointer to the interface structure containing the called function pointer.
1382 * @param pStream Pointer to audio stream.
1383 */
1384 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream));
1385
1386 /**
1387 * Sets the audio volume of a specific audio stream.
1388 *
1389 * @returns VBox status code.
1390 * @param pInterface Pointer to the interface structure containing the called function pointer.
1391 * @param pStream Pointer to audio stream.
1392 * @param pVol Pointer to audio volume structure to set the stream's audio volume to.
1393 */
1394 DECLR3CALLBACKMEMBER(int, pfnStreamSetVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol));
1395
1396 /**
1397 * Plays (transfers) available audio frames to the host backend. Only works with output streams.
1398 *
1399 * @returns VBox status code.
1400 * @param pInterface Pointer to the interface structure containing the called function pointer.
1401 * @param pStream Pointer to audio stream.
1402 * @param pcFramesPlayed Number of frames played. Optional.
1403 */
1404 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesPlayed));
1405
1406 /**
1407 * Captures (transfers) available audio frames from the host backend. Only works with input streams.
1408 *
1409 * @returns VBox status code.
1410 * @param pInterface Pointer to the interface structure containing the called function pointer.
1411 * @param pStream Pointer to audio stream.
1412 * @param pcFramesCaptured Number of frames captured. Optional.
1413 */
1414 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, uint32_t *pcFramesCaptured));
1415
1416 /**
1417 * Registers (device) callbacks.
1418 * This is handy for letting the device emulation know of certain events, e.g. processing input / output data
1419 * or configuration changes.
1420 *
1421 * @returns VBox status code.
1422 * @param pInterface Pointer to the interface structure containing the called function pointer.
1423 * @param paCallbacks Pointer to array of callbacks to register.
1424 * @param cCallbacks Number of callbacks to register.
1425 */
1426 DECLR3CALLBACKMEMBER(int, pfnRegisterCallbacks, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOCBRECORD paCallbacks, size_t cCallbacks));
1427
1428} PDMIAUDIOCONNECTOR;
1429
1430/** PDMIAUDIOCONNECTOR interface ID. */
1431#define PDMIAUDIOCONNECTOR_IID "A643B40C-733F-4307-9549-070AF0EE0ED6"
1432
1433/**
1434 * Assigns all needed interface callbacks for an audio backend.
1435 *
1436 * @param a_Prefix The function name prefix.
1437 */
1438#define PDMAUDIO_IHOSTAUDIO_CALLBACKS(a_Prefix) \
1439 do { \
1440 pThis->IHostAudio.pfnInit = RT_CONCAT(a_Prefix,Init); \
1441 pThis->IHostAudio.pfnShutdown = RT_CONCAT(a_Prefix,Shutdown); \
1442 pThis->IHostAudio.pfnGetConfig = RT_CONCAT(a_Prefix,GetConfig); \
1443 /** @todo Add pfnGetDevices here as soon as supported by all backends. */ \
1444 pThis->IHostAudio.pfnGetStatus = RT_CONCAT(a_Prefix,GetStatus); \
1445 /** @todo Ditto for pfnSetCallback. */ \
1446 pThis->IHostAudio.pfnStreamCreate = RT_CONCAT(a_Prefix,StreamCreate); \
1447 pThis->IHostAudio.pfnStreamDestroy = RT_CONCAT(a_Prefix,StreamDestroy); \
1448 pThis->IHostAudio.pfnStreamControl = RT_CONCAT(a_Prefix,StreamControl); \
1449 pThis->IHostAudio.pfnStreamGetReadable = RT_CONCAT(a_Prefix,StreamGetReadable); \
1450 pThis->IHostAudio.pfnStreamGetWritable = RT_CONCAT(a_Prefix,StreamGetWritable); \
1451 pThis->IHostAudio.pfnStreamGetStatus = RT_CONCAT(a_Prefix,StreamGetStatus); \
1452 pThis->IHostAudio.pfnStreamIterate = RT_CONCAT(a_Prefix,StreamIterate); \
1453 pThis->IHostAudio.pfnStreamPlay = RT_CONCAT(a_Prefix,StreamPlay); \
1454 pThis->IHostAudio.pfnStreamCapture = RT_CONCAT(a_Prefix,StreamCapture); \
1455 } while (0)
1456
1457/**
1458 * PDM host audio interface.
1459 */
1460typedef struct PDMIHOSTAUDIO
1461{
1462 /**
1463 * Initializes the host backend (driver).
1464 *
1465 * @returns VBox status code.
1466 * @param pInterface Pointer to the interface structure containing the called function pointer.
1467 */
1468 DECLR3CALLBACKMEMBER(int, pfnInit, (PPDMIHOSTAUDIO pInterface));
1469
1470 /**
1471 * Shuts down the host backend (driver).
1472 *
1473 * @returns VBox status code.
1474 * @param pInterface Pointer to the interface structure containing the called function pointer.
1475 */
1476 DECLR3CALLBACKMEMBER(void, pfnShutdown, (PPDMIHOSTAUDIO pInterface));
1477
1478 /**
1479 * Returns the host backend's configuration (backend).
1480 *
1481 * @returns VBox status code.
1482 * @param pInterface Pointer to the interface structure containing the called function pointer.
1483 * @param pBackendCfg Where to store the backend audio configuration to.
1484 */
1485 DECLR3CALLBACKMEMBER(int, pfnGetConfig, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
1486
1487 /**
1488 * Returns (enumerates) host audio device information.
1489 *
1490 * @returns VBox status code.
1491 * @param pInterface Pointer to the interface structure containing the called function pointer.
1492 * @param pDeviceEnum Where to return the enumerated audio devices.
1493 */
1494 DECLR3CALLBACKMEMBER(int, pfnGetDevices, (PPDMIHOSTAUDIO pInterface, PPDMAUDIODEVICEENUM pDeviceEnum));
1495
1496 /**
1497 * Returns the current status from the audio backend.
1498 *
1499 * @returns PDMAUDIOBACKENDSTS enum.
1500 * @param pInterface Pointer to the interface structure containing the called function pointer.
1501 * @param enmDir Audio direction to get status for. Pass PDMAUDIODIR_ANY for overall status.
1502 */
1503 DECLR3CALLBACKMEMBER(PDMAUDIOBACKENDSTS, pfnGetStatus, (PPDMIHOSTAUDIO pInterface, PDMAUDIODIR enmDir));
1504
1505 /**
1506 * Sets a callback the audio backend can call. Optional.
1507 *
1508 * @returns VBox status code.
1509 * @param pInterface Pointer to the interface structure containing the called function pointer.
1510 * @param pfnCallback The callback function to use, or NULL when unregistering.
1511 */
1512 DECLR3CALLBACKMEMBER(int, pfnSetCallback, (PPDMIHOSTAUDIO pInterface, PFNPDMHOSTAUDIOCALLBACK pfnCallback));
1513
1514 /**
1515 * Creates an audio stream using the requested stream configuration.
1516 * If a backend is not able to create this configuration, it will return its best match in the acquired configuration
1517 * structure on success.
1518 *
1519 * @returns VBox status code.
1520 * @param pInterface Pointer to the interface structure containing the called function pointer.
1521 * @param pStream Pointer to audio stream.
1522 * @param pCfgReq Pointer to requested stream configuration.
1523 * @param pCfgAcq Pointer to acquired stream configuration.
1524 */
1525 DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
1526
1527 /**
1528 * Destroys an audio stream.
1529 *
1530 * @returns VBox status code.
1531 * @param pInterface Pointer to the interface structure containing the called function pointer.
1532 * @param pStream Pointer to audio stream.
1533 */
1534 DECLR3CALLBACKMEMBER(int, pfnStreamDestroy, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1535
1536 /**
1537 * Controls an audio stream.
1538 *
1539 * @returns VBox status code.
1540 * @param pInterface Pointer to the interface structure containing the called function pointer.
1541 * @param pStream Pointer to audio stream.
1542 * @param enmStreamCmd The stream command to issue.
1543 */
1544 DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
1545
1546 /**
1547 * Returns the amount which is readable from the audio (input) stream.
1548 *
1549 * @returns For non-raw layout streams: Number of readable bytes.
1550 * for raw layout streams : Number of readable audio frames.
1551 * @param pInterface Pointer to the interface structure containing the called function pointer.
1552 * @param pStream Pointer to audio stream.
1553 */
1554 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetReadable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1555
1556 /**
1557 * Returns the amount which is writable to the audio (output) stream.
1558 *
1559 * @returns For non-raw layout streams: Number of writable bytes.
1560 * for raw layout streams : Number of writable audio frames.
1561 * @param pInterface Pointer to the interface structure containing the called function pointer.
1562 * @param pStream Pointer to audio stream.
1563 */
1564 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetWritable, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1565
1566 /**
1567 * Returns the amount which is pending (in other words has not yet been processed) by/from the backend yet.
1568 * Optional.
1569 *
1570 * For input streams this is read audio data by the backend which has not been processed by the host yet.
1571 * For output streams this is written audio data to the backend which has not been processed by the backend yet.
1572 *
1573 * @returns For non-raw layout streams: Number of pending bytes.
1574 * for raw layout streams : Number of pending audio frames.
1575 * @param pInterface Pointer to the interface structure containing the called function pointer.
1576 * @param pStream Pointer to audio stream.
1577 */
1578 DECLR3CALLBACKMEMBER(uint32_t, pfnStreamGetPending, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1579
1580 /**
1581 * Returns the current status of the given backend stream.
1582 *
1583 * @returns PDMAUDIOSTREAMSTS
1584 * @param pInterface Pointer to the interface structure containing the called function pointer.
1585 * @param pStream Pointer to audio stream.
1586 */
1587 DECLR3CALLBACKMEMBER(PDMAUDIOSTREAMSTS, pfnStreamGetStatus, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1588
1589 /**
1590 * Gives the host backend the chance to do some (necessary) iteration work.
1591 *
1592 * @returns VBox status code.
1593 * @param pInterface Pointer to the interface structure containing the called function pointer.
1594 * @param pStream Pointer to audio stream.
1595 */
1596 DECLR3CALLBACKMEMBER(int, pfnStreamIterate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1597
1598 /**
1599 * Signals the backend that the host wants to begin playing for this iteration. Optional.
1600 *
1601 * @param pInterface Pointer to the interface structure containing the called function pointer.
1602 * @param pStream Pointer to audio stream.
1603 */
1604 DECLR3CALLBACKMEMBER(void, pfnStreamPlayBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1605
1606 /**
1607 * Plays (writes to) an audio (output) stream.
1608 *
1609 * @returns VBox status code.
1610 * @param pInterface Pointer to the interface structure containing the called function pointer.
1611 * @param pStream Pointer to audio stream.
1612 * @param pvBuf Pointer to audio data buffer to play.
1613 * @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1614 * for raw layout streams : Size (in audio frames) of audio data buffer.
1615 * @param pcxWritten For non-raw layout streams: Returns number of bytes written. Optional.
1616 * for raw layout streams : Returns number of frames written. Optional.
1617 */
1618 DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, const void *pvBuf, uint32_t cxBuf, uint32_t *pcxWritten));
1619
1620 /**
1621 * Signals the backend that the host finished playing for this iteration. Optional.
1622 *
1623 * @param pInterface Pointer to the interface structure containing the called function pointer.
1624 * @param pStream Pointer to audio stream.
1625 */
1626 DECLR3CALLBACKMEMBER(void, pfnStreamPlayEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1627
1628 /**
1629 * Signals the backend that the host wants to begin capturing for this iteration. Optional.
1630 *
1631 * @param pInterface Pointer to the interface structure containing the called function pointer.
1632 * @param pStream Pointer to audio stream.
1633 */
1634 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureBegin, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1635
1636 /**
1637 * Captures (reads from) an audio (input) stream.
1638 *
1639 * @returns VBox status code.
1640 * @param pInterface Pointer to the interface structure containing the called function pointer.
1641 * @param pStream Pointer to audio stream.
1642 * @param pvBuf Buffer where to store read audio data.
1643 * @param cxBuf For non-raw layout streams: Size (in bytes) of audio data buffer,
1644 * for raw layout streams : Size (in audio frames) of audio data buffer.
1645 * @param pcxRead For non-raw layout streams: Returns number of bytes read. Optional.
1646 * for raw layout streams : Returns number of frames read. Optional.
1647 */
1648 DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, void *pvBuf, uint32_t cxBuf, uint32_t *pcxRead));
1649
1650 /**
1651 * Signals the backend that the host finished capturing for this iteration. Optional.
1652 *
1653 * @param pInterface Pointer to the interface structure containing the called function pointer.
1654 * @param pStream Pointer to audio stream.
1655 */
1656 DECLR3CALLBACKMEMBER(void, pfnStreamCaptureEnd, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream));
1657
1658} PDMIHOSTAUDIO;
1659
1660/** PDMIHOSTAUDIO interface ID. */
1661#define PDMIHOSTAUDIO_IID "640F5A31-8245-491C-538F-29A0F9D08881"
1662
1663/** @} */
1664
1665#endif /* !___VBox_vmm_pdmaudioifs_h */
1666
Note: See TracBrowser for help on using the repository browser.

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