Window¶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, *args, **kwargs)¶Used to set up a context in which to draw objects, using either pyglet or pygame
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.
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.
| Parameters: |
|
|---|
_assignFlipTime(obj, attrib)¶Helper function to assign the time of last flip to the obj.attrib
| Parameters: |
|
|---|
_checkMatchingSizes(requested, actual)¶Checks whether the requested and actual screen sizes differ. If not then a warning is output and the window size is set to actual
_endOfFlip(clearBuffer)¶Override end of flip with custom color channel masking if required
_getFrame(rect=None, buffer='front')¶Return the current Window as an image.
_getRegionOfFrame(rect=(-1, 1, 1, -1), buffer='front', power2=False, squarePower2=False)¶Deprecated function, here for historical reasons. You may now use _getFrame() and specify a rect to get a sub-region, just as used here
power2 can be useful with older OpenGL versions to avoid interpolation in PatchStim. If power2 or squarePower2, it will expand rect dimensions up to next power of two. squarePower2 uses the max dimensions. You need to check what your hardware & OpenGL supports, and call _getRegionOfFrame as appropriate.
_renderFBO()¶Perform a warp operation (in this case a copy operation without any warping)
_setCurrent()¶Make this window current. If useFBO=True, the framebuffer is bound after the context switch.
_setupGamma(gammaVal)¶A private method to work out how to handle gamma for this Window given that the user might have specified an explicit value, or maybe gave a Monitor
_startOfFlip()¶Custom hardware classes may want to prevent flipping from occurring and can override this method as needed. Return True to indicate hardware flip.
applyEyeTransform(clearDepth=True)¶Apply the current view and projection matrices specified by ‘viewMatrix’ and ‘projectionMatrix’ using ‘immediate mode’ OpenGL. 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. |
|---|
blendMode¶callOnFlip(function, *args, **kwargs)¶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)
clearBuffer()¶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()¶Close the window (and reset the Bits++ if necess).
color¶Set the color of the window.
NB 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 visual.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.
colorSpace¶string. (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.
dispatchAllWindowEvents()¶Dispatches events for all pyglet windows. Used by iohub 2.0 psychopy kb event integration.
farClip¶Distance to the far clipping plane in meters.
flip(clearBuffer=True)¶Flip the front and back buffers after drawing everything for your frame. (This replaces the win.update() method, better reflecting what is happening underneath).
win.flip(clearBuffer=True) # results in a clear screen after flipping win.flip(clearBuffer=False) # the screen is not cleared (so represent
# the previous screen)
fps()¶Report the frames per second since the last call to this function (or since the window was created if this is first call)
fullscr¶Set whether fullscreen mode is True or False (not all backends can toggle an open window)
gamma¶Set the monitor gamma for linearization
(don’t use this if using a Bits++ or Bits#) Overrides monitor settings.
gammaRamp¶getActualFrameRate(nIdentical=10, nMaxFrames=100, nWarmUpFrames=10, threshold=1)¶Measures the actual 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).
If there is no such sequence of identical frames a warning is logged and None will be returned.
| Parameters: |
|
|---|
getMovieFrame(buffer='front')¶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(filename) 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 win.flip() and gives a complete copy of the screen at the window’s coordinates.
getMsPerFrame(nFrames=60, showVisual=False, msg='', msDelay=0.0)¶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 win.flip(). If 0 < msDelay < 100, wait for that long in ms.
Returns timing stats (in ms) of:
| Author: |
|
|---|
logOnFlip(msg, level, obj=None)¶Send a log message that should be time-stamped at the next .flip() command.
| Parameters: |
|
|---|
mouseVisible¶Sets the visibility of the mouse cursor.
If Window was initialized with noGUI=True then the mouse is initially set to invisible, otherwise it will initially be visible.
Usage:
``win.mouseVisible = False``
``win.mouseVisible = True``
nearClip¶Distance to the near clipping plane in meters.
projectionMatrix¶Projection matrix defined as a 4x4 numpy array.
recordFrameIntervals¶To provide 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().
See also
Window.saveFrameIntervals()
resetEyeTransform(clearDepth=True)¶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.
| Returns: | |
|---|---|
| Return type: | None |
Notes
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)¶Save recorded screen frame intervals to disk, as comma-separated values.
| Parameters: |
|---|
saveMovieFrames(fileName, codec='libx264', fps=30, clearFrames=True)¶Writes any captured frames to disk.
Will write any format that is understood by PIL (tif, jpg, png, …)
| Parameters: |
|
|---|
Examples:
# writes a series of static frames as frame001.tif,
# frame002.tif etc...
myWin.saveMovieFrames('frame.tif')
#as of PsychoPy 1.84.1 the following are written with moviepy
myWin.saveMovieFrames('stimuli.mp4') # codec = 'libx264' or 'mpeg4'
myWin.saveMovieFrames('stimuli.mov')
myWin.saveMovieFrames('stimuli.gif')
setBlendMode(blendMode, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setBuffer(buffer, clear=True)¶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.
Typical usage:
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
win.flip()
setColor(color, colorSpace=None, operation='', log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you want to set color and colorSpace simultaneously. See Window.color for documentation on colors.
setGamma(gamma, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setMouseType(name='arrow')¶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
‘hresize’ : Double arrows pointing horizontally ‘vresize’ : Double arrows pointing vertically
Requires the GLFW backend, otherwise this function does nothing! Note, on Windows the ‘crosshair’ option is XORed with the background color. It will not be visible when placed over 50% grey fields.
| Parameters: | name – str, type of standard cursor to use |
|---|---|
| Returns: |
setMouseVisible(visibility, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setPerspectiveView(applyTransform=True, **kwargs)¶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.
Note that the values of ‘projectionMatrix’ and ‘viewMatrix’ will be replaced when calling this function.
| Parameters: |
|
|---|---|
| Returns: | |
| Return type: |
setRGB(newRGB)¶Deprecated: As of v1.61.00 please use setColor() instead
setRecordFrameIntervals(value=True, log=None)¶Usually you can use ‘stim.attribute = value’ syntax instead, but use this method if you need to suppress the log message.
setScale(units, font='dummyFont', prevScale=(1.0, 1.0))¶DEPRECATED: this method used to be used to switch between units for stimulus drawing but this is now handled by the stimuli themselves and the window should always be left in units of ‘pix’
setUnits(value, log=True)¶setViewPos(value, log=True)¶timeOnFlip(obj, attrib)¶Retrieves the time on the next flip and assigns it to the attrib for this obj.
| Parameters: |
|
|---|
units¶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.
viewMatrix¶View matrix defined as a 4x4 numpy array.
viewPos¶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.
waitBlanking¶None, True or False. After a call to flip() should we wait for the blank before the script continues