From 1db24844c6e2a9acf607e144877d4a1b184a5430 Mon Sep 17 00:00:00 2001 From: barry Date: Mon, 17 Oct 2016 17:52:20 -0700 Subject: [PATCH] Minor Doxygen additions and corrections to Far class headers --- opensubdiv/far/patchTable.h | 90 ++++++++++++++--------------- opensubdiv/far/patchTableFactory.h | 2 + opensubdiv/far/topologyDescriptor.h | 11 ++-- opensubdiv/far/topologyLevel.h | 6 +- opensubdiv/far/topologyRefiner.h | 26 +++++++-- 5 files changed, 80 insertions(+), 55 deletions(-) diff --git a/opensubdiv/far/patchTable.h b/opensubdiv/far/patchTable.h index 8cb009ed..4262c924 100644 --- a/opensubdiv/far/patchTable.h +++ b/opensubdiv/far/patchTable.h @@ -162,8 +162,8 @@ public: /// \brief Updates local point vertex values. /// - /// @param src Buffer with primvar data for the coarse vertex values - /// and refined vertex values + /// @param src Buffer with primvar data for the base and refined + /// vertex values /// /// @param dst Destination buffer for the computed local point /// vertex values @@ -182,8 +182,8 @@ public: /// \brief Updates local point varying values. /// - /// @param src Buffer with primvar data for the coarse varying values - /// and refined varying values + /// @param src Buffer with primvar data for the base and refined + /// varying values /// /// @param dst Destination buffer for the computed local point /// varying values @@ -202,8 +202,8 @@ public: /// \brief Updates local point face-varying values. /// - /// @param src Buffer with primvar data for the coarse face-varying - /// values and refined face-varying values + /// @param src Buffer with primvar data for the base and refined + /// face-varying values /// /// @param dst Destination buffer for the computed local point /// face-varying values @@ -298,9 +298,6 @@ public: /// \brief Returns the number of face-varying channels int GetNumFVarChannels() const; - /// \brief Deprecated @see PatchTable#GetFVarPatchDescriptor - Sdc::Options::FVarLinearInterpolation GetFVarChannelLinearInterpolation(int channel = 0) const; - /// \brief Returns the patch descriptor for \p channel PatchDescriptor GetFVarPatchDescriptor(int channel = 0) const; @@ -327,6 +324,9 @@ public: /// \brief Returns an array of face-varying patch param for \p channel ConstPatchParamArray GetFVarPatchParams(int channel = 0) const; + + /// \brief Deprecated @see PatchTable#GetFVarPatchDescriptor + Sdc::Options::FVarLinearInterpolation GetFVarChannelLinearInterpolation(int channel = 0) const; //@} @@ -369,84 +369,84 @@ public: /// /// \brief Evaluate basis functions for position and derivatives at a - /// given (s,t) parametric location of a patch. + /// given (u,v) parametric location of a patch. /// /// @param handle A patch handle indentifying the sub-patch containing the - /// (s,t) location + /// (u,v) location /// - /// @param s Patch coordinate (in coarse face normalized space) + /// @param u Patch coordinate (in base face normalized space) /// - /// @param t Patch coordinate (in coarse face normalized space) + /// @param v Patch coordinate (in base face normalized space) /// /// @param wP Weights (evaluated basis functions) for the position /// - /// @param wDs Weights (evaluated basis functions) for derivative wrt s + /// @param wDu Weights (evaluated basis functions) for derivative wrt u /// - /// @param wDt Weights (evaluated basis functions) for derivative wrt t + /// @param wDv Weights (evaluated basis functions) for derivative wrt v /// - /// @param wDss Weights (evaluated basis functions) for derivative wrt ss + /// @param wDuu Weights (evaluated basis functions) for 2nd derivative wrt u /// - /// @param wDst Weights (evaluated basis functions) for derivative wrt st + /// @param wDuv Weights (evaluated basis functions) for 2nd derivative wrt u and v /// - /// @param wDtt Weights (evaluated basis functions) for derivative wrt tt + /// @param wDvv Weights (evaluated basis functions) for 2nd derivative wrt v /// - void EvaluateBasis(PatchHandle const & handle, float s, float t, - float wP[], float wDs[] = 0, float wDt[] = 0, - float wDss[] = 0, float wDst[] = 0, float wDtt[] = 0) const; + void EvaluateBasis(PatchHandle const & handle, float u, float v, + float wP[], float wDu[] = 0, float wDv[] = 0, + float wDuu[] = 0, float wDuv[] = 0, float wDvv[] = 0) const; /// \brief Evaluate basis functions for a varying value and - /// derivatives at a given (s,t) parametric location of a patch. + /// derivatives at a given (u,v) parametric location of a patch. /// /// @param handle A patch handle indentifying the sub-patch containing the - /// (s,t) location + /// (u,v) location /// - /// @param s Patch coordinate (in coarse face normalized space) + /// @param u Patch coordinate (in base face normalized space) /// - /// @param t Patch coordinate (in coarse face normalized space) + /// @param v Patch coordinate (in base face normalized space) /// /// @param wP Weights (evaluated basis functions) for the position /// - /// @param wDs Weights (evaluated basis functions) for derivative wrt s + /// @param wDu Weights (evaluated basis functions) for derivative wrt u /// - /// @param wDt Weights (evaluated basis functions) for derivative wrt t + /// @param wDv Weights (evaluated basis functions) for derivative wrt v /// - /// @param wDss Weights (evaluated basis functions) for derivative wrt ss + /// @param wDuu Weights (evaluated basis functions) for 2nd derivative wrt u /// - /// @param wDst Weights (evaluated basis functions) for derivative wrt st + /// @param wDuv Weights (evaluated basis functions) for 2nd derivative wrt u and v /// - /// @param wDtt Weights (evaluated basis functions) for derivative wrt tt + /// @param wDvv Weights (evaluated basis functions) for 2nd derivative wrt v /// - void EvaluateBasisVarying(PatchHandle const & handle, float s, float t, - float wP[], float wDs[] = 0, float wDt[] = 0, - float wDss[] = 0, float wDst[] = 0, float wDtt[] = 0) const; + void EvaluateBasisVarying(PatchHandle const & handle, float u, float v, + float wP[], float wDu[] = 0, float wDv[] = 0, + float wDuu[] = 0, float wDuv[] = 0, float wDvv[] = 0) const; /// \brief Evaluate basis functions for a face-varying value and - /// derivatives at a given (s,t) parametric location of a patch. + /// derivatives at a given (u,v) parametric location of a patch. /// /// @param handle A patch handle indentifying the sub-patch containing the - /// (s,t) location + /// (u,v) location /// - /// @param s Patch coordinate (in coarse face normalized space) + /// @param u Patch coordinate (in base face normalized space) /// - /// @param t Patch coordinate (in coarse face normalized space) + /// @param v Patch coordinate (in base face normalized space) /// /// @param wP Weights (evaluated basis functions) for the position /// - /// @param wDs Weights (evaluated basis functions) for derivative wrt s + /// @param wDu Weights (evaluated basis functions) for derivative wrt u /// - /// @param wDt Weights (evaluated basis functions) for derivative wrt t + /// @param wDv Weights (evaluated basis functions) for derivative wrt v /// - /// @param wDss Weights (evaluated basis functions) for derivative wrt ss + /// @param wDuu Weights (evaluated basis functions) for 2nd derivative wrt u /// - /// @param wDst Weights (evaluated basis functions) for derivative wrt st + /// @param wDuv Weights (evaluated basis functions) for 2nd derivative wrt u and v /// - /// @param wDtt Weights (evaluated basis functions) for derivative wrt tt + /// @param wDvv Weights (evaluated basis functions) for 2nd derivative wrt v /// /// @param channel face-varying channel /// - void EvaluateBasisFaceVarying(PatchHandle const & handle, float s, float t, - float wP[], float wDs[] = 0, float wDt[] = 0, - float wDss[] = 0, float wDst[] = 0, float wDtt[] = 0, + void EvaluateBasisFaceVarying(PatchHandle const & handle, float u, float v, + float wP[], float wDu[] = 0, float wDv[] = 0, + float wDuu[] = 0, float wDuv[] = 0, float wDvv[] = 0, int channel = 0) const; //@} diff --git a/opensubdiv/far/patchTableFactory.h b/opensubdiv/far/patchTableFactory.h index 821535c2..975b9d45 100644 --- a/opensubdiv/far/patchTableFactory.h +++ b/opensubdiv/far/patchTableFactory.h @@ -38,6 +38,8 @@ namespace Far { class PtexIndices; class TopologyRefiner; +/// \brief Factory for constructing a PatchTable from a TopologyRefiner +/// class PatchTableFactory { public: diff --git a/opensubdiv/far/topologyDescriptor.h b/opensubdiv/far/topologyDescriptor.h index f605f38b..aceb1049 100644 --- a/opensubdiv/far/topologyDescriptor.h +++ b/opensubdiv/far/topologyDescriptor.h @@ -38,10 +38,13 @@ namespace OPENSUBDIV_VERSION { namespace Far { /// -/// \brief Descriptor for raw topology data, provided as a convenience with -/// a corresponding Factory. It should be functionally complete and simple -/// to use, but for more demanding situations, writing a custom Factory is -/// likely warranted. +/// \brief A simple reference to raw topology data for use with TopologyRefinerFactory +/// +/// TopologyDescriptor is a simple struct containing references to raw topology data used +/// to construct a TopologyRefiner. It is not a requirement but a convenience for use +/// with TopologyRefinerFactory when mesh topology is not available in an existing mesh +/// data structure. It should be functionally complete and simple to use, but for more +/// demanding situations, writing a custom Factory is usually warranted. /// struct TopologyDescriptor { diff --git a/opensubdiv/far/topologyLevel.h b/opensubdiv/far/topologyLevel.h index 1d102e0d..7a19071f 100644 --- a/opensubdiv/far/topologyLevel.h +++ b/opensubdiv/far/topologyLevel.h @@ -38,8 +38,10 @@ namespace OPENSUBDIV_VERSION { namespace Far { /// -/// \brief TopologyLevel is an interface for accessing data in a specific level of a refined -/// topology hierarchy. Instances of TopologyLevel are created and owned by a TopologyRefiner, +/// \brief An interface for accessing data in a specific level of a refined topology hierarchy. +/// +/// TopologyLevel provides an interface to data in a specific level of a topology hierarchy. +/// Instances of TopologyLevel are created and owned by a TopologyRefiner, /// which will return const-references to them. Such references are only valid during the /// lifetime of TopologyRefiner that created and returned them, and only for a given refinement, /// i.e. if the TopologyRefiner is re-refined, any references to TopoologyLevels are invalidated. diff --git a/opensubdiv/far/topologyRefiner.h b/opensubdiv/far/topologyRefiner.h index 75c2292a..0d664a10 100644 --- a/opensubdiv/far/topologyRefiner.h +++ b/opensubdiv/far/topologyRefiner.h @@ -63,7 +63,7 @@ public: /// \brief Returns the subdivision options Sdc::Options GetSchemeOptions() const { return _subdivOptions; } - /// \brief Returns true if uniform subdivision has been applied + /// \brief Returns true if uniform refinement has been applied bool IsUniform() const { return _isUniform; } /// \brief Returns the number of refinement levels @@ -75,7 +75,7 @@ public: /// \brief Returns the maximum vertex valence in all levels int GetMaxValence() const { return _maxValence; } - /// \ brief Returns true if faces have been tagged as holes + /// \brief Returns true if faces have been tagged as holes bool HasHoles() const { return _hasHoles; } /// \brief Returns the total number of vertices in all levels @@ -102,6 +102,18 @@ public: // /// \brief Uniform refinement options + /// + /// Options for uniform refinement, including the number of levels, vertex + /// ordering and generation of topology information. + /// + /// Note the impact of the option to generate fullTopologyInLastLevel. Given + /// subsequent levels of uniform refinement typically reguire 4x the data + /// of the previous level, only the minimum amount of data is generated in the + /// last level by default, i.e. a vertex and face-vertex list. If requiring + /// topology traversal of the last level, e.g. inspecting edges or incident + /// faces of vertices, the option to generate full topology in the last + /// level should be enabled. + /// struct UniformOptions { UniformOptions(int level) : @@ -119,6 +131,12 @@ public: /// \brief Refine the topology uniformly /// + /// This method applies uniform refinement to the level specified in the + /// given UniformOptions. + /// + /// Note the impact of the UniformOption to generate fullTopologyInLastLevel + /// and be sure it is assigned to satisfy the needs of the resulting refinement. + /// /// @param options Options controlling uniform refinement /// void RefineUniform(UniformOptions options); @@ -164,7 +182,7 @@ public: /// \brief Returns the options specified on refinement AdaptiveOptions GetAdaptiveOptions() const { return _adaptiveOptions; } - /// \brief Unrefine the topology (keep control cage) + /// \brief Unrefine the topology, keeping only the base level. void Unrefine(); @@ -175,7 +193,7 @@ public: /// \brief Returns the number of face-varying channels in the tables int GetNumFVarChannels() const; - /// \brief Returns the face-varying interpolation rule-set for a given channel + /// \brief Returns the face-varying interpolation rule set for a given channel Sdc::Options::FVarLinearInterpolation GetFVarLinearInterpolation(int channel = 0) const; /// \brief Returns the total number of face-varying values in all levels