Skip to content

Commit

Permalink
move the vanim doc from 'vanim.py' to 'vanim.rst'
Browse files Browse the repository at this point in the history
  • Loading branch information
@gottadiveintopython
gottadiveintopython committed Nov 29, 2023
1 parent 9ada07a commit fc36039
Show file tree
Hide file tree
Showing 2 changed files with 160 additions and 164 deletions.
161 changes: 160 additions & 1 deletion sphinx/vanim.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,164 @@
VAnim: Advanced Animation
=========================

:func:`asynckivy.animate` is an imitation of an existing API, :class:`kivy.animation.Animation`,
which is fine because it's easy to use for the people who are already familiar with Kivy.
The problem is ... it's a pretty specialized API because:

.. automodule:: asynckivy.vanim
* It can only animate attributes. Sometimes, I just need the value without actually assigning it to an attribute.
(:func:`asynckivy.interpolate` already solved this problem, though.)
* It can only interpolate between **two** values. What if you want to do it with more than two values,
like Bézier Curve?

On the contrary, ``vanim`` is low-level.
In fact, it's presumptuous to classify it as an animation API.
All it does is to calculate elapsed-time or progression-rate or both.
What to do with those values is all up to you.

That concludes the overview.
Now, let's dive into each individual API.


dt (delta time)
---------------

.. autofunction:: dt

The async form of :meth:`kivy.clock.Clock.schedule_interval`. The following callback-style code:

.. code-block::
def callback(dt):
print(dt)
if some_condition:
return False
Clock.schedule_interval(callback, 0.1)
is equivalent to:

.. code-block::
async for dt in vanim.dt(step=0.1):
print(dt)
if some_condition:
break
et (elapsed time)
-----------------

.. autofunction:: et

If you want the total elapsed time of iterations instead of delta time, this is for you.

.. code-block::
timeout = 3.0
async for et in vanim.et(...):
...
if et > timeout:
break
You can calculate ``et`` by yourself if you want to:

.. code-block::
et = 0.
timeout = 3.0
async for dt in vanim.dt(...):
et += dt
...
if et > timeout:
break
which should be as performant as the former.

dt_et
-----

.. autofunction:: dt_et

If you want both ``dt`` and ``et``, this is for you.

.. code-block::
timeout = 3.0
async for dt, et in vanim.dt_et(...):
...
if et > timeout:
break
progress
--------

.. autofunction:: progress

If you aren't interested in how much time elapsed, and are only interested in the progression rate, this is for you.

.. code-block::
async for p in vanim.progress(duration=3.0):
print(p * 100, "%")
If you want non-linear progression, :class:`kivy.animation.AnimationTransition` may be helpful.

.. code-block::
from kivy.animation import AnimationTransition
transition = AnimationTransition.in_cubic
async for p in vanim.progress(duration=3.0):
p = transition(p)
print(p * 100, "%")
dt_et_progress
--------------

.. autofunction:: dt_et_progress

Lastly, if you want the all three above, use this.

.. code-block::
async for dt, et, p in vanim.dt_et_progress(duration=3.0):
...
The ``free_await`` parameter
----------------------------

You might have noticed that all the ``vanim``'s APIs take a keyword argument named ``free_await``.
This works exactly the same as the :class:`asynckivy.repeat_sleeping` 's.

Iterations may not end in time
------------------------------

This probably doesn't matter as long as the ``step`` is small enough. But in case it's not, be aware of what will
happen.

.. code-block::
async for dt, et, p in vanim.dt_et_progress(duration=2.0, step=0.6):
print(dt, et, p)
==== ========= =========
dt et p
==== ========= =========
0.6 0.6 0.3
0.6 1.2 0.6
0.6 1.8 0.9
0.6 **2.4** **1.2**
==== ========= =========

Look at the bottom row. ``et`` largely exceeds the ``duration`` and ``p`` largely exceeds 1.0.

Alias
-----

You might dislike abbreviations as they sometimes lower the readability of code. ``vanim`` offers longer names as
well.

* ``dt`` -> ``delta_time``
* ``et`` -> ``elapsed_time``
* ``dt_et`` -> ``delta_time_elapsed_time``
* ``dt_et_progress`` -> ``delta_time_elapsed_time_progress``
163 changes: 0 additions & 163 deletions src/asynckivy/vanim.py
View file
Original file line number Diff line number Diff line change
@@ -1,166 +1,3 @@
'''
:func:`asynckivy.animate` is an imitation of an existing API, :class:`kivy.animation.Animation`,
which is fine because it's easy to use for the people who are already familiar with Kivy.
The problem is ... it's a pretty specialized API because:
* It can only animate attributes. Sometimes, I just need the value without actually assigning it to an attribute.
(:func:`asynckivy.interpolate` already solved this problem, though.)
* It can only interpolate between **two** values. What if you want to do it with more than two values,
like Bézier Curve?
On the contrary, ``vanim`` is low-level.
In fact, it's presumptuous to classify it as an animation API.
All it does is to calculate elapsed-time or progression-rate or both.
What to do with those values is all up to you.
That concludes the overview.
Now, let's dive into each individual API.
dt (delta time)
---------------
.. autofunction:: dt
The async form of :meth:`kivy.clock.Clock.schedule_interval`. The following callback-style code:
.. code-block::
def callback(dt):
print(dt)
if some_condition:
return False
Clock.schedule_interval(callback, 0.1)
is equivalent to:
.. code-block::
async for dt in vanim.dt(step=0.1):
print(dt)
if some_condition:
break
et (elapsed time)
-----------------
.. autofunction:: et
If you want the total elapsed time of iterations instead of delta time, this is for you.
.. code-block::
timeout = 3.0
async for et in vanim.et(...):
...
if et > timeout:
break
You can calculate ``et`` by yourself if you want to:
.. code-block::
et = 0.
timeout = 3.0
async for dt in vanim.dt(...):
et += dt
...
if et > timeout:
break
which should be as performant as the former.
dt_et
-----
.. autofunction:: dt_et
If you want both ``dt`` and ``et``, this is for you.
.. code-block::
timeout = 3.0
async for dt, et in vanim.dt_et(...):
...
if et > timeout:
break
progress
--------
.. autofunction:: progress
If you aren't interested in how much time elapsed, and are only interested in the progression rate, this is for you.
.. code-block::
async for p in vanim.progress(duration=3.0):
print(p * 100, "%")
If you want non-linear progression, :class:`kivy.animation.AnimationTransition` may be helpful.
.. code-block::
from kivy.animation import AnimationTransition
transition = AnimationTransition.in_cubic
async for p in vanim.progress(duration=3.0):
p = transition(p)
print(p * 100, "%")
dt_et_progress
--------------
.. autofunction:: dt_et_progress
Lastly, if you want the all three above, use this.
.. code-block::
async for dt, et, p in vanim.dt_et_progress(duration=3.0):
...
The ``free_await`` parameter
----------------------------
You might have noticed that all the ``vanim``'s APIs take a keyword argument named ``free_await``.
This works exactly the same as the :class:`asynckivy.repeat_sleeping` 's.
Iterations may not end in time
------------------------------
This probably doesn't matter as long as the ``step`` is small enough. But in case it's not, be aware of what will
happen.
.. code-block::
async for dt, et, p in vanim.dt_et_progress(duration=2.0, step=0.6):
print(dt, et, p)
==== ========= =========
dt et p
==== ========= =========
0.6 0.6 0.3
0.6 1.2 0.6
0.6 1.8 0.9
0.6 **2.4** **1.2**
==== ========= =========
Look at the bottom row. ``et`` largely exceeds the ``duration`` and ``p`` largely exceeds 1.0.
Alias
-----
You might dislike abbreviations as they sometimes lower the readability of code. ``vanim`` offers longer names as
well.
* ``dt`` -> ``delta_time``
* ``et`` -> ``elapsed_time``
* ``dt_et`` -> ``delta_time_elapsed_time``
* ``dt_et_progress`` -> ``delta_time_elapsed_time_progress``
'''
__all__ = (
'dt', 'delta_time',
'et', 'elapsed_time',
Expand Down

0 comments on commit fc36039

Please sign in to comment.