From 63d761c0beaa35e6b8c8ef05d2b60ba2c4f9e52f Mon Sep 17 00:00:00 2001 From: Nick Avramoussis <4256455+Idclip@users.noreply.github.com> Date: Fri, 14 May 2021 15:42:26 +0100 Subject: [PATCH 1/2] Added extra latex modules to doc CI for AX doxygen Signed-off-by: Nick Avramoussis <4256455+Idclip@users.noreply.github.com> --- .github/workflows/docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index ffc99506de..62cccbe70e 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,7 +20,7 @@ on: jobs: doxygen: - runs-on: ubuntu-16.04 + runs-on: ubuntu-latest env: CXX: g++ container: @@ -32,7 +32,7 @@ jobs: - name: install_epydoc run: pip install epydoc - name: install_latex - run: yum -y install texlive-latex-bin texlive-dvips + run: yum -y install texlive-latex-bin texlive-dvips texlive-collection-fontsrecommended texlive-collection-latexrecommended - name: build run: ./ci/build.sh Release None OFF None "core,python,doc" -DOPENVDB_PYTHON_WRAP_ALL_GRID_TYPES=ON -DDISABLE_DEPENDENCY_VERSION_CHECKS=ON - name: epydoc From 85d997fe151137ade7fa725be8f1823669585cbe Mon Sep 17 00:00:00 2001 From: Nick Avramoussis <4256455+Idclip@users.noreply.github.com> Date: Mon, 17 May 2021 17:15:41 +0100 Subject: [PATCH 2/2] Fixed various doxygen warnings and errors Signed-off-by: Nick Avramoussis <4256455+Idclip@users.noreply.github.com> --- doc/CMakeLists.txt | 3 +- doc/changes.txt | 2 +- openvdb/openvdb/version.h.in | 59 ++++++++------- openvdb_ax/openvdb_ax/codegen/FunctionTypes.h | 2 +- .../openvdb_ax/compiler/PointExecutable.h | 5 +- .../openvdb_ax/compiler/VolumeExecutable.h | 71 +++++++++++-------- 6 files changed, 83 insertions(+), 59 deletions(-) diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 6f79dbf05b..9779da5788 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -55,7 +55,8 @@ set(DOXY_FILES set(DOXYGEN_PROJECT_NAME "OpenVDB") set(DOXYGEN_PROJECT_NUMBER "${OpenVDB_VERSION}") set(DOXYGEN_PROJECT_BRIEF "") -set(DOXYGEN_FILE_PATTERNS "*.h") # headers only +set(DOXYGEN_FILE_PATTERNS *.h *h.in) # headers only +set(DOXYGEN_EXTENSION_MAPPING .in=C) # parse CMake config headers as C set(DOXYGEN_IMAGE_PATH "doc/img") set(DOXYGEN_RECURSIVE NO) diff --git a/doc/changes.txt b/doc/changes.txt index 63c7374f69..cdae93c05b 100644 --- a/doc/changes.txt +++ b/doc/changes.txt @@ -32,7 +32,7 @@ Improvements: Performance gains will improve relative to increases in the inputs size and dilation scheme. - Added an optional argument to - @vdblink::Tree::topologyUnion() Tree::topologyUnion@endlink which preserves + @vdblink::tree::Tree::topologyUnion() Tree::topologyUnion@endlink which preserves active tiles on the destination tree should they overlap leaf nodes from the source tree. - Reduced the time spent in the hot path of @vdblink::initialize() initialize@endlink diff --git a/openvdb/openvdb/version.h.in b/openvdb/openvdb/version.h.in index 51676cf9f0..0f39063245 100644 --- a/openvdb/openvdb/version.h.in +++ b/openvdb/openvdb/version.h.in @@ -51,20 +51,26 @@ /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// -/// @brief Auto generated build configurations from CMake +// Auto generated build configurations from CMake -/* Library major, minor and patch version numbers */ +///@{ +/// @brief Library major, minor and patch version numbers +/// @hideinitializer #define OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER ${OpenVDB_MAJOR_VERSION} +/// @hideinitializer #define OPENVDB_LIBRARY_MINOR_VERSION_NUMBER ${OpenVDB_MINOR_VERSION} +/// @hideinitializer #define OPENVDB_LIBRARY_PATCH_VERSION_NUMBER ${OpenVDB_PATCH_VERSION} +///@} -/* The ABI version that OpenVDB was built with */ /// @note This ifndef exists for compatibility with older versions of OpenVDB. /// This value should never be different from the value configured when /// OpenVDB was built, but this previously needed to be defined by downstream /// software. Redefining it here would cause build failures, so this allows /// users to transition and remove the define in their build systems. #ifndef OPENVDB_ABI_VERSION_NUMBER +/// @brief The ABI version that OpenVDB was built with +/// @hideinitializer #define OPENVDB_ABI_VERSION_NUMBER ${OPENVDB_ABI_VERSION_NUMBER} #endif @@ -82,31 +88,31 @@ /// @hideinitializer #define OPENVDB_LIBRARY_ABI_VERSION_STRING "${OpenVDB_MAJOR_VERSION}.${OpenVDB_MINOR_VERSION}.${OpenVDB_PATCH_VERSION}abi${OPENVDB_ABI_VERSION_NUMBER}" -/// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch) +/// @brief Library version number as a packed integer ("%02x%02x%04x", major, minor, patch) +/// @hideinitializer #define OPENVDB_LIBRARY_VERSION_NUMBER ${OPENVDB_PACKED_VERSION} +/// @brief The version namespace name for this library version +/// @hideinitializer +/// +/// When the ABI version number matches the library major version number, +/// symbols are named as in the following examples: +/// - @b openvdb::vX_Y::Vec3i +/// - @b openvdb::vX_Y::io::File +/// - @b openvdb::vX_Y::tree::Tree +/// +/// where X and Y are the major and minor version numbers. +/// +/// When the ABI version number does not match the library major version number, +/// symbol names include the ABI version: +/// - @b openvdb::vX_YabiN::Vec3i +/// - @b openvdb::vX_YabiN::io::File +/// - @b openvdb::vX_YabiN::tree::Tree +/// +/// where X, Y and N are the major, minor and ABI version numbers, respectively. #if OPENVDB_ABI_VERSION_NUMBER == OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER - /// @brief The version namespace name for this library version - /// @hideinitializer - /// - /// When the ABI version number matches the library major version number, - /// symbols are named as in the following examples: - /// - @b openvdb::vX_Y::Vec3i - /// - @b openvdb::vX_Y::io::File - /// - @b openvdb::vX_Y::tree::Tree - /// - /// where X and Y are the major and minor version numbers. - /// - /// When the ABI version number does not match the library major version number, - /// symbol names include the ABI version: - /// - @b openvdb::vX_YabiN::Vec3i - /// - @b openvdb::vX_YabiN::io::File - /// - @b openvdb::vX_YabiN::tree::Tree - /// - /// where X, Y and N are the major, minor and ABI version numbers, respectively. #define OPENVDB_VERSION_NAME v${OpenVDB_MAJOR_VERSION}_${OpenVDB_MINOR_VERSION} #else - // This duplication of code is necessary to avoid issues with recursive macro expansion. #define OPENVDB_VERSION_NAME v${OpenVDB_MAJOR_VERSION}_${OpenVDB_MINOR_VERSION}abi${OPENVDB_ABI_VERSION_NUMBER} #endif @@ -177,14 +183,17 @@ namespace OPENVDB_VERSION_NAME { /// @details This can be used to quickly test whether we have a valid file or not. const int32_t OPENVDB_MAGIC = 0x56444220; -// Library major, minor and patch version numbers +/// Library major, minor and patch version numbers +/// @hideinitializer const uint32_t OPENVDB_LIBRARY_MAJOR_VERSION = OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER, OPENVDB_LIBRARY_MINOR_VERSION = OPENVDB_LIBRARY_MINOR_VERSION_NUMBER, OPENVDB_LIBRARY_PATCH_VERSION = OPENVDB_LIBRARY_PATCH_VERSION_NUMBER; /// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch) +/// @hideinitializer const uint32_t OPENVDB_LIBRARY_VERSION = OPENVDB_LIBRARY_VERSION_NUMBER; -// ABI version number +/// ABI version number +/// @hideinitializer const uint32_t OPENVDB_ABI_VERSION = OPENVDB_ABI_VERSION_NUMBER; /// @brief The current version number of the VDB file format diff --git a/openvdb_ax/openvdb_ax/codegen/FunctionTypes.h b/openvdb_ax/openvdb_ax/codegen/FunctionTypes.h index 6dbf7cdff9..1c771597dc 100644 --- a/openvdb_ax/openvdb_ax/codegen/FunctionTypes.h +++ b/openvdb_ax/openvdb_ax/codegen/FunctionTypes.h @@ -823,7 +823,7 @@ struct FunctionGroup /// signature, generate and execute the function body. Returns the /// return value of the function (nullptr if void). The behaviour /// is undefined if a valid match does not exist. For such cases, - /// call the second version of ::execute. + /// call the second version of FunctionGroup::execute. /// @note This function will throw if no valid return is provided by the /// matched declaration implementation. /// diff --git a/openvdb_ax/openvdb_ax/compiler/PointExecutable.h b/openvdb_ax/openvdb_ax/compiler/PointExecutable.h index ffa3718e73..2f92b955e4 100644 --- a/openvdb_ax/openvdb_ax/compiler/PointExecutable.h +++ b/openvdb_ax/openvdb_ax/compiler/PointExecutable.h @@ -43,7 +43,8 @@ class Compiler; /// executable object; immutable except for execution settings and implements /// 'execute' functions which can be called multiple times for arbitrary sets /// of inputs. The intended usage of these executables is to configure their -/// runtime arguments and then call ::execute with your VDBs. For example: +/// runtime arguments and then call PointExecutable::execute with your VDBs. +/// For example: /// @code /// PointExecutable::Ptr exe = compiler.compile("@a += 1"); /// exe->setCreateMissing(false); // fail on missing attributes @@ -62,6 +63,8 @@ class Compiler; /// - Grain size: 1 /// The default grain sizes passed to the tbb partitioner for leaf level /// processing. +/// @sa setGrainSize +/// /// For more in depth information, see the @ref vdbaxcompilerexe documentation. class PointExecutable { diff --git a/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h b/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h index ba8f910d9d..6134568d50 100644 --- a/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h +++ b/openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h @@ -42,7 +42,8 @@ class Compiler; /// executable object; immutable except for execution settings and implements /// 'execute' functions which can be called multiple times for arbitrary sets /// of inputs. The intended usage of these executables is to configure their -/// runtime arguments and then call ::execute with your VDBs. For example: +/// runtime arguments and then call VolumeExecutable::execute with your VDBs. +/// For example: /// @code /// VolumeExecutable::Ptr exe = compiler.compile("@a += 1"); /// exe->setTreeExecutionLevel(0); // only process leaf nodes @@ -58,15 +59,18 @@ class Compiler; /// - Iteration Type: ON /// By default, processes ACTIVE values. /// @sa setValueIterator -/// - Active Tile Streaming: ON or OFF depending on AX code. +/// - Active Tile Streaming: ON, OFF or AUTO depending on AX code. /// By default, if AX detects that the AX program may produce unique /// values for leaf level voxels that would otherwise comprise a -/// given active tile, this setting is set to ON. Otherwise it is set to -/// OFF. +/// given active tile, this setting is set to ON or AUTO. Otherwise it is +/// set to OFF. /// @sa setActiveTileStreaming /// - Grain sizes: 1:32 /// The default grain sizes passed to the tbb partitioner for leaf level /// processing and active tile processing. +/// @sa setGrainSize +/// @sa setActiveTileStreamingGrainSize +/// /// For more in depth information, see the @ref vdbaxcompilerexe documentation. class VolumeExecutable { @@ -93,7 +97,7 @@ class VolumeExecutable /// /// @param grids The VDB Volumes to process void execute(openvdb::GridPtrVec& grids) const; - void execute(openvdb::GridBase& grid) const; + void execute(openvdb::GridBase& grids) const; ///@} //////////////////////////////////////////////////////// @@ -117,30 +121,34 @@ class VolumeExecutable /// than the root node's level) will cause this method to throw a runtime /// error. /// @param min The minimum tree execution level to set - /// @param min The maximum tree execution level to set + /// @param max The maximum tree execution level to set void setTreeExecutionLevel(const Index min, const Index max); /// @param level The tree execution level to set. Calls setTreeExecutionLevel /// with min and max arguments as level. void setTreeExecutionLevel(const Index level); - /// @return Get the tree execution levels. + /// @brief Get the tree execution levels. + /// @param min The minimum tree execution level + /// @param max The maximum tree execution level void getTreeExecutionLevel(Index& min, Index& max) const; /// @brief The streaming type of active tiles during execution. - /// ON: active tiles are temporarily densified (converted to leaf level - /// voxels) on an "as needed" basis and the subsequent voxel values are - /// processed. The temporarily densified node is added to the tree only - /// if a non constant voxel buffer is produced. Otherwise a child tile - /// may be created or the original tile's value may simply be modified. - /// OFF: tile topologies are left unchanged and their single value is + /// @param ON active tiles are temporarily densified (converted to leaf + /// level voxels) on an "as needed" basis and the subsequent voxel + /// values are processed. The temporarily densified node is added to the + /// tree only if a non constant voxel buffer is produced. Otherwise a + /// child tile may be created or the original tile's value may simply be + /// modified. + /// @param OFF tile topologies are left unchanged and their single value is /// processed. - /// AUTO: the volume executable analyzes the compiled kernel and attempts - /// to determine if expansion of active tiles would lead to different, - /// non-constant values in the respective voxels. This is done on a per - /// grid basis; ultimately each execution will be set to ON or OFF. - /// This option will always fall back to ON if there is any chance the - /// kernel may produce child nodes - /// The volume executable always runs an AUTO check on creation and will - /// set itself to ON (if all grids always need child nodes), OFF (if + /// @param AUTO the volume executable analyzes the compiled kernel and + /// attempts to determine if expansion of active tiles would lead to + /// different, non-constant values in the respective voxels. This is + /// done on a per grid basis; ultimately each execution will be set to + /// ON or OFF. This option will always fall back to ON if there is any + /// chance the kernel may produce child nodes + /// + /// @note The volume executable always runs an AUTO check on creation and + /// will set itself to ON (if all grids always need child nodes), OFF (if /// grids never need child nodes) or remains as AUTO (if this depends on /// which grid is being processed). /// @@ -149,8 +157,9 @@ class VolumeExecutable /// unique voxels such that they can each receive a unique value. For /// example, consider the following AX code which assigns a vector volume /// to the world space position of each voxel: + /// @code /// v@v = getvoxelpws(); - /// + /// @endcode /// Active tiles hold a single value but comprise an area greater than /// that of a single voxel. As the above kernel varies with respect to /// a nodes position, we'd need to replace these tiles with leaf voxels @@ -158,24 +167,26 @@ class VolumeExecutable /// in this case. /// /// This behaviour, however, is not always desirable .i.e: + /// @code /// v@v = {1,2,3}; - /// + /// @endcode /// In this instance, all values within a volume receive the same value /// and are not dependent on any spatially or iteratively varying /// metrics. The stream flag is set to OFF. /// /// The AUTO flag is set in cases where the runtime access pattern of the /// inputs determines streaming: + /// @code /// f@density = f@mask; /// f@mask = 0; - /// - /// In this instance, the runtime topology and values of @mask determines - /// whether child topology needs to be created in @density, but @mask + /// @endcode + /// In this instance, the runtime topology and values of \@mask determines + /// whether child topology needs to be created in \@density, but \@mask /// itself does not need streaming. Streaming will be set to ON for /// density but OFF for mask. /// /// @note This behaviour is only applied to active tiles. If the value - /// iterator is set to OFF (@sa setValueIterator), this option is ignored. + /// iterator is set to OFF, this option is ignored. /// @warning This option can generate large amounts of leaf level voxels. /// It is recommended to use a good concurrent memory allocator (such as /// jemalloc) for the best performance. @@ -217,15 +228,15 @@ class VolumeExecutable /// @note Setting g1 or g2 to zero has the effect of disabling /// multi-threading for the respective node executions. Setting both to /// zero will disable all multi-threading performed by the execute method. - /// @param g1 The grain size used for non streamed nodes (leafs or tiles) - /// @param g2 The grain size used for streamed execution (active tiles) void setGrainSize(const size_t g1); void setActiveTileStreamingGrainSize(const size_t g2); /// @return The current g1 grain size + /// @sa setGrainSize size_t getGrainSize() const; /// @return The current g2 grain size + /// @sa setActiveTileStreamingGrainSize size_t getActiveTileStreamingGrainSize() const; - ///}@ + ///@}