Big year 2024 Eyelinktoolbox update by SR-Research, release candidate. #266
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
kleinerm
force-pushed
the
eyelinktoolboxrc
branch
2 times, most recently
from
f5af7e0
to
04e079e
Compare
kleinerm
force-pushed
the
master
branch
6 times, most recently
from
de61132
to
f23ccbe
Compare
kleinerm
force-pushed
the
master
branch
2 times, most recently
from
ebeb03f
to
e4f45b7
Compare
kleinerm
force-pushed
the
master
branch
2 times, most recently
from
476f760
to
1d9f069
Compare
kleinerm
force-pushed
the
eyelinktoolboxrc
branch
from
04e079e
to
ccffc98
Compare
- Rename SR-ResearchDemo/ folder to SR-ResearchDemos - Add many new and updated demo projects: SR-ResearchDemos/PursuitTarget/ SR-ResearchDemos/SimplePicture/ SR-ResearchDemos/SimpleVideo/ SR-ResearchDemos/GazeContingent/ SR-ResearchDemos/GazeContingent/GCFastSamples/ SR-ResearchDemos/GazeContingent/FixWindowFastSamples/ SR-ResearchDemos/GazeContingent/GCBufferedEvents/ SR-ResearchDemos/GazeContingent/GCBufferedEvents/BufferedEndSacEvents/ SR-ResearchDemos/GazeContingent/GCBufferedEvents/BufferedFixUpdateEvents/ SR-ResearchDemos/GazeContingent/FixWindowBufferedSamples/ SR-ResearchDemos/StereoPicture/ SR-ResearchDemos/MRI_BlockRecord/ - Use jpg files, not more space consuming bmp files in new demo project resources. - Create LegacyDemos/ folder for various old demos which no longer represent best practices and optimal use of the Eyelink toolbox: EyelinkShortDemos/ and GazeContingentDemos/ moved under LegacyDemos/
Psychtoolbox/PsychHardware/EyelinkToolbox/EyelinkBasic/
* update general info in Eyelink.m
* preserve but move & rename legacy camera setup functionality
* scripts from EyelinkBasic/ > EyelinkBasic/Legacy
Legacy/EyelinkLegacyCalDoneBeep.m
Legacy/EyelinkLegacyCalTargetBeep.m
Legacy/EyelinkLegacyClearCalDisplay.m
Legacy/EyelinkLegacyDrawCalTarget.m
Legacy/EyelinkLegacyEraseCalTarget.m
Legacy/EyelinkLegacyTargetModeDisplay.m
Legacy/EyelinkLegacyDoDriftCorrect.m
Legacy/EyelinkLegacyDoTrackerSetup.m
* split legacy portions of script from
EyelinkDoTrackerSetup.m > Legacy/EyelinkLegacyDoTrackerSetup.m
* New functionality
- Image & video calibration target support
- Misc changes to support for stereoMode
- Legacy implementation, PsychImaging support will be in future
updates
- File specific changes
* EyelinkGetKey.m - Fix backspace key press check (el.ESC_KEY > el.BACKSPACE)
* EyelinkInitDefaults.m
- Misc cleanup comments & code
- Fix backstepping through calibration targets with el.BACKSPACE
- Add handling specific for macOS
- Add new fields to el struct
- for handling/configuring cam setup using image & video:
el.calTargetType
el.calImageTargetFilename
el.calImageInfo
el.calImageData
el.calImageTexture
el.calAnimationTargetFilename
el.calAnimationResetOnTargetMove
el.calAnimationAudioVolume
el.calAnimationLoopParam
el.calAnimationOpenSpecialFlags1
el.calAnimationSetIndexIsFrames
el.calAnimationOpenAsync
el.calAnimationOpenPreloadSecs
el.calAnimationWaitTex
el.calAnimationWaitTexClose
- for velocity models:
el.FIVE_SAMPLE_MODEL
el.NINE_SAMPLE_MODEL
el.SEVENTEEN_SAMPLE_MODEL
el.EL1000_TRACKER_MODEL
+ complimentary changes to EyelinkUpdateDefaults.m
PsychEyelinkDispatchCallback.m,
EyelinkLegacyDoTrackerSetup,
* EyelinkDoDriftCorrection.m
- misc cleanup/verbosity of comments
- related support for
- image/video calibration
- stereoMode
- general optimizations using nested functions
Many old legacy support functions have been moved from the EyelinkBasic folder to a Legacy/ subfolder, and renamed to signal their legacy/deprecated status.
These old demos may encourage EyeLink users to adapt integration conventions not in line with up-to-date recommendations from SR Research. Other functionality will be adapted into SR Research demo projects (e.g. spatial gaussian mask) in the future.
We use Unix LF, not MS-Windows / MS-DOS CRLF.
…PsychImaging. The more modern way to setup defaults and open / configure onscreen windows.
Add a new field to el struct - el.ppa_pahandle - for explicit
support and passing of a PsychPortAudio device handle created
either from PsychPortAudio('Open', ...) or when used with a
master device from PsychPortAudio('OpenSlave', ...).
EyelinkInitDefaults() inits el.ppa_pahandle to empty.
EyelinkUpdateDefaults() can either open a PsychPortAudio
default device itself when isempty(el.ppa_pahandle), for
Snd() interop, or simply use whatever was assigned by
user script itself.
PsychEyelinkDispatchCallback() uses the el.ppa_pahandle if
available.
The Eyelink mex files Eyelink('Shutdown') function is
extended to call back into a new "shutdown and cleanup"
function inside PsychEyelinkDispatchCallback() to close
self-opened PsychPortAudio devices. It also calls
'clear PsychEyelinkDispatchCallback' if a callback is
assigned as the standard PsychEyelinkDispatchCallback,
to clear internal, stale after shutdown, PsychPortAudio
buffer handles which are stored 'persistent' inside
PsychEyelinkDispatchCallback.m
-> This commit needs a Eyelink mex file rebuild. Without
it, the new PsychPortAudio support will still mostly
work, but releasing the driver will not! A 'clear all'
is needed if Eyelink mex files have not yet been rebuilt
in the initial release of this new functionality.
-> This commit also contains an unrelated massive white-space
cleanup in PsychEyelink.c, which is incomplete and should
not have ever been done as part of this commit! But such is
life...
Also fix misplacement of PsychDefaultSetup(2); calls. They must be at the beginning of each script, before any other Psychtoolbox functions.
…eanups. These are based on suggestions by Mario Kleiner for SR-Research pull request #816.
For the new setup functions for tracker setup and drift correction which use videos as calibration targets, immediately following 'OpenMovie', the movie time index is already zero, so no need for an extra SetMovieTimeIndex call.
help FUNCTIONNAME otherwise only works in Octave, not in Matlab. Also fix some names in warning() messages.
Needed for basic testing of PsychEyelinkDispatchCallback.m without access to an actual Eyelink system.
This failed with good old EyelinkGetTrackerImageDemo.m, due to unsatisified ~any(...) condition wrt. dbstack(). Now it works. I don't know why that dbstack() check is there in the first place, but it clearly caused trouble.
EyelinkDoDriftCorrect(), EyelinkLegacyDoTrackerSetup(), and EyelinkTargetModeDisplay() had various references to no longer existing other legacy functions, as the legacy fixes were incomplete. Fix up names of functions in calls. Also improve legacy warning() messages and help texts a bit, to tell users what to do instead of using legacy functions. This new legacy code was clearly not tested at all, and if it's not tested, it's broken! Ofc. it is still not tested, as I lack the needed hardware.
… support for Octave. Nested functions are used needlessly. These can not operate on global variables like eyelinkanimationtarget in Octave as they'd do on Matlab, so this is totally broken. Clearly this code has not been tested on Octave, at least not on Octave 5.2 which is the version we must still support for Eyelink toolbox, as long as we still support Ubuntu 20.04 LTS! Rewrite handling of global eyelinkanimationtarget to fix this. Testing of this is very limited, as I lack Eyelink hardware to properly test, so only the obvious bugs were fixed.
…ty'). A verbosity query does not need a new verbosity level that doesn't do anything.
- Clarify some warning / help messages. - Improve interop with Snd() in the Snd() fallback path. - Bug fix in the fallback path for unknown sound spec in EyelinkMakeSound. I am not convinced that having the Snd() fallback at all is a good idea, given we now have 3 separate sound output implementations, depending if el.ppa_pahandle is passed or not, and if EyelinkUpdateDefaults() is called or not, with three different behaviors. This may confuse users. But at least it is probably less buggy, and the design is a different decision.
…Buffer.
While this increases code complexity and issues with proper resource
management (added a memory leak already), it doesn't bring any meaningful
performance gain here, as measured:
Execution time for PsychPortAudio('FillBuffer') on a 7 year old low-end
machine under Ubuntu 20.04.6-LTS:
With ppa_beep_buffers / PsychPortAudio('CreateBuffer'): 63 - 200 usecs.
With simple beep_waveforms instead: 77 - 337 usecs.
A speed up of a non-time critical function by 140 usecs doesn't matter
in relation to the added complexity and potential for bugs and maintenance
overhead.
-> Remove it.
…bals. Get rid of global variables as much as possible. Optimize text drawing for the eye camera images text bits by getting rid of the pointless offscreen window. Now we are almost 3 times faster than before, with way more simple code.
…les.
Turned out that changing Eyelink('Verbosity', v); also changed, e.g.,
PsychPortAudio('Verbosity')! Why? Because both mex files use a non-static
verbosity variable. At least on Octave, the way mex files are compiled
there. Matlab mex files were unaffected, duh!
Make verbosity static, as all callers should use the Verbosity()
function anyway for internal verbosity queries.
Also make eyelinkDisplayCallbackFunc[] static for tidyness, and some
small formatting fix.
This is not a good approach to reset internal state of the callback function at shutdown, as it would only work for this specific function. If users create their own callback function, derived from PsychEyelinkDispatchCallback.m, e.g., just slightly modified or extended, but under a different name, they'd expect identical shutdown/cleanup behaviour, which would not be the case. Lets instead use the special cleanup -1 command code instead to do such stuff more cleanly and with less surprises for users. Also some small formatting fixes.
…variables.
For a full state reset when called via command code -1 "cleanup" during
Eyelink('Shutdown').
kleinerm
force-pushed
the
eyelinktoolboxrc
branch
from
ccffc98
to
bd6ebc8
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
No description provided.