\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{setTransVarb}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{setTransVarb}},
{\tt \manName{setTransConst}},
{\tt \manName{transEval}},
{\tt \manName{transMotionEval}}
-- set the function binding of an RCCL transform.

}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

setTransConst (tr)
   TRSF *tr;

setTransVarb (tr)
   TRSF *tr;

transEval (tr, fxn, arg)
   TRSF *tr;
   int (*fxn)();
   int arg;

transMotionEval (tr, fxn, arg, mnp)
   TRSF *tr;
   int (*fxn)();
   int arg;
   MANIP *mnp;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt tr} --}
Pointer to the transform.
\manItem{{\tt fxn} --}
Pointer to a real-time function used to modify the transform.
\manItem{{\tt arg} --}
Application provided argument to the real-time function.
\manItem{{\tt mnp} --}
Manipulator associated with a motion-activated function binding.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
These primitives control the function binding of RCCL transform data
structures (type {\tt TRSF}). 
They are synonymous with the routine {\tt setTransBinding()} (q.v.),
which receives its arguments through a structure.
Additional discussion on 
transform function binding can be found in the manual page for {\tt
setTransBinding()}. 

Transforms which are to be bound
must be allocated using the routine {\tt allocTrans()}, which sets up
the internal structures necessary to maintain function bindings.

{\tt setTransConst()} declares a transform to be {\it constant}. This means
that when a motion request is made which contains this transform in its
target position, RCCL may assume that its value is fixed
for the duration of the motion. In particular, the trajectory
generator will make a private copy of the transform (at the time
of the motion request) and use this in evaluating
the motion target. Subsequent changes in the value of the transform
will therefore not affect the motion. For efficiency, adjacent constant
transforms are combined (multiplied together) at the time of the motion
request. Transforms are initially set constant when first created
with {\tt allocTrans()}.

{\tt setTransVarb()} declares a transform to be {\it variable}. 
When a variable transform is contained in the target position of a motion
request, the trajectory generator must assume that its value is dynamic 
and continuously update the target position to account for possible
changes in the transform's value. Changes to the transform's value
while the motion is in progress will be tracked by the motion.

In addition to being declared constant or variable, transforms can be
bound to specific real-time functions which are executed by the trajectory
generator once every control cycle. A transform which is bound to a
function is also treated by the trajectory generator as a variable transform:
subsequent motion targets which contain that transform
will be re-evaluated every control cycle,
so that the motion tracks changes in the transform's value.

{\tt transEval()} binds a transform to a function, the evaluation
of which begins as soon as the call returns, 
and continues until changed by another binding call.

The transform function is called by the trajectory generator with two
arguments: 
a pointer to the transform itself, and the application argument
supplied to {\tt transEval()}:
\cverbatim
        (*fxn) (tr, arg)
          TRSF *tr;
          int arg;
@endcverbatim
\noindent
{\tt tr} is actually a pointer to a local copy of the transform, which is
copied into the original transform as soon as the function returns
(so there is no need to access the transform atomically from
within the function).

{\tt transMotionEval()} is similar to {\tt transEval()},
except that the function is evaluated only 
when the transform is contained in the target position of a motion
of the manipulator {\tt mnp}. This behaviour is basically identical to that of
the functional transforms of the orginal RCCL system. When called by the
trajectory generator, the function receives an additional argument 
pointing to the associated manipulator:
\cverbatim
        (*fxn) (tr, arg, mnp)
          TRSF *tr;
          int arg;
          MANIP *mnp;
@endcverbatim

Function bindings can be removed using {\tt setTransConst()} or
{\tt setTransVarb()}, although the latter will preserve the transform's
variable status.

Transform functions must be part of the program's control segment;
i.e., they must be contained in modules specified to the right of the {\tt
CTRL} keyword in the {\tt rcc} command (q.v.) used to compile/load the
program. 
Since the functions are executed at the control level, their execution
times need to be contained within a single control cycle. They also do not
have access to the UNIX system services. RCI utility routines provide
such things as diagnostic printing ({\tt rciPrintf()}), memory allocation
({\tt rciMalloc()}), and the ability to send UNIX signals to the planning task
({\tt rciSignal()}). This is discussed in more detail in the ``Mulit-RCCL
User's Guide''. 

\manSection{DIAGNOSTICS}
These routines return {\tt -1} in the event of an error.
They will automatically abort the program if the option {\tt RCCL_ERROR_EXIT}
is set (see {\tt rcclSetOptions(3)}). 
Error codes and messages are placed on the {\it errorStack} (q.v.). 
The following error codes may be set:

\manItem{{\tt EDescriptor} --}
Invalid transform pointer.
\manItem{{\tt EInternal} --}
Unexpected internal software or communication failure.
\manItem{{\tt EBadArg} --}
The function specified for {\tt transEval()} or
{\tt transMotionEval()} is not contained in the program's control segment.

These routines will abort the program if called from the control level.
\manSection{NOTES}
The original RCCL system distinquished between {\tt const} and {\tt hold}
transforms, where {\tt const} transforms were assumed to be unchanging
in value throughout their life (and so the trajectory generator
would reference a pointer to them directly), whereas {\tt hold}
transforms were assumed to perhaps change value from motion request to motion
request, and so the trajectory generator would {\it hold} a copy of the
transform for each motion request. The distinction is no longer meaningful:
since the trajectory generator makes private copies of all constant
transforms for each motion request anyway, the effect is that all constant
transforms behave like {\tt hold} transforms did in the original system.

Release 3.0 of RCCL had the same function binding mechanism described here,
except that the trajectory generator called the transform functions in
a different way. Transform functions were always called with two arguments:
a pointer to a local copy of the transform, and a pointer to a structure
{\tt TRANS_ARGS}, which provided additional information:
\cverbatim
        (*fxn) (tr, targs)
          TRSF *tr;
          TRANS_ARGS *targs; 
@endcverbatim
\noindent
The {\tt TRANS_ARGS} structure is defined as follows:
\cverbatim
        typedef struct {
          int arg;
          float scale;
          float time;
          MANIP *manip;
        } TRANS_ARGS; 
@endcverbatim
\noindent
{\tt arg} is the application supplied argument.
{\tt mnp} is either the associated manipulator (in the case of
{\tt transMotionEval()}), or {\tt NULL}. 
{\tt scale} and {\tt time} are the same quantities that can
be obtained by the routines {\tt rcclSysTime()} and {\tt getMotionScale()},
respectively. The system 3.0 interface is still supported if the variable
{\tt oldTfxnArgs} in the file {\filefont rccl/transControl.c} is set true.
\manSection{SEE ALSO}
\raggedright
{\tt setTransBinding(3)}, 
{\tt allocTrans(3)}, {\tt errorStack(3)}, {\tt
rcc(1)}. 

\manEnd
\end
