MGL is a simple but powerful general purpose graphic library. It is developed for NIMH ML, but can be used for other applications.
rect: [left top right bottom] in Windows's coordinate system
pos: [left bottom width height] in MATLAB's coordinate system
In MGL, 'rect (or rectangle)' and 'pos (or position)' both indicate a rectangular area on the screen. However, they use different coordinates systems and have different formats. In Windows coordinates, the top-left corner of the screen is [0 0] and x & y increase as the position moves towards the bottom-right corder. In MATLAB coordinates, the bottom-left corner is [0 0] and x & y increase as the position moves towards the top-right corner. 'pos' can be converted to 'rect' with the Pos2Rect function of MGL.
bitmap: Y-by-X-by-3 (RGB) or Y-by-X-by-4 (ARGB)
movie: Y-by-X-by-3-by-N or Y-by-X-by-4-by-N (N: number of frames)
'bitmap' and 'movie' are a double or uint8 matrix of value in the range of 0 to 255. In case of a double matrix, its value can be 0 to 1 as well. Y-by-X-by-3 is MATLAB's format for RGB data. Y-by-X-by-4 is the format for ARGB data that MGL uses (the first color pane is the alpha channel). You can create an ARGB matrix by combining your own alpha data with RGB. Reading a PNG file with mglimread returns an ARGB matrix as well, if the image file contains transparency information. Also, an ARGB matrix can be saved as a PNG file with mglpngwrite.
color: [edgecolor; facecolor] % 2-by-3
[NaN NaN NaN; facecolor] % no outline
[edgecolor; NaN NaN NaN] or [edgecolor] % open shapes
In MGL, the 'color' argument is a 2-by-3 matrix. The first row is edgecolor and the second row, facecolor. If facecolor is not necessary, the second row can be omitted. [NaN NaN NaN] indicates a transparent color.
screen: 1 (subject screen) or 2 (control screen)
count = mglgetadaptercount
[width,height,refresh_rate] = mglgetadapterdisplaymode(adapter_no) % adapter_no: 1 to count
info = mglgetadapteridentifier(adapter_no)
rect = mglgetadapterrect(adapter_no)
mglcreatesubjectscreen(adapter_no,color) % Do not use the adapter_no of the current screen
mglcreatecontrolscreen(rect,bg_color) % Need to create the subject screen first
mgldestroycontrolscreen % Destruction is in the opposite order
mgldestroysubjectscreen
Do not use the adapter number of your current screen (typically, 1), when creating the subject screen. If you do, the created screen will cover the entire viewing area, including the MATLAB command window. For precise timing control, the subject screen (and the control screen) does not process Windows messages. The only way to close the subject screen is to call the mgldestroysubjectscreen function (or shut down MATLAB).
It is not required to create the control screen, but, to do so, the subject screen should be created first. When destroying them, the order is opposite. Destroy the control screen first and then the subject screen.
While working with the created screens, you may observe that the windows of other applications do not behave well. They may become blurry and not respond to user input. These effects occur because MGL screens do not process Windows messages and therefore interfere with other applications. To fix that, just destroy the created screens and recreate them.
id = mgladdbitmap(filename); % or mgladdbitmap(bitmap);
id = mgladdbox([edgecolor; facecolor],[width height]);
id = mgladdcircle([edgecolor; facecolor],[width height]);
id = mgladdline(color,max_vertex); % and mglsetproperty(id,'addpoint',[x1 y1; x2 y2; ...]);
id = mgladdmovie(filename); % or mgladdmovie(movie);
id = mgladdpie([edgecolor; facecolor],[width height],start_angle,central_angle);
id = mgladdpolygon([edgecolor; facecolor],[width height],[x1 y1; x2 y2; ...]);
id = mgladdtext(string);
id = mgladdsound(filename); % or mgladdsound(y,fs);
These functions add a graphic/sound object and return its object id. The id is necessary to change the properties of the object. If you lose the id, try mglgetallobjects.
[id,type,status] = mglgetallobjects; % type is the object type and status is the active status.
mgladdbitmap accepts a filename (*.bmp) or a bitmap matrix.
In mgladdline, max_vertex is the maximum number of vertices that the line segment can have. The vertex coordinates (in Windows pixel coordinates) must also be set using mglsetproperty.
The file type that mgladdmovie can accept is *.mp4, *.avi or *.mpg.
The vertex coordinates of mgladdpolygon should be normalized to 0 to 1 in both x and y.
mgladdsound can read wave files (*.wav) and mp3 (*.mp3) or take the arguments of y and fs. y can be a column vector (mono sound) or a matrix (multichannel sound). fs is the frequency.
mglsetproperty(id,'property1' ,value1,'property2' ,value2,...);
'active': All MGL objects have the 'active' property, which determines whether the object will be rendered/played.
'origin': All graphic objects, except LINE, have the 'origin' property. The 'origin' is the coordinates of the object center (in Windows pixel coordinates).
'edgecolor' and 'facecolor': GDI objects (BOX, CIRCLE, PIE and POLYGON) have these properties. PIE additionally has 'startdegree' and 'centerangle'.
LINE has 'addpoint', 'color' and 'clear' properties. The 'clear' property doesn't require a value.
TEXT has 'fontface','fontsize' and 'color'. In addition, TEXT has many properties that do not require a value, such as 'normal', 'bold', 'italic', 'underline', 'strikeout', 'left', 'center', 'right', 'top', 'middle' and 'bottom'
For the entire list of supported properties, see mglsetproperty.m.
mglrendergraphic(frame_no) % Static images are not affected by frame_no. It is for movies.
mglpresent % Show rendered stimuli on the screens
mglplaysound(id) % id is always larger than 0. 0 indicates all objects.
mglstopsound(id)
mgldestroygraphic(id)
mgldestroysound(id)
You must destroy the objects that you created, to avoid memory leak. All graphic objects are also destroyed together, when either the subject screen or the control screen is destroyed.
mglgetproperty(id,'property' )
mglgetscreeninfo(screen)
mglclearscreen(screen,color)
mglsetscreencolor(screen,color)
mglsubjectscreenexists
mglcontrolscreenexists
[inVB,scanline] = mglgetrasterstatus
mglwait4vblank(state,screen) % state - 0 (return when not in VB), 1 (return when in VB)
mglkeepsystemawake(state) % state - 1 (stay awake), 2 (normal), [] (return the current state)
mglimread
mglimresize
mglimage
mglpngwrite(argb,filename)
GetMonitorPosition % in MATLAB's coordinate system
Pos2Rect % from MATLAB coordinates to Windows coordinates
See mglgetproperty.m for available properties of each object type.
The difference between mglclearscreen and mglsetscreencolor is that the latter does not clear the screen. Call mglrendergraphic and mglpresent manually to clear the screen.
mglimread, mglimresize and mglimage are similar to their MATLAB equivalents (imread, imresize and image) but can handle MGL's ARGB matrices.
mglpngwrite saves MGL's ARGB matrix as a PNG file with transparency information.