source files: [xc]tfm.[ch]
SYNTAX
(SEND <tfm> :GET <:PROPERTY> [<default-value>]) (SEND <tfm> :SET <:PROPERTY> <value>) (SEND <tfm> :REMPROP <:PROPERTY>) (SEND <tfm> :PROPERTY-LIST-LENGTH) (SEND <tfm> :PROPERTY-LIST-NTH <fix:index> [<default-value>])
DESCRIPTION
:GET fetches a given property from <tfm>. Some properties are understood and used by <tfm>. The user may also store arbitrary properties on a <tfm>'s propertylist using :SET, and fetch them via :GET.
:REMPROP removes the given property from the propertylist, returning (:PROPERTY . <val>) if the property was successfully removed, else NIL.
If :GET does not find the requested property, it returns <default-value> if one was provided, otherwise signals an error.
:PROPERTY-LIST-LENGTH and :PROPERTY-LIST-NTH are provided to allow iteration through all properties on object, the latter's <default-value> works just as on :GET.
The properties which <tfm>s recognize specially are:
:TRANSFORM Return self. :LOCATION Camera location as a '(1 2 3) style list. :TARGET Camera target as a '(1 2 3) style list. :UP Camera zenith as a '(1 2 3) style list. :RADIANS Camera field of view in radians. :DEGREES Camera field of view in degrees. :DIAMETER Diameter of clipping box centered on TARGET. :LEFT :RIGHT :TOP :BOTTOM :NEAR :FAR Orthographic viewing volume.
The :TRANSFORM message is essentially a NO-OP. It is supported so that xlisp code can accept a MATRIX44, LIGHT, or CAMERA and get the relevant transform in each case by sending it's argument a (:GET <arg> :TRANSFORM) message. You may not :SET a value for :TRANFORM on a <tfm>.
The fields are described above in terms of a camera, since that makes the purpose of the fields clearer, but they are actually present in all MATRIX44 instances, whether or not the instance is related to a camera. This slight redundancy simplifies programming by eliminating special cases.
If the above fields are modified via the :SET message (excepting :TRANFORM, which may not be :SET), before the 4x4 matrix in <tfm> is next used, the matrix contents will be recomputed to conform with the current :LOCATION, :TARGET, :UP, and :RADIANS/:DEGREES.
Note: It is sometimes a temptation to simply make :UP very large. Most likely, the :TURTLE-* commands should be used instead, but if you do this, pick a value more like 1.0e7 than 1.0e27. The latter overflows the trig fns and results in a nonsense matrix.