diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index b43d3fadf0..346ae60941 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,16 +1,19 @@ ### Description of Change(s) +### Link to proposal ([if applicable](https://openusd.org/release/contributing_to_usd.html#step-1-get-consensus-for-major-changes)) + ### Fixes Issue(s) -- - - -- [ ] I have verified that all unit tests pass with the proposed changes - -- [ ] I have submitted a signed Contributor License Agreement + +### Checklist + +[ ] I have created this PR based on the dev branch + +[ ] I have followed the [coding conventions](https://openusd.org/release/api/_page__coding__guidelines.html) + +[ ] I have added unit tests that exercise this functionality (Reference: +[testing guidelines](https://openusd.org/release/api/_page__testing__guidelines.html)) + +[ ] I have verified that all unit tests pass with the proposed changes + +[ ] I have submitted a signed Contributor License Agreement (Reference: +[Contributor License Agreement instructions](https://openusd.org/release/contributing_to_usd.html#contributor-license-agreement)) diff --git a/.github/workflows/buildusd.yml b/.github/workflows/buildusd.yml new file mode 100644 index 0000000000..a5d8485e81 --- /dev/null +++ b/.github/workflows/buildusd.yml @@ -0,0 +1,192 @@ +name: BuildUSD + +on: + push: + branches: + - dev + - release + issue_comment: + types: [created] + +env: + PYTHON_VERSION: "3.9" + PYTHON_VERSION_MAC: "3.11" + +jobs: + GetUser: + runs-on: ubuntu-20.04 + timeout-minutes: 5 + outputs: + require-result: ${{ steps.check.outputs.require-result }} + steps: + - uses: actions-cool/check-user-permission@v2 + id: check + with: + require: 'write' + username: ${{ github.event.comment.user.login }} + GetGitRef: + runs-on: ubuntu-20.04 + timeout-minutes: 5 + outputs: + ref: ${{ steps.setter.outputs.ref }} + steps: + - name: Get push ref + if: ${{ github.event_name == 'push' }} + run: | + echo "REF=${{ github.ref }}" >> $GITHUB_ENV + - name: Get PR ref + if: ${{ github.event.issue.pull_request }} + run: | + echo "REF=refs/pull/${{ github.event.issue.number }}/merge" >> $GITHUB_ENV + - name: Print ENV_VAR + run: | + echo "The value of REF is $REF" + - name: Set ENV_VAR + id: setter + run: | + echo "ref=$REF" >> "$GITHUB_OUTPUT" + Linux: + needs: [GetUser, GetGitRef] + if: ${{ (github.event.issue.pull_request && contains(github.event.comment.body, '/AzurePipelines run') && needs.GetUser.outputs.require-result == 'true' ) || github.event_name == 'push' }} + runs-on: ubuntu-20.04 + timeout-minutes: 120 + steps: + - run: echo ${{ needs.GetUser.outputs.require-result }} + - name: Checkout code + uses: actions/checkout@v4 + with: + ref: ${{needs.GetGitRef.outputs.ref}} + - name: Restore cached artifacts + id: cache-usd-build-dependency + uses: actions/cache/restore@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION }}-${{ hashFiles('build_scripts/**/*') }} + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + check-latest: false + - name: Install dependencies + run: | + sudo apt-get -qq update + sudo apt-get install -y python3-setuptools libglew-dev libxrandr-dev libxcursor-dev libxinerama-dev libxi-dev + pip install --upgrade pip + pip install PySide2 PyOpenGL + - name: Build USD + run: | + python3 build_scripts/build_usd.py --no-materialx --build USDgen/build --src USDgen/src USDinst -v + - name: Save build artifacts to cache + if: steps.cache-usd-build-dependency.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION }}-${{ hashFiles('build_scripts/**/*') }} + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: usd-linux + path: USDinst + + macOS: + needs: [GetUser, GetGitRef] + if: ${{ (github.event.issue.pull_request && contains(github.event.comment.body, '/AzurePipelines run') && needs.GetUser.outputs.require-result == 'true' ) || github.event_name == 'push' }} + runs-on: macos-13 + timeout-minutes: 120 + steps: + - run: echo ${{ needs.GetUser.outputs.require-result }} + - name: Checkout code + uses: actions/checkout@v4 + with: + ref: ${{needs.GetGitRef.outputs.ref}} + - name: Restore cached artifacts + id: cache-usd-build-dependency + uses: actions/cache/restore@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION_MAC }}-${{ hashFiles('build_scripts/**/*') }} + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION_MAC }} + check-latest: false + - name: Install dependencies + run: | + export PATH=/Applications/CMake.app/Contents/bin:$PATH + sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer + # Set SYSTEM_VERSION_COMPAT while installing Python packages to + # accommodate the macOS version numbering change from 10.x to 11 + export SYSTEM_VERSION_COMPAT=1 + pip install PySide6 PyOpenGL setuptools + export -n SYSTEM_VERSION_COMPAT + - name: Build USD + run: | + export PATH=/Applications/CMake.app/Contents/bin:$PATH + python3 build_scripts/build_usd.py --no-materialx --generator Xcode --build USDgen/build --src USDgen/src USDinst -v + - name: Save build artifacts to cache + if: steps.cache-usd-build-dependency.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION_MAC }}-${{ hashFiles('build_scripts/**/*') }} + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: usd-macOS + path: USDinst + + Windows: + needs: [GetUser, GetGitRef] + if: ${{ (github.event.issue.pull_request && contains(github.event.comment.body, '/AzurePipelines run') && needs.GetUser.outputs.require-result == 'true' ) || github.event_name == 'push' }} + runs-on: windows-2019 + timeout-minutes: 120 + steps: + - run: echo ${{ needs.GetUser.outputs.require-result }} + - name: Checkout code + uses: actions/checkout@v4 + with: + ref: ${{needs.GetGitRef.outputs.ref}} + - name: Restore cached artifacts + id: cache-usd-build-dependency + uses: actions/cache/restore@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION }}-${{ hashFiles('build_scripts/**/*') }} + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + check-latest: false + - name: Install dependencies + run: | + python -m pip install --upgrade pip + python -m pip install PyOpenGL PySide2 + - name: Build USD + run: | + REM Unset BOOST_ROOT on Windows. The VS2017-Win2016 image + REM sets this env var to a pre-installed boost which causes + REM the USD build to favor this over the boost built by + REM build_usd.py. This causes the build to fail, because + REM the pre-installed boost does not include boost_python27 + call set BOOST_ROOT= + python build_scripts/build_usd.py --no-materialx --generator "Visual Studio 16 2019" --build USDgen/build --src USDgen/src USDinst --build-args USD,"-DPXR_ENABLE_PRECOMPILED_HEADERS=OFF" -v + shell: cmd + - name: Save build artifacts to cache + if: steps.cache-usd-build-dependency.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: | + USDinst + key: ${{ runner.os }}-BuildUSD-py${{ env.PYTHON_VERSION }}-${{ hashFiles('build_scripts/**/*') }} + - name: Upload artifacts + # use v3 because actions/upload-artifact@v4 fails + # see https://github.com/actions/upload-artifact/issues/485 + uses: actions/upload-artifact@v3 + with: + name: usd-win64 + path: USDinst \ No newline at end of file diff --git a/.github/workflows/pypi.yml b/.github/workflows/pypi.yml new file mode 100644 index 0000000000..1c662a8fcf --- /dev/null +++ b/.github/workflows/pypi.yml @@ -0,0 +1,322 @@ +name: PyPiPackaging + +# Trigger this build whenever the dev or release branches are updated +# or on-demand. +# +# Ideally we'd run this pipeline for all pull requests, but doing so consumes +# our limited number of slots and almost always just duplicates the +# build done in the main pipeline. +on: + push: + branches: + - dev + - release + workflow_dispatch: + inputs: + post_release_tag: + description: 'post release tag' + default: '' + +env: + POST_RELEASE_TAG: ${{ github.event.inputs.post_release_tag == '' && ' ' || format('--post-release-tag {0}', github.event.inputs.post_release_tag) }} + +jobs: + Linux: + strategy: + matrix: + PYTHON: + - TAG: cp38 + INTERPRETER: /opt/python/cp38-cp38/bin/python + VERSION_SPEC: '3.8' + - TAG: cp39 + INTERPRETER: /opt/python/cp39-cp39/bin/python + VERSION_SPEC: '3.9' + - TAG: cp310 + INTERPRETER: /opt/python/cp310-cp310/bin/python + VERSION_SPEC: '3.10' + - TAG: cp311 + INTERPRETER: /opt/python/cp311-cp311/bin/python + VERSION_SPEC: '3.11' + runs-on: ubuntu-20.04 + timeout-minutes: 60 + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.PYTHON.VERSION_SPEC }} + check-latest: false + - name: Setting up docker + run: | + docker build -t manylinuxwithcmake build_scripts/pypi/docker + docker run --name usdmanylinux --rm -id -v ./:/opt/USD -v /home/vsts/dist:/opt/USD-dist manylinuxwithcmake + - name: Building USD + run: | + # Terrible, terrible hack. The manylinux Docker image used to build the + # Python wheel does not include the corresponding Python shared library + # to link against. https://peps.python.org/pep-0513/#libpythonx-y-so-1 + # describes why this is so. However, the FindPython CMake module used + # by USD's build system requires that the library exists and will error + # out otherwise, even though we explicitly avoid linking against Python + # via the PXR_PY_UNDEFINED_DYNAMIC_LOOKUP flag. + # + # To work around this, we create a dummy file for the library using + # the same logic as build_usd.py to determine where the library should + # exist (see GetPythonInfo). FindPython will see that the library exists + # and allow the build to continue. The file is 100% bogus, but the + # PXR_PY_UNDEFINED_DYNAMIC_LOOKUP flag will ensure that we never try to + # link against this library anyway, so it doesn't matter. + docker exec usdmanylinux ${{ matrix.PYTHON.INTERPRETER }} -c "import pathlib,sysconfig; pathlib.Path(sysconfig.get_config_var('LIBDIR'), sysconfig.get_config_var('LDLIBRARY')).touch()" + docker exec usdmanylinux ${{ matrix.PYTHON.INTERPRETER }} build_scripts/build_usd.py --build-args USD,"-DPXR_PY_UNDEFINED_DYNAMIC_LOOKUP=ON -DPXR_BUILD_USD_TOOLS=OFF -DPXR_INSTALL_LOCATION=../pxr/pluginfo" --no-materialx --no-imaging --no-examples --no-tutorials --build /opt/USD/gen/build --src /opt/USD/gen/src /opt/USD/inst -v + - name: Creating packaging directory + run: | + docker exec usdmanylinux mkdir ./packaging + docker exec usdmanylinux cp -R /opt/USD/inst ./packaging + docker exec usdmanylinux sh -c 'cp build_scripts/pypi/package_files/* ./packaging' + docker exec usdmanylinux sh -c 'cp LICENSE.txt ./packaging' + - name: Running setup.py + run: | + docker exec -w /opt/USD/packaging usdmanylinux ${{ matrix.PYTHON.INTERPRETER }} setup.py ${{ env.POST_RELEASE_TAG }} bdist_wheel --python-tag ${{ matrix.PYTHON.TAG }} + - name: Running auditwheel repair (moves .so files into package) + run: | + docker exec usdmanylinux /bin/bash -c 'PYTHONPATH=/opt/USD/packaging/pypi/lib/python LD_LIBRARY_PATH=/opt/USD/packaging/pypi/lib:$LD_LIBRARY_PATH auditwheel repair packaging/dist/*.whl' + - name: Updating pluginfo paths + run: | + WHEEL_PACKAGE_NAME=`docker exec usdmanylinux ls wheelhouse` + docker exec usdmanylinux ${{ matrix.PYTHON.INTERPRETER }} build_scripts/pypi/updatePluginfos.py "wheelhouse/$WHEEL_PACKAGE_NAME" "/opt/USD-dist/$WHEEL_PACKAGE_NAME" + - name: Stopping docker container + run: | + docker stop usdmanylinux + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: dist-linux-${{ matrix.PYTHON.TAG }} + path: /home/vsts/dist + macOS: + strategy: + matrix: + PYTHON: + - VERSION_SPEC: '3.8' + INTERPRETER: python3.8 + TAG: cp38 + - VERSION_SPEC: '3.9' + INTERPRETER: python3.9 + TAG: cp39 + - VERSION_SPEC: '3.10' + INTERPRETER: python3.10 + TAG: cp310 + - VERSION_SPEC: '3.11' + INTERPRETER: python3.11 + TAG: cp311 + runs-on: macos-13 + timeout-minutes: 120 + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.PYTHON.VERSION_SPEC }} + check-latest: false + - name: Install dependencies + run: | + ${{ matrix.PYTHON.INTERPRETER }} -m pip install --upgrade pip + ${{ matrix.PYTHON.INTERPRETER }} -m pip install delocate~=0.10.2 wheel + - name: Build USD + run: | + sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer + ${{ matrix.PYTHON.INTERPRETER }} build_scripts/build_usd.py --build-args USD,"-DPXR_PY_UNDEFINED_DYNAMIC_LOOKUP=ON -DPXR_BUILD_USD_TOOLS=OFF -DPXR_INSTALL_LOCATION=../pluginfo" --no-materialx --no-imaging --no-examples --no-tutorials --generator Xcode --build-target universal --build $GITHUB_WORKSPACE/USDgen/build --src $GITHUB_WORKSPACE/USDgen/src $GITHUB_WORKSPACE/USDinst -v + - name: Packaging USD + run: | + pwd + ls -la + mkdir ./packaging + mkdir ./packaging/inst + cp -R $GITHUB_WORKSPACE/USDinst/* ./packaging/inst + cp build_scripts/pypi/package_files/* ./packaging + cp LICENSE.txt ./packaging + ls -la ./packaging + ls -la ./packaging/inst + - name: Running setup.py + run: | + cd ./packaging + ${{ matrix.PYTHON.INTERPRETER }} setup.py ${{ env.POST_RELEASE_TAG }} bdist_wheel --python-tag ${{ matrix.PYTHON.TAG }} --plat-name macosx_10_9_universal2 + - name: Running delocate + run: | + # set DYLD_FALLBACK_LIBRARY_PATH for delocate-wheel to resolve libs + # https://github.com/pypa/cibuildwheel/issues/816 + export DYLD_FALLBACK_LIBRARY_PATH=`readlink -f USDinst/lib` + echo $DYLD_FALLBACK_LIBRARY_PATH + ls -la $DYLD_FALLBACK_LIBRARY_PATH + delocate-wheel -vv -w dist-delocated packaging/dist/* + ls -la packaging/dist + ls -la dist-delocated + - name: Updating pluginfo paths + run: | + WHEEL_PACKAGE_NAME=`ls ./packaging/dist` + mkdir -p ./dist + ls -la ./packaging/dist + ls -la ./dist + ${{ matrix.PYTHON.INTERPRETER }} build_scripts/pypi/updatePluginfos.py "./dist-delocated/$WHEEL_PACKAGE_NAME" "./dist/$WHEEL_PACKAGE_NAME" + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: dist-mac-${{ matrix.PYTHON.TAG }} + path: ./dist + Windows: + strategy: + matrix: + PYTHON: + - VERSION_SPEC: '3.8' + TAG: cp38 + - VERSION_SPEC: '3.9' + TAG: cp39 + - VERSION_SPEC: '3.10' + TAG: cp310 + - VERSION_SPEC: '3.11' + TAG: cp311 + runs-on: windows-2019 + timeout-minutes: 60 + steps: + - name: Checkout code + uses: actions/checkout@v4 + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.PYTHON.VERSION_SPEC }} + check-latest: false + - name: Install dependencies + run: | + python -m pip install wheel + shell: cmd + - name: Build USD + run: | + call C:\"Program Files (x86)"\"Microsoft Visual Studio"\2019\Enterprise\VC\Auxiliary\Build\vcvars64.bat + set BOOST_ROOT= + python --version + python build_scripts/build_usd.py --build-args USD,"-DPXR_ENABLE_PRECOMPILED_HEADERS=OFF -DPXR_PY_UNDEFINED_DYNAMIC_LOOKUP=ON -DPXR_BUILD_USD_TOOLS=OFF -DPXR_INSTALL_LOCATION=../pxr/pluginfo" --no-materialx --no-imaging --no-examples --no-tutorials --build USDgen/build --src USDgen/src USDinst -v + shell: cmd + - name: Packaging USD + run: | + dir + mkdir D:\packaging + xcopy /E /I USDinst D:\packaging\inst + copy build_scripts\pypi\package_files\* D:\packaging + copy LICENSE.txt D:\packaging + dir D:\packaging + dir D:\packaging\inst + shell: cmd + - name: Running setup.py + run: | + D: + cd D:\packaging + python setup.py ${{ env.POST_RELEASE_TAG }} bdist_wheel --python-tag ${{ matrix.PYTHON.TAG }} --plat-name win_amd64 + dir + shell: cmd + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: dist-windows-${{ matrix.PYTHON.TAG }} + path: D:\packaging\dist + + CollectPackages: + if: ${{ always() }} + needs: [Linux, macOS, Windows] + timeout-minutes: 5 + runs-on: ubuntu-24.04 + steps: + - uses: actions/download-artifact@v4 + with: + path: dist-final + pattern: dist-*-* + merge-multiple: true + - name: Display structure of downloaded files + run: ls -R dist-final + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: dist + path: dist-final + + Test: + needs: [CollectPackages] + timeout-minutes: 5 + strategy: + matrix: + BUILD_CONFIG: + - NAME: Linux_Python38 + PYTHON_VERSION_SPEC: '3.8' + IMAGE: ubuntu-20.04 + PYTHON_INTERPRETER: python3 + - NAME: Linux_Python39 + PYTHON_VERSION_SPEC: '3.9' + IMAGE: ubuntu-20.04 + PYTHON_INTERPRETER: python3 + - NAME: Linux_Python310 + PYTHON_VERSION_SPEC: '3.10' + IMAGE: ubuntu-20.04 + PYTHON_INTERPRETER: python3 + - NAME: Linux_Python311 + PYTHON_VERSION_SPEC: '3.11' + IMAGE: ubuntu-20.04 + PYTHON_INTERPRETER: python3 + - NAME: Mac_Python38 + PYTHON_VERSION_SPEC: '3.8' + IMAGE: macos-13 + PYTHON_INTERPRETER: python3 + - NAME: Mac_Python39 + PYTHON_VERSION_SPEC: '3.9' + IMAGE: macos-13 + PYTHON_INTERPRETER: python3 + - NAME: Mac_Python310 + PYTHON_VERSION_SPEC: '3.10' + IMAGE: macos-13 + PYTHON_INTERPRETER: python3 + - NAME: Mac_Python311 + PYTHON_VERSION_SPEC: '3.11' + IMAGE: macos-13 + PYTHON_INTERPRETER: python3 + - NAME: Windows_Python38 + PYTHON_VERSION_SPEC: '3.8' + IMAGE: windows-2019 + PYTHON_INTERPRETER: python3 + - NAME: Windows_Python39 + PYTHON_VERSION_SPEC: '3.9' + IMAGE: windows-2019 + PYTHON_INTERPRETER: python3 + - NAME: Windows_Python310 + PYTHON_VERSION_SPEC: '3.10' + IMAGE: windows-2019 + PYTHON_INTERPRETER: python3 + - NAME: Windows_Python311 + PYTHON_VERSION_SPEC: '3.11' + IMAGE: windows-2019 + PYTHON_INTERPRETER: python3 + runs-on: ${{ matrix.BUILD_CONFIG.IMAGE }} + steps: + - name: Install Python + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.BUILD_CONFIG.PYTHON_VERSION_SPEC }} + check-latest: false + - name: Checkout code + uses: actions/checkout@v4 + - uses: actions/download-artifact@v4 + with: + name: dist + merge-multiple: true + - name: Packaging USD + run: | + which python3 + ${{ matrix.BUILD_CONFIG.PYTHON_INTERPRETER }} --version + ${{ matrix.BUILD_CONFIG.PYTHON_INTERPRETER }} -m pip install pytest + ${{ matrix.BUILD_CONFIG.PYTHON_INTERPRETER }} -m pip install --no-index --find-links=file://${{ github.workspace }} usd-core + py.test --junitxml TEST-usdinstall-${{ matrix.BUILD_CONFIG.NAME }}.xml build_scripts/pypi/test.py + - name: Upload pytest test results + uses: actions/upload-artifact@v4 + with: + name: TEST-usdinstall-${{ matrix.BUILD_CONFIG.NAME }} + path: TEST-usdinstall-${{ matrix.BUILD_CONFIG.NAME }}.xml + # Use always() to always run this step to publish test results when there are test failures + if: ${{ always() }} \ No newline at end of file diff --git a/BUILDING.md b/BUILDING.md index 58d1a9d412..c2c16b0a04 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -36,7 +36,6 @@ Some examples: cmake \ -DTBB_ROOT_DIR=/path/to/tbb \ -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv \ --DBOOST_ROOT=/path/to/boost \ /path/to/USD/source cmake --build . --target install -- -j @@ -51,7 +50,6 @@ cmake \ -G "Xcode" \ -DTBB_ROOT_DIR=/path/to/tbb \ -DOPENSUBDIV_ROOT_DIR=/path/to/opensubdiv \ --DBOOST_ROOT=/path/to/boost \ /path/to/USD/source cmake --build . --target install -- -j @@ -67,7 +65,6 @@ build USD. -G "Visual Studio 15 2017 Win64" ^ -DTBB_ROOT_DIR=C:\path\to\tbb ^ -DOPENSUBDIV_ROOT_DIR=C:\path\to\opensubdiv ^ --DBOOST_ROOT=C:\path\to\boost ^ \path\to\USD\source cmake --build . --target install -- /m:%NUMBER_OF_PROCESSORS% @@ -695,16 +692,34 @@ Note that this flag has no effect on Windows, see [here for more info](https://docs.python.org/3/extending/windows.html) -## Build Issues FAQ +## Spline Options + +Splines (keyframe animation) are implemented by the library `pxr/base/ts`. + +#### Default Anti-Regression Authoring Mode + +A `Ts` spline provides a function from time to attribute value. Bezier math +permits long tangents to create shapes that go backwards in time, resulting in +non-functions. This is typically prevented at authoring time, and there are +several strategies available. See +[pxr/base/ts/doxygen/regression.md](./pxr/base/ts/doxygen/regression.md) for +details of the different choices. + +The hard-coded default is `TsAntiRegressionKeepRatio`. To set a different +default: -1. Boost_NO_BOOST_CMAKE: -We currently set Boost_NO_BOOST_CMAKE=ON explicitly in USD builds for all -platforms to avoid issues with Boost config files (introduced in Boost version -1.70) and python, program options component requirements. If the user wants -to use Boost specified config files for their USD build, specify --DBoost_NO_BOOST_CMAKE=OFF when running cmake. +* With `build_usd.py`: +`--build-args USD,"-DPXR_TS_DEFAULT_ANTI_REGRESSION_AUTHORING_MODE=TsAntiRegression..."` + +* With cmake: +`-DPXR_TS_DEFAULT_ANTI_REGRESSION_AUTHORING_MODE=TsAntiRegression...` + +Client code can also override the default as needed. + + +## Build Issues FAQ -2. Windows and Python 3.8+ (non-Anaconda) +1. Windows and Python 3.8+ (non-Anaconda) Python 3.8 and later on Windows will no longer search PATH for DLL dependencies. Instead, clients can call `os.add_dll_directory(p)` to set paths to search. By default on that platform USD will iterate over PATH and add all paths using diff --git a/CHANGELOG.md b/CHANGELOG.md index 68e0ca21cf..084e873cbf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,532 @@ # Change Log +## [24.11] - 2024-10-25 + +### Build + +- Removed boost dependency from OpenUSD. Note that boost must still be supplied + when OpenVDB support is enabled due to its use of boost in headers. + +- OpenUSD now uses its own internal pxr_boost::python library for generating + Python bindings instead of boost::python. + - Types from OpenUSD like Usd.Stage will no longer interoperate with other C++ + code that have been wrapped with boost::python. Client code with Python + bindings that interoperate with OpenUSD types must be updated to use the new + pxr_boost::python library. In particular, schema libraries should be + regenerated to pick up the new library. + - Users can revert to the old behavior of using boost::python by specifying + `PXR_USE_BOOST_PYTHON=ON` when running CMake. This option is for testing and + transition purposes; it is deprecated and will be removed in a future release. + +- Added "--boost-python" option to build_usd.py for building OpenUSD's Python + bindings with boost::python. This option is for testing and transition + purposes; it is deprecated and will be removed in a future release. + Note that the build script will continue to build boost if it's needed by + optional dependencies. These include OpenImageIO and OpenVDB. + +- Enabled support for imaging and usdImaging on Apple embedded platforms. + (PR: [#3215](https://github.com/PixarAnimationStudios/OpenUSD/pull/3215)) + +- OpenUSD's internal namespace now includes the patch version to help + distinguish releases within the same year. + (PR: [#3167](https://github.com/PixarAnimationStudios/OpenUSD/pull/3167)) + +- Removed support for usd-core PyPI package for Python 3.6 and deprecated + support for Python 3.7. + +### USD + +- Updated Tf file utilities to ignore reparse points on network file systems on + Windows. Reparse points on these systems are unlikely to be accessible from + the remote machines. + (PR: [#2934](https://github.com/PixarAnimationStudios/OpenUSD/pull/2934)) + +- Updated pxrTslRobinMap to latest release, 1.3.0, using erase_fast instead + of erase when the returned iterator is not needed. + (PR: [#3253](https://github.com/PixarAnimationStudios/OpenUSD/pull/3253), + [#3255](https://github.com/PixarAnimationStudios/OpenUSD/pull/3255)) + +- Added support for named color spaces from the Color Interchange Forum to + GfColorSpace. + +- Added Gf.Color and Gf.ColorSpace Python bindings. + +- Removed overloads of GfMatrix4d::Transform, GfMatrix4d::TransformAffine, + GfMatrix4d::TransformDir, and GfRotation::TransformDir that take and return + GfVec3f, as they can potentially result in loss of precision. Matrix-vector + multiplication operators for double precision matrix types and single + precision vector types have also been removed. These were deprecated in 24.05. + +- Exposed Python bindings for ArAsset, enabling operations such as + ArResolver.OpenAsset(resolvedPath) to allow reading ArAsset buffers from + Python. + (PR: [#3318](https://github.com/PixarAnimationStudios/OpenUSD/pull/3318)) + +- Various updates and fixes made for relocates. + - Fixed a bug where ancestral relocates weren't properly elided, leading to + verification failures and crashes. + - Fixed a bug with Pcp dependencies where some prim indexes from nested + relocates aren't invalidated when one of the ancestral relocates is + updated. + +- Improved how Pcp generates changelists for muting/unmuting layers and + adding/removing sublayers, improving performance especially in large stages. + Change notifications to external clients remain unaffected, and legacy + behavior is retained for layers that may contain relocates. This optimization + is still in development and is disabled by default. It can be enabled + by setting the environment variable + PCP_ENABLE_MINIMAL_CHANGES_FOR_LAYER_OPERATIONS = 1. + +- Deprecated time sample related methods on SdfLayer, to be removed in the next + release. SdfAttributeSpec now owns these time sample related methods. + +- Converted NdrSdfTypeIndicator from a std::pair to a full class. + +- Removed residual member function declaration for SdfPath. + (PR: [#3254](https://github.com/PixarAnimationStudios/OpenUSD/pull/3254)) + +- Enhanced SdfCopySpec() to handle overlapping source/destination by copying the + source to a temporary anonymous layer first, then copying that temporary to + the destination. + (Issue: [#3095](https://github.com/PixarAnimationStudios/OpenUSD/issues/3095)) + +- Initial work done on animation curves in USD. + +- Fixed performance issue writing .usdc files with high time sample counts. + (Issue: [#3249](https://github.com/PixarAnimationStudios/OpenUSD/issues/3249)) + +- Reimplemented .usda text file parser using PEGTL. This removes a dependency on + lex/yacc and also provides some performance improvements. + (PR: [#3005](https://github.com/PixarAnimationStudios/OpenUSD/pull/3005), + [#3293](https://github.com/PixarAnimationStudios/OpenUSD/pull/3293), + [#3294](https://github.com/PixarAnimationStudios/OpenUSD/pull/3294)) + +- Fixed bugs in the namespace-editing code that caused unnecessary and incorrect + edits to children defined by upstream composition dependencies. + +- Various updates for new Validation framework: + - Updated UsdValidationError to include a name property, used along with the + validator name to create an error identifier. This identifier can be used to + categorize and filter errors, especially when a validator can generate + multiple errors of different types. The error identifier is of the form + "validatorName"."ErrorName" or "plugName":"validatorName"."ErrorName". + - Added UsdValidationContext concept, which can be constructed by selecting + validators using keywords, plugins, validator metadata, schema types, or + pre-selected sets of validators. Validators for ancestor schema types are + also considered when selecting validators for a validation context. Clients + can use Validate() API to validate a layer, stage, or a set of prims with + parallel execution and error collection. UsdValidationContext initialization + may load plugins in order to load the validators. UsdValidationContext is a + stateless context, which means that clients handle validation input and + result tracking. + - Updated UsdValidationRegistry to be immortal, which means that any + registered validators and validator suites are also immortal. + - Added schema validators using the new Validation framework: + - Added StageMetadata Validator for usdGeom domain. + (PR: [#3134](https://github.com/PixarAnimationStudios/OpenUSD/pull/3134)) + - Added StageMetadata Validator for core USD. + (PR: [#3125](https://github.com/PixarAnimationStudios/OpenUSD/pull/3125)) + - Added SkelBindingApiAppliedValidator and SkelBindingApiValidator for + usdSkel domain. + (PR: [#3166](https://github.com/PixarAnimationStudios/OpenUSD/pull/3166)) + - Added MaterialBindingApiAppliedValidator, EncapsulationRulesValidator for + usdShade domain. + (PR: [#3154](https://github.com/PixarAnimationStudios/OpenUSD/pull/3154)) + (PR: [#3227](https://github.com/PixarAnimationStudios/OpenUSD/pull/3227)) + - Added a Usdz Package Encapsulation Validator for usdUtils domain. + (PR: [#3206](https://github.com/PixarAnimationStudios/OpenUSD/pull/3206)) + - Added validators for UsdGeomSubsets + (PR: [#3123](https://github.com/PixarAnimationStudios/OpenUSD/pull/3123)) + - Updated UsdValidationErrorType to be registered as TfEnum. + (PR: [#3223](https://github.com/PixarAnimationStudios/OpenUSD/pull/3223)) + - Added Python bindings for UsdValidatorMetadata, UsdValidator, + UsdValidatorSuite, UsdValidationError, UsdValidationErrorSite, + UsdValidationErrorType and UsdValidationRegistry. + (PR: [#3232](https://github.com/PixarAnimationStudios/OpenUSD/pull/3232)) + (PR: [#3236](https://github.com/PixarAnimationStudios/OpenUSD/pull/3236)) + (PR: [#3242](https://github.com/PixarAnimationStudios/OpenUSD/pull/3242)) + +- Added support for `BlockCollection()` and `ResetCollection()` to + `UsdCollectionAPI` for expression-mode collections. Also added + `IsInExpressionMode()` and `IsInRelationshipsMode()` convenience APIs. + +- usdGenSchema now adds a schemaIdentifier field to schema plugInfo metadata. + When present, this field will be used as the schema's identifier in the schema + registry. If not, the alias under UsdSchemaBase will be used. + +- Updated usdGenSchema to generate helper files used in the build so that when + adding a new schema class to a schema library, users will just need to re-run + usdGenSchema instead of having to name the generated files manually in + CMakeLists.txt + +- Updated sdrOslParser to provide metadata (usdSchemaDef_* and + sdrGlobalConfig_*) used for schema generation via usdgenschemafromsdr. This + allows clients to generate USD schema from OSL shader definitions which are + registered via sdr. + +- Added a new usdSemantics module which includes a SemanticsLabelsAPI schema + for labeling prims with tokens. The implementation diverges slightly with + [the proposal](https://github.com/PixarAnimationStudios/OpenUSD-proposals/tree/main/proposals/semantic_schema) + with the taxonomy being after "labels" instead of before in the property name + (e.g., `semantics:labels:` instead of `semantics::labels`). + In addition to the schema, UsdSemanticsLabelsQuery provides a reference for + how ancestor labeling is expected to work and inherit. + (PR: [#3103](https://github.com/PixarAnimationStudios/OpenUSD/pull/3103)) + +- Added support for elementType "segment" to UsdGeomSubset, where "segment" + refers to a segment of a UsdGeomBasisCurves object. + +- Updated UsdLuxCylinderLight bounds computation to use X axis as major axis. + (Issue: [#3233](https://github.com/PixarAnimationStudios/OpenUSD/issues/3233), + PR: [#3246](https://github.com/PixarAnimationStudios/OpenUSD/pull/3246)) + +- Removed RenderDenoisePass from usdRender schemas. + +- Fixed crash in UsdSkelAnimQuery::ComputeJointLocalTransformComponents when + translate, rotate, or scale attributes are not present. + +- Updated UsdUtils.UpdateSchemaWithSdrNode to populate the shaderId attribute + for all shaderNodes across sourceTypes for the same identifier. + +- Added Python performance module under extras directory in support of local + performance testing and for tracking performance over OpenUSD releases. See + usdmeasureperformance.py and + [documentation](https://openusd.org/release/ref_performance_metrics.html) + for more details. + +### Hydra + +- Storm and HdPrman lighting/shading have been updated to be more consistent + when combining different material types and light types. Physically based + lighting and physically based materials have not changed; nor have camera + lights and fallback materials. However, camera lights and physically based + materials will appear brighter, and physically based lights and fallback + materials will appear darker, in order to produce correct lighting response. + +- Made change to allow the generative procedural resolving scene index to be + more easily toggled (via a new switchingSceneIndex). + +- Added a new filtering scene index: HdsiPrimTypeAndPathPruningSceneIndex. One + use case is to switch between camera and scene lights by changing the path + predicate. + +- Fixed a problem with motion blur when using HdRenderIndex::InsertSceneIndex, + where the shutter interval was not communicated from the render delegate to + emulation. Hence, emulation called GetContributingSampleTimesForInterval on an + HdSampledDataSource returned by the inserted scene index with a bad + startTime/endTime. + +- Overhauled HdExtComputationSchema and related schemas. In particular, + introduced HdExtComputationCpuCallback and changed the CPU callback data + source to return the new type. + +- Added typed getters and setters to HdExtComputationContext. + +- Introduced HdsiExtComputationDependencySceneIndex which clients can use + together with the HdsiExtComputationPrimvarPruningSceneIndex to evaluate and + invalidate ext computation primvars. + +- Added the WithOrientation method to PxOsdMeshTopology which behaves similar to + the WithScheme and WithHoleIndices methods. It returns a copy of the mesh + topology object except with the orientation set to the given orientation. + +- Added GeomUtilDiskMeshGenerator for generating disk-shaped meshes. + +- Fixed the GeomUtilCapsuleMeshGenerator so that the height, bottom radius, and + top radius of the cylindrical portion of the capsule is retained and the + spheres are adjusted to maintain continuity with the cylinder sides, as + defined in the documentation for UsdGeomCapsule. + +- Altered how the numCapAxial parameter works for GeomUtilCapsuleMeshGenerator + when the radii are different. When the radii differ, the numCapAxial parameter + is doubled and the number of cross-sections are divided between the top and + bottom hemispheres relative to the angle that each portion uses. This makes + the density of the mesh more even between the bottom and top when the radii + difference is large. + +- Added normals generation to the various mesh generation utility classes. + Similar to the point generation, the classes provide a method that returns the + number of normals and a method for generating the normals into a provided + container iterator. In addition, the interpolation mode of the normals can be + requested. + +- Made improvements to the light linking scene index. Added support for + non-nested native and point instancers and significantly improved invalidation + performance. + +- Prefixed predicate expressions with "hd" for clarity and deprecated existing + predicates. + +- Added render index API to allow batching of notices sent by the merging scene + index. + +- Fixed a subtle bug in the generative procedural resolving scene index to not + cook procedurals in response to scene queries. + +- Added RecipeMaterialOverride schema. + +- Added HdsiMaterialOverrideResolvingSceneIndex to resolve material overrides. + +- Fixed bug with loading monochrome .exr images. + (PR: [#3343](https://github.com/PixarAnimationStudios/OpenUSD/pull/3343)) + +### UsdImaging + +- Added support for UsdGeomPlane in Scene Index mode. + +- Added UsdImagingModelSchema for any prim that has UsdModelAPI data in Scene + Index mode, including models demoted to act as subcomponents within other + models. + +- Fixed a bug causing spurious warnings about "implementationSource" for lights. + +- Fixed an invalidation bug so that when a material is edited, prims with + that material bound will have their primvars correctly invalidated. + (Issue: [#2382](https://github.com/PixarAnimationStudios/OpenUSD/issues/2382)) + +- Fixed DeprecationWarning in usdviewq/appController.py caused by a regex + containing an invalid escape sequence. + (PR: [#2955](https://github.com/PixarAnimationStudios/OpenUSD/pull/2955)) + +- Added AOV light adapter for transporting USD AOV lights to Hydra. + +### Storm + +- Fixed Vulkan buffer leaks in HdSt_PipelineDrawBatch. + (PR: [#3313](https://github.com/PixarAnimationStudios/OpenUSD/pull/3313)) + +- Improved Lavapipe support, enabling the Vulkan driver as a software rasterizer + on macOS. + (PR: [#3121](https://github.com/PixarAnimationStudios/OpenUSD/pull/3121)) + +- Added support for configurable anisotropic filtering in Storm and Hgi. We now + disable anisotropy for certain texture/sampler uses such as dome light + textures and AOVs. + (PR: [#3216](https://github.com/PixarAnimationStudios/OpenUSD/pull/3216)) + +- Fixed deadlock when Vulkan command buffers are consumed faster than they are + executed. + (PR: [#3170](https://github.com/PixarAnimationStudios/OpenUSD/pull/3170)) + +- Updated simpleLights to increase the brightness when used with physically + based materials (for example, UsdPreviewSurface or MaterialX). + +- Updated fallback shading to decrease the brightness when used with physically + based lights (like UsdLux), for consistency with physically based materials. + +- Fixed displacement shading when using vertex or varying displacement + parameterization with Metal. + (Issue: [#3248](https://github.com/PixarAnimationStudios/OpenUSD/issues/3248)) + +- Updated drawing of selected mesh edges to eliminate the need to apply a depth + offset in the geometry shader. + +- Exposed an option in HdMeshReprDesc to enable generation of surface edge ids + for surface and hull geom styles which do not otherwise draw edges. This + option is disabled by default which avoids enabling geometry shader stages for + more use cases. + (PR: [#3071](https://github.com/PixarAnimationStudios/OpenUSD/pull/3071)) + +- Shaders for basis curves rprims that are rendered as ribbons are now provided + with a texture coordinate that varies over the width of the curve, via the + patchCoord argument to the shader terminal. + +- Fixed potential texture memory leak by explicitly calling garbage collection + of the necessary subsystem from resource registry's garbage collection. + +- Storm draw target clients no longer need to call + HdChangeTracker::MarkStateDirty when a draw target gets disabled and enabled. + Storm automatically does the necessary invalidation by tracking the version + number of the active draw target set in HdStRenderParam. + +- Fixed the deep selection resolve mode for the "pickPointsAndInstances" pick + target. + +- Fixed missing include in glslProgram. + (PR: [#3283](https://github.com/PixarAnimationStudios/OpenUSD/pull/3283)) + +### RenderMan Hydra Plugin + +- **Important**: Removed hdPrman for RenderMan 25. This was deprecated in USD + 24.08 + +- usdRiPxr schemas for rman26.3 are not bundled with OpenUSD and instead will be + installed during a OpenUSD build from the specified RenderMan location. + +- Added support for the official RenderMan PxrPrimvarAPI schema in HdPrman. + +- Fixed a bug with missing invalidation of time-varying primvars in Scene Index + mode. This would manifest as a stale primvar value after changing the input + scene time during a render. + +- Added HD_PRMAN_INTERACTIVE_RENDER_WITH_RENDER_SETTINGS which adds the render + settings' products to the task's AOV bindings in the render view. + +- Updated simpleLights (that is, lights set via + HdxTaskController::SetLightingState) to increase the brightness when used with + or without materials. + +- Added many preprocessor directives as needed to support compiling against USD + versions back to 22.05. + +- hdPrman now respects an env var called RMAN_XPU_GPUGCONFIG that can be set + with a comma delimited list of the indexes of the selected GPUs. + +- Updated the use of ri:checkpoint:exitat to work independently of + ri:checkpoint:interval being set. + +- Updated to use "Shutter settings" on the camera and ignore ri:shutter render + setting. + +- Updated PxrBakeTexture to correctly write to non tex files which exist on disk. + +- Fixed a bug where switching between VDB volumes that kept the same path name + would not update in the interactive render. + +- Fixed a bug where interactively editing the Material Sync Mode of a + PxrMeshLight would not trigger the expected update of the mesh light + geometry's visibility. Note that mesh light support is still in active + development and will be enabled in a future release. + +- Fixed a crash that could happen when switching between RenderMan Hydra + delegates in Katana. + +- Added support for environment variable HD_PRMAN_TEX_EXTS that accepts a + colon-separated list of extensions known to be tex compatible, e.g. "tex:txr". + +- Fixed a bug where UDIM textures used by the USDUvTexture node would be flipped + incorrectly. + +- Updated Volume prims with primvar named "vel" or "velocity" to infer the type + to be vector rather than float. + +- Support for the PRMAN_OSL_BEFORE_RIXPLUGINS environment variable to allow + resolving OSL shaders before C++. + +- Support finding MaterialX search paths at runtime based on a DCC install + location. + +- Support naming the hdPrman delegate something other than "Prman". + +- Support Ri:PixelFilterName and Ri:PixelFilterWidth options. + +- Various updates to SideFX Solaris support. + - Enabled the use of interactive denoiser from within Solaris. + - Fixed a bug where background renders in Solaris could lead to a crash if a + RIS render was already running interactively or if the output type of the + render was not set to "raster". + - Fixed a bug where pixelAspectRatio wasn't having the expected effect. + - Fixed some issues with MaterialX in Solaris. + - Fixed problem where hdPrman would keep rendering in the background when the + viewport switched to the GL renderer in Solaris. + - Improved data/display window calculation and removed clamp on overscan. + - Added support for aggregate volumes in Solaris. + - Added HD_PRMAN_HIDE_DEFAULT_DOMELIGHT_TEXTURE environment variable, which, + when set, forces any textured dome lights with a prefix of `` + or `` to be camera-invisible, as a temporary measure to + support Solaris. + +- Improved hdPrman compatibility with the Hush SideFX command line rendering + utility. + +- More work on hdPrman Hydra 2.0 transition. The following assumes a recent USD + version but does not require HD_PRMAN_EXPERIMENTAL_RILEY_SCENE_INDEX_OBSERVER. + The HdPrman_RileyGlobalsSceneIndex filtering scene index now computes some of + the Riley options to add a riley:globals prim. hdPrman's + HdsiPrimManagingSceneIndexObserver picks up the options on the riley:globals + prim and makes them contribute to the Riley::SetOptions call. + +- Fixed a bug where rendering a product without vars led to a crash in RenderMan. + +- Added support for PxrEnvDayLight. + +- Small performance cleanup for purpose-based visibility. + +### MaterialX + +- Made a change to how MaterialX node names are constructed from material + network node paths to support Solaris. This change only affects hdPrman built + as part of a DCC. + +- Fixed issue with Storm when rendering custom nodes that use the + node in their defining nodegraph, and either re-use that node's output or are + a multi-output node. + +- Fixed divide by zero issue in the calculation of a light's intensity value + inside Storm's MaterialX glslfx shader. + +- Added support for custom texture nodes in hdPrman. + +- Switched the USD name of surface shader nodes to use the MaterialX node name + instead of the NodeDef name. + (Issue: [#3100](https://github.com/PixarAnimationStudios/OpenUSD/issues/3100), + PR: [#3147](https://github.com/PixarAnimationStudios/OpenUSD/pull/3147)) + +- Fixed shadow support for MaterialX materials in Metal. + (Issue: [#3176](https://github.com/PixarAnimationStudios/OpenUSD/issues/3176), + PR: [#3264](https://github.com/PixarAnimationStudios/OpenUSD/pull/3264)) + +- Fixed testUsdMtlxFileFormat.py. + (PR: [#3147](https://github.com/PixarAnimationStudios/OpenUSD/pull/3147)) + +- Added more function tracing in UsdMtlx. + (PR: [#2806](https://github.com/PixarAnimationStudios/OpenUSD/pull/2806)) + +### Embree Hydra Plugin + +- Fixed a bug in HdEmbree random number generation. + (PR: [#3211](https://github.com/PixarAnimationStudios/OpenUSD/pull/3211)) + +- Added HDEMBREE_RANDOM_NUMBER_SEED to facilitate stable image testing. + (PR: [#3183](https://github.com/PixarAnimationStudios/OpenUSD/pull/3183)) + +- Typo fix and refactoring of ray hit code. + (PR: [#3185](https://github.com/PixarAnimationStudios/OpenUSD/pull/3185)) + +### usdview + +- Made a fix to correctly handle device pixel ratio with multi-display setups. + +- Added applied API schema data to the usdview "Meta Data" tab. + (Issue: [#1431](https://github.com/PixarAnimationStudios/OpenUSD/issues/1431)) + +### Documentation + +- Added new [performance metrics page](https://openusd.org/release/ref_performance_metrics.html) + to docs, used to publish metrics for each release, and describe how metrics + are measured. + +- Various documentation updates: + - Improvements to Hydra prim schema documentation. + - Updated docs to clarify schema strength ordering. + - Additional doc fixes. + (PR: [#2695](https://github.com/PixarAnimationStudios/OpenUSD/pull/2695), + [#3287](https://github.com/PixarAnimationStudios/OpenUSD/pull/3287)) + +- SIGGRAPH 2024 BoF slides PDF added to [Downloads page](https://openusd.org/release/dl_downloads.html). + +- [Contributing to USD](https://openusd.org/release/contributing_to_usd.html) + page updated with instructions to use when making major changes. + +- Added [Security Policy](https://github.com/PixarAnimationStudios/OpenUSD/blob/release/SECURITY.md) + with details on reporting security vulnerabilities with USD. + +- Switched .dox files in pxr/usd/usd to Markdown files (which addressed some + formatting issues), and renamed enclosing directory to "docs". We recommend + Markdown for new modules, as this makes the documentation more portable. + +- Updated URL to USD Assets Working Group "Primvar Interpolation" asset in the + Rendering with USD user guide. + (PR: [#3110](https://github.com/PixarAnimationStudios/OpenUSD/pull/3110)) + +### Security + +- Fixed crash when reading .usdc file with corrupt SdfSpecType values, see + [security advisory on github](https://github.com/PixarAnimationStudios/OpenUSD/security/advisories/GHSA-4j7j-gm3f-m63w). + +
+ Previous Releases + ## [24.08] - 2024-07-25 OpenUSD is now licensed under the Tomorrow Open Source Technology license. This @@ -621,8 +1148,6 @@ validators were also added: in relationship-mode vs expression-mode, and how the built-in properties affect membership determination in each mode. -
- Previous Releases ## [24.05] - 2024-04-19 diff --git a/LICENSE.txt b/LICENSE.txt index a2cdda092e..d3bb1fa530 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -850,3 +850,31 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +================================================================ +boost +================================================================ + +Boost Software License - Version 1.0 - August 17th, 2003 + +Permission is hereby granted, free of charge, to any person or organization +obtaining a copy of the software and accompanying documentation covered by +this license (the "Software") to use, reproduce, display, distribute, +execute, and transmit the Software, and to prepare derivative works of the +Software, and to permit third-parties to whom the Software is furnished to +do so, all subject to the following: + +The copyright notices in the Software and this entire statement, including +the above license grant, this restriction and the following disclaimer, +must be included in all copies of the Software, in whole or in part, and +all derivative works of the Software, unless such copies or derivative +works are solely in the form of machine-executable object code generated by +a source language processor. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT +SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE +FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 19ad9ce782..3ae449e39b 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,8 @@ visit our [forum](https://groups.google.com/forum/#!forum/usd-interest). If you are experiencing undocumented problems with the software, please [file a bug](https://github.com/PixarAnimationStudios/OpenUSD/issues/new). +If you need to report a security issue with the software, please review the +[Security Policy](SECURITY.md). Supported Platforms ------------------- @@ -73,7 +75,6 @@ Optional: Required: - [Python](https://python.org) - - [Boost](https://boost.org) **usdview** @@ -158,8 +159,6 @@ to use a monolithic build when embedding USD These builds do not support Python bindings or command line tools. -Currently, these builds also do not support Imaging or USD Imaging. - For example, the following will download, build, and install USD's dependencies, then build and install USD for iOS into `/path/to/my_usd_install_dir`. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000000..6e1b0d8c2f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,18 @@ +# Security Policy + +We appreciate your efforts to responsibly disclose your findings and will make +every effort to acknowledge your contributions. + +## Reporting a Vulnerability + +Please use the GitHub Security Advisory +["Report a Vulnerability" tab](https://github.com/PixarAnimationStudios/OpenUSD/security/advisories/new) +to report a security issue. Please do not report security vulnerabilities +through public issues, discussions, or change requests. + +The team will send a response indicating the next steps in handling your report. +After the initial reply to your report, the security team will keep you informed +of the progress towards a fix and may ask for additional information or guidance. + +Report security bugs in third-party plugins/applications to the team maintaining +the application. diff --git a/VERSIONS.md b/VERSIONS.md index c3caf2ed56..5783e3f99d 100644 --- a/VERSIONS.md +++ b/VERSIONS.md @@ -17,7 +17,6 @@ Our test machines have the following software versions installed. | C++ Compiler | gcc 9.3.1 | Apple clang 13.1.6 (Xcode 13.3)
Apple clang 15.0.0 (Xcode 15.4) for visionOS | Visual Studio 2017 15.9 | | CMake | 3.17.5 | 3.19.5 | 3.25.3 | | Python | 3.9.16 | 3.9.13 | 3.9.13 | -| Boost | 1.76.0 | 1.78.0 | 1.76.0 | | Intel TBB | 2020 Update 3 | 2018 Update 1, 2020 Update 3 | 2020 Update 3 | | OpenSubdiv | 3.6.0 | 3.6.0 | 3.6.0 | | OpenImageIO | 2.3.21.0 | 2.3.21.0 | 2.3.21.0 | diff --git a/azure-pipelines.yml b/azure-pipelines.yml index 57364f62f7..6d36618ee5 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -25,12 +25,12 @@ jobs: - job: macOS timeoutInMinutes: 120 pool: - vmImage: 'macOS-12' + vmImage: 'macOS-13' steps: - script: | # Update PATH to ensure that pyside2-uic can be found export PATH=/Library/Frameworks/Python.framework/Versions/3.11/bin:$PATH - sudo xcode-select -s /Applications/Xcode_13.3.app/Contents/Developer + sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer # Set SYSTEM_VERSION_COMPAT while installing Python packages to # accommodate the macOS version numbering change from 10.x to 11 export SYSTEM_VERSION_COMPAT=1 @@ -51,7 +51,7 @@ jobs: steps: - script: | call C:\"Program Files (x86)"\"Microsoft Visual Studio"\2019\Enterprise\VC\Auxiliary\Build\vcvars64.bat - call set PYTHONLOCATION=C:\hostedtoolcache\windows\Python\3.7.9\x64 + call set PYTHONLOCATION=C:\hostedtoolcache\windows\Python\3.9.13\x64 call set PYTHONBIN=%PYTHONLOCATION%\python.exe call set PATH=%PYTHONLOCATION%;%PYTHONLOCATION%\Scripts;%PATH% call set BOOST_ROOT= diff --git a/azure-pypi-pipeline.yml b/azure-pypi-pipeline.yml index 23a20bfad7..38080877c4 100644 --- a/azure-pypi-pipeline.yml +++ b/azure-pypi-pipeline.yml @@ -45,12 +45,6 @@ stages: - job: Linux strategy: matrix: - Python36: - PYTHON_INTERPRETER: /opt/python/cp36-cp36m/bin/python - PYTHON_TAG: cp36 - Python37: - PYTHON_INTERPRETER: /opt/python/cp37-cp37m/bin/python - PYTHON_TAG: cp37 Python38: PYTHON_INTERPRETER: /opt/python/cp38-cp38/bin/python PYTHON_TAG: cp38 @@ -119,12 +113,6 @@ stages: - job: Windows strategy: matrix: - Python36: - PYTHON_VERSION_SPEC: 3.6 - PYTHON_TAG: cp36 - Python37: - PYTHON_VERSION_SPEC: 3.7 - PYTHON_TAG: cp37 Python38: PYTHON_VERSION_SPEC: 3.8 PYTHON_TAG: cp38 @@ -179,14 +167,6 @@ stages: - job: Mac strategy: matrix: - Python36: - PYTHON_VERSION_SPEC: 3.6 - PYTHON_INTERPRETER: python3.6 - PYTHON_TAG: cp36 - Python37: - PYTHON_VERSION_SPEC: 3.7 - PYTHON_INTERPRETER: python3.7 - PYTHON_TAG: cp37 Python38: PYTHON_VERSION_SPEC: 3.8 PYTHON_INTERPRETER: python3.8 @@ -209,14 +189,14 @@ stages: PYTHON_TAG: cp312 timeoutInMinutes: 180 pool: - vmImage: 'macOS-12' + vmImage: 'macOS-13' steps: - task: UsePythonVersion@0 inputs: versionSpec: $(PYTHON_VERSION_SPEC) addToPath: true - script: | - sudo xcode-select -s /Applications/Xcode_13.2.app/Contents/Developer + sudo xcode-select -s /Applications/Xcode_14.1.app/Contents/Developer $(PYTHON_INTERPRETER) build_scripts/build_usd.py --build-args USD,"-DPXR_PY_UNDEFINED_DYNAMIC_LOOKUP=ON -DPXR_BUILD_USD_TOOLS=OFF -DPXR_INSTALL_LOCATION=../pluginfo" --no-materialx --no-imaging --no-examples --no-tutorials --generator Xcode --build-target universal --build $HOME/USDgen/build --src $HOME/USDgen/src $HOME/USDinst -v displayName: 'Building USD' - bash: | @@ -284,14 +264,6 @@ stages: - job: Test_Install strategy: matrix: - Linux_Python36: - PYTHON_VERSION_SPEC: 3.6 - IMAGE: 'Ubuntu-20.04' - PYTHON_INTERPRETER: python3 - Linux_Python37: - PYTHON_VERSION_SPEC: 3.7 - IMAGE: 'Ubuntu-20.04' - PYTHON_INTERPRETER: python3 Linux_Python38: PYTHON_VERSION_SPEC: 3.8 IMAGE: 'Ubuntu-20.04' @@ -312,14 +284,6 @@ stages: PYTHON_VERSION_SPEC: 3.12 IMAGE: 'Ubuntu-20.04' PYTHON_INTERPRETER: python3 - Windows_Python36: - PYTHON_VERSION_SPEC: 3.6 - IMAGE: 'windows-2019' - PYTHON_INTERPRETER: python - Windows_Python37: - PYTHON_VERSION_SPEC: 3.7 - IMAGE: 'windows-2019' - PYTHON_INTERPRETER: python Windows_Python38: PYTHON_VERSION_SPEC: 3.8 IMAGE: 'windows-2019' @@ -340,33 +304,25 @@ stages: PYTHON_VERSION_SPEC: 3.12 IMAGE: 'windows-2019' PYTHON_INTERPRETER: python - Mac_Python36: - PYTHON_VERSION_SPEC: 3.6 - IMAGE: 'macOS-12' - PYTHON_INTERPRETER: python3 - Mac_Python37: - PYTHON_VERSION_SPEC: 3.7 - IMAGE: 'macOS-12' - PYTHON_INTERPRETER: python3 Mac_Python38: PYTHON_VERSION_SPEC: 3.8 - IMAGE: 'macOS-12' + IMAGE: 'macOS-13' PYTHON_INTERPRETER: python3 Mac_Python39: PYTHON_VERSION_SPEC: 3.9 - IMAGE: 'macOS-12' + IMAGE: 'macOS-13' PYTHON_INTERPRETER: python3 Mac_Python310: PYTHON_VERSION_SPEC: 3.10 - IMAGE: 'macOS-12' + IMAGE: 'macOS-13' PYTHON_INTERPRETER: python3 Mac_Python311: PYTHON_VERSION_SPEC: 3.11 - IMAGE: 'macOS-12' + IMAGE: 'macOS-13' PYTHON_INTERPRETER: python3 Mac_Python312: PYTHON_VERSION_SPEC: 3.12 - IMAGE: 'macOS-12' + IMAGE: 'macOS-13' PYTHON_INTERPRETER: python3 timeoutInMinutes: 10 pool: diff --git a/build_scripts/build_usd.py b/build_scripts/build_usd.py index f31eecd19f..6d4e8feb05 100644 --- a/build_scripts/build_usd.py +++ b/build_scripts/build_usd.py @@ -744,9 +744,9 @@ def InstallBoost_Helper(context, force, buildArgs): # compatibility issues on Big Sur and Monterey. pyInfo = GetPythonInfo(context) pyVer = (int(pyInfo[3].split('.')[0]), int(pyInfo[3].split('.')[1])) - if MacOS() or (context.buildPython and pyVer >= (3,11)): + if MacOS() or (context.buildBoostPython and pyVer >= (3,11)): BOOST_URL = "https://boostorg.jfrog.io/artifactory/main/release/1.82.0/source/boost_1_82_0.zip" - elif context.buildPython and pyVer >= (3, 10): + elif context.buildBoostPython and pyVer >= (3, 10): BOOST_URL = "https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.zip" elif IsVisualStudio2022OrGreater(): BOOST_URL = "https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.zip" @@ -829,7 +829,7 @@ def InstallBoost_Helper(context, force, buildArgs): '--with-regex' ] - if context.buildPython: + if context.buildBoostPython: b2_settings.append("--with-python") pythonInfo = GetPythonInfo(context) # This is the only platform-independent way to configure these @@ -1534,10 +1534,23 @@ def InstallMaterialX(context, force, buildArgs): ] if MacOSTargetEmbedded(context): + # The materialXShaderGen in hdSt assumes the GLSL shadergen is + # available but MaterialX intertwines GLSL shadergen support with + # also requiring rendering support. cmakeOptions.extend([ '-DMATERIALX_BUILD_GEN_MSL=ON', - '-DMATERIALX_BUILD_GEN_GLSL=OFF', + '-DMATERIALX_BUILD_GEN_GLSL=ON', '-DMATERIALX_BUILD_IOS=ON']) + PatchFile("CMakeLists.txt", + [(' set(MATERIALX_BUILD_GEN_GLSL OFF)', + ' set(MATERIALX_BUILD_GEN_GLSL ON)'), + (' if (MATERIALX_BUILD_GEN_GLSL)\n' + + ' add_subdirectory(source/MaterialXRenderGlsl)\n' + + ' endif()', + ' if (MATERIALX_BUILD_GEN_GLSL AND NOT MATERIALX_BUILD_IOS)\n' + + ' add_subdirectory(source/MaterialXRenderGlsl)\n' + + ' endif()') + ], multiLineMatches=True) cmakeOptions += buildArgs RunCMake(context, force, cmakeOptions) @@ -1622,6 +1635,11 @@ def InstallUSD(context, force, buildArgs): else: extraArgs.append('-DPXR_USE_DEBUG_PYTHON=OFF') + if context.buildBoostPython: + extraArgs.append('-DPXR_USE_BOOST_PYTHON=ON') + else: + extraArgs.append('-DPXR_USE_BOOST_PYTHON=OFF') + # CMake has trouble finding the executable, library, and include # directories when there are multiple versions of Python installed. # This can lead to crashes due to USD being linked against one @@ -1825,8 +1843,8 @@ def InstallUSD(context, force, buildArgs): - Embedded Build Targets When cross compiling for an embedded target operating system, e.g. iOS, the -following components are disabled: python, tools, imaging, tests, examples, -tutorials. +following components are disabled: python, tools, tests, examples, tutorials, +opencolorio, openimageio, openvdb. - Python Versions and DCC Plugins: Some DCCs may ship with and run using their own version of Python. In that case, @@ -2005,6 +2023,10 @@ def InstallUSD(context, force, buildArgs): "Disable performance-impacting safety checks against " "malformed input files") +group.add_argument("--boost-python", dest="build_boost_python", + action="store_true", default=False, + help="Build Python bindings with boost::python (deprecated)") + subgroup = group.add_mutually_exclusive_group() subgroup.add_argument("--debug-python", dest="debug_python", action="store_true", help= @@ -2244,6 +2266,7 @@ def __init__(self, args): # Optional components self.buildTests = args.build_tests and not embedded self.buildPython = args.build_python and not embedded + self.buildBoostPython = self.buildPython and args.build_boost_python self.buildExamples = args.build_examples and not embedded self.buildTutorials = args.build_tutorials and not embedded self.buildTools = args.build_tools and not embedded @@ -2255,9 +2278,11 @@ def __init__(self, args): # - Imaging self.buildImaging = (args.build_imaging == IMAGING or - args.build_imaging == USD_IMAGING) and not embedded + args.build_imaging == USD_IMAGING) self.enablePtex = self.buildImaging and args.enable_ptex - self.enableOpenVDB = self.buildImaging and args.enable_openvdb + self.enableOpenVDB = (self.buildImaging + and args.enable_openvdb + and not embedded) # - USD Imaging self.buildUsdImaging = (args.build_imaging == USD_IMAGING) @@ -2272,9 +2297,10 @@ def __init__(self, args): self.buildPrman = self.buildImaging and args.build_prman self.prmanLocation = (os.path.abspath(args.prman_location) if args.prman_location else None) - self.buildOIIO = args.build_oiio or (self.buildUsdImaging - and self.buildTests) - self.buildOCIO = args.build_ocio + self.buildOIIO = ((args.build_oiio or (self.buildUsdImaging + and self.buildTests)) + and not embedded) + self.buildOCIO = args.build_ocio and not embedded # - Alembic Plugin self.buildAlembic = args.build_alembic @@ -2337,7 +2363,7 @@ def ForceBuildDependency(self, dep): requiredDependencies = [ZLIB, TBB] -if context.buildPython: +if context.buildBoostPython: requiredDependencies += [BOOST] if context.buildAlembic: @@ -2411,8 +2437,14 @@ def ForceBuildDependency(self, dep): if "--tools" in sys.argv: PrintError("Cannot build tools for embedded build targets") sys.exit(1) - if "--imaging" in sys.argv: - PrintError("Cannot build imaging for embedded build targets") + if "--openimageio" in sys.argv: + PrintError("Cannot build openimageio for embedded build targets") + sys.exit(1) + if "--opencolorio" in sys.argv: + PrintError("Cannot build opencolorio for embedded build targets") + sys.exit(1) + if "--openvdb" in sys.argv: + PrintError("Cannot build openvdb for embedded build targets") sys.exit(1) # Error out if user explicitly specified building usdview without required diff --git a/cmake/defaults/CXXDefaults.cmake b/cmake/defaults/CXXDefaults.cmake index e9eee14f06..8218d50c2c 100644 --- a/cmake/defaults/CXXDefaults.cmake +++ b/cmake/defaults/CXXDefaults.cmake @@ -24,9 +24,6 @@ endif() _add_define(GL_GLEXT_PROTOTYPES) _add_define(GLX_GLXEXT_PROTOTYPES) -# Python bindings for tf require this define. -_add_define(BOOST_PYTHON_NO_PY_SIGNATURES) - # Parts of boost (in particular, boost::hash) rely on deprecated features # of the STL that have been removed from some implementations under C++17. # This define tells boost not to use those features. @@ -67,7 +64,7 @@ if (PXR_ENABLE_NAMESPACES) if (PXR_SET_INTERNAL_NAMESPACE) set(PXR_INTERNAL_NAMESPACE ${PXR_SET_INTERNAL_NAMESPACE}) else() - set(PXR_INTERNAL_NAMESPACE "pxrInternal_v${PXR_MAJOR_VERSION}_${PXR_MINOR_VERSION}") + set(PXR_INTERNAL_NAMESPACE "pxrInternal_v${PXR_MAJOR_VERSION}_${PXR_MINOR_VERSION}_${PXR_PATCH_VERSION}") endif() message(STATUS "C++ namespace configured to (external) ${PXR_EXTERNAL_NAMESPACE}, (internal) ${PXR_INTERNAL_NAMESPACE}") @@ -83,6 +80,12 @@ else() set(PXR_PYTHON_SUPPORT_ENABLED "0") endif() +if (PXR_USE_BOOST_PYTHON) + set(PXR_USE_INTERNAL_BOOST_PYTHON "0") +else() + set(PXR_USE_INTERNAL_BOOST_PYTHON "1") +endif() + # Set safety/performance configuration if (PXR_PREFER_SAFETY_OVER_SPEED) set(PXR_PREFER_SAFETY_OVER_SPEED "1") diff --git a/cmake/defaults/Options.cmake b/cmake/defaults/Options.cmake index 6c118a9479..74cee361fd 100644 --- a/cmake/defaults/Options.cmake +++ b/cmake/defaults/Options.cmake @@ -26,6 +26,7 @@ option(PXR_BUILD_PYTHON_DOCUMENTATION "Generate Python documentation" OFF) option(PXR_BUILD_HTML_DOCUMENTATION "Generate HTML documentation if PXR_BUILD_DOCUMENTATION is ON" ON) option(PXR_ENABLE_PYTHON_SUPPORT "Enable Python based components for USD" ON) option(PXR_USE_DEBUG_PYTHON "Build with debug python" OFF) +option(PXR_USE_BOOST_PYTHON "Use boost::python for Python bindings (deprecated)" OFF) option(PXR_ENABLE_HDF5_SUPPORT "Enable HDF5 backend in the Alembic plugin for USD" OFF) option(PXR_ENABLE_OSL_SUPPORT "Enable OSL (OpenShadingLanguage) based components" OFF) option(PXR_ENABLE_PTEX_SUPPORT "Enable Ptex support" OFF) @@ -52,10 +53,18 @@ if(APPLE) MESSAGE(STATUS "Setting PXR_BUILD_USD_TOOLS=OFF because they are not supported on Apple embedded platforms") set(PXR_BUILD_USD_TOOLS OFF) endif() - if (${PXR_BUILD_IMAGING}) - MESSAGE(STATUS "Setting PXR_BUILD_USD_IMAGING=OFF because it is not supported on Apple embedded platforms") - set(PXR_BUILD_IMAGING OFF) - endif () + if(${PXR_BUILD_OPENCOLORIO_PLUGIN}) + MESSAGE(STATUS "Setting PXR_BUILD_OPENCOLORIO_PLUGIN=OFF because it is not supported on Apple embedded platforms") + set(PXR_BUILD_OPENCOLORIO_PLUGIN OFF) + endif() + if(${PXR_BUILD_OPENIMAGEIO_PLUGIN}) + MESSAGE(STATUS "Setting PXR_BUILD_OPENIMAGEIO_PLUGIN=OFF because it is not supported on Apple embedded platforms") + set(PXR_BUILD_OPENIMAGEIO_PLUGIN OFF) + endif() + if(${PXR_ENABLE_OPENVDB_SUPPORT}) + MESSAGE(STATUS "Setting PXR_ENABLE_OPENVDB_SUPPORT=OFF because it is not supported on Apple embedded platforms") + set(PXR_ENABLE_OPENVDB_SUPPORT OFF) + endif() endif () endif() diff --git a/cmake/defaults/Packages.cmake b/cmake/defaults/Packages.cmake index fe60570b34..8ac373aa8f 100644 --- a/cmake/defaults/Packages.cmake +++ b/cmake/defaults/Packages.cmake @@ -20,7 +20,7 @@ set(CMAKE_THREAD_PREFER_PTHREAD TRUE) find_package(Threads REQUIRED) set(PXR_THREAD_LIBS "${CMAKE_THREAD_LIBS_INIT}") -if(PXR_ENABLE_PYTHON_SUPPORT OR PXR_ENABLE_OPENVDB_SUPPORT) +if((PXR_ENABLE_PYTHON_SUPPORT AND PXR_USE_BOOST_PYTHON) OR PXR_ENABLE_OPENVDB_SUPPORT) # Find Boost package before getting any boost specific components as we need to # disable boost-provided cmake config, based on the boost version found. find_package(Boost REQUIRED) @@ -95,31 +95,33 @@ if(PXR_ENABLE_PYTHON_SUPPORT) # USD builds only work with Python3 setup_python_package(Python3) - if(WIN32 AND PXR_USE_DEBUG_PYTHON) - set(Boost_USE_DEBUG_PYTHON ON) - endif() + if(PXR_USE_BOOST_PYTHON) + if(WIN32 AND PXR_USE_DEBUG_PYTHON) + set(Boost_USE_DEBUG_PYTHON ON) + endif() - # Manually specify VS2022, 2019, and 2017 as USD's supported compiler versions - if(WIN32) - set(Boost_COMPILER "-vc143;-vc142;-vc141") - endif() + # Manually specify VS2022, 2019, and 2017 as USD's supported compiler versions + if(WIN32) + set(Boost_COMPILER "-vc143;-vc142;-vc141") + endif() - # As of boost 1.67 the boost_python component name includes the - # associated Python version (e.g. python27, python36). - # XXX: After boost 1.73, boost provided config files should be able to - # work without specifying a python version! - # https://github.com/boostorg/boost_install/blob/master/BoostConfig.cmake - - # Find the component under the versioned name and then set the generic - # Boost_PYTHON_LIBRARY variable so that we don't have to duplicate this - # logic in each library's CMakeLists.txt. - set(python_version_nodot "${PYTHON_VERSION_MAJOR}${PYTHON_VERSION_MINOR}") - find_package(Boost - COMPONENTS - python${python_version_nodot} - REQUIRED - ) - set(Boost_PYTHON_LIBRARY "${Boost_PYTHON${python_version_nodot}_LIBRARY}") + # As of boost 1.67 the boost_python component name includes the + # associated Python version (e.g. python27, python36). + # XXX: After boost 1.73, boost provided config files should be able to + # work without specifying a python version! + # https://github.com/boostorg/boost_install/blob/master/BoostConfig.cmake + + # Find the component under the versioned name and then set the generic + # Boost_PYTHON_LIBRARY variable so that we don't have to duplicate this + # logic in each library's CMakeLists.txt. + set(python_version_nodot "${PYTHON_VERSION_MAJOR}${PYTHON_VERSION_MINOR}") + find_package(Boost + COMPONENTS + python${python_version_nodot} + REQUIRED + ) + set(Boost_PYTHON_LIBRARY "${Boost_PYTHON${python_version_nodot}_LIBRARY}") + endif() # --Jinja2 find_package(Jinja2) @@ -180,14 +182,6 @@ if (PXR_BUILD_DOCUMENTATION) endif() endif() -if (PXR_VALIDATE_GENERATED_CODE) - find_package(BISON 2.4.1 EXACT) - # Flex 2.5.39+ is required, generated API is generated incorrectly in - # 2.5.35, at least. scan_bytes generates with (..., int len, ...) instead of - # the correct (..., yy_size_t len, ...). Lower at your own peril. - find_package(FLEX 2.5.39 EXACT) -endif() - # Imaging Components Package Requirements # ---------------------------------------------- @@ -207,7 +201,7 @@ if (PXR_BUILD_IMAGING) add_definitions(-DPXR_OCIO_PLUGIN_ENABLED) endif() # --OpenGL - if (PXR_ENABLE_GL_SUPPORT) + if (PXR_ENABLE_GL_SUPPORT AND NOT PXR_APPLE_EMBEDDED) # Prefer legacy GL library over GLVND libraries if both # are installed. if (POLICY CMP0072) @@ -243,10 +237,7 @@ if (PXR_BUILD_IMAGING) endforeach() # Find the OS specific libs we need - if (APPLE) - find_library(MVK_LIBRARIES NAMES MoltenVK PATHS $ENV{VULKAN_SDK}/lib) - list(APPEND VULKAN_LIBS ${MVK_LIBRARIES}) - elseif (UNIX AND NOT APPLE) + if (UNIX AND NOT APPLE) find_package(X11 REQUIRED) list(APPEND VULKAN_LIBS ${X11_LIBRARIES}) elseif (WIN32) @@ -259,7 +250,7 @@ if (PXR_BUILD_IMAGING) endif() endif() # --Opensubdiv - set(OPENSUBDIV_USE_GPU ${PXR_ENABLE_GL_SUPPORT}) + set(OPENSUBDIV_USE_GPU ${PXR_BUILD_GPU_SUPPORT}) find_package(OpenSubdiv 3 REQUIRED) # --Ptex if (PXR_ENABLE_PTEX_SUPPORT) diff --git a/cmake/defaults/Version.cmake b/cmake/defaults/Version.cmake index 427608ca83..e9657e399e 100644 --- a/cmake/defaults/Version.cmake +++ b/cmake/defaults/Version.cmake @@ -7,6 +7,6 @@ # Versioning information set(PXR_MAJOR_VERSION "0") set(PXR_MINOR_VERSION "24") -set(PXR_PATCH_VERSION "8") # NOTE: Must not have leading 0 for single digits +set(PXR_PATCH_VERSION "11") # NOTE: Must not have leading 0 for single digits math(EXPR PXR_VERSION "${PXR_MAJOR_VERSION} * 10000 + ${PXR_MINOR_VERSION} * 100 + ${PXR_PATCH_VERSION}") diff --git a/cmake/defaults/msvcdefaults.cmake b/cmake/defaults/msvcdefaults.cmake index 78bde7a77e..13d77d0ae7 100644 --- a/cmake/defaults/msvcdefaults.cmake +++ b/cmake/defaults/msvcdefaults.cmake @@ -87,10 +87,6 @@ _add_define("_SCL_SECURE_NO_WARNINGS") # will conflict with std::min() and std::max(). _add_define("NOMINMAX") -# Needed to prevent YY files trying to include unistd.h -# (which doesn't exist on Windows) -_add_define("YY_NO_UNISTD_H") - # Forces all libraries that have separate source to be linked as # DLL's rather than static libraries on Microsoft Windows, unless # explicitly told otherwise. diff --git a/cmake/macros/Private.cmake b/cmake/macros/Private.cmake index 48fe107dd7..311524da0c 100644 --- a/cmake/macros/Private.cmake +++ b/cmake/macros/Private.cmake @@ -140,15 +140,30 @@ function(_get_python_module_name LIBRARY_FILENAME MODULE_NAME) ) endfunction() # _get_python_module_name -function(_plugInfo_subst libTarget pluginToLibraryPath plugInfoPath) +# For scenarios where we are bunding resource paths from an absolute path, +# like in the case of getting plugInfo.json from renderman bundled schemas, +# extract just the file name from resourceFile, and use it to determine our +# plugInfoFile, which will be then used to install the file to the intended +# destination directory. +function(_get_plugInfo_file resourceFile plugInfoFile) + if (IS_ABSOLUTE ${resourceFile}) + get_filename_component(resourceFileName ${resourceFile} NAME) + set(${plugInfoFile} "${CMAKE_CURRENT_BINARY_DIR}/${resourceFileName}" + PARENT_SCOPE) + else() + set(${plugInfoFile} "${CMAKE_CURRENT_BINARY_DIR}/${resourceFile}" + PARENT_SCOPE) + endif() +endfunction() # _get_plugInfo_file + +function(_plugInfo_subst libTarget pluginToLibraryPath plugInfoPath destFile) _get_resources_dir_name(PLUG_INFO_RESOURCE_PATH) set(PLUG_INFO_ROOT "..") set(PLUG_INFO_PLUGIN_NAME "pxr.${libTarget}") set(PLUG_INFO_LIBRARY_PATH "${pluginToLibraryPath}") - configure_file( ${plugInfoPath} - ${CMAKE_CURRENT_BINARY_DIR}/${plugInfoPath} + ${destFile} ) endfunction() # _plugInfo_subst @@ -224,7 +239,7 @@ function(_install_python LIBRARY_NAME) add_custom_target(${LIBRARY_NAME}_pythonfiles DEPENDS ${files_copied} ) - add_dependencies(python ${LIBRARY_NAME}_pythonfiles) + add_dependencies(python_modules ${LIBRARY_NAME}_pythonfiles) _get_folder("_python" folder) set_target_properties(${LIBRARY_NAME}_pythonfiles @@ -254,7 +269,18 @@ function(_install_resource_files NAME pluginInstallPrefix pluginToLibraryPath) # A resource file may be specified like : to # indicate that it should be installed to a different location in # the resources area. Check if this is the case. - string(REPLACE ":" ";" resourceFile "${resourceFile}") + set(plugInfoNoSubstitution) + + # Normalize path to use forward slashes on all platforms + file(TO_CMAKE_PATH "${resourceFile}" resourceFile) + + # Perform regex match to extract both source resource path and + # destination resource path. + # Regex match appropriately takes care of windows drive letter followed + # by a ":", which is also the token we use to separate the source and + # destination resource paths. + string(REGEX MATCHALL "([A-Za-z]:)?([^:]+)" resourceFile "${resourceFile}") + list(LENGTH resourceFile n) if (n EQUAL 1) set(resourceDestFile ${resourceFile}) @@ -281,17 +307,19 @@ function(_install_resource_files NAME pluginInstallPrefix pluginToLibraryPath) # path. Otherwise, use the original relative path which is relative to # the source directory. if (${destFileName} STREQUAL "plugInfo.json") + _get_plugInfo_file(${resourceFile} plugInfoFile) if (DEFINED plugInfoNoSubstitution) # Do not substitute variables and only copy the plugInfo file configure_file( ${resourceFile} - ${CMAKE_CURRENT_BINARY_DIR}/${resourceFile} + ${plugInfoFile} COPYONLY ) else() - _plugInfo_subst(${NAME} "${pluginToLibraryPath}" ${resourceFile}) + _plugInfo_subst(${NAME} "${pluginToLibraryPath}" + ${resourceFile} ${plugInfoFile}) endif() - set(resourceFile "${CMAKE_CURRENT_BINARY_DIR}/${resourceFile}") + set(resourceFile "${plugInfoFile}") endif() install( @@ -330,7 +358,7 @@ function(_install_pyside_ui_files LIBRARY_NAME) add_custom_target(${LIBRARY_NAME}_pysideuifiles DEPENDS ${uiFiles} ) - add_dependencies(python ${LIBRARY_NAME}_pythonfiles) + add_dependencies(python_modules ${LIBRARY_NAME}_pythonfiles) _get_folder("_pysideuifiles" folder) set_target_properties( @@ -991,7 +1019,7 @@ function(_pxr_python_module NAME) SHARED ${args_CPPFILES} ) - add_dependencies(python ${LIBRARY_NAME}) + add_dependencies(python_modules ${LIBRARY_NAME}) if(args_PYTHON_FILES) add_dependencies(${LIBRARY_NAME} ${LIBRARY_NAME}_pythonfiles) endif() diff --git a/cmake/macros/Public.cmake b/cmake/macros/Public.cmake index 9f3d358377..1b809e738d 100644 --- a/cmake/macros/Public.cmake +++ b/cmake/macros/Public.cmake @@ -76,7 +76,7 @@ function(pxr_python_bin BIN_NAME) ) # If we can't build Python modules then do nothing. - if(NOT TARGET python) + if(NOT TARGET python_modules) message(STATUS "Skipping Python program ${BIN_NAME}, Python modules required") return() endif() @@ -141,7 +141,7 @@ function(pxr_python_bin BIN_NAME) add_custom_target(${BIN_NAME}_script DEPENDS ${outputs} ${pb_DEPENDENCIES} ) - add_dependencies(python ${BIN_NAME}_script) + add_dependencies(python_modules ${BIN_NAME}_script) _get_folder("" folder) set_target_properties(${BIN_NAME}_script @@ -207,6 +207,7 @@ endfunction() function(pxr_library NAME) set(options DISABLE_PRECOMPILED_HEADERS + INCLUDE_SCHEMA_FILES ) set(oneValueArgs TYPE @@ -242,23 +243,90 @@ function(pxr_library NAME) # If python support is enabled, merge the python specific categories # with the more general before setting up compilation. if(PXR_ENABLE_PYTHON_SUPPORT) + set(libraryRequiresPython 0) if(args_PYTHON_PUBLIC_CLASSES) list(APPEND args_PUBLIC_CLASSES ${args_PYTHON_PUBLIC_CLASSES}) + set(libraryRequiresPython 1) endif() if(args_PYTHON_PUBLIC_HEADERS) list(APPEND args_PUBLIC_HEADERS ${args_PYTHON_PUBLIC_HEADERS}) + set(libraryRequiresPython 1) endif() if(args_PYTHON_PRIVATE_CLASSES) list(APPEND args_PRIVATE_CLASSES ${args_PYTHON_PRIVATE_CLASSES}) + set(libraryRequiresPython 1) endif() if(args_PYTHON_PRIVATE_HEADERS) list(APPEND args_PRIVATE_HEADERS ${args_PYTHON_PRIVATE_HEADERS}) + set(libraryRequiresPython 1) endif() if(args_PYTHON_CPPFILES) list(APPEND args_CPPFILES ${args_PYTHON_CPPFILES}) + set(libraryRequiresPython 1) + endif() + + if(libraryRequiresPython) + list(APPEND args_LIBRARIES ${PYTHON_LIBRARIES} python) + list(APPEND args_INCLUDE_DIRS ${PYTHON_INCLUDE_DIRS}) endif() endif() + # If this is a schema library, add schema classes + if (args_INCLUDE_SCHEMA_FILES) + set(filePath "generatedSchema.classes.txt") + + # Register a dependency so that cmake will regenerate the build + # system if generatedSchema.classes.txt changes + set_property( + DIRECTORY + APPEND + PROPERTY CMAKE_CONFIGURE_DEPENDS + ${filePath} + ) + + # Read the generated classes + file(STRINGS ${filePath} fileContents) + + # fileType potential values: + # -1: Skip line + # 0: Public Classes + # 1: Python Module Files + # 2: Resource Files + set(fileType -1) + + foreach(line ${fileContents}) + # Determine which section of the generated file we are in. + if (${fileType} EQUAL -1) + string(FIND ${line} "# Public Classes" found) + if (NOT ${found} EQUAL -1) + set(fileType 0) + continue() + endif() + elseif(${fileType} EQUAL 0) + string(FIND ${line} "# Python Module Files" found) + if (NOT ${found} EQUAL -1) + set(fileType 1) + continue() + endif() + elseif(${fileType} EQUAL 1) + string(FIND ${line} "# Resource Files" found) + if (NOT ${found} EQUAL -1) + set(fileType 2) + continue() + endif() + endif() + + # Depending on the file type, append to the appropriate list. + if (${fileType} EQUAL 0) + list(APPEND args_PUBLIC_CLASSES ${line}) + elseif(${fileType} EQUAL 1) + list(APPEND args_PYMODULE_CPPFILES ${line}) + elseif(${fileType} EQUAL 2) + list(APPEND args_RESOURCE_FILES ${line}) + endif() + endforeach() + endif() + # Collect libraries. if(NOT args_TYPE STREQUAL "PLUGIN") get_property(help CACHE PXR_ALL_LIBS PROPERTY HELPSTRING) @@ -336,13 +404,15 @@ function(pxr_library NAME) ) if(PXR_ENABLE_PYTHON_SUPPORT AND (args_PYMODULE_CPPFILES OR args_PYMODULE_FILES OR args_PYSIDE_UI_FILES)) + list(APPEND pythonModuleIncludeDirs ${PYTHON_INCLUDE_DIRS}) + _pxr_python_module( ${NAME} WRAPPED_LIB_INSTALL_PREFIX "${libInstallPrefix}" PYTHON_FILES ${args_PYMODULE_FILES} PYSIDE_UI_FILES ${args_PYSIDE_UI_FILES} CPPFILES ${args_PYMODULE_CPPFILES} - INCLUDE_DIRS ${args_INCLUDE_DIRS} + INCLUDE_DIRS "${args_INCLUDE_DIRS};${pythonModuleIncludeDirs}" PRECOMPILED_HEADERS ${pch} PRECOMPILED_HEADER_NAME ${args_PRECOMPILED_HEADER_NAME} ) @@ -388,7 +458,7 @@ endfunction() # pxr_setup_python function (pxr_create_test_module MODULE_NAME) # If we can't build Python modules then do nothing. - if(NOT TARGET python) + if(NOT TARGET python_modules) return() endif() @@ -573,7 +643,7 @@ endfunction() # pxr_build_test function(pxr_test_scripts) # If we can't build Python modules then do nothing. - if(NOT TARGET python) + if(NOT TARGET python_modules) return() endif() @@ -666,7 +736,7 @@ function(pxr_register_test TEST_NAME) endif() endif() - if(NOT TARGET python) + if(NOT TARGET python_modules) # Implicit requirement. Python modules require shared USD # libraries. If the test runs python it's certainly going # to load USD modules. If the test uses C++ to load USD @@ -1030,9 +1100,9 @@ function(pxr_toplevel_prologue) endif() # Create a target for targets that require Python. Each should add - # itself as a dependency to the "python" target. + # itself as a dependency to the "python_modules" target. if(TARGET shared_libs AND PXR_ENABLE_PYTHON_SUPPORT) - add_custom_target(python ALL) + add_custom_target(python_modules ALL) endif() endfunction() # pxr_toplevel_prologue @@ -1317,4 +1387,22 @@ function(pxr_docs_only_dir NAME) ${args_DOXYGEN_FILES} ) endif() -endfunction() # pxr_docs_only_dir \ No newline at end of file +endfunction() # pxr_docs_only_dir + +# Sets rpaths for the specified TARGET to the given RPATHS. The target's +# runtime destination directory is given by ORIGIN. If ORIGIN is not +# absolute it is assumed to be relative to CMAKE_INSTALL_PREFIX. +function(pxr_set_rpaths_for_target TARGET) + set(oneValueArgs ORIGIN) + set(multiValueArgs RPATHS) + cmake_parse_arguments(args "" "${oneValueArgs}" "${multiValueArgs}" ${ARGN}) + + _pxr_init_rpath(rpath ${args_ORIGIN}) + + foreach(path IN LISTS args_RPATHS) + _pxr_add_rpath(rpath ${path}) + endforeach() + + _pxr_install_rpath(rpath ${TARGET}) + +endfunction() # pxr_set_rpaths_for_target diff --git a/docs/README.md b/docs/README.md index 0b164acec0..1d3d4a47fe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -18,6 +18,7 @@ USD's Sphinx build uses the following Sphinx extensions: * [Sphinx Panels](https://sphinx-panels.readthedocs.io/en/latest/) * [Doxylink](https://github.com/sphinx-contrib/doxylink) * [MyST](https://myst-parser.readthedocs.io/en/v0.17.1/index.html) +* [Datatemplates](https://sphinxcontribdatatemplates.readthedocs.io/en/latest/index.html) See "Sphinx Setup" below for how to install Sphinx and the necessary extensions. diff --git a/docs/_templates/perf_metric_alab_template.tmpl b/docs/_templates/perf_metric_alab_template.tmpl new file mode 100644 index 0000000000..f535a1243d --- /dev/null +++ b/docs/_templates/perf_metric_alab_template.tmpl @@ -0,0 +1,86 @@ +{% set alab_metrics_linux_24_11 = load('performance/24.11_linux_alab.yaml', data_format='yaml') %} + +.. list-table:: Linux Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ alab_metrics_linux_24_11['open_stage']['min'] }} + | max: {{ alab_metrics_linux_24_11['open_stage']['max'] }} + | mean: {{ alab_metrics_linux_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ alab_metrics_linux_24_11['create_first_image']['min'] }} + | max: {{ alab_metrics_linux_24_11['create_first_image']['max'] }} + | mean: {{ alab_metrics_linux_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ alab_metrics_linux_24_11['close_stage']['min'] }} + | max: {{ alab_metrics_linux_24_11['close_stage']['max'] }} + | mean: {{ alab_metrics_linux_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ alab_metrics_linux_24_11['shut_down_hydra']['min'] }} + | max: {{ alab_metrics_linux_24_11['shut_down_hydra']['max'] }} + | mean: {{ alab_metrics_linux_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set alab_metrics_macos_24_11 = load('performance/24.11_macos_alab.yaml', data_format='yaml') %} + +.. list-table:: macOS Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ alab_metrics_macos_24_11['open_stage']['min'] }} + | max: {{ alab_metrics_macos_24_11['open_stage']['max'] }} + | mean: {{ alab_metrics_macos_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ alab_metrics_macos_24_11['create_first_image']['min'] }} + | max: {{ alab_metrics_macos_24_11['create_first_image']['max'] }} + | mean: {{ alab_metrics_macos_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ alab_metrics_macos_24_11['close_stage']['min'] }} + | max: {{ alab_metrics_macos_24_11['close_stage']['max'] }} + | mean: {{ alab_metrics_macos_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ alab_metrics_macos_24_11['shut_down_hydra']['min'] }} + | max: {{ alab_metrics_macos_24_11['shut_down_hydra']['max'] }} + | mean: {{ alab_metrics_macos_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set alab_metrics_win_24_11 = load('performance/24.11_windows_alab.yaml', data_format='yaml') %} + +.. list-table:: Windows Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ alab_metrics_win_24_11['open_stage']['min'] }} + | max: {{ alab_metrics_win_24_11['open_stage']['max'] }} + | mean: {{ alab_metrics_win_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ alab_metrics_win_24_11['create_first_image']['min'] }} + | max: {{ alab_metrics_win_24_11['create_first_image']['max'] }} + | mean: {{ alab_metrics_win_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ alab_metrics_win_24_11['close_stage']['min'] }} + | max: {{ alab_metrics_win_24_11['close_stage']['max'] }} + | mean: {{ alab_metrics_win_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ alab_metrics_win_24_11['shut_down_hydra']['min'] }} + | max: {{ alab_metrics_win_24_11['shut_down_hydra']['max'] }} + | mean: {{ alab_metrics_win_24_11['shut_down_hydra']['mean']}} + - TBD diff --git a/docs/_templates/perf_metric_kitchenset_template.tmpl b/docs/_templates/perf_metric_kitchenset_template.tmpl new file mode 100644 index 0000000000..ea90892b93 --- /dev/null +++ b/docs/_templates/perf_metric_kitchenset_template.tmpl @@ -0,0 +1,86 @@ +{% set kitchenset_metrics_linux_24_11 = load('performance/24.11_linux_kitchenset.yaml', data_format='yaml') %} + +.. list-table:: Linux Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ kitchenset_metrics_linux_24_11['open_stage']['min'] }} + | max: {{ kitchenset_metrics_linux_24_11['open_stage']['max'] }} + | mean: {{ kitchenset_metrics_linux_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ kitchenset_metrics_linux_24_11['create_first_image']['min'] }} + | max: {{ kitchenset_metrics_linux_24_11['create_first_image']['max'] }} + | mean: {{ kitchenset_metrics_linux_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ kitchenset_metrics_linux_24_11['close_stage']['min'] }} + | max: {{ kitchenset_metrics_linux_24_11['close_stage']['max'] }} + | mean: {{ kitchenset_metrics_linux_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ kitchenset_metrics_linux_24_11['shut_down_hydra']['min'] }} + | max: {{ kitchenset_metrics_linux_24_11['shut_down_hydra']['max'] }} + | mean: {{ kitchenset_metrics_linux_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set kitchenset_metrics_macos_24_11 = load('performance/24.11_macos_kitchenset.yaml', data_format='yaml') %} + +.. list-table:: macOS Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ kitchenset_metrics_macos_24_11['open_stage']['min'] }} + | max: {{ kitchenset_metrics_macos_24_11['open_stage']['max'] }} + | mean: {{ kitchenset_metrics_macos_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ kitchenset_metrics_macos_24_11['create_first_image']['min'] }} + | max: {{ kitchenset_metrics_macos_24_11['create_first_image']['max'] }} + | mean: {{ kitchenset_metrics_macos_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ kitchenset_metrics_macos_24_11['close_stage']['min'] }} + | max: {{ kitchenset_metrics_macos_24_11['close_stage']['max'] }} + | mean: {{ kitchenset_metrics_macos_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ kitchenset_metrics_macos_24_11['shut_down_hydra']['min'] }} + | max: {{ kitchenset_metrics_macos_24_11['shut_down_hydra']['max'] }} + | mean: {{ kitchenset_metrics_macos_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set kitchenset_metrics_win_24_11 = load('performance/24.11_windows_kitchenset.yaml', data_format='yaml') %} + +.. list-table:: Windows Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ kitchenset_metrics_win_24_11['open_stage']['min'] }} + | max: {{ kitchenset_metrics_win_24_11['open_stage']['max'] }} + | mean: {{ kitchenset_metrics_win_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ kitchenset_metrics_win_24_11['create_first_image']['min'] }} + | max: {{ kitchenset_metrics_win_24_11['create_first_image']['max'] }} + | mean: {{ kitchenset_metrics_win_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ kitchenset_metrics_win_24_11['close_stage']['min'] }} + | max: {{ kitchenset_metrics_win_24_11['close_stage']['max'] }} + | mean: {{ kitchenset_metrics_win_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ kitchenset_metrics_win_24_11['shut_down_hydra']['min'] }} + | max: {{ kitchenset_metrics_win_24_11['shut_down_hydra']['max'] }} + | mean: {{ kitchenset_metrics_win_24_11['shut_down_hydra']['mean']}} + - TBD diff --git a/docs/_templates/perf_metric_moorelane_template.tmpl b/docs/_templates/perf_metric_moorelane_template.tmpl new file mode 100644 index 0000000000..abb044e5c5 --- /dev/null +++ b/docs/_templates/perf_metric_moorelane_template.tmpl @@ -0,0 +1,86 @@ +{% set moorelane_metrics_linux_24_11 = load('performance/24.11_linux_moorelane.yaml', data_format='yaml') %} + +.. list-table:: Linux Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ moorelane_metrics_linux_24_11['open_stage']['min'] }} + | max: {{ moorelane_metrics_linux_24_11['open_stage']['max'] }} + | mean: {{ moorelane_metrics_linux_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ moorelane_metrics_linux_24_11['create_first_image']['min'] }} + | max: {{ moorelane_metrics_linux_24_11['create_first_image']['max'] }} + | mean: {{ moorelane_metrics_linux_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ moorelane_metrics_linux_24_11['close_stage']['min'] }} + | max: {{ moorelane_metrics_linux_24_11['close_stage']['max'] }} + | mean: {{ moorelane_metrics_linux_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ moorelane_metrics_linux_24_11['shut_down_hydra']['min'] }} + | max: {{ moorelane_metrics_linux_24_11['shut_down_hydra']['max'] }} + | mean: {{ moorelane_metrics_linux_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set moorelane_metrics_macos_24_11 = load('performance/24.11_macos_moorelane.yaml', data_format='yaml') %} + +.. list-table:: macOS Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ moorelane_metrics_macos_24_11['open_stage']['min'] }} + | max: {{ moorelane_metrics_macos_24_11['open_stage']['max'] }} + | mean: {{ moorelane_metrics_macos_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ moorelane_metrics_macos_24_11['create_first_image']['min'] }} + | max: {{ moorelane_metrics_macos_24_11['create_first_image']['max'] }} + | mean: {{ moorelane_metrics_macos_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ moorelane_metrics_macos_24_11['close_stage']['min'] }} + | max: {{ moorelane_metrics_macos_24_11['close_stage']['max'] }} + | mean: {{ moorelane_metrics_macos_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ moorelane_metrics_macos_24_11['shut_down_hydra']['min'] }} + | max: {{ moorelane_metrics_macos_24_11['shut_down_hydra']['max'] }} + | mean: {{ moorelane_metrics_macos_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set moorelane_metrics_win_24_11 = load('performance/24.11_windows_moorelane.yaml', data_format='yaml') %} + +.. list-table:: Windows Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ moorelane_metrics_win_24_11['open_stage']['min'] }} + | max: {{ moorelane_metrics_win_24_11['open_stage']['max'] }} + | mean: {{ moorelane_metrics_win_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ moorelane_metrics_win_24_11['create_first_image']['min'] }} + | max: {{ moorelane_metrics_win_24_11['create_first_image']['max'] }} + | mean: {{ moorelane_metrics_win_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ moorelane_metrics_win_24_11['close_stage']['min'] }} + | max: {{ moorelane_metrics_win_24_11['close_stage']['max'] }} + | mean: {{ moorelane_metrics_win_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ moorelane_metrics_win_24_11['shut_down_hydra']['min'] }} + | max: {{ moorelane_metrics_win_24_11['shut_down_hydra']['max'] }} + | mean: {{ moorelane_metrics_win_24_11['shut_down_hydra']['mean']}} + - TBD diff --git a/docs/_templates/perf_metric_shaderball_template.tmpl b/docs/_templates/perf_metric_shaderball_template.tmpl new file mode 100644 index 0000000000..d77228fed4 --- /dev/null +++ b/docs/_templates/perf_metric_shaderball_template.tmpl @@ -0,0 +1,86 @@ +{% set shaderball_metrics_linux_24_11 = load('performance/24.11_linux_shaderball.yaml', data_format='yaml') %} + +.. list-table:: Linux Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ shaderball_metrics_linux_24_11['open_stage']['min'] }} + | max: {{ shaderball_metrics_linux_24_11['open_stage']['max'] }} + | mean: {{ shaderball_metrics_linux_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ shaderball_metrics_linux_24_11['create_first_image']['min'] }} + | max: {{ shaderball_metrics_linux_24_11['create_first_image']['max'] }} + | mean: {{ shaderball_metrics_linux_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ shaderball_metrics_linux_24_11['close_stage']['min'] }} + | max: {{ shaderball_metrics_linux_24_11['close_stage']['max'] }} + | mean: {{ shaderball_metrics_linux_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ shaderball_metrics_linux_24_11['shut_down_hydra']['min'] }} + | max: {{ shaderball_metrics_linux_24_11['shut_down_hydra']['max'] }} + | mean: {{ shaderball_metrics_linux_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set shaderball_metrics_macos_24_11 = load('performance/24.11_macos_shaderball.yaml', data_format='yaml') %} + +.. list-table:: macOS Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ shaderball_metrics_macos_24_11['open_stage']['min'] }} + | max: {{ shaderball_metrics_macos_24_11['open_stage']['max'] }} + | mean: {{ shaderball_metrics_macos_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ shaderball_metrics_macos_24_11['create_first_image']['min'] }} + | max: {{ shaderball_metrics_macos_24_11['create_first_image']['max'] }} + | mean: {{ shaderball_metrics_macos_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ shaderball_metrics_macos_24_11['close_stage']['min'] }} + | max: {{ shaderball_metrics_macos_24_11['close_stage']['max'] }} + | mean: {{ shaderball_metrics_macos_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ shaderball_metrics_macos_24_11['shut_down_hydra']['min'] }} + | max: {{ shaderball_metrics_macos_24_11['shut_down_hydra']['max'] }} + | mean: {{ shaderball_metrics_macos_24_11['shut_down_hydra']['mean']}} + - TBD + +{% set shaderball_metrics_win_24_11 = load('performance/24.11_windows_shaderball.yaml', data_format='yaml') %} + +.. list-table:: Windows Metrics (min/max/mean in seconds) + :header-rows: 1 + + * - Metric + - 24.11 + - 25.02 + * - Open stage + - | min: {{ shaderball_metrics_win_24_11['open_stage']['min'] }} + | max: {{ shaderball_metrics_win_24_11['open_stage']['max'] }} + | mean: {{ shaderball_metrics_win_24_11['open_stage']['mean']}} + - TBD + * - Render first image + - | min: {{ shaderball_metrics_win_24_11['create_first_image']['min'] }} + | max: {{ shaderball_metrics_win_24_11['create_first_image']['max'] }} + | mean: {{ shaderball_metrics_win_24_11['create_first_image']['mean']}} + - TBD + * - Close stage + - | min: {{ shaderball_metrics_win_24_11['close_stage']['min'] }} + | max: {{ shaderball_metrics_win_24_11['close_stage']['max'] }} + | mean: {{ shaderball_metrics_win_24_11['close_stage']['mean']}} + - TBD + * - Shut down Hydra + - | min: {{ shaderball_metrics_win_24_11['shut_down_hydra']['min'] }} + | max: {{ shaderball_metrics_win_24_11['shut_down_hydra']['max'] }} + | mean: {{ shaderball_metrics_win_24_11['shut_down_hydra']['mean']}} + - TBD diff --git a/docs/conf.py b/docs/conf.py index e6511ffb70..cd62c20859 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -78,7 +78,8 @@ def GetSphinxLogger(): 'sphinx.ext.autosectionlabel', 'sphinxcontrib.doxylink', 'sphinx_panels', - 'myst_parser' + 'myst_parser', + 'sphinxcontrib.datatemplates' ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/contributing_to_usd.rst b/docs/contributing_to_usd.rst index 98bf013555..5d96be6114 100644 --- a/docs/contributing_to_usd.rst +++ b/docs/contributing_to_usd.rst @@ -7,6 +7,9 @@ Contributing to USD **We're excited to collaborate with the community and look forward to the many improvements you can make to USD!** +.. _contributor_license_agreement: + +***************************** Contributor License Agreement ***************************** @@ -24,47 +27,68 @@ CLAs: : please sign this one if you're an individual contributor Once your CLA is signed, send it to `usd-cla@pixar.com -`_ (please make sure to include your github username) -and wait for confirmation that we've received it. After that, you can submit -pull requests. +`__. **Please make sure to include your GitHub username** +so we can grant your GitHub account appropriate permissions to the OpenUSD repo. + +You can start to make code contributions once you’ve received confirmation that +we've received your CLA. If you are planning on making a major change (for +example, adding a new feature, or making a code change that modifies dozens of +lines of code across several different files), see +:ref:`planning_major_changes` for recommended next steps. Otherwise, for +smaller changes, such as bugfixes, you can submit GitHub pull requests for +consideration, using the +:ref:`pull request guidelines`. +.. _coding_conventions: + +****************** Coding Conventions ****************** -Please follow the coding convention and style in each file and in each library -when adding new files. +Please review the coding conventions described in the +`Coding Guidelines `__ and +`Testing Guidelines `__ and follow the +coding conventions and styles in each file and library when making changes. + +.. _pull_request_guidelines: +*********************** Pull Request Guidelines *********************** - * All development on USD should happen against the "**dev**" branch of the + * All development should happen against the "**dev**" branch of the repository. Please make sure the base branch of your pull request is set to the "**dev**" branch when filing your pull request. - * Please make sure all tests are passing with your change prior to - submitting a pull request. Keep in mind the current github CI pipeline - does not run any tests, however tests will be run when reviewing your - submitted change for consideration. + * Please make pull requests that are small and atomic. In general, it is + easier for us to merge pull requests that serve a single + purpose than those that combine several functional pieces. * Please make sure that your pull requests are clean. Use the rebase and squash git facilities as needed to ensure that the pull request is as clean as possible. - * Please make pull requests that are small and atomic. In general, it is - easier for us to merge pull requests that serve a single - purpose than those that combine several functional pieces. + * Please make sure all tests are passing with your change prior to + submitting a pull request. Keep in mind the current GitHub CI pipeline + does not run any tests, however tests will be run when reviewing your + submitted change for consideration. + + * Please search through + `existing open GitHub issues `__ + and associate your PR with issues that your change addresses. If there are + no issues related to your change, you do not need to create a new issue. + However, if your change requires multiple pull requests, it can be helpful + to create a single issue to link together and organize related PRs. - * Please search through existing open github issues and associate your PR - with issues that your change addresses, as described in :ref:`github_issues`. - If there are no issues related to your change, you do not need to create - a new issue. +.. _git_workflow: +************ Git Workflow ************ -Here is the workflow we recommend for contributing changes to USD: +Here is the workflow we recommend for contributing changes to OpenUSD: - #. Use the github website to fork your own private repository. + #. Use the GitHub website to fork your own private repository. .. | space | @@ -76,7 +100,7 @@ Here is the workflow we recommend for contributing changes to USD: - #. Add Pixar's USD repo as upstream to make it easier to update your remote + #. Add Pixar's OpenUSD repo as upstream to make it easier to update your remote and local repos with the latest changes: .. code-block:: sh @@ -86,7 +110,7 @@ Here is the workflow we recommend for contributing changes to USD: - #. Now fetch the latest changes from Pixar's USD repo like this: + #. Now fetch the latest changes from Pixar's OpenUSD repo like this: .. code-block:: sh @@ -105,7 +129,7 @@ Here is the workflow we recommend for contributing changes to USD: - #. Now you can work in your branch locally. Please review the USD + #. Now you can work in your branch locally. Please review the `Coding Guidelines `__ and `Testing Guidelines `__ when making code changes. @@ -131,25 +155,135 @@ Here is the workflow we recommend for contributing changes to USD: #. Now your remote branch will have your dev_mybugfix branch, which you can - now pull request (to USD's dev branch) using the github UI. + now pull request (to OpenUSD's dev branch) using the GitHub UI. When your pull request is merged, it will be available in the next dev and full -release. For USD release schedules, see :ref:`release_schedule` +release. For OpenUSD release schedules, see :ref:`release_schedule`. .. _github_issues: -Github Issues -############# - -Use github issues to report problems or suggestions that need discussion, or -that you might not be able to address yourself. - -You do not need to log an issue for contributing changes, or if your change -fixes an unreported issue. However, if your change requires multiple pull -requests, a single issue can be created and referenced from those PRs to -organize them. - -Before sending your change in for consideration, search through the list of -`open issues on github `_ -and check if your change addresses any issue. If so, associate your pull -request with that issue. +GitHub Issues +============= + +Use GitHub issues to report problems or suggestions that need discussion, or +that you might not be able to address yourself. Please check that your issue +does not already exist in the list of +`open issues on GitHub `__ +before submitting to avoid duplicates. + +When new issues are filed in GitHub, Pixar makes a copy in our internal issue +tracker. When "Filed as internal issue USD-XXXX" is added to an issue, this is +an automated acknowledgment that the issue has been captured in our tracker and +will be triaged for review. It does not mean work has started on the issue yet. +Some GitHub issues may be tagged with labels following triage to invite +contributions from the community. See the definitions of each label in GitHub +`here `__. + +.. _planning_major_changes: + +******************** +Making Major Changes +******************** + +Please communicate your intent to make major changes with Pixar before starting +work, to ensure your changes align with the OpenUSD strategy and reduce rework +later. Below is the recommended workflow, with each step described in more detail +afterwards. + +.. image:: contributing_workflow_diagram.svg + +Step 1. Get consensus for major changes +======================================= + +If you would like to propose a major change that is not an architectural change, +please give us a heads up by finding and commenting on the existing +:ref:`GitHub issue ` that represents the problem, or creating a +new one if an appropriate issue doesn't already exist. Please briefly explain +your high-level approach so the community and Pixar engineers can comment if +there is already related work in progress or if the approach raises any concerns. + +If you are proposing architectural changes such as schema changes/additions, +major C++ API changes/additions, or new build dependencies for OpenUSD, we +recommend writing and posting a proposal to build consensus with the broader +OpenUSD community. Proposals should be posted in the +`OpenUSD-proposals GitHub repo `__. +See the `repo README `__ +for more details on the OpenUSD proposals process. + +Proposals are often brought up and discussed in +`ASWF USD Working Group meetings `__, +which are typically held on Zoom every other Wednesday at 1pm PST. + +Proposals are ready to move forward when they've moved to the +`Published `__ +phase. + +Step 2. Make code changes +========================= + +Make code changes using the :ref:`git workflow ` described +above, following the `Coding Guidelines `__. + +Don't forget to +`add API and user documentation `__ +as needed. + +Where possible, break up your changes into smaller commits that are +functionally complete. This makes it easier for Pixar to review and, if +necessary, to troubleshoot any regressions, when you submit your changes for +review (Step 4 below). See +`Make Small Atomic Changes `__ +for some approaches on splitting changes into separate commits. + +Step 3. Test code changes +========================= + +Test your code changes, following the +`Testing Guidelines `__ as needed. +With major changes, make sure to extend existing test coverage or provide new +tests for any added functionality. + +Step 4. Submit code for review +============================== + +Once your code is ready for review, submit a GitHub PR using the +:ref:`pull request guidelines `. + +For your PR description, begin with a brief summary of the change in 50 +characters or less, followed by a blank line and then a more detailed +description of the change. Some questions to consider when drafting your +description: + +* How did this behave prior to your change? +* How was that behavior problematic? +* How does your change modify the behavior? +* What are the benefits of the modified behavior? +* Are there direct impacts to users? +* Are there follow up changes or asset changes required? + +Be clear and concise. Include related PRs and issue identifiers, if +applicable. **Please keep PR descriptions up-to-date with any code iterations.** + +Pixar will do a code review of your pull request. Use GitHub PR review comments +to discuss and review suggestions and questions that come up during the code +review. Any code review comments will need to be either addressed or further +discussed before the change can be merged. If reviewers use +`GitHub suggested changes `__, +you can use the web UI to automatically apply those changes if you agree with +the suggestion. + +Code submitted for review is expected to be buildable and testable. There may be +exceptions if you're actively engaged in discussions with a Pixar engineer about +specific parts of code. + +Step 5. Pixar will test and land your changes +============================================= + +GitHub PRs are not landed directly into the GitHub dev branch, but rather into +Pixar's internal development tree. We do this to facilitate the automated +correctness and performance testing using production assets prior to merging the +change. The open source branch is then extracted from Pixar's internal +development tree and pushed to the OpenUSD GitHub **dev** branch on a +:ref:`regular cadence `. Once your PR has been incorporated +internally and the OpenUSD repo dev branch has been updated, Pixar will +automatically close your PR. \ No newline at end of file diff --git a/docs/contributing_workflow_diagram.svg b/docs/contributing_workflow_diagram.svg new file mode 100644 index 0000000000..215db5c680 --- /dev/null +++ b/docs/contributing_workflow_diagram.svg @@ -0,0 +1,4 @@ + + + +
Start
Start
Yes
Yes
No
No
Consensus on 
proposed work?
Consensus on...
Continue discussing
Continue discus...
Yes
Yes
No
No

Did the tests pass?

Did the tests pass...
Consult as needed
Consult...
Test code
Test code
Write code & draft documentation
Write code & draft d...
Submit for code review
Submit for code re...
No
No
Yes
Yes
Are there comments to address?
Are there comment...
Pixar runs internal tests
Pixar runs interna...
Yes
Yes
No
No
Code lands in GitHub dev branch
Code lands in GitH...
Finish
Finish
1
1
2
2
3
3
4
4
5
5

Did the tests pass?

Did the tests pass...Text is not SVG - cannot display \ No newline at end of file diff --git a/docs/dl_downloads.rst b/docs/dl_downloads.rst index 26ce384d47..948b0470d6 100644 --- a/docs/dl_downloads.rst +++ b/docs/dl_downloads.rst @@ -4,6 +4,11 @@ Downloads and Videos ==================== +SIGGRAPH 2024 Notes +=================== + +| `SIGGRAPH 2024 USD, Hydra, and OpenSubdiv Birds of a Feather Notes `__ + SIGGRAPH 2023 Notes =================== diff --git a/docs/doxygen/Doxyfile.in b/docs/doxygen/Doxyfile.in index d8c444a718..26767ecd16 100644 --- a/docs/doxygen/Doxyfile.in +++ b/docs/doxygen/Doxyfile.in @@ -1,4 +1,4 @@ -# Doxyfile 1.8.6 +# Doxyfile 1.9.6 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -12,6 +12,16 @@ # For lists, items can also be appended using: # TAG += value [value, ...] # Values that contain spaces should be placed between quotes (\" \"). +# +# Note: +# +# Use doxygen to compare the used configuration file with the template +# configuration file: +# doxygen -x [configFile] +# Use doxygen to compare the used configuration file with the template +# configuration file without replacing the environment variables or CMake type +# replacement variables: +# doxygen -x_noenv [configFile] #--------------------------------------------------------------------------- # Project related configuration options @@ -71,6 +81,25 @@ OUTPUT_DIRECTORY = CREATE_SUBDIRS = NO +# Controls the number of sub-directories that will be created when +# CREATE_SUBDIRS tag is set to YES. Level 0 represents 16 directories, and every +# level increment doubles the number of directories, resulting in 4096 +# directories at level 8 which is the default and also the maximum value. The +# sub-directories are organized in 2 levels, the first level always has a fixed +# number of 16 directories. +# Minimum value: 0, maximum value: 8, default value: 8. +# This tag requires that the tag CREATE_SUBDIRS is set to YES. + +CREATE_SUBDIRS_LEVEL = 8 + +# If the ALLOW_UNICODE_NAMES tag is set to YES, doxygen will allow non-ASCII +# characters to appear in the names of generated files. If set to NO, non-ASCII +# characters will be escaped, for example _xE3_x81_x84 will be used for Unicode +# U+3044. +# The default value is: NO. + +ALLOW_UNICODE_NAMES = NO + # The OUTPUT_LANGUAGE tag is used to specify the language in which all # documentation generated by doxygen is written. Doxygen will use this # information to generate all constant output in the proper language. @@ -172,6 +201,16 @@ SHORT_NAMES = NO JAVADOC_AUTOBRIEF = YES +# If the JAVADOC_BANNER tag is set to YES then doxygen will interpret a line +# such as +# /*************** +# as being the beginning of a Javadoc-style comment "banner". If set to NO, the +# Javadoc-style will behave just like regular comments and it will not be +# interpreted by doxygen. +# The default value is: NO. + +JAVADOC_BANNER = NO + # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first # line (until the first dot) of a Qt-style comment as the brief description. If # set to NO, the Qt-style will behave just like regular Qt-style comments (thus @@ -192,6 +231,14 @@ QT_AUTOBRIEF = NO MULTILINE_CPP_IS_BRIEF = NO +# By default Python docstrings are displayed as preformatted text and doxygen's +# special commands cannot be used. By setting PYTHON_DOCSTRING to NO the +# doxygen's special commands can be used and the contents of the docstring +# documentation blocks is shown as doxygen documentation. +# The default value is: YES. + +PYTHON_DOCSTRING = YES + # If the INHERIT_DOCS tag is set to YES then an undocumented member inherits the # documentation from any documented member that it re-implements. # The default value is: YES. @@ -227,12 +274,6 @@ ALIASES = "scriptableClass=\todo" \ "scriptableEnum=" \ "factoryFunc=" -# This tag can be used to specify a number of word-keyword mappings (TCL only). -# A mapping has the form "name=value". For example adding "class=itcl::class" -# will allow you to use the command class in the itcl::class meaning. - -TCL_SUBST = - # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources # only. Doxygen will then generate output that is more tailored for C. For # instance, some of the names that are used will be different. The list of all @@ -261,6 +302,14 @@ OPTIMIZE_FOR_FORTRAN = NO OPTIMIZE_OUTPUT_VHDL = NO +# Set the OPTIMIZE_OUTPUT_SLICE tag to YES if your project consists of Slice +# sources only. Doxygen will then generate output that is more tailored for that +# language. For instance, namespaces will be presented as modules, types will be +# separated into more groups, etc. +# The default value is: NO. + +OPTIMIZE_OUTPUT_SLICE = NO + # Doxygen selects the parser to use depending on the extension of the files it # parses. With this tag you can assign which parser to use for a given # extension. Doxygen has a built-in mapping, but you can override or extend it @@ -287,6 +336,15 @@ EXTENSION_MAPPING = h=C++ MARKDOWN_SUPPORT = YES +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 5. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 5 + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can # be prevented in individual cases by by putting a % sign in front of the word @@ -337,14 +395,21 @@ IDL_PROPERTY_SUPPORT = YES DISTRIBUTE_GROUP_DOC = NO +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent # subgrouping. Alternatively, this can be done per class using the # \nosubgrouping command. # The default value is: YES. -SUBGROUPING = YES +SUBGROUPING = YES # When the INLINE_GROUPED_CLASSES tag is set to YES, classes, structs and unions # are shown inside the group in which they are included (e.g. using \ingroup) @@ -391,6 +456,19 @@ TYPEDEF_HIDES_STRUCT = NO LOOKUP_CACHE_SIZE = 3 +# The NUM_PROC_THREADS specifies the number of threads doxygen is allowed to use +# during processing. When set to 0 doxygen will based this on the number of +# cores available in the system. You can set it explicitly to a value larger +# than 0 to get more control over the balance between CPU load and processing +# speed. At this moment only the input processing can be done using multiple +# threads. Since this is still an experimental feature the default is set to 1, +# which effectively disables parallel processing. Please report any issues you +# encounter. Generating dot graphs in parallel is controlled by the +# DOT_NUM_THREADS setting. +# Minimum value: 0, maximum value: 32, default value: 1. + +NUM_PROC_THREADS = 1 + #--------------------------------------------------------------------------- # Build related configuration options #--------------------------------------------------------------------------- @@ -411,6 +489,12 @@ EXTRACT_ALL = NO EXTRACT_PRIVATE = NO +# If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual +# methods of a class will be included in the documentation. +# The default value is: NO. + +EXTRACT_PRIV_VIRTUAL = NO + # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal # scope will be included in the documentation. # The default value is: NO. @@ -448,6 +532,13 @@ EXTRACT_LOCAL_METHODS = NO EXTRACT_ANON_NSPACES = NO +# If this flag is set to YES, the name of an unnamed parameter in a declaration +# will be determined by the corresponding definition. By default unnamed +# parameters remain unnamed in the output. +# The default value is: YES. + +RESOLVE_UNNAMED_PARAMS = YES + # If the HIDE_UNDOC_MEMBERS tag is set to YES, doxygen will hide all # undocumented members inside documented classes or files. If set to NO these # members will be included in the various overviews, but no documentation @@ -461,15 +552,15 @@ HIDE_UNDOC_MEMBERS = NO # to NO these classes will be included in the various overviews. This option has # no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = YES +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # (class|struct|union) declarations. If set to NO these declarations will be # included in the documentation. # The default value is: NO. -HIDE_FRIEND_COMPOUNDS = NO +HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO these @@ -501,6 +592,19 @@ CASE_SENSE_NAMES = NO HIDE_SCOPE_NAMES = YES +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + +# If the SHOW_HEADERFILE tag is set to YES then the documentation for a class +# will show which file needs to be included to use the class. +# The default value is: YES. + +SHOW_HEADERFILE = YES + # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. @@ -714,6 +818,13 @@ WARN_IF_UNDOCUMENTED = NO WARN_IF_DOC_ERROR = NO +# If WARN_IF_INCOMPLETE_DOC is set to YES, doxygen will warn about incomplete +# function parameter documentation. If set to NO, doxygen will accept that some +# parameters have no documentation without warning. +# The default value is: YES. + +WARN_IF_INCOMPLETE_DOC = NO + # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return # value. If set to NO doxygen will only warn about wrong or incomplete parameter @@ -722,6 +833,23 @@ WARN_IF_DOC_ERROR = NO WARN_NO_PARAMDOC = NO +# If WARN_IF_UNDOC_ENUM_VAL option is set to YES, doxygen will warn about +# undocumented enumeration values. If set to NO, doxygen will accept +# undocumented enumeration values. If EXTRACT_ALL is set to YES then this flag +# will automatically be disabled. +# The default value is: NO. + +WARN_IF_UNDOC_ENUM_VAL = NO + +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS +# then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but +# at the end of the doxygen process doxygen will return with a non-zero status. +# Possible values are: NO, YES and FAIL_ON_WARNINGS. +# The default value is: NO. + +WARN_AS_ERROR = NO + # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated @@ -732,6 +860,16 @@ WARN_NO_PARAMDOC = NO WARN_FORMAT = "$file:$line: $text" +# In the $text part of the WARN_FORMAT command it is possible that a reference +# to a more specific place is given. To make it easier to jump to this place +# (outside of doxygen) the user can define a custom "cut" / "paste" string. +# Example: +# WARN_LINE_FORMAT = "'vi $file +$line'" +# See also: WARN_FORMAT +# The default value is: at line $line of file $file. + +WARN_LINE_FORMAT = "at line $line of file $file" + # The WARN_LOGFILE tag can be used to specify a file to which warning and error # messages should be written. If left blank the output is written to standard # error (stderr). @@ -774,6 +912,16 @@ INPUT = docs/doxygen/externalOverview.dox \ INPUT_ENCODING = UTF-8 +# This tag can be used to specify the character encoding of the source files +# that doxygen parses The INPUT_FILE_ENCODING tag can be used to specify +# character encoding on a per file pattern basis. Doxygen will compare the file +# name with each pattern and apply the encoding instead of the default +# INPUT_ENCODING) if there is a match. The character encodings are a list of the +# form: pattern=encoding (like *.php=ISO-8859-1). See cfg_input_encoding +# "INPUT_ENCODING" for further information on supported encodings. + +INPUT_FILE_ENCODING = + # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank the @@ -1018,6 +1166,46 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the +# clang parser (see: +# http://clang.llvm.org/) for more accurate parsing at the cost of reduced +# performance. This can be particularly helpful with template rich C++ code for +# which doxygen's built-in parser lacks the necessary type information. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. +# The default value is: NO. + +CLANG_ASSISTED_PARSING = NO + +# If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS +# tag is set to YES then doxygen will add the directory of each input to the +# include path. +# The default value is: YES. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_ADD_INC_PATHS = YES + +# If clang assisted parsing is enabled you can provide the compiler with command +# line options that you would normally use when invoking the compiler. Note that +# the include paths will already be set by doxygen for the files and directories +# specified with INPUT and INCLUDE_PATH. +# This tag requires that the tag CLANG_ASSISTED_PARSING is set to YES. + +CLANG_OPTIONS = + +# If clang assisted parsing is enabled you can provide the clang parser with the +# path to the directory containing a file called compile_commands.json. This +# file is the compilation database (see: +# http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html) containing the +# options used when the source files were built. This is equivalent to +# specifying the -p option to a clang tool, such as clang-check. These options +# will then be passed to the parser. Any options specified with CLANG_OPTIONS +# will be added as well. +# Note: The availability of this option depends on whether or not doxygen was +# generated with the -Duse_libclang=ON option for CMake. + +CLANG_DATABASE_PATH = + #--------------------------------------------------------------------------- # Configuration options related to the alphabetical class index #--------------------------------------------------------------------------- @@ -1029,13 +1217,6 @@ VERBATIM_HEADERS = YES ALPHABETICAL_INDEX = YES -# The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in -# which the alphabetical index list will be split. -# Minimum value: 1, maximum value: 20, default value: 5. -# This tag requires that the tag ALPHABETICAL_INDEX is set to YES. - -COLS_IN_ALPHA_INDEX = 5 - # In case all classes in a project start with a common prefix, all classes will # be put under the same header in the alphabetical index. The IGNORE_PREFIX tag # can be used to specify a prefix (or a list of prefixes) that should be ignored @@ -1118,7 +1299,7 @@ HTML_STYLESHEET = # Doxygen will copy the style sheet file to the output directory. For an example # see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. -# !!NOTE: We override HTML_EXTRA_STYLESHEET in the doxygen awesome settings below +# NOTE: We override HTML_EXTRA_STYLESHEET in the Doxygen Awesome settings below # HTML_EXTRA_STYLESHEET = docs/doxygen/usd_style.css @@ -1129,10 +1310,23 @@ HTML_STYLESHEET = # files. In the HTML_STYLESHEET file, use the file name only. Also note that the # files will be copied as-is; there are no commands or markers available. # This tag requires that the tag GENERATE_HTML is set to YES. -# NOTE: See also Doxygen Awesome additions below +# NOTE: We also override HTML_EXTRA_FILES in Doxygen Awesome additions below HTML_EXTRA_FILES = +# The HTML_COLORSTYLE tag can be used to specify if the generated HTML output +# should be rendered with a dark or light theme. +# Possible values are: LIGHT always generate light mode output, DARK always +# generate dark mode output, AUTO_LIGHT automatically set the mode according to +# the user preference, use light mode if no preference is set (the default), +# AUTO_DARK automatically set the mode according to the user preference, use +# dark mode if no preference is set and TOGGLE allow to user to switch between +# light and dark mode via a button. +# The default value is: AUTO_LIGHT. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_COLORSTYLE = LIGHT + # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen # will adjust the colors in the stylesheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see @@ -1171,6 +1365,17 @@ HTML_COLORSTYLE_GAMMA = 80 HTML_TIMESTAMP = YES +# If the HTML_DYNAMIC_MENUS tag is set to YES then the generated HTML +# documentation will contain a main index with vertical navigation menus that +# are dynamically created via JavaScript. If disabled, the navigation index will +# consists of multiple levels of tabs that are statically embedded in every HTML +# page. Disable this option to support browsers that do not have JavaScript, +# like the Qt help browser. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_DYNAMIC_MENUS = YES + # If the HTML_DYNAMIC_SECTIONS tag is set to YES then the generated HTML # documentation will contain sections that can be hidden and shown after the # page has loaded. @@ -1214,6 +1419,13 @@ GENERATE_DOCSET = NO DOCSET_FEEDNAME = "Doxygen generated docs" +# This tag determines the URL of the docset feed. A documentation feed provides +# an umbrella under which multiple documentation sets from a single provider +# (such as a company or product suite) can be grouped. +# This tag requires that the tag GENERATE_DOCSET is set to YES. + +DOCSET_FEEDURL = + # This tag specifies a string that should uniquely identify the documentation # set bundle. This should be a reverse domain-name style string, e.g. # com.mycompany.MyDocSet. Doxygen will append .docset to the name. @@ -1234,7 +1446,7 @@ DOCSET_PUBLISHER_ID = org.doxygen.Publisher # The default value is: Publisher. # This tag requires that the tag GENERATE_DOCSET is set to YES. -DOCSET_PUBLISHER_NAME = Pixar Animation Studios +DOCSET_PUBLISHER_NAME = "Pixar Animation Studios" # If the GENERATE_HTMLHELP tag is set to YES then doxygen generates three # additional HTML index files: index.hhp, index.hhc, and index.hhk. The @@ -1407,6 +1619,18 @@ DISABLE_INDEX = NO GENERATE_TREEVIEW = YES +# When both GENERATE_TREEVIEW and DISABLE_INDEX are set to YES, then the +# FULL_SIDEBAR option determines if the side bar is limited to only the treeview +# area (value NO) or if it should extend to the full height of the window (value +# YES). Setting this to YES gives a layout similar to +# https://docs.readthedocs.io with more room for contents, but less room for the +# project logo, title, and description. If either GENERATE_TREEVIEW or +# DISABLE_INDEX is set to NO, this option has no effect. +# The default value is: NO. +# This tag requires that the tag GENERATE_HTML is set to YES. + +FULL_SIDEBAR = NO + # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that # doxygen will group on one line in the generated HTML documentation. # @@ -1431,6 +1655,24 @@ TREEVIEW_WIDTH = 250 EXT_LINKS_IN_WINDOW = NO +# If the OBFUSCATE_EMAILS tag is set to YES, doxygen will obfuscate email +# addresses. +# The default value is: YES. +# This tag requires that the tag GENERATE_HTML is set to YES. + +OBFUSCATE_EMAILS = YES + +# If the HTML_FORMULA_FORMAT option is set to svg, doxygen will use the pdf2svg +# tool (see https://github.com/dawbarton/pdf2svg) or inkscape (see +# https://inkscape.org) to generate formulas as SVG images instead of PNGs for +# the HTML output. These images will generally look nicer at scaled resolutions. +# Possible values are: png (the default) and svg (looks nicer but requires the +# pdf2svg or inkscape tool). +# The default value is: png. +# This tag requires that the tag GENERATE_HTML is set to YES. + +HTML_FORMULA_FORMAT = png + # Use this tag to change the font size of LaTeX formulas included as images in # the HTML documentation. When you change the font size after a successful # doxygen run you need to manually remove any form_*.png images from the HTML @@ -1440,16 +1682,11 @@ EXT_LINKS_IN_WINDOW = NO FORMULA_FONTSIZE = 10 -# Use the FORMULA_TRANPARENT tag to determine whether or not the images -# generated for formulas are transparent PNGs. Transparent PNGs are not -# supported properly for IE 6.0, but are supported on all modern browsers. -# -# Note that when changing this option you need to delete any form_*.png files in -# the HTML output directory before the changes have effect. -# The default value is: YES. -# This tag requires that the tag GENERATE_HTML is set to YES. +# The FORMULA_MACROFILE can contain LaTeX \newcommand and \renewcommand commands +# to create new LaTeX commands to be used in formulas as building blocks. See +# the section "Including formulas" for details. -FORMULA_TRANSPARENT = YES +FORMULA_MACROFILE = # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering @@ -1462,6 +1699,17 @@ FORMULA_TRANSPARENT = YES USE_MATHJAX = NO +# With MATHJAX_VERSION it is possible to specify the MathJax version to be used. +# Note that the different versions of MathJax have different requirements with +# regards to the different settings, so it is possible that also other MathJax +# settings have to be changed when switching between the different MathJax +# versions. +# Possible values are: MathJax_2 and MathJax_3. +# The default value is: MathJax_2. +# This tag requires that the tag USE_MATHJAX is set to YES. + +MATHJAX_VERSION = MathJax_2 + # When MathJax is enabled you can set the default output format to be used for # the MathJax output. See the MathJax site (see: # http://docs.mathjax.org/en/latest/output.html) for more details. @@ -1713,16 +1961,6 @@ LATEX_BATCHMODE = NO LATEX_HIDE_INDICES = NO -# If the LATEX_SOURCE_CODE tag is set to YES then doxygen will include source -# code with syntax highlighting in the LaTeX output. -# -# Note that which sources are shown also depends on other settings such as -# SOURCE_BROWSER. -# The default value is: NO. -# This tag requires that the tag GENERATE_LATEX is set to YES. - -LATEX_SOURCE_CODE = NO - # The LATEX_BIB_STYLE tag can be used to specify the style to use for the # bibliography, e.g. plainnat, or ieeetr. See # http://en.wikipedia.org/wiki/BibTeX and \cite for more info. @@ -1851,6 +2089,13 @@ XML_OUTPUT = docs/doxy_xml XML_PROGRAMLISTING = YES +# If the XML_NS_MEMB_FILE_SCOPE tag is set to YES, doxygen will include +# namespace members in file scope as well, matching the HTML output. +# The default value is: NO. +# This tag requires that the tag GENERATE_XML is set to YES. + +XML_NS_MEMB_FILE_SCOPE = NO + #--------------------------------------------------------------------------- # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- @@ -2047,34 +2292,10 @@ EXTERNAL_GROUPS = NO EXTERNAL_PAGES = NO -# The PERL_PATH should be the absolute path and name of the perl script -# interpreter (i.e. the result of 'which perl'). -# The default file (with absolute path) is: /usr/bin/perl. - -PERL_PATH = /usr/bin/perl - #--------------------------------------------------------------------------- # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram -# (in HTML and LaTeX) for classes with base or super classes. Setting the tag to -# NO turns the diagrams off. Note that this option also works with HAVE_DOT -# disabled, but it is recommended to install and use dot, since it yields more -# powerful graphs. -# The default value is: YES. - -CLASS_DIAGRAMS = YES - -# You can define message sequence charts within doxygen comments using the \msc -# command. Doxygen will then run the mscgen tool (see: -# http://www.mcternan.me.uk/mscgen/)) to produce the chart and insert it in the -# documentation. The MSCGEN_PATH tag allows you to specify the directory where -# the mscgen tool resides. If left empty the tool is assumed to be found in the -# default search path. - -MSCGEN_PATH = - # You can include diagrams made with dia in doxygen documentation. Doxygen will # then run dia to produce the diagram and insert it in the documentation. The # DIA_PATH tag allows you to specify the directory where the dia binary resides. @@ -2107,22 +2328,35 @@ HAVE_DOT = @DOXYGEN_GENERATE_HTML@ DOT_NUM_THREADS = 0 -# When you want a differently looking font n the dot files that doxygen -# generates you can specify the font name using DOT_FONTNAME. You need to make -# sure dot is able to find the font, which can be done by putting it in a -# standard location or by setting the DOTFONTPATH environment variable or by -# setting DOT_FONTPATH to the directory containing the font. -# The default value is: Helvetica. +# DOT_COMMON_ATTR is common attributes for nodes, edges and labels of +# subgraphs. When you want a differently looking font in the dot files that +# doxygen generates you can specify fontname, fontcolor and fontsize attributes. +# For details please see Node, +# Edge and Graph Attributes specification You need to make sure dot is able +# to find the font, which can be done by putting it in a standard location or by +# setting the DOTFONTPATH environment variable or by setting DOT_FONTPATH to the +# directory containing the font. Default graphviz fontsize is 14. +# The default value is: fontname=Helvetica,fontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTNAME = Helvetica +DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10" -# The DOT_FONTSIZE tag can be used to set the size (in points) of the font of -# dot graphs. -# Minimum value: 4, maximum value: 24, default value: 10. +# DOT_EDGE_ATTR is concatenated with DOT_COMMON_ATTR. For elegant style you can +# add 'arrowhead=open, arrowtail=open, arrowsize=0.5'. Complete documentation about +# arrows shapes. +# The default value is: labelfontname=Helvetica,labelfontsize=10. # This tag requires that the tag HAVE_DOT is set to YES. -DOT_FONTSIZE = 10 +DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10" + +# DOT_NODE_ATTR is concatenated with DOT_COMMON_ATTR. For view without boxes +# around nodes set 'shape=plain' or 'shape=plaintext' Shapes specification +# The default value is: shape=box,height=0.2,width=0.4. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4" # By default doxygen will tell dot to use the default font as specified with # DOT_FONTNAME. If you specify a different font using DOT_FONTNAME you can set @@ -2176,6 +2410,28 @@ UML_LOOK = NO UML_LIMIT_NUM_FIELDS = 10 +# If the DOT_UML_DETAILS tag is set to NO, doxygen will show attributes and +# methods without types and arguments in the UML graphs. If the DOT_UML_DETAILS +# tag is set to YES, doxygen will add type and arguments for attributes and +# methods in the UML graphs. If the DOT_UML_DETAILS tag is set to NONE, doxygen +# will not generate fields with class member information in the UML graphs. The +# class diagrams will look similar to the default class diagrams but using UML +# notation for the relationships. +# Possible values are: NO, YES and NONE. +# The default value is: NO. +# This tag requires that the tag UML_LOOK is set to YES. + +DOT_UML_DETAILS = NO + +# The DOT_WRAP_THRESHOLD tag can be used to set the maximum number of characters +# to display on a single line. If the actual line length exceeds this threshold +# significantly it will wrapped across multiple lines. Some heuristics are apply +# to avoid ugly line breaks. +# Minimum value: 0, maximum value: 1000, default value: 17. +# This tag requires that the tag HAVE_DOT is set to YES. + +DOT_WRAP_THRESHOLD = 17 + # If the TEMPLATE_RELATIONS tag is set to YES then the inheritance and # collaboration graphs will show the relations between templates and their # instances. @@ -2240,6 +2496,13 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES +# The DIR_GRAPH_MAX_DEPTH tag can be used to limit the maximum number of levels +# of child directories generated in directory dependency graphs by dot. +# Minimum value: 1, maximum value: 25, default value: 1. +# This tag requires that the tag DIRECTORY_GRAPH is set to YES. + +DIR_GRAPH_MAX_DEPTH = 1 + # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images # generated by dot. # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order @@ -2288,6 +2551,24 @@ MSCFILE_DIRS = DIAFILE_DIRS = +# When using plantuml, the PLANTUML_JAR_PATH tag should be used to specify the +# path where java can find the plantuml.jar file or to the filename of jar file +# to be used. If left blank, it is assumed PlantUML is not used or called during +# a preprocessing step. Doxygen will generate a warning when it encounters a +# \startuml command in this case and will not generate output for the diagram. + +PLANTUML_JAR_PATH = + +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, doxygen will truncate the graph, which is visualized @@ -2312,18 +2593,6 @@ DOT_GRAPH_MAX_NODES = 50 MAX_DOT_GRAPH_DEPTH = 0 -# Set the DOT_TRANSPARENT tag to YES to generate images with a transparent -# background. This is disabled by default, because dot on Windows does not seem -# to support this out of the box. -# -# Warning: Depending on the platform used, enabling this option may lead to -# badly anti-aliased labels on the edges of a graph (i.e. they become hard to -# read). -# The default value is: NO. -# This tag requires that the tag HAVE_DOT is set to YES. - -DOT_TRANSPARENT = YES - # Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support @@ -2348,15 +2617,10 @@ GENERATE_LEGEND = YES DOT_CLEANUP = YES -#CLANG_ASSISTED_PARSING = YES - # Setup for Doxygen Awesome CSS -FULL_SIDEBAR = NO HTML_EXTRA_STYLESHEET = docs/doxygen/doxygen-awesome-css/doxygen-awesome.css \ docs/doxygen/usd_style.css HTML_EXTRA_FILES = docs/doxygen/doxygen-awesome-css/doxygen-awesome-darkmode-toggle.js \ docs/doxygen/doxygen-awesome-css/doxygen-awesome-fragment-copy-button.js \ docs/doxygen/doxygen-awesome-css/doxygen-awesome-paragraph-link.js -# HTML_COLORSTYLE is a Doxygen 1.9.x config required for Doxygen Awesome -HTML_COLORSTYLE = LIGHT \ No newline at end of file diff --git a/docs/doxygen/externalOverview.dox b/docs/doxygen/externalOverview.dox index 3f410a5d85..d70985e248 100644 --- a/docs/doxygen/externalOverview.dox +++ b/docs/doxygen/externalOverview.dox @@ -105,7 +105,7 @@ Following is a deeper indexing of the four packages. - \ref tf_page_front module is a catch-all for low-level, commonly used services developed at Pixar, including facilities for memory - tracking, error reporting and debugging, string utilities, boost python + tracking, error reporting and debugging, string utilities, Python wrapping aids, threading/synchronization tools, registry and singleton management, smart pointers, and "observer pattern" support, which we call "notification". @@ -128,9 +128,8 @@ Following is a deeper indexing of the four packages. is able to recognize and serialize. It provides a copy-on-write array-type, VtArray, which is used for all array types in Usd, and an efficient type-erasure wrapper class, VtValue, that also provides datatype - conversion facilities and support for unboxing python objects from boost - python. VtValue is supported in all Usd API for getting and setting - values. + conversion facilities and support for unboxing Python objects. + VtValue is supported in all Usd API for getting and setting values. - \ref work_page_front module provides a thin abstraction layer on top of Intel's TBB (Thread Building Blocks), and is leveraged extensively in Usd diff --git a/docs/maxperf.rst b/docs/maxperf.rst index 4b6a08d162..230174bc06 100644 --- a/docs/maxperf.rst +++ b/docs/maxperf.rst @@ -10,6 +10,12 @@ pipeline. We would like to help ensure that USD works as well and with as good performance for you as it does for us. Here are a few tips that can make a huge difference. +.. note:: + + Starting with release 24.11, Pixar is publishing performance metrics + measured using several different assets. See :ref:`performance_metrics` for + details. + Use an allocator optimized for multithreading ############################################## diff --git a/docs/performance/24.11_linux_alab.yaml b/docs/performance/24.11_linux_alab.yaml new file mode 100644 index 0000000000..e663ce2e08 --- /dev/null +++ b/docs/performance/24.11_linux_alab.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.833684 + mean: 0.7791103 + min: 0.734001 +close_stage: + max: 0.090772 + mean: 0.0874594 + min: 0.084709 +configure_and_load_plugins: + max: 0.000148 + mean: 0.0001375 + min: 0.000131 +create_first_image: + max: 8.556198 + mean: 8.1684536 + min: 7.897517 +open_and_close_usdview: + max: 9.691212 + mean: 9.3458374 + min: 9.062105 +open_stage: + max: 0.516364 + mean: 0.4642872 + min: 0.39004 +reset_prim_browser: + max: 0.001795 + mean: 0.0017705 + min: 0.001751 +shut_down_hydra: + max: 0.165165 + mean: 0.1328269 + min: 0.12083 +tear_down_the_ui: + max: 0.038048 + mean: 0.032411 + min: 0.022262 +traverse_stage: + max: 0.007567 + mean: 0.007379999999999999 + min: 0.007251 diff --git a/docs/performance/24.11_linux_kitchenset.yaml b/docs/performance/24.11_linux_kitchenset.yaml new file mode 100644 index 0000000000..97ce174c34 --- /dev/null +++ b/docs/performance/24.11_linux_kitchenset.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.387106 + mean: 0.3487857 + min: 0.329509 +close_stage: + max: 0.007835 + mean: 0.0074928 + min: 0.007057 +configure_and_load_plugins: + max: 0.000144 + mean: 0.00013680000000000002 + min: 0.000129 +create_first_image: + max: 0.3028 + mean: 0.2903682 + min: 0.279229 +open_and_close_usdview: + max: 0.847958 + mean: 0.7911669 + min: 0.752613 +open_stage: + max: 0.107452 + mean: 0.0842476 + min: 0.069993 +reset_prim_browser: + max: 0.001205 + mean: 0.0011894 + min: 0.001163 +shut_down_hydra: + max: 0.009617 + mean: 0.0093791 + min: 0.009247 +tear_down_the_ui: + max: 0.009307 + mean: 0.0080869 + min: 0.006491 +traverse_stage: + max: 0.001312 + mean: 0.0012427 + min: 0.001213 diff --git a/docs/performance/24.11_linux_moorelane.yaml b/docs/performance/24.11_linux_moorelane.yaml new file mode 100644 index 0000000000..d8e463d34e --- /dev/null +++ b/docs/performance/24.11_linux_moorelane.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.617653 + mean: 0.603799 + min: 0.598502 +close_stage: + max: 0.02107 + mean: 0.0207992 + min: 0.020613 +configure_and_load_plugins: + max: 0.000177 + mean: 0.00014000000000000001 + min: 0.000131 +create_first_image: + max: 11.776089 + mean: 11.6368226 + min: 11.484618 +open_and_close_usdview: + max: 12.911434 + mean: 12.757864399999999 + min: 12.587016 +open_stage: + max: 0.094023 + mean: 0.0791025 + min: 0.075535 +reset_prim_browser: + max: 0.009577 + mean: 0.0094567 + min: 0.009369 +shut_down_hydra: + max: 0.138991 + mean: 0.1194904 + min: 0.103945 +tear_down_the_ui: + max: 0.117169 + mean: 0.113112 + min: 0.110088 +traverse_stage: + max: 0.001397 + mean: 0.0013728 + min: 0.001346 diff --git a/docs/performance/24.11_linux_shaderball.yaml b/docs/performance/24.11_linux_shaderball.yaml new file mode 100644 index 0000000000..bab10efdde --- /dev/null +++ b/docs/performance/24.11_linux_shaderball.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.43229 + mean: 0.4245096 + min: 0.419582 +close_stage: + max: 0.000754 + mean: 0.0006054 + min: 0.000499 +configure_and_load_plugins: + max: 0.000142 + mean: 0.0001347 + min: 0.000129 +create_first_image: + max: 2.904303 + mean: 2.8882178 + min: 2.870519 +open_and_close_usdview: + max: 3.479013 + mean: 3.464824 + min: 3.44698 +open_stage: + max: 0.150255 + mean: 0.1480813 + min: 0.144294 +reset_prim_browser: + max: 0.001618 + mean: 0.0015671 + min: 0.001534 +shut_down_hydra: + max: 0.022668 + mean: 0.0223569 + min: 0.022082 +tear_down_the_ui: + max: 0.011874 + mean: 0.0116779 + min: 0.011499 +traverse_stage: + max: 0.000408 + mean: 0.000371 + min: 0.000353 diff --git a/docs/performance/24.11_macos_alab.yaml b/docs/performance/24.11_macos_alab.yaml new file mode 100644 index 0000000000..379a2294c3 --- /dev/null +++ b/docs/performance/24.11_macos_alab.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.697076 + mean: 0.6728786999999999 + min: 0.659187 +close_stage: + max: 0.041104 + mean: 0.037702 + min: 0.034878 +configure_and_load_plugins: + max: 0.000113 + mean: 8.23e-05 + min: 7.6e-05 +create_first_image: + max: N/A + mean: N/A + min: N/A +open_and_close_usdview: + max: 5.956596 + mean: 5.824605200000001 + min: 5.66041 +open_stage: + max: 0.44761 + mean: 0.4308989 + min: 0.419115 +reset_prim_browser: + max: 0.00096 + mean: 0.0008801 + min: 0.000856 +shut_down_hydra: + max: 0.120492 + mean: 0.10805630000000001 + min: 0.100348 +tear_down_the_ui: + max: 0.01839 + mean: 0.0158125 + min: 0.013213 +traverse_stage: + max: 0.003488 + mean: 0.003359 + min: 0.003253 diff --git a/docs/performance/24.11_macos_kitchenset.yaml b/docs/performance/24.11_macos_kitchenset.yaml new file mode 100644 index 0000000000..48b059ae13 --- /dev/null +++ b/docs/performance/24.11_macos_kitchenset.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.330342 + mean: 0.2986121 + min: 0.285973 +close_stage: + max: 0.002519 + mean: 0.0023587 + min: 0.002246 +configure_and_load_plugins: + max: 0.000102 + mean: 8.19e-05 + min: 7.6e-05 +create_first_image: + max: N/A + mean: N/A + min: N/A +open_and_close_usdview: + max: 0.730075 + mean: 0.6935303 + min: 0.674505 +open_stage: + max: 0.09047 + mean: 0.0732717 + min: 0.06026 +reset_prim_browser: + max: 0.000624 + mean: 0.0005443 + min: 0.000491 +shut_down_hydra: + max: 0.013024 + mean: 0.0102488 + min: 0.006481 +tear_down_the_ui: + max: 0.015206 + mean: 0.0131009 + min: 0.01074 +traverse_stage: + max: 0.000696 + mean: 0.0005692 + min: 0.000534 diff --git a/docs/performance/24.11_macos_moorelane.yaml b/docs/performance/24.11_macos_moorelane.yaml new file mode 100644 index 0000000000..dac595425f --- /dev/null +++ b/docs/performance/24.11_macos_moorelane.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.47858 + mean: 0.4695382 + min: 0.45761 +close_stage: + max: 0.00522 + mean: 0.0036797 + min: 0.003298 +configure_and_load_plugins: + max: 7.9e-05 + mean: 7.47e-05 + min: 7.2e-05 +create_first_image: + max: N/A + mean: N/A + min: N/A +open_and_close_usdview: + max: 8.820797 + mean: 8.5296113 + min: 8.308413 +open_stage: + max: 0.086856 + mean: 0.0859231 + min: 0.085466 +reset_prim_browser: + max: 0.005902 + mean: 0.0055684 + min: 0.005406 +shut_down_hydra: + max: 0.28412 + mean: 0.2741197 + min: 0.222393 +tear_down_the_ui: + max: 0.045497 + mean: 0.0383143 + min: 0.035085 +traverse_stage: + max: 0.000605 + mean: 0.0005794 + min: 0.000564 diff --git a/docs/performance/24.11_macos_shaderball.yaml b/docs/performance/24.11_macos_shaderball.yaml new file mode 100644 index 0000000000..d39901392b --- /dev/null +++ b/docs/performance/24.11_macos_shaderball.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 0.343762 + mean: 0.3297607 + min: 0.317855 +close_stage: + max: 0.000296 + mean: 0.0002641 + min: 0.000241 +configure_and_load_plugins: + max: 9.8e-05 + mean: 8.26e-05 + min: 7.6e-05 +create_first_image: + max: N/A + mean: N/A + min: N/A +open_and_close_usdview: + max: 1.152715 + mean: 1.1196469 + min: 1.096133 +open_stage: + max: 0.098122 + mean: 0.0901067 + min: 0.088529 +reset_prim_browser: + max: 0.000821 + mean: 0.0006841 + min: 0.000646 +shut_down_hydra: + max: 0.014153 + mean: 0.0116556 + min: 0.009064 +tear_down_the_ui: + max: 0.016629 + mean: 0.014055 + min: 0.01147 +traverse_stage: + max: 0.000291 + mean: 0.0002508 + min: 0.000229 diff --git a/docs/performance/24.11_windows_alab.yaml b/docs/performance/24.11_windows_alab.yaml new file mode 100644 index 0000000000..165b55d245 --- /dev/null +++ b/docs/performance/24.11_windows_alab.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 4.316167 + mean: 4.2385264 + min: 4.20729 +close_stage: + max: 0.364083 + mean: 0.35308 + min: 0.337716 +configure_and_load_plugins: + max: 0.000995 + mean: 0.0009473 + min: 0.000878 +create_first_image: + max: 11.738015 + mean: 11.290158 + min: 11.070572 +open_and_close_usdview: + max: 17.118413 + mean: 16.5591656 + min: 16.291877 +open_stage: + max: 0.465223 + mean: 0.4604347 + min: 0.453708 +reset_prim_browser: + max: 0.004434 + mean: 0.0042978 + min: 0.004152 +shut_down_hydra: + max: 0.384717 + mean: 0.2734629 + min: 0.219807 +tear_down_the_ui: + max: 0.309065 + mean: 0.2477569 + min: 0.122124 +traverse_stage: + max: 0.009832 + mean: 0.0080616 + min: 0.007263 diff --git a/docs/performance/24.11_windows_kitchenset.yaml b/docs/performance/24.11_windows_kitchenset.yaml new file mode 100644 index 0000000000..80a34d5e87 --- /dev/null +++ b/docs/performance/24.11_windows_kitchenset.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 4.095108 + mean: 3.9744485999999997 + min: 3.868397 +close_stage: + max: 0.024004 + mean: 0.0215864 + min: 0.019616 +configure_and_load_plugins: + max: 0.001014 + mean: 0.0009288 + min: 0.000885 +create_first_image: + max: 3.086248 + mean: 2.9800833 + min: 2.862769 +open_and_close_usdview: + max: 7.451705 + mean: 7.1910904 + min: 6.959639 +open_stage: + max: 0.177268 + mean: 0.1491912 + min: 0.13587 +reset_prim_browser: + max: 0.006285 + mean: 0.0041532 + min: 0.003499 +shut_down_hydra: + max: 0.023532 + mean: 0.0217044 + min: 0.020476 +tear_down_the_ui: + max: 0.110098 + mean: 0.060470300000000005 + min: 0.050172 +traverse_stage: + max: 0.002 + mean: 0.0019016 + min: 0.001795 diff --git a/docs/performance/24.11_windows_moorelane.yaml b/docs/performance/24.11_windows_moorelane.yaml new file mode 100644 index 0000000000..3ca24a90d3 --- /dev/null +++ b/docs/performance/24.11_windows_moorelane.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: N/A + mean: N/A + min: N/A +close_stage: + max: N/A + mean: N/A + min: N/A +configure_and_load_plugins: + max: N/A + mean: N/A + min: N/A +create_first_image: + max: N/A + mean: N/A + min: N/A +open_and_close_usdview: + max: N/A + mean: N/A + min: N/A +open_stage: + max: N/A + mean: N/A + min: N/A +reset_prim_browser: + max: N/A + mean: N/A + min: N/A +shut_down_hydra: + max: N/A + mean: N/A + min: N/A +tear_down_the_ui: + max: N/A + mean: N/A + min: N/A +traverse_stage: + max: N/A + mean: N/A + min: N/A diff --git a/docs/performance/24.11_windows_shaderball.yaml b/docs/performance/24.11_windows_shaderball.yaml new file mode 100644 index 0000000000..fc6496fca1 --- /dev/null +++ b/docs/performance/24.11_windows_shaderball.yaml @@ -0,0 +1,40 @@ +bring_up_the_ui: + max: 4.444394 + mean: 4.0969829 + min: 4.007564 +close_stage: + max: 0.002616 + mean: 0.0017503 + min: 0.001371 +configure_and_load_plugins: + max: 0.00118 + mean: 0.0009801 + min: 0.00086 +create_first_image: + max: 4.963428 + mean: 4.7824023 + min: 4.546317 +open_and_close_usdview: + max: 9.518625 + mean: 9.09599 + min: 8.81436 +open_stage: + max: 0.320872 + mean: 0.2995894 + min: 0.284833 +reset_prim_browser: + max: 0.004614 + mean: 0.0041768 + min: 0.003919 +shut_down_hydra: + max: 0.04744 + mean: 0.0423858 + min: 0.040305 +tear_down_the_ui: + max: 0.057904 + mean: 0.0550358 + min: 0.050231 +traverse_stage: + max: 0.001217 + mean: 0.0011315 + min: 0.001047 diff --git a/docs/performance/linux.svg b/docs/performance/linux.svg new file mode 100644 index 0000000000..72324c5b8b --- /dev/null +++ b/docs/performance/linux.svg @@ -0,0 +1,1457 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/performance/macos.svg b/docs/performance/macos.svg new file mode 100644 index 0000000000..f338f5f484 --- /dev/null +++ b/docs/performance/macos.svg @@ -0,0 +1,1536 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/performance/windows.svg b/docs/performance/windows.svg new file mode 100644 index 0000000000..ae18c642e8 --- /dev/null +++ b/docs/performance/windows.svg @@ -0,0 +1,1396 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/python/genPerformancePlots.py b/docs/python/genPerformancePlots.py new file mode 100644 index 0000000000..a8e3f59160 --- /dev/null +++ b/docs/python/genPerformancePlots.py @@ -0,0 +1,116 @@ +# +# Copyright 2024 Pixar +# +# Licensed under the terms set forth in the LICENSE.txt file available at +# https://openusd.org/license. +# +""" +Generates multiline charts, one per platform, to display performance metrics +over releases on a fixed set of assets. Input yaml files must +have filenames matching the pattern __.yaml. +e.g. 24.11_linux_shaderball.yaml +""" +import argparse +import matplotlib.pyplot as plt +import os +import re +import yaml + + +# The naming scheme should be __.yaml +FILENAME_PATTERN = ("(?P\d\d\.\d\d)_" + "(?Plinux|windows|macos)_" + "(?P.*).yaml") + +# Currently we display only the open and close metric over time. +METRIC_ID = "open_and_close_usdview" + + +def collectData(dataDir: str): + yamls = [f for f in os.listdir(dataDir) if f.endswith(".yaml")] + + data = {"macos": {}, "windows": {}, "linux": {}} + for yamlname in yamls: + match = re.match(FILENAME_PATTERN, yamlname) + if match is None: + continue + + release = match["release"] + platform = match["platform"] + asset = match["asset"] + with open(os.path.join(dataDir, yamlname)) as f: + metrics = yaml.safe_load(f) + time = metrics[METRIC_ID]["min"] + if type(time) is not float: + continue + + if asset not in data[platform]: + data[platform][asset] = [] + + data[platform][asset].append((release, time)) + + return data + + +def exportCharts(data, outputDir: str): + markers = { + "alab": "d", + "kitchenset": "s", + "moorelane": "^", + "shaderball": "o" + } + for platform, platformData in data.items(): + fig, _ = plt.subplots() + plt.close(fig) + plt.close() + plt.cla() + plt.clf() + + for asset, assetData in platformData.items(): + releases = [d[0] for d in assetData] + times = [d[1] for d in assetData] + plt.plot(releases, times, label=asset, marker=markers[asset]) + + plt.title(f"{platform} time to open and close usdview", + fontweight="bold") + plt.xlabel("OpenUSD release") + plt.ylabel("Minimum duration of 10 iterations (seconds)") + plt.legend() + plt.savefig(os.path.join(outputDir, f"{platform}.svg")) + + +def parseArgs(): + usage = "Generate a plot to be used in public performance reports" + parser = argparse.ArgumentParser(description=usage) + parser.add_argument('metricsDirectory', + type=str, + help="The directory from which to read metric yaml " + "files. File names must have format " + "__.yaml where release " + "is in format yy.mm (e.g. 24.11), and platform " + "is one of [linux, windows, macos].") + parser.add_argument('outputDirectory', + type=str, + default=".", + help="The directory to write performance charts " + "out to.") + + args = parser.parse_args() + + if not os.path.isdir(args.metricsDirectory): + raise FileNotFoundError(f"Directory {args.metricsDirectory} not found") + + if not os.path.isdir(args.outputDirectory): + raise FileNotFoundError(f"Directory {args.outputDirectory} not found") + + return args + + +def main(): + args = parseArgs() + data = collectData(args.metricsDirectory) + exportCharts(data, args.outputDirectory) + + +if __name__ == "__main__": + main() diff --git a/docs/python/genToolsetDoc.py b/docs/python/genToolsetDoc.py index ce31e2a425..8a579a1cdc 100644 --- a/docs/python/genToolsetDoc.py +++ b/docs/python/genToolsetDoc.py @@ -39,7 +39,8 @@ ("usdstitchclips", "-h"), ("usddumpcrate", "-h"), ("sdfdump", "-h"), -("sdffilter", "-h") +("sdffilter", "-h"), +("usdmeasureperformance", "-h") ] #------------------------------------------------------------------------------# diff --git a/docs/ref_performance_metrics.rst b/docs/ref_performance_metrics.rst new file mode 100644 index 0000000000..d4b1ad055f --- /dev/null +++ b/docs/ref_performance_metrics.rst @@ -0,0 +1,255 @@ +.. include:: rolesAndUtils.rst + +.. _performance_metrics: + +################### +Performance Metrics +################### + +As of release 24.11, for each release, USD generates performance metrics using a +specific set of assets and specific hardware and software configurations. This +page describes what metrics are collected, what hardware and software +configurations are used, the actual metrics results, and how to generate the +metrics locally. + +*************** +What We Measure +*************** + +For a given asset, our performance script captures the following metrics by +default (items in **bold** are reported on this page): + +* Time to load and configure USD plugins for :program:`usdview` +* **Time to open the stage** +* Time to reset the :program:`usdview` prim browser +* Time to initialize the :program:`usdview` UI +* **Time to render first image** (in :program:`usdview`) +* **Time to shutdown Hydra** +* **Time to close the stage** +* Time to tear down the :program:`usdview` UI +* **Total time to start and quit** :program:`usdview` +* Time to traverse the prims in the stage + +We run 10 iterations for each asset, and capture the minimum and maximum times +for that set of iterations. We also calculate the mean time across the 10 +iterations. + +For each asset, we first warm the filesystem cache by loading the +asset in :program:`usdview`, to ensure we're not including cache performance +issues in our metrics. + +All assets used to measure performance are assumed to be available +locally. Time to download assets is not measured or included as part of +the gathered performance metrics. + +.. _perf_environments: + +************************ +What Environment Is Used +************************ + +This section describes the computing environment used to generate the +published performance metrics. The following operating systems and hardware are +currently used. + +.. note:: + + Machine specifications are subject to change. If specifications do change + for a give release, historical performance measurements will be run to + backfill any outdated data. + +Linux +===== + +* **OS**: CentOS Linux 7 +* **CPU**: 23 cores of Intel(R) Xeon(R) Platinum 8268 CPU @ 2.90GHz +* **RAM**: 117GB +* **GPU**: NVIDIA TU102GL (Quadro RTX 6000/8000) + +macOS +===== + +* **OS**: macOS 14.3 +* **CPU**: Apple M2 Ultra (20 Core) +* **RAM**: 192GB +* **GPU**: Apple M2 Ultra GPU (76 Core) + +Windows +======= + +* **OS**: Microsoft Windows 10 Enterprise +* **CPU**: AMD EPYC 7763 64-Core Processor, 2450 Mhz, 31 Core(s), 31 Logical Processor(s) +* **RAM**: 128GB +* **GPU**: NVIDIA RTXA6000-24Q + +USD Build +========= + +For each of the operating systems and hardware platforms listed previously, we +build USD with the same build configuration. We use a stock invocation of +``build_usd.py`` with the default options (release build, Python components, +imaging and USD imaging components, usdview, etc). + +******* +Metrics +******* + +Metrics are all measured in seconds. + +Performance Graphs Per Platform +=============================== + +The following graphs show the time (in seconds) to open and close +:program:`usdview` for each asset. Graphs are provided for Linux, macOS, and +Windows platforms (as described in :ref:`perf_environments`). + +.. note:: + + For the 24.11 release, there are known issues with obtaining metrics for + the Moore Lane asset on Windows, and the create_first_image metric on + macOS. We are actively investigating these issues and will update + published metrics when these issues are resolved. + +.. image:: performance/linux.svg + :width: 500 + +.. image:: performance/macos.svg + :width: 500 + +.. image:: performance/windows.svg + :width: 500 + +Standard Shader Ball +==================== + +This asset is designed to be a comprehensive test of a broad array of material +properties in a single render. Geometry is expressed using USD, materials are +defined using MaterialX, texture maps are provided in OpenEXR format and encoded +using the Academy Color Encoding System ACEScg color space. + +.. image:: https://raw.githubusercontent.com/usd-wg/assets/main/full_assets/StandardShaderBall/media/figure02.png + :width: 500 + +The shader ball asset can be `downloaded here `__. + +.. datatemplate:yaml:: performance/24.11_linux_shaderball.yaml + :template: perf_metric_shaderball_template.tmpl + +Kitchen Set +=========== + +This asset provides a complex kitchen scene. + +.. image:: https://openusd.org/images/Kitchen_set_thumb.png + :width: 500 + +The Kitchen Set asset can be `downloaded here `__. + +.. datatemplate:yaml:: performance/24.11_linux_kitchenset.yaml + :template: perf_metric_kitchenset_template.tmpl + +ALab +==== + +ALab is a full production scene created by Animal Logic and contains over 300 +assets, complete with high-quality textures and two characters with looping +animation in shot context. Supplied as four separate downloads: the full +production scene, high-quality textures, shot cameras matching the ALab trailer, +and baked procedural fur and fabric for the animated characters. + +The metrics have been measured with the base asset merged with the additional +"techvars" info. + +.. image:: https://animallogic.com/wp-content/uploads/2022/08/LoopySequence02.gif + :width: 500 + +The ALab asset can be `downloaded here `__. + +.. datatemplate:yaml:: performance/24.11_linux_alab.yaml + :template: perf_metric_alab_template.tmpl + +Moore Lane +========== + +4004 Moore Lane is a fully composed, high-quality scene for the purpose of +testing various visual computing issues. The house itself was wrapped around a +number of typical problem areas for light transport and noise sampling. This +includes things like thin openings in exterior walls, recessed area light +sources, deeply shadowed corners, and high-frequency details. The exterior +landscape surrounding the house consisted of a relatively simple ecosystem of +instanced plants which could provide some additional levels of complexity. In +addition to the geometry itself being designed to exacerbate some typical +issues, the USD structure itself was created for several layers of testing. + +The metrics have been measured using the contained +:filename:`MooreLane_ASWF_0623.usda` file. + +.. image:: https://dpel.aswf.io/images/4004/render_20181.jpeg + :width: 500 + +The Moore Lane asset can be `downloaded here `__. + +.. datatemplate:yaml:: performance/24.11_linux_moorelane.yaml + :template: perf_metric_moorelane_template.tmpl + +*********************************** +Running Performance Metrics Locally +*********************************** + +We encourage developers to run the USD performance metrics to measure +performance impacts of OpenUSD code contributions. Performance metrics can +also be run to validate local runtime environments and hardware configurations. + +Performance metrics are generating using the :program:`usdmeasureperformance.py` +script found in ``pxr/extras/performance``. See the +`usdmeasureperformance tool docs `_ for more +information on the different parameters available. + +:program:`usdmeasureperformance.py` uses :program:`usdview` and +:program:`testusdview`, so you will need to make sure those are in your current +path, or aliased properly. + +For gathering the metrics published on this page, the following parameters +are used (for each asset): + +.. code-block:: + + python usdmeasureperformance.py -i 10 -a min -o + +Adding Custom Metrics +===================== + +You can add your own custom metrics and have :program:`usdmeasureperformance.py` +include them as part of the set of metrics that it measures. + +To define a custom metric, create a script file that defines a +``testUsdviewInputFunction()`` function that will be passed to ``testusdview``. +For example, if you wanted to add a metric named "process prims", that +traversed the stage and processed each prim in some way, you might have a +``processPrimsMetric.py`` script that looks something like: + +.. code-block:: python + + from pxr import Usd, UsdUtils, Usdviewq + + def testUsdviewInputFunction(appController): + with Usdviewq.Timer("process prims", True): + stage = appController._dataModel.stage + for prim in stage.Traverse(): + # process prim as needed, etc + +See also the "traverse stage" example in ``pxr/extras/performance/explicitMetrics/stageTraversalMetric.py``. + +To include your custom metrics when running :program:`usdmeasureperformance.py`, +add your metrics script name and metric name as part of the ``--custom-metrics`` +script parameter. For example, if you wanted to include the "process prims" +metric example for "MyTestAsset.usda", you would use a +:program:`usdmeasureperformance.py` command line similar to: + +.. code-block:: + + python usdmeasureperformance.py MyTestAsset.usda --custom-metrics processPrimsMetric.py:'process prims' + +:program:`usdmeasureperformance.py` will look for your custom metric script +relative to the directory from which the :program:`usdmeasureperformance.py` +script is run. diff --git a/docs/spec_usdz.rst b/docs/spec_usdz.rst index b7603d0322..05a73580d3 100644 --- a/docs/spec_usdz.rst +++ b/docs/spec_usdz.rst @@ -5,7 +5,7 @@ Usdz File Format Specification .. include:: rolesAndUtils.rst .. include:: -Copyright |copy| 2018, Pixar Animation Studios, *version 1.2* +Copyright |copy| 2018, Pixar Animation Studios, *version 1.3* .. contents:: :local: @@ -60,15 +60,15 @@ Usdz Specification A usdz package is an uncompressed zip archive that is allowed to contain the following file types: - +-------------+--------------------------------+ - | Kind | Allowed File Types | - +=============+================================+ - | USD | **usda**, **usdc**, **usd** | - +-------------+--------------------------------+ - | Image | **png**, **jpeg**, **exr** | - +-------------+--------------------------------+ - | Audio | **M4A**, **MP3**, **WAV** | - +-------------+--------------------------------+ + +-------------+----------------------------------------+ + | Kind | Allowed File Types | + +=============+========================================+ + | USD | **usda**, **usdc**, **usd** | + +-------------+----------------------------------------+ + | Image | **png**, **jpeg**, **exr**, **avif** | + +-------------+----------------------------------------+ + | Audio | **M4A**, **MP3**, **WAV** | + +-------------+----------------------------------------+ The rest of the section goes into more detail about the specification. @@ -198,6 +198,7 @@ Clients wishing to deliver "streamable content" `may wish to consider other layo * Otherwise, the packaging API will fail to run unless the Default Layer is manually specified. +.. _spec_usdz_file_types: File Types ---------- @@ -211,8 +212,8 @@ currently. Allowable file types are currently: OS updates) * **png**, **jpeg** (any of the multiple common extensions for - jpeg), and **OpenEXR** files for images/textures. See - :ref:`Working With Image File Formats` for more + jpeg), **OpenEXR** and **AV1 Image (AVIF)** files for images/textures. + See :ref:`Working With Image File Formats` for more details on supported image file formats. * **M4A, MP3, WAV** files for embedded audio (given in order of preferred @@ -408,3 +409,13 @@ constraints. The toolset also includes: enforce stricter "web-compliant" rules that disallow certain advanced USD features that web-browsers do not yet support. +Changes, by Version +=================== + +Version 1.3 - Current Head +-------------------------- + +From version 1.2: + + * :ref:`Adds AV1 Image (AVIF) file support `. + AVIF is now a supported file type for images/textures. \ No newline at end of file diff --git a/docs/toc.rst b/docs/toc.rst index 22f1679f90..053c83cce4 100644 --- a/docs/toc.rst +++ b/docs/toc.rst @@ -39,6 +39,7 @@ Proposals FAQ Performance Considerations + Performance Metrics Third Party Plugins .. toctree:: @@ -50,7 +51,6 @@ Contributing Contributors Release Schedule - License .. toctree:: :hidden: diff --git a/docs/toolset.help b/docs/toolset.help index 0dab58a874..1b5ee04e89 100644 --- a/docs/toolset.help +++ b/docs/toolset.help @@ -88,32 +88,20 @@ optional arguments: ==== usddiff end ==== ==== usdview start ==== -usage: usdview [-h] [--renderer {GL}] - [--select PRIMPATH] - [--camera CAMERA] - [--mask PRIMPATH[,PRIMPATH...]] - [--clearsettings] - [--config {}] - [--defaultsettings] - [--norender] [--noplugins] - [--unloaded] [--bboxStandin] - [--timing] [--allow-async] - [--traceToFile TRACETOFILE] - [--traceFormat {chrome,trace}] - [--tracePython] - [--memstats {none,stage,stageAndImaging}] - [--numThreads NUMTHREADS] - [--ff FIRSTFRAME] - [--lf LASTFRAME] - [--cf CURRENTFRAME] - [--complexity {low,medium,high,veryhigh}] - [--quitAfterStartup] - [--sessionLayer SESSIONLAYER] - [--mute MUTELAYERSRE] - [--detachLayers] - [--detachLayersInclude PATTERN[,PATTERN...]] - [--detachLayersExclude PATTERN[,PATTERN,...]] - usdFile +usage: usdview + [-h] [--renderer {GL,Prman,Embree,Tiny}] [--select PRIMPATH] + [--camera CAMERA] [--mask PRIMPATH[,PRIMPATH...]] [--clearsettings] + [--config {foo}] [--defaultsettings] [--norender] [--noplugins] + [--unloaded] [--bboxStandin] [--timing] [--allow-async] + [--traceToFile TRACETOFILE] [--traceFormat {chrome,trace}] + [--tracePython] [--memstats {none,stage,stageAndImaging}] + [--numThreads NUMTHREADS] [--ff FIRSTFRAME] [--lf LASTFRAME] + [--cf CURRENTFRAME] [--complexity {low,medium,high,veryhigh}] + [--quitAfterStartup] [--sessionLayer SESSIONLAYER] + [--mute MUTELAYERSRE] [--detachLayers] + [--detachLayersInclude PATTERN[,PATTERN...]] + [--detachLayersExclude PATTERN[,PATTERN,...]] + usdFile View a usd file @@ -122,7 +110,7 @@ positional arguments: optional arguments: -h, --help show this help message and exit - --renderer {GL}, -r {GL} + --renderer {GL,Prman,Embree,Tiny}, -r {GL,Prman,Embree,Tiny} Which render backend to use (named as it appears in the menu). --select PRIMPATH A prim path to initially select and frame @@ -139,7 +127,7 @@ optional arguments: either use commas with no spaces or quote the argument and separate paths by commas and/or spaces. --clearsettings Restores usdview settings to default - --config {} Load usdview with the state settings found in the + --config {foo} Load usdview with the state settings found in the specified config. If not provided will use the previously saved application state and automatically persist state on close @@ -215,7 +203,7 @@ usage: usdrecord [-h] [--mask PRIMPATH[,PRIMPATH...]] [--defaultTime | --frames FRAMESPEC[,FRAMESPEC...]] [--complexity {low,medium,high,veryhigh}] [--colorCorrectionMode {disabled,sRGB,openColorIO}] - [--renderer {GL}] [--imageWidth IMAGEWIDTH] + [--renderer {GL,Prman,Embree,Tiny}] [--imageWidth IMAGEWIDTH] [--enableDomeLightVisibility] [--renderPassPrimPath RPPRIMPATH] [--renderSettingsPrimPath RSPRIMPATH] @@ -283,7 +271,7 @@ optional arguments: level of refinement to use (default=low) --colorCorrectionMode {disabled,sRGB,openColorIO}, -color {disabled,sRGB,openColorIO} the color correction mode to use (default=sRGB) - --renderer {GL}, -r {GL} + --renderer {GL,Prman,Embree,Tiny}, -r {GL,Prman,Embree,Tiny} Hydra renderer plugin to use when generating images --imageWidth IMAGEWIDTH, -w IMAGEWIDTH Width of the output image. The height will be computed @@ -487,8 +475,8 @@ optional arguments: ==== usdfixbrokenpixarschemas end ==== ==== usdstitch start ==== -usage: usdstitch [-h] [-o OUT] - usdFiles [usdFiles ...] +usage: usdstitch + [-h] [-o OUT] usdFiles [usdFiles ...] Stitch multiple usd file(s) together into one. Opinion strength is determined by the order in which the file is given, with the first file getting the @@ -629,3 +617,45 @@ Options: --noValues Do not report field values. ==== sdffilter end ==== + +==== usdmeasureperformance start ==== +usage: usdmeasureperformance [-h] [-c [CUSTOM_METRICS ...]] -o OUTPUT + [-i ITERATIONS] + [-a {min,mean,max} [{min,mean,max} ...]] + asset + +Measure and export USD functional performance + +positional arguments: + asset Asset file path. + +optional arguments: + -h, --help show this help message and exit + -c [CUSTOM_METRICS ...], --custom-metrics [CUSTOM_METRICS ...] + Additional custom metrics to run `testusdview` timing + on. If not set, a default set of metrics is run. This + should be a whitespace-separated list of +