Initial setup

  1. Add the mgl directory to your Matlab path. In Matlab:
    >> addpath(genpath('MYPATH/mgl'));

    where MYPATH should be replaced by the path to your version of mgl.

  2. Make sure to enable access for assistive devices so that you can use the function mglGetKeyEvent, mglGetMouseEvent, mglPostEvent, mglSimulateRun and mglEatKeys.
  3. There are a few functions (mglEditScreenParams and mglDoRetinotopy) that require the mrTools GUI functions to be installed. To use those functions, you will need to install mrTools

Test your setup

You can see what functions are available by doing (in matlab):

>> help mgl

You can also run the function mglSystemCheck which will give you warnings if it detects any problems. If there are no problems it will just return true, so should look like the following:

>> mglSystemCheck

ans =


You may also wish to try the mglTest programs (e.g. mglTestDots, mglTestTex, etc….).

If these functions don't work you might try checking here for some issues that come up with compatibility (for example r2016a has a fix).

You may need to recompile. This may especially be necessary if you are running an older version of matlab (we run Matlab version >= R2013a 8.1 on Mac OS >= 10.10.2 as of this writing, 3/10/2015). We have found that mex files created on Matlab 7.3 do not run on matlab 14.1 for instance (if you run -nojvm you will see that it complains that it cannot find a dynamic link library for the mex functions – if you run with the matlab desktop it will just crash the system). If this happens to you simply recompile and you should be good to go.

What is in the mgl distribution

  • mgl/mgllib: The main distribution that has all functions for displaying to the screen.
  • mgl/task: A set of higher level routines that set up a structure for running tasks and trials. Relies on functions in mgl/mgllib. You do no need to use any of these functions if you just want to use this library for drawing to the screen.
  • mgl/utils: Various utility functions.

GNU General Public License

These programs are free to distribute under the GNU General Public License. See the file mgl/COPYING for details.

Recompiling mgl

If you are running into an obvious error like a segmentation fault, then you may want to recompile. The command to recompile is:

» mglMakeMetal(1);

If you run into any problems with mglMakeMetal, you may want to restart matlab and try again.

The mglMakeMetal command simply runs mex on all the .c files in the mgl/mgllib directory – you can do this by hand (e.g. mex mglPrivateOpen.c), if you prefer.

Note that this requires mex to be setup properly on your machine. On a Mac OS X machine, at a minimum you will need to have the apple developer tools installed (XCode) On linux, you will need a compatible version of gcc (older versions of gcc can be found here).

See here for more help on compiling.

If all else fails, how to get back control over the display?

If you can't do mglClose, you can always press:


this will quit your matlab session as well. You may also have to hit the <ENTER> key a couple of times to actually quit matlab.

Also, some of our test programs will run until you hit the <ESC> key (e.g. testExperiment), so it is worth trying that as well.

Compatibility with latest MAC OS and Matlab versions

We stay reasonably up-to-date with OS and Matlab versions. As of this writing (8/2023) we are using MGL on Mac OS 13.5 (Ventura) and Matlab 2023a.