% 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. % % Need this extra line, separated by a blank line for help to work on Octave - weird.