diff --git a/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx b/src/Graphic3d/Graphic3d_ArrayOfPrimitives.hxx index 373789ca78..f889f4dffc 100644 --- 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(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 76e6592eca..95c53584ec 100644 --- a/src/Poly/Poly_Triangle.hxx +++ b/src/Poly/Poly_Triangle.hxx @@ -24,7 +24,7 @@ #include //! 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 28a26dec71..57104eddb4 100644 --- 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) {