/* PsychYieldIntervalSeconds() - Yield the cpu for given 'delaySecs'
*
* PsychYieldIntervalSeconds() differs from PsychWaitIntervalSeconds() in that
* it is supposed to release the cpu to other threads or processes for *at least*
* the given amount of time 'delaySecs', instead of *exactly* 'delaySecs'.
*
* If one wants to wait an exact amount of time, one uses PsychWaitIntervalSeconds().
* If one just "has nothing to do" for some minimum amount of time, and wants to
* play nice to other threads/processes and exact timing is not crucial, then
* this is the routine of choice. Typical use is within polling loops, where one
* wants to pause between polling cycles and it doesn't matter if the pause takes
* a bit longer.
*
* A 'delaySecs' of <= zero will just release the cpu for the remainder of
* the current scheduling timeslice. If you don't know what to do, choose a
* zero setting.
*
*/
void PsychYieldIntervalSeconds(double delaySecs)
{
if (delaySecs <= 0) {
// Yield cpu for remainder of this timeslice:
sched_yield();
}
else {
// On OS/X we use standard wait ops - they're good for us:
PsychWaitIntervalSeconds(delaySecs);
}
}
PsychError PsychModuleInit(void)
{
//register the project exit function
PsychErrorExit(PsychRegisterExit(&PsychPortAudioExit));
// Register the project function which is called when the module
// is invoked with no arguments:
PsychErrorExit(PsychRegister(NULL, &PSYCHPORTAUDIODisplaySynopsis));
// Report the version
PsychErrorExit(PsychRegister("Version", &MODULEVersion));
// Register the module name
PsychErrorExit(PsychRegister("PsychPortAudio", NULL));
// Register synopsis and named subfunctions.
PsychErrorExit(PsychRegister("Verbosity", &PSYCHPORTAUDIOVerbosity));
PsychErrorExit(PsychRegister("Open", &PSYCHPORTAUDIOOpen));
PsychErrorExit(PsychRegister("OpenSlave", &PSYCHPORTAUDIOOpenSlave));
PsychErrorExit(PsychRegister("Close", &PSYCHPORTAUDIOClose));
PsychErrorExit(PsychRegister("Start", &PSYCHPORTAUDIOStartAudioDevice));
PsychErrorExit(PsychRegister("RescheduleStart", &PSYCHPORTAUDIORescheduleStart));
PsychErrorExit(PsychRegister("Stop", &PSYCHPORTAUDIOStopAudioDevice));
PsychErrorExit(PsychRegister("FillBuffer", &PSYCHPORTAUDIOFillAudioBuffer));
PsychErrorExit(PsychRegister("RefillBuffer", &PSYCHPORTAUDIORefillBuffer));
PsychErrorExit(PsychRegister("GetDevices", &PSYCHPORTAUDIOGetDevices));
PsychErrorExit(PsychRegister("GetStatus", &PSYCHPORTAUDIOGetStatus));
PsychErrorExit(PsychRegister("LatencyBias", &PSYCHPORTAUDIOLatencyBias));
PsychErrorExit(PsychRegister("GetAudioData", &PSYCHPORTAUDIOGetAudioData));
PsychErrorExit(PsychRegister("RunMode", &PSYCHPORTAUDIORunMode));
PsychErrorExit(PsychRegister("SetLoop", &PSYCHPORTAUDIOSetLoop));
PsychErrorExit(PsychRegister("EngineTunables", &PSYCHPORTAUDIOEngineTunables));
PsychErrorExit(PsychRegister("GetOpenDeviceCount", &PSYCHPORTAUDIOGetOpenDeviceCount));
PsychErrorExit(PsychRegister("UseSchedule", &PSYCHPORTAUDIOUseSchedule));
PsychErrorExit(PsychRegister("AddToSchedule", &PSYCHPORTAUDIOAddToSchedule));
PsychErrorExit(PsychRegister("CreateBuffer", &PSYCHPORTAUDIOCreateBuffer));
PsychErrorExit(PsychRegister("DeleteBuffer", &PSYCHPORTAUDIODeleteBuffer));
PsychErrorExit(PsychRegister("SetOpMode", &PSYCHPORTAUDIOSetOpMode));
PsychErrorExit(PsychRegister("DirectInputMonitoring", &PSYCHPORTAUDIODirectInputMonitoring));
PsychErrorExit(PsychRegister("Volume", &PSYCHPORTAUDIOVolume));
// Setup synopsis help strings:
InitializeSynopsis(); //Scripting glue won't require this if the function takes no arguments.
// Setup module author:
PsychSetModuleAuthorByInitials("mk");
// Call wait-routine for 0.1 secs: This to initialize the time glue on MS-Windows,
// so the first call to a timing function won't delay:
PsychWaitIntervalSeconds(0.1);
// Startup finished.
return(PsychError_none);
}
PsychError PsychModuleInit(void)
{
//register the project exit function
PsychErrorExit(PsychRegisterExit(&PsychCVExit));
// Register the project function which is called when the module
// is invoked with no arguments:
PsychErrorExit(PsychRegister(NULL, &PSYCHCVDisplaySynopsis));
// Report the version
#if PSYCH_SYSTEM == PSYCH_OSX
PsychErrorExit(PsychRegister("Version", &MODULEVersion));
#endif
// Register the module name
PsychErrorExit(PsychRegister("PsychCV", NULL));
// Register synopsis and named subfunctions.
PsychErrorExit(PsychRegister("Verbosity", &PSYCHCVVerbosity));
#ifdef PSYCHCV_USE_OPENCV
PsychErrorExit(PsychRegister("OpenEyesInitialize", &PSYCHCVOpenEyesInitialize));
PsychErrorExit(PsychRegister("OpenEyesShutdown", &PSYCHCVOpenEyesShutdown));
PsychErrorExit(PsychRegister("OpenEyesParameters", &PSYCHCVOpenEyesParameters));
PsychErrorExit(PsychRegister("OpenEyesTrackEyePosition", &PSYCHCVOpenEyesTrackEyePosition));
#endif
PsychErrorExit(PsychRegister("CopyMatrixToMemBuffer", &PSYCHCVCopyMatrixToMemBuffer));
PsychErrorExit(PsychRegister("ARInitialize", &PSYCHCVARInitialize));
PsychErrorExit(PsychRegister("ARShutdown", &PSYCHCVARShutdown));
PsychErrorExit(PsychRegister("ARLoadMarker", &PSYCHCVARLoadMarker));
PsychErrorExit(PsychRegister("ARDetectMarkers", &PSYCHCVARDetectMarkers));
PsychErrorExit(PsychRegister("ARRenderImage", &PSYCHCVARRenderImage));
PsychErrorExit(PsychRegister("ARTrackerSettings", &PSYCHCVARTrackerSettings));
PsychErrorExit(PsychRegister("ARRenderSettings", &PSYCHCVARRenderSettings));
// Setup synopsis help strings:
InitializeSynopsis(); //Scripting glue won't require this if the function takes no arguments.
// Setup module author:
PsychSetModuleAuthorByInitials("mk");
// Call wait-routine for 0.1 secs: This to initialize the time glue on MS-Windows,
// so the first call to a timing function won't delay:
PsychWaitIntervalSeconds(0.1);
// Perform all remaining initialization:
PsychCVInitialize();
// Startup finished.
return(PsychError_none);
}
/* PsychYieldIntervalSeconds() - Yield the cpu for given 'delaySecs'
*
* PsychYieldIntervalSeconds() differs from PsychWaitIntervalSeconds() in that
* it is supposed to release the cpu to other threads or processes for *at least*
* the given amount of time 'delaySecs', instead of *exactly* 'delaySecs'.
*
* If one wants to wait an exact amount of time, one uses PsychWaitIntervalSeconds().
* If one just "has nothing to do" for some minimum amount of time, and wants to
* play nice to other threads/processes and exact timing is not crucial, then
* this is the routine of choice. Typical use is within polling loops, where one
* wants to pause between polling cycles and it doesn't matter if the pause takes
* a bit longer.
*
* A 'delaySecs' of <= zero will just release the cpu for the remainder of
* the current scheduling timeslice. If you don't know what to do, choose a
* zero setting.
*
*/
void PsychYieldIntervalSeconds(double delaySecs)
{
if (delaySecs <= 0) {
// Yield cpu for remainder of this timeslice:
sched_yield();
}
else {
// On Linux we use standard wait ops - they're good enough for us.
// However, we make sure that the wait lasts at least 2x the sleepwait_threshold,
// so the cpu gets certainly released to other threads, instead of getting hogged
// by busy-waiting for too short delaySecs intervals - which would be detrimental
// to the goals of PsychYieldIntervalSeconds():
delaySecs = (delaySecs > 2.0 * sleepwait_threshold) ? delaySecs : (2.0 * sleepwait_threshold);
PsychWaitIntervalSeconds(delaySecs);
}
}
// Display link callback: Needed so we can actually start the display link:
// Gets apparently called from a separate high-priority thread, close to vblank
// time. "inNow" is the timestamp of last vblank.
static CVReturn PsychCVDisplayLinkOutputCallback(CVDisplayLinkRef displayLink, const CVTimeStamp *inNow, const CVTimeStamp *inOutputTime,
CVOptionFlags flagsIn, CVOptionFlags *flagsOut, void *displayLinkContext)
{
double tVBlank;
CVTimeStamp tVbl;
double tHost;
// Retrieve screenId of associated display screen:
int screenId = (int) (long int) displayLinkContext;
// Extra guard against shutdown races:
if (NULL == cvDisplayLink[screenId]) return(kCVReturnSuccess);
// Translate CoreVideo inNow timestamp with time of last vbl from gpu time
// to host system time, aka our GetSecs() timebase:
memset(&tVbl, 0, sizeof(tVbl));
tVbl.version = 0;
tVbl.flags = kCVTimeStampHostTimeValid;
CVDisplayLinkTranslateTime(displayLink, inNow, &tVbl);
tVBlank = (double) tVbl.hostTime / (double) 1000000000;
// Store timestamp in our shared data structure, also increment virtual vblank counter:
PsychLockMutex(&(cvDisplayLinkData[screenId].mutex));
cvDisplayLinkData[screenId].vblCount++;
cvDisplayLinkData[screenId].vblTimestamp = tVBlank;
PsychUnlockMutex(&(cvDisplayLinkData[screenId].mutex));
// Low-level timestamp debugging requested?
if (PsychPrefStateGet_Verbosity() > 20) {
// Compare CV timestamps against host time for correctness check. We wait 4 msecs,
// then take tHost and hopefully tHost will be at least 4 msecs later than the
// computed vblank timestamp tVBlank:
PsychWaitIntervalSeconds(0.004);
PsychGetAdjustedPrecisionTimerSeconds(&tHost);
// Caution: Don't run from Matlab GUI! This printf will crash Matlab otherwise.
printf("CVCallback: %i : tHost = %lf secs, tVBlank = %lf secs. tHost - tVBlank = %lf secs.\n", screenId, tHost, tVBlank, tHost - tVBlank);
}
return(kCVReturnSuccess);
}
PsychError WAITSECSWaitSecs(void)
{
double waitPeriodSecs;
double now;
//check to see if the user supplied superfluous arguments
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(1));
if (!PsychCopyInDoubleArg(1, FALSE, &waitPeriodSecs)) {
// Called without arguments. Output synopsis:
WAITSECSSynopsis();
return(PsychError_none);
}
// Wait for requested interval:
PsychWaitIntervalSeconds(waitPeriodSecs);
// Return current system time at end of sleep:
PsychGetAdjustedPrecisionTimerSeconds(&now);
PsychCopyOutDoubleArg(1, FALSE, now);
return(PsychError_none);
}
PsychError SCREENGetMouseHelper(void)
{
#if PSYCH_SYSTEM == PSYCH_OSX
Point mouseXY;
UInt32 buttonState;
double numButtons, *buttonArray;
int i;
boolean doButtonArray;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//cap the numbers of inputs and outputs
PsychErrorExit(PsychCapNumInputArgs(1)); //The maximum number of inputs
PsychErrorExit(PsychCapNumOutputArgs(3)); //The maximum number of outputs
//Buttons.
// The only way I know to detect the number number of mouse buttons is directly via HID. The device reports
//that information but OS X seems to ignore it above the level of the HID driver, that is, no OS X API above the HID driver
//exposes it. So GetMouse.m function calls PsychHID detect the number of buttons and then passes that value to GetMouseHelper
//which returns that number of button values in a vector.
PsychCopyInDoubleArg(1, kPsychArgRequired, &numButtons);
if(numButtons > 32)
PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "numButtons must not exceed 32");
if(numButtons < 1)
PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "numButtons must exceed 1");
doButtonArray=PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)numButtons, (int)1, &buttonArray);
if(doButtonArray){
buttonState=GetCurrentButtonState();
for(i=0;i<numButtons;i++)
buttonArray[i]=(double)(buttonState & (1<<i));
}
//cursor position
GetMouse(&mouseXY);
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double)mouseXY.h);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double)mouseXY.v);
#endif
#if PSYCH_SYSTEM == PSYCH_WINDOWS
static unsigned char disabledKeys[256];
static unsigned char firsttime = 1;
int keysdown, i;
unsigned char keyState[256];
double* buttonArray;
double numButtons, timestamp;
PsychNativeBooleanType* buttonStates;
POINT point;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
// Retrieve optional number of mouse buttons:
numButtons = 0;
PsychCopyInDoubleArg(1, FALSE, &numButtons);
// Are we operating in 'GetMouseHelper' mode? numButtons>=0 indicates this.
if (numButtons>=0) {
// GetMouse-Mode: Return mouse button states and mouse cursor position:
PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)3, (int)1, &buttonArray);
// Query and return mouse button state:
PsychGetMouseButtonState(buttonArray);
// Query and return cursor position in global coordinates:
GetCursorPos(&point);
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) point.x);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) point.y);
}
else {
// 'KeyboardHelper' mode: We implement either KbCheck() or KbWait() via X11.
// This is a hack to provide keyboard queries until a PsychHID() implementation
// for Microsoft Windows is available...
if (firsttime) {
// First time init:
firsttime = 0;
memset(keyState, 0, sizeof(keyState));
memset(disabledKeys, 0, sizeof(disabledKeys));
// These keycodes are always disabled: 0, 255:
disabledKeys[0]=1;
disabledKeys[255]=1;
// Mouse buttone (left, right, middle) are also disabled by default:
disabledKeys[1]=1;
disabledKeys[2]=1;
disabledKeys[4]=1;
}
if (numButtons==-1 || numButtons==-2) {
// KbCheck()/KbWait() mode
do {
// Reset overall key state to "none pressed":
keysdown=0;
// Request current time of query:
PsychGetAdjustedPrecisionTimerSeconds(×tamp);
// Query state of all keys:
for(i=1;i<255;i++){
keyState[i] = (GetAsyncKeyState(i) & -32768) ? 1 : 0;
}
// Disable all keys that are registered in disabledKeys. Check if
// any non-disabled key is down.
for (i=0; i<256; i++) {
if (disabledKeys[i]>0) keyState[i] = 0;
keysdown+=(unsigned int) keyState[i];
}
// We repeat until any key pressed if in KbWait() mode, otherwise we
// exit the loop after first iteration in KbCheck mode.
if ((numButtons==-1) || ((numButtons==-2) && (keysdown>0))) break;
// Sleep for a millisecond before next KbWait loop iteration:
PsychWaitIntervalSeconds(0.001);
} while(1);
if (numButtons==-2) {
// KbWait mode: Copy out time value.
PsychCopyOutDoubleArg(1, kPsychArgOptional, timestamp);
}
else {
// KbCheck mode:
// Copy out overall keystate:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (keysdown>0) ? 1 : 0);
// Copy out timestamp:
PsychCopyOutDoubleArg(2, kPsychArgOptional, timestamp);
// Copy out keyboard state:
PsychAllocOutBooleanMatArg(3, kPsychArgOptional, 1, 256, 1, &buttonStates);
// Build 256 elements return vector:
for(i=0; i<255; i++) {
buttonStates[i] = (PsychNativeBooleanType)((keyState[i+1]) ? 1 : 0);
}
// Special case: Null out last element:
buttonStates[255] = (PsychNativeBooleanType) 0;
}
}
}
#endif
#if PSYCH_SYSTEM == PSYCH_LINUX
unsigned char keys_return[32];
char* keystring;
PsychGenericScriptType *kbNames;
CGDirectDisplayID dpy;
Window rootwin, childwin;
int i, j, mx, my, dx, dy;
unsigned int mask_return;
double numButtons, timestamp;
double* buttonArray;
PsychNativeBooleanType* buttonStates;
int keysdown;
XEvent event_return;
XKeyPressedEvent keypressevent;
int screenNumber;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychCopyInDoubleArg(1, kPsychArgRequired, &numButtons);
// Retrieve optional screenNumber argument:
screenNumber = 0;
PsychCopyInScreenNumberArg(2, FALSE, &screenNumber);
// Map screenNumber to X11 display handle and screenid:
PsychGetCGDisplayIDFromScreenNumber(&dpy, screenNumber);
// Are we operating in 'GetMouseHelper' mode? numButtons>=0 indicates this.
if (numButtons>=0) {
// Mouse pointer query mode:
XQueryPointer(dpy, RootWindow(dpy, PsychGetXScreenIdForScreen(screenNumber)), &rootwin, &childwin, &mx, &my, &dx, &dy, &mask_return);
// Copy out mouse x and y position:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) mx);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) my);
// Copy out mouse button state:
PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)numButtons, (int)1, &buttonArray);
// Bits 8, 9 and 10 of mask_return seem to correspond to mouse buttons
// 1, 2 and 3 of a mouse for some weird reason. Bits 0-7 describe keyboard modifier keys
// like Alt, Ctrl, Shift, ScrollLock, NumLock, CapsLock...
// We remap here, so the first three returned entries correspond to the mouse buttons and
// the rest is attached behind, if requested...
// Mouse buttons: Left, Middle, Right == 0, 1, 2, aka 1,2,3 in Matlab space...
for (i=0; i<numButtons && i<3; i++) {
buttonArray[i] = (mask_return & (1<<(i+8))) ? 1 : 0;
}
// Modifier keys 0 to 7 appended:
for (i=3; i<numButtons && i<3+8; i++) {
buttonArray[i] = (mask_return & (1<<(i-3))) ? 1 : 0;
}
// Everything else appended:
for (i=11; i<numButtons; i++) {
buttonArray[i] = (mask_return & (1<<i)) ? 1 : 0;
}
}
else {
// 'KeyboardHelper' mode: We implement either KbCheck() or KbWait() via X11.
// This is a hack to provide keyboard queries until a PsychHID() implementation
// for Linux is available...
if (numButtons==-1 || numButtons==-2) {
// KbCheck()/KbWait() mode:
// Switch X-Server into synchronous mode: We need this to get
// a higher timing precision.
XSynchronize(dpy, TRUE);
do {
// Reset overall key state to "none pressed":
keysdown=0;
// Request current keyboard state from X-Server:
XQueryKeymap(dpy, keys_return);
// Request current time of query:
PsychGetAdjustedPrecisionTimerSeconds(×tamp);
// Any key down?
for (i=0; i<32; i++) keysdown+=(unsigned int) keys_return[i];
// We repeat until any key pressed if in KbWait() mode, otherwise we
// exit the loop after first iteration in KbCheck mode.
if ((numButtons==-1) || ((numButtons==-2) && (keysdown>0))) break;
// Sleep for a few milliseconds before next KbWait loop iteration:
PsychWaitIntervalSeconds(0.01);
} while(1);
if (numButtons==-2) {
// Copy out time:
PsychCopyOutDoubleArg(1, kPsychArgOptional, timestamp);
}
else {
// KbCheck mode:
// Copy out overall keystate:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (keysdown>0) ? 1 : 0);
// copy out timestamp:
PsychCopyOutDoubleArg(2, kPsychArgOptional, timestamp);
// Copy keyboard state:
PsychAllocOutBooleanMatArg(3, kPsychArgOptional, 1, 256, 1, &buttonStates);
// Map 32 times 8 bitvector to 256 element return vector:
for(i=0; i<32; i++) {
for(j=0; j<8; j++) {
buttonStates[i*8 + j] = (PsychNativeBooleanType)(keys_return[i] & (1<<j)) ? 1 : 0;
}
}
}
}
else if (numButtons == -3) {
// numButtons == -3 --> KbName mapping mode:
// Return the full keyboard keycode to ASCII character code mapping table...
PsychAllocOutCellVector(1, kPsychArgOptional, 256, &kbNames);
for(i=0; i<256; i++) {
// Map keyboard scan code to KeySym:
keystring = XKeysymToString(XKeycodeToKeysym(dpy, i, 0));
if (keystring) {
// Character found: Return its ASCII name string:
PsychSetCellVectorStringElement(i, keystring, kbNames);
}
else {
// No character for this keycode:
PsychSetCellVectorStringElement(i, "", kbNames);
}
}
}
else if (numButtons == -4) {
// GetChar() emulation.
/* do { */
/* // Fetch next keypress event from queue, block if none is available... */
/* keystring = NULL; */
/* XNextEvent(dpy, &event_return); */
/* // Check for valid keypress event and extract character: */
/* if (event_return.type == KeyPress) { */
/* keypressevent = (XKeyPressedEvent) event_return; */
/* keystring = NULL; */
/* keystring = XKeysymToString(XKeycodeToKeysym(dpy, keypressevent.keycode, 0)); */
/* } */
/* // Repeat until a valid char is returned. */
/* } while (keystring == NULL); */
/* // Copy out character: */
/* PsychCopyOutCharArg(1, kPsychArgOptional, (char) keystring); */
/* // Copy out time: */
/* PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) keypressevent.time); */
}
}
#endif
return(PsychError_none);
}
PsychError PsychModuleInit(void)
{
// Initialize all Screen('Preference', ...); settings to startup defaults:
PrepareScreenPreferences();
// Register the project exit function
PsychErrorExitMsg(PsychRegisterExit(&ScreenExitFunction), "Failed to register the Screen exit function.");
// Register the project function which is called when the module
// is invoked with no arguments:
PsychErrorExitMsg(PsychRegister(NULL, &PsychDisplayScreenSynopsis), "Failed to register the Screen synopsis function.");
// Register the module name
PsychErrorExitMsg(PsychRegister("Screen", NULL), "Failed to register the Screen module name.");
// Register named subfunctions
// Enable for debugging purposes
PsychErrorExit(PsychRegister("Null", &SCREENNull));
PsychErrorExit(PsychRegister("Version", &MODULEVersion));
PsychErrorExit(PsychRegister("Computer", &SCREENComputer));
PsychErrorExit(PsychRegister("Screens", &SCREENScreens));
PsychErrorExit(PsychRegister("PixelSize",&SCREENPixelSize));
PsychErrorExit(PsychRegister("PixelSizes",&SCREENPixelSizes));
PsychErrorExit(PsychRegister("OpenWindow", &SCREENOpenWindow));
PsychErrorExit(PsychRegister("OpenOffscreenWindow", &SCREENOpenOffscreenWindow));
PsychErrorExit(PsychRegister("Close", &SCREENClose));
PsychErrorExit(PsychRegister("CloseAll", &SCREENCloseAll));
PsychErrorExit(PsychRegister("Flip", &SCREENFlip));
PsychErrorExit(PsychRegister("AsyncFlipBegin", &SCREENFlip));
PsychErrorExit(PsychRegister("AsyncFlipEnd", &SCREENFlip));
PsychErrorExit(PsychRegister("AsyncFlipCheckEnd", &SCREENFlip));
PsychErrorExit(PsychRegister("WaitUntilAsyncFlipCertain" , &SCREENWaitUntilAsyncFlipCertain));
PsychErrorExit(PsychRegister("FillRect", &SCREENFillRect));
PsychErrorExit(PsychRegister("GetImage", &SCREENGetImage));
PsychErrorExit(PsychRegister("PutImage", &SCREENPutImage));
PsychErrorExit(PsychRegister("HideCursorHelper", &SCREENHideCursorHelper));
PsychErrorExit(PsychRegister("ShowCursorHelper", &SCREENShowCursorHelper));
PsychErrorExit(PsychRegister("SetMouseHelper", &SCREENSetMouseHelper));
PsychErrorExit(PsychRegister("Rect", &SCREENRect));
PsychErrorExit(PsychRegister("WindowScreenNumber", &SCREENWindowScreenNumber));
PsychErrorExit(PsychRegister("Windows", &SCREENWindows));
PsychErrorExit(PsychRegister("WindowKind", &SCREENWindowKind));
PsychErrorExit(PsychRegister("IsOffscreen", &SCREENIsOffscreen));
PsychErrorExit(PsychRegister("ReadNormalizedGammaTable", &SCREENReadNormalizedGammaTable));
PsychErrorExit(PsychRegister("LoadNormalizedGammaTable", &SCREENLoadNormalizedGammaTable));
PsychErrorExit(PsychRegister("FrameRate", &SCREENNominalFramerate));
PsychErrorExit(PsychRegister("NominalFrameRate", &SCREENNominalFramerate));
PsychErrorExit(PsychRegister("glPoint", &SCREENglPoint));
PsychErrorExit(PsychRegister("gluDisk", &SCREENgluDisk));
PsychErrorExit(PsychRegister("FillOval", &SCREENFillOval));
PsychErrorExit(PsychRegister("FrameOval", &SCREENFrameOval));
PsychErrorExit(PsychRegister("TextModes", &SCREENTextModes));
PsychErrorExit(PsychRegister("TextMode", &SCREENTextMode));
PsychErrorExit(PsychRegister("TextSize", &SCREENTextSize));
PsychErrorExit(PsychRegister("TextStyle", &SCREENTextStyle));
PsychErrorExit(PsychRegister("TextFont", &SCREENTextFont));
PsychErrorExit(PsychRegister("TextBounds", &SCREENTextBounds));
PsychErrorExit(PsychRegister("DrawText", &SCREENDrawText));
PsychErrorExit(PsychRegister("TextColor", &SCREENTextColor));
PsychErrorExit(PsychRegister("Preference", &SCREENPreference));
PsychErrorExit(PsychRegister("MakeTexture", &SCREENMakeTexture));
PsychErrorExit(PsychRegister("DrawTexture", &SCREENDrawTexture));
PsychErrorExit(PsychRegister("FrameRect", &SCREENFrameRect));
PsychErrorExit(PsychRegister("DrawLine", &SCREENDrawLine));
PsychErrorExit(PsychRegister("FillPoly", &SCREENFillPoly));
PsychErrorExit(PsychRegister("FramePoly", &SCREENFramePoly));
PsychErrorExit(PsychRegister("GlobalRect", &SCREENGlobalRect));
PsychErrorExit(PsychRegister("DrawDots", &SCREENDrawDots));
PsychErrorExit(PsychRegister("GetTimeList", &SCREENGetTimeList));
PsychErrorExit(PsychRegister("ClearTimeList", &SCREENClearTimeList));
PsychErrorExit(PsychRegister("BlendFunction", &SCREENBlendFunction));
PsychErrorExit(PsychRegister("WindowSize", &SCREENWindowSize));
PsychErrorExit(PsychRegister("GetMouseHelper", &SCREENGetMouseHelper));
PsychErrorExit(PsychRegister("TextBackgroundColor", &SCREENTextBackgroundColor));
PsychErrorExit(PsychRegister("LineStipple", &SCREENLineStipple));
PsychErrorExit(PsychRegister("SelectStereoDrawBuffer", &SCREENSelectStereoDrawBuffer));
PsychErrorExit(PsychRegister("DrawingFinished", &SCREENDrawingFinished));
PsychErrorExit(PsychRegister("DrawLines", &SCREENDrawLines));
PsychErrorExit(PsychRegister("GetFlipInterval", &SCREENGetFlipInterval));
PsychErrorExit(PsychRegister("CloseMovie", &SCREENCloseMovie));
PsychErrorExit(PsychRegister("OpenMovie", &SCREENOpenMovie));
PsychErrorExit(PsychRegister("PlayMovie", &SCREENPlayMovie));
PsychErrorExit(PsychRegister("SetMovieTimeIndex", &SCREENSetMovieTimeIndex));
PsychErrorExit(PsychRegister("GetMovieTimeIndex", &SCREENGetMovieTimeIndex));
PsychErrorExit(PsychRegister("GetMovieImage", &SCREENGetMovieImage));
PsychErrorExit(PsychRegister("glPushMatrix", &SCREENglPushMatrix));
PsychErrorExit(PsychRegister("glPopMatrix", &SCREENglPopMatrix));
PsychErrorExit(PsychRegister("glLoadIdentity", &SCREENglLoadIdentity));
PsychErrorExit(PsychRegister("glTranslate", &SCREENglTranslate));
PsychErrorExit(PsychRegister("glScale", &SCREENglScale));
PsychErrorExit(PsychRegister("glRotate", &SCREENglRotate));
PsychErrorExit(PsychRegister("PreloadTextures", &SCREENPreloadTextures));
PsychErrorExit(PsychRegister("FillArc", &SCREENFillArc));
PsychErrorExit(PsychRegister("DrawArc", &SCREENDrawArc));
PsychErrorExit(PsychRegister("FrameArc", &SCREENFrameArc));
PsychErrorExit(PsychRegister("CopyWindow", &SCREENCopyWindow));
PsychErrorExit(PsychRegister("WaitBlanking", &SCREENWaitBlanking));
PsychErrorExit(PsychRegister("GetOpenGLTexture", &SCREENGetOpenGLTexture));
PsychErrorExit(PsychRegister("SetOpenGLTexture", &SCREENSetOpenGLTexture));
PsychErrorExit(PsychRegister("BeginOpenGL", &SCREENBeginOpenGL));
PsychErrorExit(PsychRegister("EndOpenGL", &SCREENEndOpenGL));
PsychErrorExit(PsychRegister("OpenVideoCapture", &SCREENOpenVideoCapture));
PsychErrorExit(PsychRegister("CloseVideoCapture", &SCREENCloseVideoCapture));
PsychErrorExit(PsychRegister("StartVideoCapture", &SCREENStartVideoCapture));
PsychErrorExit(PsychRegister("StopVideoCapture", &SCREENStopVideoCapture));
PsychErrorExit(PsychRegister("GetCapturedImage", &SCREENGetCapturedImage));
PsychErrorExit(PsychRegister("SetVideoCaptureParameter", &SCREENSetVideoCaptureParameter));
PsychErrorExit(PsychRegister("VideoCaptureDevices", &SCREENVideoCaptureDevices));
PsychErrorExit(PsychRegister("LoadCLUT", &SCREENLoadCLUT));
PsychErrorExit(PsychRegister("DisplaySize", &SCREENDisplaySize));
PsychErrorExit(PsychRegister("SetOpenGLTextureFromMemPointer", &SCREENSetOpenGLTextureFromMemPointer));
PsychErrorExit(PsychRegister("ColorRange", &SCREENColorRange));
PsychErrorExit(PsychRegister("HookFunction", &SCREENHookFunction));
PsychErrorExit(PsychRegister("OpenProxy", &SCREENOpenProxy));
PsychErrorExit(PsychRegister("TransformTexture", &SCREENTransformTexture));
PsychErrorExit(PsychRegister("DrawTextures", &SCREENDrawTextures));
PsychErrorExit(PsychRegister("GetWindowInfo", &SCREENGetWindowInfo));
PsychErrorExit(PsychRegister("GetOpenGLDrawMode", &SCREENGetOpenGLDrawMode));
PsychErrorExit(PsychRegister("Resolutions", &SCREENResolutions));
PsychErrorExit(PsychRegister("Resolution", &SCREENResolution));
PsychErrorExit(PsychRegister("ConfigureDisplay", &SCREENConfigureDisplay));
PsychErrorExit(PsychRegister("CreateMovie", &SCREENCreateMovie));
PsychErrorExit(PsychRegister("FinalizeMovie", &SCREENFinalizeMovie));
PsychErrorExit(PsychRegister("AddFrameToMovie", &SCREENGetImage));
PsychErrorExit(PsychRegister("AddAudioBufferToMovie", &SCREENAddAudioBufferToMovie));
PsychErrorExit(PsychRegister("GetFlipInfo", &SCREENGetFlipInfo));
PsychSetModuleAuthorByInitials("awi");
PsychSetModuleAuthorByInitials("dhb");
PsychSetModuleAuthorByInitials("dgp");
PsychSetModuleAuthorByInitials("kas");
PsychSetModuleAuthorByInitials("fjc");
PsychSetModuleAuthorByInitials("mk");
PsychSetModuleAuthorByInitials("cb");
InitializeSynopsis();
InitWindowBank();
PsychMovieInit();
PsychVideoCaptureInit();
PsychMovieWritingInit();
// Call wait-routine for 0.1 secs: This to initialize the time glue on MS-Windows,
// so the first call to a timing function won't delay:
PsychWaitIntervalSeconds(0.1);
// Reset the "userspaceGL" flag which tells PTB that userspace GL rendering was active
// due to Screen('BeginOpenGL') command.
PsychSetUserspaceGLFlag(FALSE);
// Call display glue init last, as its error handling could go crazy if triggered
// before the init routines above got executed:
InitializePsychDisplayGlue();
return(PsychError_none);
}
PsychError SCREENGetMouseHelper(void)
{
const char *valuatorInfo[]={"label", "min", "max", "resolution", "mode", "sourceID"};
int numValuatorStructFieldNames = 6;
int numIValuators = 0;
PsychGenericScriptType *valuatorStruct = NULL;
#if PSYCH_SYSTEM == PSYCH_OSX
Point mouseXY;
UInt32 buttonState;
double *buttonArray;
int numButtons, i;
psych_bool doButtonArray;
PsychWindowRecordType *windowRecord;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//cap the numbers of inputs and outputs
PsychErrorExit(PsychCapNumInputArgs(3)); //The maximum number of inputs
PsychErrorExit(PsychCapNumOutputArgs(6)); //The maximum number of outputs
//Buttons.
// The only way I know to detect the number number of mouse buttons is directly via HID. The device reports
//that information but OS X seems to ignore it above the level of the HID driver, that is, no OS X API above the HID driver
//exposes it. So GetMouse.m function calls PsychHID detect the number of buttons and then passes that value to GetMouseHelper
//which returns that number of button values in a vector.
PsychCopyInIntegerArg(1, kPsychArgRequired, &numButtons);
if(numButtons > 32)
PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "numButtons must not exceed 32");
// Special codes -10 to -15? --> Console keyboard queries:
if(numButtons <= -10 && numButtons >= -15) {
ConsoleInputHelper((int) numButtons);
return(PsychError_none);
}
if(numButtons < 1)
PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "numButtons must exceed 1");
doButtonArray=PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)numButtons, (int)1, &buttonArray);
if(doButtonArray){
buttonState=GetCurrentButtonState();
for(i=0;i<numButtons;i++)
buttonArray[i]=(double)(buttonState & (1<<i));
}
// Get cursor position:
#ifndef __LP64__
// 32-Bit Carbon version:
GetGlobalMouse(&mouseXY);
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double)mouseXY.h);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double)mouseXY.v);
#else
// 64-Bit HIToolbox version (OSX 10.5 and later):
HIPoint outPoint;
HIGetMousePosition(kHICoordSpaceScreenPixel, NULL, &outPoint);
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) outPoint.x);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) outPoint.y);
#endif
// Return optional keyboard input focus status:
if (numButtons > 0) {
// Window provided?
// We only have the function GetUserFocusWindow on 32-Bit Carbon.
// We have a drop-in replacement in OSX/PsychCocoaGlue.c for 64-Bit Cocoa.
if (PsychIsWindowIndexArg(2)) {
// Yes: Check if it has focus.
PsychAllocInWindowRecordArg(2, TRUE, &windowRecord);
if (!PsychIsOnscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "Provided window handle isn't an onscreen window, as required.");
}
PsychCopyOutDoubleArg(4, kPsychArgOptional, (double) (GetUserFocusWindow() == windowRecord->targetSpecific.windowHandle) ? 1 : 0);
} else
{
// No. Just always return "has focus":
PsychCopyOutDoubleArg(4, kPsychArgOptional, (double) 1);
}
}
// Return optional valuator values: Unimplemented on OS/X. Just return an empty matrix.
// The buttonArray is just a dummy assignment without any meaning.
PsychCopyOutDoubleMatArg(5, kPsychArgOptional, (int) 1, (int) 0, (int) 1, buttonArray);
PsychCopyOutDoubleMatArg(6, kPsychArgOptional, (int) 1, (int) 0, (int) 1, buttonArray);
#endif
#if PSYCH_SYSTEM == PSYCH_WINDOWS
static unsigned char disabledKeys[256];
static unsigned char firsttime = 1;
int keysdown, i, priorityLevel;
unsigned char keyState[256];
double* buttonArray;
double numButtons, timestamp;
PsychNativeBooleanType* buttonStates;
POINT point;
HANDLE currentProcess;
DWORD oldPriority = NORMAL_PRIORITY_CLASS;
const DWORD realtime_class = REALTIME_PRIORITY_CLASS;
PsychWindowRecordType *windowRecord;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
// Retrieve optional number of mouse buttons:
numButtons = 0;
PsychCopyInDoubleArg(1, FALSE, &numButtons);
// Are we operating in 'GetMouseHelper' mode? numButtons>=0 indicates this.
if (numButtons>=0) {
// GetMouse-Mode: Return mouse button states and mouse cursor position:
PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)3, (int)1, &buttonArray);
// Query and return mouse button state:
PsychGetMouseButtonState(buttonArray);
// Query and return cursor position in global coordinates:
GetCursorPos(&point);
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) point.x);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) point.y);
// Window provided?
if (PsychIsWindowIndexArg(2)) {
// Yes: Check if it has focus.
PsychAllocInWindowRecordArg(2, TRUE, &windowRecord);
if (!PsychIsOnscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "Provided window handle isn't an onscreen window, as required.");
}
PsychCopyOutDoubleArg(4, kPsychArgOptional, (double) (GetForegroundWindow() == windowRecord->targetSpecific.windowHandle) ? 1 : 0);
} else {
// No. Just always return "has focus":
PsychCopyOutDoubleArg(4, kPsychArgOptional, (double) 1);
}
// Return optional valuator values: Unimplemented on Windows. Just return an empty matrix.
// The ×tamp is just a dummy assignment without any meaning.
PsychCopyOutDoubleMatArg(5, kPsychArgOptional, (int) 1, (int) 0, (int) 1, ×tamp);
PsychCopyOutDoubleMatArg(6, kPsychArgOptional, (int) 1, (int) 0, (int) 1, buttonArray);
}
else {
// 'KeyboardHelper' mode: We implement either KbCheck() or KbWait() via X11.
// This is a hack to provide keyboard queries until a PsychHID() implementation
// for Microsoft Windows is available...
// Special codes -10 to -15? --> Console keyboard queries:
if(numButtons <= -10 && numButtons >= -15) {
ConsoleInputHelper((int) numButtons);
return(PsychError_none);
}
if (firsttime) {
// First time init:
firsttime = 0;
memset(keyState, 0, sizeof(keyState));
memset(disabledKeys, 0, sizeof(disabledKeys));
// These keycodes are always disabled: 0, 255:
disabledKeys[0]=1;
disabledKeys[255]=1;
// Mouse buttone (left, right, middle) are also disabled by default:
disabledKeys[1]=1;
disabledKeys[2]=1;
disabledKeys[4]=1;
}
if (numButtons==-1 || numButtons==-2) {
// KbCheck()/KbWait() mode
do {
// Reset overall key state to "none pressed":
keysdown=0;
// Request current time of query:
PsychGetAdjustedPrecisionTimerSeconds(×tamp);
// Query state of all keys:
for(i=1;i<255;i++){
keyState[i] = (GetAsyncKeyState(i) & -32768) ? 1 : 0;
}
// Disable all keys that are registered in disabledKeys. Check if
// any non-disabled key is down.
for (i=0; i<256; i++) {
if (disabledKeys[i]>0) keyState[i] = 0;
keysdown+=(unsigned int) keyState[i];
}
// We repeat until any key pressed if in KbWait() mode, otherwise we
// exit the loop after first iteration in KbCheck mode.
if ((numButtons==-1) || ((numButtons==-2) && (keysdown>0))) break;
// Sleep for a millisecond before next KbWait loop iteration:
PsychWaitIntervalSeconds(0.001);
} while(1);
if (numButtons==-2) {
// KbWait mode: Copy out time value.
PsychCopyOutDoubleArg(1, kPsychArgOptional, timestamp);
}
else {
// KbCheck mode:
// Copy out overall keystate:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (keysdown>0) ? 1 : 0);
// Copy out timestamp:
PsychCopyOutDoubleArg(2, kPsychArgOptional, timestamp);
// Copy out keyboard state:
PsychAllocOutBooleanMatArg(3, kPsychArgOptional, 1, 256, 1, &buttonStates);
// Build 256 elements return vector:
for(i=0; i<255; i++) {
buttonStates[i] = (PsychNativeBooleanType)((keyState[i+1]) ? 1 : 0);
}
// Special case: Null out last element:
buttonStates[255] = (PsychNativeBooleanType) 0;
}
}
if (numButtons==-3) {
// Priority() - helper mode: The 2nd argument is the priority level:
// Determine our processID:
currentProcess = GetCurrentProcess();
// Get current scheduling policy:
oldPriority = GetPriorityClass(currentProcess);
// Map to PTB's scheme:
switch(oldPriority) {
case NORMAL_PRIORITY_CLASS:
priorityLevel = 0;
break;
case HIGH_PRIORITY_CLASS:
priorityLevel = 1;
break;
case REALTIME_PRIORITY_CLASS:
priorityLevel = 2;
break;
default:
priorityLevel = 0;
}
// Copy it out as optional return argument:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) priorityLevel);
// Query if a new level should be set:
priorityLevel = -1;
PsychCopyInIntegerArg(2, kPsychArgOptional, &priorityLevel);
// Priority level provided?
if (priorityLevel > -1) {
// Map to new scheduling class:
if (priorityLevel > 2) PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "Invalid Priority level: Requested Priority() level must not exceed 2.");
switch(priorityLevel) {
case 0: // Standard scheduling:
SetPriorityClass(currentProcess, NORMAL_PRIORITY_CLASS);
// Disable any MMCSS scheduling for us:
PsychSetThreadPriority((psych_thread*) 0x1, 0, 0);
break;
case 1: // High priority scheduling:
SetPriorityClass(currentProcess, HIGH_PRIORITY_CLASS);
// Additionally try to schedule us MMCSS: This will lift us roughly into the
// same scheduling range as REALTIME_PRIORITY_CLASS, even if we are non-admin users
// on Vista and Windows-7 and later, however with a scheduler safety net applied.
PsychSetThreadPriority((psych_thread*) 0x1, 10, 0);
break;
case 2: // Realtime scheduling:
// This can fail if Matlab is not running under a user account with proper permissions:
if ((0 == SetPriorityClass(currentProcess, REALTIME_PRIORITY_CLASS)) || (REALTIME_PRIORITY_CLASS != GetPriorityClass(currentProcess))) {
// Failed to get RT-Scheduling. Let's try at least high priority scheduling:
SetPriorityClass(currentProcess, HIGH_PRIORITY_CLASS);
// Additionally try to schedule us MMCSS: This will lift us roughly into the
// same scheduling range as REALTIME_PRIORITY_CLASS, even if we are non-admin users
// on Vista and Windows-7 and later, however with a scheduler safety net applied.
PsychSetThreadPriority((psych_thread*) 0x1, 10, 0);
}
break;
}
}
// End of Priority() helper for Win32.
}
}
#endif
#if PSYCH_SYSTEM == PSYCH_LINUX
double myvaluators[100];
int numvaluators;
unsigned char keys_return[32];
char* keystring;
PsychGenericScriptType *kbNames;
CGDirectDisplayID dpy;
Window rootwin, childwin, mywin;
int i, j, mx, my, dx, dy;
double mxd, myd, dxd, dyd;
unsigned int mask_return;
double timestamp;
int numButtons;
double* buttonArray;
PsychNativeBooleanType* buttonStates;
int keysdown;
XEvent event_return;
XKeyPressedEvent keypressevent;
int screenNumber;
int priorityLevel;
struct sched_param schedulingparam;
PsychWindowRecordType *windowRecord;
int mouseIndex;
XIButtonState buttons_return;
XIModifierState modifiers_return;
XIGroupState group_return;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychCopyInIntegerArg(1, kPsychArgRequired, &numButtons);
// Retrieve optional screenNumber argument:
if (numButtons!=-5) {
screenNumber = 0;
if (PsychIsScreenNumberArg(2)) {
PsychCopyInScreenNumberArg(2, FALSE, &screenNumber);
}
// Map screenNumber to X11 display handle and screenid:
PsychGetCGDisplayIDFromScreenNumber(&dpy, screenNumber);
if (PsychIsWindowIndexArg(2)) {
PsychAllocInWindowRecordArg(2, TRUE, &windowRecord);
if (!PsychIsOnscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "Provided window handle isn't an onscreen window, as required.");
}
screenNumber = windowRecord->screenNumber;
mywin = windowRecord->targetSpecific.xwindowHandle;
// Map screenNumber to X11 display handle and screenid:
PsychGetCGDisplayIDFromScreenNumber(&dpy, screenNumber);
} else {
mywin = RootWindow(dpy, PsychGetXScreenIdForScreen(screenNumber));
}
}
// Default to "old school" mouse query - System default mouse via X core protocol:
mouseIndex = -1;
PsychCopyInIntegerArg(3, FALSE, &mouseIndex);
// Are we operating in 'GetMouseHelper' mode? numButtons>=0 indicates this.
if (numButtons>=0) {
// Mouse pointer query mode:
numvaluators = 0;
if (mouseIndex >= 0) {
// XInput-2 query for handling of multiple mouse pointers:
// Query input device list for screen:
int nDevices;
XIDeviceInfo* indevs = PsychGetInputDevicesForScreen(screenNumber, &nDevices);
// Sanity check:
if (NULL == indevs) PsychErrorExitMsg(PsychError_user, "Sorry, your system does not support individual mouse pointer queries.");
if (mouseIndex >= nDevices) PsychErrorExitMsg(PsychError_user, "Invalid 'mouseIndex' provided. No such device.");
if ((indevs[mouseIndex].use != XIMasterPointer) && (indevs[mouseIndex].use != XISlavePointer) && (indevs[mouseIndex].use != XIFloatingSlave)) {
PsychErrorExitMsg(PsychError_user, "Invalid 'mouseIndex' provided. Not a pointer device.");
}
// We requery the device info struct to retrieve updated live device state:
// Crucial for slave pointers to get any state at all, but also needed on
// master pointers to get the state of additional valuators, e.g., pen pressure,
// touch area, tilt etc. for digitizer tablets, touch pads etc. For master pointers,
// the primary 2 axis for 2D (x,y) position and the button/modifier state will be
// queried via a dedicated XIQueryPointer() call, so that info gets overriden.
indevs = XIQueryDevice(dpy, indevs[mouseIndex].deviceid, &numButtons);
modifiers_return.effective = 0;
// Query real number of mouse buttons and the raw button and axis state
// stored inside the device itself. This is done mostly because slave pointer
// devices don't support XIQueryPointer() so we get their relevant info from the
// XIDeviceInfo struct itself:
numButtons = 0;
numvaluators = 0;
memset(myvaluators, 0, sizeof(myvaluators));
if (PsychIsArgPresent(PsychArgOut, 6)) {
// Usercode wants valuator info structs:
for (i = 0; i < indevs->num_classes; i++) if (indevs->classes[i]->type == XIValuatorClass) numIValuators++;
PsychAllocOutStructArray(6, TRUE, numIValuators, numValuatorStructFieldNames, valuatorInfo, &valuatorStruct);
}
for (i = 0; i < indevs->num_classes; i++) {
// printf("Class %i: Type %i\n", i, (int) indevs->classes[i]->type);
if (indevs->classes[i]->type == XIButtonClass) {
// Number of buttons: For all pointers.
numButtons = ((XIButtonClassInfo*) indevs->classes[i])->num_buttons;
// Button state for slave pointers. Will get overriden for master pointers:
buttons_return.mask = ((XIButtonClassInfo*) indevs->classes[i])->state.mask;
buttons_return.mask_len = ((XIButtonClassInfo*) indevs->classes[i])->state.mask_len;
}
// Axis state for slave pointers. First two axis (x,y) will get overriden for master pointers:
if (indevs->classes[i]->type == XIValuatorClass) {
XIValuatorClassInfo* axis = (XIValuatorClassInfo*) indevs->classes[i];
if (axis->number == 0) mxd = axis->value; // x-Axis.
if (axis->number == 1) myd = axis->value; // y-Axis.
// Additional axis, e.g., digitizer tablet, touchpads etc.:
if (axis->number >= 0 && axis->number < 100) {
myvaluators[axis->number] = axis->value;
numvaluators = (numvaluators >= axis->number + 1) ? numvaluators : axis->number + 1;
}
// Assign valuator info struct, if requested:
if (valuatorStruct) {
if (axis->label != None) {
char* atomlabel = XGetAtomName(dpy, axis->label);
PsychSetStructArrayStringElement("label", axis->number, atomlabel, valuatorStruct);
XFree(atomlabel);
} else {
PsychSetStructArrayStringElement("label", axis->number, "None", valuatorStruct);
}
PsychSetStructArrayDoubleElement("min", axis->number, (double) axis->min, valuatorStruct);
PsychSetStructArrayDoubleElement("max", axis->number, (double) axis->max, valuatorStruct);
PsychSetStructArrayDoubleElement("resolution", axis->number, (double) axis->resolution, valuatorStruct);
PsychSetStructArrayDoubleElement("mode", axis->number, (double) axis->mode, valuatorStruct);
PsychSetStructArrayDoubleElement("sourceID", axis->number, (double) axis->sourceid, valuatorStruct);
}
// printf("AXIS %i, LABEL = %s, MIN = %f, MAX = %f, VAL = %f\n", axis->number, (char*) "NONE", (float) axis->min, (float) axis->max, (float) axis->value);
}
}
// Add 32 buttons for modifier key state vector:
numButtons += 32;
// A real master pointer: Use official query for mouse devices.
if (indevs->use == XIMasterPointer) {
// Query pointer location and state:
XIQueryPointer(dpy, indevs->deviceid, RootWindow(dpy, PsychGetXScreenIdForScreen(screenNumber)), &rootwin, &childwin, &mxd, &myd, &dxd, &dyd,
&buttons_return, &modifiers_return, &group_return);
}
// Copy out mouse x and y position:
PsychCopyOutDoubleArg(1, kPsychArgOptional, mxd);
PsychCopyOutDoubleArg(2, kPsychArgOptional, myd);
// Copy out mouse button state:
PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int) numButtons, (int)1, &buttonArray);
memset(buttonArray, 0, sizeof(double) * numButtons);
if (numButtons > 0) {
// Mouse buttons:
const int buttonOffset = 1; // Buttons start at bit 1, not 0 for some strange reason? At least so on Ubuntu 10.10 and 11.10 with 2 mice and 1 joystick?
for (i = buttonOffset; (i < numButtons - 32) && ((i / 8 ) < buttons_return.mask_len); i++) {
buttonArray[i - buttonOffset] = (double) ((buttons_return.mask[i / 8] & (1 << (i % 8))) ? 1 : 0);
}
// Free mask if retrieved via XIQueryPointer():
if (indevs->use == XIMasterPointer) free(buttons_return.mask);
// Append modifier key state from associated master keyboard. Last 32 entries:
for (i = 0; i < 32; i++) {
buttonArray[numButtons - 32 + i] = (double) ((modifiers_return.effective & (1 << i)) ? 1 : 0);
}
}
// Release live state info structure:
XIFreeDeviceInfo(indevs);
}
else {
// Old school core protocol query of virtual core pointer:
XQueryPointer(dpy, RootWindow(dpy, PsychGetXScreenIdForScreen(screenNumber)), &rootwin, &childwin, &mx, &my, &dx, &dy, &mask_return);
// Copy out mouse x and y position:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) mx);
PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) my);
// Copy out mouse button state:
PsychAllocOutDoubleMatArg(3, kPsychArgOptional, (int)1, (int)numButtons, (int)1, &buttonArray);
// Bits 8, 9 and 10 of mask_return seem to correspond to mouse buttons
// 1, 2 and 3 of a mouse for some weird reason. Bits 0-7 describe keyboard modifier keys
// like Alt, Ctrl, Shift, ScrollLock, NumLock, CapsLock...
// We remap here, so the first three returned entries correspond to the mouse buttons and
// the rest is attached behind, if requested...
// Mouse buttons: Left, Middle, Right == 0, 1, 2, aka 1,2,3 in Matlab space...
for (i=0; i<numButtons && i<3; i++) {
buttonArray[i] = (mask_return & (1<<(i+8))) ? 1 : 0;
}
// Modifier keys 0 to 7 appended:
for (i=3; i<numButtons && i<3+8; i++) {
buttonArray[i] = (mask_return & (1<<(i-3))) ? 1 : 0;
}
// Everything else appended:
for (i=11; i<numButtons; i++) {
buttonArray[i] = (mask_return & (1<<i)) ? 1 : 0;
}
}
// Return optional 4th argument: Focus state. Returns 1 if our window has
// keyboard input focus, zero otherwise:
XGetInputFocus(dpy, &rootwin, &i);
PsychCopyOutDoubleArg(4, kPsychArgOptional, (double) (rootwin == mywin) ? 1 : 0);
// Return optional valuator values:
PsychCopyOutDoubleMatArg(5, kPsychArgOptional, (int) 1, (int) numvaluators, (int) 1, &myvaluators[0]);
}
else {
// 'KeyboardHelper' mode: We implement either KbCheck() or KbWait() via X11.
// This is a hack to provide keyboard queries until a PsychHID() implementation
// for Linux is available...
// Special codes -10 to -15? --> Console keyboard queries:
if(numButtons <= -10 && numButtons >= -15) {
ConsoleInputHelper((int) numButtons);
return(PsychError_none);
}
if (numButtons==-1 || numButtons==-2) {
// KbCheck()/KbWait() mode:
// Switch X-Server into synchronous mode: We need this to get
// a higher timing precision.
XSynchronize(dpy, TRUE);
do {
// Reset overall key state to "none pressed":
keysdown=0;
// Request current keyboard state from X-Server:
XQueryKeymap(dpy, keys_return);
// Request current time of query:
PsychGetAdjustedPrecisionTimerSeconds(×tamp);
// Any key down?
for (i=0; i<32; i++) keysdown+=(unsigned int) keys_return[i];
// We repeat until any key pressed if in KbWait() mode, otherwise we
// exit the loop after first iteration in KbCheck mode.
if ((numButtons==-1) || ((numButtons==-2) && (keysdown>0))) break;
// Sleep for a few milliseconds before next KbWait loop iteration:
PsychWaitIntervalSeconds(0.01);
} while(1);
if (numButtons==-2) {
// Copy out time:
PsychCopyOutDoubleArg(1, kPsychArgOptional, timestamp);
}
else {
// KbCheck mode:
// Copy out overall keystate:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (keysdown>0) ? 1 : 0);
// copy out timestamp:
PsychCopyOutDoubleArg(2, kPsychArgOptional, timestamp);
// Copy keyboard state:
PsychAllocOutBooleanMatArg(3, kPsychArgOptional, 1, 256, 1, &buttonStates);
// Map 32 times 8 bitvector to 256 element return vector:
for(i=0; i<32; i++) {
for(j=0; j<8; j++) {
buttonStates[i*8 + j] = (PsychNativeBooleanType)(keys_return[i] & (1<<j)) ? 1 : 0;
}
}
}
}
else if (numButtons == -3) {
// numButtons == -3 --> KbName mapping mode:
// Return the full keyboard keycode to ASCII character code mapping table...
PsychAllocOutCellVector(1, kPsychArgOptional, 256, &kbNames);
for(i=0; i<256; i++) {
// Map keyboard scan code to KeySym:
keystring = XKeysymToString(XKeycodeToKeysym(dpy, i, 0));
if (keystring) {
// Character found: Return its ASCII name string:
PsychSetCellVectorStringElement(i, keystring, kbNames);
}
else {
// No character for this keycode:
PsychSetCellVectorStringElement(i, "", kbNames);
}
}
}
else if (numButtons == -4) {
// GetChar() emulation.
/* do { */
/* // Fetch next keypress event from queue, block if none is available... */
/* keystring = NULL; */
/* XNextEvent(dpy, &event_return); */
/* // Check for valid keypress event and extract character: */
/* if (event_return.type == KeyPress) { */
/* keypressevent = (XKeyPressedEvent) event_return; */
/* keystring = NULL; */
/* keystring = XKeysymToString(XKeycodeToKeysym(dpy, keypressevent.keycode, 0)); */
/* } */
/* // Repeat until a valid char is returned. */
/* } while (keystring == NULL); */
/* // Copy out character: */
/* PsychCopyOutCharArg(1, kPsychArgOptional, (char) keystring); */
/* // Copy out time: */
/* PsychCopyOutDoubleArg(2, kPsychArgOptional, (double) keypressevent.time); */
}
else if (numButtons==-5) {
// Priority() - helper mode: The 2nd argument is the priority level:
// Query scheduling policy and priority:
pthread_getschedparam(pthread_self(), &priorityLevel, &schedulingparam);
// If scheduling mode is a realtime mode (RoundRobin realtime RR, or FIFO realtime),
// then assign RT priority level (range 1-99) as current priorityLevel, otherwise
// assign non realtime priority level zero:
priorityLevel = (priorityLevel == SCHED_RR || priorityLevel == SCHED_FIFO) ? schedulingparam.sched_priority : 0;
// Copy it out as optional return argument:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) priorityLevel);
// Query if a new level should be set:
priorityLevel = -1;
PsychCopyInIntegerArg(2, kPsychArgOptional, &priorityLevel);
errno=0;
// Priority level provided?
if (priorityLevel > -1) {
// Map to new scheduling class:
if (priorityLevel > 99 || priorityLevel < 0) PsychErrorExitMsg(PsychErorr_argumentValueOutOfRange, "Invalid Priority level: Requested Priority() level must be between zero and 99!");
if (priorityLevel > 0) {
// Realtime FIFO scheduling and all pages of Matlab/Octave locked into memory:
schedulingparam.sched_priority = priorityLevel;
priorityLevel = pthread_setschedparam(pthread_self(), SCHED_FIFO, &schedulingparam);
if (priorityLevel == -1) {
// Failed!
if(!PsychPrefStateGet_SuppressAllWarnings()) {
printf("PTB-ERROR: Failed to enable realtime-scheduling with Priority(%i) [%s]!\n", schedulingparam.sched_priority, strerror(errno));
if (errno==EPERM) {
printf("PTB-ERROR: You need to run Matlab/Octave with root-privileges, or run the script PsychLinuxConfiguration once for this to work.\n");
}
}
errno=0;
}
else {
// RT-Scheduling active. Lock all current and future memory:
priorityLevel = mlockall(MCL_CURRENT | MCL_FUTURE);
if (priorityLevel!=0) {
// Failed! Report problem as warning, but don't worry further.
if(!PsychPrefStateGet_SuppressAllWarnings()) printf("PTB-WARNING: Failed to enable system memory locking with Priority(%i) [%s]!\n", schedulingparam.sched_priority, strerror(errno));
// Undo any possibly partial mlocks....
munlockall();
errno=0;
}
}
}
else {
// Standard scheduling and no memory locking:
schedulingparam.sched_priority = 0;
priorityLevel = pthread_setschedparam(pthread_self(), SCHED_OTHER, &schedulingparam);
if (priorityLevel == -1) {
// Failed!
if(!PsychPrefStateGet_SuppressAllWarnings()) {
printf("PTB-ERROR: Failed to disable realtime-scheduling with Priority(%i) [%s]!\n", schedulingparam.sched_priority, strerror(errno));
if (errno==EPERM) {
printf("PTB-ERROR: You need to run Matlab/Octave with root-privileges, or run the script PsychLinuxConfiguration once for this to work.\n");
}
}
errno=0;
}
munlockall();
errno=0;
}
// End of setup of new Priority...
}
// End of Priority() helper for Linux.
}
} // End of special functions handling for Linux...
#endif
return(PsychError_none);
}
PsychError PSYCHHIDKbTriggerWait(void)
{
pRecDevice deviceRecord;
int i, deviceIndex, numDeviceIndices;
long KeysUsagePage=0x07; // This is the keyboard usage page
long KeysUsage; // This will contain the key code of the trigger key
long KbDeviceUsagePages[NUMDEVICEUSAGES]= {0x01,0x01}, KbDeviceUsages[NUMDEVICEUSAGES]={0x06,0x07}; // Generic Desktop page (0x01), keyboard (0x06), keypad (0x07)
int numDeviceUsages=NUMDEVICEUSAGES;
int deviceIndices[PSYCH_HID_MAX_KEYBOARD_DEVICES];
pRecDevice deviceRecords[PSYCH_HID_MAX_KEYBOARD_DEVICES];
psych_bool isDeviceSpecified, foundUserSpecifiedDevice;
double *timeValueOutput;
IOHIDQueueInterface **queue;
HRESULT result;
IOHIDDeviceInterface122** interface=NULL; // This requires Mac OS X 10.3 or higher
IOReturn success;
IOHIDElementCookie triggerCookie;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2)); //Specify trigger key code and the deviceNumber of the keyboard or keypad to scan.
PsychHIDVerifyInit();
if(hidDataRef!=NULL) PsychErrorExitMsg(PsychError_user, "A queue is already running, you must call KbQueueRelease() before invoking KbTriggerWait.");
//Identify the trigger
{
int KeysUsageInteger;
if(!PsychCopyInIntegerArg(1, TRUE, &KeysUsageInteger)){
PsychErrorExitMsg(PsychError_user, "Keycode is required.");
}
KeysUsage=KeysUsageInteger;
}
//Choose the device index and its record
PsychHIDGetDeviceListByUsages(numDeviceUsages, KbDeviceUsagePages, KbDeviceUsages, &numDeviceIndices, deviceIndices, deviceRecords);
isDeviceSpecified=PsychCopyInIntegerArg(2, FALSE, &deviceIndex);
if(isDeviceSpecified){ //make sure that the device number provided by the user is really a keyboard or keypad.
for(i=0;i<numDeviceIndices;i++){
if(foundUserSpecifiedDevice=(deviceIndices[i]==deviceIndex))
break;
}
if(!foundUserSpecifiedDevice)
PsychErrorExitMsg(PsychError_user, "Specified device number is not a keyboard or keypad device.");
}else{ // set the keyboard or keypad device to be the first keyboard device or, if no keyboard, the first keypad
i=0;
if(numDeviceIndices==0)
PsychErrorExitMsg(PsychError_user, "No keyboard or keypad devices detected.");
else{
deviceIndex=deviceIndices[i];
}
}
deviceRecord=deviceRecords[i];
//Allocate and init out return arguments.
PsychAllocOutDoubleArg(1, FALSE, &timeValueOutput);
if(!timeValueOutput)
PsychErrorExitMsg(PsychError_system, "Failed to allocate memory for output.");
interface=deviceRecord->interface;
if(!interface)
PsychErrorExitMsg(PsychError_system, "Could not get interface to device.");
// The following bracketed clause will get a cookie corresponding to the
// trigger. If multiple keys were of interest, the code could be modified
// trivially to iterate over an array of KeysUsage to generate an array of
// corresponding cookies
{
CFArrayRef elements;
psych_bool usedDictionary=FALSE;
{
CFDictionaryRef dict=NULL;
// The next few lines define a dictionary describing the key of interest
// If they are omitted, the code will still work, but all elements will match
// initially rather than just the one key of interest, so the code will be
// slower since it will iterate through hundreds of keys
CFStringRef keys[2] = {CFSTR("UsagePage"), CFSTR("Usage")};
CFNumberRef values[2];
values[0] = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &KeysUsagePage);
values[1] = CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &KeysUsage);
if(values[0]!=NULL && values[1]!=NULL){
// Even if they are NULL, it will be ok since dict can be NULL at the expense of some loss of efficiency
dict = CFDictionaryCreate(kCFAllocatorDefault, (const void**)keys, (const void**)values, 2, &kCFCopyStringDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks);
}
// copyMatchinfElements requires IOHIDDeviceInterface122, thus Mac OS X 10.3 or higher
// elements would have to be obtained directly from IORegistry for 10.2 or earlier
// If dict==NULL, all elements will match, leading to some inefficiency
success = (*interface)->copyMatchingElements(interface, dict, &elements);
if(dict){
usedDictionary=TRUE;
CFRelease(dict);
}
if(values[0]) CFRelease(values[0]);
if(values[1]) CFRelease(values[1]);
if(!elements){
PsychErrorExitMsg(PsychError_user, "Specified key code not found on device.");
}
}
{
// elements will only contain one element in this implementation, but has the
// advantage of generalizing to future derived implementations that listen
// for multiple keys
CFIndex i;
for (i=0; i<CFArrayGetCount(elements); i++)
{
long number;
CFDictionaryRef element= CFArrayGetValueAtIndex(elements, i);
CFTypeRef object;
if(!element) continue;
if(!usedDictionary){
// Verify tht we are dealing with a keypad or keyboard
object = CFDictionaryGetValue(element, CFSTR(kIOHIDElementUsageKey));
if (object == 0 || CFGetTypeID(object) != CFNumberGetTypeID()) continue;
if (!CFNumberGetValue((CFNumberRef) object, kCFNumberLongType,&number)) continue;
if(number!=KeysUsage) continue;
// See if element corresponds to the desired key
object = CFDictionaryGetValue(element, CFSTR(kIOHIDElementUsagePageKey));
if (object == 0 || CFGetTypeID(object) != CFNumberGetTypeID()) continue;
if (!CFNumberGetValue((CFNumberRef) object, kCFNumberLongType, &number)) continue;
if(number!=KeysUsagePage) continue;
}
// Get the cookie for this element
object= (CFDictionaryGetValue(element, CFSTR(kIOHIDElementCookieKey)));
if (object == 0 || CFGetTypeID(object) != CFNumberGetTypeID()) continue;
if(!CFNumberGetValue((CFNumberRef) object, kCFNumberLongType, &number)) continue;
triggerCookie = (IOHIDElementCookie) number;
break;
}
if(CFArrayGetCount(elements)==i){
CFRelease(elements);
PsychErrorExitMsg(PsychError_user, "Specified key code not found on device.");
}
CFRelease(elements);
}
}
// Allocate for the queue
queue=(*interface)->allocQueue(interface);
if(!queue){
PsychErrorExitMsg(PsychError_system, "Failed to allocate event queue for detecting key press.");
}
// Create the queue
result = (*queue)->create(queue, 0, 8); // 8 events can be stored before the earliest event is lost
if (kIOReturnSuccess != result){
(*queue)->Release(queue);
(*queue)=NULL;
PsychErrorExitMsg(PsychError_system, "Failed to create event queue for detecting key press.");
}
// Add the trigger to the queue
// If multiple keys were of interest, their cookies could be added in turn
result = (*queue)->addElement(queue, triggerCookie, 0);
if (kIOReturnSuccess != result){
result = (*queue)->dispose(queue);
(*queue)->Release(queue);
(*queue)=NULL;
PsychErrorExitMsg(PsychError_system, "Failed to add trigger key to event queues.");
}
// Start the queue
result = (*queue)->start(queue);
if (kIOReturnSuccess != result){
result = (*queue)->dispose(queue);
(*queue)->Release(queue);
(*queue)=NULL;
PsychErrorExitMsg(PsychError_system, "Failed to start event queues.");
}
// Watch for the trigger
{
IOHIDEventStruct event;
while(1){
AbsoluteTime zeroTime = {0,0};
result = (*queue)->getNextEvent(queue, &event, zeroTime, 0);
if(kIOReturnSuccess==result) break;
PsychWaitIntervalSeconds((double)0.004); //surrender some time to other processes
// If it were of interest to trigger selectively on key press or key release,
// this could be evaluated by checking event.value (zero versus non-zero)
// but this would put more code inside the loop
// If multiple keys are registered via addElement (not the case here), the
// cookie for the key responsible for the event can be obtained from
// event.elementCookie
}
// If event.longValue is not NULL, the documentation indicates that it is up
// to the caller to deallocate it. The circumstances under which a non-NULL
// value would be generated are not specified. My guess is that some devices
// might return a 64-bit value (e.g., a tracking device coordinate).
// Keys, having only two states, shouldn't need this, but check and free to
// be safe
if ((event.longValueSize != 0) && (event.longValue != NULL)) free(event.longValue);
// Set the time, using the same strategy as PsychTimeGlue's PsychGetPrecisionTimerSeconds
// For code maintainability, it would be better if this conversion were performed
// by a function in PsychTimeGlue
{
Nanoseconds timeNanoseconds=AbsoluteToNanoseconds(event.timestamp);
UInt64 timeUInt64=UnsignedWideToUInt64(timeNanoseconds);
double timeDouble=(double)timeUInt64;
*timeValueOutput=timeDouble / 1000000000;
}
}
// Clean up
result = (*queue)->stop(queue);
// Code from Apple sometimes removes elements from queue before disposing and sometimes does not
// I can't see any reason to do so for a queue that's one line of code away from destruction
// and therefore haven't
result = (*queue)->dispose(queue);
(*queue)->Release(queue);
(*queue)=NULL; // Just in case queue is redefined as static in the future
// PsychGetPrecisionTimerSeconds(timeValueOutput); // Less precise strategy than using event.timestamp
return(PsychError_none);
}
PsychError COCOAEVENTBRIDGEGetChar(void)
{
static Boolean firstTime=TRUE;
double returnValue, inputValue;
static Boolean wasWindowOpenedFlag=FALSE;
Boolean isThere, inputValueBoolean, lostKeyWindowFlag;
// InitializeCocoaProc CocoaInitializeCocoa;
char readChar[2];
double readTime;
int numKeypresses, numOutputArgs;
CFDictionaryRef keypressDictionary=NULL, keypressModifierFlags=NULL;
CFStringRef keypressCharacter=NULL;
CFNumberRef keypressTime=NULL, keypressAddress=NULL, keypressTickCount=NULL;
double keypressTimeDouble, keypressTickCountDouble;
char keypressCharacterUTF8[2];
CFRange characterRange;
UniChar keypressCharacterUnicode[1];
double keypressCharacterAsValue, nowGetSecs, nowTickCount, characterTickCount, keypressAddressDouble;
Boolean loadBundleError;
//for the return structure in the second argument
const char *charTimeFieldNames[]={"ticks", "secs", "address", "alphaLock", "commandKey", "controlKey", "optionKey", "shiftKey", "numericKeypad", "functionKey"};
int numStructElements=1, numStructFieldNames=10;
PsychGenericScriptType *charTimeStruct;
CFNumberRef alphaLock, commandKey, controlKey, optionKey, shiftKey, numericKeypad, helpKey, functionKey;
char alphaLockCFlag, commandKeyCFlag, controlKeyCFlag, optionKeyCFlag, shiftKeyCFlag, numericKeypadCFlag, helpKeyCFlag, functionKeyCFlag;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check to see if the user supplied superfluous arguments
PsychErrorExit(PsychCapNumOutputArgs(2));
PsychErrorExit(PsychCapNumInputArgs(1));
loadBundleError=LoadCocoaBundle();
if(loadBundleError)
PsychErrorExitMsg(PsychError_internal, "Failed to load the cocoa bundle.");
//Open the window. OpenGetCharWindow() and MakeGetCharWindowInvisible() only act once if called repeatedly.
OpenGetCharWindow();
#ifndef DEBUG_USE_VISIBLE_WINDOW
MakeGetCharWindowInvisible();
#endif
StartKeyGathering();
MakeKeyWindow();
lostKeyWindowFlag=FALSE;
while(GetNumKeypresses() < 1){
PsychWaitIntervalSeconds((double)0.005);
//this would become an infinite loop if the user moves focus to another window, because our key collection window would never
//receive input. Therefore we detect if our window loses keyWindow status. We could be more forceful about this and bring the
//window back into focus, if we have access to NSApplication within our Cocoa bundle.
lostKeyWindowFlag=!IsKeyWindow();
if(lostKeyWindowFlag)
break;
}
// StopKeyGathering();
// if(!lostKeyWindowFlag)
// RevertKeyWindow(); //restores the key window to what it was before we took it.
if(!lostKeyWindowFlag){
keypressDictionary=(CFDictionaryRef)CopyReadNextKeypress();
if(keypressDictionary != NULL){
keypressCharacter=CFDictionaryGetValue(keypressDictionary, CFSTR("character"));
keypressTime=CFDictionaryGetValue(keypressDictionary, CFSTR("time"));
keypressModifierFlags=CFDictionaryGetValue(keypressDictionary, CFSTR("modifierFlags"));
keypressTickCount=CFDictionaryGetValue(keypressDictionary, CFSTR("tickCount"));
CFNumberGetValue(keypressTickCount, kCFNumberDoubleType, &keypressTickCountDouble);
keypressAddress=CFDictionaryGetValue(keypressDictionary, CFSTR("keyCode"));
CFNumberGetValue(keypressAddress, kCFNumberDoubleType, &keypressAddressDouble);
characterRange.location=0;
characterRange.length=1;
CFStringGetCharacters(keypressCharacter, characterRange, keypressCharacterUnicode);
if(keypressCharacterUnicode[0] <= (UniChar)127){ //it's a UTF8, MATLAB knows how do display this
keypressCharacterUTF8[0]=(char)(keypressCharacterUnicode[0]); //throw out what MATLAB will not print.
keypressCharacterUTF8[1]='\0';
//mexPrintf("character: %s\n", keypressCharacterUTF8);
PsychCopyOutCharArg(1, kPsychArgOptional, keypressCharacterUTF8);
}else{
keypressCharacterAsValue=(double)(keypressCharacterUnicode[0]);
//mexPrintf("character: %f\n", keypressCharacterAsValue);
PsychCopyOutDoubleArg(1, kPsychArgOptional, keypressCharacterAsValue);
}
// CFStringGetCString(keypressCharacter, keypressCharacterUTF8, 2, kCFStringEncodingUTF8);
CFNumberGetValue(keypressTime, kCFNumberDoubleType ,&keypressTimeDouble);
// mexPrintf("time: %d\n", keypressTimeDouble);
// PsychCopyOutDoubleArg(2, kPsychArgOptional, keypressTimeDouble);
numOutputArgs= PsychGetNumOutputArgs();
if(numOutputArgs==2){
alphaLock= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSAlphaShiftKeyMask"));
CFNumberGetValue(alphaLock, kCFNumberCharType, &alphaLockCFlag);
commandKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSCommandKeyMask"));
CFNumberGetValue(commandKey, kCFNumberCharType, &commandKeyCFlag);
controlKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSControlKeyMask"));
CFNumberGetValue(controlKey, kCFNumberCharType, &controlKeyCFlag);
optionKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSAlternateKeyMask"));
CFNumberGetValue(optionKey, kCFNumberCharType, &optionKeyCFlag);
shiftKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSShiftKeyMask"));
CFNumberGetValue(shiftKey, kCFNumberCharType, &shiftKeyCFlag);
numericKeypad= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSNumericPadKeyMask"));
CFNumberGetValue(numericKeypad, kCFNumberCharType, &numericKeypadCFlag);
// helpKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSHelpKeyMask"));
// CFNumberGetValue(helpKey, kCFNumberCharType, &helpKeyCFlag);
functionKey= CFDictionaryGetValue(keypressModifierFlags, CFSTR("NSFunctionKeyMask"));
CFNumberGetValue(functionKey, kCFNumberCharType, &functionKeyCFlag);
PsychAllocOutStructArray(2, TRUE, numStructElements, numStructFieldNames, charTimeFieldNames, &charTimeStruct);
// missing from OS X
// PsychSetStructArrayBooleanElement("mouseButton", 0, , charTimeStruct);
// same in OS X and OS 9
PsychSetStructArrayDoubleElement("ticks", 0, keypressTickCountDouble, charTimeStruct);
PsychSetStructArrayDoubleElement("secs", 0, keypressTimeDouble, charTimeStruct);
PsychSetStructArrayDoubleElement("address", 0, keypressAddressDouble, charTimeStruct);
PsychSetStructArrayBooleanElement("alphaLock", 0, (Boolean)alphaLockCFlag, charTimeStruct);
PsychSetStructArrayBooleanElement("commandKey", 0, (Boolean)commandKeyCFlag, charTimeStruct);
PsychSetStructArrayBooleanElement("controlKey", 0, (Boolean)controlKeyCFlag, charTimeStruct);
PsychSetStructArrayBooleanElement("optionKey", 0, (Boolean)optionKeyCFlag, charTimeStruct);
// new for OS X
PsychSetStructArrayBooleanElement("shiftKey", 0, (Boolean)shiftKeyCFlag, charTimeStruct);
PsychSetStructArrayBooleanElement("numericKeypad", 0, (Boolean)numericKeypadCFlag, charTimeStruct);
// PsychSetStructArrayBooleanElement("helpKey", 0, (Boolean)helpKeyCFlag, charTimeStruct);
PsychSetStructArrayBooleanElement("functionKey", 0, (Boolean)functionKeyCFlag, charTimeStruct);
}
CFRelease(keypressDictionary);
} //close: if(keypressDictionary != NULL){
}else{// if(!lostKeyWindowFlag){
//If we get to here, that means that GetChar was called, set its key gathering window to be the key window, and while waiting
//for key input another window was made the key window. How should we handle this case? Here we return nan for both arguments.
//If we prefer to return an error, this could be done in the .m file wrapper, "Getchar" instead of here in "CocoaEventBridge('Getchar');
PsychCopyOutDoubleArg(1, kPsychArgOptional, PsychGetNanValue());
PsychCopyOutDoubleArg(2, kPsychArgOptional, PsychGetNanValue());
}
return(PsychError_none);
}
/* PsychEnableNative10BitFramebuffer() - Enable/Disable native 10 bpc RGB framebuffer modes.
*
* This function enables or disables the native ARGB2101010 framebuffer readout mode of supported
* graphics hardware. Currently the ATI Radeon X1000/HD2000/HD3000 and later cards should allow this.
*
* This needs support from the Psychtoolbox kernel level support driver for low-level register reads
* and writes to the GPU registers.
*
* 'windowRecord' Is used to find the Id of the screen for which mode should be changed, as well as enable
* flags to see if a change is required at all, and the OpenGL context for some specific
* fixups. A value of NULL will try to apply the operation to all heads, but may only work
* for *disabling* 10 bpc mode, not for enabling it -- Mostly useful for a master reset to
* system default, e.g., as part of error handling or Screen shutdown handling.
* 'enable' True = Enable ABGR2101010 support, False = Disable ARGB2101010 support, reenable ARGB8888 support.
*
*/
boolean PsychEnableNative10BitFramebuffer(PsychWindowRecordType* windowRecord, boolean enable)
{
int i,si,ei, headid, screenId;
unsigned int lutreg, ctlreg, value, status;
// Child protection:
if (windowRecord && !PsychIsOnscreenWindow(windowRecord)) PsychErrorExitMsg(PsychError_internal, "Invalid non-onscreen windowRecord provided!!!");
// Either screenid from windowRecord or our special -1 "all Screens" Id:
screenId = (windowRecord) ? windowRecord->screenNumber : -1;
// Define range of screens: Either a single specific one, or all:
si = (screenId!=-1) ? screenId : 0;
ei = (screenId!=-1) ? screenId+1 : PsychGetNumDisplays();
#if PSYCH_SYSTEM == PSYCH_OSX || PSYCH_SYSTEM == PSYCH_LINUX
// Loop over all target screens:
for (i=si; i<ei; i++) {
// Map screenid to headid: For now we only support 2 heads and assume
// screenId 0 == head 0, all others equal head 1:
headid = (i<=0) ? 0 : 1;
// Select Radeon HW registers for corresponding heads:
lutreg = (headid == 0) ? RADEON_D1GRPH_LUT_SEL : RADEON_D2GRPH_LUT_SEL;
ctlreg = (headid == 0) ? RADEON_D1GRPH_CONTROL : RADEON_D2GRPH_CONTROL;
// Enable or Disable?
if (enable) {
// Enable:
// Switch hardware LUT's to bypass mode:
// We set bit 8 to enable "bypass LUT in 2101010 mode":
value = PsychOSKDReadRegister(screenId, lutreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (LUTReg read failed).\n");
return(false);
}
// Set the bypass bit:
value = value | 0x1 << 8;
PsychOSKDWriteRegister(screenId, lutreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (LUTReg write failed).\n");
return(false);
}
// Switch CRTC to ABGR2101010 readout mode:
// We set bit 8 to enable that mode:
value = PsychOSKDReadRegister(screenId, ctlreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (CTLReg read failed).\n");
return(false);
}
// Set 2101010 moe bit:
value = value | 0x1 << 8;
PsychOSKDWriteRegister(screenId, ctlreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (CTLReg write failed).\n");
return(false);
}
// Pipe should be in 10 bpc mode now...
if (PsychPrefStateGet_Verbosity() > 2) printf("PTB-INFO: System framebuffer switched to ARGB2101010 mode for screen %i [head %i].\n", i, headid);
}
else {
// Disable:
// Switch CRTC to ABGR8888 readout mode:
// We clear bit 8 to enable that mode:
value = PsychOSKDReadRegister(screenId, ctlreg, &status);
if (status) {
// This codepath gets always called in PsychCloseWindow(), so we should skip it
// silently if register read fails, as this is expected on MS-Windows and on all
// non-Radeon hardware and if kernel driver isn't loaded:
if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (CTLReg read failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: Readreg. ctlreg yields %lx\n", value);
// Clear 2101010 mode bit:
value = value & ~(0x1 << 8);
PsychOSKDWriteRegister(screenId, ctlreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (CTLReg write failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: ctlreg reset\n");
// Wait 500 msecs for GPU to settle:
PsychWaitIntervalSeconds(0.5);
// Switch hardware LUT's to standard mapping mode:
// We clear bit 8 to disable "bypass LUT in 2101010 mode":
value = PsychOSKDReadRegister(screenId, lutreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (LUTReg read failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: Readreg. lutreg yields %lx\n", value);
// Clear LUT bypass bit:
value = value & ~(0x1 << 8);
PsychOSKDWriteRegister(screenId, lutreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (LUTReg write failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: lutreg reset\n");
// Pipe should be in 8 bpc mode now...
if (PsychPrefStateGet_Verbosity() > 2) printf("PTB-INFO: System framebuffer switched to standard ARGB8888 mode for screen %i [head %i].\n", i, headid);
}
// Next display head...
}
#else
// This cool stuff not supported on the uncool Windows OS:
return(FALSE);
#endif
// Done.
return(TRUE);
}
/* PsychWaitForBufferswapPendingOrFinished()
* Waits until a bufferswap for window windowRecord has either already happened or
* bufferswap is certain.
* Input values:
* windowRecord struct of onscreen window to monitor.
* timestamp = Deadline for abortion of flip detection at input.
*
* Return values:
* timestamp = System time at polling loop exit.
* beamposition = Beamposition at polling loop exit.
*
* Return value: FALSE if swap happened already, TRUE if swap is imminent.
*/
bool PsychWaitForBufferswapPendingOrFinished(PsychWindowRecordType* windowRecord, double* timestamp, int *beamposition)
{
#if PSYCH_SYSTEM == PSYCH_OSX || PSYCH_SYSTEM == PSYCH_LINUX
CGDirectDisplayID displayID;
unsigned int primarySurface, secondarySurface;
unsigned int updateStatus;
double deadline = *timestamp;
// If we are called, we know that 'windowRecord' is an onscreen window.
int screenId = windowRecord->screenNumber;
// Retrieve display id and screen size spec that is needed later...
PsychGetCGDisplayIDFromScreenNumber(&displayID, screenId);
#define RADEON_D1GRPH_UPDATE 0x6144
#define RADEON_D2GRPH_UPDATE 0x6944
#define RADEON_SURFACE_UPDATE_PENDING 4
#define RADEON_SURFACE_UPDATE_TAKEN 8
// Just need to check if GPU low-level access is supported:
if (!PsychOSIsKernelDriverAvailable(screenId)) return;
// Driver is online. Enter polling loop:
while (TRUE) {
// Read surface address registers:
primarySurface = PsychOSKDReadRegister(screenId, (screenId <=0 ) ? RADEON_D1GRPH_PRIMARY_SURFACE_ADDRESS : RADEON_D2GRPH_PRIMARY_SURFACE_ADDRESS, NULL);
secondarySurface = PsychOSKDReadRegister(screenId, (screenId <=0 ) ? RADEON_D1GRPH_SECONDARY_SURFACE_ADDRESS : RADEON_D2GRPH_SECONDARY_SURFACE_ADDRESS, NULL);
// Read update status registers:
updateStatus = PsychOSKDReadRegister(screenId, (screenId <=0 ) ? RADEON_D1GRPH_UPDATE : RADEON_D2GRPH_UPDATE, NULL);
PsychGetAdjustedPrecisionTimerSeconds(timestamp);
if (primarySurface!=windowRecord->gpu_preflip_Surfaces[0] || secondarySurface!=windowRecord->gpu_preflip_Surfaces[1] || (updateStatus & (RADEON_SURFACE_UPDATE_PENDING | RADEON_SURFACE_UPDATE_TAKEN)) || (*timestamp > deadline)) {
// Abort condition: Exit loop.
break;
}
if (PsychPrefStateGet_Verbosity() > 9) {
printf("PTB-DEBUG: Head %i: primarySurface=%p : secondarySurface=%p : updateStatus=%i\n", ((screenId <=0) ? 0:1), primarySurface, secondarySurface, updateStatus);
}
// Sleep 200 microseconds, then retry:
PsychWaitIntervalSeconds(0.0002);
};
// Take timestamp and beamposition:
*beamposition = PsychGetDisplayBeamPosition(&displayID, screenId);
PsychGetAdjustedPrecisionTimerSeconds(timestamp);
// Exit due to timeout?
if (*timestamp > deadline) {
// Mark timestamp as invalid due to timeout:
*timestamp = -1;
}
// Return FALSE if bufferswap happened already, TRUE if swap is still pending:
return((updateStatus & RADEON_SURFACE_UPDATE_PENDING) ? TRUE : FALSE);
#else
// On Windows, we always return "swap happened":
return(FALSE);
#endif
}
PsychError SCREENGetMovieImage(void)
{
PsychWindowRecordType *windowRecord;
PsychWindowRecordType *textureRecord;
PsychRectType rect;
double deadline, tnow;
int moviehandle = -1;
int waitForImage = TRUE;
double requestedTimeIndex = -1;
double presentation_timestamp = 0;
int rc=0;
int specialFlags = 0;
int specialFlags2 = 0;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(6)); // Max. 6 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(2)); // Max. 2 output args.
// Get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
// Only onscreen windows allowed:
if(!PsychIsOnscreenWindow(windowRecord)) {
PsychErrorExitMsg(PsychError_user, "GetMovieImage called on something else than an onscreen window.");
}
// Get the movie handle:
PsychCopyInIntegerArg(2, TRUE, &moviehandle);
if (moviehandle==-1) {
PsychErrorExitMsg(PsychError_user, "GetMovieImage called without valid handle to a movie object.");
}
// Get the 'waitForImage' flag: If waitForImage == true == 1, we'll do a blocking wait for
// arrival of a new image for playback. Otherwise we will return with a 0-Handle if there
// isn't any new image available.
PsychCopyInIntegerArg(3, FALSE, &waitForImage);
// Get the requested timeindex for the frame. The default is -1, which means: Get the next image,
// according to current movie playback time.
PsychCopyInDoubleArg(4, FALSE, &requestedTimeIndex);
// Get the optional specialFlags flag:
PsychCopyInIntegerArg(5, FALSE, &specialFlags);
// Get the optional specialFlags2 flag:
PsychCopyInIntegerArg(6, FALSE, &specialFlags2);
PsychGetAdjustedPrecisionTimerSeconds(&deadline);
deadline += 5;
while (rc==0) {
rc = PsychGetTextureFromMovie(windowRecord, moviehandle, TRUE, requestedTimeIndex, NULL, NULL);
PsychGetAdjustedPrecisionTimerSeconds(&tnow);
if (rc<0 || (tnow > deadline)) {
// No image available and there won't be any in the future, because the movie has reached
// its end and we are not in looped playback mode:
if (tnow > deadline) printf("PTB-ERROR: In Screen('GetMovieImage') for movie %i: Timed out while waiting for new frame after 5 seconds!\n", moviehandle);
// No new texture available: Return a negative handle:
PsychCopyOutDoubleArg(1, TRUE, -1);
// ...and an invalid timestamp:
PsychCopyOutDoubleArg(2, FALSE, -1);
// Ready!
return(PsychError_none);
}
else if (rc==0 && waitForImage == 0) {
// We should just poll once and no new texture available: Return a null-handle:
PsychCopyOutDoubleArg(1, TRUE, 0);
// ...and an invalid timestamp:
PsychCopyOutDoubleArg(2, FALSE, -1);
// Ready!
return(PsychError_none);
}
else if (rc==0 && waitForImage != 0) {
// No new texture available yet. Just sleep a bit and then retry...
PsychWaitIntervalSeconds(0.005);
}
}
// New image available: Go ahead...
// Create a texture record. Really just a window record adapted for textures.
PsychCreateWindowRecord(&textureRecord); // This also fills the window index field.
// Set mode to 'Texture':
textureRecord->windowType=kPsychTexture;
// We need to assign the screen number of the onscreen-window.
textureRecord->screenNumber=windowRecord->screenNumber;
// It is always a 32 bit texture for movie textures:
textureRecord->depth=32;
textureRecord->nrchannels = 4;
// Create default rectangle which describes the dimensions of the image. Will be overwritten
// later on.
PsychMakeRect(rect, 0, 0, 10, 10);
PsychCopyRect(textureRecord->rect, rect);
// Other setup stuff:
textureRecord->textureMemorySizeBytes= 0;
textureRecord->textureMemory=NULL;
// Assign parent window and copy its inheritable properties:
PsychAssignParentWindow(textureRecord, windowRecord);
// Try to fetch an image from the movie object and return it as texture:
PsychGetTextureFromMovie(windowRecord, moviehandle, FALSE, requestedTimeIndex, textureRecord, ((specialFlags2 & 1) ? NULL : &presentation_timestamp));
// Assign GLSL filter-/lookup-shaders if needed: usefloatformat is always == 0 as
// our current movie engine implementations only return 8 bpc fixed textures.
// The 'userRequest' flag is set if specialmode flag is set to 8.
PsychAssignHighPrecisionTextureShaders(textureRecord, windowRecord, 0, (specialFlags & 2) ? 1 : 0);
// Texture ready for consumption. Mark it valid and return handle to userspace:
PsychSetWindowRecordValid(textureRecord);
PsychCopyOutDoubleArg(1, TRUE, textureRecord->windowIndex);
// Return presentation timestamp for this image:
PsychCopyOutDoubleArg(2, FALSE, presentation_timestamp);
// Ready!
return(PsychError_none);
}
/*
PsychOSOpenOnscreenWindow()
Creates the CGL pixel format and the CGL context objects and then instantiates the context onto the screen.
-The pixel format and the context are stored in the target specific field of the window recored. Close
should clean up by destroying both the pixel format and the context.
-We mantain the context because it must be be made the current context by drawing functions to draw into
the specified window.
-We maintain the pixel format object because there seems to be now way to retrieve that from the context.
-To tell the caller to clean up PsychOSOpenOnscreenWindow returns FALSE if we fail to open the window. It
would be better to just issue an PsychErrorExit() and have that clean up everything allocated outside of
PsychOpenOnscreenWindow().
MK: The new option 'stereomode' allows selection of stereo display instead of mono display:
0 (default) == Old behaviour -> Monoscopic rendering context.
>0 == Stereo display, where the number defines the type of stereo algorithm to use.
=1 == Use OpenGL built-in stereo by creating a context/window with left- and right backbuffer. This is
the only mode of interest here, as it requires use of a stereo capable OpenGL pixelformat. All other
stereo modes are implemented by PTB itself in a platform independent manner on top of a standard mono
context.
*/
psych_bool PsychOSOpenOnscreenWindow(PsychScreenSettingsType *screenSettings, PsychWindowRecordType *windowRecord, int numBuffers, int stereomode, int conserveVRAM)
{
CGOpenGLDisplayMask displayMask;
CGLError error;
CGDirectDisplayID cgDisplayID;
CGLPixelFormatAttribute attribs[40];
int attribcount;
GLint numVirtualScreens;
GLenum glerr;
PsychRectType screenrect;
int i;
int windowLevel;
long scw, sch;
void* cocoaWindow = NULL;
// Map screen number to physical display handle cgDisplayID:
PsychGetCGDisplayIDFromScreenNumber(&cgDisplayID, screenSettings->screenNumber);
displayMask = CGDisplayIDToOpenGLDisplayMask(cgDisplayID);
// NULL-out Cocoa window handle, so this is well-defined in case of error:
windowRecord->targetSpecific.windowHandle = NULL;
// Retrieve windowLevel, an indicator of where non-CGL / non-fullscreen windows should
// be located wrt. to other windows. -2 = Allow regular window manager control of stacking
// order, visibility etc., -1 = Invisible/hidden, 0 = Behind everything else, occluded by
// everything else. 1 - 999 = At layer 'windowLevel' -> Occludes stuff on layers "below" it.
// 1000 - 1999 = At highest level, but partially translucent / alpha channel allows to make
// regions transparent. Range 1000 - 1499 = transparent for mouse and keyboard, alpha 0-99.99%,
// 1500-1599 = opaque for mouse and keyboard, alpha 0-99.99%, 2000 or higher: Above everything,
// fully opaque, occludes everything, a typical fullscreen onscreen window. 2000 is the default.
windowLevel = PsychPrefStateGet_WindowShieldingLevel();
// Window rect provided which has same size as screen?
// We do not use windowed mode if the provided window rectangle either
// matches the target screens rectangle (and therefore its exact size)
// or its screens global rectangle. In such cases we use CGL for better
// low level control and to exclude the desktop compositor from interfering:
PsychGetScreenRect(screenSettings->screenNumber, screenrect);
if (PsychMatchRect(screenrect, windowRecord->rect)) windowRecord->specialflags |= kPsychIsFullscreenWindow;
PsychGetGlobalScreenRect(screenSettings->screenNumber, screenrect);
if (PsychMatchRect(screenrect, windowRecord->rect)) windowRecord->specialflags |= kPsychIsFullscreenWindow;
if ((windowRecord->specialflags & kPsychIsFullscreenWindow) && (PsychPrefStateGet_Verbosity() > 3)) {
printf("PTB-INFO: Always using Cocoa for fullscreen windows to work around graphics driver bugs in OSX.\n");
printf("PTB-INFO: Presentation timing precision is not yet known for this configuration on most machines. Check your results.\n");
}
// Display for fullscreen window not captured? Timing precision is unclear in this mode. In theory the compositor should disable
// itself for fullscreen windows on modern OSX versions. If it really does that, who knows?
if ((windowRecord->specialflags & kPsychIsFullscreenWindow) && (PsychPrefStateGet_ConserveVRAM() & kPsychUseAGLCompositorForFullscreenWindows)) {
// Force a window rectangle that matches the global screen rectangle for that windows screen:
PsychCopyRect(windowRecord->rect, screenrect);
// Warn user about what's going on:
if (PsychPrefStateGet_Verbosity()>1) printf("PTB-INFO: No display capture / compositor lockout for fullscreen window. Timing precision is unknown.\n");
}
if ((windowRecord->specialflags & kPsychGUIWindow) && (PsychPrefStateGet_Verbosity() > 3)) {
printf("PTB-INFO: Onscreen window is configured as regular GUI window.\n");
}
// Create onscreen Cocoa window of requested position and size:
if (PsychCocoaCreateWindow(windowRecord, windowLevel, &cocoaWindow)) {
printf("\nPTB-ERROR[CreateNewWindow failed]: Failed to open Cocoa onscreen window\n\n");
return(FALSE);
}
// Transparent window requested?
if ((windowLevel >= 1000) && (windowLevel < 2000)) {
// Setup of global window alpha value for transparency. This is premultiplied to
// the individual per-pixel alpha values if transparency is enabled by Cocoa code.
//
// Levels 1000 - 1499 and 1500 to 1999 map to a master opacity level of 0.0 - 1.0:
PsychCocoaSetWindowAlpha(cocoaWindow, ((float) (windowLevel % 500)) / 499.0);
}
// Show it! Unless a windowLevel of -1 requests hiding the window:
if (windowLevel != -1) PsychCocoaShowWindow(cocoaWindow);
// If usercode wants a black startup screen then we add a pause of 0.5 seconds here
// before proceeding. This will avoid a white flash at window open time, which might
// be something the user wanted to avoid. Why does this help or is needed at all?
// Nobody knows, but this is Apples ridiculous toy OS, so why even ask such questions?
if (PsychPrefStateGet_VisualDebugLevel() < 4)
PsychYieldIntervalSeconds(0.5);
// Level zero means: Place behind all other windows:
if (windowLevel == 0) PsychCocoaSendBehind(cocoaWindow);
// Levels 1 to 999 define window levels for the group of the window.
// A level of -2 would leave this to the system:
if (windowLevel > 0 && windowLevel < 1000) PsychCocoaSetWindowLevel(cocoaWindow, windowLevel);
// Is the target display captured for a fullscreen window?
if (PsychIsScreenCaptured(screenSettings->screenNumber)) {
// Yes. Make sure our window is above the shielding window level:
PsychCocoaSetWindowLevel(cocoaWindow, (int) CGShieldingWindowLevel());
}
// Store window handle in windowRecord:
windowRecord->targetSpecific.windowHandle = cocoaWindow;
// Store vblank startline aka true height of physical display screen in pixels:
PsychGetScreenPixelSize(screenSettings->screenNumber, &scw, &sch);
windowRecord->VBL_Startline = (int) sch;
// Define pixelformat attributes for OpenGL contexts:
// No pixelformat attribs to start with:
attribcount = 0;
attribs[attribcount++]=kCGLPFADisplayMask;
attribs[attribcount++]=displayMask;
// 10 bit per component integer framebuffer requested (10-10-10-2)?
if (windowRecord->depth == 30) {
// Request a 10 bit per color component framebuffer with 2 bit alpha channel:
printf("PTB-INFO: Trying to enable 10 bpc, 30 bit integer framebuffer...\n");
attribs[attribcount++]=kCGLPFANoRecovery;
attribs[attribcount++]=kCGLPFAMinimumPolicy;
attribs[attribcount++]=kCGLPFAColorSize;
attribs[attribcount++]=10*3;
attribs[attribcount++]=kCGLPFAAlphaSize;
attribs[attribcount++]=2;
}
// 11 bit per component integer framebuffer requested (11-11-10-0)?
if (windowRecord->depth == 33) {
// Request a ~ 11 bit per color component framebuffer without alpha channel:
printf("PTB-INFO: Trying to enable 11 bpc, 32 bit integer framebuffer...\n");
attribs[attribcount++]=kCGLPFANoRecovery;
attribs[attribcount++]=kCGLPFAMinimumPolicy;
attribs[attribcount++]=kCGLPFAColorSize;
attribs[attribcount++]=32;
attribs[attribcount++]=kCGLPFAAlphaSize;
attribs[attribcount++]=0;
}
// 16 bit per component integer framebuffer requested (16-16-16-16)?
if (windowRecord->depth == 48) {
// Request a 16 bit per color component framebuffer:
printf("PTB-INFO: Trying to enable 16 bpc, 64 bit integer framebuffer...\n");
attribs[attribcount++]=kCGLPFANoRecovery;
attribs[attribcount++]=kCGLPFAMinimumPolicy;
attribs[attribcount++]=kCGLPFAColorSize;
attribs[attribcount++]=16*3;
attribs[attribcount++]=kCGLPFAAlphaSize;
attribs[attribcount++]=16;
}
// 16 bit per component, 64 bit framebuffer requested (16-16-16-16)?
if (windowRecord->depth == 64) {
// Request a floating point framebuffer in 16-bit half-float format, i.e., RGBA = 16 bits per component.
printf("PTB-INFO: Trying to enable 16 bpc float framebuffer...\n");
attribs[attribcount++]=kCGLPFAColorFloat;
attribs[attribcount++]=kCGLPFAMinimumPolicy;
attribs[attribcount++]=kCGLPFAColorSize;
attribs[attribcount++]=16*3;
attribs[attribcount++]=kCGLPFAAlphaSize;
attribs[attribcount++]=16;
}
// 32 bit per component, 128 bit framebuffer requested (32-32-32-32)?
if (windowRecord->depth == 128) {
// Request a floating point framebuffer in 32-bit float format, i.e., RGBA = 32 bits per component.
printf("PTB-INFO: Trying to enable 32 bpc float framebuffer...\n");
attribs[attribcount++]=kCGLPFAColorFloat;
attribs[attribcount++]=kCGLPFAMinimumPolicy;
attribs[attribcount++]=kCGLPFAColorSize;
attribs[attribcount++]=32*3;
attribs[attribcount++]=kCGLPFAAlphaSize;
attribs[attribcount++]=32;
}
// Possible to request use of the Apple floating point software renderer:
if (conserveVRAM & kPsychUseSoftwareRenderer) {
#ifndef kCGLRendererGenericFloatID
#define kCGLRendererGenericFloatID 0x00020400
#endif
attribs[attribcount++]=AGL_RENDERER_ID;
attribs[attribcount++]=kCGLRendererGenericFloatID;
}
// Support for 3D rendering requested?
if (PsychPrefStateGet_3DGfx()) {
// Yes. Allocate a 24-Bit depth and 8-Bit stencilbuffer for this purpose:
attribs[attribcount++]=kCGLPFADepthSize;
attribs[attribcount++]=24;
attribs[attribcount++]=kCGLPFAStencilSize;
attribs[attribcount++]=8;
// Alloc an accumulation buffer as well?
if (PsychPrefStateGet_3DGfx() & 2) {
// Yes: Alloc accum buffer, request 64 bpp, aka 16 bits integer per color component if possible:
attribs[attribcount++]=kCGLPFAAccumSize;
attribs[attribcount++]=64;
}
}
if(numBuffers>=2){
// Enable double-buffering:
attribs[attribcount++]=kCGLPFADoubleBuffer;
if ((conserveVRAM & kPsychDisableAUXBuffers) == 0) {
// Allocate one or two (for mono vs. stereo display) AUX buffers for "don't clear" mode of Screen('Flip'):
// Not clearing the framebuffer after "Flip" is implemented by storing a backup-copy of
// the backbuffer to AUXs before flip and restoring the content from AUXs after flip.
// Unless the imaging pipeline is active, which doesn't need AUX buffers due to internal
// storage of fb content in its drawbufferFBO's:
attribs[attribcount++]=kCGLPFAAuxBuffers;
attribs[attribcount++]=(stereomode==kPsychOpenGLStereo || stereomode==kPsychCompressedTLBRStereo || stereomode==kPsychCompressedTRBLStereo) ? 2 : 1;
}
}
// If stereo display output is requested with OpenGL native stereo, request a stereo-enabled rendering context.
// This is deprecated since 10.11 El Capitan, and in fact does no longer work - OpenGL quad buffered stereo is
// dead on 10.11 on all tested GPU's from Intel, NVidia, AMD.
if(stereomode==kPsychOpenGLStereo) {
attribs[attribcount++] = kCGLPFAStereo;
}
// Multisampled Anti-Aliasing requested?
if (windowRecord->multiSample > 0) {
// Request a multisample buffer:
attribs[attribcount++]= kCGLPFASampleBuffers;
attribs[attribcount++]= 1;
// Request at least multiSample samples per pixel:
attribs[attribcount++]= kCGLPFASamples;
attribs[attribcount++]= windowRecord->multiSample;
}
// Finalize attribute array with NULL.
attribs[attribcount++]=(CGLPixelFormatAttribute)NULL;
// Init to zero:
windowRecord->targetSpecific.pixelFormatObject = NULL;
windowRecord->targetSpecific.glusercontextObject = NULL;
windowRecord->targetSpecific.glswapcontextObject = NULL;
// Try to find matching pixelformat:
error = CGLChoosePixelFormat(attribs, &(windowRecord->targetSpecific.pixelFormatObject), &numVirtualScreens);
// No valid pixelformat found and stereo format requested?
if ((error || (windowRecord->targetSpecific.pixelFormatObject == NULL)) && (stereomode == kPsychOpenGLStereo)) {
// Yep: Stereo may be the culprit. Remove the stereo attribute by overwriting it with something
// that is essentially a no-op, specifically kCGLPFAAccelerated which is supported by all real
// renderers that might end up in this code-path:
for (i = 0; i < attribcount && attribs[i] != kCGLPFAStereo; i++);
attribs[i] = kCGLPFAAccelerated;
// Retry query of pixelformat without request for native OpenGL quad-buffered stereo. If we succeed, we're
// sort of ok, as the higher-level code will fallback to stereomode kPsychFrameSequentialStereo - our own
// homegrown frame-sequential stereo support, which may be good enough.
error = CGLChoosePixelFormat(attribs, &(windowRecord->targetSpecific.pixelFormatObject), &numVirtualScreens);
if (error || (windowRecord->targetSpecific.pixelFormatObject == NULL)) {
windowRecord->targetSpecific.pixelFormatObject = NULL;
printf("\nPTB-ERROR[ChoosePixelFormat failed: %s]: Disabling OpenGL native quad-buffered stereo did not help. Moving on...\n\n", CGLErrorString(error));
}
}
// Now try if choosing a matching format for a lower multisample mode helps to get unstuck:
if (windowRecord->multiSample > 0) {
if (windowRecord->targetSpecific.pixelFormatObject==NULL && windowRecord->multiSample > 0) {
// Failed. Probably due to too demanding multisample requirements: Lets lower them...
for (i = 0; i < attribcount && attribs[i] != kCGLPFASamples; i++);
while (windowRecord->targetSpecific.pixelFormatObject == NULL && windowRecord->multiSample > 0) {
attribs[i+1]--;
windowRecord->multiSample--;
error = CGLChoosePixelFormat(attribs, &(windowRecord->targetSpecific.pixelFormatObject), &numVirtualScreens);
}
if (windowRecord->multiSample == 0 && windowRecord->targetSpecific.pixelFormatObject == NULL) {
// Ok, multisampling is now at zero and we still don't succeed. Disable multisampling completely:
for (i=0; i<attribcount && attribs[i]!=kCGLPFASampleBuffers; i++);
attribs[i+1] = 0;
printf("\nPTB-ERROR[ChoosePixelFormat failed: %s]: Disabling multisample anti-aliasing did not help. Moving on...\n\n", CGLErrorString(error));
}
}
}
// Try choosing a matching display configuration again and create the window and rendering context:
// If one of these two fails, then the installed gfx hardware is not good enough to satisfy our
// requirements, or we have massive ressource shortage in the system. -> Screwed up anyway, so we abort.
if (windowRecord->targetSpecific.pixelFormatObject == NULL) error = CGLChoosePixelFormat(attribs, &(windowRecord->targetSpecific.pixelFormatObject), &numVirtualScreens);
if (error) {
printf("\nPTB-ERROR[ChoosePixelFormat failed: %s]: Reason unknown. There could be insufficient video memory or a driver malfunction. Giving up.\n\n", CGLErrorString(error));
return(FALSE);
}
// Create an OpenGL rendering context with the selected pixelformat: Share its ressources with 'slaveWindow's context, if slaveWindow is non-NULL.
// If slaveWindow is non-NULL here, then slaveWindow is typically another onscreen window. Therefore this establishes OpenGL resource sharing across
// different onscreen windows in a session, e.g., for multi-display operation:
error=CGLCreateContext(windowRecord->targetSpecific.pixelFormatObject, ((windowRecord->slaveWindow) ? windowRecord->slaveWindow->targetSpecific.contextObject : NULL),
&(windowRecord->targetSpecific.contextObject));
if (error) {
printf("\nPTB-ERROR[ContextCreation failed: %s]: Could not create master OpenGL context for new onscreen window. Insufficient video memory?\n\n", CGLErrorString(error));
return(FALSE);
}
// Enable the OpenGL rendering context associated with our window:
error=CGLSetCurrentContext(windowRecord->targetSpecific.contextObject);
if (error) {
printf("\nPTB-ERROR[SetCurrentContext failed: %s]: Insufficient video memory\n\n", CGLErrorString(error));
return(FALSE);
}
// NULL-out the AGL context field, just for safety...
windowRecord->targetSpecific.deviceContext = NULL;
// Ok, the master OpenGL rendering context for this new onscreen window is up and running.
// Auto-detect and bind all available OpenGL extensions via GLEW:
glerr = glewInit();
if (GLEW_OK != glerr)
{
/* Problem: glewInit failed, something is seriously wrong. */
printf("\nPTB-ERROR[GLEW init failed: %s]: Please report this to the forum. Will try to continue, but may crash soon!\n\n", glewGetErrorString(glerr));
fflush(NULL);
}
else {
if (PsychPrefStateGet_Verbosity()>3) printf("PTB-INFO: Using GLEW version %s for automatic detection of OpenGL extensions...\n", glewGetString(GLEW_VERSION));
}
// Enable multisampling if it was requested:
if (windowRecord->multiSample > 0) glEnable(GL_MULTISAMPLE);
// External 3D graphics support enabled?
if (PsychPrefStateGet_3DGfx()) {
// Yes. We need to create an extra OpenGL rendering context for the external
// OpenGL code to provide optimal state-isolation. The context shares all
// heavyweight ressources likes textures, FBOs, VBOs, PBOs, shader, display lists and
// starts off as an identical copy of PTB's context as of here.
error=CGLCreateContext(windowRecord->targetSpecific.pixelFormatObject, windowRecord->targetSpecific.contextObject, &(windowRecord->targetSpecific.glusercontextObject));
if (error) {
printf("\nPTB-ERROR[UserContextCreation failed: %s]: Creating a private OpenGL context for userspace OpenGL failed.\n\n", CGLErrorString(error));
return(FALSE);
}
}
// Create glswapcontextObject - An OpenGL context for exclusive use by parallel background threads,
// e.g., our thread for async flip operations and self-made frame-sequential stereo:
error=CGLCreateContext(windowRecord->targetSpecific.pixelFormatObject, windowRecord->targetSpecific.contextObject, &(windowRecord->targetSpecific.glswapcontextObject));
if (error) {
printf("\nPTB-ERROR[SwapContextCreation failed: %s]: Creating a private OpenGL context for async-bufferswaps failed.\n\n", CGLErrorString(error));
CGLSetCurrentContext(NULL);
return(FALSE);
}
// Store Cocoa onscreen window handle:
windowRecord->targetSpecific.windowHandle = cocoaWindow;
// Objective-C setup path, using Cocoa + NSOpenGLContext wrapped around already
// existing and setup CGLContext:
if (PsychCocoaSetupAndAssignOpenGLContextsFromCGLContexts(cocoaWindow, windowRecord)) {
printf("\nPTB-ERROR[Cocoa OpenGL setup failed]: Setup failed for unknown reasons.\n\n");
PsychCocoaDisposeWindow(windowRecord);
return(FALSE);
}
// Check for output display rotation enabled. Will impair timing/timestamping because
// it uses the desktop compositor for a rotated copy blit, instead of via rotated crtc
// scanout, as most crtc's don't support this in hardware:
if ((((int) CGDisplayRotation(cgDisplayID)) != 0) && (PsychPrefStateGet_Verbosity() > 1)) {
printf("PTB-WARNING: Your onscreen windows output display has rotation enabled. It is not displaying in upright orientation.\n");
printf("PTB-WARNING: On most graphics cards this will cause unreliable stimulus presentation timing and timestamping.\n");
printf("PTB-WARNING: If you want non-upright stimulus presentation, look at 'help PsychImaging' on how to achieve this in\n");
printf("PTB-WARNING: a way that doesn't impair timing. The subfunctions 'FlipHorizontal' and 'FlipVertical' are what you probably need.\n");
}
// First reference to this screen by a window?
if (screenRefCount[screenSettings->screenNumber] == 0) {
// High precision timestamping enabled? If so, we need to setup the fallback
// timestamping methods in case beamposition timestamping doesn't work:
if (PsychPrefStateGet_VBLTimestampingMode() > 0) {
// Use of CoreVideo is needed on 10.7 and later due to brokeness of the old method (thanks Apple!):
if (PsychPrefStateGet_Verbosity() > 2) {
printf("PTB-INFO: Will use fragile CoreVideo timestamping as fallback if beamposition timestamping doesn't work.\n");
// Recommend use of kernel driver if it isn't installed already for all but Intel GPU's:
if (!PsychOSIsKernelDriverAvailable(screenSettings->screenNumber) && !strstr((char*) glGetString(GL_VENDOR), "Intel")) {
printf("PTB-INFO: Installation of the PsychtoolboxKernelDriver is strongly recommended if you care about precise visual\n");
printf("PTB-INFO: onset timestamping or timing. See 'help PsychtoolboxKernelDriver' for installation instructions.\n");
}
}
if (NULL == cvDisplayLink[screenSettings->screenNumber]) {
// CoreVideo timestamping:
//
// Create and start a CVDisplayLink for this screen.
if (kCVReturnSuccess != CVDisplayLinkCreateWithCGDisplay(cgDisplayID, &cvDisplayLink[screenSettings->screenNumber])) {
if (PsychPrefStateGet_Verbosity()>1) printf("PTB-WARNING: Failed to create CVDisplayLink for screenId %i. This may impair VBL timestamping.\n", screenSettings->screenNumber);
} else {
// Assign dummy output callback, as this is mandatory to get the link up and running:
CVDisplayLinkSetOutputCallback(cvDisplayLink[screenSettings->screenNumber], &PsychCVDisplayLinkOutputCallback, (void*) (long int) screenSettings->screenNumber);
// Setup shared data structure and mutex:
memset(&cvDisplayLinkData[screenSettings->screenNumber], 0, sizeof(cvDisplayLinkData[screenSettings->screenNumber]));
PsychInitMutex(&(cvDisplayLinkData[screenSettings->screenNumber].mutex));
// Start the link:
if (kCVReturnSuccess != CVDisplayLinkStart(cvDisplayLink[screenSettings->screenNumber])) {
// Failed to start: Release it again and report error:
CVDisplayLinkRelease(cvDisplayLink[screenSettings->screenNumber]);
cvDisplayLink[screenSettings->screenNumber] = NULL;
// Teardown shared data structure and mutex:
PsychDestroyMutex(&(cvDisplayLinkData[screenSettings->screenNumber].mutex));
if (PsychPrefStateGet_Verbosity()>1) printf("PTB-WARNING: Failed to start CVDisplayLink for screenId %i. This may impair VBL timestamping.\n", screenSettings->screenNumber);
}
else {
// Display link started: Report some stuff for the fun of it...
if (PsychPrefStateGet_Verbosity() > 3) {
// Wait for 50 msecs before query of video refresh from display link to give it a chance to start up:
PsychWaitIntervalSeconds(0.050);
printf("PTB-INFO: CVDisplayLink for screen %i created to work around the brokenness of Apple Mac OS/X 10.7 and later:\n", screenSettings->screenNumber);
printf("PTB-INFO: Video refresh interval as measured by CoreVideo display link: %f msecs.\n", (float) CVDisplayLinkGetActualOutputVideoRefreshPeriod(cvDisplayLink[screenSettings->screenNumber]) * 1000.0);
CVTime outLatency = CVDisplayLinkGetOutputVideoLatency(cvDisplayLink[screenSettings->screenNumber]);
printf("PTB-INFO: Video display output delay as reported by CoreVideo display link: %f msecs.\n", screenSettings->screenNumber, (float) (((double) outLatency.timeValue / (double) outLatency.timeScale) * 1000.0));
}
}
}
}
}
else {
// VBLtimestampingmode 0 or -1 -- No CoreVideo fallback for timestamping if beamposition timestamping is unavailable:
// This is the new default as of Psychtoolbox 3.0.12 to avoid the buggy, crashy, unreliably CoreVideo fallback.
// Recommend use of kernel driver if it isn't installed already for all but Intel GPU's:
if (!PsychOSIsKernelDriverAvailable(screenSettings->screenNumber) && !strstr((char*) glGetString(GL_VENDOR), "Intel")) {
printf("PTB-INFO: Installation of the PsychtoolboxKernelDriver is strongly recommended if you care about precise visual\n");
printf("PTB-INFO: onset timestamping or timing. See 'help PsychtoolboxKernelDriver' for installation instructions.\n");
}
}
}
// Retain reference of this window to its screen:
screenRefCount[screenSettings->screenNumber]++;
// Done.
return(TRUE);
}
/* PsychEnableNative10BitFramebuffer() - Enable/Disable native 10 bpc RGB framebuffer modes.
*
* This function enables or disables the native ARGB2101010 framebuffer readout mode of supported
* graphics hardware. Currently the ATI Radeon X1000/HD2000/HD3000 and later cards should allow this.
*
* This needs support from the Psychtoolbox kernel level support driver for low-level register reads
* and writes to the GPU registers.
*
* 'windowRecord' Is used to find the Id of the screen for which mode should be changed, as well as enable
* flags to see if a change is required at all, and the OpenGL context for some specific
* fixups. A value of NULL will try to apply the operation to all heads, but may only work
* for *disabling* 10 bpc mode, not for enabling it -- Mostly useful for a master reset to
* system default, e.g., as part of error handling or Screen shutdown handling.
* 'enable' True = Enable ABGR2101010 support, False = Disable ARGB2101010 support, reenable ARGB8888 support.
*
*/
psych_bool PsychEnableNative10BitFramebuffer(PsychWindowRecordType* windowRecord, psych_bool enable)
{
#if PSYCH_SYSTEM == PSYCH_OSX || PSYCH_SYSTEM == PSYCH_LINUX
int i, si, ei, headid, headiter, screenId;
unsigned int lutreg, ctlreg, value, status;
int gpuMaintype, gpuMinortype;
// Child protection:
if (windowRecord && !PsychIsOnscreenWindow(windowRecord)) PsychErrorExitMsg(PsychError_internal, "Invalid non-onscreen windowRecord provided!!!");
// Either screenid from windowRecord or our special -1 "all Screens" Id:
screenId = (windowRecord) ? windowRecord->screenNumber : -1;
// We only support Radeon GPU's, nothing else:
if (!PsychGetGPUSpecs(screenId, &gpuMaintype, &gpuMinortype, NULL, NULL) ||
(gpuMaintype != kPsychRadeon) || (gpuMinortype >= 0xffff)) {
return(FALSE);
}
// Define range of screens: Either a single specific one, or all:
si = (screenId!=-1) ? screenId : 0;
ei = (screenId!=-1) ? screenId+1 : PsychGetNumDisplays();
// Loop over all target screens:
for (i = si; i < ei; i++) {
// Iterate over range of all assigned heads for this screenId 'i' and reconfigure them:
for (headiter = 0; headiter < kPsychMaxPossibleCrtcs; headiter++) {
// Map screenid to headid for headiter'th head:
headid = PsychScreenToCrtcId(i, headiter);
// We're done as soon as we encounter invalid negative headid.
if (headid < 0) break;
// Select Radeon HW registers for corresponding heads:
if (gpuMinortype < 0x40) {
// DCE-3 and earlier:
lutreg = (headid == 0) ? RADEON_D1GRPH_LUT_SEL : RADEON_D2GRPH_LUT_SEL;
ctlreg = (headid == 0) ? RADEON_D1GRPH_CONTROL : RADEON_D2GRPH_CONTROL;
}
else {
// DCE-4 and later:
if (headid > DCE4_MAXHEADID) {
printf("PTB-ERROR: Invalid headId %i (greater than max %i) provided for DCE-4+ display engine!\n", headid, DCE4_MAXHEADID);
return(false);
}
lutreg = EVERGREEN_DC_LUT_10BIT_BYPASS + crtcoff[headid];
ctlreg = EVERGREEN_GRPH_CONTROL + crtcoff[headid];
}
// Enable or Disable?
if (enable) {
// Enable:
// Switch hardware LUT's to bypass mode:
// We set bit 8 to enable "bypass LUT in 2101010 mode":
value = PsychOSKDReadRegister(screenId, lutreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (LUTReg read failed).\n");
return(false);
}
// Set the bypass bit:
value = value | 0x1 << 8;
PsychOSKDWriteRegister(screenId, lutreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (LUTReg write failed).\n");
return(false);
}
// Only reconfigure framebuffer scanout if this is really our true Native10bpc hack:
// This is usually skipped on FireGL/FirePro GPU's as their drivers do it already...
if (windowRecord->specialflags & kPsychNative10bpcFBActive) {
// Switch CRTC to ABGR2101010 readout mode:
// We set bit 8 to enable that mode:
value = PsychOSKDReadRegister(screenId, ctlreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (CTLReg read failed).\n");
return(false);
}
// Set 2101010 mode bit:
value = value | 0x1 << 8;
PsychOSKDWriteRegister(screenId, ctlreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 10 bit framebuffer mode (CTLReg write failed).\n");
return(false);
}
}
// Pipe should be in 10 bpc mode now...
if (PsychPrefStateGet_Verbosity() > 2) printf("PTB-INFO: System framebuffer switched to ARGB2101010 mode for screen %i [head %i].\n", i, headid);
} else {
// Disable:
// Only reconfigure framebuffer scanout if this is really our true Native10bpc hack:
// This is usually skipped on FireGL/FirePro GPU's as their drivers do it already...
if (windowRecord->specialflags & kPsychNative10bpcFBActive) {
// Switch CRTC to ABGR8888 readout mode:
// We clear bit 8 to enable that mode:
value = PsychOSKDReadRegister(screenId, ctlreg, &status);
if (status) {
// This codepath gets always called in PsychCloseWindow(), so we should skip it
// silently if register read fails, as this is expected on MS-Windows and on all
// non-Radeon hardware and if kernel driver isn't loaded:
if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (CTLReg read failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: Readreg. ctlreg yields %lx\n", value);
// Clear 2101010 mode bit:
value = value & ~(0x1 << 8);
PsychOSKDWriteRegister(screenId, ctlreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (CTLReg write failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: ctlreg reset\n");
// Wait 500 msecs for GPU to settle:
PsychWaitIntervalSeconds(0.5);
}
// Switch hardware LUT's to standard mapping mode:
// We clear bit 8 to disable "bypass LUT in 2101010 mode":
value = PsychOSKDReadRegister(screenId, lutreg, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (LUTReg read failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: Readreg. lutreg yields %lx\n", value);
// Clear LUT bypass bit:
value = value & ~(0x1 << 8);
PsychOSKDWriteRegister(screenId, lutreg, value, &status);
if (status) {
printf("PTB-ERROR: Failed to set 8 bit framebuffer mode (LUTReg write failed).\n");
return(false);
}
else if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: In disable 10bpc: lutreg reset\n");
// Pipe should be in 8 bpc mode now...
if (PsychPrefStateGet_Verbosity() > 2) printf("PTB-INFO: System framebuffer switched to standard ARGB8888 mode for screen %i [head %i].\n", i, headid);
}
} // Next display head...
} // Next screenId.
// Done.
return(TRUE);
#else
// This cool stuff not supported on the uncool Windows OS:
return(FALSE);
#endif
}
/*
* PsychQTGetTextureFromMovie() -- Create an OpenGL texture map from a specific videoframe from given movie object.
*
* win = Window pointer of onscreen window for which a OpenGL texture should be created.
* moviehandle = Handle to the movie object.
* checkForImage = true == Just check if new image available, false == really retrieve the image, blocking if necessary.
* timeindex = When not in playback mode, this allows specification of a requested frame by presentation time.
* If set to -1, or if in realtime playback mode, this parameter is ignored and the next video frame is returned.
* out_texture = Pointer to the Psychtoolbox texture-record where the new texture should be stored.
* presentation_timestamp = A ptr to a double variable, where the presentation timestamp of the returned frame should be stored.
*
* Returns true (1) on success, false (0) if no new image available, -1 if no new image available and there won't be any in future.
*/
int PsychQTGetTextureFromMovie(PsychWindowRecordType *win, int moviehandle, int checkForImage, double timeindex, PsychWindowRecordType *out_texture, double *presentation_timestamp)
{
static TimeValue myNextTimeCached = -2;
static TimeValue nextFramesTimeCached = -2;
TimeValue myCurrTime;
TimeValue myNextTime;
TimeValue nextFramesTime=0;
short myFlags;
OSType myTypes[1];
OSErr error = noErr;
Movie theMovie;
CVOpenGLTextureRef newImage = NULL;
QTVisualContextRef theMoviecontext;
unsigned int failcount=0;
float lowerLeft[2];
float lowerRight[2];
float upperRight[2];
float upperLeft[2];
GLuint texid;
Rect rect;
float rate;
double targetdelta, realdelta, frames;
PsychRectType outRect;
if (!PsychIsOnscreenWindow(win)) {
PsychErrorExitMsg(PsychError_user, "Need onscreen window ptr!!!");
}
// Activate OpenGL context of target window:
PsychSetGLContext(win);
// Explicitely disable Apple's Client storage extensions. For now they are not really useful to us.
glPixelStorei(GL_UNPACK_CLIENT_STORAGE_APPLE, GL_FALSE);
if (moviehandle < 0 || moviehandle >= PSYCH_MAX_MOVIES) {
PsychErrorExitMsg(PsychError_user, "Invalid moviehandle provided.");
}
if ((timeindex!=-1) && (timeindex < 0 || timeindex >= 10000.0)) {
PsychErrorExitMsg(PsychError_user, "Invalid timeindex provided.");
}
if (NULL == out_texture && !checkForImage) {
PsychErrorExitMsg(PsychError_internal, "NULL-Ptr instead of out_texture ptr passed!!!");
}
// Fetch references to objects we need:
theMovie = movieRecordBANK[moviehandle].theMovie;
theMoviecontext = movieRecordBANK[moviehandle].QTMovieContext;
if (theMovie == NULL) {
PsychErrorExitMsg(PsychError_user, "Invalid moviehandle provided. No movie associated with this handle.");
}
// Check if end of movie is reached. Rewind, if so...
if (IsMovieDone(theMovie) && movieRecordBANK[moviehandle].loopflag > 0) {
if (GetMovieRate(theMovie)>0) {
GoToBeginningOfMovie(theMovie);
} else {
GoToEndOfMovie(theMovie);
}
}
// Is movie actively playing (automatic async playback, possibly with synced sound)?
// If so, then we ignore the 'timeindex' parameter, because the automatic playback
// process determines which frames should be delivered to PTB when. This function will
// simply wait or poll for arrival/presence of a new frame that hasn't been fetched
// in previous calls.
if (0 == GetMovieRate(theMovie)) {
// Movie playback inactive. We are in "manual" mode: No automatic async playback,
// no synced audio output. The user just wants to manually fetch movie frames into
// textures for manual playback in a standard Matlab-loop.
// First pass - checking for new image?
if (checkForImage) {
// Image for specific point in time requested?
if (timeindex >= 0) {
// Yes. We try to retrieve the next possible image for requested timeindex.
myCurrTime = (TimeValue) ((timeindex * (double) GetMovieTimeScale(theMovie)) + 0.5f);
}
else {
// No. We just retrieve the next frame, given the current movie time.
myCurrTime = GetMovieTime(theMovie, NULL);
}
// Retrieve timeindex of the closest image sample after myCurrTime:
myFlags = nextTimeStep + nextTimeEdgeOK; // We want the next frame in the movie's media.
myTypes[0] = VisualMediaCharacteristic; // We want video samples.
GetMovieNextInterestingTime(theMovie, myFlags, 1, myTypes, myCurrTime, FloatToFixed(1), &myNextTime, &nextFramesTime);
error = GetMoviesError();
if (error != noErr) {
PsychErrorExitMsg(PsychError_internal, "Failed to fetch texture from movie for given timeindex!");
}
// Found useful event?
if (myNextTime == -1) {
if (PsychPrefStateGet_Verbosity() > 3) printf("PTB-WARNING: Bogus timevalue in movie track for movie %i. Trying to keep going.\n", moviehandle);
// No. Just push timestamp to current time plus a little bit in the hope
// this will get us unstuck:
myNextTime = myCurrTime + (TimeValue) 1;
nextFramesTime = (TimeValue) 0;
}
if (myNextTime != myNextTimeCached) {
// Set movies current time to myNextTime, so the next frame will be fetched from there:
SetMovieTimeValue(theMovie, myNextTime);
// nextFramesTime is the timeindex to which we need to advance for retrieval of next frame: (see code below)
nextFramesTime=myNextTime + nextFramesTime;
if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: Current timevalue in movie track for movie %i is %lf secs.\n", moviehandle, (double) myNextTime / (double) GetMovieTimeScale(theMovie));
if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: Next timevalue in movie track for movie %i is %lf secs.\n", moviehandle, (double) nextFramesTime / (double) GetMovieTimeScale(theMovie));
// Cache values for 2nd pass:
myNextTimeCached = myNextTime;
nextFramesTimeCached = nextFramesTime;
}
else {
// Somehow got stuck? Do nothing...
if (PsychPrefStateGet_Verbosity() > 5) printf("PTB-DEBUG: Seem to be a bit stuck at timevalue [for movie %i] of %lf secs. Nudging a bit forward...\n", moviehandle, (double) myNextTime / (double) GetMovieTimeScale(theMovie));
// Nudge the timeindex a bit forware in the hope that this helps:
SetMovieTimeValue(theMovie, GetMovieTime(theMovie, NULL) + 1);
}
}
else {
// This is the 2nd pass: Image fetching. Use cached values from first pass:
// Caching in a static works because we're always called immediately for 2nd
// pass after successfull return from 1st pass, and we're not multi-threaded,
// i.e., don't need to be reentrant or thread-safe here:
myNextTime = myNextTimeCached;
nextFramesTime = nextFramesTimeCached;
myNextTimeCached = -2;
}
}
else {
// myNextTime unavailable if in autoplayback-mode:
myNextTime=-1;
}
// Presentation timestamp requested?
if (presentation_timestamp) {
// Already available?
if (myNextTime==-1) {
// Retrieve the exact presentation timestamp of the retrieved frame (in movietime):
myFlags = nextTimeStep + nextTimeEdgeOK; // We want the next frame in the movie's media.
myTypes[0] = VisualMediaCharacteristic; // We want video samples.
// We search backward for the closest available image for the current time. Either we get the current time
// if we happen to fetch a frame exactly when it becomes ready, or we get a bit earlier timestamp, which is
// the optimal presentation timestamp for this frame:
GetMovieNextInterestingTime(theMovie, myFlags, 1, myTypes, GetMovieTime(theMovie, NULL), FloatToFixed(-1), &myNextTime, NULL);
}
// Convert pts (in Quicktime ticks) to pts in seconds since start of movie and return it:
*presentation_timestamp = (double) myNextTime / (double) GetMovieTimeScale(theMovie);
}
// Allow quicktime visual context task to do its internal bookkeeping and cleanup work:
if (theMoviecontext) QTVisualContextTask(theMoviecontext);
// Perform decompress-operation:
if (checkForImage) MoviesTask(theMovie, 0);
// Should we just check for new image? If so, just return availability status:
if (checkForImage) {
if (PSYCH_USE_QT_GWORLDS) {
// We use GWorlds. In this case we either suceed immediately due to the
// synchronous nature of GWorld rendering, or we fail completely at end
// of non-looping movie:
if (IsMovieDone(theMovie) && movieRecordBANK[moviehandle].loopflag == 0) {
// No new frame available and there won't be any in the future, because this is a non-looping
// movie that has reached its end.
return(-1);
}
// Is this the special case of a movie without video, but only sound? In that case,
// we always return a 'false' because there ain't no image to return.
if (movieRecordBANK[moviehandle].QTMovieGWorld == NULL) return(false);
// Success!
return(true);
}
// Code which uses QTVisualContextTasks...
if (QTVisualContextIsNewImageAvailable(theMoviecontext, NULL)) {
// New frame ready!
return(true);
}
else if (IsMovieDone(theMovie) && movieRecordBANK[moviehandle].loopflag == 0) {
// No new frame available and there won't be any in the future, because this is a non-looping
// movie that has reached its end.
return(-1);
}
else {
// No new frame available yet:
return(false);
}
}
if (!PSYCH_USE_QT_GWORLDS) {
// Blocking wait-code for non-GWorld mode:
// Try up to 1000 iterations for arrival of requested image data in wait-mode:
failcount=0;
while ((failcount < 1000) && !QTVisualContextIsNewImageAvailable(theMoviecontext, NULL)) {
PsychWaitIntervalSeconds(0.005);
MoviesTask(theMovie, 0);
failcount++;
}
// No new frame available and there won't be any in the future, because this is a non-looping
// movie that has reached its end.
if ((failcount>=1000) && IsMovieDone(theMovie) && (movieRecordBANK[moviehandle].loopflag == 0)) {
return(-1);
}
// Fetch new OpenGL texture with the new movie image frame:
error = QTVisualContextCopyImageForTime(theMoviecontext, kCFAllocatorDefault, NULL, &newImage);
if ((error!=noErr) || newImage == NULL) {
PsychErrorExitMsg(PsychError_internal, "OpenGL<->Quicktime texture fetch failed!!!");
}
// Disable client storage, if it was enabled:
glPixelStorei(GL_UNPACK_CLIENT_STORAGE_APPLE, GL_FALSE);
// Build a standard PTB texture record:
CVOpenGLTextureGetCleanTexCoords (newImage, lowerLeft, lowerRight, upperRight, upperLeft);
texid = CVOpenGLTextureGetName(newImage);
// Assign texture rectangle:
PsychMakeRect(outRect, upperLeft[0], upperLeft[1], lowerRight[0], lowerRight[1]);
// Set texture orientation as if it were an inverted Offscreen window: Upside-down.
out_texture->textureOrientation = (CVOpenGLTextureIsFlipped(newImage)) ? 3 : 4;
// Assign OpenGL texture id:
out_texture->textureNumber = texid;
// Store special texture object as part of the PTB texture record:
out_texture->targetSpecific.QuickTimeGLTexture = newImage;
}
else {
// Synchronous texture fetch code for GWorld rendering mode:
// At this point, the GWorld should contain the source image for creating a
// standard OpenGL texture:
// Disable client storage, if it was enabled:
glPixelStorei(GL_UNPACK_CLIENT_STORAGE_APPLE, GL_FALSE);
// Build a standard PTB texture record:
// Assign texture rectangle:
GetMovieBox(theMovie, &rect);
// Hack: Need to extend rect by 4 pixels, because GWorlds are 4 pixels-aligned via
// image row padding:
rect.right = rect.right + 4;
PsychMakeRect(out_texture->rect, rect.left, rect.top, rect.right, rect.bottom);
// Set NULL - special texture object as part of the PTB texture record:
out_texture->targetSpecific.QuickTimeGLTexture = NULL;
// Set texture orientation as if it were an inverted Offscreen window: Upside-down.
out_texture->textureOrientation = 3;
// Setup a pointer to our GWorld as texture data pointer:
out_texture->textureMemorySizeBytes = 0;
// Quicktime textures are aligned on 4 Byte boundaries:
out_texture->textureByteAligned = 4;
// Lock GWorld:
if(!LockPixels(GetGWorldPixMap(movieRecordBANK[moviehandle].QTMovieGWorld))) {
// Locking surface failed! We abort.
PsychErrorExitMsg(PsychError_internal, "PsychQTGetTextureFromMovie(): Locking GWorld pixmap surface failed!!!");
}
// This will retrieve an OpenGL compatible pointer to the GWorlds pixel data and assign it to our texmemptr:
out_texture->textureMemory = (GLuint*) GetPixBaseAddr(GetGWorldPixMap(movieRecordBANK[moviehandle].QTMovieGWorld));
// Let PsychCreateTexture() do the rest of the job of creating, setting up and
// filling an OpenGL texture with GWorlds content:
PsychCreateTexture(out_texture);
// Undo hack from above after texture creation: Now we need the real width of the
// texture for proper texture coordinate assignments in drawing code et al.
rect.right = rect.right - 4;
PsychMakeRect(outRect, rect.left, rect.top, rect.right, rect.bottom);
// Unlock GWorld surface. We do a glFinish() before, for safety reasons...
//glFinish();
UnlockPixels(GetGWorldPixMap(movieRecordBANK[moviehandle].QTMovieGWorld));
// Ready to use the texture... We're done.
}
// Normalize texture rectangle and assign it:
PsychNormalizeRect(outRect, out_texture->rect);
rate = FixedToFloat(GetMovieRate(theMovie));
// Detection of dropped frames: This is a heuristic. We'll see how well it works out...
if (rate && presentation_timestamp) {
// Try to check for dropped frames in playback mode:
// Expected delta between successive presentation timestamps:
targetdelta = 1.0f / (movieRecordBANK[moviehandle].fps * rate);
// Compute real delta, given rate and playback direction:
if (rate>0) {
realdelta = *presentation_timestamp - movieRecordBANK[moviehandle].last_pts;
if (realdelta<0) realdelta = 0;
}
else {
realdelta = -1.0 * (*presentation_timestamp - movieRecordBANK[moviehandle].last_pts);
if (realdelta<0) realdelta = 0;
}
frames = realdelta / targetdelta;
// Dropped frames?
if (frames > 1 && movieRecordBANK[moviehandle].last_pts>=0) {
movieRecordBANK[moviehandle].nr_droppedframes += (int) (frames - 1 + 0.5);
}
movieRecordBANK[moviehandle].last_pts = *presentation_timestamp;
}
// Manually advance movie time, if in fetch mode:
if (0 == GetMovieRate(theMovie)) {
// We are in manual fetch mode: Need to manually advance movie time to next
// media sample:
if (nextFramesTime == myNextTime) {
// Invalid value? Try to hack something that gets us unstuck:
myNextTime = GetMovieTime(theMovie, NULL);
nextFramesTime = myNextTime + (TimeValue) 1;
}
SetMovieTimeValue(theMovie, nextFramesTime);
}
// Check if end of movie is reached. Rewind, if so...
if (IsMovieDone(theMovie) && movieRecordBANK[moviehandle].loopflag > 0) {
if (GetMovieRate(theMovie)>0) {
GoToBeginningOfMovie(theMovie);
} else {
GoToEndOfMovie(theMovie);
}
}
return(TRUE);
}
PsychError SCREENWaitBlanking(void)
{
PsychWindowRecordType *windowRecord;
int waitFrames, framesWaited;
double tvbl, ifi;
long screenwidth, screenheight;
int vbl_startline, beampos, lastline;
psych_uint64 vblCount, vblRefCount;
CGDirectDisplayID cgDisplayID;
GLint read_buffer, draw_buffer;
// All subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(2)); //The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(1)); //The required number of inputs
PsychErrorExit(PsychCapNumOutputArgs(1)); //The maximum number of outputs
// Get the window record from the window record argument and get info from the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
if(!PsychIsOnscreenWindow(windowRecord))
PsychErrorExitMsg(PsychError_user, "Tried to call 'WaitBlanking' on something else than an onscreen window!");
// Get the number of frames to wait:
waitFrames = 0;
PsychCopyInIntegerArg(2, FALSE, &waitFrames);
// We default to wait at least one interval if no argument supplied:
waitFrames = (waitFrames < 1) ? 1 : waitFrames;
// Enable this windowRecords framebuffer as current drawingtarget:
// This is needed to make sure that Offscreen windows work propely.
PsychSetDrawingTarget(windowRecord);
// Retrieve display handle for beamposition queries:
PsychGetCGDisplayIDFromScreenNumber(&cgDisplayID, windowRecord->screenNumber);
// Retrieve final vbl_startline, aka physical height of the display in pixels:
PsychGetScreenSize(windowRecord->screenNumber, &screenwidth, &screenheight);
vbl_startline = (int) screenheight;
// Query duration of a monitor refresh interval: We try to use the measured interval,
// but fallback of the nominal value reported by the operating system if necessary:
if ((ifi = windowRecord->VideoRefreshInterval)<=0) {
if (PsychGetNominalFramerate(windowRecord->screenNumber) > 0) {
// Valid nominal framerate returned by OS: Calculate nominal IFI from it.
ifi = 1.0 / ((double) PsychGetNominalFramerate(windowRecord->screenNumber));
}
else {
// No reasonable value available! We fallback to an assumed 60 Hz refresh...
ifi = 1.0 / 60.0;
}
}
// Query vblcount to test if this method works correctly:
PsychOSGetVBLTimeAndCount(windowRecord, &vblRefCount);
// Check if beamposition queries are supported by this OS and working properly:
if (-1 != PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber) && windowRecord->VBL_Endline >= 0) {
// Beamposition queries supported and fine. We can wait for VBL without bufferswap-tricks:
// This is the OS-X way of doing things. We query the rasterbeamposition and compare it
// to the known values for the VBL area. If we enter VBL, we take a timestamp and return -
// or wait for the next VBL if waitFrames>0
// Query current beamposition when entering WaitBlanking:
beampos = PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber);
// Are we in VBL when entering WaitBlanking? If so, we should wait for one additional frame,
// because by definition, WaitBlanking should always wait for at least one monitor refresh
// interval...
if ((beampos<=windowRecord->VBL_Endline) && (beampos>=vbl_startline)) waitFrames++;
while(waitFrames > 0) {
// Enough time for a sleep? If the beam is far away from VBL area, we try to sleep to
// yield some CPU time to other processes in the system -- we are nice citizens ;)
beampos = PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber);
while (( ((float)(vbl_startline - beampos)) / (float) windowRecord->VBL_Endline * ifi) > 0.003) {
// At least 3 milliseconds left until retrace. We sleep for 1 millisecond.
PsychWaitIntervalSeconds(0.001);
beampos = PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber);
}
// Less than 3 ms away from retrace. Busy-Wait for retrace...
lastline = PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber);
beampos = lastline;
while ((beampos < vbl_startline) && (beampos >= lastline)) {
lastline = beampos;
beampos = (long) PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber);
}
// Retrace! Take system timestamp of VBL onset:
PsychGetAdjustedPrecisionTimerSeconds(&tvbl);
// If this wasn't the last frame to wait, we need to wait for end of retrace before
// repeating the loop, because otherwise we would detect the same VBL and skip frames.
// If it is the last frame, we skip it and return as quickly as possible to save the
// Matlab script some extra Millisecond for drawing...
if (waitFrames>1) {
beampos = vbl_startline;
while ((beampos<=windowRecord->VBL_Endline) && (beampos>=vbl_startline)) { beampos = PsychGetDisplayBeamPosition(cgDisplayID, windowRecord->screenNumber); };
}
// Done with this refresh interval...
// Decrement remaining number of frames to wait:
waitFrames--;
}
}
else if (vblRefCount > 0) {
// Display beamposition queries unsupported, but vblank count queries seem to work. Try those.
// Should work on Linux and OS/X:
while(waitFrames > 0) {
vblCount = vblRefCount;
// Wait for next vblank counter increment - aka start of next frame (its vblank):
while (vblCount == vblRefCount) {
// Requery:
PsychOSGetVBLTimeAndCount(windowRecord, &vblCount);
// Yield at least 100 usecs. This is accurate as this code-path
// only executes on OS/X and Linux, never on Windows (as of 01/06/2011):
PsychYieldIntervalSeconds(0.000100);
}
vblRefCount = vblCount;
// Done with this refresh interval...
// Decrement remaining number of frames to wait:
waitFrames--;
}
}
else {
// Other methods unsupported. We use the doublebuffer swap method of waiting for retrace.
//
// Working principle: On each frame, we first copy the content of the (user visible) frontbuffer into the backbuffer.
// Then we ask the OS to perform a front-backbuffer swap on next vertical retrace and go to sleep via glFinish() et al.
// until the OS signals swap-completion. This way PTB's/Matlabs execution will stall until VBL, when swap happens and
// we get woken up. We repeat this procedure 'waitFrames' times, then we take a high precision timestamp and exit the
// Waitblanking loop. As backbuffer and frontbuffer are identical (due to the copy) at swap time, the visual display
// won't change at all for the subject.
// This method should work reliably, but it has one drawback: A random wakeup delay (scheduling jitter) is added after
// retrace has been entered, so Waitblanking returns only after the beam has left retrace state on older hardware.
// This means a bit less time (1 ms?) for stimulus drawing on Windows than on OS-X where Waitblanking returns faster.
// Child protection:
if (windowRecord->windowType != kPsychDoubleBufferOnscreen) {
PsychErrorExitMsg(PsychError_internal, "WaitBlanking tried to perform swap-waiting on a single buffered window!");
}
// Setup buffers for front->back copy op:
// Backup old read- writebuffer assignments:
glGetIntegerv(GL_READ_BUFFER, &read_buffer);
glGetIntegerv(GL_DRAW_BUFFER, &draw_buffer);
// Set read- and writebuffer properly:
glReadBuffer(GL_FRONT);
glDrawBuffer(GL_BACK);
// Reset viewport to full-screen default:
glViewport(0, 0, screenwidth, screenheight);
glScissor(0, 0, screenwidth, screenheight);
// Reset color buffer writemask to "All enabled":
glColorMask(TRUE, TRUE, TRUE, TRUE);
glDisable(GL_BLEND);
glPixelZoom(1,1);
// Disable draw shader:
PsychSetShader(windowRecord, 0);
// Swap-Waiting loop for 'waitFrames' frames:
while(waitFrames > 0) {
// Copy current content of front buffer into backbuffer:
glRasterPos2i(0, screenheight);
glCopyPixels(0, 0, screenwidth, screenheight, GL_COLOR);
// Ok, front- and backbuffer are now identical, so a bufferswap
// will be a visual no-op.
// Enable beamsyncing of bufferswaps to VBL:
PsychOSSetVBLSyncLevel(windowRecord, 1);
// Trigger bufferswap in sync with retrace:
PsychOSFlipWindowBuffers(windowRecord);
// Wait for swap-completion, aka beginning of VBL:
PsychWaitPixelSyncToken(windowRecord);
// VBL happened - Take system timestamp:
PsychGetAdjustedPrecisionTimerSeconds(&tvbl);
// This code-chunk is an alternate way of syncing, only used for debugging:
if (false) {
// Disable beamsyncing of bufferswaps to VBL:
PsychOSSetVBLSyncLevel(windowRecord, 0);
// Swap buffers immediately without vsync:
PsychOSFlipWindowBuffers(windowRecord);
}
// Decrement remaining number of frames to wait:
waitFrames--;
} // Do it again...
// Enable beamsyncing of bufferswaps to VBL:
PsychOSSetVBLSyncLevel(windowRecord, 1);
// Restore assignment of read- writebuffers and such:
glEnable(GL_BLEND);
glReadBuffer(read_buffer);
glDrawBuffer(draw_buffer);
// Done with Windows waitblanking...
}
// Compute number of frames waited: It is timestamp of return of this waitblanking minus
// timestamp of return of last waitblanking, divided by duration of a monitor refresh
// interval, mathematically rounded to an integral number:
framesWaited = (int) (((tvbl - windowRecord->time_at_last_vbl) / ifi) + 0.5f);
// Update timestamp for next invocation of Waitblanking:
windowRecord->time_at_last_vbl = tvbl;
// Return optional number of frames waited:
PsychCopyOutDoubleArg(1, FALSE, (double) framesWaited);
// Done.
return(PsychError_none);
}
