function [win, winRect] = BitsPlusPlus(cmd, arg, dummy, varargin)
% BitsPlusPlus(cmd [, arg1][, arg2, ...]) -- Psychtoolbox interface to
% Cambridge Research Systems Bits++ and Bits# boxes for high precision
% stimulus output to analog displays via 14 bit video converters.
%
% This function is used to set up and interface with the Bits++ / Bits# box of
% CRS. It is a Matlab wrapper around lower level GLSL Psychtoolbox
% functions. This function depends on graphics hardware that supports the
% Psychtoolbox imaging pipeline and framebuffers with more than 14 bit
% precision, i.e., 16 bpc fixed point framebuffers or floating point
% framebuffers. Have a look at the Psychtoolbox Wiki where you can find a
% list of graphics cards with the neccessary features.
%
% This function supersedes the old Matlab based Bits++ Toolbox, which
% essentially provides the same functionality on any graphics card, but is
% harder to use, much slower and not fully integrated into PTB, ie, you
% can't take full advantage of PTB's advanced drawing and image processing
% functions when using the old Bits++ toolbox.
%
% See the help section about Bits# for advanced Bits# commands and how to
% establish communication and convenient control for the Bits# via USB
% connection.
%
% cmd - The command that BitsPlusPlus should execute. cmd can be any of
% the following:
%
%
% Load a linear identity mapping CLUT into Bits++ while running in Bits++
% mode:
%
% BitsPlusPlus('LoadIdentityClut', window);
%
% Will schedule update to an identity clut. Next invocation of
% Screen('Flip', window); will actually upload the identity clut into
% Bits++.
%
%
% BitsPlusPlus('UseFE1StereoGoggles', window, enable [, shutterState=0]);
% If 'enable' is 1, enable use of the CRS FE1 stereo goggles connected
% to the Bits display device. If 'enable' is 0 then disable use of the
% goggles again and put them in a resting state with either both shutters
% open ('shutterState = 0') or closed ('shutterState = 1').
%
%
% Schedule a Bits++ DIO command for execution on next Screen('Flip'):
%
% BitsPlusPlus('DIOCommand', window, repetitions, mask, data, command [, xpos, ypos]);
%
% This will draw the proper T-Lock control codes at positions (xpos, ypos)
% for execution of the Bits++ DIO commands (mask, data, command).
%
% You can specify multiple codes at once: If mask, data, command, xpos and
% ypos are matrices or vectors with 'num' rows, then each of the 'num' rows
% defines one T-Lock code. If mask, command, xpos and ypos are scalars and
% data is a one row vector, then only the corresponding T-Lock line is
% drawn.
%
% For each DIO command:
% 'mask' must be a 8 bit integer value, 'command' must be a 8 bit integer
% value, whereas 'data' must be a a 248 element row vector of bytes.
%
% Consult your Bits++ manual for explanation of the meaning of the values.
%
% xpos and ypos are optional: By default, the T-Lock code is drawn into the
% 3rd pixel row of the output image, so it can't collide with a potential
% T-Lock code for CLUT updates.
%
% The DIO command will become effective during the next flip command. The
% T-Lock code is drawn during 'repetitions' successive invocations of
% Screen('Flip'). If you set 'repetitions' to -1, then the code will be
% drawn until you stop it via a call to BitsPlusPlus('DIOCommandReset', window);
%
%
% Disable use of the DIO T-Lock code blitting:
%
% BitsPlusPlus('DIOCommandReset', window);
% Stops blitting of T-Lock command codes immediately. If you want to use
% them again, you have to respecify codes via the BitsPlusPlus('DIOCommand',...);
%
%
% Manage treatment of one or two connected CRS devices:
%
% BitsPlusPlus('SetDualDevices', mode);
% If 'mode' is set to 0, which is the default, assume one CRS device is connected.
%
% If 'mode' is set to 1, then assume two CRS devices, e.g., 2 Display++ or
% Bits# devices are connected for dual-display stereo/binocular stimulation and
% adapt accordingly. Apply the same CLUT in Bits++ and Mono++ display mode
% to both connected display devices in stereomodes 4, 5 and 10.
%
%
%
%
% Open a full-screen window on the Bits++ display as with
% Screen('OpenWindow', ...), perform all initialization:
%
% The following commands will execute Screen('OpenWindow') with all proper
% parameters, followed by Bits++ init routines. They are completely sufficient
% drop in replacements for Screen('OpenWindow'), accepting and returning
% exactly the same arguments that Screen() would do, adjusting all
% parameters to the constraints of the Bits++, if necessary.
%
% Activate Bits++ mode:
%
% [win, winRect] = BitsPlusPlus('OpenWindowBits++', screenid, ...);
%
% This will open an onscreen window on Bits++ screen 'screenid' with a
% standard 8 bits per color channel framebuffer. The gamma table of your
% graphics hardware will be loaded with an identity gamma table, so the
% T-Lock system of Bits++ works and Bits++ can accept commmands embedded
% into the stimulus images. Psychtoolbox will automatically embed a T-Lock
% control line into the top line of the display screen, which encodes the
% 256 entry, 14 bit per color channel CLUT to use for Bits++ display mode.
% You can change the Bits++ CLUT at any time via the standard PTB
% Screen('LoadNormalizedGammaTable', win, newclut, 2); command. The
% 'newclut' will get uploaded to the Bits++ at the next invocation of
% Screen('Flip') to allow updates of the CLUT synchronous to stimulus
% updates. 'newclut' has to be a 256 rows by 3 columns matrix with values
% in range 0.0 - 1.0: 0.0 is mapped to clut color value 0, 1.0 is mapped to
% the highest Bits++ output color value 16383.
%
% This mode works on any OpenGL graphics hardware.
%
%
% Activate Mono++ mode:
%
% [win, winRect] = BitsPlusPlus('OpenWindowMono++', screenid, ...);
%
% This will open an onscreen window on Bits++ screen 'screenid' for display
% of pure luminance (grayscale) images. The framebuffer has a resolution of
% 32 bit floating point precision by default: This means that pixel luminance
% values have to be specified as floating point numbers between 0.0 and
% 1.0. 0.0 maps to black (Output intensity 0 on Bits++ device). 1.0 maps to
% white (Maximum output intensity 16383 on Bits++ device). The intensity
% range between 0.0 and 1.0 is internally represented and processed by
% Psychtoolbox with a resolution 23 bits, i.e. over 8 million levels of
% luminance. The Bits++ can resolve this range to 14 bits, ie. 16384 levels
% of luminance during display. This mode is not compatible with the use of
% any gamma- or clut- tables. Both the graphics hardwares gamma table and
% the Bits++ internal clut are set to an identity mapping while this mode
% is active. Please read the notes below the Color++ section for graphics
% hardware requirements and other useful tips for use of Bits++.
%
% If you call this subfunction as 'OpenWindowMono++WithOverlay', the
% overlay plane of Bits++ gets enabled and an additional overlay window is
% created for drawing the image for that overlay plane.
%
% [overlaywin, overlaywinRect] = BitsPlusPlus('GetOverlayWindow', win);
% - Will return the handle to the 'overlaywin'dow associated with the
% onscreen luminance window:
%
% 'overlayWin' is the handle to the overlay window associated with the
% overlay of onscreen window 'win'. The overlay window is a standard
% offscreen window, so you can do anything with it that you would want to
% do with offscreen windows. The only difference is that the window is a
% pure index window: It only has one "color channel", which can be written
% with color values between 0 and 255. Values 1 to 255 get mapped to the
% corresponding color indices of the Bits++ overlay plane: A zero value is
% transparent -- Content of the onscreen window is visible. Positive
% non-zero color values map to the 255 indices available in overlay mode,
% these get mapped by the Bits++ CLUT to colors. You can define the
% mapping of indices to CLUT colors via the
% Screen('LoadNormalizedGammaTable', win, clut, 2); command.
%
% Updates of the overlay image are synchronized to Screen('Flip')
% updates. If you draw into the overlay window, the changed overlay image
% will become visible at Screen('Flip') time -- in sync with the changed
% onscreen window content. The overlay plane is not automatically cleared
% to background (or transparent) color after a flip, but its content
% persists across flips. You need to clear it out manually via a
% Screen('FillRect') command.
%
%
% Activate Color++ mode:
%
% [win, winRect] = BitsPlusPlus('OpenWindowColor++', screenid, ...);
%
% This will open an onscreen window on Bits++ screen 'screenid' for display
% of 14 bit per color component 42bpp color images. The framebuffer has
% a resolution of 32 bit floating point precision for each color component
% by default: This means that (Red, Green, Blue) color pixel component
% values have to be specified as floating point numbers between 0.0 and
% 1.0. 0.0 maps to minimum output intensity on Bits++ device for a channel.
% 1.0 maps to maximum output intensity 16383 on Bits++ device for a channel.
% The color intensity range between 0.0 and 1.0 is internally represented and
% processed by Psychtoolbox with an effective resolution of about 23 bits,
% i.e. over 8 million levels of color per color channel. The Bits++ can resolve
% this range to 14 bits, ie. 16384 levels of color during display. This mode
% is not compatible with the use of any gamma- or clut- tables. Both the graphics
% hardwares gamma table and the Bits++ internal clut are set to an identity
% mapping while this mode is active. Please read the notes below for graphics
% hardware requirements and other useful tips for use of Bits++.
%
%
% If you use Color++ mode, you must call
% BitsPlusPlus('SetColorConversionMode', mode); first to select the mode
% for sampling the framebuffer and converting into output color values. See
% the respective section of "help PsychImaging" for 'Color++' or
% 'EnableDataPixxC48Output' mode for the Bits+ or Datapixx device for an
% explanation of this mandatory parameter. The setting before 22nd
% September 2010 for all PTB-3 versions was 0 (==zero).
%
% You can query the mode for an onscreen window 'win' by a call to:
% mode = BitsPlusPlus('GetColorConversionMode', win);
%
%
% Notes for both Mono++ and Color++ mode:
%
% In Mono++ and Color++ mode, PTB expects color values in the range 0.0 to
% 1.0 instead of the (otherwise usual) range 0 to 255. The range 0.0-1.0
% is a more natural fit for high dynamic range/precision output devices than
% the 0-255 range with its strong ties to 8 bpc output devices. 0-1 is also
% the "natural" native color range of OpenGL, so colors in this range can
% be handled by the graphics hardware at a higher speed. You can change the
% mapping of input colors to output intensities by use of the command
% Screen('ColorRange') (see its online help for usage), but in the interest
% of uniform code and to avoid possible side effects with some graphics
% hardware, we strongly recommend using the default 0.0-1.0 color range.
%
% You can still pass standard 8bpc (256 color/intensity levels) color/luminance
% textures to PTB via standard use of Screen('MakeTexture') - the hardware
% will convert such 8bpc images to OpenGL's native color range, as well as
% any images delivered by the Quicktime movie playback engine or the video
% capture engine. If you want to provide high dynamic range, high color
% depths images, please specify them as Matlab double matrices to
% Screen('MakeTexture') and set the optional flag 'floatprecision' to 1 or
% 2, i.e., hdrtex = Screen('MakeTexture', win, myHDRImage, [], [], 2);
%
% Psychtoolbox will represent such images with an internal precision of 10
% bits + 1 bit sign if you choose the 'floatprecision' flag to be 1. If you
% choose a 'floatprecision' flag of 2, PTB will represent the images with
% an internal precision of 23 bits + 1 bit sign. You can provide negative
% color values as well, e.g., -0.5. If you wonder what the use of this
% might be, have a careful look at the tutorial script...
% 'AdditiveBlendingForLinearSuperpositionTutorial.m'
% ... for an example of extremely fast drawing of luminance gratings with
% controllable size, orientation and contrast and correct linear superposition:
%
% By default, PTB will use a 32-bit floating point framebuffer for your
% drawings, ie. the precision is way higher than needed for any high
% dynamic range/resolution display device in existence. The downside of this
% super-precision is that alpha-blending is not supported in this mode, unless
% you employ an NVidia Geforce 8000 series (and later) graphics card, or a
% ATI Radeon HD2000/3000 series graphics card (and later). If you need
% alpha-blending on older/other hardware then specify the optional flag
% 'kPsychNeed16BPCFloat' for the 'imagingmode' argument. This will reduce
% effective accuracy of the framebuffer to 10 bit precision, but allow for
% fast alpha-blending. 10 Bit precision are 4 bits less than the 14 bits
% that Bits++ can provide, but it will be possible to use the extra 14-10 =
% 4 bits for gamma correction of the display by employing a gamma
% correction shader.
%
% Gamma- and color correction:
%
% In Mono++ and Color++ mode, the hardware gamma tables of your graphics
% card and the Bits+ box can't be used for gamma- or color correction.
% However, PTB provides a much more powerful and flexible color correction
% system for this purpose. See "help PsychColorCorrection" for further
% explanation and usage examples for standard gamma correction.
%
% Graphics hardware requirements: Mono++ and Color++ mode require use of the
% Psychtoolbox imaging pipeline and floating point framebuffers. The
% minimum requirements are ATI Radeon X1000 series or NVidia Geforce-6800
% series and later graphics hardware. We currently recommend NVidia
% Geforce-8000 series or ATI Radeon HD-2000/3000 hardware for best results.
% However, this functions have been successfully tested on ATI Radeon X1600
% and NVidia Geforce-7800 hardware as well.
%
% All Bits++ modes supported by this function should work Plug & Play,
% requiring no changes to your stimulus code other than mentioned here to
% take full advantage of all functionality of Psychtoolbox just as with standard
% 8 bpc displays at the higher 14 bpc quality of Bits++. If you find this
% not to be the case then it's either an omission in our documentation
% or a bug - Please report it.
%
%
% BITS# specific functions:
%
% A Bits# device which is connected via USB will show up as an additional
% serial port on the system. This driver will communicate with the Bits#
% by establishing a serial port connection to the device via that serial
% port. Presence of a Bits# can be signalled by either calling the BitsPlusPlus('OpenBits#')
% function and passing a serial port device spec 'portSpec', or just by calling
% BitsPlusPlus('OpenBits#') without any parameters. In the latter case, the
% driver will check for the existence of a configuration file named...
% [PsychtoolboxConfigDir 'BitsSharpConfig.txt']. Presence of the file means
% to use a Bits# device, absence means to treat any device as a Bits+ device.
% Presence of a serial port device file name in the first line of that text
% configuration file will use the serial port device with that name for
% communication, otherwise the driver will try to auto-detect the proper
% serial port for communication. If you have multiple such devices, you can add
% multiple lines with serial port names to the configuration file, and then select
% a given device by specifying a index into the file as 'portSpec'. portSpec=1
% would use line 1 of the file for finding the device, portSpec=2 would use line 2
% etc.
%
%
% [handle, portHandle] = BitsPlusPlus('OpenBits#' [, portSpec]);
% -- Open a serial port control connection to a connected Bits# device, return
% a non-zero 'handle' to it on success, or the value zero if no such device exists
% or could not be opened. On successfull open, a low-level 'portHandle' is returned
% as well, which allows access to the serial port control connection via IOPort for
% people who really know what they are doing.
%
% Note: The current implementation only allows to connect to one device at a time,
% therefore use of the returned 'handle' is not very useful at the moment.
%
% The 'portSpec' parameter is optional and defines the name of the serial
% port(-device file) or index of the CRS device to use for the connection.
% If omitted, the name will be taken from a configuration file, or auto-detected.
% If specified as a string, the string defines the serial port device file. If
% specified as a numeric index, it selects the line within the configuration file
% from which the portname string will be taken, ie. index 1 = 1st line, 2 = 2nd line...
%
% This function must be called before use of any Bits# specific functions, otherwise
% they'll turn into no-ops or failures. This function can be called multiple times for
% a given device. It will only open the connection on first call. Successive calls will
% do nothing but increment a reference count of clients to the device.
%
%
% rc = BitsPlusPlus('Close' [, handle]);
% -- Decrement reference count to a Bits# device 'handle', close the serial
% connection to it once the count drops to zero, ie., as soon as nobody is using
% the connection anymore. If 'handle' is omitted, the 'Close' call is executed for
% each currently open device.
%
%
% rc = BitsPlusPlus('ResetOnWindowClose');
% -- Like 'Close', but switch display back to Bits++ video mode first, as
% that mode is "GUI friendly". Usually automatically called from Screen()
% when the Bits# stimulation onscreen window gets closed, at least if you
% used PsychImaging() to control the device.
%
%
% rc = BitsPlusPlus('CheckGPUSanity', window, xoffset [, injectFault=0]);
% -- Perform online-test of GPU identity gamma tables and DVI-D display
% encoders. Try to correct problems with wrong identity gamma tables and at
% least detect problems with (spatio-)temporal display dithering. Returns
% rc == 0 on full success, rc > 0 on failure.
% If the optional 'injectFault' parameter is set to 1, then an intentionally
% perturbed gamma table is loaded into the gpu to test how well the gamma table
% tweaking code is able to recover from wrong tables.
%
%
% pixels = BitsPlusPlus('GetVideoLine', nrPixels, scanline);
% -- Return the first (left-most) 'nrPixels' pixels in video scanline
% 'scanline' of the video display driven by a Bits# device. 'pixels' is
% a uint8 matrix with three rows for red, green and blue pixel color values,
% and 'nrPixels' columns, the three elements of each column encoding the
% r,g,b color values of the pixel corresponding to that column (x-position)
% of the scanline (y-position). Values are read back via the USB-Serial
% connection from the Bits# and the device sends back the pixel data as
% received over the DVI-D link.
%
%
% BitsPlusPlus('SwitchToBits++');
% -- Switch Bits# to Bits++ mode.
%
%
% BitsPlusPlus('SwitchToMono++');
% -- Switch Bits# to Mono++ mode.
%
%
% BitsPlusPlus('SwitchToColor++');
% -- Switch Bits# to Color++ mode.
%
%
% BitsPlusPlus('SwitchToStatusScreen');
% -- Switch Bits# to Status screen display.
%
%
% BitsPlusPlus('MassStorageMode');
% -- Switch Bits# to MassStorageMode. This will forcefully close allow
% client connections to the device, close the USB serial port connection
% and close the driver. The Bits# will report into USB mass storage mode,
% where it can get accessed like a USB flash drive, e.g., to edit configuration
% files, update firmware or EDID's etc. Only a power-cycle will bring the
% device back into a mode which allows us to connect to it again.
%
%
% History:
% 22.04.2007 Written (MK).
% xx.12.2007 Support for DIO T-Lock code generation (MK).
% 17.04.2008 Add support for overlay windows in Mono++ mode, and for color
% correction/gamma correction via PsychColorCorrection (MK).
% 4.07.2009 Add support for other color correction methods like CLUT (MK).
% 14.12.2009 Add support for other target devices, e.g., DataPixx (MK).
% 3.01.2010 Some bugfixes to DataPixx support. (MK)
% 12.01.2013 Make compatible with PTB panelfitter. (MK)
% 13.03.2013 Make compatible with CRS Bits# video display system. (MK)
% 15.04.2013 Add mode = BitsPlusPlus('GetColorConversionMode', win); (MK)
% 24.06.2016 Improved diagnostics. Now need validation from BitsPlusImagingPipelineTest
% and BitsPlusIdentityClutTest, instead of only BitsPlusImagingPipelineTest.
% Now also triggers revalidation if OS kernel version/release changes, as
% things like dithering or output color depth control are usually located in
% the kernel level display drivers, so new kernel can imply new bugs.
% 01.05.2017 Replace evalin('base', ...) call by direct call in PsychDataPixx clut updates,
% as a small performance optimization. (MK)
% Now possible due to ability for Screen() to assign imaging pipeline variables
% to callers workspace. This requires Octave 3.8+ or Matlab R2012a, which is our
% supported minimum requirement for Psychtoolbox 3.0.14.
%
% 17.06.2018 Add support for dual-display setups with two Bits+/Bits#/Display++
% Add support for returning device handles, port handles, and specifying
% devices by number in BitsSharpConfig file. (MK)
global GL;
% Flag for validation: If not set to one, then this routine will check if
% proper operation of Bitsplusplus with GPU imaging has been verified.
persistent validated;
% Type of box: 0 = Bits+, 1 = Datapixx:
persistent targetdevicetype;
% Single output device (=0), or dual devices (=1), e.g., for dual-display:
persistent dualdevices;
% Name strings:
persistent devname;
persistent drivername;
persistent bplusname;
persistent mononame;
persistent colorname;
persistent devbits;
persistent checkGPUEncoders;
persistent bitsSharpPort;
persistent refCount;
% Vector that assigns overlay window handles to onscreen window handles:
persistent OverlayWindows;
% Encoded T-Lock display list handle for driving Bits++ DIO:
persistent tlockhandle;
% Counter of pending T-Lock display list blits: Zero == Disabled.
persistent blitTLockCode;
% Corrective x-offset for DIO blitting:
persistent tlockXOffset;
% Opmode for color conversion/buffer sampling in Color++ / C48 mode:
persistent colorConversionMode;
% Vector of cached per-window colorConversionMode:
persistent colorConversionModeWin;
if nargin < 1
error('You must specify a command in argument "cmd"!');
end
win = [];
winRect = [];
if cmd == 1
% Fast callback path for PTB imaging pipeline. We got called from the
% finalizer blit chain of the imaging pipeline, asking us to perform
% some post-processing on the final framebuffer image, immediately
% before bufferswap.
%
% Currently, the only supported operation is drawing of a DIO T-Lock
% code into the framebuffer, for control of the DIO pins of the Bits++
% box. The T-Lock code has been generated already by a call to
% 'DIOCommand'. We just have to blit that "Code Image" to the
% framebuffer. We can't use Screen() commands here as we are called
% from inside Screen -- Screen is not reentrant!
%
% We only blit if there is something to blit. Then we reset to nothing
% to blit:
if blitTLockCode ~= 0
glCallList(tlockhandle);
blitTLockCode = blitTLockCode - 1;
end
return;
end
% Default debuglevel for output during initialization:
debuglevel = 1;
if isempty(validated)
validated = 0;
tlockhandle = 0;
blitTLockCode = 0;
tlockXOffset = 0;
OverlayWindows = [];
targetdevicetype = 0;
dualdevices = 0;
drivername = 'BitsPlusPlus';
devname = 'Bits+';
bplusname = 'Bits++';
mononame = 'Mono++';
colorname = 'Color++';
devbits = 14;
checkGPUEncoders = 0;
colorConversionMode = [];
colorConversionModeWin = [];
bitsSharpPort = [];
refCount = 0;
end
if strcmpi(cmd, 'DIOCommand')
% Setup new DIO command to be converted to T-Lock code and blitted:
if nargin < 2 || isempty(arg)
error('window handle for Bits++ onscreen window missing!');
end
if nargin < 3 || isempty(dummy)
error('Number of repetitions for DIO command missing!');
end
if nargin < 6
error('DIOCommand must have the parameters "Mask", "Command" and "Data"!');
end
mask = varargin{1};
data = varargin{2};
command = varargin{3};
% Create or recreate our display list:
glNewList(tlockhandle, GL.COMPILE);
for i=1:size(mask, 1)
% Process i'th row of command sequence:
% Generate DIO T-Lock image as Matlab matrix:
tlockdata = BitsPlusDIO2Matrix(mask(i), data(i,:), command(i));
% Convert from Matlab matrix to OpenGL pixel format:
encodedDIOdata = uint8(zeros(3, 508));
% Pack 3 separate RGB planes into rows 1,2,3. As Matlabs data format is
% column major order, this will end up as tightly packed pixel array in
% format RGBRGBRGB.... just as glDrawPixels likes it.
encodedDIOdata(1,:) = tlockdata(1,:,1);
encodedDIOdata(2,:) = tlockdata(1,:,2);
encodedDIOdata(3,:) = tlockdata(1,:,3);
if nargin >= 7
% Optional x, y blit position provided:
xDIO = varargin{4};
yDIO = varargin{5};
xDIO = xDIO(i);
yDIO = yDIO(i);
if yDIO < 1
yDIO = 1;
end
else
% Set default position: 3rd scanline of display, so we don't get
% into the way of a possible CLUT T-Lock code:
xDIO = 0;
yDIO = 2 + i;
end
% Add command sequence for this T-Lock code to display list:
glRasterPos2i(xDIO + tlockXOffset, yDIO);
glDrawPixels(508, 1, GL.RGB, GL.UNSIGNED_BYTE, encodedDIOdata);
end
% Finish display list;
glEndList;
% Assign number of repetitions:
blitTLockCode = dummy;
% Done. Return.
return;
end
if strcmpi(cmd, 'DIOCommandReset')
% Dummy error check: arg will be used in later revisions...
if nargin < 2 || isempty(arg)
error('window handle for Bits++ onscreen window missing!');
end
% Disable T-Lock blitting:
blitTLockCode = 0;
return;
end
if strcmpi(cmd, 'SetTargetDeviceType')
if nargin < 2
error('targetdevicetype parameter missing!');
end
% Assign targetdevicetype to internal persistent variable:
% A zero means: It is a regular CRS Bits+ box.
% A 1 means: It is a VPixx DataPixx box which is sharing setup code
% with Bits+ in this file:
targetdevicetype = arg;
switch (targetdevicetype)
case 0,
drivername = 'BitsPlusPlus';
if ~isempty(bitsSharpPort)
devname = 'Bits#';
else
devname = 'Bits+';
end
bplusname = 'Bits++';
mononame = 'Mono++';
colorname = 'Color++';
devbits = 14;
case 1,
drivername = 'PsychDatapixx';
devname = 'DataPixx';
bplusname = 'L48';
mononame = 'M16';
colorname = 'C48';
devbits = 16;
otherwise
error('Unknown targetdevicetype assigned in call to "SetTargetDeviceType"!');
end
return;
end
if strcmpi(cmd, 'SetDualDevices')
if nargin < 2
error('dualdevices parameter missing!');
end
% Assign dualdevices flag to internal persistent variable:
dualdevices = arg;
return;
end
if strcmpi(cmd, 'OpenBits#')
% Try to open connection to a Bits# device. Return true if successfull,
% false otherwise - which would likely imply a Bits+ instead of Bits#.
winRect = [];
if ~isempty(bitsSharpPort)
% Already open. Do nothing but return and report success:
win = 1;
winRect = bitsSharpPort;
% Increment reference count:
refCount = refCount + 1;
return;
end
% Explicit serial port name for connection to device provided?
if nargin > 1 && ~isempty(arg)
bitsSharpPortname = arg;
if ~ischar(bitsSharpPortname) && (~isnumeric(bitsSharpPortname) || ~isscalar(bitsSharpPortname))
error('Provided Bits# serial port name is not a valid namestring or device index!');
end
else
% No portname given:
bitsSharpPortname = [];
end
% Have a portname?
if isempty(bitsSharpPortname) || isnumeric(bitsSharpPortname)
% No: Find out if a Bits# configuration file exists. Otherwise we assume
% that usercode does not want to connect to a Bits# but user probably uses
% an older - connectionless - Bits+, and therefore turn ourselves into a no-op:
configfile = [PsychtoolboxConfigDir 'BitsSharpConfig.txt'];
if ~exist(configfile, 'file')
% No config file -> No Bits#. We no-op and return "no such device":
win = 0;
fprintf('BitsPlusPlus: Could not find a Bits# config file under [%s]. Assuming a Bits+ device instead of a Bits# is connected.\n', configfile);
fprintf('BitsPlusPlus: Please create a config file under this name if you have a Bits# and want to use it as Bits# instead of as a Bits+.\n');
fprintf('BitsPlusPlus: The most simple way is to create an empty file. A more robust way is to store the name of the Bits# serial port\n');
fprintf('BitsPlusPlus: in the first line of the text file, e.g., COM5 [Windows], or /dev/ttyACM0 [Linux] or similar.\n');
return;
end
% File exists -> We want to access a Bits#. Parse file for a port name string:
if isempty(bitsSharpPortname)
bitsSharpPortname = 1;
end
fileContentsWrapped = [];
fid = fopen(configfile);
% Get specified line:
for lineidx=1:bitsSharpPortname
fileContentsWrapped = fgets(fid);
end
fclose(fid);
% Port spec available?
if ~isempty(fileContentsWrapped) && ischar(fileContentsWrapped)
% Yes: Assign namestring for port.
bitsSharpPortname = deblank(fileContentsWrapped);
fprintf('BitsPlusPlus: Connecting to Bits# device via serial port [%s], as provided by configuration file [%s].\n', bitsSharpPortname, configfile);
else
% No: Do the guess-o-matic dance: Fail softly if it doesn't work:
try
% Try to find proper serial port:
bitsSharpPortname = FindSerialPort([], 1, 0);
fprintf('BitsPlusPlus: Connecting to Bits# device via auto-detected serial port [%s].\n', bitsSharpPortname);
catch
lerr = psychlasterror('reset');
disp(lerr.message);
fprintf('BitsPlusPlus: Failed to find the Bits# device! Is it connected and ready? See diagnostics above. Continuing without Bits# support.\n');
win = 0;
return;
end
end
else
fprintf('BitsPlusPlus: Connecting to Bits# device via serial port [%s], as provided by usercode.\n', bitsSharpPortname);
end
% Ok. Try to connect:
try
% Open the port. We reduce level of verbosity during open, to suppress clutter:
oldverblevel = IOPort('Verbosity', 1);
[bitsSharpPort, errmsg] = IOPort('OpenSerialPort', bitsSharpPortname);
IOPort('Verbosity', oldverblevel);
catch %#ok<*CTCH>
error('Failed to establish a connection to the Bits# via serial port.');
end
% Success?
if bitsSharpPort < 0
% No: Delete invalid port handle.
bitsSharpPort = []; %#ok<NASGU>
error('Failed to establish a connection to the Bits# via serial port. The error message was: %s', errmsg);
end
% Yes. Change reported device name:
devname = 'Bits#';
fprintf('BitsPlusPlus: Device information:\n');
% Some queries to the device to test the connection:
IOPort('Write', bitsSharpPort, ['$ProductType' char(13)]);
WaitSecs('YieldSecs', 0.1);
while IOPort('BytesAvailable', bitsSharpPort)
fprintf('BitsPlusPlus: %s\n', deblank(char(IOPort('Read', bitsSharpPort))));
WaitSecs('YieldSecs', 0.1);
end
IOPort('Write', bitsSharpPort, ['$SerialNumber' char(13)]);
WaitSecs('YieldSecs', 0.1);
while IOPort('BytesAvailable', bitsSharpPort)
fprintf('BitsPlusPlus: %s\n', deblank(char(IOPort('Read', bitsSharpPort))));
WaitSecs('YieldSecs', 0.1);
end
IOPort('Write', bitsSharpPort, ['$FirmwareDate' char(13)]);
WaitSecs('YieldSecs', 0.1);
while IOPort('BytesAvailable', bitsSharpPort)
fprintf('BitsPlusPlus: %s\n', deblank(char(IOPort('Read', bitsSharpPort))));
WaitSecs('YieldSecs', 0.1);
end
fprintf('\n');
% Increment reference count:
refCount = refCount + 1;
% Report success:
win = 1;
% Return IOPort handle as well:
winRect = bitsSharpPort;
return;
end
if strcmp(cmd, 'GetVideoLine')
% Readback a video line of pixels from the device:
%
% Usage:
%
% BitsPlusPlus('GetVideoLine', nrPixels, scanline);
% Parse inputs: Number of pixels to read back and scanline index
% of scanline to read back:
nrPixels = arg;
scanline = dummy;
% Perform pixel readback from device:
scanline = BitsSharpGetScanline(bitsSharpPort, scanline, nrPixels);
% Return scanline pixels as 1st return argument:
win = scanline;
return;
end
if strcmpi(cmd, 'PerformPostWindowOpenSetup')
% Called from PsychImaging after onscreen window and associated imaging pipeline
% is fully opened and initialized:
% Get windowhandle of associated onscreen window:
win = arg;
% Attach a window close callback for Device teardown at window close time:
Screen('Hookfunction', win, 'AppendMFunction', 'CloseOnscreenWindowPostGLShutdown', 'Shutdown window callback into BitsPlusPlus driver.', 'BitsPlusPlus(''ResetOnWindowClose'');');
Screen('HookFunction', win, 'Enable', 'CloseOnscreenWindowPostGLShutdown');
return;
end
if strcmpi(cmd, 'ResetOnWindowClose')
% Called from Screen() at onscreen window close time, or manually from usercode:
% Explicit device handle specified?
if nargin >= 2 && ~isempty(arg)
% Yes. Currently we only accept the handle 1, as we can not do
% multi-device yet. Just validate for future correctness:
if arg ~= 1 || isempty(bitsSharpPort)
error('BitsPlusPlus: Close: Invalid ''handle'' specified. No such device open.');
end
end
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to desktop GUI friendly Bits++ mode.\n');
IOPort('Write', bitsSharpPort, ['$BitsPlusPlus' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
% Signal that device connection was actually open:
win = 1;
else
% Signal that device connection was not actually open:
win = 0;
end
% Fall through to close command:
cmd = 'Close';
end
if strcmpi(cmd, 'Close')
% Connection to Bits# established?
% Explicit device handle specified?
if nargin >= 2 && ~isempty(arg)
% Yes. Currently we only accept the handle 1, as we can not do
% multi-device yet. Just validate for future correctness:
if arg ~= 1 || isempty(bitsSharpPort)
error('BitsPlusPlus: Close: Invalid ''handle'' specified. No such device open.');
end
end
% More than one client (this calling client) holding a reference to Bits# ?
if refCount > 1
% Yes. Just decrement the refCount to release this reference and be done:
refCount = refCount - 1;
win = 1;
return;
end
% Caller is last client of Bits#. Reset refCount to zero and really
% close the connection:
refCount = 0;
if ~isempty(bitsSharpPort)
% Yes. Close connection:
IOPort('Close', bitsSharpPort);
bitsSharpPort = [];
fprintf('BitsPlusPlus: Connection to Bits# device closed.\n');
% Signal that device connection was actually open:
win = 1;
else
% Signal that device connection was not actually open:
win = 0;
end
return;
end
if strcmpi(cmd, 'SwitchToBits++')
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to Bits++ mode.\n');
IOPort('Write', bitsSharpPort, ['$BitsPlusPlus' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
win = 1;
else
win = 0;
end
return;
end
if strcmpi(cmd, 'SwitchToMono++')
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to Mono++ mode.\n');
IOPort('Write', bitsSharpPort, ['$monoPlusPlus' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
win = 1;
else
win = 0;
end
return;
end
if strcmpi(cmd, 'SwitchToColor++')
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to Color++ mode.\n');
IOPort('Write', bitsSharpPort, ['$colourPlusPlus' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
win = 1;
else
win = 0;
end
return;
end
if strcmpi(cmd, 'SwitchToStatusScreen')
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to Diagnostic display mode.\n');
IOPort('Write', bitsSharpPort, ['$statusScreen' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
win = 1;
else
win = 0;
end
return;
end
if strcmpi(cmd, 'MassStorageMode')
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch back to Bits++ display mode, which provides a reasonably
% useable display of the regular desktop GUI:
fprintf('BitsPlusPlus: Switching Bits# device to MassStorageMode mode and disconnecting...\n');
IOPort('Write', bitsSharpPort, ['$USB_massStorage' char(13)]);
% Flush commands:
IOPort('Flush', bitsSharpPort);
% Disconnect forcefully, as the Bits# will no longer respond to our
% commands until it is manually restarted:
refCount = 0;
IOPort('Close', bitsSharpPort);
bitsSharpPort = [];
win = 1;
else
win = 0;
end
return;
end
if strcmpi(cmd, 'SetColorConversionMode')
% Set the mode of operation for color conversion in Color++ / C48 mode.
% This is a mandatory call in that mode. As the effective output
% resolution is only half the framebuffer resolution we need to decide
% what tradeoff between aspect-ratio preservation, sampling precision etc.
% to take.
colorConversionMode = arg;
return;
end
if strcmpi(cmd, 'GetColorConversionMode')
% Return the mode of operation for color conversion in Color++ / C48 mode.
if nargin < 2 || isempty(arg) || ~isa(arg, 'double') || (Screen('WindowKind', arg) ~= 1)
error('%s: "GetColorConversionMode" called without valid onscreen window handle.', drivername);
end
win = colorConversionModeWin(arg);
return;
end
if strcmpi(cmd, 'TestGPUEncoders')
% Perform check of GPU identity gamma tables and encoders during next
% 'OpenWindowXXX' call in Datapixx mode or Bits# mode. This is a one-shot,
% auto-reset flag:
checkGPUEncoders = 1;
return;
end
if strcmpi(cmd, 'ForceUnvalidatedRun')
% Enforce use of this routine without verification of correct function
% of the imaging pipeline. This is used by the correctness test itself
% in order to be able to run the validation.
validated = 1;
return;
end
if strcmpi(cmd, 'StoreValidation')
% Enforce use of this routine without verification of correct function
% of the imaging pipeline. This is used by the correctness test itself
% in order to be able to run the validation.
validationType = dummy;
ValidateBitsPlusImaging(arg, 1, devname, validationType);
return;
end
if strcmpi(cmd, 'LoadIdentityClut')
% Load an identity CLUT into Bits++ at next Screen('Flip'). This is
% just a little convenience wrapper around 'LoadNormalizedGammaTable':
% Restore Bits++ Identity CLUT so it can be used as normal display:
if nargin < 2 || isempty(arg)
error('window handle for %s onscreen window missing!', devname);
end
linear_lut = repmat(linspace(0, 1, 256)', 1, 3);
Screen('LoadNormalizedGammaTable', arg, linear_lut, 2);
return;
end
if strcmpi(cmd, 'OpenWindowBits++')
% Execute the Screen('OpenWindow') command with proper flags, followed
% by our own Initialization. Return values of 'OpenWindow'.
%
% This will set up the Bits++ mode of Bits++
% Assign screen index:
if nargin < 2 || isempty(arg) || ~isa(arg, 'double')
error('%s: "OpenWindow..." called without valid screen handle.', drivername);
end
screenid = arg;
% Assign optional clear color:
if nargin < 3
clearcolor = [];
else
clearcolor = dummy;
end
% windowRect is always full screen -- Anything else would make the
% Bits++ display fail.
if IsLinux && ~isempty(varargin)
winRect = varargin{1};
else
winRect = [];
end
% pixelSize is also fixed to 32 bit RGBA8 framebuffer:
pixelSize = 32;
% Same for double-buffering:
numbuffers = 2;
% stereomode we take...
if nargin >= 7
stereomode = varargin{4};
else
stereomode = [];
end
% multiSample gets forced to zero, as it would interfere
% with Bits++ display controller:
multiSample = 0;
% Open the window, pass all parameters (partially modified or overriden), return Screen's return values:
if nargin >= 9
[win, winRect] = Screen('OpenWindow', screenid, clearcolor, winRect, pixelSize, numbuffers, stereomode, multiSample, varargin{6:end});
else
[win, winRect] = Screen('OpenWindow', screenid, clearcolor, winRect, pixelSize, numbuffers, stereomode, multiSample);
end
% Ok, if we reach this point then we've got a proper onscreen
% window on the Bits++. Let's reassign our arguments and continue with
% the init sequence:
% First load the graphics hardwares gamma table with an identity mapping,
% so it doesn't interfere with Bits++ -- Functions from Bits++ toolbox.
LoadIdentityClut(win);
% We need the GL for DIO T-Lock setup:
if isempty(GL)
% Load & Initalize constants and moglcore, but don't set the 3D gfx
% flag for Screen():
InitializeMatlabOpenGL([], [], 1);
end
% Test accuracy/correctness of GPU's rasterizer for different output
% positioning methods: Return (non-zero) dx,dy offsets, if any:
[rpfx, rpfy, rpix] = PsychGPURasterizerOffsets(win, drivername); %#ok<ASGLU>
if rpix~=0
tlockXOffset = -rpix;
fprintf('OpenWindow%s: Applying corrective horizontal T-Lock offset of %i pixels for buggy graphics card driver. Will hopefully fix it...\n', bplusname, tlockXOffset);
end
if targetdevicetype == 1 && checkGPUEncoders
% Perform DataPixx builtin diagnostics to detect problems with
% wrong GPU gamma tables or GPU dithering:
checkGPUEncoders = 0;
if PsychDataPixx('CheckGPUSanity', win, tlockXOffset)
% Ohoh, trouble ahead! The driver detected problems with the
% GPU and wasn't able to auto-correct them.
fprintf('%s: CAUTION! DataPixx internal diagnostic detected problems with your graphics card driver which it could not correct by itself!\n', drivername);
end
end
if targetdevicetype == 0 && checkGPUEncoders
% Perform Bits# builtin diagnostics to detect problems with
% wrong GPU gamma tables or GPU dithering:
checkGPUEncoders = 0;
if doCheckGPUSanity(win, tlockXOffset, bitsSharpPort)
% Ohoh, trouble ahead! The driver detected problems with the
% GPU and wasn't able to auto-correct them.
fprintf('%s: CAUTION! Bits# internal diagnostic detected problems with your graphics card driver which it could not correct by itself!\n', drivername);
end
end
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch it to Bits++ display mode:
IOPort('Write', bitsSharpPort, ['$BitsPlusPlus' char(13)]);
fprintf('BitsPlusPlus: Switching Bits# device to Bits++ video mode. This will take about 5 seconds...\n');
WaitSecs('YieldSecs', 5);
end
% Now enable finalizer hook chains and load them with the special Bits++
% command for T-Lock based Bits++ internal CLUT updates:
if tlockXOffset ~= 0
offsetstring = sprintf('xPosition=%i', tlockXOffset);
else
offsetstring = '';
end
if targetdevicetype == 0
Screen('HookFunction', win, 'PrependBuiltin', 'LeftFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
if targetdevicetype == 1
rclutcmd = 'PsychDataPixx(1, IMAGINGPIPE_GAMMATABLE);';
Screen('HookFunction', win, 'PrependMFunction', 'LeftFinalizerBlitChain', 'Upload new clut into DataPixx callback', rclutcmd);
end
Screen('HookFunction', win, 'Enable', 'LeftFinalizerBlitChain');
if ~isempty(stereomode) && ismember(stereomode, [1, 4, 5, 10, 11])
% Enable CLUT updates on right stereo buffer as well:
% CRS devices, frame-sequential stereo or native quad-buffered OpenGL stereo,
% or dual-window stereo (mostly for OSX dual-display):
if targetdevicetype == 0 && ismember(stereomode, [1, 10, 11])
Screen('HookFunction', win, 'PrependBuiltin', 'RightFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
% Dual CRS devices, dual-display stereo on Linux or Windows:
if targetdevicetype == 0 && ismember(stereomode, [4, 5]) && dualdevices == 1
% Here one PTB window drives both video outputs (split-window style) and
% thereby both connected CRS devices. In order to set a CLUT on both of
% these devices, we need to blit the Clut T-Lock into the right half of
% our window as well. However, we use the LeftFinalizerBlitChain for this,
% as the RightFinalizerBlitChain is not operational in stereomode 4 and 5:
offsetstring = sprintf('xPosition=%i', tlockXOffset + Screen('WindowSize', win, 1) / 2);
Screen('HookFunction', win, 'PrependBuiltin', 'LeftFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
% VPixx devices, frame-sequential stereo or native quad-buffered OpenGL stereo:
if targetdevicetype == 1 && ismember(stereomode, [1, 11])
Screen('HookFunction', win, 'PrependMFunction', 'RightFinalizerBlitChain', 'Upload new clut into DataPixx callback', rclutcmd);
end
Screen('HookFunction', win, 'Enable', 'RightFinalizerBlitChain');
end
if targetdevicetype == 0
% Setup finalizer callback for DIO T-Lock updates:
tlockhandle = SetupDIOFinalizer(win, stereomode);
end
% Load an identity CLUT into the Bits++ to start with:
linear_lut = repmat(linspace(0, 1, 256)', 1, 3);
Screen('LoadNormalizedGammaTable', win, linear_lut, 2);
% Check validation:
if ~validated
% Only validate output display pipeline from framebuffer to display device:
ValidateBitsPlusImaging(win, 0, devname, 2);
end
% Reset validation flag after first run:
validated = 0;
% Set colorConversionMode for this window to safe "undefined" default:
colorConversionModeWin(win) = -1;
% Ready!
return;
end
if strcmpi(cmd, 'OpenWindowMono++') || strcmpi(cmd, 'OpenWindowMono++WithOverlay') || strcmpi(cmd, 'OpenWindowColor++')
% Execute the Screen('OpenWindow') command with proper flags, followed
% by our own Initialization. Return values of 'OpenWindow'.
%
% This will set up the Mono++ or Color++ mode of Bits++
% Assign screen index:
if nargin < 2 || isempty(arg) || ~isa(arg, 'double')
error('%s: "OpenWindow..." called without valid screen handle.', drivername);
end
screenid = arg;
% Assign optional clear color:
if nargin < 3
clearcolor = [];
else
clearcolor = dummy;
end
if isempty(clearcolor)
clearcolor = 1.0;
end
% windowRect is always full screen -- Anything else would make the
% Bits++ display fail.
if IsLinux && ~isempty(varargin)
winRect = varargin{1};
else
winRect = [];
end
% pixelSize is also fixed to 32 bit RGBA8 framebuffer:
pixelSize = 32;
% Same for double-buffering:
numbuffers = 2;
% stereomode we take...
if nargin >= 7
stereomode = varargin{4};
else
stereomode = [];
end
% Retrieve multiSample setting:
if nargin >= 8
multiSample = varargin{5};
else
multiSample = [];
end
% Imaging mode we take - and combine it with our own requirements:
if nargin >= 9
imagingmode = varargin{6};
else
imagingmode = 0;
end
% For imagingmode we need at least fast backingstore, the output
% formatter enabled and some high precision color buffer. We default to
% 32 bpc floating point, the only safe choice accross different graphics cards
% from different vendors, but the users imagingmode setting is free to
% override this with a 16 bpc fixed buffer. 16 bpc float works as well
% but can't use the full Bits++ color range at full precision.
if bitand(imagingmode, kPsychNeed16BPCFloat) || bitand(imagingmode, kPsychNeed16BPCFixed) || bitand(imagingmode, kPsychUse32BPCFloatAsap)
% User specified override: Use it.
ourspec = 0;
else
% No user specified accuracy. We play safe and choose the highest
% one:
ourspec = kPsychNeed32BPCFloat;
end
% Imagingmode must at least include the following:
imagingmode = mor(imagingmode, kPsychNeedFastBackingStore, kPsychNeedOutputConversion, kPsychNeedRetinaResolution, ourspec);
if strcmpi(cmd, 'OpenWindowColor++')
if isempty(colorConversionMode)
sca;
fprintf('The new mandatory parameter "colorConversionMode" is missing!\n');
fprintf('If you used BitsPlusPlus(''OpenWindowColor++'', ...); to get here, then\n');
fprintf('add the command BitsPlusPlus(''SetColorConversionMode'', mode);\n');
fprintf('immediately before the BitsPlusPlus(''OpenWindowColor++'', ...); command.\n\n');
fprintf('If you used the more modern and recommended PsychImaging() commands to get here, then\n');
fprintf('change your call to PsychImaging(''AddTask'', ''General'', ''EnableBits++Color++Output'');\n');
fprintf('or to PsychImaging(''AddTask'', ''General'', ''EnableDataPixxC48Output''); into a call to \n');
fprintf('PsychImaging(''AddTask'', ''General'', ''EnableBits++Color++Output'', mode);\n');
fprintf('or PsychImaging(''AddTask'', ''General'', ''EnableDataPixxC48Output'', mode);\n\n');
fprintf('The new parameter "mode" must be 0 if you want exactly the old behaviour back.\n');
fprintf('For new code, you will likely want to use a value of 1 or 2 to preserve correct\n');
fprintf('aspect ratio.\n\n');
fprintf('Please read the help section for the PsychImaging() command ("help PsychImaging")\n');
fprintf('for the ''EnableBits++Color++Output'' subcommand. It explains the meaning of the different\n');
fprintf('possible settings of "mode".\n\n');
error('Mandatory parameter "colorConversionMode" is missing!');
end
if ~ismember(colorConversionMode, [0,1,2]);
sca;
fprintf('The provided "colorConversionMode" parameter %i is not one of the valid values 0, 1 or 2!\n', colorConversionMode);
error('Mandatory parameter "colorConversionMode" is invalid!');
end
if colorConversionMode == 0
% In Color++ mode with "classic" conversion, we only have half the
% effective horizontal resolution. Tell PTB to take this into
% account for all relevant calculations:
imagingmode = mor(imagingmode, kPsychNeedHalfWidthWindow);
end
targetMode = ['$colourPlusPlus' char(13)];
targetModeName = 'Color++';
else
% Mono++ mode, with or without overlay.
targetMode = ['$monoPlusPlus' char(13)];
targetModeName = 'Mono++';
end
% Open the window, pass all parameters (partially modified or overriden), return Screen's return values:
% Note that we clear to black (==0), because we set the real background
% clear color "further down the road" after we've established our
% default color range of 0.0 - 1.0, ie. in the normalized 0 - 1 range.
if nargin > 9
[win, winRect] = Screen('OpenWindow', screenid, 0, winRect, pixelSize, numbuffers, stereomode, multiSample, imagingmode, varargin{7:end});
else
[win, winRect] = Screen('OpenWindow', screenid, 0, winRect, pixelSize, numbuffers, stereomode, multiSample, imagingmode);
end
% Ok, if we reach this point then we've got a proper onscreen
% window on the Bits++. Let's reassign our arguments and continue with
% the init sequence:
% Some more diagnostics and info for user:
winfo = Screen('GetWindowInfo', win);
% Unconditional support for 32 bpc float drawable requested?
havespoken = 0;
if ~bitand(imagingmode, kPsychNeed32BPCFloat)
% Nope. Conditional support requested?
if (bitand(imagingmode, kPsychUse32BPCFloatAsap) && winfo.GLSupportsBlendingUpToBpc < 32)
% Conditional use of 32 bpc float buffers requested, but GPU
% doesn't support 32 bpc float blending --> drawBuffer will only be
% 16 bpc -- Loss of precision!
fprintf('PTB - Info: Your framebuffer is only configured to provide about 10-11 bits of precision, because your\n');
fprintf('PTB - Info: script requested support for simultaneous alpha-blending and high precision, but your hardware is not\n');
fprintf('PTB - Info: capable of supporting highest precision with alpha-blending enabled. You will therefore only\n');
fprintf('PTB - Info: be able to use about 11 bits out of the %i bits precision that %s provides for stimulus definition.\n', devbits, devname);
fprintf('PTB - Info: Stimulus postprocessing, e.g., gamma correction, will still make good use of all %i bits though.\n', devbits);
fprintf('PTB - Info: You can either live with this limitation, or do not use alpha-blending or upgrade your graphics\n');
fprintf('PTB - Info: hardware to Direct3D-10 compliant hardware, e.g., ATI Radeon HD-3000 or NVidia Geforce-8000 and later.\n\n');
havespoken = 1;
end
if bitand(imagingmode, kPsychNeed16BPCFloat)
fprintf('PTB - Info: Your framebuffer is only configured to provide about 10-11 bits of precision, because your\n');
fprintf('PTB - Info: script requested only 16 bpc float precision. You will therefore only be able to use\n');
fprintf('PTB - Info: about 11 bits out of the %i bits precision that %s provides for stimulus drawing.\n', devbits, devname);
fprintf('PTB - Info: If you want to use the full %i bit precision, you will need to request a 32 bpc float framebuffer.\n\n', devbits);
havespoken = 1;
end
if bitand(imagingmode, kPsychNeed16BPCFixed)
fprintf('PTB - Info: Your framebuffer is configured to provide 16 bits of precision, because your\n');
fprintf('PTB - Info: script requested 16 bits fixed precision. %s will be able to finally output %i bits precision.\n', devname, devbits);
fprintf('PTB - Info: Alpha-blending will not work at this configuration with your hardware though. Choose a different\n');
fprintf('PTB - Info: mode if you need alpha-blending and high precision.\n\n');
havespoken = 1;
end
end
if (havespoken == 0) && (bitand(imagingmode, kPsychNeed32BPCFloat) || bitand(imagingmode, kPsychUse32BPCFloatAsap))
fprintf('PTB - Info: Your framebuffer is configured for maximum precision. All internal processing will be done\n');
fprintf('PTB - Info: with about 23 bits of linear precision -- %s will be able to finally output with %i bits precision.\n', devname, devbits);
if winfo.GLSupportsBlendingUpToBpc < 32
fprintf('PTB - Info: Alpha-blending will not work at this precision with your hardware though.\n');
fprintf('PTB - Info: You can either live with this limitation, or upgrade your graphics hardware to Direct3D-10\n');
fprintf('PTB - Info: compliant hardware, e.g., ATI Radeon HD-3000 or NVidia Geforce-8000 and later.\n\n');
else
fprintf('PTB - Info: Alpha-blending should be fully supported at this precision by your hardware.\n\n');
end
end
if strcmpi(cmd, 'OpenWindowColor++')
if colorConversionMode == 0
fprintf('PTB - Info: Classic half horizontal resolution color conversion for %s mode selected.\n', colorname);
fprintf('PTB - Info: Aspect ratio will be horizontally distorted, ie., 2:1.\n');
end
if colorConversionMode == 1
fprintf('PTB - Info: Aspect ratio preserving half horizontal resolution color conversion for %s\n', colorname);
fprintf('PTB - Info: mode selected. All odd-numbered pixel columns will be ignored/skipped.\n');
end
if colorConversionMode == 2
fprintf('PTB - Info: Aspect ratio preserving bilinear color conversion for %s mode selected.\n', colorname);
fprintf('PTB - Info: Will average color between adjacent even/odd pixel columns.\n');
end
fprintf('\n');
end
% First load the graphics hardwares gamma table with an identity mapping,
% so it doesn't interfere with Bits++ -- Function from Bits++ toolbox.
LoadIdentityClut(win);
% Backup current gfx-settings, so we can restore them after
% modifications: The LoadGLSLProgramFromFiles() routine enables this
% implicitely. This is unwanted in case we are in pure 2D mode, so we
% need to undo it below...
ogl = Screen('Preference', 'Enable3DGraphics');
% Create and retrieve a compiled shader and idString-Snippet for
% use with the formatting shader to allow for final
% color-transformations immediately before Mono++ conversion. This
% is mostly meant to implement gammacorrection, clamping or other
% transformations needed for a well calibrated display:
[icmShaders, icmIdString, icmConfig] = PsychColorCorrection('GetCompiledShaders', win, debuglevel);
% Operate in Mono++ mode or Color++ mode?
if strcmpi(cmd, 'OpenWindowMono++') || strcmpi(cmd, 'OpenWindowMono++WithOverlay')
% Setup for Mono++ mode:
if strcmpi(cmd, 'OpenWindowMono++WithOverlay')
useOverlay = 1;
else
useOverlay = 0;
end
% Use of overlay plane requested?
if useOverlay
% Create additional shader for overlay texel fetch:
% Our gpu panel scaler might be active, so the size of the
% virtual window - and thereby our overlay window - can be
% different from the output framebuffer size. As the sampling
% 'pos'ition for the overlay is always provided in framebuffer
% coordinates, we need to subsample in the overlay fetch.
% Calculate proper scaling factor, based on virtual and real
% framebuffer size:
[wC, hC] = Screen('WindowSize', win);
[wF, hF] = Screen('WindowSize', win, 1);
sampleX = wC / wF;
sampleY = hC / hF;
% Build the shader:
shSrc = sprintf('uniform sampler2DRect overlayImage; float getMonoOverlayIndex(vec2 pos) { return(texture2DRect(overlayImage, pos * vec2(%f, %f)).r); }', sampleX, sampleY);
% Create Offscreen window for the overlay. It has the same size
% as the onscreen window, but only 8 bpc fixed depth and a
% completely black background -- fully transparent by default.
% The specialflags 32 setting protects the overlay offscreen
% window from accidental batch-deletion by usercode calls to
% Screen('Close'):
overlaywin = Screen('OpenOffscreenWindow', win, 0, [], 8, 32);
% Retrieve low-level OpenGl texture handle to the window:
overlaytex = Screen('GetOpenGLTexture', win, overlaywin);
% Disable bilinear filtering on this texture - always use
% nearest neighbour sampling to avoid interpolation artifacts
% in color index image for clut indexing:
glBindTexture(GL.TEXTURE_RECTANGLE_EXT, overlaytex);
glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_MAG_FILTER, GL.NEAREST);
glTexParameteri(GL.TEXTURE_RECTANGLE_EXT, GL.TEXTURE_MIN_FILTER, GL.NEAREST);
glBindTexture(GL.TEXTURE_RECTANGLE_EXT, 0);
else
% No.: Create "no-op" shader for zero overlay:
shSrc = 'float getMonoOverlayIndex(vec2 pos) { return(0.0); }';
end
% Build shader from source:
overlayShader = glCreateShader(GL.FRAGMENT_SHADER);
glShaderSource(overlayShader, shSrc);
glCompileShader(overlayShader);
% Attach to list of shaders:
icmShaders(end+1) = overlayShader;
% Load Bits++ Mono++ formatting shader:
shader = LoadGLSLProgramFromFiles('Bits++_Mono++_FormattingShader', debuglevel, icmShaders);
if useOverlay
% Ok, overlay requested. Setup shader's overlayImage sampler to
% texture unit 1 and setup proper pString, so unit 1 has
% overlay bound during blit operation:
pString = sprintf('TEXTURERECT2D(1)=%i', overlaytex);
glUseProgram(shader);
glUniform1i(glGetUniformLocation(shader, 'overlayImage'), 1);
glUseProgram(0);
% Store window handle of overlay window for this onscreen
% window for later retrieval:
OverlayWindows(win) = overlaywin;
else
pString = '';
end
% Now enable output formatter hook chain and load them with the special Bits++
% Mono++ data formatting shader: We append the shader because it
% absolutely must be the last shader to execute in that chain!
idString = sprintf('Mono++ output formatting shader for CRS Bits++ : %s', icmIdString);
pString = [ pString ' ' icmConfig ];
Screen('HookFunction', win, 'AppendShader', 'FinalOutputFormattingBlit', idString, shader, pString);
else
% Setup for Color++ mode:
% No support for overlays in Color++ mode:
useOverlay = 0;
if colorConversionMode == 2
% Load "bilinear" Bits++ Color++ formatting shader for bilinear
% sampling/averaging between adjacent even/odd pixel columns:
shader = LoadGLSLProgramFromFiles('Bits++_Color++_BilinearFormattingShader', debuglevel, icmShaders);
else
% Load "classic" Bits++ Color++ formatting shader for non-interpolated
% sampling:
shader = LoadGLSLProgramFromFiles('Bits++_Color++_FormattingShader', debuglevel, icmShaders);
end
if colorConversionMode == 2
% "Bilinear" mode: Aspect ratio correct, full-width source
% framebuffer. Adjacent even/odd pixels are combined to a
% single output pixel via averaging, ie., the output color is
% the mean value of adjacent even/odd pixels:
% Empty pString, no scaling needed:
pString = '';
else
if colorConversionMode == 0
% "Classic" mode: Aspect ratio distorted half-width source framebuffer:
sampleSpacing = 0.5;
pString = 'Scaling:2.0:1.0';
end
if colorConversionMode == 1
% "Subsample" mode: Aspect ratio correct, full-width source
% framebuffer, but sampled only at even pixel location, ie.
% each second pixel column is skipped:
sampleSpacing = 1.0;
% Empty pString, no scaling needed:
pString = '';
end
glUseProgram(shader);
glUniform1f(glGetUniformLocation(shader, 'sampleSpacing'), sampleSpacing);
glUseProgram(0);
end
% Now enable output formatter hook chain and load them with the special Bits++
% Color++ data formatting shader: We append the shader because it
% absolutely must be the last shader to execute in that chain!
% We apply a scaling of 2.0 in horizontal direction for the output
% blit, to take the fact into account that the internal window
% buffers only have half display width.
idString = sprintf('Color++ output formatting shader for CRS Bits++ : %s', icmIdString);
pString = [ pString ' ' icmConfig ];
Screen('HookFunction', win, 'AppendShader', 'FinalOutputFormattingBlit', idString, shader, pString);
end
% Setup shaders image source as the first texture unit, this is by
% definition of how the imaging pipe works. Don't think really needed,
% as this is the default, but its good practice to not rely on such
% things...
glUseProgram(shader);
glUniform1i(glGetUniformLocation(shader, 'Image'), 0);
glUseProgram(0);
% Perform any setup steps that may be needed by the color correction
% routines. Must be called after 'shader' creation and attachment to
% the imaging pipe:
PsychColorCorrection('ApplyPostGLSLLinkSetup', win, 'FinalFormatting');
% Test accuracy/correctness of GPU's rasterizer for different output
% positioning methods: Return (non-zero) dx,dy offsets, if any:
[rpfx, rpfy, rpix] = PsychGPURasterizerOffsets(win, drivername); %#ok<ASGLU>
if rpix~=0
tlockXOffset = -rpix;
fprintf('%s: Applying corrective horizontal T-Lock offset of %i pixels for buggy graphics card driver. Will hopefully fix it...\n', drivername, tlockXOffset);
end
if targetdevicetype == 1 && checkGPUEncoders
% Perform DataPixx builtin diagnostics to detect problems with
% wrong GPU gamma tables or GPU dithering:
checkGPUEncoders = 0;
if PsychDataPixx('CheckGPUSanity', win, tlockXOffset)
% Ohoh, trouble ahead! The driver detected problems with the
% GPU and wasn't able to auto-correct them.
fprintf('%s: CAUTION! DataPixx internal diagnostic detected problems with your graphics card driver which it could not correct by itself!\n', drivername);
end
end
if targetdevicetype == 0 && checkGPUEncoders
% Perform Bits# builtin diagnostics to detect problems with
% wrong GPU gamma tables or GPU dithering:
checkGPUEncoders = 0;
if doCheckGPUSanity(win, tlockXOffset, bitsSharpPort)
% Ohoh, trouble ahead! The driver detected problems with the
% GPU and wasn't able to auto-correct them.
fprintf('%s: CAUTION! Bits# internal diagnostic detected problems with your graphics card driver which it could not correct by itself!\n', drivername);
end
end
% Connection to Bits# established?
if ~isempty(bitsSharpPort)
% Yes. Switch it to target display mode:
IOPort('Write', bitsSharpPort, targetMode);
fprintf('BitsPlusPlus: Switching Bits# device to %s video mode. Will take about 5 seconds...\n', targetModeName);
% Wait 5 seconds. In the worst case, if the diagnostic/status screen on Bits# was
% active, the video mode switch can take that long to stabilize:
WaitSecs('YieldSecs', 5);
end
% Enable framebuffer output formatter: From this point on, all visual
% output will be reformatted to Bits++ framebuffer format at each
% invokation of Screen('DrawingFinished') or Screen('Flip'), whatever
% comes first.
Screen('HookFunction', win, 'Enable', 'FinalOutputFormattingBlit');
% When using the overlay, we need to allow for CLUT updates as well, so
% usercode can define and change overlay colors:
if useOverlay
% Now enable finalizer hook chains and load them with the special Bits++
% command for T-Lock based Bits++ internal CLUT updates:
if tlockXOffset ~= 0
offsetstring = sprintf('xPosition=%i', tlockXOffset);
else
offsetstring = '';
end
if targetdevicetype == 0
Screen('HookFunction', win, 'PrependBuiltin', 'LeftFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
if targetdevicetype == 1
rclutcmd = 'PsychDataPixx(1, IMAGINGPIPE_GAMMATABLE);';
Screen('HookFunction', win, 'PrependMFunction', 'LeftFinalizerBlitChain', 'Upload new clut into DataPixx callback', rclutcmd);
end
Screen('HookFunction', win, 'Enable', 'LeftFinalizerBlitChain');
if ~isempty(stereomode) && ismember(stereomode, [1, 4, 5, 10, 11])
% Enable CLUT updates on right stereo buffer as well:
% CRS devices, frame-sequential stereo or native quad-buffered OpenGL stereo,
% or dual-window stereo (mostly for OSX dual-display):
if targetdevicetype == 0 && ismember(stereomode, [1, 10, 11])
Screen('HookFunction', win, 'PrependBuiltin', 'RightFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
% Dual CRS devices, dual-display stereo on Linux or Windows:
if targetdevicetype == 0 && ismember(stereomode, [4, 5]) && dualdevices == 1
% Here one PTB window drives both video outputs (split-window style) and
% thereby both connected CRS devices. In order to set a CLUT on both of
% these devices, we need to blit the Clut T-Lock into the right half of
% our window as well. However, we use the LeftFinalizerBlitChain for this,
% as the RightFinalizerBlitChain is not operational in stereomode 4 and 5:
offsetstring = sprintf('xPosition=%i', tlockXOffset + Screen('WindowSize', win, 1) / 2);
Screen('HookFunction', win, 'PrependBuiltin', 'LeftFinalizerBlitChain', 'Builtin:RenderClutBits++', offsetstring);
end
% VPixx devices, frame-sequential stereo or native quad-buffered OpenGL stereo:
if targetdevicetype == 1 && ismember(stereomode, [1, 11])
Screen('HookFunction', win, 'PrependMFunction', 'RightFinalizerBlitChain', 'Upload new clut into DataPixx callback', rclutcmd);
end
Screen('HookFunction', win, 'Enable', 'RightFinalizerBlitChain');
end
% Load an identity CLUT into the Bits++ to start with:
linear_lut = repmat(linspace(0, 1, 256)', 1, 3);
Screen('LoadNormalizedGammaTable', win, linear_lut, 2);
end
if targetdevicetype == 0
% Setup finalizer callback for DIO T-Lock updates:
tlockhandle = SetupDIOFinalizer(win, stereomode);
end
% Restore old graphics preferences:
Screen('Preference', 'Enable3DGraphics', ogl);
% Set color range to 0.0 - 1.0: This makes more sense than the normal
% 0-255 values. Try to disable color clamping. This may fail and
% produce a PTB warning, but if it succeeds then we're better off for
% the 2D drawing commands...
Screen('ColorRange', win, 1, 0);
% Set Screen background clear color, in normalized 0.0 - 1.0 range:
if (max(clearcolor) > 1) && (all(round(clearcolor) == clearcolor))
% Looks like someone's feeding old style 0-255 integer values as
% clearcolor. Output a warning to tell about the expected 0.0 - 1.0
% range of values:
warning(sprintf('\n\n%s: You specified a ''clearcolor'' argument for the OpenWindow command that looks \nlike an old 0-255 value instead of the wanted value in the 0.0-1.0 range. Please update your code for correct behaviour.', drivername)); %#ok<WNTAG,SPWRN>
end
% Set the background clear color via old fullscreen 'FillRect' trick,
% followed by a flip:
Screen('FillRect', win, clearcolor);
Screen('Flip', win);
% Check validation:
if ~validated
% Validate imaging / display pipeline:
% From usercode drawing commands to framebuffer...
ValidateBitsPlusImaging(win, 0, devname, 1);
% ... and from framebuffer to display device:
ValidateBitsPlusImaging(win, 0, devname, 2);
end
% Reset validation flag after first run:
validated = 0;
% Reset colorConversionMode after opening the window. It is a one-shot
% parameter, but not before storing a cached copy in the per-window
% vector:
if ~isempty(colorConversionMode)
colorConversionModeWin(win) = colorConversionMode;
else
colorConversionModeWin(win) = -1;
end
colorConversionMode = [];
% Ready!
return;
end
if strcmpi(cmd, 'GetOverlayWindow')
% Assign onscreen window index:
if nargin < 2 || isempty(arg) || ~isa(arg, 'double')
error('%s: "GetOverlayWindow" called without valid onscreen window handle.', drivername);
end
win = arg;
if win < 1 || win > length(OverlayWindows)
error('%s: "GetOverlayWindow": No overlay associated with given onscreen window.', drivername);
end
if OverlayWindows(win) == 0
error('%s: "GetOverlayWindow": No overlay associated with given onscreen window.', drivername);
end
% Ok, this 'win'dow has an overlay: Return its offscreen 'win'dow handle:
win = OverlayWindows(win);
% And the defining rectangle of the overlay:
winRect = Screen('Rect', win);
return;
end
if strcmpi(cmd, 'CheckGPUSanity')
if length(varargin) < 1 || isempty(varargin{1})
injectFault = 0;
else
injectFault = varargin{1};
end
win = doCheckGPUSanity(arg, dummy, bitsSharpPort, injectFault);
return;
end
if strcmpi(cmd, 'UseFE1StereoGoggles')
% Assign onscreen window index:
if nargin < 2 || isempty(arg) || ~isa(arg, 'double') || Screen('WindowKind', arg) ~= 1
error('%s: "UseFE1StereoGoggles" called without valid onscreen window handle.', drivername);
end
win = arg;
winfo = Screen('GetWindowInfo', win);
if ~ismember(winfo.StereoMode, [1,11])
% No frame-sequential mode, no point in having sync lines -> No operation.
fprintf('UseFE1StereoGoggles: Info: Provided onscreen window is not switched to frame-sequential stereo mode. Call ignored.\n');
return;
end
if nargin < 3 || isempty(dummy) || ~ismember(dummy, [0, 1])
error('%s: "UseFE1StereoGoggles" called without valid enable flag.', drivername);
end
enableIt = dummy;
% Disable instead of enable requested?
if ~enableIt
% Existing hookslots found?
lslot = Screen('HookFunction', win, 'Query', 'LeftFinalizerBlitChain', 'RenderStereoFE1LeftTLock');
rslot = Screen('HookFunction', win, 'Query', 'RightFinalizerBlitChain', 'RenderStereoFE1RightTLock');
if (lslot ~= -1) && (rslot ~= -1)
% Yes. Delete them to disable the T-Lock blitting:
Screen('HookFunction', win, 'Remove', 'LeftFinalizerBlitChain' , lslot);
Screen('HookFunction', win, 'Remove', 'RightFinalizerBlitChain', rslot);
end
% Now the T-Lock blitting for frame-sequential stereo is off and
% the shutter goggles are in some unknown state. Set them to
% requested state, which defaults to 0 for "both eyes open":
if nargin < 4 || isempty(varargin{1}) || varargin{1} ~= 1
shutterState = 0;
else
shutterState = 1;
end
% Schedule T-Lock for setting final shutter state at next flip:
[encodedDIOdata, Mask, Data, Command] = bitsGoggles(shutterState, shutterState);
BitsPlusPlus('DIOCommand', win, 1, Mask, Data, Command);
% Execute!
Screen('Flip', win);
% Ok, shutter glasses should be open, we are done.
return;
end
% Enable case - Do the setup dance:
% Build display list for left-eye image T-Lock:
displist = glGenLists(1);
glNewList(displist, GL.COMPILE);
% Generate DIO T-Lock image as Matlab matrix to open the
% right shutter at the end of scanout of the left stereo image:
tlockdata = bitsGoggles(1, 0);
% Convert from Matlab matrix to OpenGL pixel format:
encodedDIOdata = uint8(zeros(3, 508));
% Pack 3 separate RGB planes into rows 1,2,3. As Matlabs data format is
% column major order, this will end up as tightly packed pixel array in
% format RGBRGBRGB.... just as glDrawPixels likes it.
encodedDIOdata(1,:) = tlockdata(1,:,1);
encodedDIOdata(2,:) = tlockdata(1,:,2);
encodedDIOdata(3,:) = tlockdata(1,:,3);
% Place T-Lock at start position (0, display height - 1):
[xDIO, yDIO] = Screen('WindowSize', win, 1);
yDIO = yDIO - 1;
% Add command sequence for this T-Lock code to display list:
glRasterPos2i(tlockXOffset, yDIO);
glDrawPixels(508, 1, GL.RGB, GL.UNSIGNED_BYTE, encodedDIOdata);
% Finish left display list;
glEndList;
pStringLeft = sprintf('glCallList(%i);', displist);
% Build display list for right-eye image T-Lock:
displist = glGenLists(1);
glNewList(displist, GL.COMPILE);
% Generate DIO T-Lock image as Matlab matrix to open the
% left shutter at the end of scanout of the right stereo image:
tlockdata = bitsGoggles(0, 1);
% Convert from Matlab matrix to OpenGL pixel format:
encodedDIOdata = uint8(zeros(3, 508));
% Pack 3 separate RGB planes into rows 1,2,3. As Matlabs data format is
% column major order, this will end up as tightly packed pixel array in
% format RGBRGBRGB.... just as glDrawPixels likes it.
encodedDIOdata(1,:) = tlockdata(1,:,1);
encodedDIOdata(2,:) = tlockdata(1,:,2);
encodedDIOdata(3,:) = tlockdata(1,:,3);
% Place T-Lock at start position (0, display height - 1):
[xDIO, yDIO] = Screen('WindowSize', win, 1);
yDIO = yDIO - 1;
% Add command sequence for this T-Lock code to display list:
glRasterPos2i(tlockXOffset, yDIO);
glDrawPixels(508, 1, GL.RGB, GL.UNSIGNED_BYTE, encodedDIOdata);
% Finish left display list;
glEndList;
pStringRight = sprintf('glCallList(%i);', displist);
% Ok 'win'dowhandle is fine. Any blue line sync function already applied?
lslot = Screen('HookFunction', win, 'Query', 'LeftFinalizerBlitChain', 'Builtin:RenderStereoSyncLine');
rslot = Screen('HookFunction', win, 'Query', 'RightFinalizerBlitChain', 'Builtin:RenderStereoSyncLine');
% Existing hookslots found?
if (lslot ~= -1) && (rslot ~= -1)
% Yes. Need to recreate with T-Lock for FE1 instead of standard blue-line sync lines:
% Destroy old ones:
Screen('HookFunction', win, 'Remove', 'LeftFinalizerBlitChain' , lslot);
Screen('HookFunction', win, 'Remove', 'RightFinalizerBlitChain', rslot);
% Insert new slots at former position of the old ones:
posstring = sprintf('InsertAt%iMFunction', lslot);
Screen('Hookfunction', win, posstring, 'LeftFinalizerBlitChain', 'RenderStereoFE1LeftTLock', pStringLeft);
posstring = sprintf('InsertAt%iMFunction', rslot);
Screen('Hookfunction', win, posstring, 'RightFinalizerBlitChain', 'RenderStereoFE1RightTLock', pStringRight);
else
% No. Create new slots at end:
Screen('Hookfunction', win, 'AppendMFunction', 'LeftFinalizerBlitChain', 'RenderStereoFE1LeftTLock', pStringLeft);
Screen('Hookfunction', win, 'AppendMFunction', 'RightFinalizerBlitChain', 'RenderStereoFE1RightTLock', pStringRight);
end
fprintf('UseFE1StereoGoggles: Info: Enabling automatic generation of sync signals for external FE1 shutter glasses.\n');
% Enable finalizer hookchains, if not already enabled:
Screen('HookFunction', win, 'Enable', 'LeftFinalizerBlitChain');
Screen('HookFunction', win, 'Enable', 'RightFinalizerBlitChain');
return;
end
error('%s: Unknown subcommand provided. Read "help BitsPlusPlus".', drivername);
end
% Helper function: Check if system already validated for current settings:
function ValidateBitsPlusImaging(win, writefile, devname, validationType)
% Compute fingerprint of this system configuration:
validated = 0;
global GL;
screenid = Screen('WindowScreenNumber', win);
[w, h] = Screen('WindowSize', screenid);
d = Screen('PixelSize', win);
v = Screen('Version');
v = v.version;
c = Screen('Computer');
if IsLinux || IsOSX
c = c.kern.version;
else
c = c.system;
end
gfxconfig = [ glGetString(GL.VENDOR) ':' glGetString(GL.RENDERER) ':' glGetString(GL.VERSION) ];
gfxconfig = sprintf('VTYPE %i : %s : Screen %i : Resolution %i x %i x %i : ScreenVersion = %s : System = %s', validationType, gfxconfig, screenid, w, h, d, v, c);
if ~writefile
% Check if a validation file exists and if it contains this
% configuration:
fid = fopen([PsychtoolboxConfigDir 'ptbbitsplusplusvalidationfile.txt'], 'r');
if fid~=-1
while ~feof(fid)
vconf = fgetl(fid);
if strcmp(vconf, gfxconfig)
validated = 1;
break;
end
end
fclose(fid);
end
if ~validated
fprintf('\n\n------------------------------------------------------------------------------------------------------------------\n')
fprintf('\n\nThis specific configuration of graphics hardware, graphics driver and Psychtoolbox version has not yet been tested\n');
fprintf('for correct working with %s for the given display screen, screen resolution and color depths.\n\n', devname);
if validationType == 1
fprintf('Please run the test script "BitsPlusImagingPipelineTest(%i);" once, so this configuration can be verified.\n', Screen('WindowScreenNumber', win));
else
if ~isempty(strfind(devname, 'Pixx'))
fprintf('Please run the test script "BitsPlusIdentityClutTest(%i, 1);" once, so this configuration can be verified.\n', Screen('WindowScreenNumber', win));
fprintf('Alternatively "BitsPlusIdentityClutTest(%i, 1, [], 1);" can be used for verification in L48 mode.\n', Screen('WindowScreenNumber', win));
else
fprintf('Please run the test script "BitsPlusIdentityClutTest(%i);" once, so this configuration can be verified.\n', Screen('WindowScreenNumber', win));
fprintf('Alternatively "BitsPlusIdentityClutTest(%i, 0, [], 1);" can be used for verification in Bits++ mode.\n', Screen('WindowScreenNumber', win));
end
end
fprintf('After that test script suceeded, re-run your experiment script.\nThanks.\n');
fprintf('\n');
fprintf('Configuration to verify: %s\n', gfxconfig);
RestoreCluts;
sca; ShowCursor; Priority(0);
% Perform device shutdown for display device:
if ~isempty(strfind(devname, 'Pixx'))
PsychDataPixx('ResetOnWindowClose');
else
BitsPlusPlus('ResetOnWindowClose');
end
error('Configuration not yet verified. Please do it now.');
end
end
if writefile
% Append current configuration to file to mark it as verified:
[fid msg]= fopen([PsychtoolboxConfigDir 'ptbbitsplusplusvalidationfile.txt'], 'a');
if fid == -1
RestoreCluts;
sca;
error('Could not write validation file %s to filesystem [%s].', [PsychtoolboxConfigDir 'ptbbitsplusplusvalidationfile.txt'], msg);
end
% Append line:
fprintf(fid, [gfxconfig '\n']);
fclose(fid);
end
end
% Helper function for setup of finalizer blit chains in all modes. Sets up
% callback into our file for T-Lock drawing etc...
function displist = SetupDIOFinalizer(win, stereomode)
% Generate unique display list handle for later use:
displist = glGenLists(1);
% Now enable finalizer hook chains and load them with the special Bits++
% command for T-Lock based Bits++ DIO updates:
Screen('HookFunction', win, 'PrependMFunction', 'LeftFinalizerBlitChain', 'Render T-Lock DIO data callback', 'BitsPlusPlus(1);');
Screen('HookFunction', win, 'Enable', 'LeftFinalizerBlitChain');
if ~isempty(stereomode) && ismember(stereomode, [1, 11])
% This is only needed on quad-buffered stereo contexts.
Screen('HookFunction', win, 'PrependMFunction', 'RightFinalizerBlitChain', 'Render T-Lock DIO data callback', 'BitsPlusPlus(1);');
Screen('HookFunction', win, 'Enable', 'RightFinalizerBlitChain');
end
end
function scanline = BitsSharpGetScanline(bitsSharpPort, lineNr, nrPixels)
% Emit request for video scanline to Bits#
IOPort('Write', bitsSharpPort, [sprintf('$GetVideoLine=[%i,%i]', lineNr, nrPixels) char(13)]);
IOPort('Flush', bitsSharpPort);
% First we do a blocking read for the minimum number of bytes expected, which is the
% length of the header in chars + at least 3 chars per pixel (format 00; 01; 02; ... 99;):
rawline = IOPort('Read', bitsSharpPort, 1, length('#GetVideoLine;') + nrPixels * 3);
% Then we iterate over non-blocking reads until we find the end-of-date terminator code 13:
while ~isempty(rawline) && (rawline(end) ~= 13)
WaitSecs('YieldSecs', 0.001);
rawline = [rawline IOPort('Read', bitsSharpPort)]; %#ok<AGROW>
end
% Cut away header:
rawline = rawline(length('#GetVideoLine;')+1:end);
if isempty(rawline)
warning('BitsSharpGetScanline: Empty pixelline returned!'); %#ok<WNTAG>
scanline = [];
return;
end
% Convert into integer array:
rawline = char(rawline);
rawline(rawline == ';') = ' ';
scanline = sscanf(rawline, '%d');
if (length(scanline) ~= 3 * nrPixels)
warning('BitsSharpGetScanline: Incomplete pixelline %s with only %i elements (less than %i) returned!', rawline, length(scanline), 3 * nrPixels); %#ok<WNTAG>
scanline = [];
else
scanline = uint8(reshape(scanline, 3, nrPixels));
end
return;
end
function rc = doCheckGPUSanity(win, xoffset, bitsSharpPort, injectFault)
% If this isn't a connected Bits#, simply no-op with success return code:
if isempty(bitsSharpPort)
rc = 0;
return;
end
if nargin < 4 || isempty(injectFault)
injectFault = 0;
end
% Execute test and optimization (tweaking) procedure which uses
% onscreen window 'win' for sending test stimuli to the Bits# device,
% and use the builtin measurement functions of that device to drive
% the tweaking procedure. Return success status, 0 = Success, 1 = Failure.
rc = PsychGPUTestAndTweakGammaTables(win, xoffset, 1, injectFault, bitsSharpPort);
return;
end