DMDX Help.


Test Modes

    DMDX has various test modes, turned on with the <TestMode> parameter and frame option. The value of this keyword selects which test is to be activated. Test modes that gather data now dump their display to the diagnostics.txt file and also the job's data file when the test mode changes or when the job is stopped.  The introduction in later versions of DMDX has a test mode section that's got several of the more useful of these built into it.  Current tests are:

0Turns off any test mode.
 
1Turns on the Display Test Mode. When DMDX is waiting for a request and there is no active display it displays a test screen with information about how well DMDX is keeping track of the vertical retrace.  Contains the same sort of information as the TimeDX Time Video Mode display. Here's a display from version 6.1.5.4 of DMDX:

Millisectime 17880.18 - Video Retraces 1071
msecs/retrace 16.690
Timed out 0 (not 1071) - Multiply timed out 0
Critical errors 0
Most recent critical error 0 ticks
Biggest critical error 0 ticks
Late Present critical errors 0
Most recent Late Present critical error 0.00ms
Biggest Late Present critical error 0.00ms
Retrace tracking is relentless

First off you've got the number of milliseconds since the item file commenced execution and the number of retraces that have occurred followed by those two divided that should be close to the actual retrace time.  After that are the number of timed out retraces where DMDX has missed the raster and in brackets the number of times it hasn't (this is useful below when a lot of timed out retraces occur in determining whether any retraces are being correctly detected) and the number of times two timed out retraces have occurred next to each other (while not an actual error some cause for concern).  Then the biggie, the critical error count where DMDX has repeatedly lost track of the raster to the point where it's had to stop and go specifically detect it and if a time critical frame were to be displayed then it would be late. Following the count of critical errors there's the size of that error and if there's a lot of them going down the size of the largest of them.  Following that are errors where the routine that's responsible for displaying 3D scenes has returned too late for the display to have occurred on time followed by the sizes of the most recent and the largest of them (if you're using the legacy DirectDraw renderer then those will be Flip times and counts).  And after that is an indication whether DMDX has been locked out by the 3D chipset freaking out from DMDX relentlessly polling the raster status as certain machines are prone to do.   And here's a machine that's resorted to relaxed raster tracking (actually it's me tripping the code manually because I've never actually had one of these machines to probe):

Millisectime 38572.79 - Video Retraces 2311
msecs/retrace 16.689
Timed out 1213 (not 1098) - Multiply timed out 786
Critical errors 0
Most recent critical error 0 ticks
Biggest critical error 0 ticks
Late Present critical errors 0
Most recent Late Present critical error 0.00ms
Biggest Late Present critical error 0.00ms
Retrace tracking is relaxed (every 2 ms)

Here you can see that with the relaxed raster tracking DMDX is missing a lot of retraces and the "not timed out" field is showing is that indeed 1098 were correctly detected -- while not so much of a concern here where the relaxed raster tracking is only sleeping for 2 milliseconds it's much harder to detect whether any retraces are being correctly detected when it's sleeping for 8 milliseconds when the count of timed out retraces is almost as high as the retrace count and they're both ripping along at around 60 counts per second.  Assuming DMDX keeps getting blocked by the failing 3D chipset once the sleeping interval exceeds half the retrace interval DMDX will just switch to simulated raster tracking and that message will change to:

Retrace tracking is relaxed and now simulated

 
2Turns on the Millisecond Callback Latency test. When DMDX is waiting for a request and there is no active display it displays a test screen with information about the millisecond callback latencies. Currently a particular routine, called millisec() should be called by the OS every millisecond, it is responsible for polling input devices and turning clocks on and dispatching sound event related tasks. Win32 not being a real time OS this does not in fact occur at exact millisecond intervals and can in fact have large latencies, this test mode allows one to see exactly what latencies are involved. The latencies reported by this test measure the error in polling the PIO12 and Joystick (and RawJoystick) input devices (amongst other things) and not interrupt driven devices like the keyboard or the mouse (see testmode 6).
 
3Functionally equivalent to test mode 2 but it only monitors millisecond callback latencies while the display is active.
 
4Turns on the DirectDraw Sleeping Interval test. Prior to DMDX flipping the display so the next display buffer becomes visible the vertical retrace routine sleeps for as long as it calculates that it is safe to sleep for to allow the movingimages() routine to move something into the last display buffer to deal with situations similar to the tachistoscopic acid test (many single tick frames) as there is no other time under those circumstances to move those displays. This test measures whether the machine is in fact sleeping for the requested amount of time as a sleep here of longer than intended would generate a display error.  Test is superfluous and generates no data using the 3D rendering path.
 
5Functionally equivalent to test mode 2 but it only monitors millisecond callback latencies while DMDX is waiting for an input.
 
6Turns on the Positive Response Latency test.  This test and others like it require external hardware to close a key contact on a regular basis. When DMDX is waiting for a request and there is no active display it displays a test screen with information about the positive response latencies. This test was designed to enable us to measure the variability (if any) induced by the OS by measuring the keyboard autorepeat keystrokes, however due to the fact that DirectInput filters a keyboard's autorepeat keystrokes the test looses most of it's use (grrr). If you build a circuit that closes a switch on a regular basis you could see what variability (if any) is present in RTs from various devices (see Input) without having to trigger things from the CRT thus eliminating a small source of variability. If you use the PIO12 input device it's inter-trial polling interval should be set to every millisecond (instead of every ten milliseconds) with <id pio12 1,1>.

It should be noted that test mode 6 is an extreme worst case scenario as a new frame is being displayed as soon as the previous is assembled (on most machines this would be every other tick), a more realistic test is to use test mode 8 on items similar to those used in your experiments.
 
7Functionally equivalent to test mode 6 but it only monitors positive response latencies while the display is active.
 
8Functionally equivalent to test mode 6 but it only monitors positive response latencies while DMDX is waiting for an input. In order to make this test mode have any meaning at all DMDX will never actually see a response, it will simply record the latency data.
 
9Functionally equivalent to test mode 6 but it stores RTs instead of positive response latencies. This is designed for use with a phototransistor triggering off a white display some fixed number of ticks after the clock is turned on that is hooked up to some response device allowing a real world test of latency and variation of different response devices. The test only stores positive RTs (ie, correct ones) should someone ever want to use the test for another purpose.

Interestingly these days with the advent of the inpout32.dll support in TimeDX's PIO test if you have an LPT1 device in your system you can use the LPT's peculiar feature of reading back what was last written to it's data port to build a test mode 9 script when you configure the device to read back the data port with "inpout32.dll 378 378" for instance.  Test mode 9 can also be used to measure the audio capture latency.
 
10 Input Device button monitoring.  With TestMode 10 active any new input devices will list all their buttons in the diagnostics (both on screen and in diagnostics.txt), any button mappings in the item file will be listed and as buttons are pressed their names will be listed.  Along with the human readable name the decimal values of each character in the button name are listed to facilitate debugging any weird font issues.  As of DMDX version 5.1.3.0 the GUIDs of the devices DMDX sees and attempts to use are displayed as well.  In version 6.1.2.20 the names of devices and buttons were encoded in UTF-8 regardless of whether the Unicode option was in effect or not resulting in mojibake somewhere in the diagnostics when special characters were part of device and button names.  This is fixed in 6.1.2.21 and later.
 
11 Turns on wire frame rendering when using the 3D rendering path when used in the body of the item file, otherwise when used in the parameters (an accidental effect that turns out to be handy) it just overrides the background fill color thus showing the contents and size of textures presented (otherwise they're against the same color fill and you can't tell just how much of the screen DMDX is manipulating).  Similar to the alternate display in the TimeDX Video Mode Selection test and the Digital Video test turning test mode 11 on will render the background as gray and only the edges of the triangles containing the DMDX display will contain the display they would have.
 
12Monitors duration of millisecond callback, should always be 0.0ms or at worst 0.1ms. This is a useful test when using InstalCal drivers and the QPIO12 input device as the polling of the devices is done in the callback. If the duration of the callback rises nastily when using QPIO12 only polling every other millisecond should be considered (see <id>). Fortunately all machines tested so far have negligible values in this test.
 
13 Turns on the Present() time test when using the 3D rendering path. When DMDX is waiting for a request and there is no active display it displays a test screen with information about the time the Direct3D function Present() took to setup the next frame's display.  These should never be more than a few milliseconds and if one is in the order of or longer than the refresh rate there should be a corresponding display error thrown.  If used with the original DirectDraw rendering path times will be the time spent calling Flip() till it actually flipped the display.
 
14Turns on the vid_int() Latency test. When DMDX is waiting for a request and there is no active display it displays a test screen with information about the vid_int() latencies measured from the end of the last vid_int() call to the next so it excludes Present() times from being added to them. This test is primarily designed for testing the freesync mode of the vertical retrace frame scheduling code.  Currently a particular routine, called millisec() should be called by the OS every millisecond, when freesync mode is active it is responsible for signaling the retrace code as the retrace is no longer being independently tracked and firing off calls to vid_int() after each retrace.  This test measures how accurately DMDX will be able to present a display for the requested millisecond duration when using the freesync video modes.
 
15 Similar to test mode 14 but it includes time spent in vid_int() as it measures time from one vidint() call to the next.  While the millisecond time and the vid_int() calls  should track together vid_int() is responsible for firing off requests to Present() (among other things) and this can take more time than I'd like to be blocking the millisecond code for.  Testmode 14 combined with this test allows us to see the difference Present() is making.
 
16  Turns on the Retrace to Renderer Exit Latency test mode. Similar to test mode 13 but it measures time from the last retrace to the time the rendering routine (be it Present() or Flip()) returns control to DMDX, said times should be less than the retrace interval.  This test is a double check for DMDX's timed out and critical error counts.
 
17  Turns on the Requested Retrace Thread Sleep Time test mode.  When DMDX is waiting for a request and there is no active display it displays a test screen with information about the time the retrace thread asked to sleep for.  After the retrace thread has called DMDX's vid_int() routine to see if anything needs to happen on the display queue it examines the time to the next retrace and goes to sleep for a bit to let other processes have some CPU cycles.  Times displayed are real however they're actually integers and should be less than the retrace interval minus whatever time was spent calling Present() or Flip() less a bit more that the thread uses to test if the retrace is active.  Times can be negative in which case there wasn't enough time to sleep, degree of negativity shows just how much in arrears things were.  This test is a double check for DMDX's timed out and critical error counts.
 
18  Reserved.
 
19  Turns on diagnostic running in DMDX 6.1.5.1 where item numbers are used as RTs.  Normally one would just check the diagnostic run check box however if you're running your item files from the command line when using a batch file to control the run as is done with remote testing this is about the only way to turn diagnostic running on.  Of course you have to edit your item file before you pass it off for running subjects, this is for proof of concept stuff as opposed to final run time testing -- although I guess you could use macro S and a subject ID and if it's say zero diagnostic mode is enabled otherwise it gathers data...
 
20  Similar to test mode 19 this turns on diagnostic running as well as diagnostic branching in DMDX 6.1.5.1 where item numbers are used as RTs and branches are taken.
 
21  Forces all frames that result in a display to throw display errors in DMDX 6.1.5.1.
 

    Example scripts using these test modes are on the server and there's also one in the TimeDX help and there are three tests utilizing test modes 1, 2 and 13 built into the introduction so you don't even need anything except a recent copy of DMDX.EXE to test a machine.


Safe Modes

    DMDX has three safe modes, turned on with the <SafeMode> parameter and frame option. Prior to version 6.1.3.0 of DMDX any safe mode had the added effect of displaying the item in the diagnostics as the drawing routines saw it with the RTF control codes left in (the way all versions prior to 0.20 always displayed it), this capability has now been moved into it's own safe mode. Current modes are:

0Turns off any and all of the safe modes.
 
1Turns on the ESC check safe mode. If DMDX is latching up and hitting ESC is unable to wake it up this safe mode increases the frequency with which DMDX polls for the ESC key being hit and the criteria under which it will stop a job; for instance, it will respond to ESC while the display is still active -- which is normally not a good thing as the "Abort the Job" message could be overwritten with the next display frame (fairly sure when the Direct3D renderer is in use as occurs with later OSes this can't happen), however if your item file has an infinitely long frame in it setting this safe mode beforehand is the only way to stop the job.
 
2Turns on the RTF control word removal override safe mode in DMDX 6.1.3.0.  Normally DMDX will remove RTF control words from the display frame text when they are displayed in the diagnostics and if the Unicode option is in use it will mark frame text up to UTF-8 so the diagnostics contain a reasonable facsimile of the actual displayed text however if you're trying to debug some weird RTF problem using safe mode 2 and seeing the actual RTF control words has it's advantages.
 
3 Turns on the ALT-TAB recovery safe mode in DMDX 6.1.5.0.  Normally when DMDX recovers from ALT-TAB or some other application stealing the focus the user will be presented with a blank screen and they will have to request a new display if the job isn't running in continuous run mode (if it's running continuously it will start with the next item or the one after), with safe mode 3 active DMDX will redisplay the last item executed instead.  If an item was gathering an RT at the time of the ALT-TAB the item will be presented over again (even if it got as far as feedback) so you could see duplicate RTs following a display error about the focus being lost and then the first response timed out (it should have an ABORTED message) followed by a second one that will likely be a good RT.   While the general idea is to have DMDX's display resume with what was on the screen before the focus shifted there are circumstances where it can't do so, that includes items with skip display CR indicators like the introduction has where there's all sorts of fancy branching and what not going on nor will items that have not erased the previous display (as in sentence reading tasks using <cpx>) redisplay what those items had preserved from previous items.  What will happen is that something will be displayed -- unless you have items that display a blank screen of course...  Safe mode 3 also effects declining to abort a job after ESC is pressed as the display surfaces are similarly lost then. 

This works best with the Direct3D renderer, using the legacy DirectDraw renderer bits of old displays can flicker onto the screen for a moment and sometimes a bit of the next item might be displayed for a fraction of a second but there are no big problems -- not once I restructured the logic to work with both renderers anyway -- although if you hit ESC and decline to abort and then use ALT-TAB you can wind up with a blank screen, I'm not going to address it as it's a really unlikely scenario that doesn't occur with the Direct3D renderer.
 




DMDX Index.