animate.xl

// *****************************************************************************
// animate.xl                                                      Tao3D project
// *****************************************************************************
//
// File description:
//
//     Module to interpolate angles and/or positions
//
//
//
//
//
//
//
//
// *****************************************************************************
// This software is licensed under the GNU General Public License v3
// (C) 2013, Catherine Burvelle <catherine@taodyne.com>
// (C) 2011-2014,2019, Christophe de Dinechin <christophe@dinechin.org>
// (C) 2011-2013, Jérôme Forissier <jerome@taodyne.com>
// *****************************************************************************
// This file is part of Tao3D
//
// Tao3D is free software: you can r redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// Tao3D is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with Tao3D, in a file named COPYING.
// If not, see <https://www.gnu.org/licenses/>.
// *****************************************************************************

module_description
    id "8cc936c7-ee1b-41b6-bb06-7de7bb1ef709"
    name "Animate"
    description "Animation utilities."
    import_name "Animate"
    author "Taodyne SAS"
    website "http://www.taodyne.com"
    version 1.04

module_description "fr",
    name "Animations"
    description "Fonctions d'animation."

// ============================================================================
//
//    Interpolation functions
//
// ============================================================================

interpolate S:real, TX:real, X:real ->
// ----------------------------------------------------------------------------
//    Interpolate variable x with target value tx, change ratio S
// ----------------------------------------------------------------------------
    X := S * TX + (1-S) * X
    if X <> TX then time


interpolate S:real, TX:real, TY:real, TZ:real, X:real, Y:real, Z:real ->
// ----------------------------------------------------------------------------
//    Interpolate 3 variables at a time (typically coordinates)
// ----------------------------------------------------------------------------
    interpolate S, TX, X
    interpolate S, TY, Y
    interpolate S, TZ, Z


interpolate_position S:real, TX:real,TY:real,TZ:real, X:real,Y:real,Z:real ->
// ----------------------------------------------------------------------------
//    Interpolate a position and translate accordingly
// ----------------------------------------------------------------------------
    interpolate S, TX, TY, TZ, X, Y, Z
    translate X, Y, Z


interpolate_xangle S:real, TX:real, X:real ->
// ----------------------------------------------------------------------------
//   Interpolate a rotation angle around X (horizontal axis)
// ----------------------------------------------------------------------------
    interpolate S, TX, X
    rotatex X


interpolate_yangle S:real, TY:real, Y:real ->
// ----------------------------------------------------------------------------
//    Interpolate a rotation angle along Y (vertical axis)
// ----------------------------------------------------------------------------
    interpolate S, TY, Y
    rotatey Y


interpolate_zangle S:real, TZ:real, Z:real ->
// ----------------------------------------------------------------------------
//   Interpolate through Z axis (depth)
// ----------------------------------------------------------------------------
    interpolate S, TZ, Z
    rotatez Z


interpolate_scale S:real, TScale:real, Scale:real ->
// ----------------------------------------------------------------------------
//   Interpolate scale
// ----------------------------------------------------------------------------
    interpolate S, TScale, Scale
    scale Scale, Scale, Scale


interpolate_scale2 S:real, TScale:real, Scale:real ->
// ----------------------------------------------------------------------------
//   Interpolate scale on X and Y only
// ----------------------------------------------------------------------------
    interpolate S, TScale, Scale
    scale Scale, Scale, 1



// ============================================================================
//
//   Adjustments based on refresh time
//
// ============================================================================

refresh_time_adjust S:real -> (1 - (1 - S) ^ (refresh_time * 60))
// ----------------------------------------------------------------------------
//   Adjust S for the refresh time
// ----------------------------------------------------------------------------


interpolate_rt S:real, TX:real, X:real ->
// ----------------------------------------------------------------------------
//   Like interpolate, but with an adjustment for the refresh-time
// ----------------------------------------------------------------------------
    interpolate refresh_time_adjust S, TX, X



interpolate_position_rt S:real, TX:real,TY:real,TZ:real, X:real,Y:real,Z:real ->
// ----------------------------------------------------------------------------
//    Interpolate a position and translate accordingly
// ----------------------------------------------------------------------------
    interpolate_position refresh_time_adjust S, TX, TY, TZ, X, Y, Z


interpolate_xangle_rt S:real, TX:real, X:real ->
// ----------------------------------------------------------------------------
//   Interpolate a rotation angle around X (horizontal axis)
// ----------------------------------------------------------------------------
    interpolate_xangle refresh_time_adjust S, TX, X


interpolate_yangle_rt S:real, TY:real, Y:real ->
// ----------------------------------------------------------------------------
//    Interpolate a rotation angle along Y (vertical axis)
// ----------------------------------------------------------------------------
    interpolate_yangle refresh_time_adjust S, TY, Y


interpolate_zangle_rt S:real, TZ:real, Z:real ->
// ----------------------------------------------------------------------------
//   Interpolate through Z axis (depth)
// ----------------------------------------------------------------------------
    interpolate_zangle refresh_time_adjust S, TZ, Z


interpolate_scale_rt S:real, TScale:real, Scale:real ->
// ----------------------------------------------------------------------------
//   Interpolate scale
// ----------------------------------------------------------------------------
    interpolate_scale refresh_time_adjust S, TScale, Scale



// ============================================================================
//
//   Fade-in and fade-out functions
//
// ============================================================================

fade_in  Value:real, Duration:real  -> -expm1(-5 * Value / Duration)
fade_out Value:real, Duration:real  -> 1+expm1(-5 * Value / Duration)
fade_at X:real, N:real -> if X < N - 1 then 0 else if X < N - 0.5 then 2 * (X - N + 1) ^ 2 else if X < N then 1 - 2 * (X - N) ^ 2 else 1
fade_out_at X:real, N:real -> 1 - fade_at (X, N)
fade_between X:real, A:real, B:real -> (fade_at (X, A) * fade_at ( -X, -B) )

at N:real -> show fade_at (page_time, N)
between A:real, B:real -> show fade_between (page_time, A, B)

fade_list T:real, I:real, X:real -> X * fade_at (T, 1)
fade_list T:real, I:real, X:real, Rest -> (X * fade_at (T, 1) + fade_list (T - I, I, Rest) )

disabled Body -> false



// ============================================================================
//
//   Helpers to skip to a given step in an animation
//
// ============================================================================

step -> 0.0
smooth_step -> 0.0
highest_step -> 0.0
previous_page_number -> 0


skip S:real ->
// ----------------------------------------------------------------------------
//   Skip by amount S in the animation
// ----------------------------------------------------------------------------
    step := step + S
    if highest_step > 0 then
        if S > 0 and step > highest_step and page_number < page_count then
            goto_page page_name(page_number+1)
        if S < 0 and step < 0 and page_number >= 1 then
            goto_page page_name(page_number - 1)
    if S <> 0 then
        refresh 0


skip_to S:real  ->
// ----------------------------------------------------------------------------
//   Skip directly to given animation step
// ----------------------------------------------------------------------------
    step := S
    refresh 0



skip_directly_to S:real  ->
// ----------------------------------------------------------------------------
//   Skip directly to given animation step
// ----------------------------------------------------------------------------
    step := S
    smooth_step := S
    previous_page_number := page_number


step_scale N:integer ->
// ----------------------------------------------------------------------------
//    Adjust scale for current animation step
// ----------------------------------------------------------------------------
    fade_out((smooth_step - N) ^2, 1)


compute_smooth_step ->
// ----------------------------------------------------------------------------
//    Compute the value of smooth step
// ----------------------------------------------------------------------------
    if previous_page_number < page_number then
        step := 0.0
        smooth_step := 0.0
        previous_page_number := page_number
    else if previous_page_number > page_number then
        if (step = 12345678) then
            step := highest_step
            smooth_step := highest_step
            previous_page_number := page_number
        else
            step := 12345678

    interpolate 0.05, step, smooth_step
    if abs (step - smooth_step) > 0.01 then
        page_time
    highest_step := 0.0


at_step N:integer ->
// ----------------------------------------------------------------------------
//   Show something at step N
// ----------------------------------------------------------------------------
    if N > highest_step then highest_step := N
    show fade_at(smooth_step, N)



// ============================================================================
//
//   Specifying the duration of pages
//
// ============================================================================

scheduled_duration -> 30.0


page_duration Duration:real, Name:text ->
// ----------------------------------------------------------------------------
//   Go to the named page after the given duration
// ----------------------------------------------------------------------------
    scheduled_duration := Duration
    if page_time > Duration then
        goto_page Name


page_duration Duration:real, Page:integer ->
// ----------------------------------------------------------------------------
//   Go to a given page number after the given duration
// ----------------------------------------------------------------------------
    locally
        page_duration Duration, page_name Page


page_duration Duration:real ->
// ----------------------------------------------------------------------------
//   Go to the next page after the given duration
// ----------------------------------------------------------------------------
    page_duration Duration, page_number + 1



// ============================================================================
//
//   Specifying something that happens at a given time
//
// ============================================================================

smooth T:real     -> if T < 0 then 0 else if T > 1 then 1 else T^2 * (3 - 2*T)
smooth_between T:real, Low:real, High:real -> smooth (T - Low) / (High - Low)

ratio             -> 0.0
down_ratio        -> 1 - ratio
smooth_ratio      -> smooth ratio
smooth_down_ratio -> 1 - smooth_ratio


[A:real..B:real, C:real..D:real] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body when page time is in the given intervals
// ----------------------------------------------------------------------------
    if page_time in A..D then
        [A..B]
            true
            Body
        [B..C]
            ratio := 1
            Body
        [C..D]
            ratio := 1-ratio
            Body


[A:real .. B:real] Body ->
// ----------------------------------------------------------------------------
//    Evaluate Body between page times A and B
// ----------------------------------------------------------------------------
    if page_time in A..B then
        if B > A then
            ratio := (page_time - A) / (B-A)
            Body


[A:real..B:real, ] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body when page time >= A, adjust ratio relative to A..B
// ----------------------------------------------------------------------------
    [A..B]
        true
        Body
    if page_time >= B then
        ratio := 1.0
        Body


[A:real.. ] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body when page_time >= A, set ratio to 1.0
// ----------------------------------------------------------------------------
    if page_time >= A then
        ratio := 1.0
        Body


Value:real in [A:real..B:real, C:real..D:real] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body if Value is in the given intervals
// ----------------------------------------------------------------------------
    if Value in A..D then
        Value in [A..B]
            true
            Body
        Value in [B..C]
            ratio := 1
            Body
        Value in [C..D]
            ratio := 1-ratio
            Body


Value:real in [A:real .. B:real] Body ->
// ----------------------------------------------------------------------------
//    Evaluate Body if Value is between A and B
// ----------------------------------------------------------------------------
    if Value in A..B then
        if B > A then
            ratio := (Value - A) / (B-A)
            Body


Value:real in [A:real..B:real, ] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body when Value >= A, adjust ratio relative to A..B
// ----------------------------------------------------------------------------
    Value in [A..B]
        true
        Body
    if Value >= B then
        ratio := 1.0
        Body


Value:real in [A:real.. ] Body ->
// ----------------------------------------------------------------------------
//   Evaluate Body when Value >= A, set ratio to 1.0
// ----------------------------------------------------------------------------
    if Value >= A then
        ratio := 1.0
        Body

// The following definitions are used in the documentation
value_in_interval Value:real, A:real, B:real, Body -> Value in [A..B] Body
value_in_intervals Value:real, A:real, B:real, C:real, D:real, Body -> Value in [A..B, C..D] Body
value_in_interval_or_greater Value:real, A:real, B:real, Body -> Value in [A..B, ] Body
value_greater_than Value: real, A:real -> Value in [A..] Body
page_time_in_interval A:real, B:real, Body -> [A..B] Body
page_time_in_intervals A:real, B:real, C:real, D:real, Body -> [A..B, C..D] Body
page_time_in_interval_or_greater Value:real, A:real, B:real, Body -> [A..B, ] Body
page_time_greater_than A:real -> [A..] Body