262 lines
7.0 KiB
Markdown
262 lines
7.0 KiB
Markdown
# Oscillation Patterns
|
|
|
|
Quick reference for oscillation patterns used with value providers in the Berry Animation Framework.
|
|
|
|
## Available Oscillation Patterns
|
|
|
|
These waveform constants can be used with `oscillator_value`:
|
|
|
|
| Constant | Value | Alias Functions | Behavior | Use Case |
|
|
|----------|-------|-----------------|----------|----------|
|
|
| `SAWTOOTH` | 1 | `linear`, `ramp` | Linear ramp up | Uniform motion |
|
|
| `TRIANGLE` | 2 | `triangle` | Linear up then down | Sharp direction changes |
|
|
| `SQUARE` | 3 | `square` | Alternating min/max | On/off effects |
|
|
| `COSINE` | 4 | `smooth` | Smooth cosine wave | Natural oscillation |
|
|
| `SINE` | 5 | `sine` | Pure sine wave | Classic wave motion |
|
|
| `EASE_IN` | 6 | `ease_in` | Slow start, fast end | Smooth acceleration |
|
|
| `EASE_OUT` | 7 | `ease_out` | Fast start, slow end | Smooth deceleration |
|
|
| `ELASTIC` | 8 | `elastic` | Spring overshoot | Bouncy effects |
|
|
| `BOUNCE` | 9 | `bounce` | Ball bouncing | Physics simulation |
|
|
|
|
## DSL Usage
|
|
|
|
### With Oscillator Value Provider
|
|
```dsl
|
|
# Basic oscillator with different waveform types
|
|
set breathing = oscillator_value(min_value=50, max_value=255, duration=3000, form=COSINE)
|
|
set pulsing = ease_in(min_value=0, max_value=255, duration=2000)
|
|
set bouncing = oscillator_value(min_value=10, max_value=240, duration=4000, form=TRIANGLE)
|
|
```
|
|
|
|
### Using Alias Functions
|
|
```dsl
|
|
# These are equivalent to oscillator_value with specific forms
|
|
set smooth_fade = smooth(min_value=50, max_value=255, duration=3000) # form=COSINE
|
|
set sine_wave = sine(min_value=50, max_value=255, duration=3000) # form=SINE
|
|
set linear_sweep = linear(min_value=0, max_value=255, duration=2000) # form=SAWTOOTH
|
|
set triangle_wave = triangle(min_value=10, max_value=240, duration=4000) # form=TRIANGLE
|
|
```
|
|
|
|
### In Animations
|
|
```dsl
|
|
color blue = 0x0000FF
|
|
set breathing = smooth(min_value=100, max_value=255, duration=4000)
|
|
|
|
animation breathing_blue = solid(color=blue)
|
|
breathing_blue.opacity = breathing
|
|
run breathing_blue
|
|
```
|
|
|
|
## Pattern Characteristics
|
|
|
|
### SAWTOOTH (Linear)
|
|
- **Constant speed** throughout the cycle
|
|
- **Sharp reset** from max back to min
|
|
- **Best for**: Uniform sweeps, mechanical movements
|
|
|
|
```
|
|
Value
|
|
^
|
|
| /| /|
|
|
| / | / |
|
|
| / | / |
|
|
| / | / |
|
|
| / | / |
|
|
|/ |/ |
|
|
+------+------+----> Time
|
|
```
|
|
|
|
```dsl
|
|
set linear_brightness = linear(min_value=0, max_value=255, duration=2000)
|
|
```
|
|
|
|
### COSINE (Smooth)
|
|
- **Gradual acceleration** and deceleration
|
|
- **Natural feeling** transitions
|
|
- **Best for**: Breathing effects, gentle fades
|
|
|
|
```dsl
|
|
set breathing_effect = smooth(min_value=50, max_value=255, duration=3000)
|
|
```
|
|
|
|
### SINE (Pure Wave)
|
|
- **Classic sine wave** starting from minimum
|
|
- **Smooth acceleration** and deceleration like cosine but phase-shifted
|
|
- **Best for**: Wave effects, classic oscillations, audio-visual sync
|
|
|
|
```
|
|
Value
|
|
^
|
|
| ___
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
|/ \___
|
|
+--------------------+----> Time
|
|
```
|
|
|
|
```dsl
|
|
set wave_motion = sine(min_value=0, max_value=255, duration=2000)
|
|
```
|
|
|
|
### TRIANGLE
|
|
- **Linear acceleration** to midpoint, then **linear deceleration**
|
|
- **Sharp direction changes** at extremes
|
|
- **Best for**: Bouncing effects, sharp transitions
|
|
|
|
```
|
|
Value
|
|
^
|
|
| /\
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
| / \
|
|
|/ \
|
|
+-------------+----> Time
|
|
```
|
|
|
|
```dsl
|
|
set bounce_position = triangle(min_value=5, max_value=55, duration=2000)
|
|
```
|
|
|
|
### SQUARE
|
|
- **Alternating** between min and max values
|
|
- **Instant transitions** with configurable duty cycle
|
|
- **Best for**: On/off effects, strobing, digital patterns
|
|
|
|
```
|
|
Value
|
|
^
|
|
| +---+ +---+
|
|
| | | | |
|
|
| | | | |
|
|
| | +-----+ |
|
|
| | |
|
|
| | |
|
|
+-+-------------+----> Time
|
|
```
|
|
|
|
```dsl
|
|
set strobe_effect = square(min_value=0, max_value=255, duration=500, duty_cycle=25)
|
|
```
|
|
|
|
### EASE_IN
|
|
- **Slow start**, **fast finish**
|
|
- **Smooth acceleration** curve
|
|
- **Best for**: Starting animations, building intensity
|
|
|
|
```dsl
|
|
set accelerating = ease_in(min_value=0, max_value=255, duration=3000)
|
|
```
|
|
|
|
### EASE_OUT
|
|
- **Fast start**, **slow finish**
|
|
- **Smooth deceleration** curve
|
|
- **Best for**: Ending animations, gentle stops
|
|
|
|
```dsl
|
|
set decelerating = ease_out(min_value=255, max_value=0, duration=3000)
|
|
```
|
|
|
|
## Value Progression Examples
|
|
|
|
For a cycle from 0 to 100 over 2000ms:
|
|
|
|
| Time | SAWTOOTH | COSINE | SINE | TRIANGLE | EASE_IN | EASE_OUT |
|
|
|------|----------|--------|------|----------|---------|----------|
|
|
| 0ms | 0 | 0 | 0 | 0 | 0 | 0 |
|
|
| 500ms| 25 | 15 | 50 | 50 | 6 | 44 |
|
|
| 1000ms| 50 | 50 | 100 | 100 | 25 | 75 |
|
|
| 1500ms| 75 | 85 | 50 | 50 | 56 | 94 |
|
|
| 2000ms| 100 | 100 | 0 | 0 | 100 | 100 |
|
|
|
|
## Common Patterns
|
|
|
|
### Breathing Effect
|
|
```dsl
|
|
color soft_white = 0xC0C0C0
|
|
set breathing = smooth(min_value=80, max_value=255, duration=4000)
|
|
|
|
animation breathing_light = solid(color=soft_white)
|
|
breathing_light.opacity = breathing
|
|
run breathing_light
|
|
```
|
|
|
|
### Position Sweep
|
|
```dsl
|
|
strip length 60
|
|
color red = 0xFF0000
|
|
set sweeping_position = linear(min_value=0, max_value=59, duration=3000)
|
|
|
|
animation position_sweep = beacon_animation(
|
|
color=red,
|
|
position=sweeping_position,
|
|
beacon_size=3,
|
|
fade_size=1
|
|
)
|
|
run position_sweep
|
|
```
|
|
|
|
### Wave Motion
|
|
```dsl
|
|
color purple = 0x8000FF
|
|
set wave_brightness = sine(min_value=50, max_value=255, duration=2500)
|
|
|
|
animation wave_effect = solid(color=purple)
|
|
wave_effect.opacity = wave_brightness
|
|
run wave_effect
|
|
```
|
|
|
|
### Bouncing Effect
|
|
```dsl
|
|
color green = 0x00FF00
|
|
set bounce_size = triangle(min_value=1, max_value=8, duration=1000)
|
|
|
|
animation bouncing_pulse = beacon_animation(
|
|
color=green,
|
|
position=30,
|
|
beacon_size=bounce_size,
|
|
fade_size=1
|
|
)
|
|
run bouncing_pulse
|
|
```
|
|
|
|
### Accelerating Fade
|
|
```dsl
|
|
color blue = 0x0000FF
|
|
set fade_in = ease_in(min_value=0, max_value=255, duration=5000)
|
|
|
|
animation accelerating_fade = solid(color=blue)
|
|
accelerating_fade.opacity = fade_in
|
|
run accelerating_fade
|
|
```
|
|
|
|
### Strobe Effect
|
|
```dsl
|
|
color white = 0xFFFFFF
|
|
set strobe_pattern = square(min_value=0, max_value=255, duration=200, duty_cycle=10)
|
|
|
|
animation strobe_light = solid(color=white)
|
|
strobe_light.opacity = strobe_pattern
|
|
run strobe_light
|
|
```
|
|
|
|
## Tips
|
|
|
|
- **COSINE (smooth)**: Most natural for breathing and gentle effects
|
|
- **SINE**: Classic wave motion, perfect for audio-visual sync and pure oscillations
|
|
- **SAWTOOTH (linear)**: Best for consistent sweeps and mechanical movements
|
|
- **TRIANGLE**: Creates sharp, bouncing transitions
|
|
- **EASE_IN**: Perfect for building up intensity
|
|
- **EASE_OUT**: Ideal for gentle fade-outs
|
|
- **ELASTIC**: Spring-like effects with overshoot
|
|
- **BOUNCE**: Physics-based bouncing effects
|
|
- **SQUARE**: Good for on/off blinking effects
|
|
|
|
Choose the oscillation pattern that matches the feeling you want to create in your animation. |