Overview

Singleton to work with the OpenGL drawing context.

dotsTheScreen manages the Snow Dots OpenGL drawing context. "Context" includes the display and window to use for drawing, OpenGL system resources, OpenGL configuration, and state memory, all of which Snow Dots needs in order to draw graphics with OpenGL.

dotsTheMachineConfiguration provides hardware-specific default property values to dotsTheScreen.

Inheritance diagram for dotsTheScreen:

[legend]

Properties and Events
Property	width
	dispay width (cm)

Property	height
	dispay height (cm)

Property	distance
	display viewing distance (cm)

Property	displayIndex
	index of display on which to open drawing windows More...

Property	displayPixels
	rectangle representing the entire display (pixels, [0 0 w h])

Property	bitDepth
	color depth of each pixel (number of bits)

Property	multisample
	whether or not to use OpenGL full-scene antialiasing

Property	windowRect
	pixel dimensions of the current drawing window [x y x2 y2]

Property	windowFrameRate
	Hz frame rate of the current drawing window.

Property	pixelsPerDegree
	approximate conversion factor for the current display

Property	foregroundColor
	a foreground color, [L] [LA] [RGB] [RGBA], 0-255

Property	backgroundColor = [0 0 0]
	a background color, [L] [LA] [RGB] [RGBA], 0-255

Property	clockFunction
	function that returns the current time as a number

Property	gammaTableFileName
	filename with path to .mat file that contains a gamma table

Property	newGammaTable
	newly loaded color calibration

Properties and Events inherited from dotsAllSingletonObjects
null	obj = theObject(varargin)
	Return the current class instance from the private constructor.

null	g = gui()
	Launch a grapical interface for the current instance.

Protected Properties
Property	flushGauge
	utility object to account for OpenGL frame timing

Property	lastFrameInfo
	onset data from the last frame

Property	systemGammaTable
	color calibration that was in the video card at startup (nx3)

Property	offsetTime =0
	for clock synchronization

Property	isRemoteFlag = false
	To check for remote mode.

Property	isOpenFlag = false
	Screen is open.

Methods
	initialize (self)
	Return the current instance to a fresh state, closing the window.

	open (self)
	Open an OpenGL drawing window.

	close (self)
	Close the OpenGL drawing window.

frameInfo	nextFrame (self, doClear)
	Flush OpenGL drawing commands and swap OpenGL frame buffers. More...

time	getCurrentTime (self)
	Gets the current time.

frameInfo	blank (self, backgroundColor)
	Swap OpenGL frame buffers twice without drawing. More...

	saveGammaTableToMatFile (self, fileName)
	Save gamma-correction data in newGammaTable to a .mat file. More...

	readGammaTableFromMatFile (self, fileName)
	Load gamma-correction data from a .mat file into newGammaTable. More...

Methods inherited from dotsAllSingletonObjects
null	reset (varargin)
	Restore a fresh state without deleting the current instance.

null	initialize (self)
	Restore a fresh state without deleting the current object, used by constructor and reset(). More...

	initializeLists (self, listNames)
	Create or refresh topsGroupedList instances.

	set (self, varargin)
	Set multiple properties.

Static Methods
static obj	theObject (varargin)
	Access the current instance of the object.

static isOpenFlag	isOpen ()
	Check if screen is open.

static ensemble	theEnsemble (remoteDrawing, displayIndex, varargin)
	Utility for creating or retrieving a screen ensemble, which is created either as a (local) topsEnsemble or for remote drawing using dotsClientEnsemble with default network values. More...

static	reset (varargin)
	Restore the current instance to a fresh state.

static g	gui ()
	Launch a graphical interface to view dotsTheScreen properties.

static gammaTableFileName	getHostGammaTableFilename ()
	Get a filename suitable for storing a machine-specific gamma table. More...

static displayNumber	getDisplayNumber ()
	Get the number of the display used for drawing. More...

static	openWindow ()
	Open an OpenGL drawing window.

static	closeWindow ()
	Close the OpenGL drawing window.

static gammaTable values	makeGammaTable (doTest, fileName, tableSize, targetSize)
	Makes a gamma table using the optiCAL device from Cambridge Research Systems. More...

static	openScreen (remoteDrawing, displayIndex, varargin)
	Conventient routine to open a screen.

static	closeScreen ()
	Conventient routine to close a screen.

static frameInfo	blankScreen (varargin)
	Convenient routine to blank the current screen, even if remote. More...

static	setSyncTimes (offsetTime, referenceTime)
	Save current screen offset time.

static offsetTime referenceTime	getSyncTimes ()
	Get current screen offset time.

Private Methods
self	dotsTheScreen (varargin)
	Constructor is private. More...

Constructor

◆ dotsTheScreen()

self dotsTheScreen ( varargin )

private

Constructor is private.

Use dotsTheScreen.theObject to access the current instance.

Methods

◆ nextFrame()

frameInfo nextFrame	(	self	,
		doClear
	)

Flush OpenGL drawing commands and swap OpenGL frame buffers.

Parameters

doClear whether or not clear the frame buffer after displaying it

Flushes any recent drawing commands throught OpenGL rendering pipeline, then calls for a frame buffer swap. This will cause the recently drawn frame to appear on-screen.

If doClear is true (default), sends a frame buffer clear command immediately after the swap command. This will cause new future frames to start out as clear. Use doClear = false to let drawings accumulate or "pile up" frame after frame.

Returns a struct with frame timing data obtained from flushGauge. The struct has fields:

onsetTime: estimated onset time for this frame, which might be a time in the future
onsetFrame: number of frames elapsed between open() and this frame
swapTime: estimated time of the last video hardware refresh (e.g. "vertical blank"), which is alwasy a time in the past
isTight: whether this frame and the previous frame were adjacent (false if a frame was skipped)

Assigns the same struct to lastFrameInfo.

◆ blank()

frameInfo blank	(	self	,
		backgroundColor
	)

Swap OpenGL frame buffers twice without drawing.

Calls for a clear of both OpenGL frame buffers as well as two frames buffer swaps. This will cause any previous drawing commands to be processed but not shown, and the screen to turn blank. Returns a struct with frame timing data obtained from flushGauge, for the first flush. The struct has fields:

onsetTime: estimated onset time for this frame, which might be a time in the future
onsetFrame: number of frames elapsed between open() and this frame
swapTime: estimated time of the last video hardware refresh (e.g. "vertical blank"), which is alwasy a time in the past
isTight: whether this frame and the previous frame were adjacent (false if a frame was skipped)

Assigns the same struct to lastFrameInfo.

◆ saveGammaTableToMatFile()

saveGammaTableToMatFile	(	self	,
		fileName
	)

Save gamma-correction data in newGammaTable to a .mat file.

Argument: fileName ... optional. If empty uses default from setHostGammaTableFileName.

◆ readGammaTableFromMatFile()

readGammaTableFromMatFile	(	self	,
		fileName
	)

Load gamma-correction data from a .mat file into newGammaTable.

Argument: fileName ... optional. If empty uses default from setHostGammaTableFileName. Keywords: 'none' = skip 'make' = call makeGammaTable

◆ theEnsemble()

static ensemble theEnsemble	(	remoteDrawing	,
		displayIndex	,
		varargin
	)

static

Utility for creating or retrieving a screen ensemble, which is created either as a (local) topsEnsemble or for remote drawing using dotsClientEnsemble with default network values.

Aguments (for creating): remoteDrawing ... flag for creating client/server ensembles displayIndex ... 0=debug screen; 1=main screen; 2=2nd screen; etc

◆ getHostGammaTableFilename()

static gammaTableFileName getHostGammaTableFilename ( )

static

Get a filename suitable for storing a machine-specific gamma table.

◆ getDisplayNumber()

static displayNumber getDisplayNumber ( )

static

Get the number of the display used for drawing.

If Snow Dots has an open drawing window, returns a non-negative integer which corresponds to displayIndex. Otherwise, returns -1.

◆ makeGammaTable()

static gammaTable values makeGammaTable	(	doTest	,
		fileName	,
		tableSize	,
		targetSize
	)

static

Makes a gamma table using the optiCAL device from Cambridge Research Systems.

Easist way to call this is: -> dotsTheScreen.makeGammaTable(); If you want to check and plot the results, try this: -> [gammaTable, values] = dotsTheScreen.makeGammaTable(true); -> cla reset; hold on -> plot(values(:,1), values(:,2), 'k.'); % uncorrected -> plot(values(:,1), values(:,3), 'r.'); % corrected Note that this routine will put a file in your current working directory that contains the new gamma table. If you want to keep using this table by default, just make sure that it lives somewhere on your Matlab path. This function assumes that:

the optiCAL device is connected to the host computer using the USB-to-serial device. To check that it is recognized, type 'ls /dev/tty.*' ... if it is connected using the keyspan USB-serial, it should be something like /dev/tty.USA*. Use "instrfind" to find open serial objects. Returns in units of cd/m^2 2. the optiCAL argument (or default) points to the device in the file system

the sensor is suctioned onto the middle of the screen Arguments: doTest ... boolean flag to test gamma after correction fileName ... gammaFileName. [] for default. tableSize ... length of the gamma table targetSize ... diameter of spot to draw on screen, in deg visual angle Returns: gammaTable ... the new gamma table values ... nx3 matrix of [nominal values, measuredValues, correctedValues] (3rd column only if doTest=true)

◆ blankScreen()

static frameInfo blankScreen ( varargin )

static

Convenient routine to blank the current screen, even if remote.

Argument (optional): backgroundColor

Properties and Events

◆ displayIndex

Property displayIndex

index of display on which to open drawing windows

A positive integer is a 1-based index for an attached display, on which to open a full-screen window. 0 calls for a small window centered on the primary display.

The documentation for this class was generated from the following file:

dotsTheScreen.m

Overview

Properties and Events

Protected Properties

Methods

Static Methods

Private Methods

Constructor

◆ dotsTheScreen()

Methods

◆ nextFrame()

◆ blank()

◆ saveGammaTableToMatFile()

◆ readGammaTableFromMatFile()

◆ theEnsemble()

◆ getHostGammaTableFilename()

◆ getDisplayNumber()

◆ makeGammaTable()

◆ blankScreen()

Properties and Events

◆ displayIndex