PsychError SCREENOpenVideoCapture(void)
{
PsychWindowRecordType *windowRecord;
int deviceIndex;
int capturehandle = -1;
double framerate;
int width;
int height;
PsychRectType roirectangle;
Boolean roiassigned;
int reqdepth = 0;
int num_dmabuffers = 0;
int allow_lowperf_fallback = 1;
char* moviename;
int recordingflags;
int engineId;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(9)); // Max. 9 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // Max. 1 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, "OpenVideoCapture called on something else than an onscreen window.");
}
// Get the device index. We default to the first device if none is given:
deviceIndex=0;
PsychCopyInIntegerArg(2, FALSE, &deviceIndex);
// Get the optional roi rectangle:
roiassigned = PsychCopyInRectArg(3, FALSE, roirectangle);
if (IsPsychRectEmpty(roirectangle)) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (empty) roirectangle argument.");
// Query (optional) output texture pixel depth: By default, we take whatever we get from the capture device:
PsychCopyInIntegerArg(4, FALSE, &reqdepth);
if (reqdepth<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) pixeldepth argument.");
// Query number of ringbuffers to use. Our default is coded in the OS dependent subroutines.
PsychCopyInIntegerArg(5, FALSE, &num_dmabuffers);
if (num_dmabuffers<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) numbuffers argument.");
// Query, if use of low-performance fallback code is allowed if high-perf engine fails:
PsychCopyInIntegerArg(6, FALSE, &allow_lowperf_fallback);
if (allow_lowperf_fallback<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) allowfallback flag.");
// Query optional moviename for recording the grabbed video into a Quicktime movie file:
moviename = NULL;
PsychAllocInCharArg(7, FALSE, &moviename);
// Query optional movie recording flags:
// 0 = Record video, stream to disk immediately (slower, but unlimited recording duration).
// 1 = Record video, stream to memory, then at end of recording to disk (limited duration by RAM size, but faster).
// 2 = Record audio as well.
recordingflags = 0;
PsychCopyInIntegerArg(8, FALSE, &recordingflags);
// Copy in optional id of video capture engine to use. We default to the one set via the Screen('Preference', 'DefaultVideocaptureEngine');
// setting, which by itself defaults to LibDC1394 (type 1) on Linux, and Quicktime/SG (type 0) on all other OSs.
engineId = PsychPrefStateGet_VideoCaptureEngine();
PsychCopyInIntegerArg(9, FALSE, &engineId);
if (engineId<0 || engineId>1) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid 'captureEngineType' argument. Valid are zero and one.");
// Try to open the capture device and create & initialize a corresponding capture object.
// A MATLAB handle to the video capture object is returned upon successfull operation.
if (roiassigned) {
PsychOpenVideoCaptureDevice(engineId, windowRecord, deviceIndex, &capturehandle, roirectangle, reqdepth, num_dmabuffers, allow_lowperf_fallback, moviename, recordingflags);
}
else {
PsychOpenVideoCaptureDevice(engineId, windowRecord, deviceIndex, &capturehandle, NULL, reqdepth, num_dmabuffers, allow_lowperf_fallback, moviename, recordingflags);
}
// Upon sucessfull completion, we'll have a valid handle in 'capturehandle'. Return it to Matlab-world:
PsychCopyOutDoubleArg(1, TRUE, (double) capturehandle);
// Ready!
return(PsychError_none);
}
PsychError SCREENOpenVideoCapture(void)
{
PsychWindowRecordType *windowRecord;
int deviceIndex;
int capturehandle = -1;
double framerate;
int width;
int height;
PsychRectType roirectangle;
psych_bool roiassigned;
int reqdepth = 0;
int num_dmabuffers = 0;
int allow_lowperf_fallback = 1;
char* moviename;
int recordingflags;
int engineId;
// All sub functions should have these two lines
PsychPushHelp(useString, synopsisString, seeAlsoString);
if(PsychIsGiveHelp()) {PsychGiveHelp(); return(PsychError_none);};
PsychErrorExit(PsychCapNumInputArgs(9)); // Max. 9 input args.
PsychErrorExit(PsychRequireNumInputArgs(1)); // Min. 1 input args required.
PsychErrorExit(PsychCapNumOutputArgs(1)); // Max. 1 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, "OpenVideoCapture called on something else than an onscreen window.");
}
// Get the device index. We default to the first device if none is given:
deviceIndex=0;
PsychCopyInIntegerArg(2, FALSE, &deviceIndex);
// Get the optional roi rectangle:
roiassigned = PsychCopyInRectArg(3, FALSE, roirectangle);
if (roiassigned && IsPsychRectEmpty(roirectangle)) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (empty) roirectangle argument.");
// Query (optional) output texture pixel depth: By default, we take whatever we get from the capture device:
PsychCopyInIntegerArg(4, FALSE, &reqdepth);
if (reqdepth<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) pixeldepth argument.");
// Query number of ringbuffers to use. Our default is coded in the OS dependent subroutines.
PsychCopyInIntegerArg(5, FALSE, &num_dmabuffers);
if (num_dmabuffers<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) numbuffers argument.");
// Query, if use of low-performance fallback code is allowed if high-perf engine fails:
PsychCopyInIntegerArg(6, FALSE, &allow_lowperf_fallback);
if (allow_lowperf_fallback<0) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid (negative) allowfallback flag.");
// Query optional moviename for recording the grabbed video into a Quicktime movie file:
moviename = NULL;
PsychAllocInCharArg(7, FALSE, &moviename);
// Query optional movie recording flags:
// 0 = Record video, stream to disk immediately (slower, but unlimited recording duration).
// 1 = Record video, stream to memory, then at end of recording to disk (limited duration by RAM size, but faster).
// 2 = Record audio as well.
// 4 = Do not return capture data via Screen('GetCapturedImage') during video recording to disc.
// 8 = Avoid some performance optimizations which may cause trouble with some codecs.
// 16= Use multi-threading for automatic background processing and cpu offloading.
// 32= Return high quality textures via 'GetCapturedImage' if recording in parallel --> Quality tradeoff live feed vs. recording.
// 64= Return timestamps in engine time instead of GetSecs() time.
recordingflags = 0;
PsychCopyInIntegerArg(8, FALSE, &recordingflags);
// Copy in optional id of video capture engine to use. We default to the one set via the Screen('Preference', 'DefaultVideocaptureEngine');
// setting, which by itself defaults to LibDC1394 (type 1) on Linux, ARVideo (type 2) and Quicktime/SG (type 0) on OS/X for now.
engineId = PsychPrefStateGet_VideoCaptureEngine();
PsychCopyInIntegerArg(9, FALSE, &engineId);
if (engineId < 0 || engineId > 3) PsychErrorExitMsg(PsychError_user, "OpenVideoCapture called with invalid 'captureEngineType'. Valid are 0,1,2,3.");
if (engineId == 2) {
printf("\n\n");
printf("PTB-INFO: Your script explicitely requests use of video capture engine type 2 - the ARVideo video capture engine.\n");
printf("PTB-INFO: This engine has been permanently disabled and removed from Psychtoolbox since beginning of the year 2011.\n");
printf("PTB-INFO: We recommend use of the GStreamer video capture engine (engine type 3) as a technically superior replacement\n");
printf("PTB-INFO: on GNU-Linux and MS-Windows. For Mac OS/X for now we recommend use of the Quicktime engine (engine type 0)\n");
printf("PTB-INFO: as an interims solution. The Quicktime engine will be eventually replaced on OS/X by the GStreamer engine as well.\n");
printf("PTB-INFO: In most cases, the selected replacement should work without need for any further changes to your code.\n\n");
}
// Try to open the capture device and create & initialize a corresponding capture object.
// A MATLAB handle to the video capture object is returned upon successfull operation.
if (roiassigned) {
PsychOpenVideoCaptureDevice(engineId, windowRecord, deviceIndex, &capturehandle, roirectangle, reqdepth, num_dmabuffers, allow_lowperf_fallback, moviename, recordingflags);
}
else {
PsychOpenVideoCaptureDevice(engineId, windowRecord, deviceIndex, &capturehandle, NULL, reqdepth, num_dmabuffers, allow_lowperf_fallback, moviename, recordingflags);
}
// Upon sucessfull completion, we'll have a valid handle in 'capturehandle'. Return it to Matlab-world:
PsychCopyOutDoubleArg(1, TRUE, (double) capturehandle);
// Ready!
return(PsychError_none);
}
