\input manualMacros.tex
\manBegin
\manPageInfo{RCCL Reference Manual}{}{}
\manTitle{allocTransXyz}{3}
\manSection{NAME}
{\rightskip=0ptplus1fil
{\tt \manName{allocTransEul}},
{\tt \manName{allocTransPao}},
{\tt \manName{allocTransRot}},
{\tt \manName{allocTransRpy}},
{\tt \manName{allocTransXyz}}
-- functions which allocate transforms and initialize them at the same 
time.
}
\manSection{USAGE}
\cverbatim
#include <rccl.h>

TRSF *allocTransEul (name, pool, px, py, pz, phi, the, psi)
  const char* name;
  int pool;
  float px, py, pz, phi, the, psi;

TRSF *allocTransPao (name, pool, px, py, pz, ax,ay,az, ox,oy,oz)
  const char* name;
  int pool;
  float px, py, pz, ax, ay, az, ox, oy, oz;

TRSF *allocTransRot (name, pool, px, py, pz, vector, h)
  const char* name;
  int pool;
  float px, py, pz, h;
  VECT *vector;

TRSF *allocTransRpy (name, pool, px, py, pz, roll, pitch, yaw)
  const char* name;
  int pool;
  float px, py, pz, roll, pitch, yaw;

TRSF *allocTransXyz (name, pool, px, py, pz)
  const char* name;
  int pool;
  float px, py, pz;@endcverbatim
\manSection{ARGUMENTS}
\manItem{{\tt name} --}
Name of the transform (optional; can be specified as {\tt NULL} if not
required). 
\manItem{{\tt pool} --}
Memory area from which to allocate the transform. Under the current
implementation, there is one memory area on each CPU, so {\tt pool} is
actually 
a CPU number. The idea is to allocate the transform on the CPU where
it will be accessed the most. If you don't care what memory pool is used
to allocate the transform, give this argument as {\tt UNDEF}.
\manItem{{\tt px}, {\tt py}, {\tt pz} --}
Translation components along the $x$, $y$, and $z$ axes
(the transform's {\bf p} vector).
\manItem{{\tt phi}, {\tt the}, {\tt psi} --}
Euler angles
representing rotation (in degrees) first about the $z$ axis, then about the new $y$
axis, and finally about the new $z$ axis.
\manItem{{\tt ax}, {\tt ay}, {\tt az} --}
Components of a vector parallel to the transform frame's $z$ axis
(the {\bf a} vector).
\manItem{{\tt ox}, {\tt oy}, {\tt oz} --}
Components of a vector parallel to the transform frame's $y$ axis
(the {\bf o} vector).
\manItem{{\tt vector} --}
A vector describing an axis about which a rotation is defined. The vector
does not have to 
be normalized.
\manItem{{\tt h} --}
Amount of rotation (in degrees) about an specified axis.
\manItem{{\tt roll}, {\tt pitch}, {\tt yaw} --}
Roll, pitch, and yaw angles which represent rotations (in degrees),
first about the $z$ axis, then about the new $y$
axis, and finally about the new $x$ axis, respectively.
\manSection{RESTRICTIONS}
These routines must be called from the planning level.
\manSection{DESCRIPTION}
These routines allocate a new transform, using the routine {\tt allocTrans()}
(q.v.), and then instantiate the transform with the indicated values.
The transforms may be freed using {\tt freeTrans()}. The {\tt pool}
argument is the same as in {\tt allocTrans()}; it is used to control the
physical location of the transform memory; when in doubt, set {\tt pool}
to {\tt UNDEF} and let the system decide which pool to use.

{\tt allocTransEul()} returns a transform with a specified
translation and a rotation
specified by a set of Euler angles.

{\tt allocTransPao()} returns a transform with a specified 
translation and a rotation
specified by two vectors, ostensibly parallel to the {\bf a} and
{\bf o} vectors of the corresponding rotation matrix. These vectors do not
have to be 
parallel, and do not have to be perpendicular, since
a coordinate system is
constructed from them using the same algorithm used by {\tt vaoToTrsf(3)}.

{\tt allocTransRot()} returns a transform with a specified 
translation and a rotation
specified by a single rotation about a particular axis.

{\tt allocTransRpy()} returns a transform with a specified 
translation and a rotation
specified by a set of roll-pitch-yaw angles.

{\tt allocTransXyz()} returns a transform with a specified translation only
(the rotational component is set to the identity).
\manSection{DIAGNOSTICS}
These routines return {\tt NULL} 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 EMemory} --}
Not enough memory left in the shared memory pool.
\manItem{{\tt EDuplicate} --}
Attempt was made to create a transform with the same name as
one already allocated.

These routines will abort the program if called from the control level.
\manSection{SEE ALSO}
\rightskip=0ptplus1fil
{\tt allocTrans(3)}, {\tt allocMem(3)}, {\tt vaoToTrsf(3)}, {\tt eulToTrsf(3)},
{\tt rotToTrsf(3)}, {\tt rpyToTrsf(3)}, {\tt xyzToTrsf(3)}, {\tt errorStack(3)}.
\manEnd
\end
