From 47ed3dd57faead6220e8f0436b3fcdb751b3a422 Mon Sep 17 00:00:00 2001
From: Shon Ferguson <shonferg@users.sourceforge.net>
Date: Mon, 20 Feb 2006 19:53:56 +0000
Subject: [PATCH] Added more Doxygen documentation. Simplified the
ITriShapeData and ITriStripsData interfaces slightly.
---
NIF_Blocks.cpp | 16 ++----
NIF_Blocks.h | 7 ++-
niflib.h | 136 ++++++++++++++++++++++++++++++++++++++++++++++---
3 files changed, 136 insertions(+), 23 deletions(-)
diff --git a/NIF_Blocks.cpp b/NIF_Blocks.cpp
index b6bf432b..152520bd 100644
--- a/NIF_Blocks.cpp
+++ b/NIF_Blocks.cpp
@@ -2014,21 +2014,13 @@ void const * NiTriShapeData::QueryInterface( int id ) const {
}
}
-void NiTriShapeData::SetTriangleCount(int n) {
- if ( n > 65535 || n < 0 )
- throw runtime_error("Invalid Triangle Count: must be between 0 and 65535.");
-
- if ( n == 0 )
- triangles.clear();
- else
- triangles.resize(n);
-}
-
//--Setters--//
void NiTriShapeData::SetTriangles( const vector<Triangle> & in ) {
- if (in.size() != triangles.size())
- throw runtime_error("Vector size must equal Triangle Count. Call SetTriangleCount() to resize.");
+ if ( in.size() > 65535 || in.size() < 0 ) {
+ throw runtime_error("Invalid Triangle Count: must be between 0 and 65535.");
+ }
+
triangles = in;
}
diff --git a/NIF_Blocks.h b/NIF_Blocks.h
index f42cdb74..58518dfe 100644
--- a/NIF_Blocks.h
+++ b/NIF_Blocks.h
@@ -934,9 +934,7 @@ public:
void const * QueryInterface( int id ) const;
//--ITriShapeData--//
- //Counts
- short GetTriangleCount() const { return short(triangles.size()); }
- void SetTriangleCount(int n);
+
//Match Detection
void SetMatchDetectionMode(bool choice) { match_group_mode = choice; }
bool GetMatchDetectionMode() const { return match_group_mode; }
@@ -970,7 +968,7 @@ public:
//Counts
short GetStripCount() const;
void SetStripCount(int n);
- short GetTriangleCount() const;
+
//Getters
vector<short> GetStrip( int index ) const;
vector<Triangle> GetTriangles() const;
@@ -978,6 +976,7 @@ public:
void SetStrip( int index, const vector<short> & in );
private:
+ short GetTriangleCount() const;
vector< vector<short> > strips;
};
diff --git a/niflib.h b/niflib.h
index 74bc8687..e07118d7 100644
--- a/niflib.h
+++ b/niflib.h
@@ -188,7 +188,7 @@ enum TexFilterMode {
};
#ifndef NULL
-#define NULL 0
+#define NULL 0 /*!< Definition used to detect null pointers. */
#endif
/*!
@@ -1145,6 +1145,7 @@ struct Matrix44 {
rows[3][0] = m41; rows[3][1] = m42; rows[3][2] = m43; rows[3][3] = m44;
}
+ //undocumented
void AsFloatArr( float out[4][4] ) {
out[0][0] = rows[0][0]; out[0][1] = rows[0][1]; out[0][2] = rows[0][2]; out[0][3] = rows[0][3];
out[1][0] = rows[1][0]; out[1][1] = rows[1][1]; out[1][2] = rows[1][2]; out[1][3] = rows[1][3];
@@ -1839,55 +1840,176 @@ public:
virtual Matrix44 GetLocalBindPos() const = 0;
};
+/*! An advanced interface for blocks which contain mesh data.
+ * \sa ITriShapeData, ITriStripsData
+ */
class IShapeData {
public:
IShapeData() {}
virtual ~IShapeData() {}
//Counts
+
+ /*! Returns the number of verticies that make up this mesh. This is also the number of normals, colors, and UV coordinates if these are used.
+ * \return The number of vertices that make up this mesh.
+ * \sa IShapeData::SetVertexCount
+ */
virtual short GetVertexCount() const = 0;
+
+ /*! Returns the number of texture coordinate sets used by this mesh. For each UV set, there is a pair of texture coordinates for every vertex in the mesh. Each set corresponds to a texture entry in the NiTexturingPropery block.
+ * \return The number of texture cooridnate sets used by this mesh. Can be zero.
+ * \sa IShapeData::SetUVSetCount, ITexturingProperty
+ */
virtual short GetUVSetCount() const = 0;
+
+ /*! Changes the number of vertices used by this mesh. If the mesh already contains data, it will be retained so long as the new number is higher than the old number. Otherwise any verticies above the new number will be deleted. This also resizes any normal, color, or UV data associated with these verticies. Triangles and triangle strips that may be attached via other interfaces are not culled of references to newly invalid vertices, however.
+ * \param n The new size of the vertex array.
+ * \sa IShapeData::GetVertexCount
+ */
virtual void SetVertexCount(int n) = 0;
+
+ /*! Changes the number of UV sets used by this mesh. If he new size is smaller, data at the end of the array will be lost. Otherwise it will be retained. The number of UV sets must correspond with the number of textures defined in the corresponding NiTexturingProperty block.
+ * \param n The new size of the uv set array.
+ * \sa IShapeData::GetUVSetCount, ITexturingProperty
+ */
virtual void SetUVSetCount(int n) = 0;
+
//Getters
+
+ /*! Used to retrive the vertices used by this mesh. The size of the vector will be the same as the vertex count retrieved with the IShapeData::GetVertexCount function.
+ * \return A vector cntaining the vertices used by this mesh.
+ * \sa IShapeData::SetVertices, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual vector<Vector3> GetVertices() const = 0;
+
+ /*! Used to retrive the normals used by this mesh. The size of the vector will either be zero if no normals are used, or be the same as the vertex count retrieved with the IShapeData::GetVertexCount function.
+ * \return A vector cntaining the normals used by this mesh, if any.
+ * \sa IShapeData::SetNormals, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual vector<Vector3> GetNormals() const = 0;
+
+ /*! Used to retrive the vertex colors used by this mesh. The size of the vector will either be zero if no vertex colors are used, or be the same as the vertex count retrieved with the IShapeData::GetVertexCount function.
+ * \return A vector cntaining the vertex colors used by this mesh, if any.
+ * \sa IShapeData::SetColors, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual vector<Color4> GetColors() const = 0;
+
+ /*! Used to retrive the texture coordinates from one of the texture sets used by this mesh. The function will throw an exception if a texture set index that does not exist is specified. The size of the vector will be the same as the vertex count retrieved with the IShapeData::GetVertexCount function.
+ * \param index The index of the texture coordinate set to retrieve the texture coordinates from. This index is zero based and must be a positive number smaller than that returned by the IShapeData::GetUVSetCount function. If there are no texture coordinate sets, this function will throw an exception.
+ * \return A vector cntaining the the texture coordinates used by the requested texture coordinate set.
+ * \sa IShapeData::SetUVSet, IShapeData::GetUVSetCount, IShapeData::SetUVSetCount, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual vector<TexCoord> GetUVSet( int index ) const = 0;
+
//Setters
+
+ /*! Used to set the vertex data used by this mesh. The size of the vector must be the same as the vertex count retrieved with the IShapeData::GetVertexCount function or the function will throw an exception.
+ * \param in A vector containing the vertices to replace those in the mesh with. Note that there is no way to set vertices one at a time, they must be sent in one batch.
+ * \sa IShapeData::GetVertices, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual void SetVertices( const vector<Vector3> & in ) = 0;
+
+ /*! Used to set the normal data used by this mesh. The size of the vector must either be zero, or the same as the vertex count retrieved with the IShapeData::GetVertexCount function or the function will throw an exception.
+ * \param in A vector containing the normals to replace those in the mesh with. Note that there is no way to set normals one at a time, they must be sent in one batch. Use an empty vector to signify that this mesh will not be using normals.
+ * \sa IShapeData::GetNormals, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual void SetNormals( const vector<Vector3> & in ) = 0;
+
+ /*! Used to set the vertex color data used by this mesh. The size of the vector must either be zero, or the same as the vertex count retrieved with the IShapeData::GetVertexCount function or the function will throw an exception.
+ * \param in A vector containing the vertex colors to replace those in the mesh with. Note that there is no way to set vertex colors one at a time, they must be sent in one batch. Use an empty vector to signify that this mesh will not be using vertex colors.
+ * \sa IShapeData::GetColors, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual void SetColors( const vector<Color4> & in ) = 0;
+
+ /*! Used to set the texture coordinate data from one of the texture sets used by this mesh. The function will throw an exception if a texture set index that does not exist is specified. The size of the vector must be the same as the vertex count retrieved with the IShapeData::GetVertexCount function, or the function will throw an exception.
+ * \param index The index of the texture coordinate set to retrieve the texture coordinates from. This index is zero based and must be a positive number smaller than that returned by the IShapeData::GetUVSetCount function. If there are no texture coordinate sets, this function will throw an exception.
+ * \param in A vector containing the the new texture coordinates to replace those in the requested texture coordinate set.
+ * \sa IShapeData::GetUVSet, IShapeData::GetUVSetCount, IShapeData::SetUVSetCount, IShapeData::GetVertexCount, IShapeData::SetVertexCount.
+ */
virtual void SetUVSet( int index, const vector<TexCoord> & in ) = 0;
};
+/*! An advanced interface for blocks which contain mesh data which includes triangle faces.
+ * \sa IShapeData, ITriStripsData
+ */
class ITriShapeData {
public:
ITriShapeData() {}
virtual ~ITriShapeData () {}
- //Counts
- virtual short GetTriangleCount() const = 0;
- virtual void SetTriangleCount( int n ) = 0;
+
//Match Detection
+
+ /*! Used to turn match detection mode on and off. When match detection mode is on, a list of all the vertices that have identical positions are stored in the file. This may improve performance but is not well understood.
+ * \param choice True to enable match detection mode, false to disable it.
+ * \sa ITriShapeData::GetMatchDetectionMode
+ */
virtual void SetMatchDetectionMode( bool choice ) = 0;
+
+ /*! Used to query the current match detection mode. When match detection mode is on, a list of all the vertices that have identical positions are stored in the file. This may improve performance but is not well understood.
+ * \return True if match detection mode is on, false otherwise.
+ * \sa ITriShapeData::GetMatchDetectionMode
+ */
virtual bool GetMatchDetectionMode() const = 0;
+
//Getters
+
+ /*! Returns the triangle faces that make up this mesh.
+ * \return A vector containing the triangle faces that make up this mesh.
+ * \sa ITriShapeData::SetTriangles
+ */
virtual vector<Triangle> GetTriangles() const = 0;
+
//Setters
+
+ /*! Replaces the triangle face data in this mesh with new data.
+ * \param in A vector containing the new face data. Maximum size is 65,535.
+ * \sa ITriShapeData::GetTriangles
+ */
virtual void SetTriangles( const vector<Triangle> & in ) = 0;
};
+/*! An advanced interface for blocks which contain mesh data which includes triangle faces arranged into strips for better performance. Apparently cannot be used for meshes whos triangles are used in collision tests.
+ * \sa IShapeData, ITriShapeData
+ */
class ITriStripsData {
public:
ITriStripsData() {}
virtual ~ITriStripsData () {}
+
//Counts
- virtual short GetTriangleCount() const = 0;
+
+ /*! Used to get the number of triangle strips that this mesh is divided into.
+ * \return The number of triangle strips used by this mesh.
+ * \sa ITriStripData::SetStripCount
+ */
virtual short GetStripCount() const = 0;
+
+ /*! Used to resize the triangle strips array. If the new size is smaller, strips at the end of the array will be deleted.
+ * \param n The new size of the triangle strips array.
+ * \sa ITriStripData::GetStripCount
+ */
virtual void SetStripCount( int n ) = 0;
- //Getter
- virtual vector<short> GetStrip( int index ) const = 0;
+
+ //Getters
+
+ /*! This is a conveniance function which returns all triangle faces in all triangle strips that make up this mesh. It is similar to the ITriShapeData::GetTriangles function.
+ * \return A vector containing all the triangle faces from all the triangle strips that make up this mesh.
+ * \sa ITriShapeData::GetTriangles, ITriStripsData::GetStrip, ITriStripsData::SetStrip
+ */
virtual vector<Triangle> GetTriangles() const = 0;
+
+ /*! Used to retrieve all the triangles from a specific triangle strip.
+ * \param index The index of the triangle strip to retrieve the triangles from. This is a zero-based index which must be a positive number less than that returned by NiTriStripsData::GetStripCount.
+ * \return A vector containing all the triangle faces from the triangle strip specified by index.
+ * \sa ITriStripsData::SetStrip, ITriStripsData::GetTriangles
+ */
+ virtual vector<short> GetStrip( int index ) const = 0;
+
//Setter
+
+ /*! Used to set the triangle face data in a specific triangle strip.
+ * \param index The index of the triangle strip to set the face data for. This is a zero-based index which must be a positive number less than that returned by NiTriStripsData::GetStripCount.
+ * \sa ITriStripsData::GetStrip, ITriStripsData::GetTriangles
+ */
virtual void SetStrip( int index, const vector<short> & in ) = 0;
};
--
GitLab