More documentation for NiAVObject and NiObjectNET.

Removed redundant Get/SetHidden functions from NiAVObject, use Get/SetVisibility instead.
Renamed Get/SetCollision to Get/SetCollisionMode in NiAVObject.

include/obj/NiAVObject.h

@@ -41,10 +41,28 @@ public:
 	NIFLIB_HIDDEN virtual void FixLinks( const map<unsigned int,NiObjectRef> & objects, list<unsigned int> & link_stack, const NifInfo & info );
 	NIFLIB_HIDDEN virtual list<NiObjectRef> GetRefs() const;
 
-	//TODO:  What to do with newer files that have a link for a bounding box?  Wrap this in a function and translate?
+	/*!
+	 * Clears all embedded bounding box information.  Older NIF files can have a bounding box specified in them which will be used for collision detection instead of evaluating the triangles.
+	 */
 	NIFLIB_API void ClearBoundingBox();
+
+	/*!
+	 * Returns any embedded bounding box information.  NiAVObject::HasBoundingBox should be called first, as this function will throw an exception if there is no bounding box information in this object.  Older NIF files can have a bounding box specified in them which will be used for collision detection instead of evaluating the triangles.
+	 * \return The embedded bounding box dimentions.
+	 * \sa NiAVObject::HasBoundingBox
+	 */
 	NIFLIB_API BoundingBox GetBoundingBox() const;
+
+	/*!
+	 * Sets new embedded bounding box information.  Older NIF files can have a bounding box specified in them which will be used for collision detection instead of evaluating the triangles.
+	 * \param[in] n The new bounding box dimentions.
+	 */
 	NIFLIB_API void SetBoundingBox( const BoundingBox & n );
+
+	/*!
+	 * Determines whether this object has embedded bounding box information.  Older NIF files can have a bounding box specified in them which will be used for collision detection instead of evaluating the triangles.
+	 * \return True if this object has an embedded bounding box, false otherwise.
+	 */
 	NIFLIB_API bool HasBoundingBox() const;
 	
 	/*! 
@@ -68,58 +86,170 @@ public:
 	 */
 	NIFLIB_API Matrix44 GetWorldTransform() const;
 
-	/*! Meant to be called by NiNode during the addition of new children.  Should not be called directly. */
-	NIFLIB_HIDDEN void SetParent( NiNode * new_parent );
-
+	/*!
+	 * Returns the parent of this object in the scene graph.  May be NULL.
+	 * \return The parent of this object in the scene graph.
+	 */
 	NIFLIB_API Ref<NiNode> GetParent() const;
 
+	/*!
+	 * Adds a property to this object.  Properties specify various charactaristics of the object that affect rendering.  They may be shared among objects.
+	 * \param[in] obj The new property that is to affect this object.
+	 */
 	NIFLIB_API void AddProperty( const Ref<NiProperty> & obj );
+
+	/*!
+	 * Removes a property from this object.  Properties specify various charactaristics of the object that affect rendering.  They may be shared among objects.
+	 * \param[in] obj The property that is no longer to affect this object.
+	 */
 	NIFLIB_API void RemoveProperty( Ref<NiProperty> obj );
+
+	/*!
+	 * Removes all properties from this object.  Properties specify various charactaristics of the object that affect rendering.  They may be shared among objects.
+	 */
 	NIFLIB_API void ClearProperties();
+
+	/*!
+	 * Retrieves a list of all properties that affect this object.  Properties specify various charactaristics of the object that affect rendering.  They may be shared among objects.
+	 * \return All the properties that affect this object.
+	 */
 	NIFLIB_API vector< Ref<NiProperty> > GetProperties() const;
+
+	/*!
+	 * Retrieves the property that matches the specified type, if there is one.  A valid object should not have more than one property of the same type.  Properties specify various charactaristics of the object that affect rendering.  They may be shared among objects.
+	 * \param[in] compare-to The type constant of the desired property type.
+	 * \return The property that matches the specified type, or NULL if there isn't a match.
+	 * \sa NiObject::TypeConst
+	 */
 	NIFLIB_API Ref<NiProperty> GetPropertyByType( const Type & compare_to );
 
+	/*!
+	 * Can be used to get the data stored in the flags field for this object.  It is usually better to call more specific flag-toggle functions if they are availiable.
+	 * \return The flag data.
+	 */
 	NIFLIB_API unsigned short GetFlags() const;
+
+	/*!
+	 * Can be used to set the data stored in the flags field for this object.  It is usually better to call more specific flag-toggle functions if they are availiable.
+	 * \param[in] n The new flag data.  Will overwrite any existing flag data.
+	 */
 	NIFLIB_API void SetFlags( unsigned short n );
 
+	/*!
+	 * Used to get the local rotation matrix for this object.  This is a 3x3 matrix that should not include scale or translation components.
+	 * \return The local 3x3 rotation matrix for this object.
+	 */
 	NIFLIB_API Matrix33 GetLocalRotation() const;
+
+	/*!
+	 * Used to set the local rotation matrix for this object.  This is a 3x3 matrix that should not include scale or translation components.
+	 * \param[in] n The new local 3x3 rotation matrix for this object.
+	 */
 	NIFLIB_API void SetLocalRotation( const Matrix33 & n );
 
+	/*!
+	 * Used to get the local translation vector for this object.  This determines the object's offset from its parent.
+	 * \return The local translation vector for this object.
+	 */
 	NIFLIB_API Vector3 GetLocalTranslation() const;
+
+	/*!
+	 * Used to set the local translation vector for this object.  This determines the object's offset from its parent.
+	 * \param[in] n The new local translation vector for this object.
+	 */
 	NIFLIB_API void SetLocalTranslation( const Vector3 & n );
 
+	/*!
+	 * Used to get the local scale factor for this object.  The NIF format does not support separate scales along different axis, and many games do not react well to scale factors other than 1.0.
+	 * \return The local scale factor for this object.
+	 */
 	NIFLIB_API float GetLocalScale() const;
+
+	/*!
+	 * Used to set the local scale factor for this object.  The NIF format does not support separate scales along different axis, and many games do not react well to scale factors other than 1.0.
+	 * \param[in] n The new local scale factor for this object.
+	 */
 	NIFLIB_API void SetLocalScale( float n );
 
+	/*!
+	 * Gets the velocity vector for this object.  This vector exists in older NIF files and seems to have no function.
+	 * \return The velocity vector for this object.
+	 */
 	NIFLIB_API Vector3 GetVelocity() const;
+
+	/*!
+	 * Sets the velocity vector for this object.  This vector exists in older NIF files and seems to have no function.
+	 * \param[in] n The new velocity vector for this object.
+	 */
 	NIFLIB_API void SetVelocity( const Vector3 & n );
 
+	/*!
+	 * Gets the current visibility of this object as specified in its flag data.
+	 * \return True if the object is visible, false otherwise.
+	 */
 	NIFLIB_API bool GetVisibility() const;
+
+	/*!
+	 * Sets the current visibility of this object by altering its flag data.
+	 * \param[in] Whether or not the object will now be visible.  True if visible, false otherwise.
+	 */
 	NIFLIB_API void SetVisibility( bool n );
 
 	/*!
-	 * In Oblivion this links the havok objects.
+	 * Gets the current collision object for this object.  Used in later NIF versions.  In Oblivion this links to the Havok objects.
+	 * \return The current collision object for this object.
 	 */
 	NIFLIB_API Ref<NiCollisionObject > GetCollisionObject() const;
+
+	/*!
+	 * Sets the collision object for this object.  Used in later NIF versions.  In Oblivion this links to the Havok objects.
+	 * \param[in] value The new collision object to use.
+	 */
 	NIFLIB_API void SetCollisionObject( NiCollisionObject * value );
 
 	/*!
-	 * Bounding box: refers to NiCollisionData
+	 * Gets the current collision data for this object.  Usually a bounding box.  Used in some NIF versions.
+	 * \return The current collision data for this object.
 	 */
 	NIFLIB_API Ref<NiCollisionData > GetCollisionData() const;
+
+	/*!
+	 * Sets the collision data for this object.  Usually a bounding box.  Used in some NIF versions.
+	 * \param[in] value The new collision data for this object.
+	 */
 	NIFLIB_API void SetCollisionData( NiCollisionData * value );
 
-	NIFLIB_API bool GetHidden();
-	NIFLIB_API void SetHidden(bool value);
+	/*!
+	 * Used to get and set the collision type of a NiAVObject.
+	 */
+	enum CollisionType {
+		/*! No collision */
+		CT_NONE = 0,
+		/*! Collision detection will use the triangles themselves.  Possibly incompatible with triangle strips. */
+		CT_TRIANGLES = 1,
+		/*! Collision detection will use the embedded bounding box information. */
+		CT_BOUNDINGBOX = 2,
+		/*! Collision detection will continue on to the lower objects in the scene graph. */
+		CT_CONTINUE = 3
+	};
 
-   typedef enum CollisionType
-   {
-      CT_NONE, CT_TRIANGLES, CT_BOUNDINGBOX, CT_CONTINUE
-   } CollisionType;
+	/*!
+	 * Gets the current collision detection setting from the object's flag data.
+	 * \return The collision detection setting for this object.
+	 */
+	NIFLIB_API CollisionType GetCollisionMode() const;
 
-   NIFLIB_API CollisionType GetCollision();
-   NIFLIB_API void SetCollision(CollisionType value);
+	/*!
+	 * Sets the current collision detection setting in the object's flag data.
+	 * \param[in] value The new collision detection setting for this object.
+	 */
+	NIFLIB_API void SetCollisionMode( CollisionType value );
 
+   	/*!
+	 * NIFLIB_HIDDEN function.  For internal use only.
+	 * Called by NiNode during the addition of new children.
+	 */
+	NIFLIB_HIDDEN void SetParent( NiNode * new_parent );
 
 protected:
 	NiNode * parent;

include/obj/NiObjectNET.h

@@ -41,22 +41,72 @@ public:
 
 	NIFLIB_API string GetName();
 	NIFLIB_API void SetName( const string & new_name );
+
 	/*!
 	 * Formats a human readable string that includes the type of the object
 	 * \return A string in the form:  address(type) {name}
 	 */
 	NIFLIB_API virtual string GetIDString() const;
 
+	/*! 
+	 * Adds an extra data object to this one.  The way this data is stored changed after version 10.0.1.0, so the version
+	 * can optionally be included to specify the old storage method.
+	 * \param[in] obj The NiExtraData object to attach to this object.
+	 * \param[in] version The way the extra data is arranged internally varies with the NIF version, so if a file is to be written, it is best to pass the intended version.  The default is 10.0.1.0, which specifies the newer behavior.
+	 */
 	NIFLIB_API void AddExtraData( NiExtraData * obj, unsigned version = VER_10_0_1_0 );
+
+	/*! 
+	 * Removes an extra data object to this one.
+	 * \param[in] obj The NiExtraData object to remove from this object.
+	 */
 	NIFLIB_API void RemoveExtraData( NiExtraData * obj );
+
+	/*! 
+	 * Changes the internal storage method of the extra data in preparation for writing to a file.  This is only necessary if the
+	 * extra data was added in one way and needs to be output in another.  This would happen if extra data was loaded from an old file and needed to be written to a file with a newer version.
+	 * \param[in] version Specifies the NIF version that the internal data should be arranged for.
+	 */
 	NIFLIB_API void ShiftExtraData( unsigned int version = VER_10_0_1_0 );
+
+	/*!
+	 * Removes all extra data from this object.
+	 */
 	NIFLIB_API void ClearExtraData();
+
+	/*!
+	 * Returns a list of references to all the extra data referenced by this object.
+	 * \return All the extra data objects referenced by this one.
+	 */
 	NIFLIB_API list< Ref<NiExtraData> > GetExtraData() const;
 
+	/*!
+	 * Used to determine whether this object is animated.  In other words, whether it has any controllers.
+	 * \return True if the object has controllers, false otherwise.
+	 */
 	NIFLIB_API bool IsAnimated();
+
+	/*!
+	 * Adds a controller to this object.  Controllers allow various properties to be animated over time.
+	 * \param[in] obj The controller to add.
+	 */
 	NIFLIB_API void AddController( NiTimeController * obj );
+
+	/*!
+	 * Removes a controller from this object.  Controllers allow various properties to be animated over time.
+	 * \param[in] obj The controller to remove.
+	 */
 	NIFLIB_API void RemoveController( NiTimeController * obj );
+
+	/*!
+	 * Removes all controllers from this object.  This will remove any animation from it.
+	 */
 	NIFLIB_API void ClearControllers();
+
+	/*!
+	 * Gets a list of all controllers affecting this object.
+	 * \return All the controllers affecting this object.
+	 */
 	NIFLIB_API list< Ref<NiTimeController> > GetControllers() const;
 
 	//TODO: pointer to first NiTimeController type.  Need functions to add/remove.

src/obj/NiAVObject.cpp

@@ -8,13 +8,6 @@ All rights reserved.  Please see niflib.h for licence. */
 #include "../../include/obj/NiCollisionObject.h"
 using namespace Niflib;
 
-
-#define NIFLIB_GET_FLAG(value, shift, mask) \
-   (( value >> shift ) & mask)
-
-#define NIFLIB_MASK_FLAG(flag, value, shift, mask) \
-   ((flag ^ ~(mask << shift)) | ((value & mask) << shift))
-
 //Definition of TYPE constant
 const Type NiAVObject::TYPE("NiAVObject", &NI_A_V_OBJECT_PARENT::TypeConst() );
 
@@ -158,19 +151,25 @@ void NiAVObject::SetVelocity( const Vector3 & n ) {
 	velocity = n;
 }
 
-NiAVObject::CollisionType NiAVObject::GetCollision()
-{
-   return (NiAVObject::CollisionType)NIFLIB_GET_FLAG(flags, 1, 0x03);
-}
+NiAVObject::CollisionType NiAVObject::GetCollisionMode() const {
+	//Mask off the 2 significant bits
+	unsigned short temp = flags & 0x6;
 
-void NiAVObject::SetCollision(NiAVObject::CollisionType value)
-{
-   flags = NIFLIB_MASK_FLAG(flags, value, 1, 0x03);
+	//Shift the result one right
+	return NiAVObject::CollisionType(temp >> 1);
 }
 
-bool NiAVObject::GetHidden()
-{
-   return (bool)NIFLIB_GET_FLAG(flags, 0, 0x01);
+void NiAVObject::SetCollisionMode( CollisionType value ) {
+	unsigned short temp = (unsigned short)value;
+
+	//Shift one left
+	temp = temp << 1;
+
+	//Zero out the values in the flags for the 2 significant bits
+	flags = flags & 0xFFF9;
+
+	//Now combine values
+	flags = flags | temp;
 }
 
 Ref<NiCollisionData > NiAVObject::GetCollisionData() const {
@@ -200,11 +199,6 @@ void NiAVObject::SetCollisionObject( NiCollisionObject * value ) {
 	collisionObject = value;
 }
 
-void NiAVObject::SetHidden(bool value)
-{
-   flags = NIFLIB_MASK_FLAG(flags, value, 0, 0x01);
-}
-
 void NiAVObject::SetLocalTransform( const Matrix44 & n ) {
 	n.Decompose( translation, rotation, scale );
 }