A class representing a window for displaying one or more stimuli.

class psychopy.visual.Window(size=(800, 600), pos=None, color=(0, 0, 0), colorSpace='rgb', rgb=None, dkl=None, lms=None, fullscr=None, allowGUI=None, monitor=None, bitsMode=None, winType=None, units=None, gamma=None, blendMode='avg', screen=0, viewScale=None, viewPos=None, viewOri=0.0, waitBlanking=True, allowStencil=False, multiSample=False, numSamples=2, stereo=False, name='window1', checkTiming=True, useFBO=False, useRetina=True, autoLog=True, gammaErrorPolicy='raise', *args, **kwargs)[source]

Used to set up a context in which to draw objects, using either pyglet, pygame, or glfw.

The pyglet backend allows multiple windows to be created, allows the user to specify which screen to use (if more than one is available, duh!) and allows movies to be rendered.

The GLFW backend is a new addition which provides most of the same features as pyglet, but provides greater flexibility for complex display configurations.

Pygame may still work for you but it’s officially deprecated in this project (we won’t be fixing pygame-specific bugs).

These attributes can only be set at initialization. See further down for a list of attributes which can be changed after initialization of the Window, e.g. color, colorSpace, gamma etc.

  • size (array-like of int) – Size of the window in pixels [x, y].
  • pos (array-like of int) – Location of the top-left corner of the window on the screen [x, y].
  • color (array-like of float) – Color of background as [r, g, b] list or single value. Each gun can take values between -1.0 and 1.0.
  • fullscr (bool or None) – Create a window in ‘full-screen’ mode. Better timing can be achieved in full-screen mode.
  • allowGUI (bool or None) – If set to False, window will be drawn with no frame and no buttons to close etc., use None for value from preferences.
  • winType (str or None) – Set the window type or back-end to use. If None then PsychoPy will revert to user/site preferences.
  • monitor (Monitor or None) – The monitor to be used during the experiment. If None a default monitor profile will be used.
  • units (str or None) – Defines the default units of stimuli drawn in the window (can be overridden by each stimulus). Values can be None, ‘height’ (of the window), ‘norm’ (normalised), ‘deg’, ‘cm’, ‘pix’. See Units for the window and stimuli for explanation of options.
  • screen (int) – Specifies the physical screen that stimuli will appear on (‘pyglet’ and ‘glfw’ winType only). Values can be >0 if more than one screen is present.
  • viewScale (array-like of float or None) – Scaling factors [x, y] to apply custom scaling to the current units of the Window instance.
  • viewPos (array-like of float or None) – If not None, redefines the origin within the window, in the units of the window. Values outside the borders will be clamped to lie on the border.
  • viewOri (float) – A single value determining the orientation of the view in degrees.
  • waitBlanking (bool or None) – After a call to flip() should we wait for the blank before the script continues.
  • bitsMode – DEPRECATED in 1.80.02. Use BitsSharp class from pycrsltd instead.
  • checkTiming (bool) – Whether to calculate frame duration on initialization. Estimated duration is saved in monitorFramePeriod.
  • allowStencil (bool) – When set to True, this allows operations that use the OpenGL stencil buffer (notably, allowing the Aperture to be used).
  • multiSample (bool) – If True and your graphics driver supports multisample buffers, multiple color samples will be taken per-pixel, providing an anti-aliased image through spatial filtering. This setting cannot be changed after opening a window. Only works with ‘pyglet’ and ‘glfw’ winTypes, and useFBO is False.
  • numSamples (int) – A single value specifying the number of samples per pixel if multisample is enabled. The higher the number, the better the image quality, but can delay frame flipping. The largest number of samples is determined by GL_MAX_SAMPLES, usually 16 or 32 on newer hardware, will crash if number is invalid.
  • stereo (bool) – If True and your graphics card supports quad buffers then this will be enabled. You can switch between left and right-eye scenes for drawing operations using setBuffer().
  • useRetina (bool) – In PsychoPy >1.85.3 this should always be True as pyglet (or Apple) no longer allows us to create a non-retina display. NB when you use Retina display the initial win size request will be in the larger pixels but subsequent use of units='pix' should refer to the tiny Retina pixels. Window.size will give the actual size of the screen in Retina pixels.
  • gammaErrorPolicy (str) – If raise, an error is raised if the gamma table is unable to be retrieved or set. If warn, a warning is raised instead. If ignore, neither an error nor a warning are raised.


  • Some parameters (e.g. units) can now be given default values in the user/site preferences and these will be used if None is given here. If you do specify a value here it will take precedence over preferences.

array-like (float) – Dimensions of the window’s drawing area/buffer in pixels [w, h].


float – Refresh rate of the display if checkTiming=True on window instantiation.


Setup OpenGL state for this window.


Apply the current view and projection matrices.

Matrices specified by attributes viewMatrix and projectionMatrix are applied using ‘immediate mode’ OpenGL functions. Subsequent drawing operations will be affected until flip() is called.

All transformations in GL_PROJECTION and GL_MODELVIEW matrix stacks will be cleared (set to identity) prior to applying.

Parameters:clearDepth (bool) – Clear the depth buffer. This may be required prior to rendering 3D objects.

Aspect ratio of the current viewport (width / height).


Blend mode to use.

callOnFlip(function, *args, **kwargs)[source]

Call a function immediately after the next flip() command.

The first argument should be the function to call, the following args should be used exactly as you would for your normal call to the function (can use ordered arguments or keyword arguments as normal).

e.g. If you have a function that you would normally call like this:

pingMyDevice(portToPing, channel=2, level=0)

then you could call callOnFlip() to have the function call synchronized with the frame flip like this:

win.callOnFlip(pingMyDevice, portToPing, channel=2, level=0)

Clear the back buffer (to which you are currently drawing) without flipping the window. Useful if you want to generate movie sequences from the back buffer without actually taking the time to flip the window.


Close the window (and reset the Bits++ if necess).


Set the color of the window.

This command sets the color that the blank screen will have on the next clear operation. As a result it effectively takes TWO flip() operations to become visible (the first uses the color to create the new screen, the second presents that screen to the viewer). For this reason, if you want to changed background color of the window “on the fly”, it might be a better idea to draw a Rect that fills the whole window with the desired Rect.fillColor attribute. That’ll show up on first flip.

See other stimuli (e.g. GratingStim.color) for more info on the color attribute which essentially works the same on all PsychoPy stimuli.

See Color spaces for further information about the ways to specify colors and their various implications.


Documentation for colorSpace is in the stimuli.

e.g. GratingStim.colorSpace

Usually used in conjunction with color like this:

win.colorSpace = 'rgb255'  # changes colorSpace but not
                           # the value of win.color
win.color = [0, 0, 255]    # clear blue in rgb255

See Color spaces for further information about the ways to specify colors and their various implications.


Convergence offset from monitor in centimeters.

This is value corresponds to the offset from screen plane to set the convergence plane (or point for toe-in projections). Positive offsets move the plane farther away from the viewer, while negative offsets nearer. This value is used by setPerspectiveView and should be set before calling it to take effect.


  • This value is only applicable for setToeIn and setOffAxisView.

True if face culling is enabled.`


Face culling mode, either back, front or both.


Depth test comparison function for rendering.


True if depth masking is enabled. Writing to the depth buffer will be disabled.


True if depth testing is enabled.


True if 3D drawing is enabled on this window.


Eye offset in centimeters.

This value is used by setPerspectiveView to apply a lateral offset to the view, therefore it must be set prior to calling it. Use a positive offset for the right eye, and a negative one for the left. Offsets should be the distance to from the middle of the face to the center of the eye, or half the inter-ocular distance.


Distance to the far clipping plane in meters.


Flip the front and back buffers after drawing everything for your frame. (This replaces the update() method, better reflecting what is happening underneath).

Parameters:clearBuffer (bool, optional) – Clear the draw buffer after flipping. Default is True.
Returns:Wall-clock time in seconds the flip completed. Returns None if waitBlanking is False.
Return type:float or None


  • The time returned when waitBlanking is True corresponds to when the graphics driver releases the draw buffer to accept draw commands again. This time is usually close to the vertical sync signal of the display.


Results in a clear screen after flipping:


The screen is not cleared (so represent the previous screen):


Report the frames per second since the last call to this function (or since the window was created if this is first call)


Size of the framebuffer in pixels (w, h).


Face winding order to define front, either ccw or cw.


Set whether fullscreen mode is True or False (not all backends can toggle an open window).


Set the monitor gamma for linearization.


Don’t use this if using a Bits++ or Bits#, as it overrides monitor settings.


Sets the hardware CLUT using a specified 3xN array of floats ranging between 0.0 and 1.0.

Array must have a number of rows equal to 2 ^ max(bpc).

getActualFrameRate(nIdentical=10, nMaxFrames=100, nWarmUpFrames=10, threshold=1)[source]

Measures the actual frames-per-second (FPS) for the screen.

This is done by waiting (for a max of nMaxFrames) until nIdentical frames in a row have identical frame times (std dev below threshold ms).

  • nIdentical (int, optional) – The number of consecutive frames that will be evaluated. Higher –> greater precision. Lower –> faster.
  • nMaxFrames (int, optional) – The maximum number of frames to wait for a matching set of nIdentical.
  • nWarmUpFrames (int, optional) – The number of frames to display before starting the test (this is in place to allow the system to settle after opening the Window for the first time.
  • threshold (int, optional) – The threshold for the std deviation (in ms) before the set are considered a match.

Frame rate (FPS) in seconds. If there is no such sequence of identical frames a warning is logged and None will be returned.

Return type:

float or None

getFutureFlipTime(targetTime=0, clock=None)[source]

The expected time of the next screen refresh. This is currently calculated as win._lastFrameTime + refreshInterval

  • targetTime (float) – The delay from now for which you want the flip time. 0 will give the because that the earliest we can achieve. 0.15 will give the schedule flip time that gets as close to 150 ms as possible
  • clock (None, 'ptb', 'now' or any Clock object) – If True then the time returned is compatible with ptb.GetSecs()
  • verbose (bool) – Set to True to view the calculations along the way

Capture the current Window as an image.

Saves to stack for saveMovieFrames(). As of v1.81.00 this also returns the frame as a PIL image

This can be done at any time (usually after a flip() command).

Frames are stored in memory until a saveMovieFrames() command is issued. You can issue getMovieFrame() as often as you like and then save them all in one go when finished.

The back buffer will return the frame that hasn’t yet been ‘flipped’ to be visible on screen but has the advantage that the mouse and any other overlapping windows won’t get in the way.

The default front buffer is to be called immediately after a flip() and gives a complete copy of the screen at the window’s coordinates.

Parameters:buffer (str, optional) – Buffer to capture.
Returns:Buffer pixel contents as a PIL/Pillow image object.
Return type:Image
getMsPerFrame(nFrames=60, showVisual=False, msg='', msDelay=0.0)[source]

Assesses the monitor refresh rate (average, median, SD) under current conditions, over at least 60 frames.

Records time for each refresh (frame) for n frames (at least 60), while displaying an optional visual. The visual is just eye-candy to show that something is happening when assessing many frames. You can also give it text to display instead of a visual, e.g., msg='(testing refresh rate...)'; setting msg implies showVisual == False.

To simulate refresh rate under cpu load, you can specify a time to wait within the loop prior to doing the flip(). If 0 < msDelay < 100, wait for that long in ms.

Returns timing stats (in ms) of:

  • average time per frame, for all frames
  • standard deviation of all frames
  • median, as the average of 12 frame times around the median (~monitor refresh rate)
  • 2010 written by Jeremy Gray
logOnFlip(msg, level, obj=None)[source]

Send a log message that should be time-stamped at the next flip() command.

  • msg (str) – The message to be logged.
  • level (int) – The level of importance for the message.
  • obj (object, optional) – The python object that might be associated with this message if desired.

Sets the visibility of the mouse cursor.

If Window was initialized with allowGUI=False then the mouse is initially set to invisible, otherwise it will initially be visible.


win.mouseVisible = False
win.mouseVisible = True

Distance to the near clipping plane in meters.


Projection matrix defined as a 4x4 numpy array.


Record time elapsed per frame.

Provides accurate measures of frame intervals to determine whether frames are being dropped. The intervals are the times between calls to flip(). Set to True only during the time-critical parts of the script. Set this to False while the screen is not being updated, i.e., during any slow, non-frame-time-critical sections of your code, including inter-trial-intervals, event.waitkeys(), core.wait(), or image.setImage().


Enable frame interval recording, successive frame intervals will be stored:

win.recordFrameIntervals = True

Frame intervals can be saved by calling the saveFrameIntervals method:


Restore the default projection and view settings to PsychoPy defaults. Call this prior to drawing 2D stimuli objects (i.e. GratingStim, ImageStim, Rect, etc.) if any eye transformations were applied for the stimuli to be drawn correctly.


  • Calling flip() automatically resets the view and projection to defaults. So you don’t need to call this unless you are mixing views.
saveFrameIntervals(fileName=None, clear=True)[source]

Save recorded screen frame intervals to disk, as comma-separated values.

  • fileName (None or str) – None or the filename (including path if necessary) in which to store the data. If None then ‘lastFrameIntervals.log’ will be used.
  • clear (bool) – Clear buffer frames intervals were stored after saving. Default is True.
saveMovieFrames(fileName, codec='libx264', fps=30, clearFrames=True)[source]

Writes any captured frames to disk.

Will write any format that is understood by PIL (tif, jpg, png, …)

  • filename (str) – Name of file, including path. The extension at the end of the file determines the type of file(s) created. If an image type (e.g. .png) is given, then multiple static frames are created. If it is .gif then an animated GIF image is created (although you will get higher quality GIF by saving PNG files and then combining them in dedicated image manipulation software, such as GIMP). On Windows and Linux .mpeg files can be created if pymedia is installed. On macOS .mov files can be created if the pyobjc-frameworks-QTKit is installed. Unfortunately the libs used for movie generation can be flaky and poor quality. As for animated GIFs, better results can be achieved by saving as individual .png frames and then combining them into a movie using software like ffmpeg.
  • codec (str, optional) – The codec to be used by moviepy for mp4/mpg/mov files. If None then the default will depend on file extension. Can be one of libx264, mpeg4 for mp4/mov files. Can be rawvideo, png for avi files (not recommended). Can be libvorbis for ogv files. Default is libx264.
  • fps (int, optional) – The frame rate to be used throughout the movie. Only for quicktime (.mov) movies.. Default is 30.
  • clearFrames (bool, optional) – Set this to False if you want the frames to be kept for additional calls to saveMovieFrames. Default is True.


Writes a series of static frames as frame001.tif, frame002.tif etc.:


As of PsychoPy 1.84.1 the following are written with moviepy:

myWin.saveMovieFrames('stimuli.mp4') # codec = 'libx264' or 'mpeg4'

Scissor rectangle (x, y, w, h) for the current draw buffer.

Values x and y define the origin, and w and h the size of the rectangle in pixels. The scissor operation is only active if scissorTest=True.

Usually, the scissor and viewport are set to the same rectangle to prevent drawing operations from spilling into other regions of the screen. For instance, calling clearBuffer will only clear within the scissor rectangle.

Setting the scissor rectangle but not the viewport will restrict drawing within the defined region (like a rectangular aperture), not changing the positions of stimuli.


True if scissor testing is enabled.

setBuffer(buffer, clear=True)[source]

Choose which buffer to draw to (‘left’ or ‘right’).

Requires the Window to be initialised with stereo=True and requires a graphics card that supports quad buffering (e,g nVidia Quadro series)

PsychoPy always draws to the back buffers, so ‘left’ will use GL_BACK_LEFT This then needs to be flipped once both eye’s buffers have been rendered.

  • buffer (str) – Buffer to draw to. Can either be ‘left’ or ‘right’.
  • clear (bool, optional) – Clear the buffer before drawing. Default is True.


Stereoscopic rendering example using quad-buffers:

win = visual.Window(...., stereo=True)
while True:
    # clear may not actually be needed
    win.setBuffer('left', clear=True)
    # do drawing for left eye
    win.setBuffer('right', clear=True)
    # do drawing for right eye

Change the appearance of the cursor for this window. Cursor types provide contextual hints about how to interact with on-screen objects.

The graphics used ‘standard cursors’ provided by the operating system. They may vary in appearance and hot spot location across platforms. The following names are valid on most platforms:

  • arrow : Default pointer.
  • ibeam : Indicates text can be edited.
  • crosshair : Crosshair with hot-spot at center.
  • hand : A pointing hand.
  • hresize : Double arrows pointing horizontally.
  • vresize : Double arrows pointing vertically.
Parameters:name (str) – Type of standard cursor to use (see above). Default is arrow.


  • On Windows the crosshair option is negated with the background color. It will not be visible when placed over 50% grey fields.
setOffAxisView(applyTransform=True, clearDepth=True)[source]

Set an off-axis projection.

Create an off-axis projection for subsequent rendering calls. Sets the viewMatrix and projectionMatrix accordingly so the scene origin is on the screen plane. If eyeOffset is correct and the view distance and screen size is defined in the monitor configuration, the resulting view will approximate ortho-stereo viewing.

The convergence plane can be adjusted by setting convergeOffset. By default, the convergence plane is set to the screen plane. Any points on the screen plane will have zero disparity.

  • applyTransform (bool) – Apply transformations after computing them in immediate mode. Same as calling applyEyeTransform() afterwards.
  • clearDepth (bool, optional) – Clear the depth buffer.
setPerspectiveView(applyTransform=True, clearDepth=True)[source]

Set the projection and view matrix to render with perspective.

Matrices are computed using values specified in the monitor configuration with the scene origin on the screen plane. Calculations assume units are in meters. If eyeOffset != 0, the view will be transformed laterally, however the frustum shape will remain the same.

Note that the values of projectionMatrix and viewMatrix will be replaced when calling this function.

  • applyTransform (bool) – Apply transformations after computing them in immediate mode. Same as calling applyEyeTransform() afterwards.
  • clearDepth (bool, optional) – Clear the depth buffer.
setToeInView(applyTransform=True, clearDepth=True)[source]

Set toe-in projection.

Create a toe-in projection for subsequent rendering calls. Sets the viewMatrix and projectionMatrix accordingly so the scene origin is on the screen plane. The value of convergeOffset will define the convergence point of the view, which is offset perpendicular to the center of the screen plane. Points falling on a vertical line at the convergence point will have zero disparity.

  • applyTransform (bool) – Apply transformations after computing them in immediate mode. Same as calling applyEyeTransform() afterwards.
  • clearDepth (bool, optional) – Clear the depth buffer.


  • This projection mode is only ‘correct’ if the viewer’s eyes are converged at the convergence point. Due to perspective, this projection introduces vertical disparities which increase in magnitude with eccentricity. Use setOffAxisView if you want to display something the viewer can look around the screen comfortably.

Size of the drawable area in pixels (w, h).


True if stencil testing is enabled.

timeOnFlip(obj, attrib)[source]

Retrieves the time on the next flip and assigns it to the attrib for this obj.

  • obj (dict or object) – A mutable object (usually a dict of class instance).
  • attrib (str) – Key or attribute of obj to assign the flip time to.


Assign time on flip to the tStartRefresh key of myTimingDict:

win.getTimeOnFlip(myTimingDict, 'tStartRefresh')

None, ‘height’ (of the window), ‘norm’, ‘deg’, ‘cm’, ‘pix’ Defines the default units of stimuli initialized in the window. I.e. if you change units, already initialized stimuli won’t change their units.

Can be overridden by each stimulus, if units is specified on initialization.

See Units for the window and stimuli for explanation of options.


View matrix defined as a 4x4 numpy array.


The origin of the window onto which stimulus-objects are drawn.

The value should be given in the units defined for the window. NB: Never change a single component (x or y) of the origin, instead replace the viewPos-attribute in one shot, e.g.:

win.viewPos = [new_xval, new_yval]  # This is the way to do it
win.viewPos[0] = new_xval  # DO NOT DO THIS! Errors will result.

Viewport rectangle (x, y, w, h) for the current draw buffer.

Values x and y define the origin, and w and h the size of the rectangle in pixels.

This is typically set to cover the whole buffer, however it can be changed for application like multi-view rendering.


Constrain drawing to the left and right halves of the screen, where stimuli will be drawn centered on the new rectangle. Note that you need to set both the viewport and the scissor rectangle:

x, y, w, h = win.frameBufferSize  # size of the framebuffer
win.viewport = win.scissor = [x, y, w / 2.0, h]
# draw left stimuli ...

win.viewport = win.scissor = [x + (w / 2.0), y, w / 2.0, h]
# draw right stimuli ...

# restore drawing to the whole screen
win.viewport = win.scissor = [x, y, w, h]

After a call to flip() should we wait for the blank before the script continues.

Back to top