PyGaze - documentation - libscreen
The screen library is used to create Display and Screen objects, to communicate with a computer monitor and to prepare stimuli in the background.
The Display object is used to directly communicate with the computer monitor. Calling the fill method will change the contents of the Display. Calling the show method will refresh the monitor, using the current contents of the Display. Usually, you will want to use only one Display per experiment.
A Screen object is used to prepare a stimulus display, without directly showing it. You can use as many Screen objects as you want and doing so is generaly a Good Idea. It is advised to do as much of the preparing of Screens during parts of your experiment where timing is not crucial, for example at the beginning of your experiment or at the beginning of a single trial.
A Screen object has methods for directly drawing all sorts of stimuli, including rectangles, circles, text and images. If, however, you miss certain functionality, it is possibly to use PyGame or PsychoPy (depending on which DISPTYPE you use) to directly add stimuli to your Screen object. You can do this, by using a Screen object's screen property, which is either a PyGame Surface or a list of PsychoPy stimuli. An example:
| PsychoPy example | PyGame example |
|---|---|
|
# example: PsychoPy code on PyGaze objects
# import stuff from pygaze import libscreen from psychopy.visual import GratingStim # create Display object disp = libscreen.Display(disptype='psychopy') # create Screen object coolscreen = libscreen.Screen(disptype='psychopy') # create Gabor stimulus, using PsychoPy's GratingStim # note that you need to provide a PsychoPy Window object # as the first argument for the GratingStim; the # expdisplay property of a Display item is precisely # what you need! gabor = GratingStim(disp.expdisplay, tex='sin', mask='gauss',pos=(0,0), sf=0.01, size=200, ori=90) # add your gabor to the Screen coolscreen.screen.append(gabor) # now show as you would normally do disp.fill(screen=coolscreen) disp.show() |
# example: PyGame code on PyGaze objects
# import stuff from pygaze import libscreen import pygame from pygame.locals import * # create Display object disp = libscreen.Display(disptype='pygame') # create Screen object coolscreen = libscreen.Screen(disptype='pygame') # draw some text on the screen coolscreen.draw_text(text="This text is mirrored!") # mirror the text (over the vertical axis), using a PyGame function coolscreen.screen = pygame.transform.flip(coolscreen.screen, True, False) # now show as you would normally do disp.fill(screen=coolscreen) disp.show() |
contents
DisplayDisplay.show
Display.show_part
Display.fill
Display.close
Screen
Screen.create
Screen.clear
Screen.copy
Screen.draw_circle
Screen.draw_ellipse
Screen.draw_rect
Screen.draw_line
Screen.draw_polygon
Screen.draw_fixation
Screen.draw_text
Screen.draw_image
Screen.set_background_colour
Display
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| disptype | type of display: either 'pygame' or 'psychopy' (default = DISPTYPE) |
| dispsize | size of the display in pixels: a (width, height) tuple (default = DISPSIZE) |
| fgc | the foreground colour: a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255)) (default = FGC) |
| bgc | the background colour: a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255)) (default = BGC) |
| screennr | the screen number: 0, 1 etc. (default = SCREENNR) |
Updates ('flips') the display
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| None | |
| returns | |
| time | the exact refresh time when disptype is PsychoPy, or an estimate when disptype is PyGame |
Updates part(s) of the screen to given specified screen (only works when disptype is PyGame; when disptype is PsychoPy the entire display is updated)
| arguments | |
|---|---|
| rect | a single or a list of rects; a rect is a (x,y,w,h) tuple or list |
| keyword arguments | |
| screen | the screen of which the specified rects should be updated to the display (default = None) |
| returns | |
| time | the exact refresh time when disptype is PsychoPy, an estimate when disptype is PyGame |
Fills the screen with the background colour or specified screen, NOT updating it (call Display.show() to actually show the new display contents)
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| screen | the screen that should be drawn to the display or None to fill the display with its background colour |
| returns | |
| None | draws every stimulus in screen.screen (PsychoPy) or blits screen.screen to the expdisplay property (PyGame) |
Closes the Display, preventing further output from the Display object to the monitor (making your OS visible again)
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| None | |
| returns | |
| None | closes the Window object self.expdisplay (PsychoPy) or calls pygame.display.quit() (PyGame) |
Screen
A class for Screen objects, for visual stimuli (to be displayed via a Display object)
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| disptype | type of display: either 'pygame' or 'psychopy' (default = DISPTYPE) |
| dispsize | size of the display in pixels: a (width, height) tuple (default = DISPSIZE) |
| fgc | the foreground colour: a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255)) (default = FGC) |
| bgc | the background colour: a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255)) (default = BGC) |
| screen | a libscreen.Screen object to be presented on the new Screen (default=None) |
Creates a new Screen object, filled with either the background colour or specified screen; for internal use: gets called upon initialization
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| screen | a libscreen.Screen object, to be displayed on the new screen or None for the background colour |
| returns | |
| None | sets the self.screen property to a PyGame Surface or a list of PsychoPy stimuli, depending on the disptype |
Clears the screen and fills it with a colour
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | the colour to fill the screen with (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default background colour, self.bgc (default = None) |
| returns | |
| None | clears self.screen (PsychoPy) or fills it with a colour (PyGame) |
Copies a Screen to the current Screen
| arguments | |
|---|---|
| screen | a libscreen.Screen object |
| keyword arguments | |
| None | |
| returns | |
| None | sets the self.screen property to a copy of screen.screen |
Draws a circle on the Screen
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | colour for the circle (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| pos | circle center, a (x,y) position tuple or None for a central position (default = None) |
| r | circle radius (default = 50) |
| pw | penwidth: circle line thickness (default = 1) |
| fill | Boolean indicating whether the circle should be filled or not (default = False) |
| returns | |
| None | draws a circle on (PyGame) or adds a Circle stimulus to (PsychoPy) the self.screen property |
Draws an ellipse on the Screen
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | colour for the ellipse (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| x | x coordinate of the rectangle in which the ellipse is drawn or None for a horizontal centrally drawn ellipse (default = None) |
| y | y coordinate of the rectangle in which the ellipse is drawn or None for a vertical centrally drawn ellipse (default = None) |
| w | width of the rectangle in which the ellipse is drawn (default = 50) |
| h | height of the rectangle in which the ellipse is drawn (default = 50) |
| pw | penwidth: ellipse line thickness (default = 1) |
| fill | Boolean indicating whether the ellipse should be filled or not (default = False) |
| returns | |
| None | draws an ellipse on (PyGame) or adds a GratinsStim stimulus to (PsychoPy) self.screen |
Draws a rectangle on the Screen
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | colour for the rectangle (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| x | x coordinate of the rectangle or None for a horizontal centrally drawn rectangle (default = None) |
| y | y coordinate of the rectangle or None for a vertical centrally drawn rectangle (default = None) |
| w | width of the rectangle (default = 50) |
| h | height of the rectangle (default = 50) |
| pw | penwidth: rectangle line thickness (default = 1) |
| fill | Boolean indicating whether the rectangle should be filled or not (default = False) |
| returns | |
| None | draws a rectangle on (PyGame) or adds a GratinsStim stimulus to (PsychoPy) self.screen |
Draws a line on the Screen
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | colour for the line (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| spos | line start, a (x,y) position tuple or None for a quarter x and a central y position (default = None) |
| epos | line end, a (x,y) position tuple or None for a three-quarter x and a central y position (default = None) |
| pw | penwidth: line thickness (default = 1) |
| returns | |
| None | draws a line on (PyGame) or adds a Line stimulus to (PsychoPy) self.screen |
Draws a polygon on the Screen
| arguments | |
|---|---|
| pointlist | a list of (x,y) tuples indicating the cornerpoints of the polygon |
| keyword arguments | |
| colour | colour for the polygon (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| pw | penwidth: polygon line thickness (default = 1) |
| fill | Boolean indicating whether the polygon should be filled or not (default = False) |
| returns | |
| None | draws a polygon on (PyGame) or adds a ShapeStim stimulus to (PsychoPy) the self.screen property |
Draws a fixation mark (cross, x or dot) on the Screen
| arguments | |||||||||
|---|---|---|---|---|---|---|---|---|---|
| None | |||||||||
| keyword arguments | |||||||||
| fixtype | type of fixation mark, should be either of the following strings:
| ||||||||
| colour | colour for the fixation mark (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) | ||||||||
| pos | fixation mark center, a (x,y) position tuple or None for a central position (default = None) | ||||||||
| pw | penwidth: fixation line thickness (default = 1) | ||||||||
| diameter | diameter of the fixation mark in pixels (default = 12) | ||||||||
| returns | |||||||||
| None | draws on (PyGame) or adds stimuli to (PsychoPy) self.screen |
draw_text(text='text', colour=None, pos=None, center=True, font='mono', fontsize=12, antialias=True)
Draws a text on the Screen
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| text | string to be displayed; newlines ('\n') are allowed and will be recognized (default = 'text') |
| colour | colour for the text (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| pos | text position, an (x,y) position tuple or None for a central position (default = None) |
| font | font name (a string value); should be the name of a font included in the PyGaze resources/fonts directory (default = 'mono') |
| fontsize | fontsize in pixels (an integer value) (default = 12) |
| antialias | Boolean indicating whether text should be antialiased or not (default = True) |
| returns | |
| None | renders and draws a surface with text on (PyGame) or adds a SimpleTextStim to (PsychoPy) self.screen |
Draws an image on the Screen
| arguments | |
|---|---|
| image | a full path to an image file, a PIL Image, or a PyGame Surface (Surface only available with 'pygame' DISPTYPE) |
| keyword arguments | |
| pos | image center position, an (x,y) position tuple or None for a central position (default = None) |
| scale | scale factor for the image (e.g. 0.5 for half size, or 2.0 for double size), or None for no scaling (default = None) |
| returns | |
| None | loads and draws an image surface on (PyGame) or adds an ImageStim to (PsychoPy) self.screen |
Set the Screen background colour to colour
| arguments | |
|---|---|
| None | |
| keyword arguments | |
| colour | new background colour (a colour name (e.g. 'red') or a RGB(A) tuple (e.g. (255,0,0) or (255,0,0,255))) or None for the default foreground colour, self.fgc (default = None) |
| returns | |
| None | sets self.bgc |
full source
You can find the full source code for libscreen.py on GitHub.