[FFmpeg-cvslog] doc/utils/eval: review and extend, clarify ld/st index meaning

[Stefano Sabatini]

ffmpeg | branch: master | Stefano Sabatini <stefasab at gmail.com> | Fri Jan  5 00:56:40 2024 +0100| [b2bc4ac69e5a8ff74a105de621e75fb722c31eae] | committer: Stefano Sabatini

doc/utils/eval: review and extend, clarify ld/st index meaning

Prefer idx in place of id for functions accessing the internal
variables, and add a short introduction to mention them.

> http://git.videolan.org/gitweb.cgi/ffmpeg.git/?a=commit;h=b2bc4ac69e5a8ff74a105de621e75fb722c31eae
---

 doc/utils.texi | 60 ++++++++++++++++++++++++++++++++--------------------------
 1 file changed, 33 insertions(+), 27 deletions(-)

diff --git a/doc/utils.texi b/doc/utils.texi
index 2f18a61bfd..9968725d2a 100644
--- a/doc/utils.texi
+++ b/doc/utils.texi
@@ -801,6 +801,11 @@ The following binary operators are available: @code{+}, @code{-},
 
 The following unary operators are available: @code{+}, @code{-}.
 
+Some internal variables can be used to store and load intermediary
+results. They can be accessed using the @code{ld} and @code{st}
+functions with an index argument varying from 0 to 9 to specify which
+internal variable to access.
+
 The following functions are available:
 @table @option
 @item abs(x)
@@ -898,9 +903,9 @@ Return 1.0 if @var{x} is +/-INFINITY, 0.0 otherwise.
 @item isnan(x)
 Return 1.0 if @var{x} is NAN, 0.0 otherwise.
 
- at item ld(var)
-Load the value of the internal variable with number
- at var{var}, which was previously stored with st(@var{var}, @var{expr}).
+ at item ld(idx)
+Load the value of the internal variable with index @var{idx}, which was
+previously stored with st(@var{idx}, @var{expr}).
 The function returns the loaded value.
 
 @item lerp(x, y, z)
@@ -933,16 +938,14 @@ Compute the power of @var{x} elevated @var{y}, it is equivalent to
 
 @item print(t)
 @item print(t, l)
-Print the value of expression @var{t} with loglevel @var{l}. If
- at var{l} is not specified then a default log level is used.
-Returns the value of the expression printed.
-
-Prints t with loglevel l
+Print the value of expression @var{t} with loglevel @var{l}. If @var{l} is not
+specified then a default log level is used.
+Return the value of the expression printed.
 
 @item random(idx)
 Return a pseudo random value between 0.0 and 1.0. @var{idx} is the
-index of the internal variable which will be used to save the
-seed/state.
+index of the internal variable used to save the seed/state, which can be
+previously stored with @code{st(idx)}.
 
 To initialize the seed, you need to store the seed value as a 64-bit
 unsigned integer in the internal variable with index @var{idx}.
@@ -955,8 +958,8 @@ st(0,42); print(random(0)); print(random(0)); print(random(0))
 
 @item randomi(idx, min, max)
 Return a pseudo random value in the interval between @var{min} and
- at var{max}. @var{idx} is the index of the internal variable which will
-be used to save the seed/state.
+ at var{max}. @var{idx} is the index of the internal variable which will be used to
+save the seed/state, which can be previously stored with @code{st(idx)}.
 
 To initialize the seed, you need to store the seed value as a 64-bit
 unsigned integer in the internal variable with index @var{idx}.
@@ -968,14 +971,14 @@ with argument @var{ld(0)} is 0 in the interval 0.. at var{max}.
 The expression in @var{expr} must denote a continuous function or the
 result is undefined.
 
- at var{ld(0)} is used to represent the function input value, which means
-that the given expression will be evaluated multiple times with
-various input values that the expression can access through
- at code{ld(0)}. When the expression evaluates to 0 then the
-corresponding input value will be returned.
+ at var{ld(0)} is used to represent the function input value, which means that the
+given expression will be evaluated multiple times with various input values that
+the expression can access through @code{ld(0)}. When the expression evaluates to
+0 then the corresponding input value will be returned.
 
 @item round(expr)
-Round the value of expression @var{expr} to the nearest integer. For example, "round(1.5)" is "2.0".
+Round the value of expression @var{expr} to the nearest integer. For example,
+"round(1.5)" is "2.0".
 
 @item sgn(x)
 Compute sign of @var{x}.
@@ -993,12 +996,15 @@ Compute the square root of @var{expr}. This is equivalent to
 @item squish(x)
 Compute expression @code{1/(1 + exp(4*x))}.
 
- at item st(var, expr)
+ at item st(idx, expr)
 Store the value of the expression @var{expr} in an internal
-variable. @var{var} specifies the number of the variable where to
-store the value, and it is a value ranging from 0 to 9. The function
-returns the value stored in the internal variable.
-Note, Variables are currently not shared between expressions.
+variable. @var{idx} specifies the index of the variable where to store
+the value, and it is a value ranging from 0 to 9. The function returns
+the value stored in the internal variable.
+
+The stored value can be retrieved with @code{ld(var)}.
+
+Note: variables are currently not shared between expressions.
 
 @item tan(x)
 Compute tangent of @var{x}.
@@ -1007,16 +1013,16 @@ Compute tangent of @var{x}.
 Compute hyperbolic tangent of @var{x}.
 
 @item taylor(expr, x)
- at item taylor(expr, x, id)
+ at item taylor(expr, x, idx)
 Evaluate a Taylor series at @var{x}, given an expression representing
-the @code{ld(id)}-th derivative of a function at 0.
+the @code{ld(idx)}-th derivative of a function at 0.
 
 When the series does not converge the result is undefined.
 
- at var{ld(id)} is used to represent the derivative order in @var{expr},
+ at var{ld(idx)} is used to represent the derivative order in @var{expr},
 which means that the given expression will be evaluated multiple times
 with various input values that the expression can access through
- at code{ld(id)}. If @var{id} is not specified then 0 is assumed.
+ at code{ld(idx)}. If @var{idx} is not specified then 0 is assumed.
 
 Note, when you have the derivatives at y instead of 0,
 @code{taylor(expr, x-y)} can be used.