DMDX Help.


2D Input Device Keyword

<2DInputDevice text1 [options] text2,N1,N2,N3,N4 [...]>
<2Did text1 [options] text2,N1,N2,N3,N4 [...]>

options:
datalogging
noclick
checkoverlapping
clipcursor
cursoroff
cursoron

built in devices:
mouse
windowstouch
tcpipreply,xfieldname,yfieldname,validstring


    Parameter to select an input device as 2D input, ie a touch screen. text1 must be the name of an existing installed DirectInput device that has been calibrated by the TimeDX input test (unless it's "mouse""windowstouch" or "tcpipreply", see below). Once a device is selected there is no way to deselect it without starting a new item file (which can be done with the chain keyword), you can however unmap all the devices' buttons with <UnMapButtons>.  Names with spaces in them must be in quotes.  As of DMDX 3.2.0.0. there a number of options that can follow  text1, notably datalogging, noclick, checkoverlapping, clipcursor, cursoroff and cursoron detailed below.  The  text2 is the arbitrary name for a region on the screen that will generate a response of that name (with added + and - symbols when hit or released) where N1 is the left most coordinate of the region,  N2 the top most, N3 is one more than the right most and N4 one more than the bottom (ie, a standard windows RECT structure).  text2 must begin with a non-numeric character.  text2,N1,N2,N3,N4 will need to be repeated for each possible region of the screen that will be used as an input throughout the whole item file.   N1,N2,N3,N4 can be real as per the graphics keywords assuming a video mode has already been specified.  If regions overlap the first defined region that matches the 2D coordinates is used (although checkoverlapping changes this, see below).  Coordinates of this RECT structure can be updated as the item file runs with <setbuttonrect> should your buttons move.  In the following example even though the bottom input (specified in absolute coordinates whereas the others are fractional merely for demonstrative purposes) is totally overlapped it still catches touches in the bottom third of the screen:

<vm 1024,768,16,60> <2did "magic touch usb" bottom,0,512,1024,768 left,0,0,.5,1 right,.5,0,1,1> <mpr +right> <mnr +left> <mr +bottom>

    One problem is devices having cute little symbols as part of the name making it very hard to get the name of a device into an item file.  To combat this DMDX dumps the names of available input devices into the diagnostics, not only that it also checks a parsed version of the name that has unusual characters removed from it that is also printed in brackets.  Turning test mode 10 on helps too as it will dump names of all devices and buttons on them as well.

 

Built in devices:

    There are a few special built in devices for 2D input and the first of them is the mouse device.  These built in devices don't connect to any DirectInput device nor do they need calibration in TimeDX (not that you could calibrate the mouse anyway as it has relative axes and the calibration routines only handle devices with absolute axes).  Instead the mouse taps into the windows mouse messages, both left and right clicks generate the same button press.  Because the mouse gets it's data from windows messages and those messages can get aggregated timing isn't going to be real accurate but as far as I can tell the whole pointing paradigm is alien to RTs in any event.  The mouse also turns the cursor on seeing as it's kinda hard to use a mouse to point at things unless there's a cursor...  Turning on DMDX's <MinSleep> option to maximize processing of the mouse system messages may increase RT accuracy of this special device.  Also note that the mouse device doesn't work real well with multiple monitor setups unless you're using the Direct3D rendering path.  When I wrote the code I assumed no one would ever need that but there you go.  The solution when using the classic DirectDraw renderer is to set the video card to clone mode where the two displays are copies of each other.  It's also possible setting a clipcursor region (below) in desktop coordinates might enable the mouse to be used on a second display.

    There second built in device is the windowstouch device added in version 6.0.0.0 of DMDX.  Like the mouse device this device doesn't need calibration in TimeDX instead it  is calibrated somewhere in the Windows Control Panel.  Like the mouse the windowstouch device gets it's data from windows messages, specifically WM_TOUCH messages, however because it's dealing with isolated touches of the screen I suspect the timing of this device is much better.

    The third built in device is the tcpipreply device added in version 6.1.2.0 of DMDX.  This device does not need calibration in TimeDX as it is presumably calibrated elsewhere in the eye tracker software (or what have you, anything that talks line based ASCII TCP/IP can talk to the tcpipreply device).  The 2Did tcpipreply device parses data  from a TCP/IP reply setup with the <InputDevice> parameter and is thus unique needing both an <id> parameter and a <2Did> one.  The tcpipreply device has to be told the names of the fields that contain the data it uses so it must be followed by three strings as in tcpipreply,xfieldname,yfieldname,validstring.  The data in the first two fields are the x coordinate and the y coordinate from the eye tracker and can be real values between zero and one in which case they're multiplied by the relevant dimension of the screen.  In addition the device needs a particular validation string, validstring, to be present before the other fields can be considered valid and similar to the strings the <send> keyword sends it can contain '' for double quotes and ., for a semicolon.  If your device device doesn't contain a particular validation string per se pick some string that will always be present, it can be a single character.  See the <expireif> keyword help for an example of the tcpipreply device in use, typical use of tcpipreply for a Gazepoint eye tracker might  be tcpipreply,BPOGX,BPOGY,BPOGV=''1'' (so the BPOGV field is zero when the data isn't valid).

 

Options:

    The datalogging option initiates data logging with each clockon and must be followed by two parameters.  Firstly the maximum number of data points that could be gathered (not all points may be gathered in a trial, data logging terminates when a response is registered) and secondly the period between each data point gathered in milliseconds.  Data logged are the coordinates that device presented at that time and not all devices provide a continuous data stream, a lot of them only report movement information so if the device isn't being moved you won't see any data points.  Data is dumped at the end of each item on a single line in the output file in triplets of time,x,y and if you're using the "mouse" input device the times can be little wild as Windows delivers mouse movement information at it's leisure.

    The noclick option checks all data points received against the button regions so no clicking of buttons is needed.  Not all devices provide a continuous data stream so not all 2D devices can be used with noclick.

    The checkoverlapping option forces the routines that check coordinates from some device being within a given button's region to check all regions regardless of whether a match is found or not.  Normally DMDX stops once a match is found regardless of whether that region is mapped as a response or not.  Turning checkoverlapping on allows you to have multiple overlapping regions and select which one is active with the usual <mpr>, <mnr> etc. keywords instead of having to have lots of non overlapping regions and combining signals out of them (which was a pain, believe me).

    The cursoroff and cursoron options override the default windows cursor display state for that device.  Eg, if you are using the mouse device you'll need cursoroff if you don't want a cursor and you'll need cursoron for all other devices (to date anyway) if you want to see the cursor.  Note options that affect the cursor only work with devices that have drivers that affect the cursor.  This means things like touch screens and mice, joysticks won't affect the cursor (see Joysticks below).

    The clipcursor option confines the cursor to given region of the screen when using the mouse 2Dinputdevice (read: no joystick support, see Joysticks below).  clipcursor must be followed by four coordinates in the same way as a button definition (see above).  Aside from uses I haven't thought of this allows continuous ratings to be made of video and logged with the datalogging option when the region provided to clip the cursor to is one pixel high and the width of the screen as the following item file demonstrates (a similar file dvRatingsDialdemo.rtf can be found in the digital video demo):

<ep> <cr> <dfm 0.55>
s3 <vm 800,600,16,60> <nfb> <2did mouse datalogging,50,50 clipcursor,0, 525, 800, 526>
<id keyboard>
<eop>
$ 0 @-3 "The instructions", @-2 "across", @-1 "multiple", "lines" <branch 99>

mB+@14"0       1        2               3            4       5           6            7             8",

@15"    not at all/                             somewhat/                             extremely/",

@16"      none                                 some                             a great deal"+;

~99; $

+100 * <d 300> <t 4000> <dv -1,.1,.75,.75> "happy/429-53_l.mpg" <dv% 0> / ~B;
+101 * <d 300> <t 4000> <dv -1,.1,.75,.75> "neutral/485-31_l.mpg" <dv% 0> / ~B;
+102 * <d 300> <t 4000> <dv -1,.1,.75,.75> "sad/331-79_l.mpg" <dv% 0> / ~B;

$ 0 "Done"; $

     A more complicated use of the clipcursor option entails having the subject move the mouse back to the center of the screen between each rating (utilizing noclick so just positioning the cursor is enough).  Although joysticks can now do better job of this, see Joysticks below.  Note that <id keyboard> is no longer used as the request is provided by moving the mouse back to  the center of the screen:

<ep> <cr> <dfm 0.55>
s3 g2 <vm 800,600,16,60> <nfb> <2did mouse datalogging,50,50 noclick clipcursor,0,525,800,526 center,395,520,405,530> <mr +center>
<eop>
$ 0 @-3 "The instructions", @-2 "this time", @-1 "the cursor", "needs to be centered" , @16 "Continue" <branch 99>

mB+@14"0       1        2               3            4       5           6            7             8",

@15"    not at all/                             somewhat/                             extremely/",

@16"      none                                 some                             a great deal"+;

~99; $

+100 * <d 300> <t 4000> <dv -1,.1,.75,.75> "happy/429-53_l.mpg" <dv% 0> / ~B;
0 @16 "Continue";
+101 * <d 300> <t 4000> <dv -1,.1,.75,.75> "neutral/485-31_l.mpg" <dv% 0> / ~B;
0 @16 "Continue";
+102 * <d 300> <t 4000> <dv -1,.1,.75,.75> "sad/331-79_l.mpg" <dv% 0> / ~B;
0 @16 "Continue";

$ 0 "Done";

     Note also that just leaving the cursor in the center of the screen won't automatically continue to the next item as Windows only provides data when the mouse moves so DMDX doesn't see the non-moving mouse parked over the request button, a rather nice side effect.
   
Joysticks:

     Joystick drivers don't manipulate the windows cursor so users are driving blind when using a joystick in DMDX.  If visual feedback of how far a stick is being pushed is required you can load up an external driver that takes the joystick and manipulates the cursor's position with it.  When used in absolute mode the cursor will always return to the center of the screen making rating tasks automatically home on a neutral rating (assuming of course you have positive and negative ratings).  We found a nice one called Joystick Mouse Tool 1.0 that works well.  You no longer tell <2Did> to use the joystick but instead use the mouse device mentioned above with no restrictions.




DMDX Index.