File: VRRSupport.m

package info (click to toggle)
psychtoolbox-3 3.0.19.14.dfsg1-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 86,796 kB
  • sloc: ansic: 176,245; cpp: 20,103; objc: 5,393; sh: 2,753; python: 1,397; php: 384; makefile: 193; java: 113
file content (197 lines) | stat: -rw-r--r-- 10,881 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
% VRRSupport - How to set up and use variable refresh rate (VRR) displays.
%
% This text describes how you can take advantage of variable refresh rate
% displays (also known as VRR displays, DisplayPort Adaptive Sync displays,
% HDMI VRR displays, FreeSync displays, or G-Sync displays) to improve the
% timing granularity of visual stimulus presentation to smaller time-scales
% than what the video refresh rate of your display allows, e.g., for a 60
% Hz display with a refresh duration of 1/60 second or 16.666 msecs.
%
% Regular fixed rate refresh displays only allow to start presentation of
% a new stimulus image at frame boundaries between video refresh cycles,
% e.g., for a 60 Hz display only at integral multiples of 16.666 msecs. If
% you specify a requested stimulus onset time 'when' in
% Screen('Flip', window, when); then your stimulus image won't show up
% until the start time 't' of the first video refresh cycle after 'when' ie.
% only at time 't' >= 'when' with t being a multiple of 16.666 msecs. This
% means that interstimulus intervals or stimulus presentation durations are
% limited to multiple of 16.666 msecs. Dynamic animations correspondingly
% can only run at framerates (fps) which are integral divisors of the video
% refresh rate, e.g., for a 60 Hz display at 60 fps, 30 fps, 20 fps, 15 fps,
% 12.5 fps, 10 fps, ...
%
% For some high level overview:
%
% https://en.wikipedia.org/wiki/Variable_refresh_rate
% https://en.wikipedia.org/wiki/FreeSync
% https://en.wikipedia.org/wiki/Nvidia_G-Sync
%
% If you have an operating system, a graphics card, video cables and a display
% device which are VRR capable, you can enable a Psychtoolbox function to enable
% a continuous setting of inter-stimulus-interval (ISI) and the system will try
% its best to conform to your specification. There is still a minimum stimulus
% presentation duration / ISI which is the duration of a video refresh cycle of
% your display, ie. for a 60 Hz display, that would be 16.666 msecs. However,
% above 16.666 msecs you can specify ISI or stimulus duration with millisecond
% precision and the system will try to obey, ie. closely match the onset of a
% requested 'when' time.
%
% This allows for variable ISI's / stimulus durations over a larger range
% of values, and it allows for changing any framerate fps for animations
% that is <= 60 Hz and not locked to the 30, 20, 15, 12.5 ... fps sequence,
% e.g., choose 38.4 fps, 42.2 fps, etc.
%
% So far the theory. In practice things are not always that beautiful.
%
% But first things first:
%
% On a properly setup hardware + software system, you can request this new
% fine-grained timing mode via a new PsychImaging task, before opening a
% opaque, non-transparent, unoccluded, toplevel, decorationless, fullscreen
% onscreen window:
%
% PsychImaging('PrepareConfiguration');
% PsychImaging('AddTask', 'General', 'UseFineGrainedTiming');
% win = PsychImaging('OpenWindow', screenNumber, ...);
%
% If the hardware and software supports fine-grained timing mode (referred
% to from now on as VRR), the opened fullscreen window will be presented
% with VRR mode and vbl = Screen('Flip', win, when); will try to obey 'when' as
% closely as possible, as long as 'when' for flip is more than one video
% refresh duration away from the time of previous Flip, ie. when >= vbl +
% videorefreshduration. If you request a 'when' smaller than 1 video refresh
% duration away, the system will behave as in the past, it will flip after one
% video refresh duration. How well this mechanism works is highly dependent on
% your operating system, graphics card, display driver and display device.
%
%
% Operating system requirements:
%
% Currently only Linux is supported. This has been tested with Ubuntu
% 20.04-LTS and later versions of Ubuntu Linux.
%
% Hardware requirements:
%
% Ideally a modern "FreeSync capable" AMD graphics card (GPU). GPU's of the
% Sea Islands gpu family (Graphics Core Next 2nd Generation, cfe.
% https://en.wikipedia.org/wiki/Graphics_Core_Next#second) should work after
% some manual extra setup, GPU's of the Volcanic Islands or Polaris series
% (Graphics Core Next 3rd Generation, cfe.
% https://en.wikipedia.org/wiki/Graphics_Core_Next#third) should work plug
% and play. GPU's of the AMD Vega series or later (Graphics Core Next 5th
% Generation, cfe. https://en.wikipedia.org/wiki/Graphics_Core_Next#fifth)
% should provide improved stability and precision for VRR mode in many cases
% and are therefore recommended if you intend to make heavy use of this new
% feature. Best results have been obtained during actual testing with AMD
% RavenRidge integrated gpu's - the stuff found in modern AMD Ryzen
% processors. Those Ryzen integrated graphics or AMD Navi discrete gpu's
% are recommended strongly.
%
% Such "FreeSync" gpu's from AMD need to be currently combined with a
% "FreeSync" or "FreeSync-2" or "FreeSync-2 HDR" certified display that is
% connected via DisplayPort cable. FreeSync-2 certified displays are preferable
% for better quality and displays which are both "AMD FreeSync-2" certified, and
% simultaneously certified as "NVidia G-Sync compatible", should provide best
% quality. A display with a large refresh rate range (VRR range) of 30 Hz - 120 Hz
% (or higher) is recommended. One problem of VRR displays is that they may flicker
% if ISI's are changed too rapidly over a too large range. Higher quality displays
% (probably correlated to purchase prize) are supposed to flicker less. Both AMD
% and NVidia have testing labs to test and certify displays if they meet certain
% criteria (like little flicker), with FreeSync2 / FreeSync2 HDR having to conform
% to stricter criteria than FreeSync, and a display that is both FreeSync2
% certified and G-Sync compatible will have passed the strictest tests at both
% AMD and NVidia.
%
% Some interesting technical talk from AMD at XDC 2019 about VRR / FreeSync
% under Linux:
%
% https://www.youtube.com/watch?v=ajBf_b4Aw98
%
% Blurbusters has a list of FreeSync monitors here:
% https://www.blurbusters.com/freesync/list-of-freesync-monitors
%
% Another option that may work, but is *not* expected to work as well as AMD,
% would be a NVidia G-Sync capable graphics card, ie. the Kepler GPU family or
% later cards (GeForce GTX 650 Ti Boost GPU or higher) in combination with a
% NVidia G-Sync capable monitor, or a Pascal GPU family card (GeForce GTX 1000
% series) or later with "G-Sync compatible" monitor, e.g., certain models of
% FreeSync2 monitors.
%
% Blurbusters has a list of G-Sync monitors here:
% https://www.blurbusters.com/gsync/list-of-gsync-monitors
%
% Please note that currently simultaneously "FreeSync and G-Sync compatible"
% monitors should work well with both AMD and NVidia GPU's, but G-Sync monitors
% will *only* work with NVidia GPU's. Therefore a "FreeSync2 and G-Sync compatible"
% monitor would be a much better long-term choice, which doesn't restrict the
% freedom of choice of graphics card.
%
% Intel integrated graphics chips of type Tigerlake or later ("Intel Xe
% graphics" or later), or future Intel discrete graphics cards, should also
% support VRR over Displayport if you use Linux 5.12 or later. However,
% this has not been tested in practice yet, due to lack of suitable
% hardware.
%
% As operating system, Ubuntu Linux 20.04.3 LTS or later, or compatible
% flavors, are currently recommended.
%
% Setup:
% ------
%
% Run our XOrgConfCreator script, answer the question for "advanced
% features" with (y)es, answer the question about VRR support with (y)es,
% and the other questions to your liking, finish the script to save the new
% config file, then run XOrgConfSelector to select that file as new
% configuration for the following work sessions accordingly, followed by a
% logout and login (or a reboot if you want) to activate the new
% configuration.
%
% For NVidia GPU's (Not recommended! May or may not work ok) you must
% install a recent enough NVidia proprietary graphics and display driver,
% use a X-Screen with exactly one G-Sync monitor, and use the
% nvidia-settings GUI app to enable "G-Sync" mode whenever you need it, and
% disable "G-Sync" mode whenever you want to use conventional fixed refresh
% rate presentation again. Psychtoolbox was lightly tested with a NVidia
% GeForce GTX 1070 + "435 series" drivers in December 2019, the situation
% may have changed since then.
%
% Once you have set up your hardware and OS accordingly, you can add the
% above mentioned 'UseFineGrainedTiming' PsychImaging command to script
% which want to utilize VRR for fine grained timing or controllable
% framerate. With AMD or Intel hardware, Psychtoolbox Screen() command will
% help you to diagnose and fix any problems that might prevent VRR from
% working - pointing out missing but required setup steps. With NVidia
% hardware, Screen() will just mostly hope that it works and is properly
% setup and enabled, simply failing or malfunctioning in "interesting"
% ways, if something is not set up correctly.
%
% An example script for testing and exercising VRR mode can be found as
% VRRTest.m
%
% Starting 4th December 2019, Psychtoolbox 3.0.16 shipped very basic support for
% VRR. It works reasonably well, as long as you choose animation framerates that
% are within the supported VRR range of your display, e.g., 30 - 144 Hz, or
% 48 - 144 Hz or such, or inter-stimulus-intervals that are within a range
% corresponding to those framerates, e.g., for a 30 - 144 Hz display, from 6.9444
% msecs to 33.333 msecs. For framerates lower than the displays minimum, e.g.,
% below 30 fps, or corresponding ISI's above 33.333 msecs on a 30 Hz display,
% timing may become very unstable and unpredictable! Smooth changes in framerate
% or small incremental changes in ISI may provide more stable results than quick
% changes.
%
% As of 18th December 2019, Psychtoolbox 3.0.16 ships improved support for VRR.
% A more sophisticated scheduler allows for more stable and precise results over
% a larger range of framerates and ISI's. See "help PsychImaging" for the new
% scheduling method "OwnScheduled", versus the old method "Simple". Testing
% shows pretty good stability and precision on AMD FreeSync gpu's. NVidia G-Sync
% also showed some improvement, but is less stable than AMD, just as expected.
%
% These are operating system and hardware limitations at the moment. Future
% versions of Psychtoolbox and especially in combination with future
% versions of the Linux operating system are expected to provide vastly
% improved support and stability with modern AMD graphics cards - Ryzen
% integrated processor graphics, or Navi discrete gpu's and later models
% recommended for best results, Vega may also work well but is so far
% untested - and potentially Intel graphics chips, much less so with NVidia
% hardware. But only time will tell... Stay tuned...
%