This is an old revision of the document!


mgl 2.0

Overview

This beta version (mgl 2.0) contains cocoa based code for running under 64 bit Matlab on Mac OS X, a Windows alpha version (but not yet linux) and a number of improvements as outlined below. Everything in the mgl 2.0 beta for Mac OS X is now working. It should be 100% backwards compatible with any mgl stimulus code you wrote in the past. But, it is still a beta, so use at your own risk. Check the commit logs for recent changes. It has been running on Mac OS 10.6 and versions of Matlab up to 7.9.

New Features

  • Nanosecond precision keyboard/mouse timestamps The functions mglGetKeyEvent, mglGetMouseEvent now return timestamps that have nanosecond precision (and not 1/60 second precision as before). Of course, this is just what the OS reports, there is no guarantee that the hardware & software delays will actually give nanosecond precision, but really people, this is good enough for psychophysics. Make sure to enable access for assistive devices.
  • Transparent windows For mglOpen(0) you can display a transparent window by passing in a value greater than 0 and less than 1, e.g. mglOpen(0.7); What is this good for? Uhm, it makes your desktop less cluttered when you are debugging your stimulus code? I dunno, give me a break. I like transparency.
  • mglPostEvent and mglSimulateRun These are functions that can create keyboard events at a specified time, so that you can test your stimulus program with periodic backticks (like from the scanner) or simulated subject responses. See here for more info.
  • mglEatKeys This is a function that allows you to remove key events from the system event queue. This is useful so that you don't get a lot of backticks or 1's and 2's in the matlab command window. Also if keyboard focus is on your full screen mgl window, it will prevent the annoying bonk sound that occurs on some systems. The key events are still accessible to your stimulus program through mglGetKeyEvent. See here for more info.
  • mglResolution Get and set the resolution of displays. See here for more info.
  • mglMovie Available on 64bit Mac Matlab only. You can use it to display quicktime movies. It is possible to arbitrarily position and size the movie, play, pause, hide, show, and grab a frame into a matlab matrix among other things. Also, if you are running the Matlab desktop you will only be able to use it for windowed contexts (i.e. mglOpen(0)) since the full screen contexts use CGL instead of Cocoa. See here for more info.
  • Dereferencing MGL global There are now two functions mglGetParam and mglSetParam that should be used to get and set MGL globals like verbose.
  • mglCharToKeycode Has an optional argument that allows it to return all keycodes that match a given character instead of just the first one.
  • code The mex code for mgl has been cleaned up to make it easier to distinguish the os-specific code. All os-specific code has been clearly marked with easily visible comments. Where appropriate os-specific code has been made into functions to make it clear what the inputs and outputs of the os-specific code are.
  • compiling The default is to compile for Cocoa. You can override this by doing mglMake('carbon').
  • Windows Chris Broussard has begun work on a windows port. It is still in alpha but has basic functionality implemented (open/flush/close windowed screens and ability to draw using openGL functions).
  • EyeLink Eric Dewitt and Eli Merriam have been working on mgl functions to directly interface with the SR Research EyeLink eye tracker system. See here for more info.
  • mglEditScreenParams A mrParamsDialog based gui for setting screen parameters for use with the task code. See here for more details.
  • Digital I/O using National Instruments cards You can now use NI cards to read and write digital I/O. In particular you can get the volume acquisition pulse from the magnet and the user responses as digital signals. You need to use mglMake('digio') to enable this feature. See here for more info.
  • Calculated randVars You can now specify calculated randVar variables in a task that are available in thistrial like parameters and other randVars. However, the value of these variables are saved at the end of the trial. This allows values that are generated at random during a trial or through user interaction to be saved and retrieved using the standard getTaskParameters mechanism.

Cocoa

Apple has given up support for Carbon based GUIs for 64 bit applications, so internal functions have been rewritten to use the Cocoa based interface. For those of you who don't know, Carbon is Mac's really old C API from OS 9 days and Cocoa is Mac's slick new object-oriented API which uses an extension to the C language called Objective-C. Essentially Cocoa is NextStep (and even uses NS as a prefix to most classes).

If you are interested in understanding the cocoa code, you may find the book Cocoa programming for Mac OS X by Aaron Hillegass to be helpful. Also Wikipedia has a pretty good entry on Objective-C programming.

Download

The 2.0 beta mgl can be retrieved using svn:

svn checkout http://gru.brain.riken.jp/svn/mgl/trunk mgl

To use the code, simply add mgl to your MATLAB-path:

>> addpath(genpath('mgl'));

And make sure to enable access for assistive devices so that you can use the function mglGetKeyEvent, mglGetMouseEvent, mglPostEvent, mglSimulateRun and mglEatKeys.

There are a few functions (mglEditScreenParams and mglDoRetinotopy) that require the mrTools GUI functions to be installed. If you are not already using mrTools, you can download the following:

svn checkout http://cbi.nyu.edu/svn/mrTools/trunk/mrUtilities/MatlabUtilities mrToolsUtilities

and add that to your MATLAB-path (with the correct path)

>> addpath('mrToolsUtilities');

The code has generally been precompiled for Mac OS 10.6, Matlab 7.9. If you are using an earlier version of Mac OS or Matlab, you are advised to recompile mgl:

mglMake(1);

Download with proxy-server

For non-NYU users, if your institution uses a proxy-server, you might have to set up svn to allow you to access the svn respository. Check System Preferences→Network→Advanced→Proxies and note down the name of the proxy server and port (e.g. blah.nottingham.ac.uk, port 3128). You can then edit the subversion setup file (~/.subversion/servers) in your home directory to set up rules for accessing this repository. For more details see http://subversion.tigris.org/faq.html#proxy

Here are a couple of lines from the servers text file that you can use to specify the rules for access, e.g.

[groups]
group1 = gru.brain.riken.jp

[group1]
http-proxy-host = blah.nottingham.ac.uk
http-proxy-port = 3128

Upgrading

If you are using an older version of MGL, you may want to move that directory to some other name (e.g. mglv15) before installing this version. Older versions of mgl will always be available through SVN, so it is easy to downgrade as well.

If you have an old svn repository that you downloaded from http://yoyodyne.cns.nyu.edu/svn/mgl/trunk, then you can switch to the new repository by cd'ing to your mgl directory and running:

svn switch --relocate http://yoyodyne.cns.nyu.edu/svn/mgl/trunk http://gru.brain.riken.jp/svn/mgl/trunk

Keyboard events

The functions to get keyboard and mouse events rely on a low level system called “event taps”. You need to enable this system (it is usually used as an accessibility option). For 10.9 (“Mavericks”) and later versions of Mac OS you should go to System Preferences/Security & Privacy where you should allow Terminal.app to “control your computer”

On earlier versions of Mac OS you can go to your System Preferences/Universal Access and clicking “Enable access for assistive devices”.