🌪️ Suck Function - Complete Technical Documentation#

Advanced radial pixel transformation with fluid dynamics

Overview#

The suck function represents a major advancement in KidLisp's transformation capabilities, implementing fluid dynamics principles for organic pixel displacement. It provides smooth, physics-based radial transformations that create vortex-like effects.

Mathematical Foundation#

Core Algorithm#

Based on polar coordinate transformation and irrotational vortex mathematics:

• Radial displacement: Pixels move along radial lines from center point
• Euclidean distance: Smooth circular patterns rather than rectilinear Manhattan distance
• Bilinear interpolation: Anti-aliasing for sub-pixel precision
• Wrapping behavior: Seamless edge wrapping for continuous loops
• Accumulation system: Continuous evolution through threshold-based execution

Physics Implementation#

The function implements irrotational vortex flow:

displacement = strength × (distance / maxDistance)
newRadius = currentRadius + displacement

This creates natural, fluid-like motion that feels organic and responsive.

Usage Patterns#

Basic Syntax#

(suck strength)                ; Radial effect from screen center
(suck strength centerX centerY) ; Radial effect from custom point

Parameter Details#

• strength: Positive = inward motion, negative = outward motion
• centerX, centerY: Optional center point (defaults to screen center)

Example Effects#

Static Effects#

(suck 1)           ; Strong inward vortex
(suck -0.5)        ; Gentle outward flow
(suck 0.1)         ; Subtle breathing effect

Animated Sequences#

; Pulsing vortex
(s1 (suck 0.5))    ; Gentle pulse every second
(s0.1 (suck 0.1))  ; Rapid micro-movements

; Complex timing patterns
["2s..." 1 0 -1]   ; Multi-phase timing with varying strength

Layered Compositions#

; Combined with other transformations
(blur 1)           ; Soften edges first
(suck 0.2)         ; Add subtle vortex
(contrast 1.2)     ; Enhance final result

Masked Applications#

; Selective area effects
(mask 64 64 128 128)  ; Define rectangular region
(suck 2)              ; Strong effect only in masked area
(unmask)              ; Remove mask

Technical Implementation#

Performance Optimizations#

• Accumulation thresholds: Prevents excessive computation
• Bilinear sampling: Smooth anti-aliased results
• Deferred execution: Compatible with embedded layer system
• Memory efficiency: In-place pixel manipulation

Integration Features#

• Embedded layer support: Works with embed command
• Mask compatibility: Respects drawing masks
• Timing integration: Works with s() timing expressions
• API consistency: Follows KidLisp function patterns

Advanced Use Cases#

Fluid Simulations#

; Simulated fluid dynamics
(def vortex_strength (sin (* frame 0.1)))
(suck vortex_strength)

Interactive Effects#

; Mouse-driven vortex
(suck 0.5 mouse_x mouse_y)

Complex Animations#

; Multi-center vortex system
(repeat 3 i
  (suck 0.3 (* i 100) (* i 80)))

Implementation History#

Development Timeline#

• 2025-09-06: ✅ Core implementation with polar coordinate mathematics
• 2025-09-06: ✅ Bilinear interpolation for anti-aliasing
• 2025-09-06: ✅ Edge wrapping and accumulation system
• 2025-09-06: ✅ KidLisp integration and deferred execution
• 2025-09-06: ✅ Embedded layer compatibility

Design Decisions#

1. Euclidean vs Manhattan distance: Chose Euclidean for smooth circular patterns
2. Bilinear vs nearest neighbor: Chose bilinear for quality anti-aliasing
3. Accumulation system: Enables continuous evolution and performance control
4. Polar coordinates: Natural fit for radial transformations

Comparison with Other Transforms#

The suck function represents the most mathematically sophisticated transformation in KidLisp, incorporating real physics principles for natural, organic motion.

For usage examples and integration patterns, see the main KidLisp documentation and the zoom-vs-suck implementation report.