voirs_spatial/visual_audio/
types.rs

1//! Core types for visual audio integration
2
3use crate::{Position3D, Result};
4use serde::{Deserialize, Serialize};
5use std::collections::HashMap;
6use std::time::{Duration, Instant};
7
8/// Visual display interface for spatial audio cues
9pub trait VisualDisplay: Send + Sync {
10    /// Render a visual effect at the specified position
11    fn render_effect(&mut self, effect: &VisualEffect) -> Result<()>;
12
13    /// Clear all visual effects
14    fn clear_all(&mut self) -> Result<()>;
15
16    /// Update display refresh
17    fn update(&mut self) -> Result<()>;
18
19    /// Check if the display is ready
20    fn is_ready(&self) -> bool;
21
22    /// Get display capabilities
23    fn capabilities(&self) -> VisualDisplayCapabilities;
24
25    /// Get display identifier
26    fn display_id(&self) -> String;
27}
28
29/// Visual effect for spatial audio indication
30#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct VisualEffect {
32    /// Effect identifier
33    pub id: String,
34
35    /// Effect name
36    pub name: String,
37
38    /// Visual elements composing this effect
39    pub elements: Vec<VisualElement>,
40
41    /// Effect duration
42    pub duration: Duration,
43
44    /// Whether effect should loop
45    pub looping: bool,
46
47    /// Effect priority (higher numbers take precedence)
48    pub priority: u8,
49
50    /// 3D position for the visual effect
51    pub position: Position3D,
52
53    /// Associated audio source
54    pub audio_source_id: Option<String>,
55}
56
57/// Individual visual element within an effect
58#[derive(Debug, Clone, Serialize, Deserialize)]
59pub struct VisualElement {
60    /// Start time within the effect
61    pub start_time: Duration,
62
63    /// Element duration
64    pub duration: Duration,
65
66    /// Visual element type
67    pub element_type: VisualElementType,
68
69    /// Color information
70    pub color: ColorRGBA,
71
72    /// Intensity/brightness (0.0 to 1.0)
73    pub intensity: f32,
74
75    /// Size/scale factor
76    pub size: f32,
77
78    /// Animation parameters
79    pub animation: Option<AnimationParams>,
80
81    /// Distance-based attenuation
82    pub distance_attenuation: f32,
83}
84
85/// Types of visual elements
86#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
87pub enum VisualElementType {
88    /// Point light indicator
89    PointLight,
90
91    /// Directional light beam
92    DirectionalLight,
93
94    /// Particle effect
95    ParticleEffect,
96
97    /// 3D geometric shape
98    Shape(ShapeType),
99
100    /// Text/label display
101    Text,
102
103    /// Progress bar/meter
104    ProgressBar,
105
106    /// Waveform visualization
107    Waveform,
108
109    /// Frequency spectrum display
110    Spectrum,
111
112    /// Custom visual effect
113    Custom(String),
114}
115
116/// Shape types for visual elements
117#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
118pub enum ShapeType {
119    /// Sphere
120    Sphere,
121
122    /// Cube
123    Cube,
124
125    /// Cylinder
126    Cylinder,
127
128    /// Cone (directional indicator)
129    Cone,
130
131    /// Ring/circle
132    Ring,
133
134    /// Arrow (directional)
135    Arrow,
136}
137
138/// Color representation with alpha
139#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
140pub struct ColorRGBA {
141    /// Red component (0.0-1.0)
142    pub r: f32,
143
144    /// Green component (0.0-1.0)
145    pub g: f32,
146
147    /// Blue component (0.0-1.0)
148    pub b: f32,
149
150    /// Alpha/transparency (0.0-1.0)
151    pub a: f32,
152}
153
154/// Animation parameters for visual elements
155#[derive(Debug, Clone, Serialize, Deserialize)]
156pub struct AnimationParams {
157    /// Animation type
158    pub animation_type: AnimationType,
159
160    /// Animation speed multiplier
161    pub speed: f32,
162
163    /// Animation amplitude
164    pub amplitude: f32,
165
166    /// Phase offset
167    pub phase: f32,
168
169    /// Easing function
170    pub easing: EasingFunction,
171}
172
173/// Animation types
174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
175pub enum AnimationType {
176    /// Static (no animation)
177    Static,
178
179    /// Pulsing intensity
180    Pulse,
181
182    /// Smooth fade in/out
183    Fade,
184
185    /// Rotation around axis
186    Rotate,
187
188    /// Scaling up/down
189    Scale,
190
191    /// Position oscillation
192    Oscillate,
193
194    /// Spiral movement
195    Spiral,
196
197    /// Custom animation
198    Custom(String),
199}
200
201/// Easing functions for smooth animation
202#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
203pub enum EasingFunction {
204    /// Linear interpolation
205    Linear,
206
207    /// Ease in (slow start)
208    EaseIn,
209
210    /// Ease out (slow end)
211    EaseOut,
212
213    /// Ease in-out (slow start and end)
214    EaseInOut,
215
216    /// Bounce effect
217    Bounce,
218
219    /// Elastic effect
220    Elastic,
221}
222
223/// Visual display capabilities
224#[derive(Debug, Clone, Serialize, Deserialize)]
225pub struct VisualDisplayCapabilities {
226    /// Maximum simultaneous effects
227    pub max_concurrent_effects: usize,
228
229    /// Supported visual element types
230    pub supported_elements: Vec<VisualElementType>,
231
232    /// Color depth (bits per channel)
233    pub color_depth: u8,
234
235    /// Refresh rate (Hz)
236    pub refresh_rate: f32,
237
238    /// 3D positioning support
239    pub spatial_support: bool,
240
241    /// Animation support
242    pub animation_support: bool,
243
244    /// Transparency/alpha support
245    pub alpha_support: bool,
246
247    /// Display resolution
248    pub resolution: (u32, u32),
249
250    /// Field of view (degrees)
251    pub field_of_view: Option<f32>,
252
253    /// Device-specific features
254    pub features: HashMap<String, String>,
255}
256
257/// Direction zones for color coding
258#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
259pub enum DirectionZone {
260    /// Front (±30 degrees)
261    Front,
262
263    /// Left side (30-150 degrees)
264    Left,
265
266    /// Back (150-210 degrees)
267    Back,
268
269    /// Right side (210-330 degrees)
270    Right,
271
272    /// Above listener
273    Above,
274
275    /// Below listener
276    Below,
277}
278
279/// Performance metrics for visual audio processing
280#[derive(Debug, Clone, Serialize, Deserialize)]
281pub struct VisualAudioMetrics {
282    /// Visual processing latency (ms)
283    pub processing_latency: f32,
284
285    /// Audio-visual synchronization accuracy (ms RMS error)
286    pub sync_accuracy: f32,
287
288    /// Active effects count
289    pub active_effects: usize,
290
291    /// Frame rate (FPS)
292    pub frame_rate: f32,
293
294    /// GPU utilization percentage
295    pub gpu_utilization: f32,
296
297    /// Effect cache hit rate
298    pub cache_hit_rate: f32,
299
300    /// User satisfaction rating
301    pub user_satisfaction: f32,
302
303    /// Resource usage statistics
304    pub resource_usage: VisualResourceUsage,
305}
306
307/// Visual resource usage tracking
308#[derive(Debug, Clone, Serialize, Deserialize)]
309pub struct VisualResourceUsage {
310    /// CPU usage percentage
311    pub cpu_usage: f32,
312
313    /// GPU memory usage (MB)
314    pub gpu_memory_usage: f32,
315
316    /// System memory usage (MB)
317    pub system_memory_usage: f32,
318
319    /// Effect library size
320    pub effect_library_size: usize,
321
322    /// Active display count
323    pub active_displays: usize,
324
325    /// Render queue size
326    pub render_queue_size: usize,
327}
328
329// Helper structs for internal processing
330
331#[derive(Debug)]
332pub(crate) struct VisualEvent {
333    pub(crate) source_id: String,
334    pub(crate) event_type: VisualEventType,
335    pub(crate) intensity: f32,
336    pub(crate) color_hint: Option<ColorRGBA>,
337    pub(crate) timestamp: Instant,
338}
339
340#[derive(Debug)]
341pub(crate) struct SpatialVisualEvent {
342    pub(crate) base_event: VisualEvent,
343    pub(crate) position: Position3D,
344    pub(crate) distance: f32,
345    pub(crate) attenuation: f32,
346    pub(crate) direction_zone: DirectionZone,
347}
348
349#[derive(Debug, Clone, PartialEq, Eq)]
350pub(crate) enum VisualEventType {
351    FrequencyBand(FrequencyBand),
352    Onset,
353    Beat,
354    Downbeat,
355    SpectralChange,
356    Silence,
357    Custom(String),
358}
359
360#[derive(Debug, Clone, Copy, PartialEq, Eq)]
361pub(crate) enum FrequencyBand {
362    Low,
363    Mid,
364    High,
365}
366
367// Default implementations
368
369impl Default for VisualAudioMetrics {
370    fn default() -> Self {
371        Self {
372            processing_latency: 0.0,
373            sync_accuracy: 0.0,
374            active_effects: 0,
375            frame_rate: 0.0,
376            gpu_utilization: 0.0,
377            cache_hit_rate: 0.0,
378            user_satisfaction: 5.0,
379            resource_usage: VisualResourceUsage::default(),
380        }
381    }
382}
383
384impl Default for VisualResourceUsage {
385    fn default() -> Self {
386        Self {
387            cpu_usage: 0.0,
388            gpu_memory_usage: 0.0,
389            system_memory_usage: 0.0,
390            effect_library_size: 0,
391            active_displays: 0,
392            render_queue_size: 0,
393        }
394    }
395}
voirs_spatial/visual_audio/types.rs

voirs_spatial/visual_audio/
types.rs
