>Psychtoolbox>PsychDocumentation

ConserveVRAMSettings: Workaround for flawed hardware and drivers

The command Screen(‘Preference’, ‘ConserveVRAM’, mode); can be used to
enable a couple of special work-arounds inside Screen to work around
broken operating systems, graphics drivers or graphics hardware, or to
work around resource limitations of graphics hardware.

You define the requested workaround by setting the parameter ‘mode’ to a
sum of the following values:

Allowed summands (flags) for ‘mode’ and their effect:

1 == kPsychDisableAUXBuffers: A setting of 1 asks Psychtoolbox to not
allocate any OpenGL AUXiliary buffers when opening a new onscreen window.
AUX buffers are only needed if you want to run the Screen(‘Flip’) command
with the optional argument ‘dontclear = 1’ and you are not using the
imaging pipeline, or if you want to use stereomode 2 or 3 without using
the imaging pipeline. If you do use the imaging pipeline or don’t use any
of the above, there’s no need for AUX buffers.

This setting is mostly meant to save a bit of VRAM on graphics hardware
that only has very small amounts of VRAM, e.g., only 16 MB or 8 MB VRAM.

2 == kPsychDontSwitchToOptimalVidMode: A setting of 2 asks Psychtoolbox
to avoid switching the display to a different resolution, as would be
normally done on macOS for Intel Macs in fullscreen mode in order to fix
various macOS bugs. Instead a mode with proper timing properties but
matching video resolution and refresh rate to the currently active mode
is chosen if possible. This is usually the wrong thing to do, but for
certain special external display configurations it might help, e.g., with
external display splitter devices from Matrox.

The flag is silently ignored on Windows and Linux, as the visual timing
workarounds influenced by this flag are only needed on buggy macOS.

Note that this flag value 2 used to have a different meaning in older
Psychtoolbox releases, influencing texture memory optimizations. These
have been removed as they were both not needed anymore and buggy on
recent macOS releases.

4 == kPsychOverrideWglChoosePixelformat: This is a workaround for broken
MS-Windows graphics drivers: Ask Screen to not use the
wglChoosePixelFormat() command when creating a new onscreen window. This
can prevent crashes on such broken setups, but it will disable OpenGL
multisampling for anti-aliasing, ie., the ‘multisample’ parameter of
Screen(‘OpenWindow’) will be ignored. In the future, other special
capabilities will be disabled as well.

8 == kPsychDisableContextIsolation: This is a workaround for broken
MS-Windows graphics drivers: Do not create separate isolated OpenGL
rendering contexts for Screen and MOGL when using low level OpenGL 3D
graphics commands with OpenGL for Matlab. This prevents crashes on broken
setups, but debugging of your own 3D code may become much harder. Its
better to upgrade to the latest fixed drivers.
Before you try this setting 8, first try if the setting 256 (see below)
fixes the problem for you. That is a softer approach - If it works for
you then you won’t lose any important functionality!

16 == kPsychDontAttachStencilToFBO: Do not attach stencil buffer
attachments to OpenGL framebuffer objects when using OpenGL 3D graphics
in conjunction with the Psychtoolbox imaging pipeline. This is again a
workaround for some broken MS-Windows graphics drivers to make the 3D +
imaging combo work at least when no stencil buffer is needed.

32 == kPsychDontShareContextRessources: Do not share resources between
different onscreen windows. Usually you want PTB to share all resources
like offscreen windows, textures and GLSL shaders among all open onscreen
windows. If that causes trouble for some weird reason, you can prevent
automatic sharing with this flag.

64 == kPsychUseSoftwareRenderer: Request use of a software implemented
renderer instead of the GPU hardware renderer. This request is silently
ignored if your platform doesn’t support software rendering. Currently
only MacOS/X 10.4 and later in windowed mode (i.e. not fullscreen)
supports this via the Apple floating point renderer. Mostly useful for
testing and debugging of scripts that need floating point support on
hardware that doesn’t support this. Not generally useful for production
use.

On MS-Windows this allows to use the Microsoft GDI software renderer,
ie., to not abort if that renderer is detected. Normally Screen() would
abort when detecting the GDI renderer.

On GNU/Linux this allows to use the Mesa X11 software renderer, ie.,
to not abort if that renderer is detected. Normally Screen() would
abort when detecting that renderer.

128 == kPsychEnforceForegroundWindow: Request application of the Windows
GDI calls SetForegroundWindow() and SetFocus() on each created onscreen
window on MS-Windows. This may improve reliability of onscreen windows
staying in front of all other windows, but is incompatible with the use
of GetChar, CharAvail and ListenChar, so it must be requested with this
flag. These calls are unfortunately absolutely crucial on MS-Vista and
later operating systems to guarantee artifact free (tear-free) and timing
accurate stimulus onset and robust and accurate stimulus onset
timestamping. Therefore they are automatically applied to all fullscreen
windows on Windows Vista and later operating systems. See the option
kPsychPreventForegroundWindow to forcefully disable/prevent use of these
options, if use of GetChar() et al. is more important than artifact free
stimulus presentation.

256 == kPsychUseWindowsContextSharingWorkaround1
On MS-Windows, skip a few not too essential setup steps when creating a
userspace OpenGL rendering context for 3D mode. This is a “soft” version
of kPsychDisableContextIsolation – Less intrusive as it doesn’t disable
context isolation completely, but only a subset. May be able to
work-around an NVidia driver bug reported in March 2008 on GF8xxx series.

512 == kPsychAvoidCPUGPUSync: Avoid any internal calls (if possible) that
could cause a synchronization of the CPU and GPU. Synchronization is a
potentially expensive operation that can degrade performance in certain
circumstances. Its often needed for error checking. Setting this flag may
give you a speedup on certain operations, but at the cost of reduced
error checking and error handling: Error conditions detected otherwise
may silently slip through and cause mysterious malfunctions or stimulus
corruption without PTB noticing this or providing any troubleshooting
tips. The usefulness of this flag highly depends on your graphics
hardware, driver and operating system. It may give a large speedup, or no
speedup at all, but it will always reduce robustness!

1024 == kPsychTextureUploadFormatOverride
Tell PTB to use the opposite texture format of what its auto-detection
thinks is optimal. Screen contains code to auto-detect certain type of
graphics chips with broken drivers and tries to work-around them by
choosing different parameters for fast texture creation in certains
circumstances. In case those vendors should ever fix their drivers and
thereby the built-in workaround becoming invalid, this allows to override
PTB’s choice. This is mostly to work around broken ATI drivers on
MS-Windows which cause miserable texture creation performance with the
standard optimized settings.

2048 == kPsychAvoidFramebufferBlitIfPossible
Tell PTB to not use the EXT_framebuffer_blit extension if a lower-speed
workaround solution exists. This will mostly affect the operation of
Screen(‘CopyWindow’) when the imaging pipeline is active. Normally a more
flexible, capable, faster method would be used, unless you set this flag
to fall back to the old solution.

4096 == kPsychUseBeampositionQueryWorkaround
Tell PTB to always use the workaround for broken beamposition queries in
VBL on MS-Windows, even if the automatic startup test does not detect any
problems. This for rare cases where the test fails to detect broken
setups.

8192 == kPsychUseAGLForFullscreenWindows
Tell PTB on Mac OS/X to always use the Cocoa/NSOpenGL API for OpenGL
system setup, even if the requested onscreen window is a fullscreen
window. Normally PTB would use the CGL API for fullscreen windows for
higher efficiency. This setting is automatically implicitly applied if
PTB is running on OSX version 10.8 “Mountain Lion” or later, to work
around various hilarious graphics driver bugs.

16384 == kPsychUseCompositorForFullscreenWindows
Tell PTB to use a compositing window manager for stimulus display if such
a desktop compositor is supported on your operating system. Currently
this flags affects operation on MacOS/X and on Microsoft Windows Vista
and later versions of Windows.

On Windows Vista and Windows-7, it will enforce use of the Windows Aero
desktop compositor (aka DWM or Desktop Window Manager). Accuracy and
reliability of visual stimulus onset timing and the accuracy and
reliability of stimulus onset timestamps will be greatly reduced in this
mode - up to the point of being completely useless for timed stimulus
presentation. The mode may however be useful for debugging and code
development as a convenience feature. By default, PTB disables the DWM as
soon as a fullscreen window is opened, unless the
PsychDebugWindowConfiguration() function was used to switch to debug
mode.

On Mac OS/X this will cause Screen to avoid capturing the display. This
may or may not affect display performance, who knows?

32768 == kPsychBusyWaitForVBLBeforeBufferSwapRequest
If Screen(‘Flip’) in sync with vertical retrace is requested and
beamposition queries are supported, use a busy-waiting, high cpu load
spin-wait loop to wait for onset of vertical blank interval (VBL) before
submitting doublebuffer swaprequests to the GPU. This is meant as a
last-ressort workaround for GPU’s with severely broken sync-to-VBL
support. The only known current example is the Apple Leopard operatings
system when used with NVidia Geforce 8000 GPU’s or later in
frame-sequential stereo mode. This will create a very high cpu load and
may have negative side effects on system timing. Use as last resort!

65536 (= 2^16) == kPsychDontUseNativeBeamposQuery [Deprecated]
Do not use operating system native beamposition queries, but try to use
own mechanism, or none at all. This was used to work around bugs in OS
native beamposition query mechanisms, e.g., Leopard 10.5.7 + ATI GPU’s.
It has no function anymore under OSX as of Psychtoolbox 3.0.12.

131072 (= 2^17) == kPsychDisableAeroDWM [Deprecated]
Disable the Aero DWM desktop composition manager on Windows Vista and
later. By default, Psychtoolbox will do this anyway for fullscreen windows,
as this provides better timing behaviour, so this flag is pretty pointless
now. On Windows-8 and later, the DWM can not be disabled anymore anyway.

262144 (= 2^18) == kPsychPreventForegroundWindow [Deprecated]
Prevent calls to the Windows GDI functions SetForegroundWindow() and
SetFocus() on each created fullscreen onscreen window on MS-Windows.

524288 (= 2^19) == kPsychDisableOpenMLScheduling
Disable use of OpenML scheduling for Screen(‘Flip’) bufferswaps. OpenML
is currently supported on some recent versions of GNU/Linux with certain
graphics cards and drivers (e.g., Free graphics stack on Ubuntu 10.10 and
later with modern Intel and ATI/AMD GPU’s and XOrg Servers 1.8.2, 1.9.x and
later, Linux kernel 2.6.35 and later). PTB will use OpenML for scheduling
and timestamping of visual stimulus onset if it detects a Linux system
with support for OpenML. The kPsychDisableOpenMLScheduling flag will
forcefully disable use of OpenML, e.g., for debugging/testing purpose.

1048576 (= 2^20) == kPsychBypassLUTFor10BitFramebuffer
If a 30 bpp, 10 bpc native 10 bit framebuffer is requested and
Psychtoolbox is executing on Linux (as superuser) or OS/X (with the
PsychtoolboxKernelDriver loaded), then apply the 10 bit LUT bypass enable
hack even on graphics cards where this should not be required, e.g., on
the FireGL or FirePro cards from ATI/AMD. This as a workaround for broken
ATI/AMD graphics drivers which are able to configure a 10 bit framebuffer
and scanout, but fail to setup the LUT’s properly.

2097152 (= 2^21) == kPsychEnforce10BitFramebufferHack
Use 10 bpc framebuffer hack even if PTB thinks it is not needed or
appropriate. This implies kPsychBypassLUTFor10BitFramebuffer, and the
same conditions must be met for it to possibly work. This can be used to
enforce 10 bpc mode on FireGL/FirePro GPU’s with broken drivers. It
overrides all our safeguards and may end in a hard machine crash is used
on the wrong setup. Try to use the regular way of enabling this in ATI’s
Catalyst Control Center application if possible.

4194304 (= 2^22) == kPsychIgnoreNominalFramerate
Do not use the nominal video refresh rate of a screen as reported by the
operating system for internal calibrations and tests. Return zero instead
of this rate in calls to Screen(‘Framerate’) or Screen(‘NominalFramerate’).
This to work around broken or problematic video refresh reporting mechanisms.

2^23 == kPsychUseOldStyleAsyncFlips
Do not use the enhanced Screen(‘AsyncFlipBegin’) implementation which
allows for more parallelism between your code and pending async flips.
There is no reason to use this flag except for benchmarking by PTB
developers. Or, of course, if you should happen to have an operating
system + graphics driver + GPU combo which performs much worse with the
new method than with the old one.

2^24 == kPsychDontAutoEnableImagingPipeline
Do not automatically enable support for fast offscreen windows on
graphics cards (GPU’s) that support this. Do not automatically enable the
full Psychtoolbox image processing pipeline on supported GPU’s for stereo
display modes which would benefit from it.

On Psychtoolbox versions released before the year 2012, you needed to
enable those two features manually. 2012+ PTB’s will auto-enable on
suitable hardware if this promises improvements in performance,
flexibility or robustness. In the unlikely case you should encounter
problems with this behaviour due to graphics driver or operating system
bugs, you can revert to the old opt-in behaviour: The PsychImaging()
command then allows you to enable those features manually and separately,
just as on pre 2012 PTB’s.

2^25 == kPsychOldStyleOverrideRedirect
Use the old-school method of setting the override_redirect property
of X11 Windows on Linux, as it was done until end 2012. This just as
a safe-guard in case somebody runs a very exotic or old Linux setup,
where the new method doesn’t work.

2^26 == kPsychForceUseNativeBeamposQuery [Deprecated]
Force use of the OSX builtin beamposition query mechanism, even if the
PsychtoolboxKernelDriver is installed and would provide better results.

As of Psychtoolbox 3.0.12, this does nothing anymore.

This was mostly for internal testing and benchmarking of Psychtoolbox. As
of April 2013 and MacOSX 10.8 “Mountain Lion”, our own implementation was
superior to Apple’s broken implementation, so we defaulted to use of our
own implementation whenever possible. The OSX native implementation was
only supported on NVidia gpu’s anymore, scheduled for removal in a future
OSX version (marked as deprecated in Apple developer documentation!),
always slightly broken and more noisy, imprecise and higher overhead than
our own implementation. At least on OSX 10.8 with GeForce-600 gpu’s, the
OSX implementation was completely broken for anything but analog VGA CRT
displays, ie., it delivers bogus results for any kind of internal or
external digital lcd flat panel! Since OSX 10.10, Apple removed their
support completely, so current PTB can only use the PsychtoolboxKernelDriver
method anyway.

2^27 == kPsychForceOpenMLTSWorkaround
Force use of OpenML swap completion timestamp workaround. This to
workaround certain potential timestamping bugs in some graphics drivers.
Currently no such bugs exist, so this option is just to future-proof
your Psychtoolbox against potential bugs in future operating systems.
Bugs were present in Linux versions 3.13 - 3.15 for a short period of
time between April and July 2014 which made this workaround necessary.
However, the workaround is automatically enabled on such Linux versions
without the need for this conservevram setting. The relevant Linux bugs
have been fixed by mid-July 2014, ie., at the time of this writing, in all
versions of the Linux kernel (Linux >= 3.13.11.5+, 3.14.12+, 3.15.5+, 3.16+).
Nonetheless we leave this manual way to enable the workaround, should the
need ever arise again in the future.

2^28 == kPsychAssumeGfxCapVCGood
Force the assumption that the graphics hardware is capable of processing
OpenGL vertex colors at full 32 bpc floating point precision. This allows
to avoid the use of special texture filter shaders when drawing bilinearly
filtered floating point textures while color clamping is disabled on a
floating point onscreen window or offscreen window. Instead the standard
fixed function pipeline is used by default. By default Psychtoolbox assumes
insufficient precision and uses such a shader, but some defective graphics
drivers, e.g., for AMD graphics cards under Mac OSX 10.11 “El Capitan”, will
perform bilinear texture sampling at insufficient precision, which can be a
hazard for vision research which requires > 8 bpc color/luminance/contrast
precision. This flag allows to enforce fixed function as a potential plan B.
The HighColorPrecisionDrawingTest() script will detect such defective graphics
drivers and advice the user to use this flag in such situations.

–> It’s always better to update your graphics drivers with fixed
versions or buy proper hardware than using these workarounds. They are
meant as a last ressort, e.g., if you need to get something going quickly
or can’t get access to bug-fixed drivers.