PEBLObjects - Graphics and Objects¶
This module contains functions for creating and manipulating graphical objects, windows, and visual elements.
AddObject()¶
Adds an object to a parent object (window)
Description:
Adds a widget to a parent window, at the top of the object stack. Once added, the object will be drawn onto the parent last, meaning it will be on top of anything previously added. In general, objects can be added to other objects as well as windows. For example, you can add drawing objects (circles, etc.) to an image to annotate the image and maintain its proper x,y coordinates. Also, if you ‘re-add’ an object that is already on a widget, it will get automatically removed from the window first. This is an easy way to reorder elements on a screen.
AddObject(<obj>, <window>) AddObject(<obj>, <canvas>) AddObject(<obj>, <widget>)
Example:
define Start(p)
{
win <- MakeWindow()
img <- MakeImage("pebl.png")
circ <- Circle(20,20,10,MakeColor("red"),1)
AddObject(circ,img)
AddObject(img,win)
Move(img,100,100)
Draw()
WaitForAnyKeyPress()
}
See Also:
Bezier()¶
Creates bezier curve centered at x,y with relative points
Description:
Creates a smoothed line through the points specified by <xpoints>, <ypoints>. The lists <xpoints> and <ypoints> are adjusted by <x> and <y>, so they should be relative to 0, not the location you want the points to be at. Like other drawn objects, the bezier must then be added to the window to appear. <steps> denotes how smooth the approximation will be.
Usage:
Bezier(<x>,<y>,<xpoints>,<ypoints>,
<steps>,<color>)
Example:
win <- MakeWindow()
#This makes a T
xpoints <- [-10,10,10,20,20,-20,-20,-10]
ypoints <- [-20,-20,40,40,50,50,40,40]
p1 <- Bezier(100,100,xpoints, ypoints,
5, MakeColor("black"))
AddObject(p1,win)
Draw()
See Also:
Circle()¶
Creates circle with radius r centered at position x,y
Description:
Creates a circle for graphing at x,y with radius r. Circles must be added to a parent widget before it can be drawn; it may be added to widgets other than a base window. The properties of circles may be changed by accessing their properties directly, including the FILLED property which makes the object an outline versus a filled shape.
Usage:
Circle(<x>, <y>, <r>,<color>)
Example:
c <- Circle(30,30,20, MakeColor(green))
AddObject(c, win)
Draw()
See Also:
Draw()¶
Redraws a widget and its children
Description:
Redraws the screen or a specific widget.
Usage:
Draw()
Draw(<object>)
See Also:
DrawFor()¶
Description:
Draws a screen or widget, returning after <cycles> refreshes. This function currently does not work as intended in the SDL implementation, because of a lack of control over the refresh blank. It may work in the future.
Usage:
DrawFor( <object>, <cycles>)
See Also:
Ellipse()¶
Creates ellipse with radii rx and ry centered at position x,y
Description:
Creates a ellipse for graphing at x,y with radii rx and ry. Ellipses are only currently definable oriented in horizontal/vertical directions. Ellipses must be added to a parent widget before it can be drawn; it may be added to widgets other than a base window. The properties of ellipses may be changed by accessing their properties directly, including the FILLED property which makes the object an outline versus a filled shape.
Usage:
Ellipse(<x>, <y>, <rx>, <ry>,<color>)
Example:
e <- Ellipse(30,30,20,10, MakeColor(green))
AddObject(e, win)
Draw()
See Also:
GetCursorPosition()¶
Description:
Returns an integer specifying where in a textbox the edit cursor is. The value indicates which character it is on.
Usage:
GetCursorPosition(<textbox>)
See Also:
GetLineBreaks()¶
Description:
This gets linebreaks for a textbox. It is mainly used internally for text rendering/layout, but could be useful in other contexts.
Example:
gWin <- MakeWindow()
obj <- EasyTextbox("test a b c
d e f
g h i j k
l m n o p q r
s t u v",30,30,gWin,22, 40,200)
breaks <- GetLineBreaks(obj)
Print("Number of lines:" + Length(breaks))
GetParent()¶
Description:
This gets parent of a widget.
Example:
gWin <- MakeWindow()
obj <- EasyLabel("test",30,30,gWin,22)
## later
win <- GetParent(obj) ##should be gWin
GetPixelColor()¶
Gets the color of a specified pixel on a widget
Description:
Gets a color object specifying the color of a particular pixel on a widget.
Usage:
color <- GetPixelColor(widget,x,y)
Example:
##Judge brightness of a pixel
img <- MakeImage("test.png")
col <- GetPixelColor(img,20,20)
hsv <- RGBtoHSV(col)
Print(Third(hsv))
See Also:
GetProperty()¶
Returns value of property
Description:
Gets a particular named property of an object. This works for custom or built-in objects. If the property does not exist, a fatal error will be signaled, and so you should check using PropertyExists() if there is any chance the property does not exist.
Example:
obj <- MakeCustomObject("myobject")
obj.taste <- "buttery"
obj.texture <- "creamy"
SetProperty(obj,"flavor","tasty")
list <- GetPropertyList(obj)
loop(i,list)
{
if(PropertyExists(obj,i)
{
Print(i + ": " + GetProperty(obj,i))
}
}
See Also:
GetPropertyList(), PropertyExists(), SetProperty(), MakeCustomObject(), PrintProperties()
GetPropertyList()¶
Gets a list of all the property names of an object
Description:
Gets a list of all of the properties an object has. This works for custom or built-in objects.
Example:
obj <- MakeCustomObject("myobject")
obj.taste <- "buttery"
obj.texture <- "creamy"
SetProperty(obj,"flavor","tasty")
list <- GetPropertyList(obj)
loop(i,list)
{
if(PropertyExists(obj,i)
{
Print(i + ": " + GetProperty(obj,i))
}
}
See Also:
GetProperty(), PropertyExists(), SetProperty() MakeCustomObject(), PrintProperties()
GetSize()¶
Description:
Returns a list of [height, width], specifying the size of the widget. The .width and .height properties can also be used instead of this function
Usage:
GetSize(<widget>)
Example:
image <- MakeImage("stim1.bmp")
xy <- GetSize(image)
x <- Nth(xy, 1)
y <- Nth(xy, 2)
GetText()¶
Returns the text in a textbox or label
Description:
Returns the text stored in a text object (either a textbox or a label). The .text properties can also be used instead of this function.
Usage:
GetText(<widget>)
See Also:
SetCursorPosition(), GetCursorPosition(), SetEditable(), MakeTextBox()
GetVocalResponseTime()¶
A simple voice key
Description:
This is a simple audio amplitude voice key controlled by two parameters ONLY AVAILABLE ON WINDOWS AND LINUX.
Usage:
GetVocalResponseTime(buffer,
timethreshold,
energythreshold)
Example:
buffer <- MakeAudioInputBuffer(5000)
resp0 <- GetVocalResponseTime(buffer,.35, 200)
SaveAudioToWaveFile("output.wav",buffer)
See Also:
Hide()¶
Hides an object
Description:
Makes an object invisible, so it will not be drawn.
Usage:
Hide(<object>)
Example:
window <- MakeWindow()
image1 <- MakeImage("pebl.bmp")
image2 <- MakeImage("pebl.bmp")
AddObject(image1, window)
AddObject(image2, window)
Hide(image1)
Hide(image2)
Draw() # empty screen will be drawn.
Wait(3000)
Show(image2)
Draw() # image2 will appear.
Hide(image2)
Draw() # image2 will disappear.
Wait(1000)
Show(image1)
Draw() # image1 will appear.
See Also:
Line()¶
Creates line starting at x,y and ending at x+dx, y+dy
Description:
Creates a line for graphing at x,y ending at x+dx, y+dy. dx and dy describe the size of the line. Lines must be added to a parent widget before it can be drawn; it may be added to widgets other than a base window. Properties of lines may be accessed and set later.
Usage:
Line(<x>, <y>, <dx>, <dy>, <color>)
Example:
l <- Line(30,30,20,20, MakeColor("green")
AddObject(l, win)
Draw()
See Also:
LoadAudioFile()¶
Load an audio file
Description:
Loads an audio file supported by the ffmpeg library. It is nearly identical to LoadMovie(), but only works for audio files (.ogg, .mp3, .wav, .aiff, .wma, et.). It creates a movie object, which can then be played using PlayMovie() or StartPlayback() functions. Currently, only supported on Windows and Linux. The ffmpeg (http://ffmpeg.org) library supports a wide range of audio formats, including most .wav, .mp3, .ogg, .flac, .aiff, .wma, and others. Currently, there appears to sometimes be playback problems if the audio stream is not stereo, so be sure to convert your audio to stereo. Also, there appears to be some problems with .flac data formats. If you have problems with playback, you should verify that your media file loads with another ffmpeg media player.
Usage:
LoadAudioFile(audiofile)
Example:
movie <- LoadAudioFile("instuctions.mp3")
PrintProperties(inst)
PlayMovie(inst)
PausePlayback(insnt)
See Also:
LoadMovie()¶
Load a movie file
Description:
DOES NOT WORK IN PEBL 2.0+ Loads a movie file using the ffmpeg library. It creates a movie object, which can then be played using PlayMovie() or StartPlayback() functions. Currently, only supported on Windows and Linux. The ffmpeg (http://ffmpeg.org) library supports a wide range of video and audio formats, including most .mpg, .avi, .ogg and .mp3 type formats. Audio-only formats should load and play with LoadMovie, but another function, LoadAudioFile(), has been created for these, as they do not need to be added to a window to work. If you have problems with playback, you should verify that your media file loads with another ffmpeg media player. For technical reasons, a movie MUST be loaded directly onto a window, and not another widget.
Usage:
LoadMovie(movie,window, width, height)
Example:
movie <- LoadMovie("movie.avi",gWin,640,480)
PrintProperties(movie)
Move(movie,20,20)
Draw()
StartPlayback(movie)
Wait(500) #Play 500 ms of the movie.
PausePlayback(movie)
See Also:
LoadAudioFile(), LoadMovie(), PlayMovie(), StartPlayback(), PausePlayback()
LoadSound()¶
Loads a soundfile from the filename, returning a variable that can be played
Description:
Loads a soundfile from <filename>, returning a variable that can be played using the PlayForeground or PlayBackground functions. LoadSound As of PEBL version 2.1, LoadSound will load raw and compressed audio files of various sorts. This includes uncompressed .wav files, .mp3, .ogg, .flac, and .midi files. This is based on the sdl2_mixer library, and so more details about the file formats accepted can be found by examining that library. Examples of using LoadSound are found in demo tests testaudio.pbl When the file gets loaded, it gets automatically transcoded into a stereo 44100-sampling rate audio stream, regardless of its original playback rate. We have reports that in some cases, this can cause some problems, especially if a mono file gets loaded multiple times in an experiment. If you experience playback problems, try converting your audio to stereo 44100 hz and see if it helps.
Usage:
LoadSound(<filename>)
Example:
woof <- LoadSound("dog.wav")
PlayBackground(woof)
Wait(200)
Stop(woof)
PlayForeground(woof)
See Also:
PlayForeground(), PlayBackground(), LoadAudioFile(), LoadMovie()
MakeAudioInputBuffer()¶
Creates a buffer to record audio input
Description:
Creates a sound buffer to use for audio recording or voicekey sound input. It is currently very simple, allowing only to set the duration. By default, it record mono at 44100 hz.
Usage:
MakeAudioInputBuffer(<time-in-ms>)
Example:
buffer <- MakeAudioInputBuffer(5000)
resp0 <- GetVocalResponseTime(buffer,.35, 200)
SaveAudioToWaveFile("output.wav",buffer)
See Also:
MakeCanvas()¶
Creates a blank canvas
Description:
Makes a canvas object <x> pixels by y pixels, in color <color>. A canvas is an object that other objects can be attached to, and imprinted upon. When the canvas gets moved, the attached objects move as well. The background of a canvas can be made invisible by using a color with alpha channel == 0. The Setpixel and SetPoint functions let you change individual pixels on a canvas, to enable adding noise, drawing functional images, etc. A canvas gets ‘cleared’ by calling ResetCanvas(canvas). Any object added to a canvas creates an ‘imprint’ on the canvas that remains if the object is moved. This allows you to use another image as a paintbrush on the canvas, and lets you to add noise to text. Because a text label gets re-rendered when its drawn, if you want to add pixel noise to a stimulus, you can create a label, add it to a canvas, then add pixel noise to the canvas.
Usage:
MakeCanvas(<x>, <y>, <color>)
Example:
gWin <- MakeWindow()
clear <- MakeColor("white")
clear.alpha <- 0
#make a transparent canvas:
x <- MakeCanvas(300,300,clear)
AddObject(x,gWin)
Move(x,300,300)
img <- MakeImage("pebl.png")
AddObject(img,x)
Move(img,100,100)
Draw(x) #imprint the image on the canvas
Move(img,100,200)
Draw(x) #imprint the image on the canvas
Hide(img)
#draw a line on the canvas
i <- 10
red <- MakeColor("red")
while(i < 200)
{
SetPixel(x,20,i,red)
i <- i + 1
}
Draw()
WaitForAnyKeyPress()
See Also:
MakeColor()¶
Creates a color based on a color name
Description:
Makes a color from <colorname> such as red'', ``green'', and nearly 800 others. Color names and corresponding RGB values can be found in ``doc/colors.txt.
Usage:
MakeColor(<colorname>)
Example:
green <- MakeColor("green")
black <- MakeColor("black")
See Also:
MakeColorRGB()¶
Creates a color based on red, green, and blue values
Description:
Makes an RGB color by specifying <red>, <green>, and <blue> values (between 0 and 255).
Usage:
MakeColorRGB(<red>, <green>, <blue>)
See Also:
MakeCustomObject()¶
Creates custom object.
Description:
Creates a ‘custom’ object that can encapsulate multiple properties. It takes a name as an argument, but this is currently not accessible.
Example:
obj <- MakeCustomObject("myobject")
obj.taste <- "buttery"
obj.texture <- "creamy"
SetProperty(obj,"flavor","tasty")
list <- GetPropertyList(obj)
loop(i,list)
{
if(PropertyExists(obj,i)
{
Print(i + ": " + GetProperty(obj,i))
}
}
See Also:
GetPropertyList(), PropertyExists(), SetProperty(), IsCustomObject(), PrintProperties(), GetProperty()
MakeFont()¶
Creates a font which can be used to make labels
Description:
Makes a font. The first argument must be a text name of a font. The font can reside anywhere in PEBL’s search path, which would primarily include the media/fonts directory, and the working directory (where the script is saved).
style changes from normal to bold/underline, italic. 0=normal, 1=underline, 2=italic,3=bolditalic
fgcolor and bgcolor need to be colors, not just names of colors
if show-backing is 0, the font gets rendered with an invisible
background; otherwise with a bgcolor background. (Note: previous to PEBL 0.11, the final argument = 0 rendered the font with non anti-aliased background, which I can see almost no use for.)
Usage:
MakeFont(<ttf_filename>, <style>, <size>,
<fgcolor>, <bgcolor>, <show-backing>)
Example:
font <- MakeFont("Vera.ttf",0,22,MakeColor("black"),
MakeColor("white"),1)
MakeImage()¶
Creates an image by reading in an image file (jpg, gif, png, bmp, etc.)
Description:
Makes an image widget from an image file. .bmp formats should be supported; others may be as well.
Usage:
MakeImage(<filename>)
MakeLabel()¶
Description:
Makes a text label for display on-screen. Text will be on a single line, and the Move() command centers <text> on the specified point.
Usage:
MakeLabel(<text>, <font>)
MakeSineWave()¶
Creates a pure sine wave.
Description:
Creates a sine wave that can be played using the Play() or PlayBackground() functions. It will create a single-channel sound at 44100 bitrate, 16 bit precision.
Usage:
MakeSineWave(<duration_in_ms>, <hz>, <amplitude>)
Example:
##Make a sound that is 1000 ms, but just play 300 ms
sound <- MakeSineWave(200, 220, 1000)
PlayBackground(sound)
Wait(300)
Stop(sound)
See Also:
PlayForeground(), PlayBackGround(), Stop()
MakeTextBox()¶
Creates a sized box filled
Description:
Creates a textbox in which to display text. Textboxes allow multiple lines of text to be rendered; automatically breaking the text into lines.
Usage:
MakeTextbox(<text>,<font>,<width>,<height>)
Example:
font <-MakeFont("Vera.ttf", 1, 12, MakeColor("red"),
MakeColor("green"), 1)
tb <- MakeTextBox("This is the text in the textbox",
font, 100, 250)
See Also:
MakeLabel(), GetText(), SetText(), SetCursorPosition(), GetCursorPosition(), SetEditable()
MakeWindow()¶
Creates main window, in color named by argument, or grey if no argument is named
Description:
Creates a window to display things in. Background is specified by <color>.
Usage:
MakeWindow(opt:<color>, opt:<width>,opt:<height>)
Example:
win <- MakeWindow()
gWin <- MakeWindow("white")
##make a second window for debugging or experimenter data entry.
gWin2 <- MakeWindow("black",400,200)
Move()¶
Description:
Moves an object to a specified location. Images and Labels are moved according to their center; TextBoxes are moved according to their upper left corner.
Usage:
Move(<object>, <x>, <y>)
Example:
Move(label, 33, 100)
See Also:
MoveCorner(), MoveCenter(), X() and Y() properties.
PausePlayback()¶
Pauses playback of movie
Description:
Pauses a playing movie or audio stream. This is used for movies whose playback was initiated using StartPlayback, which then ran as background threads during a Wait() function.
Usage:
PausePlayBack(movie)
Example:
movie <- LoadMovie("movie.avi",gWin,640,480)
PrintProperties(movie)
Move(movie,20,20)
Draw()
StartPlayback(movie)
Wait(500) #Play 500 ms of the movie.
PausePlayback(movie)
Wait(500)
See Also:
PlayBackground()¶
Plays the sound ‘in the background’, returning immediately
Description:
Plays the sound ‘in the background’, returning immediately.
Usage:
PlayBackground(<sound>)
Example:
sound <- MakeSineWave(200, 220, 1000)
PlayBackground(sound)
Wait(300)
Stop(sound)
See Also:
PlayForeground()¶
Plays the sound ‘in the foreground’, not returning until the sound is complete
Description:
Plays the sound ‘in the foreground’; does not return until the sound is complete.
Usage:
PlayForeground(<sound>)
Example:
sound <- MakeSineWave(200, 220, 1000)
PlayForeground(sound)
See Also:
Polygon()¶
Description:
Creates a polygon in the shape of the points specified by <xpoints>, <ypoints>. The lists <xpoints> and <ypoints> are adjusted by <x> and <y>, so they should be relative to 0, not the location you want the points to be at. Like other drawn objects, the polygon must then be added to the window to appear.
Usage:
Polygon(<x>,<y>,<xpoints>,<ypoints>,
<color>,<filled>)
Example:
win <- MakeWindow()
#This makes a T
xpoints <- [-10,10,10,20,20,-20,-20,-10]
ypoints <- [-20,-20,40,40,50,50,40,40]
p1 <- Polygon(100,100,xpoints, ypoints,
MakeColor("black"),1)
AddObject(p1,win)
Draw()
See Also:
PrintProperties()¶
Prints a list of all available properties of an object (for debugging)
Description:
Prints .properties/values for any complex object. These include textboxes, fonts, colors, images, shapes, etc. Mostly useful as a debugging tool.
Usage:
PrintProperties(<object>)
Example:
win <- MakeWindow()
tb <- EasyTextbox("one",20,20,win,22,400,80)
PrintProperties(tb)
##Output:
----------
[CURSORPOS]: 0
[EDITABLE]: 0
[HEIGHT]: 80
[ROTATION]: 0
[TEXT]: one
[VISIBLE]: 1
[WIDTH]: 400
[X]: 20
[Y]: 20
[ZOOMX]: 1
[ZOOMY]: 1
----------
See Also:
PropertyExists()¶
Determines whether a particular property exists
Description:
Tests whether a particular named property exists. This works for custom or built-in objects. This is important to check properties that might not exist, because trying to GetProperty of a non-existent property will cause a fatal error.
Example:
obj <- MakeCustomObject("myobject")
obj.taste <- "buttery"
obj.texture <- "creamy"
SetProperty(obj,"flavor","tasty")
list <- GetPropertyList(obj)
loop(i,list)
{
if(PropertyExists(obj,i)
{
Print(i + ": " + GetProperty(obj,i))
}
}
See Also:
GetPropertyList(), GetProperty(), SetProperty() MakeCustomObject(), PrintProperties()
Rectangle()¶
Creates rectangle with size (dx, dy) centered at position x,y
Description:
Creates a rectangle for graphing at x,y with size dx and dy. Rectangles are only currently definable oriented in horizontal/vertical directions. A rectangle must be added to a parent widget before it can be drawn; it may be added to widgets other than a base window. The properties of rectangles may be changed by accessing their properties directly, including the FILLED property which makes the object an outline versus a filled shape.
Usage:
Rectangle(<x>, <y>, <dx>, <dy>, <color>)
Example:
r <- Rectangle(30,30,20,10, MakeColor(green))
AddObject(r, win)
Draw()
See Also:
RemoveObject()¶
Removes an object from a parent window
Description:
Removes a child widget from a parent. Useful if you are adding a local widget to a global window inside a loop. If you do not remove the object and only Hide() it, drawing will be sluggish. Objects that are local to a function are removed automatically when the function terminates, so you do not need to call RemoveObject() on them at the end of a function.
Usage:
RemoveObject( <object>, <parent>)
ResizeWindow()¶
Resizes a window to a specified width and height
Description:
Resizes an existing window to the specified dimensions. This allows you to dynamically change the size of a window during program execution.
Usage:
ResizeWindow(<window>, <width>, <height>)
Example:
win <- MakeWindow("grey")
##Start with default size, then resize
ResizeWindow(win, 1024, 768)
Draw()
See Also:
RotoZoom()¶
Rotates and zooms a graphical widget
Description:
Rotates and zooms a widget (such as an image or label) by specified amounts. The rotation parameter specifies rotation in degrees. The xzoom and yzoom parameters specify scaling factors for horizontal and vertical dimensions (1.0 = no change, 2.0 = double size, 0.5 = half size). The smooth parameter (0 or 1) determines whether to use anti-aliasing for smoother appearance.
Usage:
RotoZoom(<widget>, <rotation>, <xzoom>, <yzoom>, <smooth>)
Example:
img <- MakeImage("stimulus.png")
AddObject(img, win)
Move(img, 320, 240)
##Rotate 45 degrees, double size, with smoothing
RotoZoom(img, 45, 2.0, 2.0, 1)
Draw()
##Rotate 90 degrees, normal size, no smoothing
RotoZoom(img, 90, 1.0, 1.0, 0)
Draw()
See Also:
SaveAudioToWaveFile()¶
Saves buffer to a .wav file format
Description:
Saves a buffer, recorded using the GetAudioInputBuffer, to a .wav file for later analysis or archive.
Usage:
SaveAudioToWaveFile(filename, buffer)
Example:
gResponseBuffer <- MakeAudioInputBuffer(5000)
resp0 <- GetVocalResponseTime(gResponseBuffer,.35, 200)
SaveAudioToWaveFile("output.wav",gResponseBuffer)
See Also:
GetVocalResponseTime(), MakeAudioInputBuffer(), RecordToBuffer()
RecordToBuffer()¶
Records audio input to a pre-allocated buffer
Description:
Records audio from the microphone directly into a pre-allocated audio buffer. This function allows precise control over recording duration and provides a synchronous recording interface. The buffer must be created first using MakeAudioInputBuffer(). An optional duration parameter can specify recording time in milliseconds; if omitted, the function records for the full buffer duration. ONLY AVAILABLE ON WINDOWS AND LINUX.
Usage:
RecordToBuffer(<buffer>)
RecordToBuffer(<buffer>, <duration_ms>)
Example:
## Record for full buffer duration (5 seconds)
buffer <- MakeAudioInputBuffer(5000)
RecordToBuffer(buffer)
SaveAudioToWaveFile("recording.wav", buffer)
## Record for specific duration (3 seconds into 5 second buffer)
buffer <- MakeAudioInputBuffer(5000)
RecordToBuffer(buffer, 3000)
SaveAudioToWaveFile("recording-3s.wav", buffer)
See Also:
MakeAudioInputBuffer(), SaveAudioToWaveFile(), GetVocalResponseTime(), StartAudioMonitor()
StartAudioMonitor()¶
Starts real-time audio monitoring with ring buffer
Description:
Creates and starts an audio monitoring system that continuously records audio in a ring buffer. This is useful for real-time audio analysis, voice key calibration, and audio level visualization. The monitor runs in the background and can be queried with GetAudioStats() to retrieve recent audio statistics. The monitor must be stopped with StopAudioMonitor() to free audio hardware resources. ONLY AVAILABLE ON WINDOWS AND LINUX.
Usage:
StartAudioMonitor(<buffer_size_ms>)
Example:
## Start monitoring with 3-second ring buffer
monitor <- StartAudioMonitor(3000)
## Continuously check audio levels
loop(i, Sequence(1, 100, 1))
{
Wait(100)
stats <- GetAudioStats(monitor, 500) ## Last 500ms
energy <- First(stats)
Print("Energy: " + energy)
}
StopAudioMonitor(monitor)
See Also:
StopAudioMonitor()¶
Stops audio monitoring and releases audio hardware
Description:
Stops an audio monitor created by StartAudioMonitor() and releases the audio hardware. This function performs complete cleanup including pausing recording, closing the SDL audio device, and clearing global audio state. It is critical to call this function before starting other audio operations like GetVocalResponseTime() to ensure the audio hardware is available. ONLY AVAILABLE ON WINDOWS AND LINUX.
Usage:
StopAudioMonitor(<monitor>)
Example:
## Monitor audio for 10 seconds then stop
monitor <- StartAudioMonitor(2000)
Wait(10000)
StopAudioMonitor(monitor)
## Now audio hardware is free for other operations
buffer <- MakeAudioInputBuffer(5000)
rt <- GetVocalResponseTime(buffer, 0.35, 200)
See Also:
GetAudioStats()¶
Retrieves audio statistics from monitoring buffer
Description:
Returns audio statistics from the most recent N milliseconds of an audio monitor created by StartAudioMonitor(). The function returns a list containing three values: [energy, power, rmssd]. Energy represents total signal energy, power represents average power, and rmssd (root mean square of successive differences) indicates signal variability. These statistics are useful for voice key calibration, detecting speech onset, and monitoring audio levels. ONLY AVAILABLE ON WINDOWS AND LINUX.
Usage:
GetAudioStats(<monitor>, <window_ms>)
Example:
## Monitor and display real-time audio statistics
monitor <- StartAudioMonitor(5000)
loop(i, Sequence(1, 50, 1))
{
Wait(200)
stats <- GetAudioStats(monitor, 1000) ## Last 1 second
energy <- First(stats)
power <- Nth(stats, 2)
rmssd <- Third(stats)
Print("Energy: " + energy + " Power: " + power + " RMSSD: " + rmssd)
}
StopAudioMonitor(monitor)
See Also:
StartAudioMonitor(), StopAudioMonitor(), GetVocalResponseTime()
SetCursorPosition()¶
Description:
Moves the editing cursor to a specified character position in a textbox.
Usage:
SetCursorPosition(<textbox>, <integer>)
Example:
SetCursorPosition(tb, 23)
See Also:
SetEditable()¶
Turns on or off the editing cursor
Description:
Sets the editable'' status of the textbox. All this really does is turns on or off the cursor; editing must be done with the (currently unsupported) device function ``GetInput().
Usage:
SetEditable()
Example:
SetEditable(tb, 0)
SetEditable(tb, 1)
See Also:
GetEditable()
SetFont()¶
Changes the font of a text object
Description:
Resets the font of a textbox or label. Change will not appear until the next Draw() function is called. Can be used, for example, to change the color of a label to give richer feedback about correctness on a trial (see example below). Font can alse be set by assigning to the object.font property of an object.
Usage:
SetFont(<text-widget>, <font>)
Example:
fontGreen <- MakeFont("vera.ttf",1,22,
MakeColor("green"),
MakeColor("black"), 1)
fontRed <- MakeFont("vera.ttf",1,22,
MakeColor("red"),
MakeColor("black"), 1)
label <- MakeLabel(fontGreen, "Correct")
#Do trial here.
if(response == 1)
{
SetText(label, "CORRECT")
SetFont(label, fontGreen)
} else {
SetText(label, "INCORRECT")
SetFont(label, "fontRed)
}
Draw()
See Also:
SetPanning()¶
Sets volume of left and right channel.
Description:
Sets the audio panning; the volume of the left and right audio channels.
Usage:
SetPanning(<audio>,<left>,<right>)
Example:
one <- LoadSound("1.wav")
PlayForeground(one)
SetPanning(one,1.0,0.0)
PlayForeground(one)
SetPanning(one,.5,.5)
PlayForeground(one)
See Also:
SetPlayRepeats()¶
Sets a repeat count on a sound playback.
Description:
Sets repetition count on an audio file. When played back, i will play this sound reps+1 times. If set to 0, it will play just once. If set to -1, it will repeat indefinitely.
Usage:
SetPlayRepeats(<audio>,<reps>)
Example:
one <- LoadSound("1.wav")
PlayForeground(one)
SetPlayRepeats(one,5)
PlayForeground(one)
SetPanning(one,-1)
PlayBackground(one)
Wait(5000)
Stop(one)
See Also:
SetProperty()¶
Sets property of an object
Description:
Sets a a property of a custom object. This works for custom or built-in objects, but new properties can only be set on custom object. This function works essentially identically to the obj.property assignment, but it allows you to create property names from input. It is used extensively for the PEBL parameter setting.
Example:
obj <- MakeCustomObject("myobject")
obj.taste <- "buttery"
obj.texture <- "creamy"
SetProperty(obj,"flavor","tasty")
list <- GetPropertyList(obj)
loop(i,list)
{
if(PropertyExists(obj,i)
{
Print(i + ": " + GetProperty(obj,i))
}
}
See Also:
GetProperty(), PropertyExists(), GetPropertyList(), MakeCustomObject(), PrintProperties()
SetPixel()¶
Sets the color of a pixel at specified coordinates
Description:
Sets the pixel at x,y to a particular color. SetPixel is primarily useful for images and canvases–labels and textboxes get re-rendered upon draw so any use of SetPixel will get overwritten when it gets drawn. It won’t work on windows or shapes. This function can also be called using SetPoint().
Usage:
SetPixel(<widget>, <x>, <y>, <color>)
Example:
back <- MakeCanvas(50,50)
AddObject(back,gWin)
col <- MakeColor("green")
xy <- [[10,10],[10,11],[10,12],[10,13]]
loop(i,xy)
{
SetPixel(back, First(i), Second(i), col)
}
Draw()
See Also:
SetPoint()¶
Sets the color of a point at specified coordinates (alias for SetPixel)
Description:
Sets the pixel at x,y to a particular color. SetPoint is an alias for SetPixel() and functions identically. It is primarily useful for images and canvases–labels and textboxes get re-rendered upon draw so any use of SetPoint will get overwritten when it gets drawn. It won’t work on windows or shapes.
Usage:
SetPoint(<widget>, <x>, <y>, <color>)
Example:
back <- MakeCanvas(50,50)
AddObject(back,gWin)
col <- MakeColor("green")
xy <- [[10,10],[10,11],[10,12],[10,13]]
loop(i,xy)
{
SetPoint(back, First(i), Second(i), col)
}
Draw()
See Also:
SetText()¶
Sets the text in a textbox or label
Description:
Resets the text of a textbox or label. Change will not appear until the next Draw() function is called. The object.text property can also be used to change text of an object, by doing: object.text <- "new text"
Usage:
SetText(<text-widget>, <text>)
Example:
# Fixation Cross:
label <- MakeLabel(font, "+")
Draw()
SetText(label, "X")
Wait(100)
Draw()
See Also:
Show()¶
Shows an object
Description:
Sets a widget to visible, once it has been added to a parent widget. This just changes the visibility property, it does not make the widget appear. The widget will not be displayed until the Draw() function is called. The .visible property of objects can also be used to hide or show the object.
Usage:
Show(<object>)
Example:
window <- MakeWindow()
image1 <- MakeImage("pebl.bmp")
image2 <- MakeImage("pebl.bmp")
AddObject(image1, window)
AddObject(image2, window)
Hide(image2)
Draw()
Wait(300)
Show(image2)
Draw()
See Also:
Square()¶
Creates square with width size centered at position x,y
Description:
Creates a square for graphing at x,y with size <size>. Squares are only currently definable oriented in horizontal/vertical directions. A square must be added to a parent widget before it can be drawn; it may be added to widgets other than a base window. The properties of squares may be changed by accessing their properties directly, including the FILLED property which makes the object an outline versus a filled shape.
Usage:
Ellipse(<x>, <y>, <size>, <color>)
Example:
s <- Square(30,30,20, MakeColor(green))
AddObject(s, win)
Draw()
See Also:
StartPlayback()¶
Initiates playback in background, updated with Wait()
Description:
Initiates playback of a movie so that it will play in the background when a Wait() or WaitFor() function is called. This allows one to collect a response while playing a movie. The movie will not actually play until the event loop is started, typically with something like Wait().
Usage:
StartPlayBack(movie)
Example:
movie <- LoadMovie("movie.avi",gWin,640,480)
PrintProperties(movie)
Move(movie,20,20)
Draw()
StartPlayback(movie)
Wait(500) #Play 500 ms of the movie.
PausePlayback(movie)
See Also:
Stop()¶
Stops a sound playing in the background from playing
Description:
Stops a sound playing in the background from playing. Calling Stop() on a sound object that is not playing should have no effect, but if an object is aliased, Stop() will stop the file. Note that sounds play in a separate thread, so interrupting the thread has a granularity up to the duration of the thread-switching quantum on your computer; this may be tens of milliseconds.
Usage:
Stop(<sound-object>)
Example:
buzz <- LoadSound("buzz.wav")
PlayBackground(buzz)
Wait(50)
Stop(buzz)
See Also:
PlayForeground(), PlayBackGround()
ThickLine()¶
Creates a thick line between two points
Description:
Makes a thick line between two coordinates. This uses the SDL_gfx thickline primitive.
Usage:
ThickLine(<x1>,<y1>,<x2>,<y2>,
<size-in-pixels>,<color>)
Example:
a <- ThickLine(10,10,300,400,20,
MakeColor("red"))
AddObject(a,gWin)
Draw()
See Also: