VirtualBox

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

Last change on this file since 80537 was 76861, checked in by vboxsync, 6 years ago

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