Maarten Lankhorst : dsound:
Add some comments from earlier patch that makes code a little better
understandable .
Alexandre Julliard
julliard at wine.codeweavers.com
Thu Feb 22 05:56:37 CST 2007
Module: wine
Branch: master
Commit: 0036298a140645e1aacd3a22c272647998ef09e0
URL: http://source.winehq.org/git/wine.git/?a=commit;h=0036298a140645e1aacd3a22c272647998ef09e0
Author: Maarten Lankhorst <m.b.lankhorst at gmail.com>
Date: Wed Feb 21 20:16:22 2007 +0100
dsound: Add some comments from earlier patch that makes code a little better understandable.
---
dlls/dsound/mixer.c | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++-
1 files changed, 90 insertions(+), 1 deletions(-)
diff --git a/dlls/dsound/mixer.c b/dlls/dsound/mixer.c
index 1597aa0..8eba8c0 100644
--- a/dlls/dsound/mixer.c
+++ b/dlls/dsound/mixer.c
@@ -98,6 +98,14 @@ void DSOUND_RecalcFormat(IDirectSoundBufferImpl *dsb)
dsb->writelead = (dsb->freq / 100) * dsb->pwfx->nBlockAlign;
}
+/**
+ * Check for application callback requests for when the play position
+ * reaches certain points.
+ *
+ * The offsets that will be triggered will be those between the recorded
+ * "last played" position for the buffer (i.e. dsb->playpos) and "len" bytes
+ * beyond that position.
+ */
void DSOUND_CheckEvent(IDirectSoundBufferImpl *dsb, int len)
{
int i;
@@ -163,6 +171,10 @@ static inline BYTE cvtS16toU8(INT16 s)
return (s >> 8) ^ (unsigned char)0x80;
}
+/**
+ * Copy a single frame from the given input buffer to the given output buffer.
+ * Translate 8 <-> 16 bits and mono <-> stereo
+ */
static inline void cp_fields(const IDirectSoundBufferImpl *dsb, BYTE *ibuf, BYTE *obuf )
{
DirectSoundDevice * device = dsb->device;
@@ -209,7 +221,24 @@ static inline void cp_fields(const IDirectSoundBufferImpl *dsb, BYTE *ibuf, BYTE
}
}
-/* Now with PerfectPitch (tm) technology */
+/**
+ * Mix at most the given amount of data into the given device buffer from the
+ * given secondary buffer, starting from the dsb's first currently unmixed
+ * frame (buf_mixpos), translating frequency (pitch), stereo/mono and
+ * bits-per-sample. The secondary buffer sample is looped if it is not
+ * long enough and it is a looping buffer.
+ * (Doesn't perform any mixing - this is a straight copy operation).
+ *
+ * Now with PerfectPitch (tm) technology
+ *
+ * dsb = the secondary buffer
+ * buf = the device buffer
+ * len = number of bytes to store in the device buffer
+ *
+ * Returns: the number of bytes read from the secondary buffer
+ * (ie. len, adjusted for frequency, number of channels and sample size,
+ * and limited by buffer length for non-looping buffers)
+ */
static INT DSOUND_MixerNorm(IDirectSoundBufferImpl *dsb, BYTE *buf, INT len)
{
INT i, size, ipos, ilen;
@@ -356,6 +385,10 @@ static void DSOUND_MixerVol(IDirectSoundBufferImpl *dsb, BYTE *buf, INT len)
}
}
+/**
+ * Make sure the device's tmp_buffer is at least the given size. Return a
+ * pointer to it.
+ */
static LPBYTE DSOUND_tmpbuffer(DirectSoundDevice *device, DWORD len)
{
TRACE("(%p,%d)\n", device, len);
@@ -372,6 +405,19 @@ static LPBYTE DSOUND_tmpbuffer(DirectSoundDevice *device, DWORD len)
return device->tmp_buffer;
}
+/**
+ * Mix (at most) the given number of bytes into the given position of the
+ * device buffer, from the secondary buffer "dsb" (starting at the current
+ * mix position for that buffer).
+ *
+ * Returns the number of bytes actually mixed into the device buffer. This
+ * will match fraglen unless the end of the secondary buffer is reached
+ * (and it is not looping).
+ *
+ * dsb = the secondary buffer to mix from
+ * writepos = position (offset) in device buffer to write at
+ * fraglen = number of bytes to mix
+ */
static DWORD DSOUND_MixInBuffer(IDirectSoundBufferImpl *dsb, DWORD writepos, DWORD fraglen)
{
INT i, len, ilen, field, todo;
@@ -381,9 +427,15 @@ static DWORD DSOUND_MixInBuffer(IDirectSoundBufferImpl *dsb, DWORD writepos, DWO
len = fraglen;
if (!(dsb->playflags & DSBPLAY_LOOPING)) {
+ /* This buffer is not looping, so make sure the requested
+ * length will not take us past the end of the buffer */
int secondary_remainder = dsb->buflen - dsb->buf_mixpos;
int adjusted_remainder = MulDiv(dsb->device->pwfx->nAvgBytesPerSec, secondary_remainder, dsb->nAvgBytesPerSec);
assert(adjusted_remainder >= 0);
+ /* The adjusted remainder must be at least one sample,
+ * otherwise we will never reach the end of the
+ * secondary buffer, as there will perpetually be a
+ * fractional remainder */
TRACE("secondary_remainder = %d, adjusted_remainder = %d, len = %d\n", secondary_remainder, adjusted_remainder, len);
if (adjusted_remainder < len) {
TRACE("clipping len to remainder of secondary buffer\n");
@@ -404,12 +456,16 @@ static DWORD DSOUND_MixInBuffer(IDirectSoundBufferImpl *dsb, DWORD writepos, DWO
TRACE("MixInBuffer (%p) len = %d, dest = %d\n", dsb, len, writepos);
+ /* first, copy the data from the DirectSoundBuffer into the temporary
+ buffer, translating frequency/bits-per-sample/number-of-channels
+ to match the device settings */
ilen = DSOUND_MixerNorm(dsb, ibuf, len);
if ((dsb->dsbd.dwFlags & DSBCAPS_CTRLPAN) ||
(dsb->dsbd.dwFlags & DSBCAPS_CTRLVOLUME) ||
(dsb->dsbd.dwFlags & DSBCAPS_CTRL3D))
DSOUND_MixerVol(dsb, ibuf, len);
+ /* Now mix the temporary buffer into the devices main buffer */
if (dsb->device->pwfx->wBitsPerSample == 8) {
BYTE *obuf = dsb->device->buffer + writepos;
@@ -667,8 +723,23 @@ void DSOUND_ForceRemix(IDirectSoundBufferImpl *dsb)
LeaveCriticalSection(&dsb->lock);
}
+/**
+ * Mix some frames from the given secondary buffer "dsb" into the device
+ * primary buffer.
+ *
+ * dsb = the secondary buffer
+ * playpos = the current play position in the device buffer (primary buffer)
+ * writepos = the current safe-to-write position in the device buffer
+ * mixlen = the maximum number of bytes in the primary buffer to mix, from the
+ * current writepos.
+ *
+ * Returns: the number of bytes beyond the writepos that were mixed.
+ */
static DWORD DSOUND_MixOne(IDirectSoundBufferImpl *dsb, DWORD playpos, DWORD writepos, DWORD mixlen)
{
+ /* The buffer's primary_mixpos may be before or after the the device
+ * buffer's mixpos, but both must be ahead of writepos. */
+
DWORD len, slen;
/* determine this buffer's write position */
DWORD buf_writepos = DSOUND_CalcPlayPosition(dsb, writepos, writepos);
@@ -823,6 +894,19 @@ post_mix:
return slen;
}
+/**
+ * For a DirectSoundDevice, go through all the currently playing buffers and
+ * mix them in to the device buffer.
+ *
+ * playpos = the current play position in the primary buffer
+ * writepos = the current safe-to-write position in the primary buffer
+ * mixlen = the maximum amount to mix into the primary buffer
+ * (beyond the current writepos)
+ * recover = true if the sound device may have been reset and the write
+ * position in the device buffer changed
+ *
+ * Returns: the length beyond the writepos that was mixed to.
+ */
static DWORD DSOUND_MixToPrimary(DirectSoundDevice *device, DWORD playpos, DWORD writepos, DWORD mixlen, BOOL recover)
{
INT i, len, maxlen = 0;
@@ -941,6 +1025,11 @@ void DSOUND_WaveQueue(DirectSoundDevice *device, DWORD mixq)
/* #define SYNC_CALLBACK */
+/**
+ * Perform mixing for a Direct Sound device. That is, go through all the
+ * secondary buffers (the sound bites currently playing) and mix them in
+ * to the primary buffer (the device buffer).
+ */
static void DSOUND_PerformMix(DirectSoundDevice *device)
{
int nfiller;
More information about the wine-cvs
mailing list