VirtualBox

source: vbox/trunk/src/VBox/Devices/Audio/AudioMixer.h@ 82302

Last change on this file since 82302 was 77602, checked in by vboxsync, 6 years ago

Audio/Mixer: Centralized a mixer stream's internal status updating by implementing audioMixerStreamUpdateStatus() and adding AUDMIXSTREAM_STATUS_ flags. Also check this status in audioMixerSinkMultiplexSync() when writing to a mixer stream's buffer.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 9.8 KB
Line 
1/* $Id: AudioMixer.h 77602 2019-03-07 15:10:01Z vboxsync $ */
2/** @file
3 * VBox audio - Mixing routines.
4 *
5 * The mixing routines are mainly used by the various audio device emulations
6 * to achieve proper multiplexing from/to attached devices LUNs.
7 */
8
9/*
10 * Copyright (C) 2014-2019 Oracle Corporation
11 *
12 * This file is part of VirtualBox Open Source Edition (OSE), as
13 * available from http://www.virtualbox.org. This file is free software;
14 * you can redistribute it and/or modify it under the terms of the GNU
15 * General Public License (GPL) as published by the Free Software
16 * Foundation, in version 2 as it comes in the "COPYING" file of the
17 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
18 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
19 */
20
21#ifndef VBOX_INCLUDED_SRC_Audio_AudioMixer_h
22#define VBOX_INCLUDED_SRC_Audio_AudioMixer_h
23#ifndef RT_WITHOUT_PRAGMA_ONCE
24# pragma once
25#endif
26
27#include <iprt/cdefs.h>
28#include <iprt/critsect.h>
29
30#include <VBox/vmm/pdmaudioifs.h>
31
32/**
33 * Structure for maintaining an audio mixer instance.
34 */
35typedef struct AUDIOMIXER
36{
37 /** The mixer's name. */
38 char *pszName;
39 /** The mixer's critical section. */
40 RTCRITSECT CritSect;
41 /** The master volume of this mixer. */
42 PDMAUDIOVOLUME VolMaster;
43 /** List of audio mixer sinks. */
44 RTLISTANCHOR lstSinks;
45 /** Number of used audio sinks. */
46 uint8_t cSinks;
47} AUDIOMIXER, *PAUDIOMIXER;
48
49/** Defines an audio mixer stream's flags. */
50#define AUDMIXSTREAMFLAGS uint32_t
51
52/** No flags specified. */
53#define AUDMIXSTREAM_FLAG_NONE 0
54/** The mixing stream is flagged as being enabled (active). */
55#define AUDMIXSTREAM_FLAG_ENABLED RT_BIT(0)
56
57/** Defines an audio mixer stream's internal status. */
58#define AUDMIXSTREAMSTATUS uint32_t
59
60/** No status set. */
61#define AUDMIXSTREAM_STATUS_NONE 0
62/** The mixing stream is enabled (active). */
63#define AUDMIXSTREAM_STATUS_ENABLED RT_BIT(0)
64/** The mixing stream can be read from. */
65#define AUDMIXSTREAM_STATUS_CAN_READ RT_BIT(1)
66/** The mixing stream can be written to. */
67#define AUDMIXSTREAM_STATUS_CAN_WRITE RT_BIT(2)
68
69
70/** Prototype needed for AUDMIXSTREAM struct definition. */
71typedef struct AUDMIXSINK *PAUDMIXSINK;
72
73/**
74 * Structure for maintaining an audio mixer stream.
75 */
76typedef struct AUDMIXSTREAM
77{
78 /** List node. */
79 RTLISTNODE Node;
80 /** Name of this stream. */
81 char *pszName;
82 /** The streams's critical section. */
83 RTCRITSECT CritSect;
84 /** Sink this stream is attached to. */
85 PAUDMIXSINK pSink;
86 /** Stream flags of type AUDMIXSTREAM_FLAG_. */
87 uint32_t fFlags;
88 /** Stream status of type AUDMIXSTREAM_STATUS_. */
89 uint32_t fStatus;
90 /** Pointer to audio connector being used. */
91 PPDMIAUDIOCONNECTOR pConn;
92 /** Pointer to PDM audio stream this mixer stream handles. */
93 PPDMAUDIOSTREAM pStream;
94 /** Last read (recording) / written (playback) timestamp (in ns). */
95 uint64_t tsLastReadWrittenNs;
96 /** The stream's circular buffer for temporarily
97 * holding (raw) device audio data. */
98 PRTCIRCBUF pCircBuf;
99} AUDMIXSTREAM, *PAUDMIXSTREAM;
100
101/** Defines an audio sink's current status. */
102#define AUDMIXSINKSTS uint32_t
103
104/** No status specified. */
105#define AUDMIXSINK_STS_NONE 0
106/** The sink is active and running. */
107#define AUDMIXSINK_STS_RUNNING RT_BIT(0)
108/** The sink is in a pending disable state. */
109#define AUDMIXSINK_STS_PENDING_DISABLE RT_BIT(1)
110/** Dirty flag.
111 * For output sinks this means that there is data in the
112 * sink which has not been played yet.
113 * For input sinks this means that there is data in the
114 * sink which has been recorded but not transferred to the
115 * destination yet. */
116#define AUDMIXSINK_STS_DIRTY RT_BIT(2)
117
118/**
119 * Audio mixer sink direction.
120 */
121typedef enum AUDMIXSINKDIR
122{
123 /** Unknown direction. */
124 AUDMIXSINKDIR_UNKNOWN = 0,
125 /** Input (capturing from a device). */
126 AUDMIXSINKDIR_INPUT,
127 /** Output (playing to a device). */
128 AUDMIXSINKDIR_OUTPUT,
129 /** The usual 32-bit hack. */
130 AUDMIXSINKDIR_32BIT_HACK = 0x7fffffff
131} AUDMIXSINKDIR;
132
133/**
134 * Audio mixer sink command.
135 */
136typedef enum AUDMIXSINKCMD
137{
138 /** Unknown command, do not use. */
139 AUDMIXSINKCMD_UNKNOWN = 0,
140 /** Enables the sink. */
141 AUDMIXSINKCMD_ENABLE,
142 /** Disables the sink. */
143 AUDMIXSINKCMD_DISABLE,
144 /** Pauses the sink. */
145 AUDMIXSINKCMD_PAUSE,
146 /** Resumes the sink. */
147 AUDMIXSINKCMD_RESUME,
148 /** Tells the sink's streams to drop all (buffered) data immediately. */
149 AUDMIXSINKCMD_DROP,
150 /** Hack to blow the type up to 32-bit. */
151 AUDMIXSINKCMD_32BIT_HACK = 0x7fffffff
152} AUDMIXSINKCMD;
153
154/**
155 * Structure for keeping audio input sink specifics.
156 * Do not use directly. Instead, use AUDMIXSINK.
157 */
158typedef struct AUDMIXSINKIN
159{
160 /** The current recording source. Can be NULL if not set. */
161 PAUDMIXSTREAM pStreamRecSource;
162} AUDMIXSINKIN;
163
164/**
165 * Structure for keeping audio output sink specifics.
166 * Do not use directly. Instead, use AUDMIXSINK.
167 */
168typedef struct AUDMIXSINKOUT
169{
170} AUDMIXSINKOUT;
171
172/**
173 * Structure for maintaining an audio mixer sink.
174 */
175typedef struct AUDMIXSINK
176{
177 RTLISTNODE Node;
178 /** Pointer to mixer object this sink is bound to. */
179 PAUDIOMIXER pParent;
180 /** Name of this sink. */
181 char *pszName;
182 /** The sink direction, that is,
183 * if this sink handles input or output. */
184 AUDMIXSINKDIR enmDir;
185 /** The sink's critical section. */
186 RTCRITSECT CritSect;
187 /** This sink's mixing buffer, acting as
188 * a parent buffer for all streams this sink owns. */
189 PDMAUDIOMIXBUF MixBuf;
190 /** Union for input/output specifics. */
191 union
192 {
193 AUDMIXSINKIN In;
194 AUDMIXSINKOUT Out;
195 };
196 /** Sink status of type AUDMIXSINK_STS_XXX. */
197 AUDMIXSINKSTS fStatus;
198 /** The sink's PCM format. */
199 PDMAUDIOPCMPROPS PCMProps;
200 /** Number of streams assigned. */
201 uint8_t cStreams;
202 /** List of assigned streams.
203 * Note: All streams have the same PCM properties, so the
204 * mixer does not do any conversion. */
205 /** @todo Use something faster -- vector maybe? */
206 RTLISTANCHOR lstStreams;
207 /** The volume of this sink. The volume always will
208 * be combined with the mixer's master volume. */
209 PDMAUDIOVOLUME Volume;
210 /** The volume of this sink, combined with the last set master volume. */
211 PDMAUDIOVOLUME VolumeCombined;
212 /** Timestamp since last update (in ms). */
213 uint64_t tsLastUpdatedMs;
214 /** Last read (recording) / written (playback) timestamp (in ns). */
215 uint64_t tsLastReadWrittenNs;
216#ifdef VBOX_AUDIO_MIXER_DEBUG
217 struct
218 {
219 PPDMAUDIOFILE pFile;
220 } Dbg;
221#endif
222} AUDMIXSINK, *PAUDMIXSINK;
223
224/**
225 * Audio mixer operation.
226 */
227typedef enum AUDMIXOP
228{
229 /** Invalid operation, do not use. */
230 AUDMIXOP_INVALID = 0,
231 /** Copy data from A to B, overwriting data in B. */
232 AUDMIXOP_COPY,
233 /** Blend data from A with (existing) data in B. */
234 AUDMIXOP_BLEND,
235 /** The usual 32-bit hack. */
236 AUDMIXOP_32BIT_HACK = 0x7fffffff
237} AUDMIXOP;
238
239/** No flags specified. */
240#define AUDMIXSTRMCTL_FLAG_NONE 0
241
242int AudioMixerCreate(const char *pszName, uint32_t uFlags, PAUDIOMIXER *ppMixer);
243int AudioMixerCreateSink(PAUDIOMIXER pMixer, const char *pszName, AUDMIXSINKDIR enmDir, PAUDMIXSINK *ppSink);
244void AudioMixerDestroy(PAUDIOMIXER pMixer);
245void AudioMixerInvalidate(PAUDIOMIXER pMixer);
246void AudioMixerRemoveSink(PAUDIOMIXER pMixer, PAUDMIXSINK pSink);
247int AudioMixerSetMasterVolume(PAUDIOMIXER pMixer, PPDMAUDIOVOLUME pVol);
248void AudioMixerDebug(PAUDIOMIXER pMixer, PCDBGFINFOHLP pHlp, const char *pszArgs);
249
250int AudioMixerSinkAddStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream);
251int AudioMixerSinkCreateStream(PAUDMIXSINK pSink, PPDMIAUDIOCONNECTOR pConnector, PPDMAUDIOSTREAMCFG pCfg, AUDMIXSTREAMFLAGS fFlags, PAUDMIXSTREAM *ppStream);
252int AudioMixerSinkCtl(PAUDMIXSINK pSink, AUDMIXSINKCMD enmCmd);
253void AudioMixerSinkDestroy(PAUDMIXSINK pSink);
254uint32_t AudioMixerSinkGetReadable(PAUDMIXSINK pSink);
255uint32_t AudioMixerSinkGetWritable(PAUDMIXSINK pSink);
256AUDMIXSINKDIR AudioMixerSinkGetDir(PAUDMIXSINK pSink);
257const char *AudioMixerSinkGetName(const PAUDMIXSINK pSink);
258PAUDMIXSTREAM AudioMixerSinkGetRecordingSource(PAUDMIXSINK pSink);
259PAUDMIXSTREAM AudioMixerSinkGetStream(PAUDMIXSINK pSink, uint8_t uIndex);
260AUDMIXSINKSTS AudioMixerSinkGetStatus(PAUDMIXSINK pSink);
261uint8_t AudioMixerSinkGetStreamCount(PAUDMIXSINK pSink);
262bool AudioMixerSinkIsActive(PAUDMIXSINK pSink);
263int AudioMixerSinkRead(PAUDMIXSINK pSink, AUDMIXOP enmOp, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead);
264void AudioMixerSinkRemoveStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream);
265void AudioMixerSinkRemoveAllStreams(PAUDMIXSINK pSink);
266void AudioMixerSinkReset(PAUDMIXSINK pSink);
267void AudioMixerSinkGetFormat(PAUDMIXSINK pSink, PPDMAUDIOPCMPROPS pPCMProps);
268int AudioMixerSinkSetFormat(PAUDMIXSINK pSink, PPDMAUDIOPCMPROPS pPCMProps);
269int AudioMixerSinkSetRecordingSource(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream);
270int AudioMixerSinkSetVolume(PAUDMIXSINK pSink, PPDMAUDIOVOLUME pVol);
271int AudioMixerSinkWrite(PAUDMIXSINK pSink, AUDMIXOP enmOp, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten);
272int AudioMixerSinkUpdate(PAUDMIXSINK pSink);
273
274int AudioMixerStreamCtl(PAUDMIXSTREAM pStream, PDMAUDIOSTREAMCMD enmCmd, uint32_t fCtl);
275void AudioMixerStreamDestroy(PAUDMIXSTREAM pStream);
276bool AudioMixerStreamIsActive(PAUDMIXSTREAM pStream);
277bool AudioMixerStreamIsValid(PAUDMIXSTREAM pStream);
278
279#endif /* !VBOX_INCLUDED_SRC_Audio_AudioMixer_h */
280
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