core_animation/
lib.rs

1//! Rust bindings for macOS Core Animation with builder APIs.
2//!
3//! Core Animation is Apple's GPU-accelerated rendering system. This crate
4//! wraps it with ergonomic builders, focusing on **particle effects** and
5//! **layer composition**.
6//!
7//! # Quick Start
8//!
9//! Particles burst outward from a point:
10//!
11//! ```ignore
12//! use std::f64::consts::PI;
13//! use core_animation::prelude::*;
14//!
15//! let emitter = CAEmitterLayerBuilder::new()
16//!     .position(320.0, 240.0)
17//!     .shape(EmitterShape::Point)
18//!     .particle(|p| {
19//!         p.birth_rate(100.0)           // spawn rate
20//!             .lifetime(5.0)            // seconds until particle disappears
21//!             .velocity(80.0)           // movement speed
22//!             .emission_range(PI * 2.0) // spread angle (full circle)
23//!             .color(Color::CYAN)
24//!             .image(ParticleImage::soft_glow(64))
25//!     })
26//!     .build();
27//!
28//! window.container().add_sublayer(&emitter);
29//! window.show_for(10.seconds());
30//! ```
31//!
32//! Simpler API for the same effect:
33//!
34//! ```ignore
35//! let burst = PointBurstBuilder::new(320.0, 240.0)
36//!     .velocity(100.0)
37//!     .color(Color::PINK)
38//!     .build();
39//! ```
40//!
41//! # Examples
42//!
43//! See [`examples/README.md`](https://github.com/sassman/t-rec-rs/tree/main/crates/core-animation/examples)
44//! for runnable demos with screenshots.
45//!
46//! ```bash
47//! cargo run --example emitter
48//! ```
49//!
50//! # Modules
51//!
52//! - [`animation_builder`] - GPU-accelerated animations ([`CABasicAnimationBuilder`](animation_builder::CABasicAnimationBuilder),
53//!   [`KeyPath`](animation_builder::KeyPath), [`Easing`](animation_builder::Easing))
54//! - [`particles`] - Particle emitter builders ([`CAEmitterLayerBuilder`](particles::CAEmitterLayerBuilder),
55//!   [`PointBurstBuilder`](particles::PointBurstBuilder), [`ParticleImage`](particles::ParticleImage))
56//! - [`window`] - Test window for examples ([`WindowBuilder`])
57//!
58//! # Types
59//!
60//! **This crate:**
61//! - [`Color`] - RGBA color with presets (`Color::CYAN`, `Color::rgb(...)`)
62//! - [`CALayerBuilder`] - Generic layer builder
63//! - [`CAShapeLayerBuilder`] - Vector shape builder
64//! - [`CATextLayerBuilder`] - Text rendering builder with fonts and alignment
65//! - [`DurationExt`] - `5.seconds()`, `500.millis()` syntax
66//!
67//! **Re-exported from Apple frameworks:**
68//! - [`CALayer`], [`CAShapeLayer`], [`CATransform3D`] - Core Animation
69//! - [`CGPoint`](objc2_core_foundation::CGPoint), [`CGSize`](objc2_core_foundation::CGSize),
70//!   [`CGRect`](objc2_core_foundation::CGRect) - Geometry
71//! - [`CGPath`](objc2_core_graphics::CGPath), [`CGColor`](objc2_core_graphics::CGColor) - Graphics
72//!
73//! Use [`prelude`] to import common types.
74
75#![cfg(target_os = "macos")]
76
77pub mod animation_builder;
78mod color;
79mod duration_ext;
80mod layer_builder;
81mod layer_ext;
82pub mod particles;
83mod shape_layer_builder;
84mod text_layer_builder;
85pub mod window;
86
87// Re-export Color type
88pub use color::Color;
89
90// Re-export the main types from objc2-quartz-core
91pub use objc2_quartz_core::{CALayer, CAShapeLayer, CATextLayer, CATransform3D};
92
93// Re-export our builders
94pub use layer_builder::CALayerBuilder;
95pub use shape_layer_builder::CAShapeLayerBuilder;
96pub use text_layer_builder::{CATextLayerBuilder, TextAlign, Truncation};
97
98// Re-export window types
99pub use window::{Screen, Window, WindowBuilder, WindowLevel, WindowStyle};
100
101// Re-export duration extension
102pub use duration_ext::DurationExt;
103
104// Re-export layer extension
105pub use layer_ext::CALayerExt;
106
107// Re-export dependencies for convenience
108pub use objc2_core_foundation;
109pub use objc2_core_graphics;
110pub use objc2_core_text;
111pub use objc2_quartz_core;
112
113/// Prelude module for convenient imports.
114pub mod prelude {
115    // Color type
116    pub use crate::color::Color;
117
118    // Animation builder types
119    pub use crate::animation_builder::{CABasicAnimationBuilder, Easing, KeyPath, Repeat};
120
121    // Builders
122    pub use crate::layer_builder::CALayerBuilder;
123    pub use crate::particles::{
124        CAEmitterCellBuilder, CAEmitterLayerBuilder, EmitterMode, EmitterShape, ParticleImage,
125        PointBurstBuilder, RenderMode,
126    };
127    pub use crate::shape_layer_builder::CAShapeLayerBuilder;
128    pub use crate::text_layer_builder::{CATextLayerBuilder, TextAlign, Truncation};
129    pub use crate::window::{Screen, Window, WindowBuilder, WindowLevel, WindowStyle};
130
131    // Duration extension for ergonomic timing
132    pub use crate::duration_ext::DurationExt;
133
134    // Layer extension for snake_case methods
135    pub use crate::layer_ext::CALayerExt;
136
137    // Core Animation types
138    pub use crate::{CALayer, CAShapeLayer, CATextLayer, CATransform3D};
139    pub use objc2_quartz_core::CABasicAnimation;
140
141    // Core Foundation types (geometry, strings, collections, run loop)
142    pub use objc2_core_foundation::{
143        kCFRunLoopDefaultMode, kCFTypeDictionaryKeyCallBacks, kCFTypeDictionaryValueCallBacks,
144        CFAttributedString, CFDictionary, CFDictionaryKeyCallBacks, CFDictionaryValueCallBacks,
145        CFIndex, CFRetained, CFRunLoop, CFString, CFStringBuiltInEncodings, CFTimeInterval,
146        CGAffineTransform, CGFloat, CGPoint, CGRect, CGSize,
147    };
148
149    // Core Graphics types (context, colors, paths, transforms, display)
150    pub use objc2_core_graphics::{
151        CGAffineTransformIdentity, CGColor, CGContext, CGDirectDisplayID, CGDisplayBounds,
152        CGMainDisplayID, CGPath,
153    };
154
155    // Core Text types (fonts, lines, string attributes)
156    pub use objc2_core_text::{
157        kCTFontAttributeName, kCTForegroundColorAttributeName, CTFont, CTLine,
158    };
159
160    // AppKit types (NSApplication)
161    pub use objc2_app_kit::NSApplication;
162
163    // Smart pointer for Objective-C objects
164    pub use objc2::rc::Retained;
165}
core_animation/lib.rs

core_animation/
lib.rs
