movieStimulus Class Reference

movieStimulus is the class for movie based stimulus objects More...

Detailed Description

movieStimulus is the class for movie based stimulus objects

Copyright ©2014-2022 Ian Max Andolina — released: LGPL3, see LICENCE.md

Inheritance diagram for movieStimulus:

Public Member Functions
function	movieStimulus (in varargin)
	Class constructor.
function	setup (in me, in sM)
	Setup this object in preperation for use When displaying a stimulus object, the main properties that are to be modified are copied into cache copies of the property, both to convert from user-friendly visual description (c/d, Hz, degrees) to computer pixels metrics; and to be animated and modified as independant variables. So xPosition is copied to xPositionOut and converted from degrees to pixels. The animation and drawing functions use these modified properties, and when they are updated, for example to change to a new xPosition, internal methods ensure reconversion and update any dependent properties. This method initialises the object in preperation for display.
function	set_xPositionOut (in me, in value)
function	set_yPositionOut (in me, in value)
function	update (in me)
	Update this stimulus object structure for screenManager.
function	updatePositions (in me, in x, in y)
	Update only position info with pixels, faster and doesn't reset movie.
function	draw (in me)
	Draw this stimulus object.
function	animate (in me)
	Animate an structure for screenManager.
function	reset (in me)
	Reset an structure for screenManager.
function	findFile (in me, in dir)
	find a file or directory
Public Member Functions inherited from baseStimulus
virtual	setup (in runObject)
	ALL Children must implement these 5 methods!
function	baseStimulus (in varargin)
	Class constructor.
function set	colour (in me, in value)
	colour set method Allow 1 (R=G=B) 3 (RGB) or 4 (RGBA) value colour
function set	alpha (in me, in value)
	alpha set method
function get	delta (in me)
	delta Get method delta is the normalised number of pixels per frame to move a stimulus
function get	dX (in me)
	dX Get method X position increment for a given delta and angle
function get	dY (in me)
	dY Get method Y position increment for a given delta and angle
function	show (in me)
	Method to set isVisible=true.
function	hide (in me)
	Method to set isVisible=false.
function	setOffTime (in me, in time)
	set offTime
function	setDelayTime (in me, in time)
	set delayTime
function	resetTicks (in me)
	reset the various tick counters for our stimulus
function	getMousePosition (in me)
	get mouse position we make sure this is only called once per animation tick to improve performance and ensure all stimuli that are following mouse position have consistent X and Y per frame update This sets mouseX and mouseY and mouseValid if mouse is within PTB screen (useful for mouse override positioning for stimuli)
function	run (in me, in benchmark, in runtime, in s, in forceScreen, in showVBL)
	Run stimulus in a window to preview it.
function	makePanel (in me, in parent)
	make a GUI properties panel for this object
function	selectFilePanel (in me, in varargin)
	read values from a GUI properties panel for this object
function	readPanel (in me, in varargin)
	read values from a GUI properties panel for this object
function	showPanel (in me)
	show GUI properties panel for this object
function	hidePanel (in me)
	hide GUI properties panel for this object
function	closePanel (in me, in varargin)
	close GUI panel for this object
function	cleanHandles (in me, in ignoredArg)
	clean any handles
function	getP (in me, in name, in range)
	gets a property copy or original property
function	setP (in me, in name, in value)
	sets a property copy or original property
function	updateXY (in me, in x, in y, in useDegrees)
	Update only position info, faster and doesn't reset image etc.
Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.
function get	fullName (in me)
function	getALF (in me, in subject, in sessionPrefix, in lab, in create)
function	findAttributes (in me, in attrName, in attrValue)
function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.
function	findPropertyDefault (in me, in propName)
function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.
function	checkSuperclasses (in List)
function	editProperties (in me, in properties)
	method to modify a set of properties
function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.
function	initialiseGlobals (in me, in doReset, in doOpen)
function	initialiseSaveFile (in me)
	Initialise Save prefix.
function	checkPaths (in me)
	checks the paths are valid

Public Attributes
Property	type
Property	direction
Property	lockAngle
Property	filePath
	the name / path of a file or folder, if empty a default will be used
Property	selection
Property	blocking
Property	pixelFormat
Property	preloadSecs
	how many seconds to preload, -1 tries all
Property	specialFlagsOpen
Property	specialFlagsFrame
Property	specialFlags2Frame
Property	loopStrategy
	how to handle looping (1=PTB default)
Property	mask
	mask out a colour? e.g. [0 0 0]
Property	maskTolerance
	mask tolerance
Property	enforceBlending
	if movie has transparency, enforce opengl blending?
Property	filePaths
	list of imagenames if selection > 0
Property	nVideos
	number of videos
Property	currentFile
	current randomly selected movie
Property	scale
	scale is dependent on stimulus size and movie width
Property	family
Property	movie
	handle from OpenMovie
Property	duration
	details
Property	fps
Property	width
Property	height
Property	count
Property	typeList
Property	filePathList
Property	buffertex
Property	shader
	shader for masking
Property	ignorePropertiesUI
	properties to not show in the UI panel
Public Attributes inherited from baseStimulus
Property	type
	stimulus type
Property	xPosition
Property	yPosition
Property	size
Property	colour
Property	alpha
	Alpha (opacity) [0-1], this gets combined with the RGB colour.
Property	startPosition
Property	speed
Property	angle
	angle in degrees (0 - 360)
Property	delayTime
Property	offTime
	time to turn stimulus off, relative to stimulus onset
Property	isVisible
	true or false, whether to draw() this object
Property	mouseOverride
	override X and Y position with mouse input? Useful for RF mapping
Property	showOnTracker
	show the position on the Eyetracker display?
Property	verbose
	Do we log extra details to the command-line?
Property	xFinal
Property	yFinal
Property	mvRect
Property	szIsPx
Property	szPx
	computed size in pixels
Property	szD
	computed size in °
Property	xFinalD
	X and Y position in °
Property	yFinalD
Property	isRect
Property	tick
	tick updates +1 on each call of draw (even if delay or off is true and no stimulus is drawn, resets on each update
Property	drawTick
	draw tick only updates when a draw is actually performed, resets on each update
Property	ppd
	pixels per degree (normally inhereted from screenManager)
Property	delta
	What our per-frame motion delta is.
Property	dX
	X update which is computed from our speed and angle.
Property	dY
	X update which is computed from our speed and angle.
Public Attributes inherited from optickaCore
Property	name
	object name
Property	comment
	comment
Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false
Property	dateStamp
	clock() dateStamp set on construction
Property	uuid
	universal ID
Property	paths
	storage of various paths
Property	fullName
	The fullName is the object name combined with its uuid and class name.

Protected Member Functions
function	loadMovie (in me)
	loadMovie
function	setRect (in me)
	setRect setRect makes the PsychRect based on the texture and screen values This is overridden from parent class so we can scale texture using the size value
function	checkfilePath (in me)
function	findFiles (in me)
	findFiles
Protected Member Functions inherited from baseStimulus
function	addRuntimeProperties (in me)
	These are transient properties that specify actions during runtime.
function	updateRuntimeProperties (in me)
	Update transient properties that specify actions during runtime.
function	computePosition (in me)
	compute xFinal and yFinal (in pixels) taking startPosition, xPosition, yPosition and direction/angle into account
function	setAnimationDelta (in me)
function	setRect (in me)
function	toStructure (in me, in tmp)
	Converts properties to a structure.
function	removeTmpProperties (in me)
	Finds and removes dynamic properties.
function	delete (in me)
Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	addArgs (in me, in args)
function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	getFonts (in me)
	set paths for object
function	toStructure (in me)
	Converts properties to a structure.
function	getType (in me, in in)
function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.
function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.

Protected Attributes
Property	thisMovie
Property	msrcMode
Property	mdstMode
Property	allowedProperties
	allowed properties passed to object upon construction
Property	ignoreProperties
	properties to not create transient copies of during setup phase
Protected Attributes inherited from baseStimulus
Property	family
	the stimulus family (grating, dots etc.)
Property	texture
	Our texture pointer for texture-based stimuli.
Property	handles
	handles for the GUI
Property	sM
	our screen manager
Property	animator
	animation manager
Property	screenVals
	screen settings generated by sM on setup
Property	isSetup
Property	isGUI
	is panel constructed?
Property	dstRect
	initial screen rectangle position [LEFT TOP RIGHT BOTTOM]
Property	mouseValid
	is mouse position within screen co-ordinates?
Property	mouseX
	mouse X position
Property	mouseY
	mouse Y position
Property	delayTicks
	delay ticks to wait until display
Property	offTicks
	ticks before stimulus turns off
Property	inSetup
	are we setting up?
Property	delta_
	delta cache
Property	dX_
	dX cache
Property	dY_
	dY cache
Property	isInSetColour
	deal with interaction of colour and alpha
Property	setLoop
Property	ignorePropertiesBase
	Which properties to ignore cloning when making transient copies in setup.
Property	ignorePropertiesUIBase
	Which properties to not draw in the UI panel.
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object
Property	mversion
	Matlab version number, this is transient so it is not saved.
Property	sansFont
	sans font
Property	monoFont
	monoFont
Property	className
	class name
Property	savePrefix
	save prefix generated from clock time
Property	fullName_
	cached full name

Additional Inherited Members
Public Types inherited from baseStimulus
enum	Events { readPanelUpdate }
Static Public Member Functions inherited from baseStimulus
static function	d2r (in degrees)
	degrees2radians
static function	r2d (in r)
	radians2degrees
static function	findDistance (in x1, in y1, in x2, in y2)
	findDistance in X and Y coordinates
static function	updatePosition (in delta, in angle)
	updatePosition returns dX and dY given an angle and delta
Static Public Member Functions inherited from optickaCore
static function	makeArgs (in args)
	Converts cell args to structure array.
static function	addDefaults (in args, in defs)
	add default options to arg input
static function	hasKey (in in, in key)
	check if a struct / object has a propery / field
static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.

Constructor & Destructor Documentation

movieStimulus()

function movieStimulus::movieStimulus

(

in

varargin

)

Class constructor.

This parses any input values and initialises the object.

Parameters

varargin

are passed as a list of parametoer or a structure of properties which is parsed.

Returns

instance of opticka class.

Member Function Documentation

animate()

function movieStimulus::animate ( in  me )

virtual

Animate an structure for screenManager.

Reimplemented from baseStimulus.

checkfilePath()

function movieStimulus::checkfilePath ( in  me )

protected

draw()

function movieStimulus::draw ( in  me )

virtual

Draw this stimulus object.

Reimplemented from baseStimulus.

findFile()

function movieStimulus::findFile	(	in	me,
		in	dir
	)

find a file or directory

findFiles()

function movieStimulus::findFiles ( in  me )

protected

findFiles

loadMovie()

function movieStimulus::loadMovie ( in  me )

protected

loadMovie

reset()

function movieStimulus::reset ( in  me )

virtual

Reset an structure for screenManager.

Reimplemented from baseStimulus.

set_xPositionOut()

function movieStimulus::set_xPositionOut	(	in	me,
		in	value
	)

set_yPositionOut()

function movieStimulus::set_yPositionOut	(	in	me,
		in	value
	)

setRect()

function movieStimulus::setRect ( in  me )

protected

setRect setRect makes the PsychRect based on the texture and screen values This is overridden from parent class so we can scale texture using the size value

setup()

function movieStimulus::setup	(	in	me,
		in	sM
	)

Setup this object in preperation for use When displaying a stimulus object, the main properties that are to be modified are copied into cache copies of the property, both to convert from user-friendly visual description (c/d, Hz, degrees) to computer pixels metrics; and to be animated and modified as independant variables. So xPosition is copied to xPositionOut and converted from degrees to pixels. The animation and drawing functions use these modified properties, and when they are updated, for example to change to a new xPosition, internal methods ensure reconversion and update any dependent properties. This method initialises the object in preperation for display.

Parameters

sM	screenManager object for reference

update()

function movieStimulus::update ( in  me )

virtual

Update this stimulus object structure for screenManager.

Reimplemented from baseStimulus.

updatePositions()

function movieStimulus::updatePositions	(	in	me,
		in	x,
		in	y
	)

Update only position info with pixels, faster and doesn't reset movie.

Member Data Documentation

allowedProperties

Property movieStimulus::allowedProperties

protected

allowed properties passed to object upon construction

blocking

Property movieStimulus::blocking

do we block when getting a frame? This is important, as if it is 1 then you will drop frames waiting for the the synced video frame. Set to 0 this class uses double buffering to keep drawing the previous frame unitl a new frame is ready, ensuring other stimuli animate smoothly alongside the video.

buffertex

Property movieStimulus::buffertex

texture buffer for non-blocking movie playback, this is the previous frame until a new frame is available

count

Property movieStimulus::count

currentFile

Property movieStimulus::currentFile

current randomly selected movie

direction

Property movieStimulus::direction

the direction of the whole object - i.e. the motion direction object can move in (different to the angle).

duration

Property movieStimulus::duration

details

enforceBlending

Property movieStimulus::enforceBlending

if movie has transparency, enforce opengl blending?

family

Property movieStimulus::family

filePath

Property movieStimulus::filePath

the name / path of a file or folder, if empty a default will be used

filePathList

Property movieStimulus::filePathList

filePaths

Property movieStimulus::filePaths

list of imagenames if selection > 0

fps

Property movieStimulus::fps

height

Property movieStimulus::height

ignoreProperties

Property movieStimulus::ignoreProperties

protected

properties to not create transient copies of during setup phase

ignorePropertiesUI

Property movieStimulus::ignorePropertiesUI

properties to not show in the UI panel

lockAngle

Property movieStimulus::lockAngle

do we lock the texture angle to the direction? If so what is the offset (0 = parallel, 90 = orthogonal etc.)

loopStrategy

Property movieStimulus::loopStrategy

how to handle looping (1=PTB default)

mask

Property movieStimulus::mask

mask out a colour? e.g. [0 0 0]

maskTolerance

Property movieStimulus::maskTolerance

mask tolerance

mdstMode

Property movieStimulus::mdstMode

protected

movie

Property movieStimulus::movie

handle from OpenMovie

msrcMode

Property movieStimulus::msrcMode

protected

nVideos

Property movieStimulus::nVideos

number of videos

pixelFormat

Property movieStimulus::pixelFormat

pixel format for opening movie? 6 is more efficient if H264 used. 1 = Luminance/Greyscale image, 2 = Luminance+Alpha, 3 = RGB 8 bit per channel, 4 = RGBA8, 5 = YUV 4:2:2 packed pixel format on some graphics hardware, 6 = YUV-I420 planar format, using GLSL shaders for color space conversion on suitable graphics cards. 7 or 8 = Y8-Y800 planar format, using GLSL shaders, 9 = 16 bit Luminance, 10 = 16 bpc RGBA image

preloadSecs

Property movieStimulus::preloadSecs

how many seconds to preload, -1 tries all

scale

Property movieStimulus::scale

scale is dependent on stimulus size and movie width

selection

Property movieStimulus::selection

selection if N > 0, then this is a number of images from 1:N, e.g. filePath = base.jpg, selection=5, then base1.jpg - base5.jpg update() will randomly select one from this group.

shader

Property movieStimulus::shader

shader for masking

specialFlags2Frame

Property movieStimulus::specialFlags2Frame

special flags for 'GetMovieImage' 1 = don't return any time info (maybe slightly faster?) 2 = don't return any textures, for bechmarking.

specialFlagsFrame

Property movieStimulus::specialFlagsFrame

special flags for 'GetMovieImage' 1 = use GL_TEXTURE_2D 2 = high precision 8 = no mipmap with GL_TEXTURE_2D 32 = prevent closing the texture by a call to Screen('Close')

specialFlagsOpen

Property movieStimulus::specialFlagsOpen

additional special flags, numbers can be added together 1 = Use YUV video decoding instead of RGBA 2 = linux with psychportaudio 4 = draw motion vectors on top of decoded video frames 8 = skip all B-Frames during decoding to reduce processor load on very slow machines 16 = convert all video textures immediately into a format which makes them useable as offscreen windows 32,64,128 = different loop strategies 256 = revent automatic deinterlacing of video 512 = marks the movie as encoded in Psychtoolbox's own proprietary 16 bpc high precision format 1024 = video frames are encoded as raw Bayer sensor data

thisMovie

Property movieStimulus::thisMovie

protected

type

Property movieStimulus::type

typeList

Property movieStimulus::typeList

width

Property movieStimulus::width

---

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

• stimuli/movieStimulus.m