[Home]	[About]
[Screenshots]	[Download]
[News]	[Community]
[Documentation]	[Manual]
[Bugs & Requests]	[Wiki]

/home/tetron/hack/vos/libs/vos/metaobjects/a3dl/object3d.hh

Go to the documentation of this file.

/*
    This file is part of the Virtual Object System of
    the Interreality project (http://interreality.org).

    Copyright (C) 2001, 2002 Peter Amstutz

    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Lesser General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.

    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Lesser General Public License for more details.

    You should have received a copy of the GNU Lesser General Public
    License along with this library; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA

    Peter Amstutz <http://www.interreality.org>
*/
#ifndef _OBJECT3D_HH_
#define _OBJECT3D_HH_

#include "a3dldefs.hh"
#include <vos/vos/vos.hh>
#include "material.hh"

#ifndef A3DL_EXPORTS
IMPORT_METAOBJECT_FACTORIES(A3DL_Object3D)
#endif

namespace A3DL
{
    class MaterialIterator;

    /** @class Object3D object3d.hh vos/metaobjects/a3dl/object3d.hh
     *  @ingroup libmetaobject_a3dl
     *  Base class for all 3D objects. Provides properties for position,
     *  orientation and scaling (size) of the object, as well as material.
     */
    class A3DL_API Object3D : public VOS::MetaObject
    {
    public:
        Object3D(VOS::VobjectBase* superobject);
        virtual ~Object3D();

        /** Initialize this object to have no property access control, position
         * (0,0,0), orientation (0,1,0,0) and scaling(1,1,1).
         */
        virtual void initialize();

        /** Set position of this 3D object.
            @param x X translation, relative to origin of parent object
            @param y Y translation, relative to origin of parent object
            @param z Z translation, relative to origin of parent object
            @throws NoSuchObjectError if "position" subobject does not exist, or is not a property.
        */
        virtual void setPosition(double x, double y, double z);


        /** Set the orientation of this 3D object in axis-angle
            rotation.  The first three parameters are a unit vector in
            world space which define an axis, the fourth parameter is
            a clockwise rotation about that axis.  For example, [0 1 0 20] would
            specify a rotation of 20 degrees around a vector pointing
            straight up.
            @note You can convert a quaternion into angle-axis
            rotation with the following math:
            @code
            phi = 2.0 * acos(quat.r);
            x = quat.x / sin(phi/2.0);
            y = quat.y / sin(phi/2.0);
            z = quat.z / sin(phi/2.0);
            @endcode
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void setOrientation(double x, double y, double z, double phi);

        /** Convenience function to set the orientation of this 3D object using a quaternion,
            which is then converted to A3DL's axis-angle notation.
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void setOrientationWithQuaternion(double x, double y, double z, double phi);

        /** Set scaling factors of this 3D object.
            @param x X scaling
            @param y Y scaling
            @param z Z scaling
            @throws NoSuchObjectError if "scaling" subobject does not exist, or is not a property.
        */
        virtual void setScaling(double x, double y, double z);

        /** Get position of this 3D object.
            @param x X translation, relative to origin of parent object
            @param y Y translation, relative to origin of parent object
            @param z Z translation, relative to origin of parent object
            @throws NoSuchObjectError if "position" subobject does not exist, or is not a property.
        */
        virtual void getPosition(double& x, double& y, double& z);

        /** Get the orientation of this 3D object in axis-angle
            rotation. See setOrientation() for details.

            @note This can be easily converted into a quaternion with
            the following math:
            @code
            quat.r = cos(phi/2.0);
            quat.x = x * sin(phi/2.0);
            quat.y = y * sin(phi/2.0);
            quat.z = z * sin(phi/2.0);
            @endcode
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void getOrientation(double& x, double& y, double& z, double& phi);

        /** Convenience function to get the orientation of this 3D
            object as a quaternion, converting from A3DL's axis-angle
            representation.
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void getOrientationAsQuaternion(double& x, double& y, double& z, double& phi);

        /** Get scaling factors of this 3D object.
            @param x X scaling
            @param y Y scaling
            @param z Z scaling
            @throws NoSuchObjectError if "scaling" subobject does not exist, or is not a property.
        */
        virtual void getScaling(double& x, double& y, double& z);


        /** Get material vobject. */
        virtual VUtil::vRef<Material> getMaterial(bool createIfNone = true);

        /** Set a material vobject */
        virtual void setMaterial(Material* obj);

        /** Get all attached material objects */
        virtual MaterialIterator getMaterials();

        /** Set the hard transform (HT) position of this 3D object.
            This transform is applied against the object before the
            normal position transform is applied and is not affected
            by hierarchical transforms.
            @param x X translation, relative to origin of parent object
            @param y Y translation, relative to origin of parent object
            @param z Z translation, relative to origin of parent object
            @throws NoSuchObjectError if "position" subobject does not exist, or is not a property.
        */
        virtual void setPositionHT(double x, double y, double z);


        /** Set the hard transform (HT) orientation of this 3D object
            in axis-angle rotation.  This transform is applied against
            the object before the normal orientation transform is applied
            and is not affected by hierarchical transforms.  The first
            three parameters are a unit vector in world space which
            define an axis, the fourth parameter is a clockwise
            rotation about that axis.  For example, [0 1 0 20] would
            specify a rotation of 20 degrees around a vector pointing
            straight up.
            @note You can convert a quaternion into angle-axis
            rotation with the following math:
            @code
            phi = 2.0 * acos(quat.r);
            x = quat.x / sin(phi/2.0);
            y = quat.y / sin(phi/2.0);
            z = quat.z / sin(phi/2.0);
            @endcode
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void setOrientationHT(double x, double y, double z, double phi);

        /** Convenience function to set the hard transform (HT)
            orientation of this 3D object using a quaternion, which is
            then converted to A3DL's axis-angle notation.  This
            transform is applied against the object before the normal
            orientation transform is applied and is not affected by
            hierarchical transforms.

            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void setOrientationWithQuaternionHT(double x, double y, double z, double phi);


        /** Set the hard transform (HT) scaling this 3D object.  This
            transform is applied against the object before the normal
            scaling transform is applied and is not affected by
            hierarchical transforms.
            @param x X scaling
            @param y Y scaling
            @param z Z scaling
            @throws NoSuchObjectError if "scaling" subobject does not exist, or is not a property.
        */
        virtual void setScalingHT(double x, double y, double z);

        /** Get the hard transform (HT) position of this 3D object.
            This transform is applied against the object before the
            normal position transform is applied and is not affected by
            hierarchical transforms.

            @param x X translation, relative to origin of parent object
            @param y Y translation, relative to origin of parent object
            @param z Z translation, relative to origin of parent object
            @throws NoSuchObjectError if "position" subobject does not exist, or is not a property.
        */
        virtual void getPositionHT(double& x, double& y, double& z);

        /** Get the hard transform (HT) orientation of this 3D object in axis-angle
            rotation. See setOrientation() for details.  This
            transform is applied against the object before the normal
            orientation transform is applied and is not affected by
            hierarchical transforms.

            @note This can be easily converted into a quaternion with
            the following math:
            @code
            quat.r = cos(phi/2.0);
            quat.x = x * sin(phi/2.0);
            quat.y = y * sin(phi/2.0);
            quat.z = z * sin(phi/2.0);
            @endcode
            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void getOrientationHT(double& x, double& y, double& z, double& phi);

        /** Convenience function to get the hard transform (HT)
            orientation of this 3D object as a quaternion, converting
            from A3DL's axis-angle representation.  This
            transform is applied against the object before the normal
            orientation transform is applied and is not affected by
            hierarchical transforms.

            @param x X vector component
            @param y Y vector component
            @param z Z vector component
            @param phi the rotation about the vector axis, in degrees
            @throws NoSuchObjectError if "orientation" subobject does not exist, or is not a property.
        */
        virtual void getOrientationAsQuaternionHT(double& x, double& y, double& z, double& phi);


        /** Get the hard transform (HT) scaling of this 3D object.
            This transform is applied against the object before the
            normal scaling transform is applied and is not
            affected by hierarchical transforms.
            @param x X scaling
            @param y Y scaling
            @param z Z scaling
            @throws NoSuchObjectError if "scaling" subobject does not exist, or is not a property.
        */
        virtual void getScalingHT(double& x, double& y, double& z);


        virtual const std::string getVOSType();
        static VOS::MetaObject* new_Object3D(VOS::VobjectBase* superobject, const std::string& type);

        void setOrInsertChild(const std::string& name, VOS::Vobject* obj);

        /** @return If true, applyForce/applyTorque will be fed into a
            physics engine and the object will have dynamic response.
            If false applyForce/applyTorque apply the change directly
            as a delta to the position/orientation property.
         */
        virtual bool supportsPhysics();

        /** Apply an instantaneous linear force vector to this object
            @param x component of vector
            @param y component of vector
            @param z component of vector
        */
        virtual void applyForce(double x, double y, double z);

        /** Apply an instantaneous angular torque to this object.
            The direction of the vector specifies the axis, the length
            of the vector specifies the magnitude, and the direction of rotation
            is determined by the "right hand" rule.
            @param x component of vector
            @param y component of vector
            @param z component of vector
         */
        virtual void applyTorque(double x, double y, double z);

        /** Fetch the current linear velocity vector for this object
            @param x component of vector
            @param y component of vector
            @param z component of vector
        */
        virtual void getLinearVelocity(double& x, double& y, double& z);

        /** Fetch the current angular velocity of this object.
            The direction of the vector specifies the axis, the length
            of the vector specifies the magnitude, and the direction of rotation
            is determined by the "right hand" rule.
            @param x component of vector
            @param y component of vector
            @param z component of vector
         */
        virtual void getAngularVelocity(double& x, double& y, double& z);

        /** Utility functions for getting/setting properties */
        //@{
        static void setThreeFloatProperty(Vobject& vob, const std::string& name, double x, double y, double z);
        static void getThreeFloatProperty(Vobject& vob, const std::string& name, double* x, double* y, double* z);
        //@}

        /** Get position property object. */
        virtual VUtil::vRef<VOS::Property> getPositionObj();

        /** Set position property object */
        virtual void setPositionObj(VOS::Property* obj);
        virtual VUtil::vRef<VOS::Property> getOrientationObj();
        virtual void setOrientationObj(VOS::Property* obj);
        virtual VUtil::vRef<VOS::Property> getScalingObj();
        virtual void setScalingObj(VOS::Property* obj);

        virtual void moveTo(double x, double y, double z, double timestep);
    };
}

#endif