0032795: Documentation - clarify indexation range within Poly_Triangulation/Graphic3d...

diff --git a/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx b/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx
index 373789ca78d821490e9f4c74ae99a7ea691fc6a5..f889f4dffceebd5771575e74751d05eb1671daf8 100644 (file)
--- a/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx
+++ b/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx
@@ -300,12 +300,18 @@ public:
   }
 
   //! Change the vertice of rank theIndex in the array.
+  //! @param[in] theIndex  node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theVertex 3D coordinates
   void SetVertice (const Standard_Integer theIndex, const gp_Pnt& theVertex)
   {
     SetVertice (theIndex, Standard_ShortReal (theVertex.X()), Standard_ShortReal (theVertex.Y()), Standard_ShortReal (theVertex.Z()));
   }
 
-  //! Change the vertice of rank theIndex in the array.
+  //! Change the vertice in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theX coordinate X
+  //! @param[in] theY coordinate Y
+  //! @param[in] theZ coordinate Z
   void SetVertice (const Standard_Integer theIndex, const Standard_ShortReal theX, const Standard_ShortReal theY, const Standard_ShortReal theZ)
   {
     Standard_OutOfRange_Raise_if (theIndex < 1 || theIndex > myAttribs->NbMaxElements(), "BAD VERTEX index");
@@ -319,13 +325,19 @@ public:
     }
   }
 
-  //! Change the vertex color of rank theIndex in the array.
+  //! Change the vertex color in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theColor node color
   void SetVertexColor (const Standard_Integer theIndex, const Quantity_Color& theColor)
   {
     SetVertexColor (theIndex, theColor.Red(), theColor.Green(), theColor.Blue());
   }
 
-  //! Change the vertex color of rank theIndex in the array.
+  //! Change the vertex color in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theR red   color value within [0, 1] range
+  //! @param[in] theG green color value within [0, 1] range
+  //! @param[in] theB blue  color value within [0, 1] range
   void SetVertexColor (const Standard_Integer theIndex, const Standard_Real theR, const Standard_Real theG, const Standard_Real theB)
   {
     Standard_OutOfRange_Raise_if (theIndex < 1 || theIndex > myAttribs->NbMaxElements(), "BAD VERTEX index");
@@ -339,7 +351,9 @@ public:
     myAttribs->NbElements = Max (theIndex, myAttribs->NbElements);
   }
 
-  //! Change the vertex color of rank theIndex in the array.
+  //! Change the vertex color in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theColor node RGBA color values within [0, 255] range
   void SetVertexColor (const Standard_Integer  theIndex,
                        const Graphic3d_Vec4ub& theColor)
   {
@@ -352,10 +366,12 @@ public:
     myAttribs->NbElements = Max (theIndex, myAttribs->NbElements);
   }
 
-  //! Change the vertex color of rank theIndex> in the array.
+  //! Change the vertex color in the array.
   //! @code
   //!   theColor32 = Alpha << 24 + Blue << 16 + Green << 8 + Red
   //! @endcode
+  //! @param[in] theIndex   node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theColor32 packed RGBA color values
   void SetVertexColor (const Standard_Integer theIndex, const Standard_Integer theColor32)
   {
     Standard_OutOfRange_Raise_if (theIndex < 1 || theIndex > myAttribs->NbMaxElements(), "BAD VERTEX index");
@@ -365,13 +381,19 @@ public:
     }
   }
 
-  //! Change the vertex normal of rank theIndex in the array.
+  //! Change the vertex normal in the array.
+  //! @param[in] theIndex  node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theNormal normalized surface normal
   void SetVertexNormal (const Standard_Integer theIndex, const gp_Dir& theNormal)
   {
     SetVertexNormal (theIndex, theNormal.X(), theNormal.Y(), theNormal.Z());
   }
 
-  //! Change the vertex normal of rank theIndex in the array.
+  //! Change the vertex normal in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theNX surface normal X component
+  //! @param[in] theNY surface normal Y component
+  //! @param[in] theNZ surface normal Z component
   void SetVertexNormal (const Standard_Integer theIndex, const Standard_Real theNX, const Standard_Real theNY, const Standard_Real theNZ)
   {
     Standard_OutOfRange_Raise_if (theIndex < 1 || theIndex > myAttribs->NbMaxElements(), "BAD VERTEX index");
@@ -385,13 +407,18 @@ public:
     myAttribs->NbElements = Max (theIndex, myAttribs->NbElements);
   }
 
-  //! Change the vertex texel of rank theIndex in the array.
+  //! Change the vertex texel in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theTexel node UV coordinates
   void SetVertexTexel (const Standard_Integer theIndex, const gp_Pnt2d& theTexel)
   {
     SetVertexTexel (theIndex, theTexel.X(), theTexel.Y());
   }
 
-  //! Change the vertex texel of rank theIndex in the array.
+  //! Change the vertex texel in the array.
+  //! @param[in] theIndex node index within [1, VertexNumberAllocated()] range
+  //! @param[in] theTX node U coordinate
+  //! @param[in] theTY node V coordinate
   void SetVertexTexel (const Standard_Integer theIndex, const Standard_Real theTX, const Standard_Real theTY)
   {
     Standard_OutOfRange_Raise_if (theIndex < 1 || theIndex > myAttribs->NbMaxElements(), "BAD VERTEX index");
@@ -404,7 +431,9 @@ public:
     myAttribs->NbElements = Max (theIndex, myAttribs->NbElements);
   }
 
-  //! Returns the vertice at rank theRank from the vertex table if defined.
+  //! Returns the vertice from the vertex table if defined.
+  //! @param[in] theRank node index within [1, VertexNumber()] range
+  //! @return node 3D coordinates
   gp_Pnt Vertice (const Standard_Integer theRank) const
   {
     Standard_Real anXYZ[3];
@@ -413,6 +442,10 @@ public:
   }
 
   //! Returns the vertice coordinates at rank theRank from the vertex table if defined.
+  //! @param[in]  theRank node index within [1, VertexNumber()] range
+  //! @param[out] theX node X coordinate value
+  //! @param[out] theY node Y coordinate value
+  //! @param[out] theZ node Z coordinate value
   void Vertice (const Standard_Integer theRank, Standard_Real& theX, Standard_Real& theY, Standard_Real& theZ) const
   {
     theX = theY = theZ = 0.0;
@@ -424,6 +457,8 @@ public:
   }
 
   //! Returns the vertex color at rank theRank from the vertex table if defined.
+  //! @param[in] theRank node index within [1, VertexNumber()] range
+  //! @return node color RGB value
   Quantity_Color VertexColor (const Standard_Integer theRank) const
   {
     Standard_Real anRGB[3];
@@ -431,7 +466,9 @@ public:
     return Quantity_Color (anRGB[0], anRGB[1], anRGB[2], Quantity_TOC_RGB);
   }
 
-  //! Returns the vertex color at rank theIndex from the vertex table if defined.
+  //! Returns the vertex color from the vertex table if defined.
+  //! @param[in]  theIndex node index within [1, VertexNumber()] range
+  //! @param[out] theColor node RGBA color values within [0, 255] range
   void VertexColor (const Standard_Integer theIndex,
                     Graphic3d_Vec4ub&      theColor) const
   {
@@ -439,7 +476,11 @@ public:
     theColor = *reinterpret_cast<const Graphic3d_Vec4ub* >(myColData + myColStride * (theIndex - 1));
   }
 
-  //! Returns the vertex color values at rank theRank from the vertex table if defined.
+  //! Returns the vertex color values from the vertex table if defined.
+  //! @param[in]  theRank node index within [1, VertexNumber()] range
+  //! @param[out] theR node red   color component value within [0, 1] range
+  //! @param[out] theG node green color component value within [0, 1] range
+  //! @param[out] theB node blue  color component value within [0, 1] range
   void VertexColor (const Standard_Integer theRank, Standard_Real& theR, Standard_Real& theG, Standard_Real& theB) const
   {
     theR = theG = theB = 0.0;
@@ -454,7 +495,9 @@ public:
     theB = Standard_Real(aColor.b()) / 255.0;
   }
 
-  //! Returns the vertex color values at rank theRank from the vertex table if defined.
+  //! Returns the vertex color values from the vertex table if defined.
+  //! @param[in]  theRank  node index within [1, VertexNumber()] range
+  //! @param[out] theColor node RGBA color packed into 32-bit integer
   void VertexColor (const Standard_Integer theRank, Standard_Integer& theColor) const
   {
     Standard_OutOfRange_Raise_if (theRank < 1 || theRank > myAttribs->NbElements, "BAD VERTEX index");
@@ -464,7 +507,9 @@ public:
     }
   }
 
-  //! Returns the vertex normal at rank theRank from the vertex table if defined.
+  //! Returns the vertex normal from the vertex table if defined.
+  //! @param[in] theRank node index within [1, VertexNumber()] range
+  //! @return normalized 3D vector defining surface normal
   gp_Dir VertexNormal (const Standard_Integer theRank) const
   {
     Standard_Real anXYZ[3];
@@ -473,6 +518,10 @@ public:
   }
 
   //! Returns the vertex normal coordinates at rank theRank from the vertex table if defined.
+  //! @param[in]  theRank node index within [1, VertexNumber()] range
+  //! @param[out] theNX   normal X coordinate
+  //! @param[out] theNY   normal Y coordinate
+  //! @param[out] theNZ   normal Z coordinate
   void VertexNormal (const Standard_Integer theRank, Standard_Real& theNX, Standard_Real& theNY, Standard_Real& theNZ) const
   {
     theNX = theNY = theNZ = 0.0;
@@ -487,6 +536,8 @@ public:
   }
 
   //! Returns the vertex texture at rank theRank from the vertex table if defined.
+  //! @param[in] theRank node index within [1, VertexNumber()] range
+  //! @return UV coordinates
   gp_Pnt2d VertexTexel (const Standard_Integer theRank) const
   {
     Standard_Real anXY[2];
@@ -495,6 +546,9 @@ public:
   }
 
   //! Returns the vertex texture coordinates at rank theRank from the vertex table if defined.
+  //! @param[in]  theRank node index within [1, VertexNumber()] range
+  //! @param[out] theTX texel U coordinate value
+  //! @param[out] theTY texel V coordinate value
   void VertexTexel (const Standard_Integer theRank, Standard_Real& theTX, Standard_Real& theTY) const
   {
     theTX = theTY = 0.0;

diff --git a/src/Poly/Poly_Triangle.hxx b/src/Poly/Poly_Triangle.hxx
index 76e6592eca148f6a66e8047040e6e3f37e4e76d4..95c53584ec9de249e3e220cf30e8603cf6b9f659 100644 (file)
--- a/src/Poly/Poly_Triangle.hxx
+++ b/src/Poly/Poly_Triangle.hxx
@@ -24,7 +24,7 @@
 #include <Standard_OutOfRange.hxx>
 
 //! Describes a component triangle of a triangulation (Poly_Triangulation object).
-//! A Triangle is defined by a triplet of nodes.
+//! A Triangle is defined by a triplet of nodes within [1, Poly_Triangulation::NbNodes()] range.
 //! Each node is an index in the table of nodes specific to an existing
 //! triangulation of a shape, and represents a point on the surface.
 class Poly_Triangle

diff --git a/src/Poly/Poly_Triangulation.hxx b/src/Poly/Poly_Triangulation.hxx
index 28a26dec71e0202b146be27284480dc973fbfa86..57104eddb422c8ff9944e898082bb5e555e2dbf2 100644 (file)
--- a/src/Poly/Poly_Triangulation.hxx
+++ b/src/Poly/Poly_Triangulation.hxx
@@ -33,31 +33,24 @@ class Poly_TriangulationParameters;
 
 DEFINE_STANDARD_HANDLE(Poly_Triangulation, Standard_Transient)
 
-//! Provides a triangulation for a surface, a set of surfaces, or
-//! more generally a shape.
-//! A triangulation consists of an approximate representation
-//! of the actual shape, using a collection of points and
-//! triangles. The points are located on the surface. The
-//! edges of the triangles connect adjacent points with a
-//! straight line that approximates the true curve on the surface.
+//! Provides a triangulation for a surface, a set of surfaces, or more generally a shape.
+//!
+//! A triangulation consists of an approximate representation of the actual shape,
+//! using a collection of points and triangles.
+//! The points are located on the surface.
+//! The edges of the triangles connect adjacent points with a straight line that approximates the true curve on the surface.
+//!
 //! A triangulation comprises:
-//! -   A table of 3D nodes (3D points on the surface).
-//! -   A table of triangles. Each triangle (Poly_Triangle
-//! object) comprises a triplet of indices in the table of 3D
-//! nodes specific to the triangulation.
-//! -   A table of 2D nodes (2D points), parallel to the table of
-//! 3D nodes. This table is optional. If it exists, the
-//! coordinates of a 2D point are the (u, v) parameters
-//! of the corresponding 3D point on the surface
-//! approximated by the triangulation.
-//! -   A deflection (optional), which maximizes the distance
-//! from a point on the surface to the corresponding point
-//! on its approximate triangulation.
-//! In many cases, algorithms do not need to work with the
-//! exact representation of a surface. A triangular
-//! representation induces simpler and more robust adjusting,
-//! faster performances, and the results are as good.
-//! This is a Transient class.
+//! - A table of 3D nodes (3D points on the surface).
+//! - A table of triangles.
+//!   Each triangle (Poly_Triangle object) comprises a triplet of indices in the table of 3D nodes specific to the triangulation.
+//! - An optional table of 2D nodes (2D points), parallel to the table of 3D nodes.
+//!   2D point are the (u, v) parameters of the corresponding 3D point on the surface approximated by the triangulation.
+//! - An optional table of 3D vectors, parallel to the table of 3D nodes, defining normals to the surface at specified 3D point.
+//! - An optional deflection, which maximizes the distance from a point on the surface to the corresponding point on its approximate triangulation.
+//!
+//! In many cases, algorithms do not need to work with the exact representation of a surface.
+//! A triangular representation induces simpler and more robust adjusting, faster performances, and the results are as good.
 class Poly_Triangulation : public Standard_Transient
 {
   DEFINE_STANDARD_RTTIEXT(Poly_Triangulation, Standard_Transient)
@@ -134,9 +127,13 @@ public:
   Standard_Boolean HasNormals() const { return !myNormals.IsEmpty(); }
 
   //! Returns a node at the given index.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @return 3D point coordinates
   gp_Pnt Node (Standard_Integer theIndex) const { return myNodes.Value (theIndex - 1); }
 
   //! Sets a node coordinates.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @param[in] thePnt   3D point coordinates
   void SetNode (Standard_Integer theIndex,
                 const gp_Pnt& thePnt)
   {
@@ -144,9 +141,13 @@ public:
   }
 
   //! Returns UV-node at the given index.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @return 2D point defining UV coordinates
   gp_Pnt2d UVNode (Standard_Integer theIndex) const { return myUVNodes.Value (theIndex - 1); }
 
   //! Sets an UV-node coordinates.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @param[in] thePnt   UV coordinates
   void SetUVNode (Standard_Integer theIndex,
                   const gp_Pnt2d&  thePnt)
   {
@@ -154,9 +155,13 @@ public:
   }
 
   //! Returns triangle at the given index.
+  //! @param[in] theIndex triangle index within [1, NbTriangles()] range
+  //! @return triangle node indices, with each node defined within [1, NbNodes()] range
   const Poly_Triangle& Triangle (Standard_Integer theIndex) const { return myTriangles.Value (theIndex); }
 
   //! Sets a triangle.
+  //! @param[in] theIndex triangle index within [1, NbTriangles()] range
+  //! @param[in] theTriangle triangle node indices, with each node defined within [1, NbNodes()] range
   void SetTriangle (Standard_Integer theIndex,
                     const Poly_Triangle& theTriangle)
   {
@@ -164,6 +169,8 @@ public:
   }
 
   //! Returns normal at the given index.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @return normalized 3D vector defining a surface normal
   gp_Dir Normal (Standard_Integer theIndex) const
   {
     const gp_Vec3f& aNorm = myNormals.Value (theIndex - 1);
@@ -171,6 +178,8 @@ public:
   }
 
   //! Returns normal at the given index.
+  //! @param[in]  theIndex node index within [1, NbNodes()] range
+  //! @param[out] theVec3  3D vector defining a surface normal
   void Normal (Standard_Integer theIndex,
                gp_Vec3f& theVec3) const
   {
@@ -178,6 +187,8 @@ public:
   }
 
   //! Changes normal at the given index.
+  //! @param[in] theIndex node index within [1, NbNodes()] range
+  //! @param[in] theVec3  normalized 3D vector defining a surface normal
   void SetNormal (const Standard_Integer theIndex,
                   const gp_Vec3f& theNormal)
   {
@@ -185,6 +196,8 @@ public:
   }
 
   //! Changes normal at the given index.
+  //! @param[in] theIndex  node index within [1, NbNodes()] range
+  //! @param[in] theNormal normalized 3D vector defining a surface normal
   void SetNormal (const Standard_Integer theIndex,
                   const gp_Dir& theNormal)
   {