Documentation
¶
Overview ¶
Package stimuli provides visual and auditory stimulus types (fixation cross, text, pictures, video, shapes, sound, etc.) that implement the Stimulus and VisualStimulus interfaces for use with the experiment Screen.
Index ¶
- func PlayBuzzer(audioDevice sdl.AudioDeviceID) error
- func PlayPing(audioDevice sdl.AudioDeviceID) error
- func PlaySoundFromMemory(audioDevice sdl.AudioDeviceID, data []byte) error
- func PreloadAllVisual(screen *io.Screen, visuals []VisualStimulus) error
- func PreloadVisualOnScreen(screen *io.Screen, v VisualStimulus) error
- type BlankScreen
- type Canvas
- func (c *Canvas) Blit(stim VisualStimulus, screen *io.Screen) error
- func (c *Canvas) Clear(screen *io.Screen) error
- func (c *Canvas) Draw(screen *io.Screen) error
- func (c *Canvas) GetPosition() sdl.FPoint
- func (c *Canvas) Preload() error
- func (c *Canvas) Present(screen *io.Screen, clear, update bool) error
- func (c *Canvas) SetPosition(pos sdl.FPoint)
- func (c *Canvas) Unload() error
- type Circle
- func (c *Circle) Draw(screen *io.Screen) error
- func (c *Circle) GetPosition() sdl.FPoint
- func (c *Circle) InsideCircle(areaRadius float32, areaPos sdl.FPoint) bool
- func (c *Circle) Preload() error
- func (c *Circle) Present(screen *io.Screen, clear, update bool) error
- func (c *Circle) SetPosition(pos sdl.FPoint)
- func (c *Circle) Unload() error
- type DotCloud
- func (dc *DotCloud) Draw(screen *io.Screen) error
- func (dc *DotCloud) GetPosition() sdl.FPoint
- func (dc *DotCloud) Make(nDots int, dotRadius float32, gap float32) bool
- func (dc *DotCloud) Preload() error
- func (dc *DotCloud) Present(screen *io.Screen, clear, update bool) error
- func (dc *DotCloud) SetPosition(pos sdl.FPoint)
- func (dc *DotCloud) Unload() error
- type FixCross
- type GaborPatch
- type Line
- type Picture
- type Rectangle
- type Shape
- type Sound
- type Stimulus
- type StimulusCircle
- func (sc *StimulusCircle) Draw(screen *io.Screen) error
- func (sc *StimulusCircle) GetPosition() sdl.FPoint
- func (sc *StimulusCircle) Make(shuffle bool, jitter bool)
- func (sc *StimulusCircle) Preload() error
- func (sc *StimulusCircle) Present(screen *io.Screen, clear, update bool) error
- func (sc *StimulusCircle) SetPosition(pos sdl.FPoint)
- func (sc *StimulusCircle) Unload() error
- type TextBox
- type TextInput
- func (ti *TextInput) Draw(screen *io.Screen) error
- func (ti *TextInput) Get(screen *io.Screen, keyboard *io.Keyboard) (string, error)
- func (ti *TextInput) GetPosition() sdl.FPoint
- func (ti *TextInput) Preload() error
- func (ti *TextInput) Present(screen *io.Screen, clear, update bool) error
- func (ti *TextInput) SetPosition(pos sdl.FPoint)
- func (ti *TextInput) Unload() error
- type TextLine
- type ThermometerDisplay
- func (td *ThermometerDisplay) Draw(screen *io.Screen) error
- func (td *ThermometerDisplay) GetPosition() sdl.FPoint
- func (td *ThermometerDisplay) Preload() error
- func (td *ThermometerDisplay) Present(screen *io.Screen, clear, update bool) error
- func (td *ThermometerDisplay) SetPosition(pos sdl.FPoint)
- func (td *ThermometerDisplay) Unload() error
- type Tone
- type Video
- func (v *Video) Draw(screen *io.Screen) error
- func (v *Video) DrawAt(screen *io.Screen, dest *sdl.FRect) error
- func (v *Video) IsFinished() bool
- func (v *Video) IsPaused() bool
- func (v *Video) IsPlaying() bool
- func (v *Video) Pause()
- func (v *Video) Play() error
- func (v *Video) Preload() error
- func (v *Video) PreloadDevice(screen *io.Screen, audioDevice sdl.AudioDeviceID) error
- func (v *Video) Present(screen *io.Screen, clear, update bool) error
- func (v *Video) Seek(t time.Duration) error
- func (v *Video) Stop()
- func (v *Video) Unload() error
- func (v *Video) Update() error
- type VisualMask
- type VisualStimulus
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PlayBuzzer ¶ added in v0.1.1
func PlayBuzzer(audioDevice sdl.AudioDeviceID) error
PlayBuzzer plays the embedded buzzer sound synchronously on the given audio device.
func PlayPing ¶ added in v0.1.1
func PlayPing(audioDevice sdl.AudioDeviceID) error
PlayPing plays the embedded "correct" ping sound synchronously on the given audio device.
func PlaySoundFromMemory ¶
func PlaySoundFromMemory(audioDevice sdl.AudioDeviceID, data []byte) error
PlaySoundFromMemory is a helper to play a sound from a byte slice on a given audio device in the background.
func PreloadAllVisual ¶ added in v0.1.1
func PreloadAllVisual(screen *io.Screen, visuals []VisualStimulus) error
PreloadAllVisual preloads a slice of visual stimuli on the given screen.
func PreloadVisualOnScreen ¶ added in v0.1.1
func PreloadVisualOnScreen(screen *io.Screen, v VisualStimulus) error
PreloadVisualOnScreen attempts to preload GPU resources for a visual stimulus on the given screen without presenting it. For known stimulus types it calls their internal preload routines; for others it falls back to calling Draw, which will lazily allocate textures without updating the screen contents.
Types ¶
type BlankScreen ¶
BlankScreen is a full-screen filled rectangle of one color (e.g. for inter-trial intervals).
func NewBlankScreen ¶
func NewBlankScreen(color sdl.Color) *BlankScreen
NewBlankScreen creates a blank screen that draws the given color over the full screen.
func (*BlankScreen) GetPosition ¶
func (b *BlankScreen) GetPosition() sdl.FPoint
func (*BlankScreen) Preload ¶
func (b *BlankScreen) Preload() error
func (*BlankScreen) Present ¶
func (b *BlankScreen) Present(screen *io.Screen, clear, update bool) error
func (*BlankScreen) SetPosition ¶
func (b *BlankScreen) SetPosition(pos sdl.FPoint)
func (*BlankScreen) Unload ¶
func (b *BlankScreen) Unload() error
type Canvas ¶
Canvas is an offscreen render target of the given size and background color; stimuli can be drawn to it, then the canvas is drawn to the screen.
func NewCanvas ¶
NewCanvas creates a canvas with the given width, height, and background color (center at 0,0).
func (*Canvas) Blit ¶
func (c *Canvas) Blit(stim VisualStimulus, screen *io.Screen) error
Blit draws a stimulus onto the canvas.
func (*Canvas) GetPosition ¶
func (*Canvas) SetPosition ¶
type Circle ¶
Circle is a filled circle with the given radius and color; Position is center-based.
func (*Circle) Draw ¶
Draw draws the circle using multiple lines or points. For better performance, we could use a texture.
func (*Circle) GetPosition ¶
func (*Circle) InsideCircle ¶
InsideCircle checks if the circle is inside another circle (area).
func (*Circle) SetPosition ¶
type DotCloud ¶
type DotCloud struct {
Radius float32
Position sdl.FPoint
BackgroundColor sdl.Color
DotColor sdl.Color
Dots []*Circle
}
DotCloud represents a circular cloud of dots.
func NewDotCloud ¶
NewDotCloud creates a new DotCloud.
func (*DotCloud) GetPosition ¶
func (*DotCloud) SetPosition ¶
type FixCross ¶
FixCross is a centered fixation cross (horizontal and vertical lines). Position is in center-based coordinates; Size and LineWidth are in the same units.
func NewFixCross ¶
NewFixCross creates a fixation cross with the given size, line width, and color (center at 0,0).
func (*FixCross) GetPosition ¶
func (*FixCross) SetPosition ¶
type GaborPatch ¶
type GaborPatch struct {
Sigma float64
Theta float64 // orientation in degrees
Lambda float64 // spatial frequency
Phase float64
Psi float64
Gamma float64
BackgroundColor sdl.Color
Position sdl.FPoint
Size float32
Texture *sdl.Texture
}
GaborPatch is a Gabor patch (sinusoidal grating windowed by a Gaussian) with orientation, spatial frequency, phase, and size parameters.
func NewGaborPatch ¶
func NewGaborPatch(sigma, theta, lambda, phase, psi, gamma float64, bgColor sdl.Color, size float32) *GaborPatch
NewGaborPatch creates a Gabor patch with the given sigma, theta (degrees), lambda, phase, psi, gamma, background color, and size in pixels.
func (*GaborPatch) GetPosition ¶
func (gp *GaborPatch) GetPosition() sdl.FPoint
func (*GaborPatch) Preload ¶
func (gp *GaborPatch) Preload() error
func (*GaborPatch) Present ¶
func (gp *GaborPatch) Present(screen *io.Screen, clear, update bool) error
func (*GaborPatch) SetPosition ¶
func (gp *GaborPatch) SetPosition(pos sdl.FPoint)
func (*GaborPatch) Unload ¶
func (gp *GaborPatch) Unload() error
type Line ¶
Line is a line segment from Start to End in center-based coordinates, with the given color and line width.
func (*Line) GetPosition ¶
func (*Line) SetPosition ¶
type Picture ¶
type Picture struct {
FilePath string
Memory []byte
Position sdl.FPoint
Texture *sdl.Texture
Width float32
Height float32
}
Picture is an image stimulus loaded from a file path or from memory (e.g. embedded data).
func NewPicture ¶
NewPicture creates a picture stimulus from a file path, with center position (x, y).
func NewPictureFromMemory ¶
NewPictureFromMemory creates a new Picture stimulus from embedded data.
func (*Picture) GetPosition ¶
func (*Picture) SetPosition ¶
type Rectangle ¶
Rectangle is a filled rectangle with center at (x,y) and size (w,h) in center-based coordinates.
func NewRectangle ¶
NewRectangle creates a rectangle centered at (x, y) with width w, height h, and the given color.
func (*Rectangle) GetPosition ¶
func (*Rectangle) SetPosition ¶
type Shape ¶
Shape is a filled polygon defined by Points (relative to the shape center) and a single color.
func (*Shape) GetPosition ¶
func (*Shape) SetPosition ¶
type Sound ¶
type Sound struct {
FilePath string
Memory []byte
Data []byte
Spec sdl.AudioSpec
Stream *sdl.AudioStream
}
Sound represents an audio stimulus (WAV).
func NewSoundFromMemory ¶
NewSoundFromMemory creates a new Sound stimulus from embedded data.
func (*Sound) PreloadDevice ¶
func (s *Sound) PreloadDevice(audioDevice sdl.AudioDeviceID) error
PreloadDevice loads the WAV file and prepares the audio stream.
type Stimulus ¶
type Stimulus interface {
Present(screen *io.Screen, clear, update bool) error
Preload() error
Unload() error
}
Stimulus is the interface for all visual and auditory stimuli.
type StimulusCircle ¶
type StimulusCircle struct {
Radius float32
Stimuli []VisualStimulus
Position sdl.FPoint
}
StimulusCircle represents a collection of stimuli arranged in a circle.
func NewStimulusCircle ¶
func NewStimulusCircle(radius float32, stimuli []VisualStimulus) *StimulusCircle
NewStimulusCircle creates a new StimulusCircle.
func (*StimulusCircle) Draw ¶
func (sc *StimulusCircle) Draw(screen *io.Screen) error
Draw draws all stimuli in the circle.
func (*StimulusCircle) GetPosition ¶
func (sc *StimulusCircle) GetPosition() sdl.FPoint
func (*StimulusCircle) Make ¶
func (sc *StimulusCircle) Make(shuffle bool, jitter bool)
Make arranges the stimuli in a circle.
func (*StimulusCircle) Preload ¶
func (sc *StimulusCircle) Preload() error
func (*StimulusCircle) Present ¶
func (sc *StimulusCircle) Present(screen *io.Screen, clear, update bool) error
Present clears and draws the circle.
func (*StimulusCircle) SetPosition ¶
func (sc *StimulusCircle) SetPosition(pos sdl.FPoint)
func (*StimulusCircle) Unload ¶
func (sc *StimulusCircle) Unload() error
type TextBox ¶
type TextBox struct {
Text string
BoxWidth int32
Position sdl.FPoint
Color sdl.Color
Alignment ttf.HorizontalAlignment
Font *ttf.Font
Texture *sdl.Texture
Width float32
Height float32
}
TextBox represents a multi-line text box with wrapping and alignment.
func NewTextBox ¶
NewTextBox creates a multi-line text box with the given maximum width (in pixels), center position, and color.
func (*TextBox) GetPosition ¶
func (*TextBox) SetPosition ¶
type TextInput ¶
type TextInput struct {
Message string
Position sdl.FPoint
BoxWidth float32
BackgroundColor sdl.Color
FrameColor sdl.Color
TextColor sdl.Color
UserText string
}
TextInput represents a text input box for user input.
func NewTextInput ¶
func NewTextInput(message string, position sdl.FPoint, boxWidth float32, bgColor, frameColor, textColor sdl.Color) *TextInput
NewTextInput creates a new TextInput.
func (*TextInput) GetPosition ¶
func (*TextInput) SetPosition ¶
type TextLine ¶
type TextLine struct {
Text string
Position sdl.FPoint
Color sdl.Color
Font *ttf.Font
Texture *sdl.Texture
Width float32
Height float32
}
TextLine is a single line of text rendered with an optional font (or the screen default).
func NewTextLine ¶
NewTextLine creates a text line at (x, y) in center-based coordinates with the given color.
func (*TextLine) GetPosition ¶
func (*TextLine) SetPosition ¶
type ThermometerDisplay ¶
type ThermometerDisplay struct {
State float32 // 0 to 100
Goal float32 // 0 to 100
Size sdl.FPoint
NrSegments int
Position sdl.FPoint
FrameColor sdl.Color
ActiveColor sdl.Color
InactiveColor sdl.Color
GapColor sdl.Color
GoalColor sdl.Color
SegmentGap float32
}
ThermometerDisplay represents a segmented progress bar with an optional goal.
func NewThermometerDisplay ¶
func NewThermometerDisplay(size sdl.FPoint, nrSegments int, state, goal float32) *ThermometerDisplay
NewThermometerDisplay creates a new ThermometerDisplay.
func (*ThermometerDisplay) GetPosition ¶
func (td *ThermometerDisplay) GetPosition() sdl.FPoint
func (*ThermometerDisplay) Preload ¶
func (td *ThermometerDisplay) Preload() error
func (*ThermometerDisplay) Present ¶
func (td *ThermometerDisplay) Present(screen *io.Screen, clear, update bool) error
func (*ThermometerDisplay) SetPosition ¶
func (td *ThermometerDisplay) SetPosition(pos sdl.FPoint)
func (*ThermometerDisplay) Unload ¶
func (td *ThermometerDisplay) Unload() error
type Tone ¶
type Tone struct {
Frequency float64
Duration int // ms
Amplitude float32
Stream *sdl.AudioStream
Data []byte
}
Tone is a procedural sine-wave tone with configurable frequency (Hz), duration (ms), and amplitude.
func NewTone ¶
NewTone creates a sine wave tone with the given frequency in Hz, duration in milliseconds, and amplitude (0–1).
func (*Tone) PreloadDevice ¶
func (t *Tone) PreloadDevice(audioDevice sdl.AudioDeviceID) error
PreloadDevice generates the tone's PCM data.
type Video ¶
type Video struct {
FilePath string
// Video properties
Width int
Height int
FPS float64
// contains filtered or unexported fields
}
Video represents a video stimulus that can be played with optional audio. It uses FFmpeg via the go-astiav bindings for demuxing/decoding and SDL3 for rendering frames and streaming audio to the experiment's audio device.
Typical usage:
v := stimuli.NewVideo("assets/clip.mp4")
if err := v.Preload(); err != nil { log.Fatal(err) }
if err := v.PreloadDevice(exp.Screen, exp.AudioDevice); err != nil { log.Fatal(err) }
if err := v.Play(); err != nil { log.Fatal(err) }
err := exp.Run(func() error {
if err := v.Update(); err != nil { return err }
if err := v.Present(exp.Screen, true, true); err != nil { return err }
if !v.IsPlaying() { return sdl.EndLoop }
return nil
})
func NewVideo ¶
NewVideo creates a new video stimulus for the given file path. The underlying FFmpeg/SDL resources are allocated lazily in Preload and PreloadDevice.
func (*Video) DrawAt ¶ added in v0.1.1
DrawAt renders the current video frame to the given destination rectangle. If dest is nil, the frame is centered at its native size using the renderer's current output size.
func (*Video) IsFinished ¶
IsFinished returns true if the video has finished playback.
func (*Video) IsPlaying ¶
IsPlaying returns true if the video is currently active (playing or paused).
func (*Video) Pause ¶
func (v *Video) Pause()
Pause pauses video playback, preserving the current playback position. Use Play() to resume from this position.
func (*Video) Play ¶
Play starts (or resumes) video decoding and playback. It creates internal frame/audio buffers, launches the decoding goroutine, and resets the playback clock. Calling Play while paused resumes from the paused position.
func (*Video) Preload ¶
Preload opens the media file, discovers the best video and audio streams, allocates and opens the corresponding codec contexts, and prepares the software scaler/resampler. It does not allocate any SDL resources.
func (*Video) PreloadDevice ¶
PreloadDevice prepares SDL‑specific resources for the video:
- creates a texture on the provided Screen's renderer for video frames,
- creates and binds an SDL AudioStream to the given audio device (if the video has an audio stream).
If Preload has not been called yet, PreloadDevice will call it first.
func (*Video) Present ¶
Present implements the Stimulus interface for Video by drawing the current frame (optionally clearing the screen first) and optionally updating the screen. It does not itself advance decoding; call Update separately.
func (*Video) Seek ¶
Seek moves the playback position to the specified time. Note: This stops the current playback and should be called before Play() or while the video is stopped.
func (*Video) Stop ¶
func (v *Video) Stop()
Stop stops the video playback and cleans up decoding resources.
func (*Video) Update ¶
Update advances decoding and playback state. It should be called frequently (typically once per frame) from the main experiment loop to:
- pull decoded frames/audio from internal buffers,
- push audio samples into the SDL AudioStream,
- update which frame should currently be displayed based on the FPS.
type VisualMask ¶
type VisualMask struct {
Size sdl.FPoint
Position sdl.FPoint
DotSize sdl.FPoint
BackgroundColor sdl.Color
DotColor sdl.Color
DotPercentage int
Texture *sdl.Texture
}
VisualMask is a pattern mask of random dots over a background (e.g. for masking stimuli); DotPercentage controls fill (0–100).
func NewVisualMask ¶
func NewVisualMask(width, height float32, dotWidth, dotHeight float32, bgColor, dotColor sdl.Color, dotPercentage int) *VisualMask
NewVisualMask creates a mask of the given size, dot size, background and dot colors, and dot percentage (0–100).
func (*VisualMask) GetPosition ¶
func (vm *VisualMask) GetPosition() sdl.FPoint
func (*VisualMask) Preload ¶
func (vm *VisualMask) Preload() error
func (*VisualMask) Present ¶
func (vm *VisualMask) Present(screen *io.Screen, clear, update bool) error
func (*VisualMask) SetPosition ¶
func (vm *VisualMask) SetPosition(pos sdl.FPoint)
func (*VisualMask) Unload ¶
func (vm *VisualMask) Unload() error