Docs @ Psychtoolbox Wiki : Screen

Search PTB Function help:
homepsychtoolbox.orgpage updateslogin

Screen

PsychtoolboxPsychBasic

Screen is a MEX file for precise control of the video display. Screen has
many functions.

Inside MATLAB:

Screen has many functions; type "Screen" for a list:

For explanation of any particular screen function, just add a question
mark "?". E.g. for 'OpenWindow', try either of these equivalent forms:

All the Screen Preference settings are documented together:


Contents

  1. General Screen arguments
  2. Screen Subfunctions
  3. OpenGL
  4. When you get a MATLAB error
  5. Stopping Programs
  6. Bugs


 

General Screen ARGUMENTS

common to most subfunctions of Screen:


"windowPtr" argument: Screen 'OpenWindow' and 'OpenOffscreenWindow'
both return a windowPtr, a number that designates the window you just created.
You can create many windows. To use a window, you pass its windowPtr to the
Screen function you want to apply to that window.

"rect" argument: "rect" is a 1x4 matrix containing the coordinates of an
imaginary box containing all the pixels. All screen and window coordinates
follow Apple Macintosh conventions. (In Apples the pixels occupy the space
between the coordinates. Thus a rect [0 0 1 1] contains just one pixel.)
Coordinates can be local to the window (i.e. 0,0 origin is at upper left of
window), or local to the screen (origin at upper left of screen), or "global",
which follows Apple's convention of treating the entire desktop (all your
screens) as one big screen, with the origin at upper left of the main screen,
which has the menu bar. Historically we've had two different orderings of the
elements of rect, so, for general compatibility, all of the Psychophysics
Toolbox refers to the elements symbolically, through RectLeft, RectTop,
etc. Since 2/97, we use Apple's standard ordering: RectLeft=1, RectTop=2,
RectRight=3, RectBottom=4.

[optional arguments]: Brackets in the function list, e.g. [color], indicate
optional arguments, not matrices. Optional arguments must be in order, without
omitting earlier ones, but you can use the empty matrix [] as a place holder,
with the same effect as omitting it.


 

Screen SUBFUNCTIONS


The red keywords are links for more detailed background information!

% Activate compatibility mode: Try to behave like the old MacOS-9 Psychtoolbox:
oldEnableFlag=Screen('Preference', 'EmulateOldPTB', [enableFlag]);

% Open or close a window or texture:
[windowPtr,rect]=Screen('OpenWindow',windowPtrOrScreenNumber [,color] [,rect] [,pixelSize] [,numberOfBuffers] [,stereomode] [,multisample][,imagingmode][,specialFlags][,clientRect]);
[windowPtr,rect]=Screen('OpenOffscreenWindow',windowPtrOrScreenNumber [,color] [,rect] [,pixelSize] [,specialFlags] [,multiSample]);
textureIndex=Screen('MakeTexture', WindowIndex, imageMatrix [, optimizeForDrawAngle=0] [, specialFlags=0] [, floatprecision=0] [, textureOrientation=0] [, textureShader=0]);
oldParams = Screen('PanelFitter', windowPtr [, newParams]);
Screen('Close', [windowOrTextureIndex or list of textureIndices/offscreenWindowIndices]);
Screen('CloseAll');

%  Draw lines and solids like QuickDraw and DirectX (OS 9 and Windows):
currentbuffer = Screen('SelectStereoDrawBuffer', windowPtr [, bufferid] [, param1]);
Screen('DrawLine', windowPtr [,color], fromH, fromV, toH, toV [,penWidth]);
Screen('DrawArc',windowPtr,[color],[rect],startAngle,arcAngle)
Screen('FrameArc',windowPtr,[color],[rect],startAngle,arcAngle[,penWidth] [,penHeight] [,penMode])
Screen('FillArc',windowPtr,[color],[rect],startAngle,arcAngle)
Screen('FillRect', windowPtr [,color] [,rect] );
Screen('FrameRect', windowPtr [,color] [,rect] [,penWidth]);
Screen('FillOval', windowPtr [,color] [,rect] [,perfectUpToMaxDiameter]);
Screen('FrameOval', windowPtr [,color] [,rect] [,penWidth] [,penHeight] [,penMode]);
Screen('FramePoly', windowPtr [,color], pointList [,penWidth]);
Screen('FillPoly', windowPtr [,color], pointList [, isConvex]);

% New OpenGL functions for OS X:
Screen('glPoint', windowPtr, color, x, y [,size]);
Screen('gluDisk', windowPtr, color, x, y [,size]);
Screen('DrawDots', windowPtr, xy [,size] [,color] [,center] [,dot_type]);
Screen('DrawLines', windowPtr, xy [,width] [,colors] [,center] [,smooth]);
[sourceFactorOld, destinationFactorOld, colorMaskOld]=Screen('BlendFunction', windowIndex, [sourceFactorNew], [destinationFactorNew], [colorMaskNew]);

% Draw Text in windows
textModes = Screen('TextModes');
oldCopyMode=Screen('TextMode', windowPtr [,textMode]);
oldTextSize=Screen('TextSize', windowPtr [,textSize]);
oldStyle=Screen('TextStyle', windowPtr [,style]);
[oldFontName,oldFontNumber,oldTextStyle]=Screen('TextFont', windowPtr [,fontNameOrNumber][,textStyle]);
[normBoundsRect, offsetBoundsRect]= Screen('TextBounds', windowPtr, text [,x] [,y] [,yPositionIsBaseline] [,swapTextDirection]);
[newX,newY]=Screen('DrawText', windowPtr, text [,x] [,y] [,color] [,backgroundColor] [,yPositionIsBaseline] [,swapTextDirection]);
oldTextColor=Screen('TextColor', windowPtr [,colorVector]);
oldTextBackgroundColor=Screen('TextBackgroundColor', windowPtr [,colorVector]);

% Copy an image, very quickly, between textures, offscreen windows and onscreen windows.
[resident [texidresident]] = Screen('PreloadTextures', windowPtr [, texids]);
Screen('DrawTexture', windowPointer, texturePointer [,sourceRect] [,destinationRect] [,rotationAngle] [, filterMode] [, globalAlpha] [, modulateColor] [, textureShader] [, specialFlags] [, auxParameters]);
Screen('DrawTextures', windowPointer, texturePointer(s) [, sourceRect(s)] [, destinationRect(s)] [, rotationAngle(s)] [, filterMode(s)] [, globalAlpha(s)] [, modulateColor(s)] [, textureShader] [, specialFlags] [, auxParameters]);
Screen('CopyWindow', srcWindowPtr, dstWindowPtr, [srcRect], [dstRect], [copyMode])

% Copy an image, slowly, between matrices and windows :
imageArray=Screen('GetImage', windowPtr [,rect] [,bufferName] [,floatprecision=0] [,nrchannels=3])
Screen('PutImage', windowPtr, imageArray [,rect]);

% Synchronize with the window's screen (on-screen only):
[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('Flip', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);
[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('AsyncFlipBegin', windowPtr [, when] [, dontclear] [, dontsync] [, multiflip]);
[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('AsyncFlipEnd', windowPtr);
[VBLTimestamp StimulusOnsetTime FlipTimestamp Missed Beampos] = Screen('AsyncFlipCheckEnd', windowPtr);
[VBLTimestamp StimulusOnsetTime swapCertainTime] = Screen('WaitUntilAsyncFlipCertain', windowPtr);
[info] = Screen('GetFlipInfo', windowPtr [, infoType=0] [, auxArg1]);
[telapsed] = Screen('DrawingFinished', windowPtr [, dontclear] [, sync]);
framesSinceLastWait = Screen('WaitBlanking', windowPtr [, waitFrames]);

% Load color lookup table of the window's screen (on-screen only):
[gammatable, dacbits, reallutsize] = Screen('ReadNormalizedGammaTable', windowPtrOrScreenNumber [, physicalDisplay]);
Screen('LoadNormalizedGammaTable', windowPtrOrScreenNumber, table [, loadOnNextFlip] [, physicalDisplay]);
oldclut = Screen('LoadCLUT', windowPtrOrScreenNumber [, clut] [, startEntry=0] [, bits=8]);

% Get (and set) information about a window or screen:
screenNumbers=Screen('Screens' [, physicalDisplays]);
windowPtrs=Screen('Windows');
kind=Screen(windowPtr, 'WindowKind');
isOffscreen=Screen(windowPtr,'IsOffscreen');
hz=Screen('FrameRate', windowPtrOrScreenNumber [, mode] [, reqFrameRate]);
hz=Screen('NominalFrameRate', windowPtrOrScreenNumber [, mode] [, reqFrameRate]);
[ monitorFlipInterval nrValidSamples stddev ]=Screen('GetFlipInterval', windowPtr [, nrSamples] [, stddev] [, timeout]);
screenNumber=Screen('WindowScreenNumber', windowPtr);
rect=Screen('Rect', windowPtrOrScreenNumber [, realFBSize=0]);
pixelSize=Screen('PixelSize', windowPtrOrScreenNumber);
pixelSizes=Screen('PixelSizes', windowPtrOrScreenNumber);
[width, height]=Screen('WindowSize', windowPointerOrScreenNumber [, realFBSize=0]);
[width, height]=Screen('DisplaySize', ScreenNumber);
[oldmaximumvalue, oldclampcolors, oldapplyToDoubleInputMakeTexture] = Screen('ColorRange', windowPtr [, maximumvalue][, clampcolors][, applyToDoubleInputMakeTexture]);
info = Screen('GetWindowInfo', windowPtr [, infoType=0] [, auxArg1]);
resolutions=Screen('Resolutions', screenNumber);
oldResolution=Screen('Resolution', screenNumber [, newwidth] [, newheight] [, newHz] [, newPixelSize] [, specialMode]);
oldSettings = Screen('ConfigureDisplay', setting, screenNumber, outputId [, newwidth][, newheight][, newHz][, newX][, newY]);

% Get/set details of environment, computer, and video card (i.e. screen):
struct=Screen('Version');
comp=Screen('Computer');
oldBool=Screen('Preference', 'IgnoreCase' [,bool]);
tick0Secs=Screen('Preference', 'Tick0Secs', tick0Secs);
psychTableVersion=Screen('Preference', 'PsychTableVersion');
mexFunctionName=Screen('Preference', 'PsychTableCreator');
proc=Screen('Preference', 'Process');
Screen('Preference','SkipSyncTests', skipTest);
Screen('Preference','VisualDebugLevel', level (valid values between 0 and 5));
Screen('Preference', 'ConserveVRAM', mode (valid values between 0 and 3));
Screen('Preference', 'Enable3DGraphics', [enableFlag]);

% Helper functions.  Don't call these directly, use eponymous wrappers:
[x, y, buttonVector, hasKbFocus, valuators]= Screen('GetMouseHelper', numButtons [, screenNumber][, mouseIndex]);
Screen('HideCursorHelper', windowPntr [, mouseIndex]);
Screen('ShowCursorHelper', windowPntr [, cursorshapeid][, mouseIndex]);
Screen('SetMouseHelper', windowPntrOrScreenNumber, x, y [, mouseIndex]);

% Internal testing of Screen
timeList= Screen('GetTimelist');
Screen('ClearTimelist');
Screen('Preference','DebugMakeTexture', enableDebugging);

% Movie and multimedia playback functions:
[ moviePtr [duration] [fps] [width] [height] [count] [aspectRatio]]=Screen('OpenMovie', windowPtr, moviefile [, async=0] [, preloadSecs=1] [, specialFlags1=0][, pixelFormat=4][, maxNumberThreads=-1][, movieOptions]);
Screen('CloseMovie', moviePtr);
[ texturePtr [timeindex]]=Screen('GetMovieImage', windowPtr, moviePtr, [waitForImage], [fortimeindex], [specialFlags = 0] [, specialFlags2 = 0]);
[droppedframes] = Screen('PlayMovie', moviePtr, rate, [loop], [soundvolume]);
timeindex = Screen('GetMovieTimeIndex', moviePtr);
[oldtimeindex] = Screen('SetMovieTimeIndex', moviePtr, timeindex [, indexIsFrames=0]);
moviePtr = Screen('CreateMovie', windowPtr, movieFile [, width][, height][, frameRate=30][, movieOptions][, numChannels=4][, bitdepth=8]);
Screen('FinalizeMovie', moviePtr);
Screen('AddFrameToMovie', windowPtr [,rect] [,bufferName] [,moviePtr=0] [,frameduration=1]);
Screen('AddAudioBufferToMovie', moviePtr, audioBuffer);

% Video capture functions:
devices = Screen('VideoCaptureDevices' [, engineId]);
videoPtr =Screen('OpenVideoCapture', windowPtr [, deviceIndex][, roirectangle][, pixeldepth][, numbuffers][, allowfallback][, targetmoviename][, recordingflags][, captureEngineType][, bitdepth=8]);
Screen('CloseVideoCapture', capturePtr);
[fps starttime] = Screen('StartVideoCapture', capturePtr [, captureRateFPS] [, dropframes=0] [, startAt]);
droppedframes = Screen('StopVideoCapture', capturePtr [, discardFrames=1]);
[ texturePtr [capturetimestamp] [droppedcount] [average_intensityOrRawImageMatrix]]=Screen('GetCapturedImage', windowPtr, capturePtr [, waitForImage=1] [,oldTexture] [,specialmode] [,targetmemptr]);
oldvalue = Screen('SetVideoCaptureParameter', capturePtr, 'parameterName' [, value]);

% Low level direct access to OpenGL-API functions:
% Online info for each function available by opening a terminal window
% and typing 'man Functionname' + Enter.

Screen('glPushMatrix', windowPtr);
Screen('glPopMatrix', windowPtr);
Screen('glLoadIdentity', windowPtr);
Screen('glTranslate', windowPtr, tx, ty [, tz]);
Screen('glScale', windowPtr, sx, sy [, sz]);
Screen('glRotate', windowPtr, angle, [rx = 0], [ry = 0] ,[rz = 1]);

% Support for 3D graphics rendering and for interfacing with external OpenGL code:
Screen('Preference', 'Enable3DGraphics', [enableFlag]);  % Enable 3D gfx support.
Screen('BeginOpenGL', windowPtr [, sharecontext]);  % Prepare window for external OpenGL drawing.
Screen('EndOpenGL', windowPtr);  % Finish external OpenGL drawing.
[targetwindow, IsOpenGLRendering] = Screen('GetOpenGLDrawMode');
[textureHandle rect] = Screen('SetOpenGLTextureFromMemPointer', windowPtr, textureHandle, imagePtr, width, height, depth [, upsidedown][, target][, glinternalformat][, gltype][, extdataformat][, specialFlags]);
[textureHandle rect] = Screen('SetOpenGLTexture', windowPtr, textureHandle, glTexid, target [, glWidth][, glHeight][, glDepth][, textureShader][, specialFlags]);
[ gltexid gltextarget texcoord_u texcoord_v ] =Screen('GetOpenGLTexture', windowPtr, textureHandle [, x][, y]);

% Support for plugins and for builtin high performance image processing pipeline:
[ret1, ret2, ...] = Screen('HookFunction', windowPtr, 'Subcommand', 'HookName', arg1, arg2, ...);
proxyPtr = Screen('OpenProxy', windowPtr [, imagingmode]);
transtexid = Screen('TransformTexture', sourceTexture, transformProxyPtr [, sourceTexture2][, targetTexture][, specialFlags]);



 

OpenGL


Instead of offscreen windows, the OpenGL Psychtoolbox uses fast rendering
and OpenGL textures for animation. With the exception of matrices, all
drawing may be done during the animation loop directly to the onscreen
window, rather than being rendered to offscreen windows before the start
of the movie. Matrices are converted to Textures before the start of the
animation and, like offscreen windows in OS 9, may be quickly copied to
an onscreen window during movie play. Offscreen windows are still supported
if you need to draw very complex stimuli. You can draw the stimulus into
an offscreen window and then quickly copy the window into the onscreen
window. For most purposes however, it is possible to draw directly into
the backbuffer of your offscreen window and make the backbuffer visible
on next vertical blank by a call to Screen('Flip', windowPtr).

See MovieDemoOSX and DriftDemoOSX for examples of how to create and show
movies this way.

Off-screen windows are invisible, but useful as an intermediate place to
create and store images for later display. Copying from window to window
is very fast. It's easy to precompute a series of off-screen windows
and then show them as a movie, in real time, one per video frame:

% make movie
window=Screen('OpenWindow', 0, 0);
rect=[0 0 200 200];
for i=1:100
    movie(i)=Screen('OpenOffscreenWindow', window, 0, rect);
    Screen('FillOval', movie(i), 255, [0 0 2 2]*(i-1));
end;

% show movie
for i=[1:100 100:-1:1] % forwards and backwards
    Screen('CopyWindow',movie(i),window,rect,rect);
    Screen('Flip', window);
end;
Screen('CloseAll');


 

WHEN YOU GET A MATLAB ERROR


If your computer only has one screen (the typical scenario) and your program
produces a Matlab error while your full-screen window is open, you'll hear
the beep, but you won't be able to see the Matlab Command Window. Follow the
instructions below for bringing forward the command window, then type clear
screen to flush just the Screen MEX file, or "clear mex" to flush all the
MEX files. When flushed, as part of its exit sequence, Screen closes all its
windows, restores the screen's normal color table, and shows the cursor. Or you
can get just those effects, without flushing, by calling Screen('CloseAll')
or sca - which is an abbreviation for Screen('CloseAll').


You can use Matlab's EVAL command to do this for you automatically. E.g.
if your program is called "foo.m", run your program by calling EVAL:
eval('foo','clear screen;error(''error in foo'')')

If an error occurs in FOO, Matlab, instead of halting, will execute the
second argument to EVAL, which restores your screen and reports the
error.

 

Stopping programs:


Command-zero brings the Matlab Command window forward. (Type a zero "0" while
holding the apple-cloverleaf "command" key down.)

Ctrl-C halts any program. (Type a "c" while holding down the "Ctrl" key).
Sometimes, Ctrl-C fails to halt progams executing in a Matlab process run with
the "-nojvm" option. To halt a runaway Psychtoolbox script in Psychtoolbox
you might resort to the Windows Task Manager to kill the Matlab process. (Use
Ctrl-Alt-Delete to open a window from which you can start the Task Manager.)


Windows:


Ctrl-Alt-Delete allows you to launch the Windows task manager, which
reduces the Psychtoolbox onscreen windows when it opens. (Simultaneosly
press the "Ctrl", "Alt", and "Delete" keys.) There are also simpler ways of
reducing the Psychtoolbox window which are specific to particular
versions of Windows.
Windows 2000: Alt-Tab will bring another application to the foreground,
minimizing the Matlab Psychtoolbox window.

OS-X:

Apple-Command-Escape executes "Force Quit" on Matlab, closing Matlab and all
of its windows.

Linux:

Ctrl-C, Ctrl-C, then blindly type sca


See "help PsychDemos" for many demos which demonstrate Screen's capabilities.

Differences in Screens capabilities between different operating systems
are discussed in the online help for the different subfunctions, our
"PsychDemos" if differences apply, and on the Psychtoolbox Wiki under
"Platform Differences and writing portable code".

 

BUGS


All known bugs and fixes are eventually described at the web site under "Bugs":
web http://psychtoolbox.org/ ;

Initial reports appear first at the forum:
web http://www.yahoogroups.com/messages/psychtoolbox/ ;

If you find a bug, please report it to the forum:
web mailto:psychtoolbox@yahoogroups.com ;

It will help greatly if you can supply a minimal-length program that exhibits
the bug. And please include as much information about your hardware and software
setup to document the context in which you're running, e.g., Computer type, graphics
card type and model, operating system, Matlab version, Psychtoolbox version and flavor
and the output of PTB to the Matlab window.



Path
Psychtoolbox/PsychBasic/Screen.m


Valid XHTML 1.0 Transitional :: Valid CSS :: Powered by WikkaWiki
Page was generated in 0.3020 seconds