\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{jbiasMotionEval}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{jbiasSelect}},
{\tt \manName{jbiasMotionEval}},
{\tt \manName{setJbiasConst}},
{\tt \manName{setJbiasVarb}}
-- RCCL joint bias control routines.

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

jbiasSelect (mnp, on)
   MANIP *mnp;
   int on;

jbiasMotionEval (fxn, arg, mnp)
   int (*fxn)();
   int arg;
   MANIP *mnp;

setJbiasConst (mnp)
   MANIP *mnp;

setJbiasVarb (mnp)
   MANIP *mnp;
@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt mnp} --}
Manipulator reference structure.
\manItem{{\tt on} --}
Set to true (non-zero) to enable joint biasing.
\manItem{{\tt fxn} --}
Pointer to a real-time function used to modify the joint bias values.
\manItem{{\tt arg} --}
User provided argument to the real-time function.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
They are not defined for virtual manipulators.
Joint biasing is currently available for joint interpolated motions only.
\manSection{DESCRIPTION}
RCCL allows motion targets to vary by changing the values of the
transforms that define those targets. It is also possible to change
the value of a target by applying a bias to the target joint values.
These bias values are stored in the {\tt jbias} field of the
{\tt MANIP} structure. By default, these are set to zero and
do not change. However, a programmer can put values in the
joint biases or attach them to a real time function that modifies the
values in real time. This function binding is similar to
the function binding for transforms, 
except that it is at the joint level, and there is only one set of
joint biases for each manipulator.

To use joint biasing, it is necessary to enable
it for each desired robot by calling {\tt jbiasSelect()}
with {\tt on} set to a true (non-zero) value. Joint biasing
will then remain in effect until disabled with another
call to {\tt jbiasSelect()}. Joint biasing is currently available only
for joint interpolated motions.

The joint biases are stored in the {\tt jbias} field
of the robot's {\tt MANIP} structure,
and can be read or written atomically using
the shared memory primitives {\tt readMem()} and {\tt writeMem()} (q.v.).

By default, when joint biasing is enabled, 
each motion request receives a private fixed copy of the joint bias
values at the time the motion request is made. 
The trajectory generator then uses these private values
to offset the motion's target position. Subsequent changes made to the
original joint bias values will affect only later motions.

It is possible to change this default behaviour in two ways:

\manItem{1.} By declaring the joint biases to be {\it variable}.
Motion requests will then {\it not} receive a private
copy of the joint biases, but will instead track the original
values directly.

\manItem{2.} By attaching the joint biases to a control level
function, called by the trajectory generator, which modifies their values. 

The first option is controlled by the following two routines:

{\tt setJbiasVarb()} declares the joint biases to be variable.
Subsequent motion requests will track the values of the joint
biases directly.

{\tt setJbiasConst()} resets the joint biases to be constant. Subsequent
motion requests will use a private fixed copy of the joint biases instead of
tracking them.

Binding the joint biases to a function is done using an additional routine:

{\tt jbiasMotionEval()} attaches the function {\tt fxn()} to the joint
biases for the duration of the
next motion. {\tt arg} is an application argument passed
to the function. After the next motion request, the binding of the
joint biases reverts to what it was previously (either constant or variable).

The modifying function is called as follows:
\cverbatim
        fxn (jbias, arg, mnp)
        JNTS *jbias;
        int arg;
        MANIP *mnp;
        {
                ....
        } @endcverbatim \noindent
{\tt jbias} points to the joint biases (or, more precisely, a copy of
them which is written into {\tt mnp->jbias} as soon as
the routine returns). {\tt arg} is the application argument specifed
by {\tt jbiasMotionEval()}, and {\tt mnp} is a pointer
to the manipulator.

\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 ENotDefined} --}
The functions were called for a virtual manipulator.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\raggedright
{\tt setTransBinding(3)}, {\tt errorStack(3)}, {\tt rcc(1)},
{\tt readMem(3)}.

\manEnd
\end
