effects

package
v0.6.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 24, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package effects defines deterministic, device-neutral lighting effect types.

Example (CustomEffect) 
effect := &examplePulse{
	caps:  Capabilities{LightType: device.LightTypeMatrix, Width: 2, Height: 1},
	color: Color{Hue: 30, Saturation: 100, Brightness: 100, Kelvin: 3500},
}

frames := Render(effect, 100*time.Millisecond, 300*time.Millisecond)
fmt.Println(len(frames))
fmt.Println(frames[0].Frame.Colors[0].Brightness)

Output:
3
25

Index

Examples

Constants

View Source 
const (
	// DefaultRunStep is used by RunSequence when a run does not specify a positive step.
	DefaultRunStep = 100 * time.Millisecond
)

Variables

View Source 
var (
	// ErrEmptyFrame is returned when a frame contains no colors.
	ErrEmptyFrame = errors.New("empty frame")
	// ErrInvalidFrame is returned when a frame has invalid dimensions or too few colors.
	ErrInvalidFrame = errors.New("invalid frame")
	// ErrInvalidDeviceState is returned when cached device state cannot form a frame.
	ErrInvalidDeviceState = errors.New("invalid device state")
)
View Source 
var (
	// ErrUnknownEffect is returned when an effect ID is not registered.
	ErrUnknownEffect = errors.New("unknown effect")
	// ErrDuplicateEffect is returned when registering the same effect ID twice.
	ErrDuplicateEffect = errors.New("duplicate effect")
	// ErrInvalidDefinition is returned when an effect definition is invalid.
	ErrInvalidDefinition = errors.New("invalid effect definition")
	// ErrUnsupportedDeviceKind is returned when an effect does not support capabilities.
	ErrUnsupportedDeviceKind = errors.New("unsupported device kind")
	// ErrInvalidConfig is returned when an effect config is invalid.
	ErrInvalidConfig = errors.New("invalid effect config")
)
View Source 
var (
	// ErrMissingEffect is returned when a Runner has no effect.
	ErrMissingEffect = errors.New("missing effect")
	// ErrMissingRenderer is returned when a Runner has no renderer.
	ErrMissingRenderer = errors.New("missing renderer")
	// ErrInvalidStep is returned when a Runner has a non-positive step.
	ErrInvalidStep = errors.New("step must be positive")
)
View Source 
var DefaultColor = Color{Hue: 220, Saturation: 100, Brightness: 100, Kelvin: 3500}

DefaultColor is used when a palette does not define a requested color.

Functions

func BoolParam added in v0.4.4 

func BoolParam(params map[string]any, key string) (bool, error)

BoolParam returns a validated boolean parameter.

func ChoiceParam added in v0.4.4 

func ChoiceParam(params map[string]any, key string) (string, error)

ChoiceParam returns a validated string choice parameter.

func ClampPercent 

func ClampPercent(value float64) float64

ClampPercent clamps value to the valid percentage range used by Color fields.

func DurationParam added in v0.4.4 

func DurationParam(params map[string]any, key string) (time.Duration, error)

DurationParam returns a validated duration parameter.

func FrameSize added in v0.4.4 

func FrameSize(width, height int) int

FrameSize returns the number of colors needed for a width by height frame.

func NumberParam added in v0.4.4 

func NumberParam(params map[string]any, key string) (float64, error)

NumberParam returns a validated number parameter.

func Register added in v0.4.2 

func Register(def EffectDefinition) error

Register adds def to the global effect registry.

Example 
err := Register(EffectDefinition{
	ID:          EffectID("example_pulse"),
	Label:       "Example Pulse",
	Description: "Pulse the first logical cell.",
	DeviceKinds: []device.LightType{device.LightTypeMatrix},
	Params: []ParamDefinition{
		{
			Key:     "color",
			Label:   "Color",
			Kind:    ParamColor,
			Default: Color{Hue: 30, Saturation: 100, Brightness: 100, Kelvin: 3500},
		},
	},
	New: func(config Config, caps Capabilities) (Effect, error) {
		color, err := ColorParam(config.Params, "color")
		if err != nil {
			return nil, err
		}
		return &examplePulse{caps: caps, color: color}, nil
	},
})
if err != nil {
	fmt.Println(err)
	return
}

effect, err := New(Config{ID: EffectID("example_pulse")}, Capabilities{
	LightType: device.LightTypeMatrix,
	Width:     2,
	Height:    1,
})
if err != nil {
	fmt.Println(err)
	return
}

frame, ok := effect.Next(time.Second)
fmt.Println(ok)
fmt.Println(frame.Width)

Output:
true
2

func RunSequence 

func RunSequence(ctx context.Context, renderer Renderer, runs ...RunConfig) error

RunSequence runs effects in order through renderer.

func SetFrameColor added in v0.4.4 

func SetFrameColor(frame *Frame, x, y int, color Color) bool

SetFrameColor sets the color at x,y and reports whether the coordinate is valid.

func ValidateFrame added in v0.4.4 

func ValidateFrame(frame Frame) error

ValidateFrame validates frame dimensions and color count.

Types

type AdaptOptions added in v0.4.1 

type AdaptOptions struct {
	Reduction ReductionStrategy
}

AdaptOptions configures logical frame adaptation to a device surface.

type Capabilities 

type Capabilities struct {
	LightType         device.LightType
	Zones             int
	Width             int
	Height            int
	ChainLength       int
	ChainOrientations []device.Orientation
	HasColor          bool
	TemperatureRange  device.TemperatureRange
}

Capabilities describes the logical rendering surface available to effects.

func CapabilitiesFromDevice 

func CapabilitiesFromDevice(d device.Device) Capabilities

CapabilitiesFromDevice derives effect capabilities from an existing device.

type Color 

type Color = device.Color

Color is the logical HSBK color used by generated frames.

It aliases device.Color so frames can be used with existing lifxlan-go device and message APIs without conversion.

func BlankColor added in v0.4.4 

func BlankColor() Color

BlankColor returns the standard off color used for blank frame cells.

func ColorParam added in v0.4.4 

func ColorParam(params map[string]any, key string) (Color, error)

ColorParam returns a validated color parameter.

func FrameColor added in v0.4.4 

func FrameColor(frame Frame, x, y int) (Color, bool)

FrameColor returns the color at x,y and whether the coordinate is valid.

func WithBrightness 

func WithBrightness(c Color, brightness float64) Color

WithBrightness returns c with brightness clamped to the valid percentage range.

type Comet added in v0.6.4 

type Comet struct {
	// contains filtered or unexported fields
}

Comet moves a bright head with a fading tail over a dimmed background.

func NewComet added in v0.6.4 

func NewComet(cfg CometConfig) *Comet

NewComet returns a Comet effect.

func (*Comet) FrameAtPhase added in v0.6.4 

func (c *Comet) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the comet cycle. During the first traversal, phase [0,1), the tail does not wrap ahead of the head. Later phases use steady-state wrapping, so a completed loop can trail across the cycle boundary.

func (*Comet) Next added in v0.6.4 

func (c *Comet) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*Comet) Reset added in v0.6.4 

func (c *Comet) Reset()

Reset returns the effect to the start of its cycle.

type CometConfig added in v0.6.4 

type CometConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Axis is the axis the comet travels along. Empty uses FlowAxisHorizontal.
	Axis FlowAxis
	// Period is how long one full traversal takes when advanced by Next. Zero uses
	// defaultFlowPeriod. Ignored by FrameAtPhase.
	Period time.Duration
	// HeadSize is the number of logical cells kept at full head brightness. Zero
	// uses defaultCometHeadSize.
	HeadSize int
	// TailSize is the number of logical cells fading behind the head. Zero uses
	// defaultCometTailSize.
	TailSize int
	// BackgroundBrightnessFactor scales the background as a fraction of palette
	// brightness. Zero uses defaultCometBackgroundBrightnessFactor.
	BackgroundBrightnessFactor float64
	// PeakBrightnessFactor scales the comet head as a fraction of palette
	// brightness. Values above 1 boost the head and tail, clamped to 100. Zero
	// uses defaultCometPeakBrightnessFactor.
	PeakBrightnessFactor float64
	// TailCurve shapes the tail falloff. Higher values drop the tail toward the
	// background faster. Zero uses defaultCometTailCurve.
	TailCurve float64
	// TailSaturationFactor is the saturation retained at the end of the tail, as a
	// fraction of accent saturation. Zero uses defaultCometTailSaturationFactor.
	TailSaturationFactor float64
}

CometConfig configures a Comet effect.

type ConcentricFrames 

type ConcentricFrames struct {
	// contains filtered or unexported fields
}

ConcentricFrames draws matrix borders according to Direction.

func NewConcentricFrames 

func NewConcentricFrames(cfg ConcentricFramesConfig) *ConcentricFrames

NewConcentricFrames returns a ConcentricFrames effect.

func (*ConcentricFrames) Next 

func (c *ConcentricFrames) Next(dt time.Duration) (Frame, bool)

Next returns the next concentric frame.

func (*ConcentricFrames) Reset 

func (c *ConcentricFrames) Reset()

Reset resets the effect.

type ConcentricFramesConfig 

type ConcentricFramesConfig struct {
	Capabilities Capabilities
	Direction    Direction
	Colors       []Color
	Cycles       int
}

ConcentricFramesConfig configures a ConcentricFrames effect.

type Config added in v0.4.2 

type Config struct {
	ID     EffectID       `json:"id"`
	Params map[string]any `json:"params,omitempty"`
}

Config is a serializable, target-free effect configuration.

type DeviceFrame added in v0.4.1 

type DeviceFrame struct {
	ChainIndex  int
	Colors      []Color
	SendWidth   int
	Height      int
	Orientation device.Orientation
	Duration    time.Duration
}

DeviceFrame is a packet-independent frame adapted to a device surface.

For matrix devices, ChainIndex identifies the matrix chain, SendWidth/Height describe the physical send layout, and Orientation preserves the chain orientation for later packet rendering. For non-matrix devices, ChainIndex is 0 and Orientation is OrientationRightSideUp.

func AdaptFrameToSurface added in v0.4.1 

func AdaptFrameToSurface(frame Frame, surface device.Surface, opts AdaptOptions) ([]DeviceFrame, error)

AdaptFrameToSurface adapts a target-free logical frame to a device surface.

Matrix adaptation samples colors from the logical frame by surface cell coordinates. Cells outside the logical frame are padded with blank colors, cells outside the surface are cropped, and hidden matrix cells are blanked. Adapted matrix DeviceFrames keep packet/send dimensions and do not apply orientation; Orientation is carried so a later renderer can rotate for the physical device.

type Direction 

type Direction int

Direction defines how ConcentricFrames moves between matrix borders. 

const (
	// DirectionInwards draws borders from the outside in.
	DirectionInwards Direction = iota
	// DirectionOutwards draws borders from the inside out.
	DirectionOutwards
	// DirectionInOut draws borders from the outside in, then back out.
	DirectionInOut
	// DirectionOutIn draws borders from the inside out, then back in.
	DirectionOutIn
)

type Effect 

type Effect interface {
	Next(dt time.Duration) (Frame, bool)
	Reset()
}

Effect produces deterministic logical frames.

func New added in v0.4.2 

func New(config Config, caps Capabilities) (Effect, error)

New validates config and returns a configured effect for caps.

type EffectDefinition added in v0.4.2 

type EffectDefinition struct {
	ID          EffectID
	Label       string
	Description string
	DeviceKinds []device.LightType
	Params      []ParamDefinition
	New         func(Config, Capabilities) (Effect, error)
}

EffectDefinition describes a registered effect and its configurable params.

func Definition added in v0.4.2 

func Definition(id EffectID) (EffectDefinition, bool)

Definition returns the definition for id.

func Definitions added in v0.4.2 

func Definitions() []EffectDefinition

Definitions returns registered definitions in deterministic ID order.

type EffectID added in v0.4.2 

type EffectID string

EffectID identifies a registered effect. 

const (
	// EffectComet identifies the Comet effect.
	EffectComet EffectID = "comet"
	// EffectSparkle identifies the Sparkle effect.
	EffectSparkle EffectID = "sparkle"
	// EffectScanner identifies the Scanner effect.
	EffectScanner EffectID = "scanner"
	// EffectSolid identifies the Solid effect.
	EffectSolid EffectID = "solid"
	// EffectGradient identifies the Gradient effect.
	EffectGradient EffectID = "gradient"
	// EffectGradientDrift identifies the GradientDrift effect.
	EffectGradientDrift EffectID = "gradient_drift"
	// EffectPaletteSweep identifies the PaletteSweep effect.
	EffectPaletteSweep EffectID = "palette_sweep"
	// EffectSweep identifies the Sweep effect.
	EffectSweep EffectID = "sweep"
	// EffectWaterfall identifies the Waterfall matrix effect.
	EffectWaterfall EffectID = "waterfall"
	// EffectRockets identifies the Rockets matrix effect.
	EffectRockets EffectID = "rockets"
	// EffectSnake identifies the Snake matrix effect.
	EffectSnake EffectID = "snake"
	// EffectWorm identifies the Worm matrix effect.
	EffectWorm EffectID = "worm"
	// EffectWave identifies the Wave matrix effect.
	EffectWave EffectID = "wave"
	// EffectConcentricFrames identifies the ConcentricFrames matrix effect.
	EffectConcentricFrames EffectID = "concentric_frames"
	// EffectFlow identifies the Flow effect.
	EffectFlow EffectID = "flow"
	// EffectRing identifies the Ring matrix effect.
	EffectRing EffectID = "ring"
)

type Flow added in v0.6.0 

type Flow struct {
	// contains filtered or unexported fields
}

Flow travels a brightness crest across the surface while palette colors scroll along with it, so every zone or pixel takes part.

Sweep, by contrast, lights a single cell over a flat background. On a long strip that reads as a dot rather than motion, and it leaves most of the surface holding one color.

func NewFlow added in v0.6.0 

func NewFlow(cfg FlowConfig) *Flow

NewFlow returns a Flow effect.

func (*Flow) FrameAtPhase added in v0.6.0 

func (f *Flow) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the cycle, where whole numbers are the same point in the traversal. Phase may run backwards: passing a decreasing sequence reverses the travel, and negative values are valid.

This exists for callers that build a timeline ahead of playback rather than streaming frames. They know the position of every event they are about to emit and need the frame for it, which stepping an effect forward cannot express: two events at the same moment, or events generated out of order, would each advance the effect and drift from the position they were meant to represent.

func (*Flow) Next added in v0.6.0 

func (f *Flow) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*Flow) Reset added in v0.6.0 

func (f *Flow) Reset()

Reset returns the effect to the start of its cycle.

type FlowAxis added in v0.6.0 

type FlowAxis string

FlowAxis is the axis a crest travels along. It is deliberately not called a direction: Direction already describes inward and outward travel for concentric effects, and this chooses an axis rather than a sense along one. 

const (
	// FlowAxisHorizontal travels along x, the length of a strip.
	FlowAxisHorizontal FlowAxis = "horizontal"
	// FlowAxisVertical travels along y. A single-row surface has no y to travel, so
	// it behaves as horizontal there.
	FlowAxisVertical FlowAxis = "vertical"
	// FlowAxisDiagonal travels along x+y, crossing a matrix corner to corner.
	FlowAxisDiagonal FlowAxis = "diagonal"
)

type FlowBrightnessMode added in v0.6.2 

type FlowBrightnessMode string

FlowBrightnessMode controls whether Flow modulates brightness or only scrolls palette colors. 

const (
	// FlowBrightnessCrest scrolls colors and applies a moving brightness crest.
	FlowBrightnessCrest FlowBrightnessMode = "crest"
	// FlowBrightnessConstant scrolls colors without changing their brightness.
	FlowBrightnessConstant FlowBrightnessMode = "constant"
)

type FlowConfig added in v0.6.0 

type FlowConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Axis is the axis the crest travels along. Empty uses FlowAxisHorizontal.
	Axis FlowAxis
	// Direction controls the travel direction along Axis. Empty uses
	// FlowDirectionForward.
	Direction FlowDirection
	// Period is how long one full traversal takes when the effect is advanced by
	// Next. Zero uses defaultFlowPeriod. Ignored by FrameAtPhase, which is given a
	// position directly.
	Period time.Duration
	// Floor is how lit the trough stays, as a fraction of the crest. Zero uses
	// defaultFlowFloor.
	Floor float64
	// BrightnessMode controls whether brightness moves as a crest or stays at the
	// palette color brightness. Empty uses FlowBrightnessCrest.
	BrightnessMode FlowBrightnessMode
	// Sampling controls whether palette colors step cell-by-cell or interpolate
	// between adjacent stops. Empty uses FlowSamplingStep.
	Sampling FlowSamplingMode
}

FlowConfig configures a Flow effect.

type FlowDirection added in v0.6.4 

type FlowDirection string

FlowDirection controls the direction a flow travels along its axis. 

const (
	// FlowDirectionForward moves the visible pattern from lower position indexes
	// toward higher position indexes.
	FlowDirectionForward FlowDirection = "forward"
	// FlowDirectionReverse moves the visible pattern from higher position indexes
	// toward lower position indexes.
	FlowDirectionReverse FlowDirection = "reverse"
)

type FlowSamplingMode added in v0.6.4 

type FlowSamplingMode string

FlowSamplingMode controls how palette colors are sampled between logical cells. 

const (
	// FlowSamplingStep uses whole-cell palette steps, preserving existing output.
	FlowSamplingStep FlowSamplingMode = "step"
	// FlowSamplingInterpolate blends adjacent palette stops for sub-cell motion.
	FlowSamplingInterpolate FlowSamplingMode = "interpolate"
)

type Frame 

type Frame struct {
	Colors   []Color
	Width    int
	Height   int
	Duration time.Duration
}

Frame is a target-free logical color frame.

func FrameFromDeviceState added in v0.4.6 

func FrameFromDeviceState(d device.Device, duration time.Duration) (Frame, error)

FrameFromDeviceState converts cached device color state into a logical Frame.

The function is pure: it does not query the network or mutate d. Matrix devices are converted through device.SurfaceFromDevice so chain layout, hidden cells, send width, and orientation are interpreted consistently with AdaptFrameToSurface.

func NewFrame added in v0.4.4 

func NewFrame(width, height int, duration time.Duration, color Color) Frame

NewFrame returns a logical frame filled with color.

type FrameAt 

type FrameAt struct {
	At    time.Duration
	Frame Frame
}

FrameAt is a logical frame at a deterministic timeline offset.

func Render 

func Render(effect Effect, step, duration time.Duration) []FrameAt

Render produces timestamped frames from effect using a fixed deterministic step.

Example 
palette := Palette{
	Base: []Color{
		{Hue: 0, Saturation: 100, Brightness: 50, Kelvin: 3500},
		{Hue: 120, Saturation: 100, Brightness: 50, Kelvin: 3500},
	},
}
effect := NewGradient(GradientConfig{
	Capabilities: Capabilities{LightType: device.LightTypeMultiZone, Zones: 2},
	Palette:      palette,
})

frames := Render(effect, time.Second, 2*time.Second)
fmt.Println(len(frames))
fmt.Println(frames[0].At)
fmt.Println(frames[0].Frame.Width)

Output:
2
0s
2

type Gradient 

type Gradient struct {
	// contains filtered or unexported fields
}

Gradient fills the logical surface with deterministic palette stops.

func NewGradient 

func NewGradient(cfg GradientConfig) *Gradient

NewGradient returns a Gradient effect.

func (*Gradient) Next 

func (g *Gradient) Next(dt time.Duration) (Frame, bool)

Next returns the next gradient frame.

func (*Gradient) Reset 

func (g *Gradient) Reset()

Reset resets the effect.

type GradientConfig 

type GradientConfig struct {
	Capabilities Capabilities
	Palette      Palette
}

GradientConfig configures a Gradient effect.

type GradientDrift added in v0.6.4 

type GradientDrift struct {
	// contains filtered or unexported fields
}

GradientDrift scrolls palette colors across a multizone or matrix surface without changing palette brightness.

func NewGradientDrift added in v0.6.4 

func NewGradientDrift(cfg GradientDriftConfig) *GradientDrift

NewGradientDrift returns a GradientDrift effect.

func (*GradientDrift) FrameAtPhase added in v0.6.4 

func (g *GradientDrift) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the drift cycle. Whole phases address the same palette position, and negative phases wrap.

func (*GradientDrift) Next added in v0.6.4 

func (g *GradientDrift) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*GradientDrift) Reset added in v0.6.4 

func (g *GradientDrift) Reset()

Reset returns the effect to the start of its cycle.

type GradientDriftConfig added in v0.6.4 

type GradientDriftConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Axis is the axis the palette scrolls along. Empty uses FlowAxisHorizontal.
	Axis FlowAxis
	// Direction controls the travel direction along Axis. Empty uses
	// FlowDirectionForward.
	Direction FlowDirection
	// Period is how long one full drift takes when advanced by Next. Zero uses
	// defaultFlowPeriod. Ignored by FrameAtPhase.
	Period time.Duration
	// Sampling controls whether palette colors step cell-by-cell or interpolate
	// between adjacent stops. Empty uses FlowSamplingStep.
	Sampling FlowSamplingMode
}

GradientDriftConfig configures a GradientDrift effect.

type Palette 

type Palette struct {
	Name        string
	Base        []Color
	Accents     []Color
	Backgrounds []Color
}

Palette groups colors for deterministic effects.

func PaletteParam added in v0.4.4 

func PaletteParam(params map[string]any, key string) (Palette, error)

PaletteParam returns a validated palette parameter.

func (Palette) Accent 

func (p Palette) Accent() Color

Accent returns the first accent color, falling back to Primary.

func (Palette) AccentAt 

func (p Palette) AccentAt(index int) Color

AccentAt returns a deterministic accent for index, falling back to ColorAt.

func (Palette) Background 

func (p Palette) Background() Color

Background returns the first background color, falling back to Secondary.

func (Palette) ColorAt 

func (p Palette) ColorAt(index int) Color

ColorAt returns a deterministic color for index from base colors followed by accents.

func (Palette) GradientStops 

func (p Palette) GradientStops(count int) []Color

GradientStops returns count deterministic stops from backgrounds, base colors, then accents.

func (Palette) Primary 

func (p Palette) Primary() Color

Primary returns the first base color, or DefaultColor when no base color is set.

func (Palette) Secondary 

func (p Palette) Secondary() Color

Secondary returns the second base color, falling back to Primary.

type PaletteSweep added in v0.6.4 

type PaletteSweep struct {
	// contains filtered or unexported fields
}

PaletteSweep moves a multi-color band over a dim drifting gradient background.

func NewPaletteSweep added in v0.6.4 

func NewPaletteSweep(cfg PaletteSweepConfig) *PaletteSweep

NewPaletteSweep returns a PaletteSweep effect.

func (*PaletteSweep) FrameAtPhase added in v0.6.4 

func (p *PaletteSweep) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the sweep cycle. Whole phases address the same point, and negative phases wrap.

func (*PaletteSweep) Next added in v0.6.4 

func (p *PaletteSweep) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*PaletteSweep) Reset added in v0.6.4 

func (p *PaletteSweep) Reset()

Reset returns the effect to the start of its cycle.

type PaletteSweepConfig added in v0.6.4 

type PaletteSweepConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Axis is the axis the band travels along. Empty uses FlowAxisHorizontal.
	Axis FlowAxis
	// Direction controls the travel direction along Axis. Empty uses
	// FlowDirectionForward.
	Direction FlowDirection
	// Period is how long one full traversal takes when advanced by Next. Zero uses
	// defaultFlowPeriod. Ignored by FrameAtPhase.
	Period time.Duration
	// BandSize is the moving band width in logical cells. If zero, BandFraction is
	// used instead.
	BandSize int
	// BandFraction is the moving band width as a fraction of the surface span.
	// Zero uses defaultPaletteSweepBandFraction.
	BandFraction float64
	// BackgroundBrightnessFactor scales the drifting background gradient as a
	// fraction of palette brightness. Zero uses
	// defaultPaletteSweepBackgroundBrightnessFactor.
	BackgroundBrightnessFactor float64
	// TailBrightnessFactor is the brightness retained at the trailing edge of the
	// band. Zero uses defaultPaletteSweepTailBrightnessFactor.
	TailBrightnessFactor float64
	// Sampling controls whether gradient colors step cell-by-cell or interpolate
	// between adjacent stops. Empty uses FlowSamplingStep.
	Sampling FlowSamplingMode
}

PaletteSweepConfig configures a PaletteSweep effect.

type ParamChoice added in v0.4.2 

type ParamChoice struct {
	Value string
	Label string
}

ParamChoice describes one allowed choice value.

type ParamDefinition added in v0.4.2 

type ParamDefinition struct {
	Key      string
	Label    string
	Kind     ParamKind
	Default  any
	Min      *float64
	Max      *float64
	Step     *float64
	Choices  []ParamChoice
	Required bool
}

ParamDefinition describes one effect configuration parameter.

type ParamKind added in v0.4.2 

type ParamKind string

ParamKind identifies a configurable parameter type. 

const (
	// ParamNumber is a numeric parameter.
	ParamNumber ParamKind = "number"
	// ParamBool is a boolean parameter.
	ParamBool ParamKind = "bool"
	// ParamChoiceKind is a string choice parameter.
	ParamChoiceKind ParamKind = "choice"
	// ParamColor is a Color parameter.
	ParamColor ParamKind = "color"
	// ParamPalette is a Palette parameter.
	ParamPalette ParamKind = "palette"
	// ParamDuration is a time.Duration parameter.
	ParamDuration ParamKind = "duration"
)

type PhaseEffect added in v0.6.0 

type PhaseEffect interface {
	Effect
	FrameAtPhase(phase float64, duration time.Duration) Frame
}

PhaseEffect can return a deterministic frame for an absolute cycle position.

Whole phases address the same point in the effect cycle, and negative phases wrap. This is useful for offline timeline generation where frames may be requested out of order or more than once for the same timestamp.

type Random added in v0.4.4 

type Random struct {
	// contains filtered or unexported fields
}

Random is a deterministic random source for effects.

Effects that need random-looking output should keep their own Random and call Reset from the effect's Reset method.

func NewRandom added in v0.4.4 

func NewRandom(seed uint64) *Random

NewRandom returns a deterministic random source initialized with seed.

func (*Random) Color added in v0.4.4 

func (r *Random) Color(colors []Color) Color

Color returns a deterministic color from colors.

If colors is empty, Color returns DefaultColor.

func (*Random) Float64 added in v0.4.4 

func (r *Random) Float64() float64

Float64 returns a deterministic value in [0.0, 1.0).

func (*Random) IntN added in v0.4.4 

func (r *Random) IntN(n int) int

IntN returns a deterministic integer in [0, n).

If n <= 0, IntN returns 0.

func (*Random) PaletteColor added in v0.4.4 

func (r *Random) PaletteColor(palette Palette) Color

PaletteColor returns a deterministic color from palette colors.

Base colors are considered first, followed by accents and backgrounds. If palette does not define any colors, PaletteColor returns DefaultColor.

func (*Random) Reset added in v0.4.4 

func (r *Random) Reset()

Reset rewinds r to its initial seed.

func (*Random) Seed added in v0.4.4 

func (r *Random) Seed() uint64

Seed returns the seed used by r.

type ReductionStrategy added in v0.4.1 

type ReductionStrategy int

ReductionStrategy defines how many logical colors collapse into one color. 

const (
	// ReductionFirst uses the first logical color in the reduced range.
	ReductionFirst ReductionStrategy = iota
	// ReductionAverage averages hue circularly and other color fields linearly.
	ReductionAverage
)

type Renderer 

type Renderer interface {
	RenderFrame(context.Context, Frame) error
}

Renderer renders logical frames to a target-specific destination.

type Ring added in v0.6.0 

type Ring struct {
	// contains filtered or unexported fields
}

Ring expands a soft ring from the center of a matrix surface.

func NewRing added in v0.6.0 

func NewRing(cfg RingConfig) *Ring

NewRing returns a Ring effect.

func (*Ring) FrameAtPhase added in v0.6.0 

func (r *Ring) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the cycle, where whole numbers are the same point in the expansion. Phase may be negative and wraps to the equivalent forward position.

func (*Ring) Next added in v0.6.0 

func (r *Ring) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*Ring) Reset added in v0.6.0 

func (r *Ring) Reset()

Reset returns the effect to the start of its cycle.

type RingConfig added in v0.6.0 

type RingConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Period is how long one full expansion takes when the effect is advanced by
	// Next. Zero uses defaultRingPeriod. Ignored by FrameAtPhase, which is given a
	// position directly.
	Period time.Duration
	// Width is the ring thickness in logical cells. Zero uses defaultRingWidth.
	Width float64
	// Floor is how lit the background stays, as a fraction of the ring brightness.
	// Zero uses defaultRingFloor.
	Floor float64
}

RingConfig configures a Ring effect.

type Rockets 

type Rockets struct {
	// contains filtered or unexported fields
}

Rockets moves a single pixel through the matrix in row-major order.

func NewRockets 

func NewRockets(cfg RocketsConfig) *Rockets

NewRockets returns a Rockets effect.

func (*Rockets) Next 

func (r *Rockets) Next(dt time.Duration) (Frame, bool)

Next returns the next rockets frame.

func (*Rockets) Reset 

func (r *Rockets) Reset()

Reset resets the effect.

type RocketsConfig 

type RocketsConfig struct {
	Capabilities Capabilities
	Colors       []Color
	Cycles       int
}

RocketsConfig configures a Rockets effect.

type RunConfig 

type RunConfig struct {
	Effect   Effect
	Duration time.Duration
	Step     time.Duration
}

RunConfig describes one effect run in a live sequence.

type Runner 

type Runner struct {
	Effect   Effect
	Renderer Renderer
	Step     time.Duration
}

Runner runs an effect live through a target-bound renderer.

func NewRunner 

func NewRunner(effect Effect, renderer Renderer, step time.Duration) *Runner

NewRunner returns a Runner for effect and renderer using step as the fallback frame duration.

func (*Runner) Run 

func (r *Runner) Run(ctx context.Context) error

Run renders frames until the effect ends, the context is canceled, or rendering fails.

type Scanner added in v0.6.4 

type Scanner struct {
	// contains filtered or unexported fields
}

Scanner moves a soft band back and forth across a multizone or matrix surface.

func NewScanner added in v0.6.4 

func NewScanner(cfg ScannerConfig) *Scanner

NewScanner returns a Scanner effect.

func (*Scanner) FrameAtPhase added in v0.6.4 

func (s *Scanner) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the scanner cycle. Whole phases address the same point, negative phases wrap, and half phases are the opposite end of the bounce.

func (*Scanner) Next added in v0.6.4 

func (s *Scanner) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*Scanner) Reset added in v0.6.4 

func (s *Scanner) Reset()

Reset returns the effect to the start of its cycle.

type ScannerConfig added in v0.6.4 

type ScannerConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Axis is the axis the scanner travels along. Empty uses FlowAxisHorizontal.
	Axis FlowAxis
	// Period is how long one full bounce cycle takes when advanced by Next. Zero
	// uses defaultFlowPeriod. Ignored by FrameAtPhase.
	Period time.Duration
	// Width is the soft band width in logical cells. Zero uses defaultScannerWidth.
	Width float64
	// BackgroundBrightnessFactor scales the background as a fraction of palette
	// brightness. Zero uses defaultScannerBackgroundBrightnessFactor.
	BackgroundBrightnessFactor float64
	// PeakBrightnessFactor scales the scan peak as a fraction of palette
	// brightness. Values above 1 boost the peak, clamped to 100. Zero uses
	// defaultScannerPeakBrightnessFactor.
	PeakBrightnessFactor float64
}

ScannerConfig configures a Scanner effect.

type Snake 

type Snake struct {
	// contains filtered or unexported fields
}

Snake moves a trailing segment through a serpentine matrix path.

func NewSnake 

func NewSnake(cfg SnakeConfig) *Snake

NewSnake returns a Snake effect.

func (*Snake) Next 

func (s *Snake) Next(dt time.Duration) (Frame, bool)

Next returns the next snake frame.

func (*Snake) Reset 

func (s *Snake) Reset()

Reset resets the effect.

type SnakeConfig 

type SnakeConfig struct {
	Capabilities Capabilities
	Size         int
	Color        Color
	Cycles       int
}

SnakeConfig configures a Snake effect.

type Solid 

type Solid struct {
	// contains filtered or unexported fields
}

Solid fills every logical zone or pixel with the same color.

func NewSolid 

func NewSolid(cfg SolidConfig) *Solid

NewSolid returns a Solid effect.

func (*Solid) Next 

func (s *Solid) Next(dt time.Duration) (Frame, bool)

Next returns the next solid frame.

func (*Solid) Reset 

func (s *Solid) Reset()

Reset resets the effect.

type SolidConfig 

type SolidConfig struct {
	Capabilities Capabilities
	Color        Color
}

SolidConfig configures a Solid effect.

type Sparkle added in v0.6.4 

type Sparkle struct {
	// contains filtered or unexported fields
}

Sparkle lights deterministic, random-looking cells over a dimmed background.

func NewSparkle added in v0.6.4 

func NewSparkle(cfg SparkleConfig) *Sparkle

NewSparkle returns a Sparkle effect.

func (*Sparkle) FrameAtPhase added in v0.6.4 

func (s *Sparkle) FrameAtPhase(phase float64, duration time.Duration) Frame

FrameAtPhase returns the frame at an absolute position in the sparkle cycle. Whole phases address the same point, and negative phases wrap.

func (*Sparkle) Next added in v0.6.4 

func (s *Sparkle) Next(dt time.Duration) (Frame, bool)

Next advances the effect by dt and returns the frame at the new position.

func (*Sparkle) Reset added in v0.6.4 

func (s *Sparkle) Reset()

Reset returns the effect to the start of its cycle.

type SparkleConfig added in v0.6.4 

type SparkleConfig struct {
	Capabilities Capabilities
	Palette      Palette
	// Density is the fraction of a cycle where each cell is lit. Zero uses
	// defaultSparkleDensity.
	Density float64
	// Decay controls how quickly each sparkle fades. Larger values fade faster.
	// Zero uses defaultSparkleDecay.
	Decay float64
	// BackgroundFloor is how lit the background stays as a fraction of palette
	// brightness. Zero uses defaultSparkleFloor.
	BackgroundFloor float64
	// Floor is a compatibility alias for BackgroundFloor.
	Floor float64
	// PeakBrightnessFactor scales active sparkle brightness. Values above 1 boost
	// sparkles above palette brightness, clamped to 100. Zero uses
	// defaultSparklePeak.
	PeakBrightnessFactor float64
	// Seed changes the deterministic sparkle pattern.
	Seed uint64
	// Period is how long one full sparkle cycle takes when advanced by Next. Zero
	// uses defaultSparklePeriod. Ignored by FrameAtPhase.
	Period time.Duration
}

SparkleConfig configures a Sparkle effect.

type Sweep 

type Sweep struct {
	// contains filtered or unexported fields
}

Sweep moves one accent color across a background frame.

func NewSweep 

func NewSweep(cfg SweepConfig) *Sweep

NewSweep returns a Sweep effect.

func (*Sweep) Next 

func (s *Sweep) Next(dt time.Duration) (Frame, bool)

Next returns the next sweep frame.

func (*Sweep) Reset 

func (s *Sweep) Reset()

Reset resets the effect.

type SweepConfig 

type SweepConfig struct {
	Capabilities Capabilities
	Palette      Palette
}

SweepConfig configures a Sweep effect.

type Waterfall 

type Waterfall struct {
	// contains filtered or unexported fields
}

Waterfall fills rows cumulatively with a centered color strip.

func NewWaterfall 

func NewWaterfall(cfg WaterfallConfig) *Waterfall

NewWaterfall returns a Waterfall effect.

func (*Waterfall) Next 

func (w *Waterfall) Next(dt time.Duration) (Frame, bool)

Next returns the next waterfall frame.

func (*Waterfall) Reset 

func (w *Waterfall) Reset()

Reset resets the effect.

type WaterfallConfig 

type WaterfallConfig struct {
	Capabilities Capabilities
	Colors       []Color
	Cycles       int
}

WaterfallConfig configures a Waterfall effect.

type Wave added in v0.4.6 

type Wave struct {
	// contains filtered or unexported fields
}

Wave displaces matrix columns upward as a wave front moves across the frame.

func NewWave added in v0.4.6 

func NewWave(cfg WaveConfig) *Wave

NewWave returns a Wave effect.

func (*Wave) Next added in v0.4.6 

func (w *Wave) Next(dt time.Duration) (Frame, bool)

Next returns the next wave frame.

func (*Wave) Reset added in v0.4.6 

func (w *Wave) Reset()

Reset resets the effect.

type WaveConfig added in v0.4.6 

type WaveConfig struct {
	Capabilities Capabilities
	Initial      *Frame
	Palette      Palette
	Amplitude    int
	Width        int
	Waves        int
	Cycles       int
}

WaveConfig configures a Wave effect.

type Worm 

type Worm struct {
	// contains filtered or unexported fields
}

Worm moves short batches of pixels through a serpentine matrix path.

func NewWorm 

func NewWorm(cfg WormConfig) *Worm

NewWorm returns a Worm effect.

func (*Worm) Next 

func (w *Worm) Next(dt time.Duration) (Frame, bool)

Next returns the next worm frame.

func (*Worm) Reset 

func (w *Worm) Reset()

Reset resets the effect.

type WormConfig 

type WormConfig struct {
	Capabilities Capabilities
	Size         int
	Color        Color
	Cycles       int
}

WormConfig configures a Worm effect.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.