psychtoolbox-3-common 3.0.11.20140816.dfsg1-1 / usr / share / psychtoolbox-3 / PsychGLImageProcessing / PsychVideoSwitcher.m

function varargout = PsychVideoSwitcher(cmd, varargin)
% PsychVideoSwitcher(command [,arg1, arg2, .....]);
%
% Psychtoolbox support for the Xiangrui Li et al. "VideoSwitcher" video
% attenuator device for high precision luminance output with up to 16 bits
% luminance resolution.
%
% This routine incorporates code contributed by Xiangru Li for switching
% between monochrome and color display mode and for performing the
% reference Matlab routines for image formatting.
%
% Options: 'command' is a command string, specifying a subcommand. The
% following subcommands are supported with the following options:
%
% Public functions:
%
%
% PsychVideoSwitcher('SwitchMode', screenIdx, enableLuminanceMode [, VideoSwitcherIsABox])
% - Switch programmatically between high precision luminance mode and
% standard RGB true color display mode. 'screenIdx' is the screen index of the
% for the display screen to switch.
%
% 'enableLuminanceMode' is meaningful only for card VideoSwitcher, which
% must be set to 0 to switch to RGB mode, and to 1 to switch to high
% precision luminance mode. For box version, the SwitchMode subfunction
% ignores the third input, and only toggles between two display modes,
% equivalent to pushing the switch button on the box.
%
% 'VideoSwitcherIsABox' is an optional argument: If set to 1, then perform
% switching procedure for an external (box) device. If set to zero, then
% perform procedure for an internal (PCI card) device. If argument is
% omitted, the proper default type is read from a configuration file stored
% in the path mypath = PsychtoolboxConfigDir('VideoSwitcher');
%
% If you create a file named 'VideoSwitcherIsABox' in that directory
% mypath, the switcher is assumed to be an external box. If you create a
% file named 'VideoSwitcherIsACard', the code assumes a PCI card based
% device. If no such files exist, the switcher is assumed to be a box.
%
% It is important for the code to know if the switcher is a box or a card,
% as the switching strategy is different.
%
%
% PsychVideoSwitcher('SetTrigger', win, triggerLine [, count=infinite]);
% - Set trigger line and options for VideoSwitcher connected to the display
% of onscreen window 'win'.
%
% 'triggerLine' defines the vertical (y) position of a trigger line to be
% drawn to the green channel of the final image, in order to trigger the
% trigger-circuit of the VideoSwitcher. If you set it to a negative value
% or to empty [], triggering will be disabled (This is the default).
%
% 'count' Optional: Number of redraw cycles (invocations of
% Screen('Flip')), that the triggerline should be drawn. If left out, the
% line will be drawn on each redraw until disabled. If set to some value,
% it will be drawn for 'count' number of redraws, then disabled.
%
% The trigger mechanism only works if the VideoSwitcher is set to high
% precision luminance display. It will emit a TTL pulse of 100 microseconds
% duration when the triggerline is drawn by your display. Only one TTL
% trigger pulse per video refresh is possible.
%
%
% PsychVideoSwitcher('SetBackgroundLuminanceHint', win, luminance);
% - Tell the driver the 'luminance' value of the background pixels of
% onscreen windows 'win'. The driver will use this hint to optimize
% conversion of background pixels. This allows for a quite significant
% speedup if your stimulus only covers a fraction of the display area and
% the remaining area is just a uniform luminance background. This is only
% functional if you use the driver that uses the calibration LUT, not the
% simple driver.
%
%
% RGBImage = PsychVideoSwitcher('MapLuminanceToRGB', lum, ratio [, trigger]);
% - Perform conversion of a luminance image into a RGBImage. This is a pure
% Matlab based implementation for graphics hardware that is not capable of
% supporting the imaging pipeline.
%
%  Inputs:
%     lum: luminance (MxN matrix with values from 0 to 1)
%     ratio: blue to red ratio of the video switcher
%     trigger: when non-zero, a trigger will be sent in current frame
%         trigger=1 or 'top', the first line of image
%         trigger=2 or 'auto',  the first line with non-zero image
%         trigger=3 or 'middle', the middle line of image
%     If you omit ratio, you should give it in this code
%  Output: RGB image (MxNx3 matrix with values from 0 to 255)
%
%
% RGBImage = PsychVideoSwitcher('MapLuminanceToRGBCalibrated', lum, ratio, lut [, trigger])
% - Perform conversion of a luminance image into a RGBImage. This is a pure
% Matlab based implementation for graphics hardware that is not capable of
% supporting the imaging pipeline.
%
%  Inputs:
%     lum: luminance (MxN matrix with values from 0 to 1)
%     ratio: blue to red ratio of the video switcher
%     lut: The 257 slots calibrated luminance table as described below.
%     trigger: when non-zero, a trigger will be sent in current frame
%         trigger=1 or 'top', the first line of image
%         trigger=2 or 'auto',  the first line with non-zero image
%         trigger=3 or 'middle', the middle line of image
%     If you omit ratio, you should give it in this code
%  Output: RGB image (MxNx3 matrix with values from 0 to 255)
% 
% Note: this runs slow when lum matrix is large. 200x200 can take 1 second.
%
% This uses the calibrated luminance table saved in calibratedlum.mat.
% For detail, check the paper http://lobes.usc.edu/Journals/JNM03.pdf
% 
% The steps to get the table:
%
%  1. Switch the video switcher to grayscale mode;
%
%  2. Set up the equipement to accurately measure screen luminance;
%     you can use a photometer or data acquisition system;
%
%  3. Measure 257 luminance levels at RGB of [0 0 b] and [btrr 0 255],
%     where b is 0:255, and btrr the blue to red ratio of switcher; 
%
%  4. Store 257 luminance in a variable callum and normalize them:
%     callum=callum/callum(257);
%
%  5. Save it to a configuration file. See the help for subfunction
%     'GetDefaultConfig' below for how and where to store the calibration
%     table.
%
%
% [btrr, lut] = PsychVideoSwitcher('GetDefaultConfig', win);
% - Get default 'btrr' parameter and 'lut' lookup table from configuration
% files and return them. This function can be used by you to get switcher
% parameters for use with the Matlab conversion functions above. It will be
% automatically used by the imaging pipeline (by PsychImaging() command) if
% you select VideoSwitcher as an output device but don't provide explicit
% settings for 'btrr' and/or 'lut'.
%
% Configuration files for the VideoSwitcher should be stored in the folder
% whose path you get if you type mypath = PsychtoolboxConfigDir('VideoSwitcher');
%
% You can store a configuration file specific to a display screen
% 'screenid' (with the numbering as in Screen('Screens')). The file should
% have the name SettingsforScreen_X.mat with X being the screen number,
% e.g., SettingsforScreen_0.mat . This allows you to store per-display
% device settings. Alternatively you can store settings in a "global"
% config file named GlobalSettings.mat if they are not specific to the
% display. The stored mat file should contain up to two variables:
%
% The variable 'btrr' should store the measured/calibrated BTRR
% Blue-To-Red-Ratio for yor switcher and display setup. This variable is
% mandatory.
%
% The optional variable 'lut' would be a 257 elements double vector of
% luminance calibration data, as described in the help text immediately
% above the help for this subfunction (== help for
% 'MapLuminanceToRGBCalibrated').
%
% You would create such a file by typing, e.g.:
% btrr = 128;
% lut = the lookup table vector created by calibration...
% save 'GlobalSettings.mat' btrr lut
%
%
%
%
% Internal helper functions for Psychtoolbox - Must not be called from
% normal user code!!
%
% luttexid = PsychVideoSwitcher('GetLUTTexture', win, lut, btrr, shader);
% - Convert blue-to-luminance calibration lookup table 'lut' into a lookup
% table texture for the imaging pipeline, set it up and return a texture
% handle 'luttexid' to it. 'btrr' is the required BTRR value. 'shader' is
% the GLSL shader handle of the output formatting shader used.
%
%
% PsychVideoSwitcher(win);
% - If 'win' is a numeric onscreen window handle, perform all operations to
% implement the green channel trigger functionality for onscreen window
% 'win'. This routine uses MOGL glXXX() functions to implement drawing of
% proper trigger pixel values to the green channel for trigger creation.
%

% History:
% 05/25/08 mk  Initial incomplete implementation. Incorporates code from
%              Xiangrui Li in helper subroutines.
% 05/24/11 xl  3rd input for SwitchMode is not manditory since it is not
%              used by box version.
% 07/17/13 xl  Clarify in help text that SwitchMode only toggles between
%              two display modes.  

% GL access is needed for setup of green trigger channel in callback:
global GL;

% Cell array of trigger settings per window:
persistent triggerForWindow;

% Cell array with cached btrr and lut for window handle:
persistent cachedStuffForWindow;

% Cache info if videoswitcher is of external box type or PCI card type:
persistent VideoSwitcherIsABox;

% Subfunction dispatch:
if nargin < 1
    error('You must provide a command string!');
end

if isscalar(cmd) && isnumeric(cmd)
    % Special callback from within PTB imaging pipeline:
    if isempty(triggerForWindow) || isempty(triggerForWindow{cmd})
        % Invalid window handle or trigger disabled: Just skip.
        return;
    end

    % Extract triggerLine for this window:
    triggerSpec = triggerForWindow{cmd};
    triggerLine = triggerSpec.triggerline;

    % Trigger disabled or trigger drawn for wanted 'count' number of
    % redraws?
    if triggerLine < 0 || triggerSpec.count == 0
        % Yes. Just return.
        return;
    end
    
    % Decrement count:
    triggerSpec.count = triggerSpec.count - 1;
    triggerForWindow{cmd} = triggerSpec;
    
    % Due to a bug (or misfeature?) in imaging pipeline, we have unit 1
    % active here. Need to disable it:
    % FIXME: Fix the pipeline in next beta release cycle!
    % MK: Fixed in source code, but all Screen mex files need recompile!
    glPushAttrib(GL.ENABLE_BIT);

    glActiveTexture(GL.TEXTURE1);
    glDisable(GL.TEXTURE_RECTANGLE_ARB);
    
    % This one for unit 0 is always needed, because unit 0 is enabled by
    % design of the pipeline, not due to a bug:
    glActiveTexture(GL.TEXTURE0);
    glDisable(GL.TEXTURE_RECTANGLE_ARB);
    
    % Disable all channels for writing except green channel:
    glColorMask(GL.FALSE, GL.TRUE, GL.FALSE, GL.FALSE);
    glColor4f(0, 1, 0, 0);

    % Draw horizontal line 'triggerLine' into green channel of bound
    % framebuffer: We actually draw a stripe of 10 lines width, just to make
    % sure the VideoSwitcher picks it up, regardless of resolution.
    glBegin(GL.QUADS);
    glVertex2i(0, triggerLine);
    glVertex2i(10000, triggerLine);
    glVertex2i(10000, triggerLine+10);
    glVertex2i(0, triggerLine+10);    
    glEnd();
    
    % Reenable all channels for writing:
    glColorMask(GL.TRUE, GL.TRUE, GL.TRUE, GL.TRUE);
    glPopAttrib;
    
    % Done. Return to calling routine:
    return;
end

if ~ischar(cmd)
    error('Subcommand must be a string!');
end

if strcmpi(cmd, 'MapLuminanceToRGB')
    % Call lum2rgb() function to use simple conversion of luminance image
    % to RGB image:
    varargout{1} = lum2rgb(varargin{:});
    
    return;
end

if strcmpi(cmd, 'MapLuminanceToRGBCalibrated')
    % Call lum2rgb() function to use lut based conversion of luminance image
    % to RGB image:
    varargout{1} = lum2calrgb(varargin{:});
    
    return;
end

if strcmpi(cmd, 'SwitchMode')
    % Switch VideoSwitcher between monochrome and color mode by sending a
    % sequence of frames with special green-channel control codes:
    if nargin < 2
        error('screenId is missing!');
    end
    
    screenid = varargin{1};
    if ~ismember(screenid, Screen('Screens'))
        error('Invalid screenId provided - No such display screen!');
    end

    if nargin < 3 || isempty(varargin{2})
        enableLuminanceMode = 0; % XL: for box, this is not used
    else
        enableLuminanceMode = varargin{2};
    end
    
    if isempty(enableLuminanceMode) || ~isscalar(enableLuminanceMode) || ~isnumeric(enableLuminanceMode) || ~ismember(enableLuminanceMode, [0,1])
        error('Invalid enableLuminanceMode flag provided. Must be 0 or 1!');
    end

    if nargin < 4
        % No type parameter provided:
        if isempty(VideoSwitcherIsABox)
            % Check if type is stored in config file:
            lpath = sprintf('%sVideoSwitcherIsABox', PsychtoolboxConfigDir('VideoSwitcher'));
            if exist(lpath, 'file')
                VideoSwitcherIsABox = 1;
            else
                lpath = sprintf('%sVideoSwitcherIsACard', PsychtoolboxConfigDir('VideoSwitcher'));
                if exist(lpath, 'file')
                    VideoSwitcherIsABox = 0;
                else
                    fprintf('PsychVideoSwitcher: Could not find out if VideoSwitcher is a box or a PCI card. Just assuming it is a box...\n');
                    VideoSwitcherIsABox = 1;
                end
            end
        end
    else
        VideoSwitcherIsABox = varargin{3};
        if isempty(VideoSwitcherIsABox) || ~isscalar(VideoSwitcherIsABox) || ~isnumeric(VideoSwitcherIsABox) || ~ismember(VideoSwitcherIsABox, [0,1])
            error('Invalid VideoSwitcherIsABox flag provided. Must be 0 or 1!');
        end
    end
    
    % Enumerate all onscreen windows for screen 'screenid':
    allWindows = Screen('Windows');
    allWindowKinds = Screen('WindowKind', allWindows);
    onscreenWins = allWindows(allWindowKinds == 1);
    for win = onscreenWins
        % Is 'win' an onscreen window on screen screenid?
        if Screen('WindowScreenNumber', win) == screenid
            % This 'win'dow is an onscreen window on our target screenid.
            % Close it -- We don't want any onscreen windows on the screen
            % to switch, as they could clash/interfere with the switching
            % operation. Recycling them is impossible as we don't know
            % their configuration wrt. imaging mode, size etc.:
            Screen('Close', win);
        end
    end
    
    % Ok, our target screen 'screenid' is clear of any onscreen windows.
    % Create our own one: Fullscreen, black background clear color, no
    % imaging pipe or anything else, double-buffered. Disable all
    % sync-tests, warnings etc. for this switch action:
    oldverbosity = Screen('Preference', 'Verbosity', 1);
    oldsynclevel = Screen('Preference', 'SkipSyncTests', 2);
    oldvisuallevel = Screen('Preference', 'VisualDebugLevel', 0);
    win = Screen('OpenWindow', screenid, 0, []);
    
    % Hide mouse cursor:
    HideCursor;
    
    % Get current display size:
    [width, height]=Screen('WindowSize', win);

    % Get video refresh duration: We query nominal framerate, as this is faster
    % and sufficient for our purpose:
    ifi=Screen('NominalFramerate', win);
    if ifi == 0
        % Special case: Invalid framerate -- This usually means 60 Hz:
        ifi = 1/60;
    else
        % ifi is 1/Hz:
        ifi = 1/ifi;
    end

    if VideoSwitcherIsABox
        % Perform switching procedure for external box based VideoSwitcher:
        switchColorBox(win, width, height, ifi, enableLuminanceMode);
    else
        % Perform switching procedure for internal PCI based VideoSwitcher:
        switchColorCard(win, width, height, ifi, enableLuminanceMode);
    end
    
    % Show mouse cursor again:
    ShowCursor;

    % Close our window:
    Screen('Close', win);
    
    % Restore old settings:
    Screen('Preference', 'Verbosity', oldverbosity);
    Screen('Preference', 'SkipSyncTests', oldsynclevel);
    Screen('Preference', 'VisualDebugLevel', oldvisuallevel);
    
    return;
end

if strcmpi(cmd, 'SetTrigger')
    % Define the trigger line for a specific onscreen window:
    
    if nargin < 3
        error('You must provide the windowhandle and triggerline to the "SetTrigger" subfunction.');
    end
    
    win = varargin{1};
    if ~isscalar(win) || ~isnumeric(win) || Screen('WindowKind', win)~=1
        error('The "window" argument must be a scalar windowhandle of an onscreen window for the "SetTrigger" subfunction.');
    end

    triggerline = varargin{2};
    
    % Empty triggerline == Disable trigger:
    if isempty(triggerline)
        triggerForWindow{win} = [];
    else
        if ~isscalar(triggerline) || ~isnumeric(triggerline)
            error('The "triggerLine" argument must be a scalar numeric value for the "SetTrigger" subfunction.');
        end

        % Store this setting in our cell array:
        triggerSpec.triggerline = triggerline;
        
        % Optional count provided?
        if nargin < 4 || isempty(varargin{3})
            % Nope: Set to infinite count:
            triggerSpec.count = -1;
        else
            % Yes: Set it.
            triggerSpec.count = varargin{3};
        end
                
        triggerForWindow{win} = triggerSpec;
    end
    
    return;
end

if strcmpi(cmd, 'GetDefaultConfig')
    % Retrieve default configuration for a specific onscreen window:
    
    if nargin < 2
        screenid = 0;
    else
        % Retrieve window handle for the already opened onscreen window on
        % which VideoSwitcher is supposed to be operating:
        win = varargin{1};
        if ~isscalar(win) || ~isnumeric(win)
            error('The "window" argument must be a scalar windowhandle of an onscreen window or a scalar screenid for the "GetDefaultConfig" subfunction.');
        end

        % Screenid or windowhandle?
        if ismember(win, Screen('Screens'))
            % Screenid - Assign:
            screenid = win;
        else
            % Either windowhandle or error:
            if Screen('WindowKind', win)~=1
                error('The "window" argument must be a scalar windowhandle of an onscreen window or a scalar screenid for the "GetDefaultConfig" subfunction.');
            end

            % The 'win'dowhandle by itself is meaningless. We map the windowhandle
            % to its associated screenid and then lookup proper configuration files
            % for that screen:
            screenid = Screen('WindowScreenNumber', win);
        end
    end
    
    % First check for a per-screen file:
    lpath = sprintf('%sSettingsforScreen_%i.mat', PsychtoolboxConfigDir('VideoSwitcher'), screenid);
    if exist(lpath, 'file')
        % Per screen file: Load it.
        switcherconfig = load(lpath);
    else
        % No such per screen file. Try global default file:
        lpath = sprintf('%sGlobalSettings.mat', PsychtoolboxConfigDir('VideoSwitcher'));
        if exist(lpath, 'file')
            % Load global file:
            switcherconfig = load(lpath);
        else
            % No files at all. Setup a default config:
            switcherconfig.btrr = 128;
            switcherconfig.lut = linspace(0, 1, 257);
            fprintf('\nPsychVideoSwitcher: Warning: No meaningful configuration for VideoSwitcher available in configuration directory:\n%s\nUsing fake default settings: BTRR=128 and a linear 257 slot lut...\n\n', PsychtoolboxConfigDir('VideoSwitcher'));
            lpath = [];
        end
    end
    
    if ~isempty(lpath)
        fprintf('PsychVideoSwitcher: Info: Configuration for VideoSwitcher loaded from default config file:\n%s\n', lpath);
    end
    
    % Return BTRR setting:
    varargout{1} = switcherconfig.btrr;
    
    % Return Blue channel to luminance calibration lut, if any:
    if isfield(switcherconfig, 'lut')
        varargout{2} = switcherconfig.lut;
    else
        varargout{2} = [];
    end
    
    return;
end

if strcmpi(cmd, 'GetLUTTexture')
    if nargin < 4
        error('You must provide the window handle, lut lookup table and btrr to the "GetLUTTexture" subfunction.');
    end
    
    win = varargin{1};
    if ~isscalar(win) || ~isnumeric(win) || Screen('WindowKind', win)~=1
        error('The "window" argument must be a scalar windowhandle of an onscreen window or a scalar screenid for the "GetLUTTexture" subfunction.');
    end
    
    lut = varargin{2};
    
    if isempty(lut)
        error('You must provide the lut lookup table as 2nd argument to the "GetLUTTexture" subfunction.');
    end
    
    if ~isvector(lut)
        error('lut must be a vector!');
    end

    if size(lut, 1) ~=1
        lut = transpose(lut);
    end
    
    [channels, nslots] = size(lut);

    if channels~=1
        error('lut must be a vector!');
    end
    
    if nslots~=257
        error('lut must have 257 slots, aka columns!');
    end

    if ~isa(lut,'double')
        error('lut must by of double precision type!');
    end

    btrr = varargin{3};
    if isempty(btrr) || ~isscalar(btrr) || ~isa(btrr,'double')
        error('You must provide a valid scalar double btrr value as 3rd argument!');
    end
    
    if nargin < 5
        shader = 0;
    else
        shader = varargin{4};
        if isempty(shader)
            shader = 0;
        end
    end
    
    
    % mylut is the input lut: Row 1=Red, 2=Green, 3=Blue, 4=Alpha
    % component of a texel, 257 texels for the 257 texel wide, 1 row high
    % RGBA float texture:
    mylut = zeros(4, 257);
    
    % Fill with normalized lut:
    lut = lut / lut(257);
    
    % Hmm, a dirty trick, indeed: We shift the maximum value by a very
    % small epsilon to avoid a boundary artifact - a wrong conversion for a
    % input luminance value of exactly 1.0:
    lut(257) = lut(257) + 1e-7;
    
    % Red channel (channel 1) contains lut values, aka minimum luminance
    % values for each corresponding blue channel driver value:
    mylut(1,:) = lut;
    
    % Green channel (channel 2) contains the upper bound, ie. the channel 1
    % value of the preceding slot:
    mylut(2,1:256) = lut(2:257);

    % The upper limit of slot 257 is not defined. Set it to a value higher
    % than the minimum of slot 257:
    mylut(2,257) = lut(257);
    
    mylut(3,1:256) = repmat(btrr, 1, 256) ./ ( mylut(2,1:256) - mylut(1,1:256) );
    % This is not well-defined at all: Just set it to a high value and hope
    % for the best... As luminance values are clamped to a maximum of 1.0,
    % thi...
    mylut(3,257) = 1e10;
    
    % Build texture:
    luttex = glGenTextures(1);
    glBindTexture(GL.TEXTURE_RECTANGLE_EXT, luttex);
    glTexImage2D(GL.TEXTURE_RECTANGLE_EXT, 0, GL.RGBA_FLOAT32_APPLE, 257, 1, 0, GL.RGBA, GL.FLOAT, moglsingle(mylut));

    % Make sure we use nearest neighbour sampling:
    glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_MIN_FILTER, GL.NEAREST);
    glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_MAG_FILTER, GL.NEAREST);

    % And that we clamp to edge:
    glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_WRAP_S, GL.CLAMP);
    glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_WRAP_T, GL.CLAMP);

    glBindTexture(GL.TEXTURE_RECTANGLE_EXT, 0);

    % Return texture handle:
    varargout{1} = luttex;

    % We store an internal backup copy of used input lut and btrr for this
    % window handle:
    wincache.btrr = btrr;
    wincache.lut = lut;
    wincache.shader = shader;
    cachedStuffForWindow{win} = wincache;
    
    return;
end

if strcmpi(cmd, 'SetBackgroundLuminanceHint')
    if nargin < 3
        error('You must provide the window handle and luminance hint value to the "SetBackgroundLuminanceHint" subfunction.');
    end
    
    win = varargin{1};
    if ~isscalar(win) || ~isnumeric(win) || Screen('WindowKind', win)~=1
        error('The "window" argument must be a scalar windowhandle of an onscreen window or a scalar screenid for the "SetBackgroundLuminanceHint" subfunction.');
    end
    
    lum = varargin{2};
    if ~isscalar(lum) || ~isnumeric(lum)
        error('The "backgroundLuminance" argument must be a scalar luminance value in range [0 ; 1] for the "SetBackgroundLuminanceHint" subfunction.');
    end
    
    % Ok, we have luminance value and window handle. Do we have relevant
    % cached info for this windowhandle?
    if isempty(cachedStuffForWindow) || isempty(cachedStuffForWindow{win})
        fprintf('PsychVideoSwitcher(''SetBackgroundLuminanceHint''): I do not have neccessary internal information for this onscreen window!\n');
        fprintf('Call PsychImaging(''OpenWindow'',...) first! This also has no function if you don''t use the calibrated VideoSwitcher driver.\n');
    end
    
    % Extract info:
    wincache = cachedStuffForWindow{win};
    
    % Only do this if the LUT based converter is used:
    if wincache.shader ~= 0
        % Map luminance value to color values via Matlab based conversion
        % routines:
        RGBPixel = lum2calrgb(lum, wincache.btrr, wincache.lut, 0);

        % Store (R,B) values in 0-1 range in red and blue channels, the
        % luminance "key" value in the green channel:
        redv = double(RGBPixel(1,1,1))/255;
        greenv = lum;
        bluev = double(RGBPixel(1,1,3))/255;

        % Find GLSL shader handle for VideoSwitcher shader:

        % Set values in shader:
        glUseProgram(wincache.shader);
        glUniform3f(glGetUniformLocation(wincache.shader, 'BackgroundPixel'), redv, greenv, bluev);
        glUseProgram(0);
    end
    
    % Done.
    return;
end

% Unknown command string - No match to any of the routines above:
error('Unknown subcommand provided!');

return; %#ok<UNRCH>

% Helper functions:
%
% Convert luminance matrix into RGB image to drive a video switcher.
%
% Usage: RGBimage = lum2rgb (lum, ratio [, trigger])
%  Inputs:
%     lum: luminance (MxN matrix with values from 0 to 1)
%     ratio: blue to red ratio of the video switcher
%     trigger: when non-zero, a trigger will be sent in current frame
%         trigger=1 or 'auto', the first line of image
%         trigger=2 or 'top',  the first line with non-zero image
%         trigger=3 or 'middle', the middle line of image
%     If you omit ratio, you should give it in this code
%  Output: RGB image (MxNx3 matrix with values from 0 to 255)
% XL, 01/03/2008
function img = lum2rgb (lum, ratio, trigger)
if nargin<3 || isempty(trigger), trigger=0; end
if nargin<2 || isempty(ratio), ratio=128; end
if nargin<1, disp('Usage: RGBimage = lum2rgb (lum, ratio [, trigger])'); return; end

sz=size(lum);
img = uint8(zeros(sz(1),sz(2),3));   % preallocate memory
lum=lum*255;	% now 0 to 255
img(:,:,3) = uint8(min(255,floor((ratio+1)/ratio*lum)));       % first calculates BLUE
img(:,:,1) = uint8((ratio+1)*lum-double(img(:,:,3))*ratio);	% then remainder is achieved by RED

if trigger==0, return; end

switch trigger
    case {2, 'top'}
        line = 1;    % first line of the image
    case {3, 'middle'}
        line = round(sz(1)/2);    % middle of image
    otherwise
        line = ceil(find(lum',1,'first')/sz(2));    % the first line where lum is non-zero
end
img(line,:,2) = uint8(255);         % set green to 255. Will send trigger when displayed
return;

% Convert luminance matrix into RGB image to drive a video switcher.
% This uses the calibrated luminance table saved in calibratedlum.mat.
% For detail, check the paper http://lobes.usc.edu/Journals/JNM03.pdf
% 
% The steps to get the table:
%  1. Switch the video switcher to grayscale mode;
%  2. Set up the equipement to accurately measure screen luminance;
%     you can use a photometer or data acquisition system;
%  3. Measure 257 luminance levels at RGB of [0 0 b] and [btrr 0 255],
%     where b is 0:255, and btrr the blue to red ratio of switcher; 
%  4. Store 257 luminance in variable callum and normalize them:
%     callum=callum/callum(257);
%  5. Save it under a proper folder with Matlab path: 
%     save calibratedlum callum;
% 
% Usage: RGBimage = lum2calrgb (lum, ratio [, trigger])
%  Inputs:
%     lum: luminance (MxN matrix with values from 0 to 1)
%     ratio: blue to red ratio of the video switcher
%     trigger: when non-zero, a trigger will be sent in current frame
%         trigger=1 or 'auto', the first line of image
%         trigger=2 or 'top',  the first line with non-zero image
%         trigger=3 or 'middle', the middle line of image
%     If you omit ratio, you should give it in this code
%  Output: RGB image (MxNx3 matrix with values from 0 to 255)
% 
% Note: this runs slow when lum matrix is large. 200x200 can take 1 second.
% XL, 01/08/2008
function img = lum2calrgb (lum, ratio, callum, trigger)
if nargin<4 || isempty(trigger), trigger=0; end
if nargin<3, disp('Usage: RGBimage = lum2calrgb (lum, ratio, lut [, trigger])'); return; end

if length(callum)~=257
    error('Calibrated luminance table must have 257 entries.');
end

sz=size(lum);
blue=ones(sz)*255;
for i=1:256
    ind=find(lum>=callum(i) & lum<callum(i+1));
    blue(ind)=i-1; %#ok<FNDSB>
end
img=zeros(sz(1),sz(2),3);   % preallocate memory
img(:,:,3)=blue;
img(:,:,1)=(lum-callum(blue+1))./(callum(blue+2)-callum(blue+1))*ratio;  % red
img=uint8(img);

if trigger==0, return; end
switch trigger
    case {2, 'top'}
        line = 1;    % first line of the image
    case {3, 'middle'}
        line = round(sz(1)/2);    % middle of image
    otherwise
        line = ceil(find(lum',1,'first')/sz(2));    % the first line where lum is non-zero
end
img(line,:,2) = uint8(255);         % set green to 255. Will send trigger when displayed

return;

% Switch between normal color mode and high grayscale mode of a box video switcher. 
% Usage for box switcher:
%  switchColor(windowOrScreenNumber) to switch back and forth between two modes.
% Call it to switch to grayscale mode after you open a window, and 
% call it again to switch back to normal color mode after you finish display.
% XL, 01/08/2008
function switchColorBox(w, width, height, ifi, enableLuminanceMode) %#ok<INUSD>

% Doesn't help doesn't hurt either:
Screen('FillRect',w,0);

ppb=1/ifi*width*height/4e6; % pixels per bit based on 4 MHz detection frequency

% these 2 signals will make a switch
bits=[1 1 1 0 0 1 0 1 0 1 0 1 1 1 1 0 0 0 1 1 0 1 1 0 1; ... 
      1 1 0 1 1 0 1 1 1 0 1 1 0 1 1 0 1 0 1 0 1 1 0 0 1]; 

% factor means the percent of time to display pixels within a frame.
% Here we use a large range of factor so it will work for different settings.
range=[0.6 0.85];   % you can narrow the range at specific monitor setting
step=0.2/ppb; % in case of switch failure, reduce 0.2 to about 0.15
pixelPos=round((0:25)*ppb/range(1));
img1=zeros(1, pixelPos(26), 3); % one line image, will change green layer
img2=img1;
for i=1:25
    img1(1, pixelPos(i)+1:pixelPos(i+1), 2)=bits(1,i)*255;
    img2(1, pixelPos(i)+1:pixelPos(i+1), 2)=bits(2,i)*255;
end
tex(1)=Screen('MakeTexture',w,uint8(img1));
tex(2)=Screen('MakeTexture',w,uint8(img2));

for i=1:2
    for factor=(range(1):step:range(2))/range(1)
        rd=rand*ppb*0.5; % random shift up to half a bit
        Screen('DrawTexture',w, tex(i),[],[rd 0 pixelPos(26)/factor+rd 1]); 
        Screen('Flip',w);
    end
end

% Release textures:
Screen('Close', tex);

return;

% Switch between normal color mode and high grayscale mode of a card video switcher. 
% Usage: switchColorCard [(color,windowOrScreenNumber)]
%   Optional inputs: 
%     color: 0, 'BW' or 'gray' to switch to high grayscale monochrome mode, 
%        otherwise (or omit) to switch to color mode.
%     windowOrScreenNumber: windowPtr or screen number. Default is current onscreen.
% XL, 11/2007

function switchColorCard(w, width, height, ifi, enableLuminanceMode)

Screen('FillRect',w,0);

ppb=1/ifi*width*height/4e6; % pixels per bit based on 4 MHz detection frequency

% 1st row to gray, 2nd color
bits=[1 1 1 0 0 1 0 1 0 1 0 1 1 1 1 0 0 0 1 1 0 1 1 0 1; ... 
      1 1 0 1 1 0 1 1 1 0 1 1 0 1 1 0 1 0 1 0 1 1 0 0 1]; 

if enableLuminanceMode==1
    % Switch to monochrome mode:
    color=1;
else
    % Switch to RGB mode:
    color=2;
end

% factor means the percent of time to display pixels within a frame.
% Here we use a large range of factor so it will work for different settings.
range=[0.6 0.85];   % you can narrow the range at specific monitor setting
step=0.2/ppb; % in case of switch failure, reduce 0.2 to about 0.15
pixelPos=round((0:25)*ppb/range(1));
img=zeros(1, pixelPos(26), 3); % one line image, will change green layer
for i=1:25
    img(1, pixelPos(i)+1:pixelPos(i+1), 2)=bits(color,i)*255;
end
tex=Screen('MakeTexture',w,uint8(img));

for factor=(range(1):step:range(2))/range(1)
    rd=rand*ppb*0.5; % random shift up to half a bit
    Screen('DrawTexture',w,tex,[],[rd 0 rd+pixelPos(26)/factor 1]);
    Screen('Flip',w); 
end

% MK: Release textures:
Screen('Close', tex);

return;