Recompiling MGL

We (Apple developers) run the latest Mac OS (10.5.6 as of this writing) with the latest version of Matlab (7.6 as of this writing) or (Linux developers) Ubuntu 64-bit (Gutsy) and 32-bit (Feisty) with Matlab 7.4 and the binaries are created to run on these systems. As noted above, some older versions (notably Matlab 14.1) are not able to use these mex files and crash when you try to run mglOpen. If this happens, then all you need to do is recompile MGL using mglMake(1).

License manager timing glitch

The Matlab license manager checks every 30 seconds for the license. This can cause there to be an apparent frame glitch in your stimulus code, especially if you are using a network license (on our machines it can take ~200 ms to check for the license). The only known workaround to this is to run on a machine that has a local copy of the license. You can check this for yourself by seeing how long it takes to do screen refreshes:

 mglOpen;
 global MGL;
 checkTime = 30*MGL.frameRate;
 timeTaken = zeros(1,checkTime);
 mglFlush;
 for i = 1:checkTime
   flushStart = mglGetSecs;
   mglFlush;
   timeTaken(i) = mglGetSecs(flushStart);
 end 
 mglClose;
 plot((1:checkTime)/MGL.frameRate,timeTaken);
 zoom on;xlabel('seconds');ylabel('Frame refresh time (seconds)');

If you have the same problem, you should see one large spike in the time course like this:

<div> </div>

This one shows it taking about 65 ms. Note that you may see small deviations in which one frame takes longer and then the following frame takes shorter than the mean. These are normal flucations persumably due to multi-tasking and other events that are intermittently taking up time. As long as these are shorter than a frame refresh interval minus the time it takes you to process the stimuli for your display, you will not drop any frames. Note that in the above code, if you change mglFlush to any other command, such as WaitSecs(1/frameRate);, you will still see the big spike for the license manager check–confirming that this has nothing to do with drawing to the screen.

Function not supported on Linux

Not all functions are currently supported on the Linux platform. The list of funcitons not supported yet are:

  • mglText
  • mglTextDraw
  • mglPlaySound
  • mglInstallSound
  • mglDescribeDisplays
  • mglSwitchDisplay
  • mglListener

If you want to use text under the linux operating system, you can use mglStrokeText.

Here is a more recent update from Jonas about the Linux version:

I am in the process of upgrading the Linux version of MGL to run under Ubuntu (64-bit and 32-bit) with NVIDIA and ATI graphics cards. Although the upgrade is still incomplete, most functions work equally well under Linux at this stage. Some differences that will remain between the platforms are listed below.

  • no support for font-based text - this needs to be upgraded, I started looking into using FreeType for this which is widely available and would be easy to implement in the same texture-based way that the Mac code relies on. Care must be taken to ensure that the code is maximally portable across platforms, so it may be that some Mac-specific idiosyncracies need to be modified
  • note that the stroke text works perfectly under Linux, so unless you are very enamoured with a specific font this is a perfectly usable workaround (though some symbols, eg %, are missing currently)
  • some differences in the way you specify special keys, but this is generally to Linux' advantage - eg you can use ESC, BACKSPACE etc as names (relies on the XKeySymDef.h or sth like that)
  • timing is in general more accurate on Linux, since the clock rate is much higher on modern systems (100-500Hz vs 60Hz on the Mac)
  • no parallel port interface yet so you can't use Justin's code for calibration
  • no sound - need to decide on a standard to use that is most widely available
  • the syncing with OpenGL is idiosyncratic and depends on the graphics card. I have implemented this to use both the SGI video sync extension and the environment variable (both NVIDIA and ATI provide this option). The former is not supported by all OpenGL cards (though most modern ones) and can interact with the environment variable option, so I will make the latter the default, with an option to use the SGI extension when compiling only.

For the time being, only NVIDIA and ATI cards will be supported (because I only have access to those two machines).

  • setting screen size and resolution requires the XRandR extension, which is supported on recent X distributions (Xorg 7.0 and later). Older X servers (eg Apple's X11) won't work.
  • you need to reuse the X display or you run into memory problems, and the code for doing this needs to be checked for consistency. This is similar to the Mac window situation and relates to the uneasy relationship between Matlab and X. When you open a window, the MGL global variable will contain a window and display pointer that is used on subsequent calls; care must be taken not to clear the MGL variable between calls (once you do so, running MGL is likely to crash Matlab, even if you run clear all, which correctly closes the display).

Functions not supported on Mac

  • mglSetRandR allows you to set and get resolution and refresh rate from the command line. There is no support for Mac at present; use the Display Manager.

Opening in a window with matlab desktop (Mac only)

This issue had been resolved, but if you find you are still having problems, here is what the issue was and how to resolve it:

On Mac OS X there seems to be some interaction with having mutliple threads in the workspace that causes working within a window (i.e. mglOpen(0) as opposed to fullscreen) to be unstable. The workaround for now is not to close the window once it is opened. This seems to work fairly well. When one is completely finished working with the window, one can call mglPrivateClose to close the window. But after that, calling mglOpen(0) is likely to crash.

mglOpen(0) works fine if running matlab -nojvm or -nodesktop.

Precise timing of key press events

On Mac OS X if you want to get key press events, you can get them with a system (nanosecond precision) time stamp in the cocoa beta (see below). For the previous version of mgl you could only get them with a resolution of 1/60 second. If you are willing to sit in a loop testing the keyboard, you can use mglGetKeys and get acceptable time resolution (your time resolution will depend on how fast you poll the keyboard status). On Linux, the time resolution depends on the kernel's hard-coded HZ setting, which is usually between 100-500; the value can be retrieved (at least on Ubuntu) by typing cat /boot/config-`uname -r` | grep '^CONFIG_HZ=' The time resolution is 1/HZ sec; so on the current developer system, with HZ=250, key presses can be timed with a resolution of 1/250=4msec.

64bit Matlab on Mac OS X

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).

Everything in the mgl cocoa beta is now working. It should be 100% backwards compatible with any mgl stimulus code you wrote in the past. There are also a few improvements:

  • Events 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.
  • 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.
  • mglResolution Get and set the resolution of displays.
  • 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.
  • 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 full screen and windowed screens and ability to draw using openGL functions).

A beta for the new Cocoa based mgl can be retrieved using svn:

svn checkout http://yoyodyne.cns.nyu.edu/svn/mgl/trunk mgl

To use the code, simply add mgl to your 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.

To see a list of changes (there are continuing to be a lot of changes, so if you have checked out the beta, make sure to do periodic updates), you can check the commit logs.

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 = yoyodyne.cns.nyu.edu

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

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.

Working notes

Functions affected and status
  • mglPrivateOpen: working.
  • mglPrivateClose: working.
  • mglGetMouse: working.
  • mglGetKeyEvent: working. nanosecond time stamps.
  • mglGetMouseEvent: working. nanosecond time stamps.
  • mglCharToKeycode: working. update wiki page.
  • mglKeycodeToChar: working.
  • mglPlaySound: working.
  • mglInstallSound: working.
  • mglPrivateDescribeDisplays: working except for gammaTableWidth/Length
  • mglPrivateSwitchDisplay: working.
  • mglPrivateMoveWindow: working.
  • mglMovie: working.
Bug list
  1. Resizing window It is more stable to open a cocoa window once and then keep hiding and showing that window. For now this means that you can't resize the display. The code that I wrote to do that seems to resize the window but not the openGLView.
  2. Screen Saver When the screen goes blank because of energy saver settings the open MGL window dumps to the debugger.
List of functions to be checked with Linux

Every function with os-specific code has been touched in the beta. Generally this has been done to mark where the os-specific code is, or to break-out an os-specific function so that it is better determined what the inputs/outputs of those functions need to be. In general, I think the goal should be to have mgl compile cleanly for all functions on both platforms (if something isn't implemented, it should just print out a message that it is not implemented). I have tried to structure the code so that this will be easy to do.

  • mglGetMouseEvent This has a new interface that allows getting all events and returning event information in array rather than structure form. This is implemented in the .m file so it should just work with the linux version, but it needs to be checked.
  • mglGetKeyEvent Same story as mglGetMouseEvent
  • mglPrivateOpen Broke-out an os-specific c-function. This no longer sets the resolution and refresh rate of the monitor. That is set by mglResolution (See below). So the code needs to be slightly modified to not do this. screenWidth and screenHeight are passed for opening windowed contexts.
  • mglResolution This sets/gets the resolution and refresh rate of the monitor. It should give the same functionality as your mglSetRandR but I didn't have that function in the repository so I couldn't use it as a base for this function. (Also, I think the name is a bit confusing for non X programmers – I initially thought it was a random number generator). Should be pretty straight forward for you to put the linux specific code into mglResolution though – I have written os-specific function calls that should be pretty straight-forward.
  • mglPrivateClose Broke-out an os-specific c-function.
  • mglSetGammaTable Broke-out an os-specific c-function.
  • mglGetGammaTable Broke-out a os-specific c-function.
  • mglCharToKeycode This now has an option to return all matching keycodes rather than just the first one encoutered (so that you can get the numbers on the keypad for instance). This needs to be implemented in the mex file.
  • mglKeycodeToChar Broke-out an os-specific c-function
  • mglMovie/mglPrivateMovie This should compile and return a message that it is not implemented.
  • mglText This I almost surely broke. The break-out c-function should return the bitmap text (which the linux code already did, so it should just be a small fix).
  • mglInstallSound Should compile and give not-implemented message.
  • mglPlaySound Should compile and give not-implemented message.

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), by going to your System Preferences/Universal Access and clicking “Enable access for assistive devices”.

software/mgl/knownissues.txt · Last modified: 2009/05/01 13:32 (external edit)
www.chimeric.de Creative Commons License Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0