updateTrans(3)

NAME
updateTrans -- solve for a transform at end of next requested RCCL motion.

USAGE
updateTrans (mnp, tr, pos, t1, tx)
  MANIP *mnp;
  TRSF *tr, *t1, *tx;
  POS *pos;

ARGUMENTS

mnp --
    Manipulator reference structure.

tr --
    Place for the trajectory generator to put the solved transform. This must be a transform allocated with the allocTrans() routines.

pos --
    Position equation containing the transform to be solved for.

t1 --
    The transform being solved for. This must be a component transform of pos (including T6).

tx --
    Instantiation value for T6. This argument is necessary if pos contains T6 and T6 is not the transform being solved for, because T6 has no particular value. Otherwise, this argument may be specified as NULL. If specified, this must be a transform allocated with the allocTrans() routines.

RESTRICTIONS
This routine must be called from the planning level.

DESCRIPTION
This routine tells the trajectory generator to solve for the value of a transform within a particular position equation at the end of the next requested motion. The trajectory generator will evaluate the transform at the same time it updates the here transform in the MANIP structure.

This is equivalent to having the trajectory generator perform a solveTrans() at the end of the next requested motion. The argument syntax and semmantics of updateTrans() are identical to solveTrans(), and the manual page for solveTrans() should be consulted for additional information. Unlike solveTrans(), the argument transforms tr and tx (if specified) must have been created using the allocTrans() routines so that they can be accessed by the trajectory generator.

updateTrans() requests are cancelled when the trajectory generator is turned off (see rcclRelease(3)). An update request will also not be honored if the associated motion is aborted on the queue before it has started executing (this is an implementation constraint). Only one update request is permitted per motion and per manipulator.

Unlike with the move() requests, the system does not make a private copy of the constant transforms in the position equation of an update request. This was done for reasons of generality, but it might be changed if it causes problems.

DIAGNOSTICS
This routine returns -1 in the event of an error. It 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:

EBadArg --
    The variable transform tx was either not provided when it is needed, or not allocated using the allocTrans() routines.

ERange --
    The transform t1 is not contained in the position equation pos.

ETooMany --
    The position to be solved for contains more than MAX_UPDATE_POS terms.

The routine will abort the program if called from the control level.

BUGS
We should implement updateChain() and updateInvChain() as well; this may be done if there is demand for it.

Performing an update request can be expensive, in that the trajectory generator has to multiply together all the transforms in the position data structure during one control cycle.

SEE ALSO
solveTrans(3), makePosition(3), setTransVarb(3).