|
From: Lars I. <lar...@us...> - 2004-12-06 20:09:52
|
Update of /cvsroot/pywin32/pywin32/com/win32comext/directsound/src In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv10590/com/win32comext/directsound/src Modified Files: PyIDirectSound.cpp directsound.cpp Log Message: Documentation improvements - work in progress. Index: PyIDirectSound.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/PyIDirectSound.cpp,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** PyIDirectSound.cpp 30 Nov 2004 21:30:28 -0000 1.1 --- PyIDirectSound.cpp 6 Dec 2004 20:09:41 -0000 1.2 *************** *** 62,66 **** } ! // @pymethod |PyIDirectSound|SetCooperativeLevel|Description of SetCooperativeLevel. PyObject *PyIDirectSound::SetCooperativeLevel(PyObject *self, PyObject *args) { --- 62,66 ---- } ! // @pymethod |PyIDirectSound|SetCooperativeLevel|The IDirectSound::SetCooperativeLevel method sets the cooperative level of the application for this sound device. PyObject *PyIDirectSound::SetCooperativeLevel(PyObject *self, PyObject *args) { *************** *** 108,112 **** } ! // @pymethod |PyIDirectSound|CreateSoundBuffer|Description of CreateSoundBuffer. PyObject *PyIDirectSound::CreateSoundBuffer(PyObject *self, PyObject *args) { --- 108,112 ---- } ! // @pymethod |PyIDirectSound|CreateSoundBuffer|The IDirectSound::CreateSoundBuffer method creates a DirectSoundBuffer object to hold a sequence of audio samples. PyObject *PyIDirectSound::CreateSoundBuffer(PyObject *self, PyObject *args) { *************** *** 152,156 **** } ! // @pymethod |PyIDirectSound|GetCaps|Description of GetCaps. PyObject *PyIDirectSound::GetCaps(PyObject *self, PyObject *args) { --- 152,156 ---- } ! // @pymethod |PyIDirectSound|GetCaps|The GetCaps method retrieves the capabilities of the hardware device that is represented by the DirectSound object. See <l DSCAPS contants>. PyObject *PyIDirectSound::GetCaps(PyObject *self, PyObject *args) { *************** *** 177,181 **** } ! // @pymethod |PyIDirectSound|Compact|Description of Compact. PyObject *PyIDirectSound::Compact(PyObject *self, PyObject *args) { --- 177,181 ---- } ! // @pymethod |PyIDirectSound|Compact|The Compact method moves the unused portions of on-board sound memory, if any, to a contiguous block so that the largest portion of free memory will be available. PyObject *PyIDirectSound::Compact(PyObject *self, PyObject *args) { *************** *** 201,205 **** } ! // @pymethod |PyIDirectSound|GetSpeakerConfig|Description of GetSpeakerConfig. PyObject *PyIDirectSound::GetSpeakerConfig(PyObject *self, PyObject *args) { --- 201,205 ---- } ! // @pymethod |PyIDirectSound|GetSpeakerConfig|The GetSpeakerConfig method retrieves the speaker configuration. PyObject *PyIDirectSound::GetSpeakerConfig(PyObject *self, PyObject *args) { *************** *** 225,229 **** } ! // @pymethod |PyIDirectSound|SetSpeakerConfig|Description of SetSpeakerConfig. PyObject *PyIDirectSound::SetSpeakerConfig(PyObject *self, PyObject *args) { --- 225,229 ---- } ! // @pymethod |PyIDirectSound|SetSpeakerConfig|The SetSpeakerConfig method specifies the speaker configuration of the DirectSound object. PyObject *PyIDirectSound::SetSpeakerConfig(PyObject *self, PyObject *args) { Index: directsound.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/directsound.cpp,v retrieving revision 1.3 retrieving revision 1.4 diff -C2 -d -r1.3 -r1.4 *** directsound.cpp 2 Dec 2004 09:48:36 -0000 1.3 --- directsound.cpp 6 Dec 2004 20:09:41 -0000 1.4 *************** *** 138,142 **** /* List of module functions */ ! // @module directsound|A module encapsulating the DirectSound interfaces static struct PyMethodDef directsound_methods[]= { --- 138,142 ---- /* List of module functions */ ! /* @module directsound|A module encapsulating the DirectSound interfaces. See <l DirectSound examples> for a quick overview. */ static struct PyMethodDef directsound_methods[]= { *************** *** 188,202 **** PyCom_RegisterExtensionSupport(dict, g_interfaceSupportData, sizeof(g_interfaceSupportData)/sizeof(g_interfaceSupportData[0])); ! ADD_CONSTANT(DSCAPS_PRIMARYMONO); ADD_CONSTANT(DSCAPS_PRIMARYSTEREO); ADD_CONSTANT(DSCAPS_PRIMARY8BIT); ADD_CONSTANT(DSCAPS_PRIMARY16BIT); ADD_CONSTANT(DSCAPS_CONTINUOUSRATE); ADD_CONSTANT(DSCAPS_EMULDRIVER); ADD_CONSTANT(DSCAPS_CERTIFIED); ADD_CONSTANT(DSCAPS_SECONDARYMONO); ADD_CONSTANT(DSCAPS_SECONDARYSTEREO); ADD_CONSTANT(DSCAPS_SECONDARY8BIT); ! ADD_CONSTANT(DSCAPS_SECONDARY16BIT); ADD_CONSTANT(DSBPLAY_LOOPING); // @const directsound|DSBPLAY_LOOPING|text. ADD_CONSTANT(DSBSTATUS_PLAYING); --- 188,215 ---- PyCom_RegisterExtensionSupport(dict, g_interfaceSupportData, sizeof(g_interfaceSupportData)/sizeof(g_interfaceSupportData[0])); ! // @topic DSCAPS constants| ! ! // @const directsound|DSCAPS_PRIMARYMONO|The device supports monophonic primary buffers. ! ADD_CONSTANT(DSCAPS_PRIMARYMONO); ! // @const directsound|DSCAPS_PRIMARYSTEREO|The device supports stereo primary buffers. ADD_CONSTANT(DSCAPS_PRIMARYSTEREO); + // @const directsound|DSCAPS_PRIMARY8BIT|The device supports hardware-mixed secondary buffers with 8-bit samples. ADD_CONSTANT(DSCAPS_PRIMARY8BIT); + // @const directsound|DSCAPS_PRIMARY16BIT|The device supports primary sound buffers with 16-bit samples. ADD_CONSTANT(DSCAPS_PRIMARY16BIT); + // @const directsound|DSCAPS_CONTINUOUSRATE|The device supports all sample rates between the dwMinSecondarySampleRate and dwMaxSecondarySampleRate member values. Typically, this means that the actual output rate will be within +/- 10 hertz (Hz) of the requested frequency. ADD_CONSTANT(DSCAPS_CONTINUOUSRATE); + // @const directsound|DSCAPS_EMULDRIVER|The device does not have a DirectSound driver installed, so it is being emulated through the waveform-audio functions. Performance degradation should be expected. ADD_CONSTANT(DSCAPS_EMULDRIVER); + // @const directsound|DSCAPS_CERTIFIED|This driver has been tested and certified by Microsoft. ADD_CONSTANT(DSCAPS_CERTIFIED); + // @const directsound|DSCAPS_SECONDARYMONO|The device supports hardware-mixed monophonic secondary buffers. ADD_CONSTANT(DSCAPS_SECONDARYMONO); + // @const directsound|DSCAPS_SECONDARYSTEREO|The device supports hardware-mixed stereo secondary buffers. ADD_CONSTANT(DSCAPS_SECONDARYSTEREO); + // @const directsound|DSCAPS_SECONDARY8BIT|The device supports hardware-mixed secondary buffers with 8-bit samples. ADD_CONSTANT(DSCAPS_SECONDARY8BIT); ! // @const directsound|DSCAPS_SECONDARY16BIT|The device supports hardware-mixed secondary sound buffers with 16-bit samples. ! ADD_CONSTANT(DSBPLAY_LOOPING); // @const directsound|DSBPLAY_LOOPING|text. ADD_CONSTANT(DSBSTATUS_PLAYING); *************** *** 212,237 **** --- 225,277 ---- ADD_CONSTANT(DS3DMODE_HEADRELATIVE); ADD_CONSTANT(DS3DMODE_DISABLE); + + // @topic DSCAPS constants| + + // @const directsound|DSBCAPS_PRIMARYBUFFER|Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer will be created. ADD_CONSTANT(DSBCAPS_PRIMARYBUFFER); + // @const directsound|DSBCAPS_STATIC|Indicates that the buffer will be used for static sound data. Typically, these buffers are loaded once and played many times. These buffers are candidates for hardware memory. ADD_CONSTANT(DSBCAPS_STATIC); + // @const directsound|DSBCAPS_LOCHARDWARE|The buffer is in hardware memory and uses hardware mixing. ADD_CONSTANT(DSBCAPS_LOCHARDWARE); + // @const directsound|DSBCAPS_LOCSOFTWARE|The buffer is in software memory and uses software mixing. ADD_CONSTANT(DSBCAPS_LOCSOFTWARE); + // @const directsound|DSBCAPS_CTRL3D|The buffer is either a primary buffer or a secondary buffer that uses 3-D control. To create a primary buffer, the dwFlags member of the DSBUFFERDESC structure should include the DSBCAPS_PRIMARYBUFFER flag. ADD_CONSTANT(DSBCAPS_CTRL3D); + // @const directsound|DSBCAPS_CTRLFREQUENCY|The buffer must have frequency control capability. ADD_CONSTANT(DSBCAPS_CTRLFREQUENCY); + // @const directsound|DSBCAPS_CTRLPAN|The buffer must have pan control capability. ADD_CONSTANT(DSBCAPS_CTRLPAN); + // @const directsound|DSBCAPS_CTRLVOLUME|The buffer must have volume control capability. ADD_CONSTANT(DSBCAPS_CTRLVOLUME); + // @const directsound|DSBCAPS_CTRLPOSITIONNOTIFY|The buffer must have control position notify capability. ADD_CONSTANT(DSBCAPS_CTRLPOSITIONNOTIFY); + // @const directsound|DSBCAPS_STICKYFOCUS|Changes the focus behavior of the sound buffer. This flag can be specified in an IDirectSound::CreateSoundBuffer call. With this flag set, an application using DirectSound can continue to play its sticky focus buffers if the user switches to another application not using DirectSound. In this situation, the application's normal buffers are muted, but the sticky focus buffers are still audible. This is useful for nongame applications, such as movie playback (DirectShow), when the user wants to hear the soundtrack while typing in Microsoft Word or Microsoft® Excel, for example. However, if the user switches to another DirectSound application, all sound buffers, both normal and sticky focus, in the previous application are muted. ADD_CONSTANT(DSBCAPS_STICKYFOCUS); + // @const directsound|DSBCAPS_GLOBALFOCUS|The buffer is a global sound buffer. With this flag set, an application using DirectSound can continue to play its buffers if the user switches focus to another application, even if the new application uses DirectSound. The one exception is if you switch focus to a DirectSound application that uses the DSSCL_EXCLUSIVE or DSSCL_WRITEPRIMARY flag for its cooperative level. In this case, the global sounds from other applications will not be audible. ADD_CONSTANT(DSBCAPS_GLOBALFOCUS); + // @const directsound|DSBCAPS_GETCURRENTPOSITION2|Indicates that IDirectSoundBuffer::GetCurrentPosition should use the new behavior of the play cursor. In DirectSound in DirectX 1, the play cursor was significantly ahead of the actual playing sound on emulated sound cards; it was directly behind the write cursor. Now, if the DSBCAPS_GETCURRENTPOSITION2 flag is specified, the application can get a more accurate play position. If this flag is not specified, the old behavior is preserved for compatibility. Note that this flag affects only emulated sound cards; if a DirectSound driver is present, the play cursor is accurate for DirectSound in all versions of DirectX. ADD_CONSTANT(DSBCAPS_GETCURRENTPOSITION2); + // @const directsound|DSBCAPS_MUTE3DATMAXDISTANCE|The sound is reduced to silence at the maximum distance. The buffer will stop playing when the maximum distance is exceeded, so that processor time is not wasted. ADD_CONSTANT(DSBCAPS_MUTE3DATMAXDISTANCE); + ADD_CONSTANT(DSCBCAPS_WAVEMAPPED); + + // @const directsound|DSSPEAKER_HEADPHONE|The speakers are headphones. ADD_CONSTANT(DSSPEAKER_HEADPHONE); + // @const directsound|DSSPEAKER_MONO|The speakers are monaural. ADD_CONSTANT(DSSPEAKER_MONO); + // @const directsound|DSSPEAKER_QUAD|The speakers are quadraphonic. ADD_CONSTANT(DSSPEAKER_QUAD); + // @const directsound|DSSPEAKER_STEREO|The speakers are stereo (default value). ADD_CONSTANT(DSSPEAKER_STEREO); + // @const directsound|DSSPEAKER_SURROUND|The speakers are surround sound. ADD_CONSTANT(DSSPEAKER_SURROUND); + // @const directsound|DSSPEAKER_GEOMETRY_MIN|The speakers are directed over an arc of 5 degrees. ADD_CONSTANT(DSSPEAKER_GEOMETRY_MIN); + // @const directsound|DSSPEAKER_GEOMETRY_NARROW|The speakers are directed over an arc of 10 degrees. ADD_CONSTANT(DSSPEAKER_GEOMETRY_NARROW); + // @const directsound|DSSPEAKER_GEOMETRY_WIDE|The speakers are directed over an arc of 20 degrees. ADD_CONSTANT(DSSPEAKER_GEOMETRY_WIDE); + // @const directsound|DSSPEAKER_GEOMETRY_MAX|The speakers are directed over an arc of 180 degrees. ADD_CONSTANT(DSSPEAKER_GEOMETRY_MAX); // real macros - todo if can be bothered *************** *** 260,261 **** --- 300,357 ---- PyDict_SetItemString(dict, "DSBUFFERDESCType", (PyObject *)&PyDSBUFFERDESCType); } + + /* @topic DirectSound examples| + + @ex Our raison d'etre - playing sounds:| + + WAV_HEADER_SIZE = struct.calcsize('<4sl4s4slhhllhh4sl') + + def wav_header_unpack(data): + '''Unpack a wav header and stuff it into a WAVEFORMATEX structure''' + (riff, riffsize, wave, fmt, fmtsize, format, nchannels, samplespersecond, + datarate, blockalign, bitspersample, data, datalength) \ + = struct.unpack('<4sl4s4slhhllhh4sl', data) + + if riff != 'RIFF' or fmtsize != 16 or fmt != 'fmt ' or data != 'data': + raise ValueError, 'illegal wav header' + + wfx = pywintypes.WAVEFORMATEX() + wfx.wFormatTag = format + wfx.nChannels = nchannels + wfx.nSamplesPerSec = samplespersecond + wfx.nAvgBytesPerSec = datarate + wfx.nBlockAlign = blockalign + wfx.wBitsPerSample = bitspersample + + return wfx, datalength + + # Play a wav file and wait until it's finished + + fname=os.path.join(os.path.dirname(__file__), "01-Intro.wav") + f = open(fname, 'rb') + + # Read and unpack the wav header + hdr = f.read(WAV_HEADER_SIZE) + wfx, size = wav_header_unpack(hdr) + + d = ds.DirectSoundCreate(None, None) + d.SetCooperativeLevel(None, ds.DSSCL_PRIORITY) + + sdesc = ds.DSBUFFERDESC() + sdesc.dwFlags = ds.DSBCAPS_STICKYFOCUS | ds.DSBCAPS_CTRLPOSITIONNOTIFY + sdesc.dwBufferBytes = size + sdesc.lpwfxFormat = wfx + + buffer = d.CreateSoundBuffer(sdesc, None) + + event = win32event.CreateEvent(None, 0, 0, None) + notify = buffer.QueryInterface(ds.IID_IDirectSoundNotify) + + notify.SetNotificationPositions((ds.DSBPN_OFFSETSTOP, event)) + + buffer.Update(0, f.read(size)) + + buffer.Play(0) + + win32event.WaitForSingleObject(event, -1) + */ |
