[ggt-devel] API oddities

[Patrick H. <pa...@13...>]

In writing up the Python bindings for GMTL functions, I ran across what 
seem to be inconsistencies in the GMTL API.  There are two functions in 
particular: gmtl::cross() and gmtl::normalize().  In the case of 
gmtl::cross(), there are two forms (using gmtl::Vec3f as an instantiating 
type in this example):

    template gmtl::Vec3f cross(const gmtl::Vec3f&, const gmtl::Vec3f&);
    template gmtl::Vec3f& cross(gmtl::Vec3f&, const gmtl::Vec3f&,
                                const gmtl::Vec3f&);

Why is there a version that returns a vector by value?  As far as I have 
seen, this is the only such function in the entire GMTL API.  All the 
others follow the second form where the result vector has to exist a 
priori.  It might be appropriate for the first variant to be renamed 
gmtl::makeCross().

With gmtl::normalize(), the vector version has both different syntax and 
semantics WRT the quaternion version.  For example:

    template float normalize(gmtl::Vec3f&);
    template gmtl::Quatf& normalize(gmtl::Quatf&);

In the vector case, gmtl::normalize() returns the length of the vector 
before it was normalized.  Is that information typically useful?  The 
quaternion version seems to follow the GMTL conventions more closely--at 
least when compared to functions like gmtl::invert(), gmtl::transpose(), 
and so on.

My confusion is based mostly on my declining math skills.  I would be 
happy to learn that there are valid reasons for these inconsistencies, 
though having inconsistencies such as these does make the Python mappings 
a little more complicated.

  -Patrick


P.S. There are several places where data types are being passed by value 
where pass-by-reference behavior would be appropriate.  I didn't note 
where each of these is, but I should be able to find them in my long list 
of function instantiations.


-- 
Patrick L. Hartling			| Research Assistant, VRAC
pa...@13...				| 2274 Howe Hall Room 2624
PGP: http://www.137.org/patrick/pgp.txt	| T: +1.515.294.4916
http://www.137.org/patrick/		| http://www.vrac.iastate.edu/