1 | /* $Id: AudioMixBuffer.h 106061 2024-09-16 14:03:52Z vboxsync $ */
|
---|
2 | /** @file
|
---|
3 | * Audio Mixing bufer convert audio samples to/from different rates / formats.
|
---|
4 | */
|
---|
5 |
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2014-2024 Oracle and/or its affiliates.
|
---|
8 | *
|
---|
9 | * This file is part of VirtualBox base platform packages, as
|
---|
10 | * available from https://www.virtualbox.org.
|
---|
11 | *
|
---|
12 | * This program is free software; you can redistribute it and/or
|
---|
13 | * modify it under the terms of the GNU General Public License
|
---|
14 | * as published by the Free Software Foundation, in version 3 of the
|
---|
15 | * License.
|
---|
16 | *
|
---|
17 | * This program is distributed in the hope that it will be useful, but
|
---|
18 | * WITHOUT ANY WARRANTY; without even the implied warranty of
|
---|
19 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
---|
20 | * General Public License for more details.
|
---|
21 | *
|
---|
22 | * You should have received a copy of the GNU General Public License
|
---|
23 | * along with this program; if not, see <https://www.gnu.org/licenses>.
|
---|
24 | *
|
---|
25 | * SPDX-License-Identifier: GPL-3.0-only
|
---|
26 | */
|
---|
27 |
|
---|
28 | #ifndef VBOX_INCLUDED_SRC_Audio_AudioMixBuffer_h
|
---|
29 | #define VBOX_INCLUDED_SRC_Audio_AudioMixBuffer_h
|
---|
30 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
31 | # pragma once
|
---|
32 | #endif
|
---|
33 |
|
---|
34 | #include <iprt/cdefs.h>
|
---|
35 | #include <VBox/vmm/pdmaudioifs.h>
|
---|
36 |
|
---|
37 | /** @defgroup grp_pdm_ifs_audio_mixing_buffers Audio Mixing Buffers
|
---|
38 | * @ingroup grp_pdm_ifs_audio_mixing
|
---|
39 | *
|
---|
40 | * @note This is currently placed under PDM Audio Interface as that seemed like
|
---|
41 | * the best place for it.
|
---|
42 | *
|
---|
43 | * @{
|
---|
44 | */
|
---|
45 |
|
---|
46 |
|
---|
47 | /**
|
---|
48 | * Rate processing information of a source & destination audio stream.
|
---|
49 | *
|
---|
50 | * This is needed because both streams can differ regarding their rates and
|
---|
51 | * therefore need to be treated accordingly.
|
---|
52 | */
|
---|
53 | typedef struct AUDIOSTREAMRATE
|
---|
54 | {
|
---|
55 | /** Current (absolute) offset in the output (destination) stream.
|
---|
56 | * @todo r=bird: Please reveal which unit these members are given in. */
|
---|
57 | uint64_t offDst;
|
---|
58 | /** Increment for moving offDst for the destination stream.
|
---|
59 | * This is needed because the source <-> destination rate might be different. */
|
---|
60 | uint64_t uDstInc;
|
---|
61 | /** Current (absolute) offset in the input stream. */
|
---|
62 | uint32_t offSrc;
|
---|
63 | /** Set if no conversion is necessary. */
|
---|
64 | bool fNoConversionNeeded;
|
---|
65 | bool afPadding[3];
|
---|
66 |
|
---|
67 | /** Last processed frame of the input stream.
|
---|
68 | * Needed for interpolation. */
|
---|
69 | union
|
---|
70 | {
|
---|
71 | int32_t ai32Samples[PDMAUDIO_MAX_CHANNELS];
|
---|
72 | } SrcLast;
|
---|
73 |
|
---|
74 | /**
|
---|
75 | * Resampling function.
|
---|
76 | * @returns Number of destination frames written.
|
---|
77 | */
|
---|
78 | DECLR3CALLBACKMEMBER(uint32_t, pfnResample, (int32_t *pi32Dst, uint32_t cDstFrames,
|
---|
79 | int32_t const *pi32Src, uint32_t cSrcFrames, uint32_t *pcSrcFramesRead,
|
---|
80 | struct AUDIOSTREAMRATE *pRate));
|
---|
81 |
|
---|
82 | } AUDIOSTREAMRATE;
|
---|
83 | /** Pointer to rate processing information of a stream. */
|
---|
84 | typedef AUDIOSTREAMRATE *PAUDIOSTREAMRATE;
|
---|
85 |
|
---|
86 | /**
|
---|
87 | * Mixing buffer volume parameters.
|
---|
88 | *
|
---|
89 | * The volume values are in fixed point style and must be converted to/from
|
---|
90 | * before using with e.g. PDMAUDIOVOLUME.
|
---|
91 | */
|
---|
92 | typedef struct AUDMIXBUFVOL
|
---|
93 | {
|
---|
94 | /** Set to @c true if this stream is muted, @c false if not. */
|
---|
95 | bool fMuted;
|
---|
96 | /** Set if all (relevant) channels are at max. */
|
---|
97 | bool fAllMax;
|
---|
98 | /** The per-channels values. */
|
---|
99 | uint32_t auChannels[PDMAUDIO_MAX_CHANNELS];
|
---|
100 | } AUDMIXBUFVOL;
|
---|
101 | /** Pointer to mixing buffer volument parameters. */
|
---|
102 | typedef AUDMIXBUFVOL *PAUDMIXBUFVOL;
|
---|
103 |
|
---|
104 |
|
---|
105 | /** Pointer to audio mixing buffer. */
|
---|
106 | typedef struct AUDIOMIXBUF *PAUDIOMIXBUF;
|
---|
107 | /** Pointer to a const audio mixing buffer. */
|
---|
108 | typedef struct AUDIOMIXBUF const *PCAUDIOMIXBUF;
|
---|
109 |
|
---|
110 |
|
---|
111 | /**
|
---|
112 | * State & config for AudioMixBufPeek created by AudioMixBufInitPeekState.
|
---|
113 | */
|
---|
114 | typedef struct AUDIOMIXBUFPEEKSTATE
|
---|
115 | {
|
---|
116 | /** Encodes @a cFrames from @a paSrc to @a pvDst. */
|
---|
117 | DECLR3CALLBACKMEMBER(void, pfnEncode,(void *pvDst, int32_t const *paSrc, uint32_t cFrames, struct AUDIOMIXBUFPEEKSTATE *pState));
|
---|
118 | /** Sample rate conversion state (only used when needed). */
|
---|
119 | AUDIOSTREAMRATE Rate;
|
---|
120 | /** Source (mixer) channels. */
|
---|
121 | uint8_t cSrcChannels;
|
---|
122 | /** Destination channels. */
|
---|
123 | uint8_t cDstChannels;
|
---|
124 | /** Destination frame size. */
|
---|
125 | uint8_t cbDstFrame;
|
---|
126 | /** The destination frame layout described as indexes into the source frame.
|
---|
127 | * This ASSUMES that all channels uses the same sample size, so one sample per
|
---|
128 | * channel if you like.
|
---|
129 | * Negative values are special: -1 for zero, -2 for silence.
|
---|
130 | * @note Blending stereo into mono is not really expressible here. */
|
---|
131 | int8_t aidxChannelMap[PDMAUDIO_MAX_CHANNELS];
|
---|
132 | } AUDIOMIXBUFPEEKSTATE;
|
---|
133 | /** Pointer to peek state & config. */
|
---|
134 | typedef AUDIOMIXBUFPEEKSTATE *PAUDIOMIXBUFPEEKSTATE;
|
---|
135 |
|
---|
136 |
|
---|
137 | /**
|
---|
138 | * State & config for AudioMixBufWrite, AudioMixBufSilence, AudioMixBufBlend and
|
---|
139 | * AudioMixBufBlendGap, created by AudioMixBufInitWriteState.
|
---|
140 | */
|
---|
141 | typedef struct AUDIOMIXBUFWRITESTATE
|
---|
142 | {
|
---|
143 | /** Encodes @a cFrames from @a pvSrc to @a paDst. */
|
---|
144 | DECLR3CALLBACKMEMBER(void, pfnDecode,(int32_t *paDst, const void *pvSrc, uint32_t cFrames, struct AUDIOMIXBUFWRITESTATE *pState));
|
---|
145 | /** Encodes @a cFrames from @a pvSrc blending into @a paDst. */
|
---|
146 | DECLR3CALLBACKMEMBER(void, pfnDecodeBlend,(int32_t *paDst, const void *pvSrc, uint32_t cFrames, struct AUDIOMIXBUFWRITESTATE *pState));
|
---|
147 | /** Sample rate conversion state (only used when needed). */
|
---|
148 | AUDIOSTREAMRATE Rate;
|
---|
149 | /** Destination (mixer) channels. */
|
---|
150 | uint8_t cDstChannels;
|
---|
151 | /** Source hannels. */
|
---|
152 | uint8_t cSrcChannels;
|
---|
153 | /** Source frame size. */
|
---|
154 | uint8_t cbSrcFrame;
|
---|
155 | /** The destination frame layout described as indexes into the source frame.
|
---|
156 | * This ASSUMES that all channels uses the same sample size, so one sample per
|
---|
157 | * channel if you like.
|
---|
158 | * Negative values are special: -1 for zero, -2 for silence.
|
---|
159 | * @note Blending stereo into mono is not really expressible here. */
|
---|
160 | int8_t aidxChannelMap[PDMAUDIO_MAX_CHANNELS];
|
---|
161 | } AUDIOMIXBUFWRITESTATE;
|
---|
162 | /** Pointer to write state & config. */
|
---|
163 | typedef AUDIOMIXBUFWRITESTATE *PAUDIOMIXBUFWRITESTATE;
|
---|
164 |
|
---|
165 |
|
---|
166 | /**
|
---|
167 | * Audio mixing buffer.
|
---|
168 | */
|
---|
169 | typedef struct AUDIOMIXBUF
|
---|
170 | {
|
---|
171 | /** Magic value (AUDIOMIXBUF_MAGIC). */
|
---|
172 | uint32_t uMagic;
|
---|
173 | /** Size of the frame buffer (in audio frames). */
|
---|
174 | uint32_t cFrames;
|
---|
175 | /** The frame buffer.
|
---|
176 | * This is a two dimensional array consisting of cFrames rows and
|
---|
177 | * cChannels columns. */
|
---|
178 | int32_t *pi32Samples;
|
---|
179 | /** The number of channels. */
|
---|
180 | uint8_t cChannels;
|
---|
181 | /** The frame size (row size if you like). */
|
---|
182 | uint8_t cbFrame;
|
---|
183 | uint8_t abPadding[2];
|
---|
184 | /** The current read position (in frames). */
|
---|
185 | uint32_t offRead;
|
---|
186 | /** The current write position (in frames). */
|
---|
187 | uint32_t offWrite;
|
---|
188 | /** How much audio frames are currently being used in this buffer.
|
---|
189 | * @note This also is known as the distance in ring buffer terms. */
|
---|
190 | uint32_t cUsed;
|
---|
191 | /** Audio properties for the buffer content - for frequency and channel count.
|
---|
192 | * (This is the guest side PCM properties.) */
|
---|
193 | PDMAUDIOPCMPROPS Props;
|
---|
194 | /** Internal representation of current volume used for mixing. */
|
---|
195 | AUDMIXBUFVOL Volume;
|
---|
196 | /** Name of the buffer. */
|
---|
197 | char *pszName;
|
---|
198 | } AUDIOMIXBUF;
|
---|
199 |
|
---|
200 | /** Magic value for AUDIOMIXBUF (Antonio Lucio Vivaldi). */
|
---|
201 | #define AUDIOMIXBUF_MAGIC UINT32_C(0x16780304)
|
---|
202 | /** Dead mixer buffer magic. */
|
---|
203 | #define AUDIOMIXBUF_MAGIC_DEAD UINT32_C(0x17410728)
|
---|
204 |
|
---|
205 | /** Converts (audio) frames to bytes. */
|
---|
206 | #define AUDIOMIXBUF_F2B(a_pMixBuf, a_cFrames) PDMAUDIOPCMPROPS_F2B(&(a_pMixBuf)->Props, a_cFrames)
|
---|
207 | /** Converts bytes to (audio) frames.
|
---|
208 | * @note Does *not* take the conversion ratio into account. */
|
---|
209 | #define AUDIOMIXBUF_B2F(a_pMixBuf, a_cb) PDMAUDIOPCMPROPS_B2F(&(a_pMixBuf)->Props, a_cb)
|
---|
210 |
|
---|
211 |
|
---|
212 | int AudioMixBufInit(PAUDIOMIXBUF pMixBuf, const char *pszName, PCPDMAUDIOPCMPROPS pProps, uint32_t cFrames);
|
---|
213 | void AudioMixBufTerm(PAUDIOMIXBUF pMixBuf);
|
---|
214 | void AudioMixBufDrop(PAUDIOMIXBUF pMixBuf);
|
---|
215 | void AudioMixBufSetVolume(PAUDIOMIXBUF pMixBuf, PCPDMAUDIOVOLUME pVol);
|
---|
216 |
|
---|
217 | /** @name Mixer buffer getters
|
---|
218 | * @{ */
|
---|
219 | uint32_t AudioMixBufSize(PCAUDIOMIXBUF pMixBuf);
|
---|
220 | uint32_t AudioMixBufSizeBytes(PCAUDIOMIXBUF pMixBuf);
|
---|
221 | uint32_t AudioMixBufUsed(PCAUDIOMIXBUF pMixBuf);
|
---|
222 | uint32_t AudioMixBufUsedBytes(PCAUDIOMIXBUF pMixBuf);
|
---|
223 | uint32_t AudioMixBufFree(PCAUDIOMIXBUF pMixBuf);
|
---|
224 | uint32_t AudioMixBufFreeBytes(PCAUDIOMIXBUF pMixBuf);
|
---|
225 | bool AudioMixBufIsEmpty(PCAUDIOMIXBUF pMixBuf);
|
---|
226 | uint32_t AudioMixBufReadPos(PCAUDIOMIXBUF pMixBuf);
|
---|
227 | uint32_t AudioMixBufWritePos(PCAUDIOMIXBUF pMixBuf);
|
---|
228 | /** @} */
|
---|
229 |
|
---|
230 | /** @name Mixer buffer reading
|
---|
231 | * @{ */
|
---|
232 | int AudioMixBufInitPeekState(PCAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFPEEKSTATE pState, PCPDMAUDIOPCMPROPS pDstProps);
|
---|
233 | void AudioMixBufPeek(PCAUDIOMIXBUF pMixBuf, uint32_t offSrcFrame, uint32_t cMaxSrcFrames, uint32_t *pcSrcFramesPeeked,
|
---|
234 | PAUDIOMIXBUFPEEKSTATE pState, void *pvDst, uint32_t cbDst, uint32_t *pcbDstPeeked);
|
---|
235 | void AudioMixBufAdvance(PAUDIOMIXBUF pMixBuf, uint32_t cFrames);
|
---|
236 | /** @} */
|
---|
237 |
|
---|
238 | /** @name Mixer buffer writing
|
---|
239 | * @{ */
|
---|
240 | int AudioMixBufInitWriteState(PCAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, PCPDMAUDIOPCMPROPS pSrcProps);
|
---|
241 | void AudioMixBufWrite(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, const void *pvSrcBuf, uint32_t cbSrcBuf,
|
---|
242 | uint32_t offDstFrame, uint32_t cMaxDstFrames, uint32_t *pcDstFramesWritten);
|
---|
243 | void AudioMixBufSilence(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, uint32_t offFrame, uint32_t cFrames);
|
---|
244 | void AudioMixBufBlend(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, const void *pvSrcBuf, uint32_t cbSrcBuf,
|
---|
245 | uint32_t offDstFrame, uint32_t cMaxDstFrames, uint32_t *pcDstFramesBlended);
|
---|
246 | void AudioMixBufBlendGap(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, uint32_t cFrames);
|
---|
247 | void AudioMixBufCommit(PAUDIOMIXBUF pMixBuf, uint32_t cFrames);
|
---|
248 | /** @} */
|
---|
249 |
|
---|
250 | /** @} */
|
---|
251 | #endif /* !VBOX_INCLUDED_SRC_Audio_AudioMixBuffer_h */
|
---|
252 |
|
---|