setTransVarb(3)

NAME
setTransVarb, setTransConst, transEval, transMotionEval -- set the function binding of an RCCL transform.

USAGE
#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;

ARGUMENTS

tr --
    Pointer to the transform.

fxn --
    Pointer to a real-time function used to modify the transform.

arg --
    Application provided argument to the real-time function.

mnp --
    Manipulator associated with a motion-activated function binding.

RESTRICTIONS
These routines must be called from the planning level.

DESCRIPTION
These primitives control the function binding of RCCL transform data structures (type TRSF). They are synonymous with the routine setTransBinding() (q.v.), which receives its arguments through a structure. Additional discussion on transform function binding can be found in the manual page for setTransBinding().

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

setTransConst() declares a transform to be 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 allocTrans().

setTransVarb() declares a transform to be 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.

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 transEval():
        (*fxn) (tr, arg)
          TRSF *tr;
          int arg;

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).

transMotionEval() is similar to transEval(), except that the function is evaluated only when the transform is contained in the target position of a motion of the manipulator 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:
        (*fxn) (tr, arg, mnp)
          TRSF *tr;
          int arg;
          MANIP *mnp;

Function bindings can be removed using setTransConst() or 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 CTRL keyword in the 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 (rciPrintf()), memory allocation (rciMalloc()), and the ability to send UNIX signals to the planning task (rciSignal()). This is discussed in more detail in the "Mulit-RCCL User's Guide".

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

EDescriptor --
    Invalid transform pointer.

EInternal --
    Unexpected internal software or communication failure.

EBadArg --
    The function specified for transEval() or transMotionEval() is not contained in the program's control segment.

These routines will abort the program if called from the control level.

NOTES
The original RCCL system distinquished between const and hold transforms, where 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 hold transforms were assumed to perhaps change value from motion request to motion request, and so the trajectory generator would 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 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 TRANS_ARGS, which provided additional information:
        (*fxn) (tr, targs)
          TRSF *tr;
          TRANS_ARGS *targs;

The TRANS_ARGS structure is defined as follows:
        typedef struct {
          int arg;
          float scale;
          float time;
          MANIP *manip;
        } TRANS_ARGS;

arg is the application supplied argument. mnp is either the associated manipulator (in the case of transMotionEval()), or NULL. scale and time are the same quantities that can be obtained by the routines rcclSysTime() and getMotionScale(), respectively. The system 3.0 interface is still supported if the variable oldTfxnArgs in the file rccl/transControl.c is set true.

SEE ALSO
setTransBinding(3), allocTrans(3), errorStack(3), rcc(1).