~ubuntu-branches/ubuntu/trusty/psychtoolbox-3/trusty-proposed

function PsychPortAudioTimingTest(exactstart, deviceid, latbias, waitframes, useDPixx, triggerLevel)

% PsychPortAudioTimingTest([exactstart=1][, deviceid=-1][, latbias=0][, waitframes=1][, useDPixx=0][, triggerLevel=0.01])

% Some parameters may need tweaking. Make sure you got a setup as described

% in 'help InitializePsychSound' for best results.

% 'triggerLevel' = Sound signal amplitude for DataPixx to detect sound

%                  onset. Defaults to 0.01 = 1% of max amplitude if

%                  exactstart == 0, otherwise it is auto-detected by

%                  calibration. This will likely need tweaking on your

%                  setup. If the measured audio onset delta by DataPixx is

%                  much lower (or almost zero) than the expected delta

%                  reported by PsychPortAudio, then the triggerLevel may be

%                  too low and you should try if slightly higher thresholds

%                  help to discriminate signal from noise. Too high values

%                  may cause a hang of the script. In practice, levels

%                  between 0.01 and 0.1 should yield good results. Setting

%                  the 'useDPixx' flag to 2 also plots the waveforms

%                  captured by DataPixx, which may help in selection of the

%                  optimal triggerLevel.

%

reqlatencyclass = 2;

    % Hack to accomodate bad Windows systems or sound cards. By default,

    % the more aggressive default setting of something like 5 msecs can

    % cause sound artifacts on cheaper / less pro sound cards:

    suggestedLatencySecs = 0.015 %#ok<NOPRT>

    fprintf('Choosing a high suggestedLatencySecs setting of 15 msecs to account for shoddy Windows operating system.\n');

    fprintf('For low-latency applications, you may want to tweak this to lower values if your system works better than average timing-wise.\n');

 

if nargin < 6

    % Default triggerLevel is "auto-trigger":

    triggerLevel = [];

end

 

% Generate some beep sound 1000 Hz, 0.1 secs, 50% amplitude:

    if ~(exactstart && isempty(triggerLevel))

        if isempty(triggerLevel)

            % Choose a default of 1% of max. signal amplitude:

            triggerLevel = 0.01;

        end

        fprintf('Using a trigger level for DataPixx of %f. This may need tweaking by you...\n', triggerLevel);

        DatapixxAudioKey('TriggerLevel', triggerLevel);

    end

    

    % DataPixx: Setup Screen imagingpipeline to support measurement via the PSYNC

    % video synchronization mode of DataPixx and Screen():

 

% Set waitframes to a good default, if none is provided by user:

if isempty(waitframes)

    % We try to choose a waitframes that maximizes the chance of hitting

    % the onset deadline. We are conservative in our estimate, because a

    % few video refresh cycles hardly matter for this test, but increase

    % our chance of success without need for manual tuning by user:

    if isempty(suggestedLatencySecs)

        % Let's assume 12 msecs on Linux and OSX as a achievable latency by

        % default, then double it:

        waitframes = ceil((2 * 0.012) / ifi) + 1;        

    else

        % Whatever was provided, then double it:

        waitframes = ceil((2 * suggestedLatencySecs) / ifi) + 1;

    end

end

 

fprintf('\n\nWaiting %i video refresh cycles before white-flash.\n', waitframes);

 

% Auto-Selection of triggerLevel for Datapixx timestamping requested?

if useDPixx && exactstart && isempty(triggerLevel)

    % Use auto-trigger mode. Tell the function how long the silence

    % interval at start of each trial is expected to be. This will be

    % used for calibration: We set it to 75% of the duration of the pause

    % between start of Datapixx recording and scheduled sound onset time:

    DatapixxAudioKey('AutoTriggerLevel', ifi * waitframes * 0.75);

    fprintf('Setting lead time of silence in Datapixx auto-trigger mode to %f msecs.\n', ifi * waitframes * 0.75 * 1000);

end

 

% Perform one warmup trial, to get the sound hardware fully up and running,

% performing whatever lazy initialization only happens at real first use.

% This "useless" warmup will allow for lower latency for start of playback

% during actual use of the audio driver in the real trials:

PsychPortAudio('Start', pahandle, 1, 0, 1);

PsychPortAudio('Stop', pahandle, 1);

 

% Ok, now the audio hardware is fully initialized and our driver is on

% hot-standby, ready to start playback of any sound with minimal latency.

 

KbStrokeWait;

% Realtime scheduling: Can be used if otherwise timing is not good enough.

    % This flip clears the display to black and returns timestamp of black onset:

    % It also triggers start of audio recording by the DataPixx, if it is

    % used, so the DataPixx gets some lead-time before actual audio onset.

        % Schedule start of audio at exactly the predicted visual stimulus

        % onset caused by the next flip command.

        PsychPortAudio('Start', pahandle, 1, visonset1 + waitframes * ifi, 0);

        PsychPortAudio('Start', pahandle, 1, 0, 0);

        % 'visonset1' is the GetSecs() time of start of capture on

        % DataPixx. 'audio_onset' is reported GetSecs() audio onset time

        % according to PsychPortAudio.

    % Wait a bit...