PsychError PSYCHHIDGiveMeReports(void)
{
PsychGenericScriptType *outErr;
const char *fieldNames[] = {"n", "name", "description"};
char *name = "", *description = "";
long error = 0;
int deviceIndex;
int reportBytes = 1024;
PsychPushHelp(useString,synopsisString,seeAlsoString);
if (PsychIsGiveHelp()) { PsychGiveHelp(); return(PsychError_none); };
PsychErrorExit(PsychCapNumOutputArgs(2));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychCopyInIntegerArg(1,TRUE,&deviceIndex);
PsychCopyInIntegerArg(2,false,&reportBytes);
PsychHIDVerifyInit();
// Returns 1st return argument 'reports':
error = GiveMeReports(deviceIndex,reportBytes); // PsychHIDReceiveReports.c
// Return 2nd return argument 'err' struct:
PsychHIDErrors(NULL, error, &name, &description);
PsychAllocOutStructArray(2, kPsychArgOptional, -1, 3, fieldNames, &outErr);
PsychSetStructArrayStringElement("name", 0, name, outErr);
PsychSetStructArrayStringElement("description", 0, description, outErr);
PsychSetStructArrayDoubleElement("n", 0, (double) error, outErr);
return(PsychError_none);
}
PsychError SCREENSetMouseHelper(void)
{
int screenNumber;
int xPos, yPos;
int deviceIdx = -1;
int detachFromMouse = 0;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(5)); //The maximum number of inputs
PsychErrorExit(PsychCapNumOutputArgs(0)); //The maximum number of outputs
PsychCopyInScreenNumberArg(1, TRUE, &screenNumber);
PsychCopyInIntegerArg(2,TRUE, &xPos);
PsychCopyInIntegerArg(3,TRUE, &yPos);
PsychCopyInIntegerArg(4,FALSE, &deviceIdx);
PsychCopyInIntegerArg(5,FALSE, &detachFromMouse);
// Position the cursor. On OSX this will also automatically attach it
// to mouse movement:
PsychPositionCursor(screenNumber, xPos, yPos, deviceIdx);
#if PSYCH_SYSTEM == PSYCH_OSX
if (detachFromMouse) CGAssociateMouseAndMouseCursorPosition(false);
#endif
return(PsychError_none);
}
PsychError PSYCHHIDOpenUSBDevice(void)
{
PsychUSBSetupSpec deviceSpec;
int deviceID, vendorID, configurationId;
int errcode;
int usbHandle = -1;
PsychUSBDeviceRecord *usbDev = NULL;
// Setup the help features.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if (PsychIsGiveHelp()) {
PsychGiveHelp();
return PsychError_none;
}
// Make sure the correct number of input arguments is supplied.
PsychErrorExit(PsychCapNumInputArgs(3));
PsychErrorExit(PsychRequireNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
// Grab the mandatory vendor and device IDs.
PsychCopyInIntegerArg(1, TRUE, &vendorID);
PsychCopyInIntegerArg(2, TRUE, &deviceID);
// Try to get free slot in internal device bank: This will error-exit if no capacity left.
usbDev = PsychHIDGetFreeUSBDeviceSlot(&usbHandle);
// Setup specification of wanted device:
// So far we only match against vendorID and deviceID, but may want to extend this
// to more options in the future. That's why its passed via a PsychUSBSetupSpec struct.
// -> Can rather easily extend that struct (and corresponding open routines) with new
// fields without major code rewrites in other places.
deviceSpec.vendorID = vendorID;
deviceSpec.deviceID = deviceID;
// This is the index of the device configuration to choose: Defaults to zero.
configurationId = 0;
PsychCopyInIntegerArg(3, FALSE, &configurationId);
deviceSpec.configurationID = (int) configurationId;
// Try to open the device. This will init the device structure properly and
// also set the valid flag to "active/open" if open succeeds:
if (!PsychHIDOSOpenUSBDevice(usbDev, &errcode, &deviceSpec)) {
// MK TODO: We don't set or use 'errcode' yet.
PsychErrorExitMsg(PsychError_user, "Failed to open the specified type of generic USB device. Make sure it is plugged in or not already open.");
}
// Return device handle:
PsychCopyOutDoubleArg(1, FALSE, (double) usbHandle);
return PsychError_none;
}
PsychError SCREENStopVideoCapture(void)
{
int capturehandle = -1;
int dropped;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(1)); // Max. 1 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // One output arg.
// Get the handle:
PsychCopyInIntegerArg(1, TRUE, &capturehandle);
if (capturehandle==-1) {
PsychErrorExitMsg(PsychError_user, "StopVideoCapture called without valid handle to a capture object.");
}
// Try to stop capture:
dropped = PsychVideoCaptureRate(capturehandle, 0, 0, NULL);
PsychCopyOutDoubleArg(1, FALSE, dropped);
// Ready!
return(PsychError_none);
}
// Open a serial port on a serial port device:
PsychError IOPORTConfigureSerialPort(void)
{
static char useString[] = "IOPort('ConfigureSerialPort', handle, configString);";
static char synopsisString[] =
"(Re-)Configure a serial port device, specified by 'handle'.\n"
"The string 'configString' is a string with pairs of paramName=paramValue "
"tokens, separated by a delimiter, e.g., a space. It allows to specify specific "
"values 'paramValue' to specific serial port parameters 'paramName'. Not all "
"parameters are supported by all operating systems, and all settings have reasonable "
"defaults. Settings unknown to a specific operating system are ignored.\n\n"
"See the help of 'OpenSerialPort' for possible settings.";
static char seeAlsoString[] = "'OpenSerialPort'";
char* configString = NULL;
PsychSerialDeviceRecord* device = NULL;
int handle;
// Setup online help:
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none); };
PsychErrorExit(PsychCapNumInputArgs(2)); // The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(2)); // The required number of inputs
PsychErrorExit(PsychCapNumOutputArgs(0)); // The maximum number of outputs
// Get required portSpec:
PsychCopyInIntegerArg(1, kPsychArgRequired, &handle);
// Get the configString:
PsychAllocInCharArg(2, kPsychArgRequired, &configString);
// Return return value of configuration call:
return(PsychIOOSConfigureSerialPort(PsychGetPortIORecord(handle)->device, configString));
}
PsychError SCREENCloseMovie(void)
{
int moviehandle = -1;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(1)); // Max. 1 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(0)); // No output args.
// Get the window record from the window record argument and get info from the window record
//PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
// Get the movie handle:
PsychCopyInIntegerArg(1, TRUE, &moviehandle);
if (moviehandle==-1) {
PsychErrorExitMsg(PsychError_user, "CloseMovie called without valid handle to a movie object.");
}
// Try to delete the movie object, releasing all associated ressources:
PsychDeleteMovie(moviehandle);
return(PsychError_none);
}
PsychError IOPORTVerbosity(void)
{
static char useString[] = "oldlevel = IOPort('Verbosity' [,level]);";
static char synopsisString[] =
"Set level of verbosity for error/warning/status messages. 'level' optional, new level "
"of verbosity. 'oldlevel' is the old level of verbosity. The following levels are "
"supported: 0 = Shut up. 1 = Print errors, 2 = Print also warnings, 3 = Print also some info, "
"4 = Print more useful info (default), >5 = Be very verbose (mostly for debugging the driver itself). ";
static char seeAlsoString[] = "";
int level= -1;
// Setup online help:
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none); };
PsychErrorExit(PsychCapNumInputArgs(1)); // The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(0)); // The required number of inputs
PsychErrorExit(PsychCapNumOutputArgs(1)); // The maximum number of outputs
PsychCopyInIntegerArg(1, kPsychArgOptional, &level);
if (level < -1) PsychErrorExitMsg(PsychError_user, "Invalid level of verbosity provided. Valid are levels of zero and greater.");
// Return current/old level:
PsychCopyOutDoubleArg(1, kPsychArgOptional, (double) verbosity);
// Set new level, if one was provided:
if (level > -1) verbosity = level;
return(PsychError_none);
}
PsychError PSYCHHIDKbCheck(void)
{
int deviceIndex;
int m, n, p;
double *scanList = NULL;
psych_bool isDeviceSpecified;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(3));
PsychErrorExit(PsychCapNumInputArgs(2));
// Choose the device index and its record
isDeviceSpecified=PsychCopyInIntegerArg(1, FALSE, &deviceIndex);
if (!isDeviceSpecified) {
// set the keyboard or keypad device to be the first keyboard device or, if no keyboard, the first keypad
deviceIndex = INT_MAX;
}
// Optional 2nd argument 'scanlist' provided?
if (PsychAllocInDoubleMatArg(2, FALSE, &m, &n, &p, &scanList)) {
// Yep. Matching size?
if (p!=1 || m * n != 256) PsychErrorExitMsg(PsychError_user, "Provided 'scanList' parameter is not a vector of 256 doubles, as required!");
}
return(PsychHIDOSKbCheck(deviceIndex, scanList));
}
PsychError SCREENRect(void)
{
PsychWindowRecordType *windowRecord;
int screenNumber;
PsychRectType rect;
int realFBSize = 0;
//all sub functions should have these two lines
PsychPushHelp(useString, synopsisString,seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check for superfluous arguments
PsychErrorExit(PsychCapNumInputArgs(2)); //The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(1)); //Insist that the argument be present.
PsychErrorExit(PsychCapNumOutputArgs(1)); //The maximum number of outputs
// Get optional 'realFBSize' flag: Defaults to zero.
PsychCopyInIntegerArg(2, FALSE, &realFBSize);
if(PsychIsScreenNumberArg(1)){
PsychCopyInScreenNumberArg(1, TRUE, &screenNumber);
PsychGetScreenRect(screenNumber, rect);
PsychCopyOutRectArg(1, FALSE, rect);
}else if(PsychIsWindowIndexArg(1)){
PsychAllocInWindowRecordArg(1, TRUE, &windowRecord);
PsychOSProcessEvents(windowRecord, 0);
PsychCopyOutRectArg(1, FALSE, (realFBSize) ? windowRecord->rect : windowRecord->clientrect);
}else
PsychErrorExitMsg(PsychError_user, "Argument was recognized as neither a window index nor a screen pointer");
return(PsychError_none);
}
// Close given port.
PsychError IOPORTClose(void)
{
static char useString[] = "IOPort('Close', handle);";
static char synopsisString[] =
"Close a I/O port device 'handle'. This works for all device types.\n";
static char seeAlsoString[] = "'CloseAll'";
int handle;
// Setup online help:
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none); };
PsychErrorExit(PsychCapNumInputArgs(1)); // The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(1)); // The required number of inputs
PsychErrorExit(PsychCapNumOutputArgs(0)); // The maximum number of outputs
// Get handle:
PsychCopyInIntegerArg(1, kPsychArgRequired, &handle);
// Close associated port:
PsychCloseIOPort(handle);
return(PsychError_none);
}
PsychError PSYCHHIDKbTriggerWait(void)
{
int deviceIndex;
int numScankeys;
int* scanKeys;
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.
// Identify the mandatory trigger array:
if (!PsychAllocInIntegerListArg(1, TRUE, &numScankeys, &scanKeys)){
PsychErrorExitMsg(PsychError_user, "Keycode is required.");
}
// Get optional deviceIndex:
if (!PsychCopyInIntegerArg(2, FALSE, &deviceIndex)) deviceIndex = -1;
// Execute:
PsychHIDOSKbTriggerWait(deviceIndex, numScankeys, scanKeys);
return(PsychError_none);
}
PsychError SCREENTextStyle(void)
{
boolean doSetStyle;
PsychWindowRecordType *windowRecord;
int oldTextStyle, newTextStyle;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check for valid number of arguments
PsychErrorExit(PsychRequireNumInputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
//Get the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
//Save the old text size value and return it.
oldTextStyle=windowRecord->textAttributes.textStyle;
PsychCopyOutDoubleArg(1, FALSE, (double)oldTextStyle);
//Fetch and set the new size if it is specified.
doSetStyle= PsychCopyInIntegerArg(2, FALSE, &newTextStyle);
if(doSetStyle)
windowRecord->textAttributes.textStyle=newTextStyle;
return(PsychError_none);
}
PsychError SCREENFinalizeMovie(void)
{
static char useString[] = "Screen('FinalizeMovie', moviePtr);";
static char synopsisString[] = "Finish creating a new movie file with handle 'moviePtr' and store it to filesystem.\n";
static char seeAlsoString[] = "CreateMovie AddFrameToMovie CloseMovie PlayMovie GetMovieImage GetMovieTimeIndex SetMovieTimeIndex";
int moviehandle = -1;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(1)); // Max. 3 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(0)); // Max. 1 output args.
// Get the moviehandle:
PsychCopyInIntegerArg(1, kPsychArgRequired, &moviehandle);
// Finalize the movie:
if (!PsychFinalizeNewMovieFile(moviehandle)) {
PsychErrorExitMsg(PsychError_user, "FinalizeMovie failed for reason mentioned above.");
}
return(PsychError_none);
}
PsychError PSYCHHIDReceiveReportsStop(void)
{
long error=0;
int deviceIndex;
mxArray **outErr;
PsychPushHelp(useString,synopsisString,seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(1));
PsychCopyInIntegerArg(1,TRUE,&deviceIndex);
error=ReceiveReportsStop(deviceIndex);
outErr=PsychGetOutArgMxPtr(1);
if(outErr!=NULL){
char *name="",*description="";
const char *fieldNames[]={"n", "name", "description"};
mxArray *fieldValue;
PsychHIDErrors(NULL, error,&name,&description); // Get error name and description, if available.
*outErr=mxCreateStructMatrix(1,1,3,fieldNames);
fieldValue=mxCreateString(name);
if(fieldValue==NULL)PrintfExit("Couldn't allocate \"err\".");
mxSetField(*outErr,0,"name",fieldValue);
fieldValue=mxCreateString(description);
if(fieldValue==NULL)PrintfExit("Couldn't allocate \"err\".");
mxSetField(*outErr,0,"description",fieldValue);
fieldValue=mxCreateDoubleMatrix(1,1,mxREAL);
if(fieldValue==NULL)PrintfExit("Couldn't allocate \"err\".");
*mxGetPr(fieldValue)=(double)error;
mxSetField(*outErr,0,"n",fieldValue);
}
return(PsychError_none);
}
PsychError SCREENStartVideoCapture(void)
{
int capturehandle = -1;
double captureFPS = 25;
int dropframes = 0;
double starttime = 0;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(4)); // Max. 4 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(2)); // Max. 2 output args.
// Get the handle:
PsychCopyInIntegerArg(1, TRUE, &capturehandle);
if (capturehandle==-1) {
PsychErrorExitMsg(PsychError_user, "StartVideoCapture called without valid handle to a capture object.");
}
PsychCopyInDoubleArg(2, FALSE, &captureFPS);
if (captureFPS<=0) {
PsychErrorExitMsg(PsychError_user, "StartVideoCapture called with a negative capture rate.");
}
PsychCopyInIntegerArg(3, FALSE, &dropframes);
if (dropframes<0) {
PsychErrorExitMsg(PsychError_user, "StartVideoCapture called with invalid (negative) dropframes - argument.");
}
PsychCopyInDoubleArg(4, FALSE, &starttime);
if (starttime<0) {
PsychErrorExitMsg(PsychError_user, "StartVideoCapture called with invalid (negative) startAt - argument.");
}
// Try to start capture:
captureFPS = (double) PsychVideoCaptureRate(capturehandle, captureFPS, dropframes, &starttime);
PsychCopyOutDoubleArg(1, FALSE, captureFPS);
PsychCopyOutDoubleArg(2, FALSE, starttime);
// Ready!
return(PsychError_none);
}
PsychError SCREENPlayMovie(void)
{
int moviehandle = -1;
double rate = 0;
int loop = 0;
double sndvolume = 1;
double dropped = 0;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(4)); // Max. 4 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // Max. 1 output args.
// Get the movie handle:
PsychCopyInIntegerArg(1, TRUE, &moviehandle);
if (moviehandle==-1) {
PsychErrorExitMsg(PsychError_user, "PlayMovie called without valid handle to a movie object.");
}
// Get the requested playback rate.
PsychCopyInDoubleArg(2, TRUE, &rate);
// Get the 'loop' flag: If zero, we don't loop, otherwise we loop.
PsychCopyInIntegerArg(3, FALSE, &loop);
// Get the requested sound volume. Defaults to 1 == Full blast!
PsychCopyInDoubleArg(4, FALSE, &sndvolume);
if (sndvolume<0) sndvolume = 0;
if (sndvolume>1) sndvolume = 1;
// Start playback via low-level routines:
dropped = (double) PsychPlaybackRate(moviehandle, rate, loop, sndvolume);
// Return optional count of dropped frames:
PsychCopyOutDoubleArg(1, FALSE, dropped);
// Ready!
return(PsychError_none);
}
PsychError PSYCHHIDGetRawState(void)
{
int deviceIndex, elementIndex;
double value;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychCopyInIntegerArg(1, TRUE, &deviceIndex);
PsychCopyInIntegerArg(2, TRUE, &elementIndex);
PsychHIDOSGamePadAxisQuery(deviceIndex, elementIndex, NULL, NULL, &value, NULL);
if (PSYCH_SYSTEM != PSYCH_LINUX) PsychCopyOutDoubleArg(1, FALSE, value);
return(PsychError_none);
}
PsychError PSYCHHIDGiveMeReports(void)
{
long error=0;
int deviceIndex;
int reportBytes=1024;
mxArray **outErr;
pRecDevice device;
PsychPushHelp(useString,synopsisString,seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(2));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychCopyInIntegerArg(1,TRUE,&deviceIndex);
PsychCopyInIntegerArg(2,false,&reportBytes);
PsychHIDVerifyInit();
device=PsychHIDGetDeviceRecordPtrFromIndex(deviceIndex);
if(!HIDIsValidDevice(device))PrintfExit("PsychHID:GiveMeReports: Invalid device.\n");
// reports
error=GiveMeReports(deviceIndex,reportBytes); // PsychHIDReceiveReports.c
// err
outErr=PsychGetOutArgMxPtr(2); // outErr==NULL if optional argument is absent.
if(outErr!=NULL){
const char *fieldNames[]={"n", "name", "description"};
mxArray *fieldValue;
char *name="",*description="";
PsychHIDErrors(error,&name,&description); // Get error name and description, if available.
*outErr=mxCreateStructMatrix(1,1,3,fieldNames);
fieldValue=mxCreateString(name);
mxSetField(*outErr,0,"name",fieldValue);
fieldValue=mxCreateString(description);
mxSetField(*outErr,0,"description",fieldValue);
fieldValue=mxCreateDoubleMatrix(1,1,mxREAL);
*mxGetPr(fieldValue)=(double)error;
mxSetField(*outErr,0,"n",fieldValue);
}
return(PsychError_none);
}
PsychError SCREENSetMouseHelper(void)
{
int screenNumber;
int xPos, yPos;
int deviceIdx = -1;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(4)); //The maximum number of inputs
PsychErrorExit(PsychCapNumOutputArgs(0)); //The maximum number of outputs
PsychCopyInScreenNumberArg(1, TRUE, &screenNumber);
PsychCopyInIntegerArg(2,TRUE, &xPos);
PsychCopyInIntegerArg(3,TRUE, &yPos);
PsychCopyInIntegerArg(4,FALSE, &deviceIdx);
PsychPositionCursor(screenNumber, xPos, yPos, deviceIdx);
return(PsychError_none);
}
PsychError SCREENAddAudioBufferToMovie(void)
{
static char useString[] = "Screen('AddAudioBufferToMovie', moviePtr, audioBuffer);";
static char synopsisString[] =
"Add a buffer filled with audio data samples to movie 'moviePtr'.\n"
"This function is only supported with the GStreamer based movie writing functions. "
"It doesn't work on MS-Windows with Matlab versions before R2007a and it doesn't work "
"on Apple OS/X yet.\n"
"The movie must have been created in 'CreateMovie' with an options string that "
"enables writing of an audio track into the movie, otherwise this function will fail.\n"
"You enable writing of audio tracks by adding the keyword 'AddAudioTrack' to the options string.\n"
"Alternatively, if your options string is a gst-launch style pipeline description, it must contain "
"one pipeline element with a name option of 'name=ptbaudioappsrc'.\n"
"'audioBuffer' must be 'numChannels' rows by 'numSamples' columns double matrix of audio data. "
"Each row encodes one audio channel, each column element in a row encodes a sample. "
"E.g., a 2-by-48000 matrix would encode 48000 samples for a two channel stereo sound track.\n"
"Sample values must lie in the range between -1.0 and +1.0.\n"
"The audio buffer is converted into a movie specific sound format and then appended to "
"the audio samples already stored in the audio track.\n"
"\n";
static char seeAlsoString[] = "FinalizeMovie AddFrameToMovie CloseMovie PlayMovie GetMovieImage GetMovieTimeIndex SetMovieTimeIndex";
int moviehandle = -1;
int m, n, p;
double* buffer;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {
PsychGiveHelp();
return(PsychError_none);
};
PsychErrorExit(PsychCapNumInputArgs(2)); // Max. 2 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(0)); // Max. 0 output args.
// Get movie handle:
PsychCopyInIntegerArg(1, kPsychArgRequired, &moviehandle);
// And audio date buffer:
PsychAllocInDoubleMatArg(2, kPsychArgRequired, &m, &n, &p, &buffer);
if (p!=1 || m < 1 || n < 1) PsychErrorExitMsg(PsychError_user, "Invalid audioBuffer provided. Must be a 2D matrix with at least one row and at least one column!");
// Pass audio data to movie writing engine:
PsychAddAudioBufferToMovie(moviehandle, m, n, buffer);
return(PsychError_none);
}
PsychError SCREENTextStyle(void)
{
psych_bool doSetStyle, foundFont;
PsychWindowRecordType *windowRecord;
int oldTextStyle, newTextStyle;
#if PSYCH_SYSTEM == PSYCH_OSX
PsychFontStructType *fontRecord;
#endif
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check for valid number of arguments
PsychErrorExit(PsychRequireNumInputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
//Get the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
//Save the old text size value and return it.
oldTextStyle=windowRecord->textAttributes.textStyle;
PsychCopyOutDoubleArg(1, FALSE, (double)oldTextStyle);
//Fetch and set the new size if it is specified.
doSetStyle= PsychCopyInIntegerArg(2, FALSE, &newTextStyle);
if (doSetStyle) {
windowRecord->textAttributes.needsRebuild|=(windowRecord->textAttributes.textStyle != newTextStyle) ? TRUE : FALSE;
windowRecord->textAttributes.textStyle=newTextStyle;
#if PSYCH_SYSTEM == PSYCH_OSX
// Need to update font name and number from changed style on OS/X:
foundFont = PsychGetFontRecordFromFontFamilyNameAndFontStyle((char*) windowRecord->textAttributes.textFontName, windowRecord->textAttributes.textStyle, &fontRecord);
if (foundFont) {
strncpy((char*) windowRecord->textAttributes.textFontName, (const char*) fontRecord->fontFMFamilyName, 255);
windowRecord->textAttributes.textFontNumber= fontRecord->fontNumber;
}
else {
// Failed! Revert to old setting:
windowRecord->textAttributes.textStyle = oldTextStyle;
}
#endif
}
return(PsychError_none);
}
/* This function is called by the special subfunction 'DescribeModuleFunctionsHelper'.
* It returns the full table of registered subfunction names as an array.
* Useful for automatic documentation generators...
*
*/
PsychError PsychDescribeModuleFunctions(void)
{
static char useString[] = "subfunctionNames = Modulename('DescribeModuleFunctionsHelper' [, mode] [, subfunctionName]);";
static char synopsisString[] = "Return a cell array of strings naming all subfunctions supported by this module if "
"the optional 'subfunctionName' argument is omitted. If 'subfunctionName' is a "
"string with a valid subfunction name for the module, and 'mode' is 1, return a 3 element cell "
"array of strings which describe the detailed syntax, help and see also strings "
"for that function - the text you'd get for Modulename('subfunctionName?'); ";
static char seeAlsoString[] = "";
char* subfname;
int i;
PsychGenericScriptType *cellVector;
PsychFunctionPtr fcn;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
// Check for valid number of arguments
PsychErrorExit(PsychCapNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychCopyInIntegerArg(1, FALSE, &i);
subfname = NULL;
PsychAllocInCharArg(2, FALSE, &subfname);
if (subfname) {
// Find named subfunction in functin table:
fcn = PsychGetProjectFunction(subfname);
if (fcn) {
// This will trigger the subfunction 'fcn' to execute its PsychGiveHelp() method, then
// return. PsychGiveHelp() will return the help text to Runtime as cell array of strings,
// instead of printing to runtimes console:
PsychSetGiveHelp();
PsychOneShotReturnHelp();
(*fcn)();
PsychClearGiveHelp();
}
}
else {
// Generate a cell array to return
PsychAllocOutCellVector(1, FALSE, numFunctionsREGISTER, &cellVector);
for(i=0; i < numFunctionsREGISTER; i++) PsychSetCellVectorStringElement(i, functionTableREGISTER[i].name, cellVector);
}
return(PsychError_none);
}
PsychError PSYCHHIDKbQueueFlush(void)
{
int deviceIndex, flushType;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2));
deviceIndex = -1;
PsychCopyInIntegerArg(1, kPsychArgOptional, &deviceIndex);
flushType = 1;
PsychCopyInIntegerArg(2, kPsychArgOptional, &flushType);
// Return current count of contained events pre-flush:
PsychCopyOutDoubleArg(1, FALSE, (double) PsychHIDAvailEventBuffer((PSYCH_SYSTEM != PSYCH_OSX) ? deviceIndex : 0, (flushType & 4) ? 1 : 0));
if (flushType & 1) PsychHIDOSKbQueueFlush(deviceIndex);
if (flushType & 2) PsychHIDFlushEventBuffer((PSYCH_SYSTEM != PSYCH_OSX) ? deviceIndex : 0);
return(PsychError_none);
}
PsychError SCREENGetMovieTimeIndex(void)
{
int moviehandle = -1;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(1)); // Max. 1 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // One output arg.
// Get the movie handle:
PsychCopyInIntegerArg(1, TRUE, &moviehandle);
if (moviehandle==-1) {
PsychErrorExitMsg(PsychError_user, "GetMovieTimeIndex called without valid handle to a movie object.");
}
// Retrieve and return current movie time index:
PsychCopyOutDoubleArg(1, TRUE, PsychGetMovieTimeIndex(moviehandle));
// Ready!
return(PsychError_none);
}
PsychError SCREENWindowSize(void)
{
PsychWindowRecordType *windowRecord;
int screenNumber;
double rectWidth, rectHeight;
long fbWidth, fbHeight;
int realFBSize = 0;
//all sub functions should have these two lines
PsychPushHelp(useString, synopsisString,seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check for superfluous arguments
PsychErrorExit(PsychCapNumInputArgs(2)); //The maximum number of inputs
PsychErrorExit(PsychRequireNumInputArgs(1)); //Insist that the argument be present.
PsychErrorExit(PsychCapNumOutputArgs(2)); //The maximum number of outputs
// Get optional 'realFBSize' flag: Defaults to zero.
PsychCopyInIntegerArg(2, FALSE, &realFBSize);
if(PsychIsScreenNumberArg(1)){
PsychCopyInScreenNumberArg(1, TRUE, &screenNumber);
if (realFBSize) {
// Physical size in pixels:
PsychGetScreenPixelSize(screenNumber, &fbWidth, &fbHeight);
}
else {
// Logical size in points:
PsychGetScreenSize(screenNumber, &fbWidth, &fbHeight);
}
PsychCopyOutDoubleArg(1, kPsychArgOptional, fbWidth);
PsychCopyOutDoubleArg(2, kPsychArgOptional, fbHeight);
}else if(PsychIsWindowIndexArg(1)){
PsychAllocInWindowRecordArg(1, TRUE, &windowRecord);
PsychOSProcessEvents(windowRecord, 0);
rectWidth=PsychGetWidthFromRect((realFBSize) ? windowRecord->rect : windowRecord->clientrect);
rectHeight=PsychGetHeightFromRect((realFBSize) ? windowRecord->rect : windowRecord->clientrect);
PsychCopyOutDoubleArg(1, kPsychArgOptional, rectWidth);
PsychCopyOutDoubleArg(2, kPsychArgOptional, rectHeight);
}else
PsychErrorExitMsg(PsychError_user, "Argument was recognized as neither a window index nor a screen pointer");
return(PsychError_none);
}
PsychError SCREENTextFont(void)
{
boolean doSetByName, doSetByNumber, foundFont;
PsychWindowRecordType *windowRecord;
PsychFontStructType *fontRecord;
int oldTextFontNumber, inputTextFontNumber;
char *oldTextFontName, *inputTextFontName;
//all subfunctions should have these two lines.
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()){PsychGiveHelp();return(PsychError_none);};
//check for valid number of arguments
PsychErrorExit(PsychRequireNumInputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(2));
PsychErrorExit(PsychCapNumOutputArgs(2));
//Get the window record
PsychAllocInWindowRecordArg(kPsychUseDefaultArgPosition, TRUE, &windowRecord);
//Save the old text size value and return it.
oldTextFontNumber=windowRecord->textAttributes.textFontNumber;
PsychCopyOutDoubleArg(2, FALSE, (double)oldTextFontNumber);
oldTextFontName=windowRecord->textAttributes.textFontName;
PsychCopyOutCharArg(1, FALSE, oldTextFontName);
//Fetch and set the new font if specified by name or number
PsychCheckInputArgType(2, kPsychArgOptional, PsychArgType_double | PsychArgType_char); //if the argument is there check that it is the right type.
doSetByNumber= PsychCopyInIntegerArg(2, kPsychArgAnything, &inputTextFontNumber);
doSetByName= PsychAllocInCharArg(2, kPsychArgAnything, &inputTextFontName);
foundFont=0;
if(doSetByNumber)
foundFont=PsychGetFontRecordFromFontNumber(inputTextFontNumber, &fontRecord);
if(doSetByName)
foundFont=PsychGetFontRecordFromFontFamilyNameAndFontStyle(inputTextFontName, windowRecord->textAttributes.textStyle, &fontRecord);
if(foundFont){
strncpy(windowRecord->textAttributes.textFontName, fontRecord->fontFMFamilyName, 255);
windowRecord->textAttributes.textFontNumber= fontRecord->fontNumber;
}
return(PsychError_none);
}
PsychError PSYCHHIDKbQueueStop(void)
{
int deviceIndex;
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {
PsychGiveHelp();
return(PsychError_none);
};
PsychErrorExit(PsychCapNumOutputArgs(0));
PsychErrorExit(PsychCapNumInputArgs(1));
deviceIndex = -1;
PsychCopyInIntegerArg(1, kPsychArgOptional, &deviceIndex);
PsychHIDOSKbQueueStop(deviceIndex);
return(PsychError_none);
}
PsychError SCREENSetVideoCaptureParameter(void)
{
int capturehandle = -1;
double value = DBL_MAX;
double oldvalue;
char* pname = NULL;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(3)); // Max. 3 input args.
PsychErrorExit(PsychRequireNumInputArgs(2)); // Min. 2 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // One output arg.
// Get the device handle:
PsychCopyInIntegerArg(1, TRUE, &capturehandle);
if (capturehandle==-1) {
PsychErrorExitMsg(PsychError_user, "SetVideoCaptureParameter called without valid handle to a capture object.");
}
// Copy in parameter name string:
PsychAllocInCharArg(2, TRUE, &pname);
if (pname == NULL) {
PsychErrorExitMsg(PsychError_user, "SetVideoCaptureParameter called without a parameter name string.");
}
// Copy in (optional) value for parameter:
PsychCopyInDoubleArg(3, FALSE, &value);
// Try to set parameter:
oldvalue = PsychVideoCaptureSetParameter(capturehandle, pname, value);
// Return old value of capture parameter:
if (strstr(pname, "Get")==NULL) {
PsychCopyOutDoubleArg(1, FALSE, oldvalue);
}
// Ready!
return(PsychError_none);
}
PsychError SCREENVideoCaptureDevices(void)
{
int engineId;
// All sub functions should have these two lines
PsychPushHelp(useString2, synopsisString2, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(1)); // Max. 1 input args.
PsychErrorExit(PsychRequireNumInputArgs(0)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // Max. 1 output args.
engineId = PsychPrefStateGet_VideoCaptureEngine();
PsychCopyInIntegerArg(1, FALSE, &engineId);
// Do actual enumeration for the given engineId:
PsychEnumerateVideoSources(engineId, 1);
// Ready!
return(PsychError_none);
}
PsychError PRIORITYPriority(void)
{
double *returnValue;
pid_t processID;
int oldPriority, newPriority;
//check to see if the user supplied superfluous arguments
PsychErrorExit(PsychCapNumOutputArgs(1));
PsychErrorExit(PsychCapNumInputArgs(1));
//Allocate a return matrix and load it with the current process priority.
PsychAllocOutDoubleArg(1, FALSE, &returnValue);
processID= getpid();
oldPriority=getpriority(PRIO_PROCESS, processID);
*returnValue=(double)oldPriority;
//Fetch the input argument and set the priority
if(PsychCopyInIntegerArg(1, FALSE, &newPriority))
setpriority(PRIO_PROCESS, processID, newPriority);
return(PsychError_none);
}
