Update History

Bug fixes and documentation revisions included in all updates.


  • Element type screenRecorder and command recordElements: Set image/movie file size (px), specific multiple file names


  • Option to use vector trial definition numbering for organizing trial definitions into groups in multiple dimensions (e.g. block + condition within block) in complex experiment designs


  • Element type screenRecorder and command recordElements: Improved handling of frame rate, saving series of images in folders, revamped documentation


A major update including a visual interface and broad revamp of documentation:

  • Visual interface based on tables made in any spreadsheet app (Microsoft Excel, Apple Numbers, Google Sheets, etc.). The coding method of making an experiment is unchanged and remains as an option.
  • Better handling of saved screen measurements for multiple screens
  • Better handling of keyboard input when multiple keyboards are attached
  • Interface for setting element and/or trial timing from synchronization triggers is now analogous to setting timing from without triggers: element start/end.t_sync, trial object start/end.t_ sync
  • Element type backColor: Functionality for setting background color for part of a trial is now in backColor elements. Setting broader experiment and/or trial background color in experiment/trial object properties is unchanged.
  • Getting started / Making an experiment documentation is now online
  • All documentation online is searchable
  • Element type programming manual is greatly shortened by focusing only on making visual stimulus element types, which is what 99% of people need
  • pb <><object type><> at the MATLAB command line now shows a quick alphabetical list of properties with their default values before asking to open full documentation
  • Many minor additions/changes


  • Use custom GLSL shaders for any visual element with property shader


  • Added element property addDisplay to add any element display pixel-wise to whatever is behind it on screen to make a superposition (sufficient graphics hardware required)
  • Element type noise: If addDisplay is enabled, noise will add to whatever is behind it on screen, typically another element. This allows the full flexibility of noise elements in adding noise to any other elements.
  • Minor additions/changes: Element property layerdepth, pixeResolutionchannelResolution (backwards compatibility with old code is preserved)
  • Minor additions/changes: Added screen object properties bufferChannelResolution, clampChannels


  • Added a tutorial combining a scanner + staircase experiment
  • Minor additions/changes: element type line now has a default (just for quick display purposes)
  • Element type programming: streamlined making a quick class by making core option screen default


  • Minor additions/changes: Improvements to text rendering


  • Introductory tutorial video posted on the homepage
  • textInput elements allow the subject to type text during an experiment


  • Use operating system-independent key names for keyboard input. Use the command line tool showKey to see them.


  • Minor additions/changes: Timing from trigger for trials (trial object start.timeFromTrigger) now automatically extrapolates to set a maximum end time for the last trial in a sequence consistent with the other trials, which can simplify writing experiment scripts


  • Fleshed out system requirements information in all documentation
  • Minor additions/changes: Options to see all property names and defaults for an object type with the pb command


  • Minor additions/changes: Flag to apply small angle approximation tanθ ≈ θ in tools deg2px, px2deg


  • Element type picture: Added ability to show multiple pictures either arranged spatially or in a sequence across time
  • Added element types checkerboard, dartboard
  • Important bug fixes to pb_update
  • Minor additions/changes: Added screen distance unit <cds>"deg-"<cds>, which is degrees visual angle with small angle approximation tanθ ≈ θ applied. You can use this if you need degrees that scale linearly with regular distance units like cm, px, etc.
  • Minor additions/changes: recordElements: option to set recording duration directly in elements


  • Element type programming: Use custom index properties in element_setShared, element_doShared


  • Added property colorMask for all visual elements, allowing to modulate RGB color channels for an element display
  • Added property filterGrayscale for all visual elements, allowing fastering filtering (e.g. convolution) for grayscale elements
  • text elements now have transparent background by default


  • Added element type polygon


  • Added tool recordElements to make recording/capturing any visual elements to single images, series of multiple images, or movie files easy. Uses screenRecorder elements under the hood.
  • Property backColor for visual elements allows tweaking how alpha blending for antialiasing works on some elements


  • Added element type gaussian for a Gaussian blob
  • Added element type mask for a rectangular/elliptical/Gaussian occluding aperture
  • Element type bmlWalker: Added property showMarkerNums to give a static display with marker dots replaced by numbers. Useful if you want to visualize what numbers correspond to what markers in a motion data set.
  • All element type documentation pages now have a uniform section near the top documenting whether and how objects of the type can end on their own (without needing to set property end). Before this was kind of mixed into the documentation in different ways and different places across types. This change hopefully makes this important factoid easy to check for any type.
  • Element type programming: Type script tool element_openTexture replaces element_openDrawTexture and covers both opening blank textures for draw commands and loading image matrixes onto textures.


  • Element types movie, sound, dotPath, bmlWalker: Added properties to show specific time ranges in the source file/data
  • Element type programming: Improved support for deprecated properties.


  • bmlWalker element type: Can load marker motion data from .c3d files. Can use property nn_markers to only use some markers in the data.
  • showElements: option to group elements horizontally or vertically when showing multiple elements at a time


  • New timing options: Element end.orAfter tells the element not to run any time after the condition is met if it occurs before the element would start. Trial object property end allows setting end conditions for a whole trial
  • Added defaults for inputs to tools deg2px and px2deg to make them more automatic and easy
  • Minor additions/changes: tweaks to pbLog.txt file output for debugging element timing


  • Core visual option to set different gamma decoding for different elements. Also a special gamma option for filters (intensity, contrast, convolution, noise) to apply them in luminance space as opposed to gamma-encoded RGB space. These complement the existing option to set the graphics card gamma for the whole display. In all cases you can use a lookup table or simple power law gamma.
  • Core visual option to use pixel resolutions (bit depths) > 32 bit RGBA for an element display
  • Option in showElements to show multiple elements at the same time instead of consecutively
  • Added distance unit wwh which scales x coordinates by window width and y coordinates by window height in a vector or matrix value, e.g. <cd>[1 1]<cd> = window size.
  • Easier and more flexible interface and other improvements for screenRecorder elements


  • Core visual option for contrast scaling
  • picture element options for grayscale, custom image transformation code
  • movie element option for grayscale
  • screenRecorder elements can be set to find and record the display area of a specified element
  • Element type programming: function element_predraw for lower latency drawing of static displays; deprecate properties


  • Option to not shuffle MATLAB's random number generator for all randomization tools randomNum, randomOrder, etc.
  • Option to repeat random patterns by using a seed for MATLAB's random number generator in noise and bmlWalker elements. Tutorial 7 (stereo display) updated to show a random dot stereogram using this feature.
  • Options to use a rectangular distribution and quantize intensity (e.g. binary intensity) in noise elements


  • Use property vary to set drift/movement on any time-dependent path for any visual element, and more generally to vary element properties in real time when the element is running


  • Added element type noise for white Gaussian noise.
  • Added property noise to picture elements to apply noise using any of the options available in MATLAB imnoise.
  • Added record property frameRate to trial objects, recording instantaneous frame rate for all frames in a trial.


  • Added element type screenRecorder to record/capture displays to a single image file, sequence of multiple image files, or movie file


  • Option to set trial repetition and order directly in trial definitions with an optional trial run number input to addTrial, instead of using setTrialList
  • Option to save and reuse exact random scrambling patterns across bmlWalker elements


  • Important bug fixes to functionality in MATLAB versions earlier than R2021a (down to R2017a): pb_install, pb_update, results csv file writing, pb_prefs
  • Minor additions/changes: catch scripts can now use properties changed or added in a script that halted on error (element type programming)


  • Added element type profiler. This runs the MATLAB code profiler for code debugging and assessment.


  • Results also write to a .csv file for analysis in apps other than MATLAB
  • Use a flag input to runExperiment to test the experiment by running it in auto-response mode to simulate a subject run unattended


  • A family of helper tools for working with strings/substrings (strcontains, strstarts, strends, and i variants)
  • keyPress elements now default to using Psychtoolbox KbCheck for responses, keyboard queue for triggers


  • All reference documentation (core and element types) is now online. Non-reference documentation remains in /docs but is also available online.
  • Revamp of MATLAB help: All documentation is now hyperlinked, including all function help text, Contents.m files summarizing files and folders, all options in pb_prefs, and the pb command menu. Added files summaries for /tools and /element type programming/basic. Now uses the standard MATLAB ver command for version information.
  • Compatibility options which are especially useful to avoid problems that Psychtoolbox experiences on Macs. See pb_prefs → screen tab → sync tests and compositor.
  • Save and resume any experiment run quit part-way through (type help runExperiment for details)
  • Any property that uses deg visual angle can also use px, wh (window height), ww (window width), or cm units using <cd>{value, <cd><cds>"unit"<cds><cd>}<cd> syntax
  • All visual element types now have all core visual options (rotation, alpha, convolution filter, etc.). (Previously some did not implement these options, e.g. line, linearDotMask, etc.)
  • Added intensity scaling as a core visual option
  • New input options to element_draw, _redraw for element type programmers
  • Minor additions/changes: Optionally use one number for symmetric dimensions in size properties across many element types (e.g. one number for a square side length as opposed to a rectangle). Added fit/fill/px sizing options to element types picture and movie. Can set Gaussian convolution filter width. Can specify separable custom convolution kernels. And more.


  • Graphical interface for setting general preferences (default property values for trial, experiment, and device objects) using command pb_prefs. Especially useful for easily setting common parameters like Psychtoolbox sync tests; experiment window size; sound device, sample rate, and quality; etc.
  • Results output is now organized by object, not object class. More readable and each trial always uses one row.
  • Second results output now uses nan and <><missing><> values where possible to preserve numeric and string arrays for easier analysis
  • Option to set trial repetition and order directly in trial definitions using trial object property n. An alternative to the command setTrialList for unusual cases.
  • Added tools randomDistribute, randomDistributePerms for use in experiment scripts. Added an output to randomOrder to facilitating inverting order.
  • Added element type dotPath: arbitrary dot motion based on (x, y) time series data
  • Minor additions/changes: Default volume = on for movie elements


  • Sound input functionality using Psychtoolbox PortAudio, and element type soundRecorder to record sound to file
  • A sound-based Stroop demo where the subject responds verbally
  • Minor additions/changes: Set a break interval in a repeating display for element type bmlWalker


  • Added support for Cedrus response pads, and element type cedrusPress
  • Streamlined framework for devices (screen, PortAudio, keyboard queues, ports, button boxes, etc.) in element type code
  • Reduced start latency of keyPress, portSender, portReceiver, and other elements that use keyboard queues or ports


  • All response handler elements can now register triggers as well as record responses from subject, allowing you to use any response handler modality for triggers
  • Element type keyPress now uses a keyboard queue by default for better time measurement precision and never missing a key press. Polling functionality (Psychtoolbox KbCheck) is still available as an option.
  • Merged element type keyReceiver into keyPress
  • Add latency and buffer size properties to speaker device objects, which allows control over those technical settings in Psychtoolbox PortAudio. This is necessary to prevent crackling on some systems.
  • Added multisampling (general antialiasing) option to screen device objects


  • Added a second results output from runExperiment which contains results compressed into a numeric matrix or other arrays for extracting/plotting/analyzing with MATLAB functions. The first results output remains easily viewable as a table in MATLAB's visual variable editor.
  • Added an option in addTrial to define distinct trial groups by number, which can be useful in complex experiments
  • Stroop and biological motion demo experiments



  • Simplified the interface for setting timing from sync with a scanner or other external device
  • Minor additions/changes: Fast step sizes now default to regular step sizes for fixed step staircases


  • Can now use any static visual elements in pre-trial intervals, not just fixation crosses


  • Minor additions/changes: Can now load motion data directly from files for bmlWalker elements. Faster opening of bmlWalker elements when many there are many elements using the same motion data in an experiment.


  • PsychBench 1 beta