Update online docs for 3.0.22.2 release.

Author: kleinerm

docs/EyelinkCleanupHelper.md

@@ -0,0 +1,17 @@
+# [EyelinkCleanupHelper](EyelinkCleanupHelper)
+##### >[Psychtoolbox](Psychtoolbox)>[PsychHardware](PsychHardware)>[EyelinkToolbox](EyelinkToolbox)>[EyelinkOneLiners](EyelinkOneLiners)
+
+% Restore character output to command window, disable [GetChar](GetChar) et al.:  
+
+
+
+
+<div class="code_header" style="text-align:right;">
+  <span style="float:left;">Path&nbsp;&nbsp;</span> <span class="counter">Retrieve <a href=
+  "https://raw.github.com/Psychtoolbox-3/Psychtoolbox-3/beta/Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkCleanupHelper.m">current version from GitHub</a> | View <a href=
+  "https://github.com/Psychtoolbox-3/Psychtoolbox-3/commits/beta/Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkCleanupHelper.m">changelog</a></span>
+</div>
+<div class="code">
+  <code>Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkCleanupHelper.m</code>
+</div>
+

docs/EyelinkTransferFileHelper.md

@@ -0,0 +1,24 @@
+# [EyelinkTransferFileHelper](EyelinkTransferFileHelper)
+##### >[Psychtoolbox](Psychtoolbox)>[PsychHardware](PsychHardware)>[EyelinkToolbox](EyelinkToolbox)>[EyelinkOneLiners](EyelinkOneLiners)
+
+[EyelinkTransferFileHelper](EyelinkTransferFileHelper)(el, edfFile)  
+  
+Helper function for transferring a copy of the EDF file to the experiment folder  
+on the display computer and displaying some feedback to the user.  
+  
+'el' Eyelink struct.  
+'edfFile' Name of the EDF file.  
+  
+
+
+
+
+<div class="code_header" style="text-align:right;">
+  <span style="float:left;">Path&nbsp;&nbsp;</span> <span class="counter">Retrieve <a href=
+  "https://raw.github.com/Psychtoolbox-3/Psychtoolbox-3/beta/Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkTransferFileHelper.m">current version from GitHub</a> | View <a href=
+  "https://github.com/Psychtoolbox-3/Psychtoolbox-3/commits/beta/Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkTransferFileHelper.m">changelog</a></span>
+</div>
+<div class="code">
+  <code>Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkOneLiners/EyelinkTransferFileHelper.m</code>
+</div>
+

docs/HDRViewer.md

@@ -31,7 +31,7 @@ https://www.openexr.com/downloads.html
 'highprecision' If set to 1, request floating point 16 fp16 display  
 output, instead of the default 10 bpc fixed point output of HDR-10.  
 If set to 2, will request a 16 bpc fixed point framebuffer, which allows for up  
-to 16 bpc linear precision, but in reality on early 2021 hardware at most 12 bpc.  
+to 16 bpc linear precision, but in reality on early 2025 hardware at most 12 bpc.  
 On most operating-systems + driver + gpu combos this 16 bpc mode will fail.  
 
 'windowed' If set to 1 and running on MS-Windows, create a non-fullscreen  

docs/HybridGraphics.md

@@ -33,26 +33,27 @@ outputs (internal flat panel and external video connectors like
 controlled and allows selection of which gpu is driving the  
 displays, the other gpu is powered down for maximum power saving.  
 
-# macOS, Linux on Apple hardware and on other muxed Laptops  
+# macOS, Linux on Apple hardware, and on other muxed Laptops  
 
-As of 2021, all past and current dual-gpu laptops from Apple (Intel  
+As of the year 2026, all past Intel dual-graphics laptops from Apple (Intel  
 [MacBookPro](MacBookPro) line with [NVidia](NVidia) or AMD gpu) are muxed. When using macOS, the  
 operating system controls the mux to select an appropriate gpu. For light  
 desktop and 2D use, the iGPU is active. Whenever a 3D application starts  
 up, e.g., Psychtoolbox, the iGPU gets disconnected and powered down and  
 the dGPU gets powered up and connected. From the perspective of  
 Psychtoolbox there essentially is only one GPU, which is the dGPU, either  
-a [NVidia](NVidia) or AMD graphics card. Apart from a couple of rather horrible  
-bugs, e.g., for the 2010 [MacBookPro](MacBookPro) with some recent versions of macOS,  
-this means that hybrid graphics under macOS usually "just works".  
+a [NVidia](NVidia) or AMD graphics card. This means that hybrid graphics under macOS  
+usually "just works".  
 
-If one uses an Apple [MacBookPro](MacBookPro) under Linux then the machine will run  
+If one uses an Apple Intel [MacBookPro](MacBookPro) under Linux then the machine will run  
 with either the dGPU active and the Laptop behaves like a machine with  
 one gpu, or the active gpu can be switched via the Linux "vgaswitcheroo"  
 mechanism. The same applies for other PC laptops which are equipped with  
 a mux. Iow. one can manually select the performance vs. power consumption  
 tradeoff.  
 
+# Muxless laptops  
+  
 Most modern common PC laptops are muxless though. The iGPU is hard-wired  
 to the video outputs, both to the laptop flat panel and the external  
 outputs. The iGPU is always active and drives the displays and takes care  
@@ -64,9 +65,9 @@ the iGPU and the iGPU then displays the images on behalf of the dGPU.
 This involves some significant overhead: Multiple milliseconds of time  
 are needed for each [Screen](Screen)('[Flip](Flip)') to copy image data from the dGPU to  
 the iGPU, and converting the data into a format the iGPU can display. For  
-this reason, display latency on a muxless laptop will always be longer  
-and absolute graphics performance lower than on a laptop which only has a  
-dGPU of the same model, or on a muxless laptop. A big problem is the need  
+this reason, display latency on a muxless laptop will always be longer,  
+and absolute graphics performance lower, than on a laptop which only has a  
+dGPU of the same model, or on a laptop with mux. A big problem is the need  
 to properly synchronize the rendering of the dGPU with the display of the  
 iGPU. Depending on how this synchronization or handshake is implemented,  
 visual stimulus onset timing and timestamping can be highly unreliable  
@@ -77,7 +78,7 @@ and inaccurate.
 On Microsoft Windows a handshake method is used which maintains good  
 framerates for video games and similar applications, but causes visual  
 stimulus onset timing and timestamping to be almost always completely  
-wrong, with observed errors in the range of +/- 33 msecs on a 60 Hz  
+wrong, e.g., with observed errors in the range of +/- 33 msecs on a 60 Hz  
 panel. That means that the dGPU is unusable if visual timing matters in  
 any way. The best you can do on a muxless laptop under Microsoft Windows  
 is to configure the driver to disable the dGPU and only use the iGPU for  
@@ -88,29 +89,21 @@ MS-Windows, even on regular single gpu laptops.
 
 # LINUX  
 
-On Linux, as of December 2021, good progress has been made in  
+On Linux, as of the year 2026, good progress has been made in  
 implementing methods which provide both good performance \*and\* reliable,  
 trustworthy, accurate visual timing and timestamping. Some - but not all!  
 - types of Laptop hardware should work well, but for all of them some  
 special configuration or software upgrades are needed.  
 
-We recommend [XServer](XServer) version 1.20.11 or later, and Mesa version 21.0.3 or  
-later, and Linux 5.11 or later, as this combination provides best  
-performance and ease of setup for all supported types of hybrid graphics  
-laptops. Users of Ubuntu Linux can simply install Ubuntu 20.04.3 LTS from  
-fresh installation media, or upgrade to 20.04.3 LTS from earlier Ubuntu  
-releases and then install the new hardware enablement stack (HWE) via ...  
-  
-sudo apt install --install-recommends linux-lowlatency-hwe-20.04  
+The minimum required software to make this work well under the native X11  
+X-Server is [XServer](XServer) version 1.20.11, Mesa version 21.0.3, and Linux 5.11.  
 
-... if it isn't already automatically installed after an upgrade to 20.04.3 LTS.  
+Any Linux distribution at least as recent and modern as Ubuntu 22.04 LTS  
+will provide all that is needed for good hybrid graphics support.  
 
 The following sections describe the current level and quality of support  
-for different types of hybrid graphics laptops, and required  
-configuration steps, assuming you have sufficiently up to date kernel,  
-X-Server and Mesa as explained in the previous paragraph. Psychtoolbox  
-would tell you if you need to upgrade your kernel, if you'd run it on a  
-muxless hybrid graphics Laptop.  
+for different types of hybrid graphics laptops, and required configuration  
+steps.  
 
 
 ### \* Laptops with an Intel iGPU combined with a [NVidia](NVidia) dGPU ("[NVidia](NVidia) Optimus" models):  
@@ -126,28 +119,27 @@ muxless hybrid graphics Laptop.
   gpu family [(GeForce]((GeForce) 800 series) or later, so you would need the  
   proprietary driver to take advantage of those later models.  
 
-  For using such gpu's with the [NVidia](NVidia) proprietary driver, choose a  
+  For using such gpu's with the [NVidia](NVidia) proprietary driver, you need a  
   driver of version 495.44 or later. It may work with earlier drivers,  
   e.g., maybe even from the 450 series, but was only "tested" with the  
-  495.44 driver. Linux 5.11 and X-Server 1.20.11 or later is strongly  
-  recommended. Iow. Ubuntu 20.04.3-LTS will HWE stack and all updates  
-  applied.  
+  495.44 driver. Ubuntu 22.04-LTS and later do have all needed software  
+  and modern enough [NVidia](NVidia) proprietary drivers for this to work well.  
 
   On Ubuntu, the "nvidia-settings" GUI tool allows you - in the PRIME  
   profiles section - to switch between "high performance" [NVidia](NVidia)  
-  graphics, standard "power efficient" Intel graphics. and "on demand"  
-  Optimus mode. You should select "On demand" and reboot. The command  
-  line tool "prime-select ondemand" does the same selection. This may  
-  also work with the other selections, but may require custom xorg.conf  
-  files in that case.  
+  graphics, standard "power efficient" Intel graphics, and "on demand"  
+  Optimus mode. You should select "On demand" and then reboot. The command  
+  line command "prime-select ondemand" will do the same. This may also  
+  work with the other selections, but may require custom xorg.conf files  
+  in that case.  
 
   Now you should be able to choose if you want to use the Intel iGPU or  
   the [NVidia](NVidia) dGPU for rendering:  
 
   Starting "octave" or "matlab" you would get to use the Intel iGPU, low  
   power consumption, full PTB feature set, but lower performance.  
 
-  Starting "octave' or "matlab" with the following prefix...  
+  Starting "octave' or "matlab" from a terminal with the following prefix...  
 
   \_\_NV\_PRIME\_RENDER\_OFFLOAD=1 \_\_GLX\_VENDOR\_LIBRARY\_NAME=nvidia octave  
   or  
@@ -172,13 +164,9 @@ muxless hybrid graphics Laptop.
 
 ### \* Laptops with an Intel iGPU combined with an AMD dGPU ("AMD Enduro" models):  
 
-  These should work very well out of the box on Ubuntu 20.04.3 LTS and  
+  These should work very well out of the box on Ubuntu 22.04 LTS and  
   later, as explained above.  
 
-  On other Linux distributions, make sure to install Linux 4.8.11 or  
-  later versions of the Linux kernel, together with X-Server 1.18 or  
-  later, and Mesa version 17.0 or later.  
-  
 ###   AMD Enduro hybrid graphics was tested with three PC setups:  
 
   - Intel HD "Haswell desktop" graphics chip + AMD Radeon R9 380 Tonga Pro.  
@@ -192,36 +180,37 @@ muxless hybrid graphics Laptop.
 ### \* Laptops with dual [NVidia](NVidia) gpus [NVidia](NVidia) iGPU + [NVidia](NVidia) dGPU:  
 
   Muxless would not work with any current official solution [1]. However,  
-  i am not aware of any recent muxless laptops - or any such muxless  
-  laptops actually - which use dual-[NVidia](NVidia) gpus. All known dual-[NVidia](NVidia)  
-  laptops are rather old (around year 2010 or earlier) and use a hardware  
-  mux, so Linux "vgaswitcheroo" mechanism can be used to switch between  
-  gpus for perfect results.  
+  i am not aware of any muxless laptops which use dual-[NVidia](NVidia) gpus. All  
+  known to us dual-[NVidia](NVidia) laptops are very old (around the year 2010 or  
+  earlier) and use a hardware mux, so Linux "vgaswitcheroo" mechanism can  
+  be used to switch between gpus for perfect results.  
 
 
 ### \* Laptops with dual AMD gpus AMD iGPU + AMD dGPU ("AMD Enduro" models):  
 
   Muxless is untested due to lack of suitable AMD dual-gpu hardware, but  
-  according to code review should work on the recommended Linux 5.11 and  
-  later for AMD iGPU's of type "Stoney", "Carrizo", "Raven2", "Renoir",  
-  "Picasso", "[VanGogh](VanGogh)" and later. Essentially most integrated graphics  
-  chips (APU's) in laptops or PC's with modern AMD Ryzen processors,  
-  except for early models which use [RavenRidge](RavenRidge) 1st generation iGPU's.  
-  Check product specs, but in general Ryzen 5 2000/3000 series machines  
-  may have the problematic [RavenRidge](RavenRidge) iGPU's, whereas recent Ryzen 7 4000  
-  series may have more modern and suitablg iGPU's  
+  according to code review should work under Linux 5.11 and later for  
+  AMD iGPU's of type "Stoney", "Carrizo", "Raven2", "Renoir", "Picasso",  
+  "[VanGogh](VanGogh)" and later. Essentially most integrated graphics chips (APU's)  
+  in laptops or PC's with modern AMD Ryzen processors, except for early  
+  models which use [RavenRidge](RavenRidge) 1st generation iGPU's. Check product specs,  
+  but in general Ryzen 5 2000/3000 series machines may have such  
+  problematic [RavenRidge](RavenRidge) iGPU's, whereas recent Ryzen 7 4000 series may  
+  have more modern and suitablg iGPU's.  
 
   Stimuli should display without any artifacts and timing and timestamping  
   should be accurate and trustworthy. Performance should be good.  
 
 
 ### \* Laptops with AMD iGPU + [NVidia](NVidia) dGPU ("[NVidia](NVidia) Optimus" models):  
 
-  Psychtoolbox 3.0.18.2 and later has some support for this. Setup is the  
+  Psychtoolbox since version 3.0.18.2 has some support for this. Setup is the  
   same as in the section above for Intel iGPU + [NVidia](NVidia) dGPU. However, due  
-  to current limitations in the AMD Linux display driver amdgpu-kms as of  
-  at least Linux 5.16, proper pageflipping and scanout is not yet  
-  supported. Psychtoolbox will need to use (and force-enable) the desktop  
+  to limitations in the AMD Linux display driver amdgpu-kms as of at least  
+  Linux 5.16, proper pageflipping and scanout was not supported. The  
+  following info has not been reevaluated and updated in the last years,  
+  so the current state of support as of the year 2026 is unknown to us.  
+  Psychtoolbox will need to use (and force-enable) the desktop  
   compositor of your Ubuntu/Gnome/KDE desktop GUI to get proper high  
   quality pictures on the display. It will try some hackery to try to get  
   proper visual stimulus onset timing and timestamping, but the  
@@ -239,26 +228,17 @@ muxless hybrid graphics Laptop.
   "Mutter" X11 compositor and window manager), you can try the following  
   command setenv('PSYCH\_EXPERIMENTAL\_NETWMTS', '1') to opt-in into some highly  
   experimental mode which makes timing reliable and trustworthy, however while  
-  potentially reducing framerate. Additional downsides are that currently only  
-  single-window use with [Screen](Screen)('[Flip](Flip)') will work, also no more fancy things like  
-  flip events, async flips, frame-sequential stereo or VRR. This is a construction site!  
-  
-  I also have developed experimental patches to the Linux amdgpu driver to  
-  lift all these limitations on AMD to get the same excellent performance and  
-  reliability as with Intel iGPU's, but the current patches are hacky and  
-  unlikely to get accepted into official Linux kernels in their current  
-  state. Time permitting i will try to get those integrated properly.  
-  Meanwhile, these only exist on my development machine and i haven't  
-  decided on the conditions under which these may be made available to  
-  Psychtoolbox users. The only sure thing is that it won't happen free of  
-  cost, as this work requires a lot of time and money.  
+  potentially reducing framerate. Additional downsides are that currently  
+  only single-window use with [Screen](Screen)('[Flip](Flip)') will work, also no more  
+  fancy things like flip events, async flips, frame-sequential stereo or  
+  VRR. This is a construction site!  
 
 
 For those combinations that should work (Intel iGPU + [NVidia](NVidia)/AMD dGPU  
-"Optimus/Enduro", and AMD iGPU + AMD dGPU), after you've upgraded to all  
-the required software, the following setup steps are needed for muxless  
-PRIME mode. Note that these \*do not apply\* to Optimus with the proprietary  
-graphics driver from [NVidia](NVidia), for which setup was explained above:  
+"Optimus/Enduro", and AMD iGPU + AMD dGPU), the following setup steps are  
+needed for muxless PRIME mode. Note that these \*do not apply\* to Optimus  
+with the proprietary graphics driver from [NVidia](NVidia), for which setup was  
+explained above:  
 
 1. Run the "[XOrgConfCreator](XOrgConfCreator)" script to create a proper [XOrg](XOrg) configuration file,  
    and then "[XOrgConfSelector](XOrgConfSelector)" to switch to that configuration file, logout and  

docs/LMSToMacBoyn.md

@@ -1,7 +1,7 @@
 # [LMSToMacBoyn](LMSToMacBoyn)
 ##### >[Psychtoolbox](Psychtoolbox)>[PsychColorimetric](PsychColorimetric)
 
-ls = [LMSToMacBoyn](LMSToMacBoyn)(LMS,[T\_cones,T\_lum])  
+[ls, factorsLMS] = [LMSToMacBoyn](LMSToMacBoyn)(LMS,[T\_cones,T\_lum],[lumReturnFlag)  
 
 Compute [MacLeod](MacLeod)-Boynton chromaticity from cone exciation coordinates.  
 This is L/Lum and S/Lum, with appropriate normalization as described  
@@ -32,6 +32,24 @@ When you use the CIE cone fundamentals and corresponding luminance
 functions, this procedure yields the [MacLeod](MacLeod)-Boynton chromaticity  
 diagrams as specified in CIE 170-2:2015.  
 
+It would have been smarter to write this routine to return lsY rather  
+than just ls, long ago.  Getting Y back makes it easier to convert back  
+to LMS, and also be consistent with the way other conversions to  
+chromaticity are set up.  Changing this now would probably break some  
+existing code, so instead this routine now takes an optional fourth  
+argument that returns the luminance used in the denominator.  If you ask  
+for this, you need to provide T\_LMS and T\_Y as well, which is recommended  
+for clarity in any case.  Set lumReturnFlag = 1 on call to get back three  
+vectors with Y (the normalizing denominator) as the third coordinate.  In  
+general this will not be the same as L+M in the passed cone system, but  
+rather a weighted combination of L and M, with the weights computed from  
+the passed T\_LMS and T\_Y.  
+  
+The factorsLMS return value is a column vector with three entries that  
+specifies how this routine decided to scale the passed LMS cone  
+fundamentals to best approximate luminance and get the s axis scaling.  
+Note that if you pass LMS as the empty matrix, you can obtain this vector without doing much else.  
+  
 \*\* Legacy Usage: Just pass LMS values. In this case, we assume that the  
 passed LMS values were computed with respect to the Smith-Pokorny  
 fundamentals normalized to a peak of 1 and Judd-Vos luminance (more or  
@@ -56,6 +74,11 @@ the gains of having this work as now specified in the CIE standard.
                seems good to match the standard. Thanks to Danny Garside  
                for pointing out the scaling specified in the 2015  
                standard.  
+06/16/25 dhb   Provide lurReturnFlag and corresponding output option, but  
+               keep code backward compatible when that is not passed.  
+         dhb   Return the factorsLM column vector computed by this  
+               routine, so that it is easily available to the caller if   
+               wanted.