SMPTE Timecodes & Timelines, Sequences and Keyframes.

[TheNachoBIT]

I'm making this a draft for now, this PR is to document the progress i've been making so far with this experiment.

This experiment can also fail. If you see any kind of flaw, please feel free to point it out.

The final goals of this (if succeeds) are:

• Allow Interpoli to be more general-purpose, so it can be used for animation, video editing, motion graphics, videogames, sound design, etc.
• Allow for both developers and people with expertise in other artistic areas to have the same concepts.
• Allow for potential optimizations with interpolations at a large-scale (lots of characters being animated at once in a videogame, a big timeline that contains a lot of properties, etc.)

Progress.

• [x] Learn how to rebase this PR to upstream Interpoli.
• [x] Rebase.
• [x] SMPTE Timecodes (Basics).
  • [x] Basics.
  • [x] Make it run on full integers (frames being isize instead of f64).
  • [x] Add syncronization based on nanoframes (to allow 23.97fps, 23.98fps, 29.97fps, ... to run properly).
  • [x] Add '==' functionality (specially for asserts).
  • [x] Make as_string() prettier (print out '00:00:00:00' instead of '0:0:0:0').
  • [x] Jump to specific parts of the Timecode.
  • [x] Add Utilities (will be useful for Timelines & Tweening).
• [x] Timelines (Basics).
  • [x] Get basic time functionality.
  • [x] Create new(...) functions.
  • [x] Add Sequences to the mix.
  • [x] Add Timeline Nesting
  • [x] Add AnimationEngine for Tweening
  • [x] Get Animated Values
• [x] Timelines (Extras).
  • [x] ~Add OpenTimelineIO Compatibility. (https://github.com/AcademySoftwareFoundation/OpenTimelineIO)~ (Definetly in a later PR, because this current one is getting really big).
  • [x] Add being able to go backwards.
  • [x] Add thread-safety.
  • [x] Being able to resume the sequence after hitting a sequence end.
• [x] Sequence (Basics).
  • [x] Add tree functionality.
  • [x] Get and/or create keyframes.
  • [x] Be able to use it with all types available.
  • [x] Add ways to get keyframes between timestamps.
  • [x] Add multiple keyframe support.
• [ ] Keyframes.
  • [x] Basic storage functionality.
  • [ ] Add States. (Easing, Hold, etc.)
  • [ ] Add functions to make API easier.
• [x] AnimationEngine (Basics).
  • [x] Basic Tweening Functionality.
  • [x] Add states.
• [x] SMPTE Timecodes (Extras)
  • [x] ~Sync based on denominators (Get help from @xorgy for this).~ (Probably in a later PR)
  • [x] Better utility implementations.
  • [x] Search for edge-use cases.
• [x] For review
  • [x] Fix errors and apply recommendations detected via clippy
  • [x] Make sure to apply cargo fmt (i always forget about that command ;_;)
  • [x] Remove unwraps or functionality that can trigger a panic.

SMPTE Timecodes (Update 2).

SMPTE Timecodes are time units that are set like a clock: HH:MM:SS:FF (Hours, Minutes, Seconds, Frames).

For convenience, there's a macro that helps visualize this concept better in code:

tcode_hmsf!(01:23:45:01) // A timecode with Hours (h), Minutes (m), Seconds (s) and Frames (f).

~(Sadly, Rust's macros don't allow me to use ":" so i have to use ";" instead, if there's a workaround for this, please let me know)~

EDIT: I fixed it!

Timecodes can be used as a Timestamp, or as a value for a Timeline, by setting the Framerate:

tcode_hmsf_framerate!(00:01:02:56, Framerate::Fixed(20.0))

There's Framerate::Fixed(n) and Framerate::Interpolated(n). Once Timelines become a thing, fixed framerates will round up to the nearest frame when the tween is calculated, which will be useful for frame-by-frame animations. Interpolated frames on the other hand, will interpolate regardless of the framerate you're running (unless you explicitly set "hold" frames).

Timecodes with a framerate can advance and reverse by frames, seconds, minutes, hours and use Duration (Instant coming soon).

Example: Play one second frame-by-frame.

let mut time = tcode_hmsf_framerate!(00:00:00:00, Framerate::Fixed(24.0));

for i in 0..24 {
    time.next_frame();
}

println!("{:?}", time.as_string()); // Outputs "00:00:01:00 (24.0)"

Example: Add by Duration.

use std::time::Duration;

let mut time = tcode_hmsf_framerate!(00:00:00:00, Framerate::Fixed(24.0));

time.add_by_duration(Duration::from_millis(999));

println!("{:?}", time.as_string()); // Outputs "00:00:00:23 (24.0)"

Example: Sub by Duration.

use std::time::Duration;

let mut time = tcode_hmsf_framerate!(01:00:00:00, Framerate::Fixed(24.0)); // 1 hour

time.sub_by_duration(Duration::from_secs(1800));

println!("{:?}", time.as_string()); // Outputs "00:30:00:00 (24.0)" (30 minutes)

The draft repository contains more examples in form of tests inside of lib.rs.

This is all of the progress for now, for any questions, please feel free to ask :)