{"id":31768362,"url":"https://github.com/Autodesk/hydra-viewport-toolbox","last_synced_at":"2025-10-10T02:02:06.976Z","repository":{"id":299497390,"uuid":"959345683","full_name":"Autodesk/hydra-viewport-toolbox","owner":"Autodesk","description":"Utilities to support graphics viewports using OpenUSD Hydra","archived":false,"fork":false,"pushed_at":"2025-10-02T15:16:16.000Z","size":2985,"stargazers_count":13,"open_issues_count":9,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-02T15:29:11.714Z","etag":null,"topics":["hydra","openusd","viewport"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Autodesk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-02T16:34:51.000Z","updated_at":"2025-09-25T21:01:09.000Z","dependencies_parsed_at":"2025-06-16T21:42:34.423Z","dependency_job_id":"fca13448-5511-4acf-9748-c756bbe497a8","html_url":"https://github.com/Autodesk/hydra-viewport-toolbox","commit_stats":null,"previous_names":["autodesk/hydra-viewport-toolbox"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Autodesk/hydra-viewport-toolbox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2Fhydra-viewport-toolbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2Fhydra-viewport-toolbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2Fhydra-viewport-toolbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2Fhydra-viewport-toolbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Autodesk","download_url":"https://codeload.github.com/Autodesk/hydra-viewport-toolbox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Autodesk%2Fhydra-viewport-toolbox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002454,"owners_count":26083388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hydra","openusd","viewport"],"created_at":"2025-10-10T02:00:46.738Z","updated_at":"2025-10-10T02:02:06.970Z","avatar_url":"https://github.com/Autodesk.png","language":"C++","funding_links":[],"categories":["Libraries \u0026 Tools"],"sub_categories":["Hydra"],"readme":"# Hydra Viewport Toolbox\nThe **Hydra Viewport Toolbox** (HVT) is a library of utilities that can be used by an application to simplify the use of [OpenUSD](https://openusd.org) Hydra for the application's graphics viewports. The utilities can be used together or independently to add common viewport functionality and improve the performance and visual quality of viewports.\n\nHVT currently includes the following features but it is being expanded to include even more.\n\n- Layering of Hydra render delegate output, optionally from different render delegates (\"passes\").\n- Management of multiple viewports.\n- Hydra task management, supporting application-defined lists of tasks.\n- Management of data commonly needed for tasks, e.g. render buffers and lighting.\n- Tasks for features commonly needed for viewports, e.g. antialiasing and ambient occlusion.\n- User interaction for common operations, e.g. selection and camera manipulation.\n\nHVT is developed and maintained by Autodesk. The contents of this repository are fully open source under [the Apache license](LICENSE.md), with [feature requests and code contributions](CONTRIBUTING.md) welcome!\n\n## 🚀 Quick Start\n\nTo build the project locally using the default configuration:\n\n### Linux/macOS:\n```bash\ncmake --preset debug\ncmake --build --preset debug\n```\n\n### Windows:\n**Prerequisites:** You need Visual Studio's x64 development environment loaded. Use one of these methods:\n\n**Option 1 (Recommended):** Open **\"x64 Native Tools Command Prompt for VS 2022\"** from the Start Menu, then:\n```cmd\ncmake --preset debug\ncmake --build --preset debug\n```\n\n**Option 2:** Configure your current PowerShell session:\n\u003e **💡 Note:** Replace [Edition] with your installed Visual Studio edition (e.g., Community, Professional, or Enterprise). If you have a different version (e.g., 2019), adjust the 2022 part of the path as well.\n```powershell\n\u0026 \"C:\\Program Files\\Microsoft Visual Studio\\2022\\[Edition]\\Common7\\Tools\\Launch-VsDevShell.ps1\" -Arch amd64\ncmake --preset debug\ncmake --build --preset debug\n```\n\n\u003e **💡 Why?** Windows requires the Visual Studio x64 toolchain environment for proper compiler and SDK paths.\n\nThis uses the built-in vcpkg manifest and cmake presets to automatically configure dependencies and build paths. No additional setup is needed beyond the platform prerequisites above.\n\nFor more information or to customize the configuration, see [Using CMake Presets](#using-cmake-presets) and [vcpkg Integration](#vcpkg-integration).\n\n## ✅ Continuous Integration (CI)\n\nCI builds and tests are run via GitHub Actions using shared CMake presets.\n\n### 🧪 CI Minimal\n\nA lightweight CI workflow (`ci-minimal.yaml`) runs automatically on every pull request and push, building and testing on Linux (Debug) by default.\n\nIt can also be run manually with custom options to test a specific platform (`windows`, `linux`, or `macos`) and configuration (`debug` or `release`) by selecting from the “Run workflow” button in GitHub Actions.\n\n### 🔁 CI Full\n\nA full matrix workflow (ci-full.yaml) tests on Linux, macOS, and Windows with both Debug and Release configurations. This does not run by default on every PR.\nTo run it manually, use the “Run workflow” button under the “Actions” tab on GitHub after pushing your branch.\nIt also runs when a PR merges into main.\n\n### 🔐 Secrets and Reusable Workflows\n\nThe CI uses reusable workflows to share common build logic across different jobs and platforms.\nThe GitHub Packages authentication secret (`GH_PACKAGES_TOKEN`) is only required by the `setup-vcpkg-cache.yaml` workflow, and it is securely passed from the top-level workflows (`ci-minimal.yaml` and `ci-full.yaml`) through the reusable build steps (`ci-steps.yaml`).\n\nThis design avoids exposing secrets to workflows that don’t need them and keeps each workflow focused on its specific responsibilities.\n\n## vcpkg Integration\n\nThis project uses vcpkg in manifest mode to manage third-party dependencies cleanly and automatically.\n\n### 🧰 Zero-Setup Build\n\nAll required vcpkg steps (initialization, bootstrapping, and toolchain setup) are fully automated. You do not need to install vcpkg manually or set any variables—just configure and build using one of the provided CMake presets (see below).\nIf the externals/vcpkg/ submodule is missing or uninitialized, the build system will fetch and bootstrap it for you.\n\n### 💡 How it Works\n-\tThe logic is handled in cmake/VcpkgSetup.cmake.\n-\tvcpkg is only enabled if: The tests are enabled or no USD installation path provided\n-\tThen the vcpkg submodule will be fetched, vcpkg will be bootstrapped, toolchain will be set.\n-\tThis ensures seamless support for both standalone builds and builds as part of larger projects.\n\n### 📦 USD Integration\n-\tIf OPENUSD_INSTALL_PATH is not set, the vcpkg usd-minimal feature is enabled by default.\n-\tYou can override this to use a local OpenUSD install by setting OPENUSD_INSTALL_PATH from env or cmake.\n\n### 🔁 Customizing the vcpkg Triplet (Optional)\nBy default, the vcpkg triplet is inferred from the target platform (Located in externals/vcpkg/triplets).\nYou can override this by setting the following CMake variable during configuration:\n```bash\n-DHVT_BASE_TRIPLET_FILE=/absolute/path/to/custom-triplet.cmake\n```\nThis allows advanced users to:\n-\tCustomize compiler flags or features used for all dependencies\n-\tSwitch between shared vs static libraries\n-\tTarget custom platforms or ABIs\n\nMake sure your custom triplet inherits from a standard vcpkg triplet if needed.\n\nFor faster release-only builds, use this to skip building debug dependencies:\n```bash\n-DHVT_RELEASE_ONLY_VCPKG_DEPS=ON\n```\n\n### 🧹 Cleaning vcpkg NuGet Cache (Optional)\n\n💡 **Note:** You can browse cached NuGet packages under the **\"Packages\"** section of the GitHub repository (right sidebar). These packages are auto-generated by `vcpkg` and include platform-specific metadata such as the compiler ID, version, and triplet hash. This is useful when diagnosing build issues or confirming what's cached.\n\nIf you're encountering issues with cached binary packages (e.g., missing or corrupted `.lib` files), you can delete the corresponding NuGet cache entry from GitHub. This can be done either manually via the GUI or using the included workflow.\n\n#### ⚙️ Using the Workflow\n\n1. Go to the **Actions** tab on GitHub.\n2. Select the **“Clean vcpkg NuGet Cache”** workflow.\n3. Enter the name of the vcpkg package to clean (e.g., `tbb`, `usd`) and run in dry-run mode first.\n4. Review the listed versions. If correct, run again with dry-run disabled to delete.\n\nThe workflow uses GitHub’s API to delete **all versions** of the specified package from the NuGet registry for this repo.\n\n\u003e ⚠️ **Warning:** This should only be used by repo admins or advanced users when CI builds consistently fail due to corrupted or incorrect cached packages.\n\n## Using CMake Presets\n\nThis project uses CMake Presets to define consistent and shareable build configurations across local development and CI.\n\n### 🧰 Why Presets?\nPresets provide a clean, declarative way to manage build options, toolchain setup, and environment variables. In this project, they are used to:\n-\tSimplify getting started with local builds.\n-\tAutomatically configure vcpkg when needed.\n-\tKeep CI scripts clean by reusing the same preset logic used locally.\n\nAll CI builds use these same presets internally, ensuring consistent behavior between local and automated builds.\n\n### 🔧 Building with CMake Presets\n\nThis project provides CMakePresets.json-based builds for easy setup. Presets ensure consistent options and automatic toolchain configuration.\n\nTo configure and build:\n```bash\ncmake --preset debug       # Configure Debug build with vcpkg\ncmake --build --preset debug\n```\n\nOr to use a specific OpenUSD install:\n```bash\n# Requires setting OPENUSD_INSTALL_PATH env to be set before calling cmake\nexport OPENUSD_INSTALL_PATH=/path/to/local/usd\ncmake --preset debug\ncmake --build --preset debug\n```\n\n### 🧪 Running Tests with CMake Presets\nUse the test preset to run the test suite:\n```bash\nctest --preset debug\n```\n\n### 🛠️ Custom Builds with CMake User Presets\n\nYou can create your own build configurations by adding a CMakeUserPresets.json file in the project root. This file is excluded by .gitignore, so it won’t interfere with version control or shared presets.\n\nThis is ideal for:\n-\tSpecifying custom paths (e.g., OPENUSD_INSTALL_PATH)\n-\tChanging build directories\n-\tTweaking options like enabling experimental features or using alternate compilers\n\n📁 Example CMakeUserPresets.json:\n```bash\n{\n  \"version\": 3,\n  \"configurePresets\": [\n    {\n      \"name\": \"my-debug\",\n      \"inherits\": \"debug\",\n      \"environment\": {\n      },\n      \"cacheVariables\": {\n        \"OPENUSD_INSTALL_PATH\": \"/path/to/my/openusd\"\n      }\n    }\n  ]\n}\n```\n\nUse it just like the built-in presets:\n```bash\ncmake --preset my-debug\ncmake --build --preset my-debug\n```\n\n💡 For more info on user presets, see the CMake Presets documentation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAutodesk%2Fhydra-viewport-toolbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAutodesk%2Fhydra-viewport-toolbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAutodesk%2Fhydra-viewport-toolbox/lists"}