DDK WAVETST Test Case Descriptions
==================================

Unless otherwise stated, all tests use window callback messages and block
waiting for these messages.

When the test shell is running tests in auto mode any interactive messages
will be logged with the prefix "Message suppressed:".

Some test cases are designed to provoke an error from the wave driver.  
All errors from the wave driver are logged with the prefix "Error:".  Such
messages do not necessarily mean the test case has failed.

Some test cases have the prefix "ASYNC:".  These test cases were designed
to be executed only on asyncronous drivers and will not run by WaveTst on
syncronous drivers.


Case 1: waveOutGetNumDevs
    Call waveOutGetNumDevs (verify API returns correct number visually)
 
Case 2: waveOutGetDevCaps:
    Get next device caps (Calls waveOutGetDevCaps on every Wave Output device)
    Call with wSize = 1
    Call with wSize = 0
    Call with invalid device id (483)
 
Case 3: waveOutOpen:
(If a format is supported, the test will try to play a buffer at
 the given format.)
    Open using WAVE_MAPPER
    Open with WM callback
    Open with DLL callback
    Open with task callback
    Call with invalid device ID
    Open with no callback
    Query format after waveOutOpen
    Open without WAVE_ALLOWSYNC
    Query 11M8 hWaveOut null
    No callback, 11M8
    Query 11M16 hWaveOut null
    No callback, 11M16
    Query 11S8 hWaveOut null
    No callback, 11S8
    Query 11S16 hWaveOut null
    No callback, 11S16
    Query 22M8 hWaveOut null
    No callback, 22M8
    Query 22M16 hWaveOut null
    No callback, 22M16
    Query 22S8 hWaveOut null
    No callback, 22S8
    Query 22S16 hWaveOut null
    No callback, 22S16
    Query 44M8 hWaveOut null
    No callback, 44M8
    Query 44M16 hWaveOut null
    No callback, 44M16
    Query 44S8 hWaveOut null
    No callback, 44S8
    Query 44S16 hWaveOut null
    No callback, 44S16
    Query 55S32 hWaveOut null
    No callback, 55S32
 
Case 4: waveOutClose:
    Close when no buffers playing, no buffers in (driver's) queue
    Close paused device, no buffers
    Close paused device, buffers in queue
    Close after finished playing
    ASYNC: Close while playing 
    Close after playing (normal)
 
Case 5: waveOutPrepareHeader:
    Internal done bit  (You can call waveOutPrepare then waveOutUnprepare
                        without setting the 'done' bit manually)
    Prepare after waveOutOpen
    Prepare same buffer twice
 
Case 6: waveOutUnprepareHeader:
    Unprepare after waveOutPrepare
    Unprepare same buffer twice
    Header was never prepared
    ASYNC: Unprepare buffer which is playing
    Call when writing finished
 
Case 7: waveOutWrite Device/Header States:
    Write before waveOutPrepare
    Write after waveOutPrepare
    Write after call to waveOutPause
    Write header1 while header1 still playing
    Write after waveOutReset
    ASYNC: Write header2 while header1 still playing


Case 8: waveOutWrite Looping:
    Write with WHDR_BEGINLOOP 0 loops (Driver should not play anything)
    Write with WHDR_ENDLOOP
    Write with 1 loop - BEGIN block
    Write with 1 loop - END block
    Write with 3 loops - BEGIN block
    Write with 3 loops - END block
    Write with WHDR_BEGIN and WHDR_ENDLOOP flags, 4 loops
    Write while looping
    ASYNC: Write 3 buffers, 3 loops. (1st header has WHDR_BEGINLOOP flag, 
    		 	              3rd header has WHDR_ENDLOOP flag) 
    ASYNC: Write Medium.wav, Short.wav with 3 loops, Long.wav    
    ASYNC: Write while looping

Case 9: waveOutWrite 2K Multiples
(This test writes buffers with datalengths whose sizes are multiples of
 2048 bytes.  Compare your wave driver's output with that of DDK sample
 sndblst.)

Case 10: waveOutWrite <2K Buffers
(Same as case 9 above except the datalengths in this test are all less
 than 2048 bytes.)

Case 11: waveOutWrite >64K Buffers
    Write >64K buffer, start at 10K
    Write >64K buffer, start at 70K
 
Case 12: waveOutPause:
    Pause before waveOutPrepare
    Pause after waveOutPrepare
    Call waveOutPause twice
    ASYNC: Pause during write
    ASYNC: Pause while looping
 
Case 13: waveOutRestart:
    waveOutRestart before calling waveOutWrite
    waveOutRestart before calling waveOutPause
    waveOutRestart after calling waveOutPause
    waveOutRestart while writing
    Call waveOutRestart twice in a row
    Restart while looping
    Restart while paused & looping
 
Case 14: waveOutReset:
    Reset before playing
    Reset paused device
    Reset after playing
    ("Position(TIME_SAMPLES): 0" should be displayed here.  This verifies
      that your driver reset the position for waveOutGetPosition correctly.)
    Reset when device already reset
    ASYNC: Reset while playing, w/logging
    ASYNC: Reset while playing, no logging

Case 15 waveOutReset While Playing:
(This test plays Short.wav in a for() loop while calling waveOutReset
 occasionally.  Compare your driver's output with the DDK sample sndblst.) 


Case 16: waveOutGetPosition:
(This test polls the 'done' bit)
    GetPosition after waveOutPrepare, before playing
    GetPosition during write, TIME_BYTES
    GetPosition during write, TIME_MS
    GetPosition during write, TIME_SAMPLES
    GetPosition during write, TIME_SMPTE
    GetPosition during write, TIME_MIDI
    GetPosition during write, BOGUS FLAG
    GetPosition after reading TIME_BYTES
    Verify ending position in TIME_BYTES
    GetPosition after reading TIME_SAMPLES
    Verify ending position in TIME_SAMPLES
    GetPosition after waveOutReset
 
Case 17: waveOutBreakLoop:
    BreakLoop when not playing 
    BreakLoop when playing - not looping 
    BreakLoop when looping
    BreakLoop when paused and looping
    BreakLoop when paused and not looping
 
Case 18: waveInGetNumDevs:
    Call waveInGetNumDevs (verify API returns correct number visually) 

Case 19: waveInGetDevCaps
    Get next device caps  (Calls waveInGetNumDevs on every Wave Input device)
    Call with invalid device id (20)
    Call with wSize = 2
    Call with wSize = 0

Case 20: waveInOpen 
(If a format is supported, the test will try to play a buffer at
 the given format.)
    Open with WM callback
    Open with DLL callback
    Open with task callback
    Call with invalid device ID
    Query format after open
    Query 11M8 hWaveIn null
    No callback, 11M8
    Query 11M16 hWaveIn null
    No callback, 11M16
    Query 11S8 hWaveIn null
    No callback, 11S8
    Query 11S16 hWaveIn null
    No callback, 11S16
    Query 22M8 hWaveIn null
    No callback, 22M8
    Query 22M16 hWaveIn null
    No callback, 22M16
    Query 22S8 hWaveIn null
    No callback, 22S8
    Query 22S16 hWaveIn null
    No callback, 22S16
    Query 44M8 hWaveIn null
    No callback, 44M8
    Query 44M16 hWaveIn null
    No callback, 44M16
    Query 44S8 hWaveIn null
    No callback, 44S8
    Query 44S16 hWaveIn null
    No callback, 44S16
    Query 55S32 hWaveIn null
    No callback, 55S32
 
Case 21: waveInClose:
    Close after waveInStop
    Close after waveInOpen
    Close after waveInOpen
    Close with buffer in queue
    ASYNC: Close while reading
    Close when read complete
 
Case 22: waveInPrepareHeader:
    Prepare after waveInOpen
    Prepare buffer twice

Case 23: waveInUnprepareHeader: 
    Unprepare before prepare
    Unprepare buffer twice
    Unprepare while reading into buffer
    Unprepare after finished reading
 
Case 24: waveInAddBuffer States:
    AddBuffer an unprepared buffer
    AddBuffer a prepared buffer
    Add 2 buffers
    Use buffer on two different reads after preparing
    Add header1 while header1 still recording
    ASYNC: Add header2 while header1 recording


Case 25: waveInAddBuffer >64K Buffers:
    Addbuffer 90K buffer, start at 10K
    Addbuffer 90K buffer, start at 70K
 
Case 26: waveInAddBuffer Check dwBytesRecorded:
(This test verifies that when waveInReset is called directly after
 adding a header for recording, the header's dwBytesRecorded field
 is set to zero by the wave driver.  The test should display 4 header
 IDs and their respective dwBytesRecorded fields.) 

Case 27: waveInStart:
    Start before waveInAddBuffer
    Start after waveInAddBuffer
    Start after waveInStop
    Call twice
 
Case 28: waveInStop:
    Stop before prepare
    Call stop before waveInStart
    Stop while reading
    Call waveInStop twice
    Call waveInStop after all buffers done (finished recording)
 
Case 29: waveInReset:
    Reset before reading, no buffers present (in driver's queue)
    Reset before reading, buffer present
    Reset stopped device
    Reset when device already reset
 
Case 30: waveInGetPosition:
(This test polls the 'done' bit)
    GetPosition before prepare
    GetPosition during read; TIME_MS
    GetPosition during read; TIME_SAMPLES
    GetPosition during read; TIME_SMPTE
    GetPosition during read; TIME_MIDI
    GetPosition during read; TIME_BYTES
    GetPosition during read; BOGUS FLAG
    GetPosition after reading
    Verify ending position in TIME_BYTES
    GetPosition after reading
    Verify ending position in TIME_SAMPLES
    GetPosition after waveInReset
 
Case 31: Record and play test
(Record into three four second buffers and play back.)
 
Case 32: PASS:Record and Play: 128 <2K buffers

Case 33: Record and play: one second buffers
(Record into twelve one second buffers and play back.)

Case 34: Record and play: one 900K buffer

Case 35: Record and Play: 0 and 1 size buffers:
    waveInPrepare buffer size 0
    waveInAddBuffer 1 size buffer
    waveInAddBuffer buffer with dwBufferLength == 0
    waveOutPrepare buffer size 0
    waveOutWrite 0 size buffer
    waveOutWrite buffer with dwBufferLength == 0
    waveOutWrite 1 size buffer

Case 36: Test CPU Consumption:
(This test gives a rough estimate of CPU percentage required to play
 a wave file.  Note that running other tasks in the background can
 influence this test.  Also note that long.wav must be 11 seconds of data.)

Case 37: Test Actual Play Time:
(This test estimates how long it takes a wave driver to play a long.wav -
 which must be 11 seconds of data - and compares that time to the ideal
 time to play the WAV data of that length and format.  The test "fails"
 if the difference rounds to greater than 1 percent.  Variations in 
 actual playtime can affect timing sensitive applications.)
 
Case 38: wave in WM callback:
(This test waits for appropriate window messages)
 
Case 39: wave in task callback:
(This test waits for task signals)
 
Case 40: wave in DLL callback:
(This test waits for appropriate DLL messages)
 
Case 41: wave out WM callback:
(This test waits for appropriate window messages)
    Writing (2 2K) prepared buffers...
    Writing (2 2K) prepared buffers, then Reset()
 
Case 42: wave out task callback:
(This test waits for task signals while playing a .wav file)
 
Case 43: wave out DLL callback
(This test waits for appropriate DLL messages while playing a .wav file)
    
Case 44: waveOutGetPlaybackRate:
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
        Call before playing
        Call while playing
        Call after playing
        Call after SetPlaybackRate to 0x00011111 
 
Case 45: waveOutSetPlaybackRate:
(Test will fail if waveOutGetPlaybackRate does not return the exact playback
 rate value passed in by waveOutSetPlaybackRate.)
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
        Call before playing
        Call with minium rate (0), while playing
        Call while playing
        ASYNC: Call while playing, 0x000FFFFF
        ASYNC: Call while playing, 0x00010000
        Call after playing, 0x00011111
 
Case 46: waveOutGetVolume:
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
        if left/right volume supported:
           Call while playing, 0x7FFF0000
           Call after playing, 0x00020002
        else
           Call before playing, 0x00007FFF
           Call after playing,  0x00000002


Case 47: waveOutSetVolume:
(Test will fail if waveOutGetVolume does not return the exact volume
 value passed in by waveOutSetVolume.)
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
    	Call before playing 0x00000000
        if left/right volume supported:
           Call while playing, 0x7FFF0000
           Call after playing, 0x00007FFF
           Call after playing, 0x00020002
        else
           Call before playing, 0x00007FFF
           Call after playing,  0x00000002
          

Case 48: waveOutGetPitch:
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
        Call before playing: verifies Pitch = 0x00010000 
        ASYNC: Call while playing
        Call after SetPitch to 0x00011111; verifies pitch was set


Case 49: waveOutSetPitch:
(Test will fail if waveOutGetPitch does not return the exact volume
 value passed in by waveOutSetPitch.)
    if device does not support:
	Call when not supported 
    else:
        (POLLS 'DONE' BIT)
        Call before playing, Ox00090101
        Call before playing, Ox00020000
	ASYNC: Call while playing,  0x00000000
	ASYNC: Call while playing,  0x00010000
        Call after playing,  0x00087FFF
