VirtualBox

source: vbox/trunk/src/VBox/Devices/Audio/AudioMixBuffer.h@ 103914

Last change on this file since 103914 was 98103, checked in by vboxsync, 21 months ago

Copyright year updates by scm.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 10.2 KB
Line 
1/* $Id: AudioMixBuffer.h 98103 2023-01-17 14:15:46Z vboxsync $ */
2/** @file
3 * Audio Mixing bufer convert audio samples to/from different rates / formats.
4 */
5
6/*
7 * Copyright (C) 2014-2023 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 */
53typedef 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. */
84typedef 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 */
92typedef 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. */
102typedef AUDMIXBUFVOL *PAUDMIXBUFVOL;
103
104
105/** Pointer to audio mixing buffer. */
106typedef struct AUDIOMIXBUF *PAUDIOMIXBUF;
107/** Pointer to a const audio mixing buffer. */
108typedef struct AUDIOMIXBUF const *PCAUDIOMIXBUF;
109
110
111/**
112 * State & config for AudioMixBufPeek created by AudioMixBufInitPeekState.
113 */
114typedef 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. */
134typedef AUDIOMIXBUFPEEKSTATE *PAUDIOMIXBUFPEEKSTATE;
135
136
137/**
138 * State & config for AudioMixBufWrite, AudioMixBufSilence, AudioMixBufBlend and
139 * AudioMixBufBlendGap, created by AudioMixBufInitWriteState.
140 */
141typedef 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. */
163typedef AUDIOMIXBUFWRITESTATE *PAUDIOMIXBUFWRITESTATE;
164
165
166/**
167 * Audio mixing buffer.
168 */
169typedef 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
212int AudioMixBufInit(PAUDIOMIXBUF pMixBuf, const char *pszName, PCPDMAUDIOPCMPROPS pProps, uint32_t cFrames);
213void AudioMixBufTerm(PAUDIOMIXBUF pMixBuf);
214void AudioMixBufDrop(PAUDIOMIXBUF pMixBuf);
215void AudioMixBufSetVolume(PAUDIOMIXBUF pMixBuf, PCPDMAUDIOVOLUME pVol);
216
217/** @name Mixer buffer getters
218 * @{ */
219uint32_t AudioMixBufSize(PCAUDIOMIXBUF pMixBuf);
220uint32_t AudioMixBufSizeBytes(PCAUDIOMIXBUF pMixBuf);
221uint32_t AudioMixBufUsed(PCAUDIOMIXBUF pMixBuf);
222uint32_t AudioMixBufUsedBytes(PCAUDIOMIXBUF pMixBuf);
223uint32_t AudioMixBufFree(PCAUDIOMIXBUF pMixBuf);
224uint32_t AudioMixBufFreeBytes(PCAUDIOMIXBUF pMixBuf);
225bool AudioMixBufIsEmpty(PCAUDIOMIXBUF pMixBuf);
226uint32_t AudioMixBufReadPos(PCAUDIOMIXBUF pMixBuf);
227uint32_t AudioMixBufWritePos(PCAUDIOMIXBUF pMixBuf);
228/** @} */
229
230/** @name Mixer buffer reading
231 * @{ */
232int AudioMixBufInitPeekState(PCAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFPEEKSTATE pState, PCPDMAUDIOPCMPROPS pDstProps);
233void AudioMixBufPeek(PCAUDIOMIXBUF pMixBuf, uint32_t offSrcFrame, uint32_t cMaxSrcFrames, uint32_t *pcSrcFramesPeeked,
234 PAUDIOMIXBUFPEEKSTATE pState, void *pvDst, uint32_t cbDst, uint32_t *pcbDstPeeked);
235void AudioMixBufAdvance(PAUDIOMIXBUF pMixBuf, uint32_t cFrames);
236/** @} */
237
238/** @name Mixer buffer writing
239 * @{ */
240int AudioMixBufInitWriteState(PCAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, PCPDMAUDIOPCMPROPS pSrcProps);
241void AudioMixBufWrite(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, const void *pvSrcBuf, uint32_t cbSrcBuf,
242 uint32_t offDstFrame, uint32_t cMaxDstFrames, uint32_t *pcDstFramesWritten);
243void AudioMixBufSilence(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, uint32_t offFrame, uint32_t cFrames);
244void AudioMixBufBlend(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, const void *pvSrcBuf, uint32_t cbSrcBuf,
245 uint32_t offDstFrame, uint32_t cMaxDstFrames, uint32_t *pcDstFramesBlended);
246void AudioMixBufBlendGap(PAUDIOMIXBUF pMixBuf, PAUDIOMIXBUFWRITESTATE pState, uint32_t cFrames);
247void AudioMixBufCommit(PAUDIOMIXBUF pMixBuf, uint32_t cFrames);
248/** @} */
249
250/** @} */
251#endif /* !VBOX_INCLUDED_SRC_Audio_AudioMixBuffer_h */
252
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