Graphics and display setup¶
Do this once, right after installation, on every computer that will show stimuli to participants. It takes about ten minutes, and it protects the one thing an SSVEP or FPVS experiment cannot recover afterwards: the stimulus flickering at exactly the frequency the design says.
Why it matters¶
The toolbox draws one frame per screen refresh. On a 120 Hz panel a 12 Hz flicker is exactly 10 frames per cycle, and the whole design (frequencies, phases, the spacing between targets) rests on every frame being shown for exactly one refresh. Three things in the graphics path can break that, and none of them produces an error message on its own:
- Vertical sync (vsync) off. The program swaps frames whenever it likes instead of waiting for the panel. Frames tear, and the program can draw more frames than the panel shows, so some are never seen.
- A driver mode that discards or reshapes frames. NVIDIA's Fast sync, AMD's Enhanced Sync and variable-refresh technologies (G-SYNC, FreeSync) all exist to decouple drawing from refreshing. That is good for games and wrong for a stimulus.
- A frame path that Windows composes. The toolbox opens a borderless full-screen window, not an exclusive full-screen mode. Windows may route it through the desktop compositor, which adds a queue of frames between the program and the panel.
A frame that is repeated or dropped shifts the flicker's phase by a fraction of a cycle, and over a trial it changes the average frequency. At 40 Hz on a 240 Hz panel, losing 5 % of the refreshes moves the stimulus by about 2 Hz, which is more than the spacing of a typical frequency-tagged design.
What the toolbox checks for you, and what you set by hand¶
The toolbox cannot change your driver settings. It can notice some of the ways they go wrong.
| Automatic | By hand | |
|---|---|---|
| The swap interval the program asked for | Read at start-up of a full-screen run (from v1.0); a run with vsync off is refused | The driver can still override what the program asks for, so set it below |
| Refresh rate | The measured rate is compared with the display's mode. A run presenting below 80 % of its mode is refused; from v1.0, so is one running more than 1 % faster than its mode | Choose the mode yourself, and keep it fixed |
| Every frame waited for | The program waits for each flip to finish before drawing the next (from v1.0) | Do not cap or throttle the frame rate in the driver |
| Frames drawn against refreshes elapsed | Counted per trial and flagged in the run's report as missed refreshes or extra frames (the Presentation timing section) | Read the report after a pilot run |
| Which monitor, HDR, scaling, power mode | Not checked | This page |
| What reaches the screen | Not checked: only a light sensor can see it | The flik-o-meter, a light sensor on the screen |
A flagged trial is never removed from your data; the report says which ones and why, and you decide. The point of this page is to make sure the flags stay quiet.
The only ground truth is the flik-o-meter, a photodiode on the screen that measures the frequency the participant is actually shown. Run it on any new computer, display or driver setting before collecting data.
Settings by graphics vendor¶
Driver menus change names between versions. Where this page says "check your driver's equivalent", look for the option with the same purpose rather than the same wording. In every case you can make the setting global, or create a program profile for just the toolbox so the rest of the computer keeps its usual settings.
NVIDIA (NVIDIA Control Panel, Manage 3D settings)¶
| Setting | Use | Avoid |
|---|---|---|
| Vertical sync | Use the 3D application setting or On (both are fine) | Off, Fast, Adaptive |
| Monitor technology / G-SYNC | Fixed refresh for the toolbox's Python (or G-SYNC off) | G-SYNC or G-SYNC Compatible on for the program |
| Low Latency Mode | Off | On, Ultra |
| Max Frame Rate | Off | Any cap |
| Power management mode | Prefer maximum performance (recommended; it keeps clocks up, it does not change sync) | |
| OpenGL present method (OpenGL GDI compatibility in some versions) | Auto or Prefer native | Forcing Prefer layered on DXGI Swapchain without checking the result with the flik-o-meter |
To make a program profile: open Manage 3D settings, go to the Program Settings tab, choose Add, and browse to the python.exe of the ssvep environment, then add pythonw.exe from the same folder. The desktop launcher starts the app with pythonw.exe and some commands with python.exe, so a profile covering only one of them silently does nothing for the other. The environment's folder is usually ...\miniforge3\envs\ssvep\ (or wherever conda env list shows ssvep). Set the table's values on each program, then press Apply.
AMD (Radeon Software: Adrenalin, Gaming, Graphics)¶
| Setting | Use | Avoid |
|---|---|---|
| Wait for Vertical Refresh | Always on, or On, unless application specifies | Always off, Off unless application specifies |
| Enhanced Sync (a separate toggle) | Off | On |
| AMD FreeSync (under the Display tab, and per program) | Off for the toolbox's Python | On for the program |
| Radeon Chill, Radeon Boost, Radeon Anti-Lag | Off | On (they change frame pacing) |
| Frame Rate Target Control | Off | Any cap |
Adrenalin also supports a per-program profile: add the same two python.exe and pythonw.exe files as above.
Intel integrated graphics (Intel Graphics Software, or Intel Graphics Command Center on older drivers)¶
Check your driver's equivalent of each of the following. Names differ between driver generations, and some laptops hide the panel behind the manufacturer's own control app.
- Vsync: set to the application's setting or to On. Avoid options described as "adaptive", "smart" or "sync off" for games.
- Variable refresh / Adaptive Sync: off for the toolbox.
- Panel power saving (sometimes "Display Power Saving" or "Dynamic refresh rate"): off. These lower the refresh rate or the brightness while the screen is busy, which changes the stimulus.
- Power plan: plugged in, on a high-performance plan.
Windows settings¶
- Set the refresh rate explicitly. Settings → System → Display → Advanced display, choose the stimulus display, and set Choose a refresh rate to the rate your design uses. Leave Dynamic refresh rate (the setting that switches between, for example, 60 and 120 Hz) off, because the toolbox measures the rate once at start-up. Keep the display at its native resolution and scaling mode.
- Turn HDR off for the stimulus display (Settings → System → Display → HDR). HDR remaps brightness in ways that distort flicker amplitude.
- Variable refresh rate (Settings → System → Display → Graphics → Change default graphics settings → Variable refresh rate): turn it off. Optimizations for windowed games sits on the same page; it changes how DirectX 10 and 11 windows are presented, and the toolbox draws with OpenGL, so it may not apply. Whether the toolbox's frames go through that path is decided on NVIDIA by the driver's OpenGL present method above. Turning it off is harmless. If your Windows version does not show these options, skip them.
- Scaling. A display scale other than 100 % does not change the stimulus. Leave it as it is, unless the toolbox's window is cut off.
- Multiple monitors. Make the stimulus display the primary display, or disconnect the others during a run: Settings → System → Display, select the stimulus display, tick Make this my main display. In the pilot behind this page, the stimulus display was not the primary display and ran at a different refresh rate from it, and the first seconds of each run showed timing that looked like the desktop compositor was in the way. That cause is not confirmed, but making the stimulus display primary is a cheap precaution. Keep the operator's screen quiet during a run (no video, no notifications) and do not touch the stimulus computer during the first seconds of a run.
- Do not change modes mid-session. Do not plug or unplug monitors, change the refresh rate or switch power mode while a session is open.
Integrated graphics or a dedicated GPU¶
Both can do this job. What matters is that the frames reach the panel one per refresh, not how fast the graphics chip is.
- Integrated graphics are fine for SSVEP and FPVS at a modest refresh rate (for example 60 or 120 Hz) if vsync is locked. The toolbox draws flat or simple shapes and does not need a fast chip. High refresh rates (240 Hz and above) and large images leave less headroom, and if the program cannot finish a frame inside one refresh, that frame is repeated. A dedicated GPU gives more headroom.
- Laptops with two graphics chips (NVIDIA Optimus, AMD switchable graphics) normally send the dedicated GPU's frames through the integrated GPU on their way to the built-in screen. That extra hop is a frame queue the toolbox cannot see. If your laptop has a dedicated-only or MUX switch mode (vendors call it names such as Ultimate, Discrete GPU only or dGPU mode), prefer it for stimulus work; it usually needs a restart. Without one, make Windows use the dedicated chip for the toolbox: Settings → System → Display → Graphics, add the
ssvepenvironment'spython.exeandpythonw.exeas desktop apps, and set each to High performance. The names vary by Windows version: older versions have Add an app with a Desktop app dropdown and an Options button, and newer ones have Add desktop app and a GPU preference dropdown. - Which chip drives which screen. On many laptops the built-in panel is wired to one chip and an external HDMI or DisplayPort monitor to the other. The same stimulus program can therefore behave differently on the two screens. Test on the screen you will really use, and do not move the window between them in a session.
- Battery and power saver throttle both chips and may lower the refresh rate. Run on mains power, with the power mode set to best performance.
- Do not run other graphics-heavy programs (video calls, games, screen recording) alongside a session.
A short checklist¶
- Vertical sync on or "use the application setting"; Fast, Enhanced and Adaptive modes off; G-SYNC and FreeSync off; frame-rate caps off.
- A program profile for both
python.exeandpythonw.exein thessvepenvironment, where your driver supports it. - The stimulus display at its native resolution and its chosen fixed refresh rate; HDR and dynamic refresh off; it is the primary display.
- Laptop: plugged in, high-performance mode, dedicated GPU only if possible.
- A pilot run: it starts without a refusal, and the run's report shows no flagged presentation timing.
- Before real data: a flik-o-meter measurement on the stimulus display.
If a run is refused or flagged, see Troubleshooting.