|
From: Lars I. <lar...@us...> - 2005-03-23 22:52:10
|
Update of /cvsroot/pywin32/pywin32/com/win32comext/directsound/src In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv25396/com/win32comext/directsound/src Modified Files: PyDSBCAPS.cpp PyDSBUFFERDESC.cpp PyIDirectSound.cpp directsound.cpp Log Message: Documentation improvements - work in progress. Index: PyDSBUFFERDESC.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/PyDSBUFFERDESC.cpp,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** PyDSBUFFERDESC.cpp 30 Nov 2004 21:30:28 -0000 1.1 --- PyDSBUFFERDESC.cpp 23 Mar 2005 22:51:08 -0000 1.2 *************** *** 93,97 **** /*static*/ struct PyMemberDef PyDSBUFFERDESC::members[] = { {"dwFlags", T_INT, OFF(m_dsbd.dwFlags), 0, "Identifies the capabilities to include when creating a new DirectSoundBuffer object"}, ! // @prop integer|dwFlags|Identifies the capabilities to include when creating a new DirectSoundBuffer object. {"dwBufferBytes", T_INT, OFF(m_dsbd.dwBufferBytes), 0, "Size of the new buffer, in bytes. This value must be 0 when creating primary buffers. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX"}, // @prop integer|dwBufferBytes|Size of the new buffer, in bytes. This value must be 0 when creating primary buffers. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX. --- 93,111 ---- /*static*/ struct PyMemberDef PyDSBUFFERDESC::members[] = { {"dwFlags", T_INT, OFF(m_dsbd.dwFlags), 0, "Identifies the capabilities to include when creating a new DirectSoundBuffer object"}, ! // @prop integer|dwFlags|Identifies the capabilities to include when creating a new DirectSoundBuffer object. Specify one or more of the following: ! // @flagh Flag|Description ! // @flag DSBCAPS_PRIMARYBUFFER|Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer will be created. ! // @flag 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. ! // @flag DSBCAPS_LOCHARDWARE|The buffer is in hardware memory and uses hardware mixing. ! // @flag DSBCAPS_LOCSOFTWARE|The buffer is in software memory and uses software mixing. ! // @flag 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. ! // @flag DSBCAPS_CTRLFREQUENCY|The buffer must have frequency control capability. ! // @flag DSBCAPS_CTRLPAN|The buffer must have pan control capability. ! // @flag DSBCAPS_CTRLVOLUME|The buffer must have volume control capability. ! // @flag DSBCAPS_CTRLPOSITIONNOTIFY|The buffer must have control position notify capability. ! // @flag 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. ! // @flag 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. ! // @flag 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. ! // @flag 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. {"dwBufferBytes", T_INT, OFF(m_dsbd.dwBufferBytes), 0, "Size of the new buffer, in bytes. This value must be 0 when creating primary buffers. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX"}, // @prop integer|dwBufferBytes|Size of the new buffer, in bytes. This value must be 0 when creating primary buffers. For secondary buffers, the minimum and maximum sizes allowed are specified by DSBSIZE_MIN and DSBSIZE_MAX. Index: PyIDirectSound.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/PyIDirectSound.cpp,v retrieving revision 1.4 retrieving revision 1.5 diff -C2 -d -r1.4 -r1.5 *** PyIDirectSound.cpp 10 Mar 2005 23:23:58 -0000 1.4 --- PyIDirectSound.cpp 23 Mar 2005 22:51:09 -0000 1.5 *************** *** 76,80 **** if ( !PyArg_ParseTuple(args, "Oi:SetCooperativeLevel", &obHWND, // @pyparm int|hwnd||Window handle to the application or None. ! &level) ) // @pyparm int|level||Requested priority level. See the DSSCL constants. return NULL; --- 76,86 ---- if ( !PyArg_ParseTuple(args, "Oi:SetCooperativeLevel", &obHWND, // @pyparm int|hwnd||Window handle to the application or None. ! &level) ) // @pyparm int|level||Requested priority level. Specify one of the following values: ! // @flagh Level|Description ! // @flag DSSCL_NORMAL|Sets the application to a fully cooperative status. Most applications should use this level, because it has the smoothest multitasking and resource-sharing behavior. ! // @flag DSSCL_PRIORITY|Sets the application to the priority level. Applications with this cooperative level can call the DirectSoundBuffer.setFormat and DirectSound.compact methods. ! // @flag DSSCL_EXCLUSIVE|Sets the application to the exclusive level. When it has the input focus, the application will be the only one audible (sounds from applications with the DSBCAPS_GLOBALFOCUS flag set will be muted). With this level, it also has all the privileges of the DSSCL_PRIORITY level. DirectSound will restore the hardware format, as specified by the most recent call to the DirectSoundBuffer.setFormat method, once the application gains the input focus. (Note that DirectSound will always restore the wave format, no matter what priority level is set.) ! // @flag DSSCL_WRITEPRIMARY|This is the highest priority level. The application has write access to the primary sound buffers. No secondary sound buffers in any application can be played. ! return NULL; Index: PyDSBCAPS.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/PyDSBCAPS.cpp,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** PyDSBCAPS.cpp 30 Nov 2004 21:30:28 -0000 1.1 --- PyDSBCAPS.cpp 23 Mar 2005 22:51:06 -0000 1.2 *************** *** 88,91 **** --- 88,105 ---- /*static*/ struct PyMemberDef PyDSBCAPS::members[] = { {"dwFlags", T_INT, OFF(m_caps.dwFlags), 0, "Flags that specify buffer-object capabilities."}, // @prop integer|dwFlags|Flags that specify buffer-object capabilities. + // @flagh Flag|Description + // @flag DSBCAPS_PRIMARYBUFFER|Indicates that the buffer is a primary sound buffer. If this value is not specified, a secondary sound buffer will be created. + // @flag 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. + // @flag DSBCAPS_LOCHARDWARE|The buffer is in hardware memory and uses hardware mixing. + // @flag DSBCAPS_LOCSOFTWARE|The buffer is in software memory and uses software mixing. + // @flag 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. + // @flag DSBCAPS_CTRLFREQUENCY|The buffer must have frequency control capability. + // @flag DSBCAPS_CTRLPAN|The buffer must have pan control capability. + // @flag DSBCAPS_CTRLVOLUME|The buffer must have volume control capability. + // @flag DSBCAPS_CTRLPOSITIONNOTIFY|The buffer must have control position notify capability. + // @flag 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. + // @flag 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. + // @flag 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. + // @flag 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. {"dwBufferBytes", T_INT, OFF(m_caps.dwBufferBytes), 0, "Size of the buffer, in bytes"}, // @prop integer|nChannels|Size of the buffer, in bytes. {"dwUnlockTransferRate", T_INT, OFF(m_caps.dwUnlockTransferRate), 0, Index: directsound.cpp =================================================================== RCS file: /cvsroot/pywin32/pywin32/com/win32comext/directsound/src/directsound.cpp,v retrieving revision 1.6 retrieving revision 1.7 diff -C2 -d -r1.6 -r1.7 *** directsound.cpp 8 Mar 2005 20:46:49 -0000 1.6 --- directsound.cpp 23 Mar 2005 22:51:09 -0000 1.7 *************** *** 228,237 **** { "DirectSoundCaptureCreate", directsound_DirectSoundCaptureCreate, 1}, // @pymeth DirectSoundCaptureCreate|The DirectSoundCaptureCreate function creates and initializes an object that supports the IDirectSoundCapture interface. { "DirectSoundCaptureEnumerate", directsound_DirectSoundCaptureEnumerate, 1}, // @pymeth DirectSoundCaptureEnumerate|The DirectSoundCaptureEnumerate function enumerates the DirectSoundCapture objects installed in the system. ! {"DSCAPS", PyWinMethod_NewDSCAPS, 1 }, // @pymeth DSCAPS|Creates a new <o PyDSCAPS> object. ! {"DSBCAPS", PyWinMethod_NewDSBCAPS, 1 }, // @pymeth DSBCAPS|Creates a new <o PyDSBCAPS> object. ! {"DSCCAPS", PyWinMethod_NewDSCCAPS, 1 }, // @pymeth DSCCAPS|Creates a new <o PyDSCCAPS> object. ! {"DSCBCAPS", PyWinMethod_NewDSCBCAPS, 1 }, // @pymeth DSCBCAPS|Creates a new <o PyDSCBCAPS> object. ! {"DSBUFFERDESC", PyWinMethod_NewDSBUFFERDESC, 1 }, // @pymeth DSBUFFERDESC|Creates a new <o PyDSBUFFERDESC> object. ! {"DSCBUFFERDESC", PyWinMethod_NewDSCBUFFERDESC, 1 }, // @pymeth DSCBUFFERDESC|Creates a new <o PyDSCBUFFERDESC> object. { NULL, NULL }, }; --- 228,237 ---- { "DirectSoundCaptureCreate", directsound_DirectSoundCaptureCreate, 1}, // @pymeth DirectSoundCaptureCreate|The DirectSoundCaptureCreate function creates and initializes an object that supports the IDirectSoundCapture interface. { "DirectSoundCaptureEnumerate", directsound_DirectSoundCaptureEnumerate, 1}, // @pymeth DirectSoundCaptureEnumerate|The DirectSoundCaptureEnumerate function enumerates the DirectSoundCapture objects installed in the system. ! {"DSCAPS", PyWinMethod_NewDSCAPS, 1 }, // @pymeth DSCAPS|Creates a new <o PyDSCAPS> object. ! {"DSBCAPS", PyWinMethod_NewDSBCAPS, 1 }, // @pymeth DSBCAPS|Creates a new <o PyDSBCAPS> object. ! {"DSCCAPS", PyWinMethod_NewDSCCAPS, 1 }, // @pymeth DSCCAPS|Creates a new <o PyDSCCAPS> object. ! {"DSCBCAPS", PyWinMethod_NewDSCBCAPS, 1 }, // @pymeth DSCBCAPS|Creates a new <o PyDSCBCAPS> object. ! {"DSBUFFERDESC", PyWinMethod_NewDSBUFFERDESC, 1 }, // @pymeth DSBUFFERDESC|Creates a new <o PyDSBUFFERDESC> object. ! {"DSCBUFFERDESC", PyWinMethod_NewDSCBUFFERDESC, 1 }, // @pymeth DSCBUFFERDESC|Creates a new <o PyDSCBUFFERDESC> object. { NULL, NULL }, }; *************** *** 275,280 **** 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); --- 275,278 ---- *************** *** 327,332 **** 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); --- 325,328 ---- *************** *** 432,436 **** # 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') --- 428,431 ---- *************** *** 451,468 **** 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) - */ - - /* @topic DirectSoundCapture examples| ! @ex This shows how to record into a wav file:| import pywintypes --- 446,458 ---- 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) ! @ex This example shows how to record into a wav file:| import pywintypes |
