MATLAB Programming/Psychtoolbox/OS X FAQ

This section contains a number of questions about details of implementation of OSX. Being a wiki, you are encouraged to add your problems to these questions and your insight to these answers...

FAQ
Q: What is the difference between a texture and a window and a screen?

A: A screen corresponds to a physically connected display device. Screen 0 is the display with the Dock and menu bar. Screen 1 (on a dual-display system) is the 2nd display, and so on... The Screen('Screens') command returns a vector of all available screens - the available, connected and powered on display devices. If you have a dual-display setup whose displays are switched into mirror-mode (both displays show same content), then this will appear to PTB as a single screen. The screen-number just defines on which physical output device you want to open/show your stimulus window.

An onscreen-window is used to display your stimulus. Each screen can have exactly one full-screen onscreen window - or no PTB window at all. All drawing commands expect a handle to an onscreen window so they know where to draw to.

Onscreen windows are double-buffered: They consist of a backbuffer and a frontbuffer. The backbuffer is, where all drawing operations are performed -- where you build/prepare your stimulus for presentation. The frontbuffer is scanned out and displayed by your display - your beamer, flat-panel or CRT at the display refresh interval.

After you've finished drawing and your stimulus image is ready in the backbuffer, you issue the Screen('Flip',...) command. This command asks PTB to switch the role of the front- and back- buffer at the next vertical retrace of your display device. This way, the former backbuffer becomes the new frontbuffer and your new stimulus gets shown to the subject. The former frontbuffer becomes the new backbuffer and is ready for drawing the next stim. As the bufferswap is synchronized with vertical retrace and always happens in less than 1 microsecond, you'll get perfect, flickerfree, tearfree stimulus presentation timing, regardless how long drawing takes -- Unless obviously you try to draw something too complex in a too short period of time. The important point is that Flip decouples drawing (with its timing variabilities) and actual stimulus presentation - something not possible in the MacOS-9 and Win toolboxes.

Offscreen windows are the same as Textures in the Psychtoolboxes released since 2006. Internally they are the same thing, so you can always use a Psychtoolbox texture where you would use an Offscreen window and an offscreen window where you would use a texture. They only differ in creation and performance: Textures are created by Screen('MakeTexture') from a Matlab image matrix or automatically by the Quicktime movie playback engine or the videocapture engine. Creating them is very fast and efficient. They are also optimized for fastest possible drawing. Offscreen windows are created by the call Screen('OpenOffscreenWindow'); - they are initialized with a selectable size, color depth and initial uniform color, not with image content. They are optimized for fast drawing *into* them - Each Screen drawing command can not only draw to onscreen windows, but also into offscreen windows. After creation, they are (nearly) synonymous.

E.g.:

Say you have a image matrix I in Matlab, e.g., created via I=imread('myimage.png'):

Then:

tex=Screen('MakeTexture', win, I);

is the same as:

tex=Screen('OpenOffscreenWindow', win); Screen('PutImage', tex, I);

in, just that the former is much faster than the latter. The advantage is also that the Screen('DrawTexture') command allows to scale, zoom, filter and rotate textures while drawing, that texture drawing is extremely fast as it uses specialized hardware on your graphics card, and much more...

Q: How do you create a duplicate of an offscreen window?

A: You would first create an empty offscreen window of the same size and color depth as your original offscreen window, then copy the original windows content into the new window:

Be origWin the offscreen window you want to duplicate, then:

duplicateWin = Screen('OpenOffscreenWindow', origWin); Screen('CopyWindow', origWin, duplicateWin);

-> duplicateWin is a copy of origWin.

Q: Is there any simpe way to set TextSize (or other such parameters) for all windows/screens?

A: No. You have to set it for each window via the Screen('TextSize', win, ...) command. But that's not much work, given that most people have at most two windows.

Q:Can 'OpenOffScreenWindow' windows have multiple buffers?

A: Nope. It wouldn't make sense to have multiple buffers.