├── .github └── workflows │ └── build-and-deploy.yml ├── .gitignore ├── ALAB_LICENSE ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── book.toml ├── preview.png ├── src ├── SUMMARY.md ├── getting_usd.md ├── images │ ├── USDLogoLrgWithAlpha.png │ ├── alab2.png │ ├── alab_root_layer_stack.png │ ├── terminology │ │ ├── attributes.png │ │ ├── composition.png │ │ ├── defaultPrim_cube.png │ │ ├── defaultPrim_empty.png │ │ ├── defaultPrim_sphere.png │ │ ├── edittarget.png │ │ ├── inherits_1.png │ │ ├── inherits_2.png │ │ ├── inherits_base.png │ │ ├── instancing_1.png │ │ ├── instancing_2.png │ │ ├── kind.png │ │ ├── kind_assembly.png │ │ ├── kind_component.png │ │ ├── kind_group.png │ │ ├── layer_stack.png │ │ ├── livrps.png │ │ ├── metadata.png │ │ ├── metadata_prop.png │ │ ├── metadata_stage.png │ │ ├── overrides.png │ │ ├── payload_1.png │ │ ├── payload_2.png │ │ ├── payload_example.gif │ │ ├── prim.png │ │ ├── prim_path.png │ │ ├── property_path.png │ │ ├── purpose.gif │ │ ├── purpose_proxy.png │ │ ├── purpose_render.png │ │ ├── reference_1.png │ │ ├── reference_2.png │ │ ├── reference_3.png │ │ ├── reference_4.png │ │ ├── reference_5.png │ │ ├── reference_6.png │ │ ├── relationships.png │ │ ├── robot_usd.png │ │ ├── schemas_1.png │ │ ├── schemas_2.png │ │ ├── schemas_3.png │ │ ├── specializes_1.png │ │ ├── specializes_2.png │ │ ├── specializes_3.png │ │ ├── specializes_4.png │ │ ├── stage_traversal.gif │ │ ├── sublayer.png │ │ ├── variant_switching.gif │ │ └── world_usd.png │ └── usd_icon_small.png ├── index.md ├── motivation.md ├── terminology │ ├── LIVRPS.md │ ├── api_schemas.md │ ├── composition.md │ ├── composition_arcs.md │ ├── default_prim.md │ ├── edittarget.md │ ├── inherits.md │ ├── instancing.md │ ├── isa_schemas.md │ ├── kind.md │ ├── layer.md │ ├── layer_stacks.md │ ├── list_editing.md │ ├── local_sublayer.md │ ├── metadata.md │ ├── opinions.md │ ├── overrides.md │ ├── path.md │ ├── payload.md │ ├── prims.md │ ├── properties.md │ ├── purpose.md │ ├── reference.md │ ├── schemas.md │ ├── specializes.md │ ├── specifier.md │ ├── stage.md │ ├── stage_traversal.md │ ├── terminology.md │ └── variantset.md ├── usd_primer.md └── what_is_usd_not.md └── theme ├── catppuccin-highlight.css ├── catppuccin.css ├── custom.css ├── index.hbs └── mdbook-admonish.css /.github/workflows/build-and-deploy.yml: -------------------------------------------------------------------------------- 1 | name: Build and Deploy 2 | 3 | on: 4 | # Triggers the workflow on push or pull request events but only for the "main" branch 5 | push: 6 | branches: ["main"] 7 | pull_request: 8 | branches: ["main"] 9 | 10 | workflow_dispatch: 11 | 12 | permissions: 13 | contents: read 14 | pages: write 15 | id-token: write 16 | 17 | jobs: 18 | build: 19 | runs-on: ubuntu-latest 20 | 21 | steps: 22 | - name: Install latest stable 23 | uses: actions-rs/toolchain@v1 24 | with: 25 | toolchain: stable 26 | override: true 27 | 28 | - name: Install mdbook 29 | uses: actions-rs/cargo@v1 30 | with: 31 | command: install 32 | args: --version 0.4.30 mdbook 33 | 34 | - name: Install mdbook-catppuccin 35 | uses: actions-rs/cargo@v1 36 | with: 37 | command: install 38 | args: --version 0.1.1 mdbook-catppuccin 39 | 40 | - name: Install mdbook-admonish 41 | uses: actions-rs/cargo@v1 42 | with: 43 | command: install 44 | args: --version 1.9.0 mdbook-admonish 45 | 46 | - uses: actions/checkout@v3 47 | 48 | - name: Build the book 49 | run: mdbook build -d book 50 | 51 | - name: Upload built book artifact 52 | uses: actions/upload-artifact@v3 53 | with: 54 | name: book 55 | path: book 56 | if-no-files-found: error 57 | 58 | deploy: 59 | runs-on: ubuntu-latest 60 | needs: build 61 | if: github.event_name != 'pull_request' 62 | 63 | environment: 64 | name: github-pages 65 | url: ${{ steps.deployment.outputs.page_url }} 66 | 67 | steps: 68 | - name: Download build artifact 69 | uses: actions/download-artifact@v3 70 | with: 71 | name: book 72 | path: . 73 | - name: Upload Pages 74 | uses: actions/upload-pages-artifact@v1 75 | with: 76 | path: . 77 | - name: Deploy to GitHub Pages 78 | id: deployment 79 | uses: actions/deploy-pages@v1 80 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /ALAB_LICENSE: -------------------------------------------------------------------------------- 1 | # ASWF Digital Assets License v1.1 2 | 3 | License for Animal Logic ALab (the “Asset Name”). 4 | 5 | Animal Logic ALab Copyright 2022 Animal Logic Pty Limited. All rights reserved. 6 | 7 | Redistribution and use of these digital assets, with or without modification, solely for education, training, research, software and hardware development, performance benchmarking (including publication of benchmark results and permitting reproducibility of the benchmark results by third parties), or software and hardware product demonstrations, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of these digital assets or any part of them must include the above copyright notice, this list of conditions and the disclaimer below, and if applicable, a description of how the redistributed versions of the digital assets differ from the originals. 10 | 2. Publications showing images derived from these digital assets must include the above copyright notice. 11 | 3. The names of copyright holder or the names of its contributors may NOT be used to promote or to imply endorsement, sponsorship, or affiliation with products developed or tested utilizing these digital assets or benchmarking results obtained from these digital assets, without prior written permission from copyright holder. 12 | 4. The assets and their output may only be referred to as the Asset Name listed above, and your use of the Asset Name shall be solely to identify the digital assets. Other than as expressly permitted by this License, you may NOT use any trade names, trademarks, service marks, or product names of the copyright holder for any purpose. 13 | 14 | DISCLAIMER: THESE DIGITAL ASSETS ARE PROVIDED BY THE COPYRIGHT HOLDER “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE DISCLAIMED. IN NO EVENT SHALL COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 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 THESE DIGITAL ASSETS, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 15 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | Before making a contribution to this repository (and we hope you do), please read over this document first. 4 | 5 | Any changes or new work should be done on the `develop` branch of this repository. When creating Pull Requests, please ensure that the base branch is set to "develop". The repository owners will take care of promoting any changes to `main`. 6 | 7 | ## Conventions and Style 8 | 9 | ### Admonishments 10 | This book makes heavy use of admonishments, please use the following guidelines when adding these basic admonishments. Any unlisted admonishments are of course free to use as you see fit. 11 | 12 | See the [mkdocs-material documentation](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) for the supported types. 13 | 14 | #### Notes 15 | When adding notes to a page, do so with the `note` admonish and omit the title. This will result in a simple note box. 16 | 17 | ~~~markdown 18 | ```admonish note title="" 19 | Simple concise note 20 | ``` 21 | ~~~ 22 | 23 | Larger notes can have titles of course. And there are some within this book, but in general, notes should have a small footprint. 24 | 25 | #### Examples 26 | Use the example markdown when you want to showcase an example 27 | 28 | ~~~markdown 29 | ```admonish example title="" 30 | images, code, etc... 31 | ``` 32 | ~~~ 33 | 34 | #### Warnings 35 | Use when it's important to confer to the reader that something may have side effects, information is inconclusive or unverified, etc... 36 | 37 | ~~~markdown 38 | ```admonish warning 39 | Warning about a topic 40 | ``` 41 | ~~~ 42 | 43 | #### Tips 44 | Use for fun-facts, tidbits of information that are adjacent to the topic 45 | 46 | ~~~markdown 47 | ```admonish tip title="Fun fact" 48 | This is a fun fact 49 | ``` 50 | ~~~ 51 | 52 | #### Abstract 53 | When needing to distinguish between two different "sub concepts" 54 | 55 | See [Properties](./src/terminology/properties.md) for an example on how `abstract`s are used to distinguish between `attributes` and `properties`. 56 | 57 | ~~~markdown 58 | ```admonish abstract title="A sub-concept" 59 | subconcept discription 60 | ``` 61 | ~~~ 62 | 63 | ### Glossary Chapters 64 | Most chapters explaining something from the USD Glossary should follow this simple layout 65 | 66 | ~~~txt 67 | # 68 | 69 | 70 | 71 | ```admonish example title="" 72 | [![](../images/terminology/.png)](../images/terminology/.png) 73 | ``` 74 | 75 | 76 | 77 | --- 78 | 79 | ```admonish note title="" 80 | ↪ [USD Glossary - ]() 81 | ``` 82 | ~~~ 83 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Remedy Entertainment 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Book of USD 2 | 3 | ![Preview with Frappe styling of the book](./preview.png) 4 | 5 | This book aims to offer a more human-readable and artist friendly way of learning Universal Scene Description (USD) and its jargon. It is not a replacement of the [official USD Glossary](https://graphics.pixar.com/usd/release/glossary.html), but more of a starting point for anyone new to the technology. 6 | 7 | ## Install Rust language and dependencies 8 | 9 | - Follow the instructions on https://www.rust-lang.org/learn/get-started to install rust for your system 10 | - Run `rustup update` to update rust to the latest version 11 | - Run `cargo install mdbook mdbook-catppuccin mdbook-admonish` to install [`mdbook`](https://rust-lang.github.io/mdBook/), [`mdbook-catppuccin`](https://github.com/catppuccin/mdbook) and [`mdbook-admonish`](https://github.com/tommilligan/mdbook-admonish) 12 | 13 | ## Building 14 | Building is as simple as 15 | `mdbook build -d ` 16 | 17 | Be sure to also run `mdbook clean -d ` once in a while 18 | 19 | ## Previewing 20 | You can also preview the book via `mdbook serve --open` to automatically compile and preview the book in your web browser 21 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "Getting Started with Universal Scene Description (USD)" 3 | authors = ["Remedy Entertainment Plc"] 4 | language = "en" 5 | multilingual = false 6 | src = "src" 7 | 8 | [output.html] 9 | default-theme = "Latte" 10 | preferred-dark-theme = "frappe" 11 | curly-quotes = true 12 | git-repository-url = "https://github.com/Remedy-Entertainment/USDBook" 13 | edit-url-template = "https://github.com/Remedy-Entertainment/USDBook/edit/develop/{path}" 14 | git-repository-icon = "fa-github" 15 | additional-css = [ 16 | "theme/custom.css", 17 | 'theme/mdbook-admonish.css', 18 | 'theme/catppuccin.css', 19 | 'theme/catppuccin-highlight.css', 20 | ] 21 | no-section-label = true 22 | 23 | [output.html.fold] 24 | enable = true 25 | level = 4 26 | 27 | [preprocessor.admonish] 28 | command = "mdbook-admonish" 29 | assets_version = "2.0.1" # do not edit: managed by `mdbook-admonish install` 30 | 31 | [preprocessor.catppuccin] 32 | assets_version = "0.1.1" # DO NOT EDIT: Managed by `mdbook-catppuccin install` 33 | -------------------------------------------------------------------------------- /preview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/preview.png -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # SUMMARY 2 | [Book of USD](index.md) 3 | 4 | ---------------------- 5 | 6 | 7 | - [Introduction]() 8 | - [Motivation](./motivation.md) 9 | - [What is USD](./usd_primer.md) 10 | - [What is it not?](./what_is_usd_not.md) 11 | - [Getting USD](./getting_usd.md) 12 | - [USD Terminology](./terminology/terminology.md) 13 | - [Prims](./terminology/prims.md) 14 | - [Properties](./terminology/properties.md) 15 | - [Path](./terminology/path.md) 16 | - [Layer](./terminology/layer.md) 17 | - [Metadata](./terminology/metadata.md) 18 | - [Layer Stack](./terminology/layer_stacks.md) 19 | - [Composition](./terminology/composition.md) 20 | - [Stage](./terminology/stage.md) 21 | - [Opinions](./terminology/opinions.md) 22 | - [Overrides](./terminology/overrides.md) 23 | - [Stage Traversal](./terminology/stage_traversal.md) 24 | - [Kind](./terminology/kind.md) 25 | - [Purpose](./terminology/purpose.md) 26 | - [Specifier](./terminology/specifier.md) 27 | - [Composition Arcs](./terminology/composition_arcs.md) 28 | - [Local/Sublayer](./terminology/local_sublayer.md) 29 | - [Reference](./terminology/reference.md) 30 | - [VariantSet](./terminology/variantset.md) 31 | - [Payload](./terminology/payload.md) 32 | - [Inherits](./terminology/inherits.md) 33 | - [Specializes](./terminology/specializes.md) 34 | - [Strength Ordering (LIVRPS)](./terminology/LIVRPS.md) 35 | - [Default Prim](./terminology/default_prim.md) 36 | - [List-Editing](./terminology/list_editing.md) 37 | - [EditTarget](./terminology/edittarget.md) 38 | - [Instancing](./terminology/instancing.md) 39 | - [Schemas](./terminology/schemas.md) 40 | - [IsA Schemas](./terminology/isa_schemas.md) 41 | - [API Schemas](./terminology/api_schemas.md) -------------------------------------------------------------------------------- /src/getting_usd.md: -------------------------------------------------------------------------------- 1 | # Getting USD 2 | 3 | USD is an amazing technology stack, but unfortunately that is also what makes it hard to get started with. It is a suite of libraries and tools that are all part of the larger ecosystem that makes up USD. And while third party tooling is getting better and better, just "grabbing USD" can prove to be quite challenging. 4 | 5 | Pixar Animation Studios offers the [source code on GitHub](https://github.com/PixarAnimationStudios/USD), and for developers that is generally the first point of entry to get started. They would clone the repository, bootstrap the right version of Python and their favorite C++ compiler and then take a long coffee break to get all the tools and libraries built for their system. 6 | 7 | Suffice to say, this approach isn't for everyone. Fortunately, it is also not the _only_ way to get started with USD. 8 | 9 | As a newcomer, there are generally two ways in how to get and use USD. 10 | 11 | ```admonish abstract title="Within a Host Application" 12 | Host Applications are third party software that choose to embed USD into their toolset, or be built entirely on top of USD. 13 | 14 | Below is a small list of the most well known applications that do so: 15 | - [NVIDIA Omniverse Create](https://www.nvidia.com/en-us/omniverse/apps/create/) - A very capable USD assembler built on top of [NVIDIA's Omniverse](https://www.nvidia.com/en-us/omniverse) which brings you very close to working with raw USD 16 | - [Autodesk Maya + MayaUsd](https://www.autodesk.com/products/maya) - Professional 3D Software, the Maya USD integration is an add-on that can be installed during installation 17 | - [SideFx Houdini + Solaris](https://www.sidefx.com/products/houdini/solaris/) - Professional 3D Software, the look development suite called Solaris is built-in and built on USD 18 | 19 | ``` 20 | 21 | ~~~admonish abstract title="Standalone" 22 | This is at the moment the least artist-friendly option, but can be interesting for those who wish to experience USD as it is provided by Pixar Animation Studios. There are two ways of getting to use USD in a standalone manner: 23 | 24 | * **Prebuilt binaries** 25 | While there are few prebuilt binaries available, NVIDIA does provide some at [developer.nvidia.com/usd](https://developer.nvidia.com/usd#bin) 26 | 27 | * **Compile-it-yourself** 28 | This is the "traditional" way of getting started with USD and can be as mentioned incredibly daunting for non-software engineers. But, if you do wish to go down this route; Pixar Animation Studios provide [fantastic build instructions](https://github.com/PixarAnimationStudios/USD) 29 | 30 | ~~~ 31 | 32 | 33 | If you are new to USD, and you want to learn to construct and work with USD; it's recommended to build USD compositions and layers through a Host Application. Each host does have its own learning curve and individual challenges and idiosyncrasies with regards to USD; but will likely get you going the fastest. 34 | 35 | ```admonish note title="" 36 | The `Compile-it-yourself` method is used for all images within this book, and relies heavily on bundled USD tools such as `usdview`. 37 | ``` -------------------------------------------------------------------------------- /src/images/USDLogoLrgWithAlpha.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/USDLogoLrgWithAlpha.png -------------------------------------------------------------------------------- /src/images/alab2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/alab2.png -------------------------------------------------------------------------------- /src/images/alab_root_layer_stack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/alab_root_layer_stack.png -------------------------------------------------------------------------------- /src/images/terminology/attributes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/attributes.png -------------------------------------------------------------------------------- /src/images/terminology/composition.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/composition.png -------------------------------------------------------------------------------- /src/images/terminology/defaultPrim_cube.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/defaultPrim_cube.png -------------------------------------------------------------------------------- /src/images/terminology/defaultPrim_empty.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/defaultPrim_empty.png -------------------------------------------------------------------------------- /src/images/terminology/defaultPrim_sphere.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/defaultPrim_sphere.png -------------------------------------------------------------------------------- /src/images/terminology/edittarget.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/edittarget.png -------------------------------------------------------------------------------- /src/images/terminology/inherits_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/inherits_1.png -------------------------------------------------------------------------------- /src/images/terminology/inherits_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/inherits_2.png -------------------------------------------------------------------------------- /src/images/terminology/inherits_base.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/inherits_base.png -------------------------------------------------------------------------------- /src/images/terminology/instancing_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/instancing_1.png -------------------------------------------------------------------------------- /src/images/terminology/instancing_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/instancing_2.png -------------------------------------------------------------------------------- /src/images/terminology/kind.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/kind.png -------------------------------------------------------------------------------- /src/images/terminology/kind_assembly.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/kind_assembly.png -------------------------------------------------------------------------------- /src/images/terminology/kind_component.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/kind_component.png -------------------------------------------------------------------------------- /src/images/terminology/kind_group.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/kind_group.png -------------------------------------------------------------------------------- /src/images/terminology/layer_stack.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/layer_stack.png -------------------------------------------------------------------------------- /src/images/terminology/livrps.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/livrps.png -------------------------------------------------------------------------------- /src/images/terminology/metadata.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/metadata.png -------------------------------------------------------------------------------- /src/images/terminology/metadata_prop.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/metadata_prop.png -------------------------------------------------------------------------------- /src/images/terminology/metadata_stage.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/metadata_stage.png -------------------------------------------------------------------------------- /src/images/terminology/overrides.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/overrides.png -------------------------------------------------------------------------------- /src/images/terminology/payload_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/payload_1.png -------------------------------------------------------------------------------- /src/images/terminology/payload_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/payload_2.png -------------------------------------------------------------------------------- /src/images/terminology/payload_example.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/payload_example.gif -------------------------------------------------------------------------------- /src/images/terminology/prim.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/prim.png -------------------------------------------------------------------------------- /src/images/terminology/prim_path.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/prim_path.png -------------------------------------------------------------------------------- /src/images/terminology/property_path.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/property_path.png -------------------------------------------------------------------------------- /src/images/terminology/purpose.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/purpose.gif -------------------------------------------------------------------------------- /src/images/terminology/purpose_proxy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/purpose_proxy.png -------------------------------------------------------------------------------- /src/images/terminology/purpose_render.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/purpose_render.png -------------------------------------------------------------------------------- /src/images/terminology/reference_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_1.png -------------------------------------------------------------------------------- /src/images/terminology/reference_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_2.png -------------------------------------------------------------------------------- /src/images/terminology/reference_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_3.png -------------------------------------------------------------------------------- /src/images/terminology/reference_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_4.png -------------------------------------------------------------------------------- /src/images/terminology/reference_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_5.png -------------------------------------------------------------------------------- /src/images/terminology/reference_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/reference_6.png -------------------------------------------------------------------------------- /src/images/terminology/relationships.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/relationships.png -------------------------------------------------------------------------------- /src/images/terminology/robot_usd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/robot_usd.png -------------------------------------------------------------------------------- /src/images/terminology/schemas_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/schemas_1.png -------------------------------------------------------------------------------- /src/images/terminology/schemas_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/schemas_2.png -------------------------------------------------------------------------------- /src/images/terminology/schemas_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/schemas_3.png -------------------------------------------------------------------------------- /src/images/terminology/specializes_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/specializes_1.png -------------------------------------------------------------------------------- /src/images/terminology/specializes_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/specializes_2.png -------------------------------------------------------------------------------- /src/images/terminology/specializes_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/specializes_3.png -------------------------------------------------------------------------------- /src/images/terminology/specializes_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/specializes_4.png -------------------------------------------------------------------------------- /src/images/terminology/stage_traversal.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/stage_traversal.gif -------------------------------------------------------------------------------- /src/images/terminology/sublayer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/sublayer.png -------------------------------------------------------------------------------- /src/images/terminology/variant_switching.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/variant_switching.gif -------------------------------------------------------------------------------- /src/images/terminology/world_usd.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/terminology/world_usd.png -------------------------------------------------------------------------------- /src/images/usd_icon_small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Remedy-Entertainment/USDBook/a9d0c2a64e2eddf0c724846b19e0542a7d3ed309/src/images/usd_icon_small.png -------------------------------------------------------------------------------- /src/index.md: -------------------------------------------------------------------------------- 1 | ![](images/USDLogoLrgWithAlpha.png#center) 2 | 3 | # Book of USD 4 | 5 | **[Universal Scene Description (USD)](https://graphics.pixar.com/usd/release/index.html)** is a novel way of defining and working with 3D-Scene data, developed by [Pixar Animation Studios](https://www.pixar.com/). 6 | 7 | This book aims to be a companion document for the [official documentation](https://graphics.pixar.com/usd/release/index.html) 8 | 9 | ```admonish note title="Authors" 10 | * [Remedy Entertainment Plc](https://www.remedygames.com) 11 | ``` 12 | 13 | ```admonish quote title="License (MIT)" 14 | {{#include ../LICENSE}} 15 | ``` 16 | 17 | Most images in this book are using the [Animal Logic ALab](https://animallogic.com/alab/) USD Scene. 18 | ```admonish quote title="Animal Logic ALab License (ASWF Digital Assets License v1.1)" 19 | {{#include ../ALAB_LICENSE}} 20 | ``` 21 | 22 | ---- 23 | 24 | ```admonish tip title="Contributing" 25 | This is an open project and any contributions are welcome and appreciated! See the [GitHub Repository](https://github.com/Remedy-Entertainment/USDBook) for more information 26 | ``` -------------------------------------------------------------------------------- /src/motivation.md: -------------------------------------------------------------------------------- 1 | # Motivation 2 | 3 | Universal Scene Description (USD) is already making big waves in the VFX/Film and Games industries, with large players such as [NVidia](https://www.nvidia.com/en-us/omniverse/), [Apple](https://opensource.apple.com/projects/usd/) and [Autodesk](https://makeanything.autodesk.com/usd) jumping on the technology. But as a newcomer; it can be an incredibly daunting and frustrating journey to venture into. 4 | 5 | This book's driving motivation is to offer a _succinct, beginner-friendly and structured_ way of introducing USD, its concepts and terminology. At the moment this book focusses predominantly on terminology, but will be expanded upon with workflow examples in the future. 6 | 7 | ```admonish question title="You may be wondering at this point" 8 | _Why read this book instead the [official USD Glossary](https://graphics.pixar.com/usd/release/glossary.html) and [Tutorials](https://graphics.pixar.com/usd/release/tut_usd_tutorials.html)?_ 9 | ``` 10 | 11 | Jumping head-first into the [official USD Glossary](https://graphics.pixar.com/usd/release/glossary.html) or [Tutorials](https://graphics.pixar.com/usd/release/tut_usd_tutorials.html) is a perfectly valid strategy; unfortunately, the reality is that USD is a very complex machine with many moving parts intertwined with one another. Simply trying out USD's bundled applications like `USDView` can be quite involved if you're not a software engineer. 12 | Many concepts are also tied to the hip, as such it can be very easy to drown in terminology. This kind of "rabbit-hole-diving" method of learning can be incredibly confusing and overwhelming. 13 | 14 | This book offers an alternative path to that. 15 | 16 | 17 | ------- 18 | 19 | ```admonish note title="Author's Note" 20 | At [Remedy Entertainment](https://www.remedygames.com), we absolutely ❤ USD! We even gave [a talk](https://www.youtube.com/watch?v=FI2pyzTOvaQ) about how we are using it to make AAA games! 21 | 22 | After the aforementioned presentation, we were asked to release our internal documentation on USD itself publicly as we had written a more simplified subset of the [official USD Glossary](https://graphics.pixar.com/usd/release/glossary.html). This book is that documentation, albeit cleaned up, rewritten and adjusted for `mdbook` compatibility. 23 | 24 | We are releasing this with a permissive license, so you are free to fork/copy/change your version of this book as you see fit. 25 | ``` -------------------------------------------------------------------------------- /src/terminology/LIVRPS.md: -------------------------------------------------------------------------------- 1 | # Strength Ordering (LIVRPS) 2 | 3 | Composition and opinion value resolution go hand in hand, and in order to remain sane; there are rules. Each composition arc has a "strength" assigned to it. Meaning that if for example opinions targeting a property are authored on 3 different composition arcs within the same layer stack, the composition arc that is the "strongest" wins. This is where the acronym `LIVRPS (Liver Peas)` comes into play. 4 | 5 | It stands for 6 | - `L`ocal 7 | - `I`nherits 8 | - `V`ariants 9 | - `R`eferences 10 | - `P`ayloads 11 | - `S`pecializes 12 | 13 | This list acts as top-down stack. When USD needs to resolve an opinion for a property or metadatum, it will look for opinions via these composition arcs in this exact order. If an opinion has been found, any subsequent searches down the stack are immediately aborted and the opinion is resolved. If no authored opinion has been found, USD will fall back to the property/metadatum's default value. 14 | 15 | All composition arcs besides Local will trigger a recursive LIVRP(S) evaluation. However, within this recursive evaluation, `S`(pecializes) is ignored except for the [Specializes](../intermediate/specializes.md) composition arc. It triggers a full `LIVRPS` evaluation if encountered. 16 | 17 | The following diagram visualizes the decision tree of when and where opinion values are fetched 18 | 19 | ![](../images/terminology/livrps.png) 20 | 21 | --- 22 | 23 | ```admonish note title="" 24 | ↪ [USD Glossary - LIVRPS Strength Ordering](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-livrps-strength-ordering) 25 | ``` -------------------------------------------------------------------------------- /src/terminology/api_schemas.md: -------------------------------------------------------------------------------- 1 | # API Schemas 2 | 3 | API Schemas offer a way to contribute to a prim's "definition" by defining sets of predefined properties and metadata or offer a way to extract that information for you. 4 | 5 | Generally speaking, API Schemas come in two different flavors, `Non-applied API Schemas` and `Single or Multiple-applied API Schemas`. 6 | 7 | ## Non-Applied Schemas 8 | These schemas helps the developer by offering a high level abstraction for fetching properties and metadata. 9 | 10 | These kinds of schemas usually do not define properties themselves, only ways to fetch them. 11 | 12 | ```python 13 | # Python example to set the Kind type on a prim via the UsdModelAPI, a non-applied API schema 14 | Usd.ModelAPI(prim).SetKind(Kind.Tokens.subcomponent) 15 | ``` 16 | 17 | ```admonish info title="" 18 | Users will generally never have to deal with these as they can only really be used programmatically 19 | ``` 20 | 21 | ## Single or Multiple-applied API Schemas 22 | 23 | These are the kinds of schemas users will interact with implicitly. 24 | Applied API Schemas define the default properties that will be added to a prim's definition when it is applied. 25 | 26 | For example if an applied schema (let's call it `FooAPI`) defines a `float` attribute named `foo`, when that schema is applied to a prim, the `foo` property will be available for users to express opinions on. If the user does not express an opinion on it, `foo` will fall back to its default value. 27 | 28 | In a more concrete example, let's look at the `MaterialBindingAPI` which is responsible for defining properties on prims that need a binding to a material. 29 | The prim at path `/Sphere/Mesh` has the `MaterialBindingAPI` applied to it through the prim's apiSchemas metadata (this a [List-Editable](./list_editing.md) metadatum btw, so users can also override which API Schemas are applied to a prim) 30 | 31 | ```admonish example title="Applied Schemas" 32 | ![](../images/terminology/schemas_1.png) 33 | ``` 34 | 35 | This allows for editing the `material:binding` property on this prim now. The important thing to note here is the `custom` metadatum on the property. This indicates that the property is known to USD and that it belongs to a schema. Generally speaking, if `custom` is authored as True, it is considered an inert, out-of-schema property. 36 | 37 | ```admonish example title="Schema defined attribute" 38 | ![](../images/terminology/schemas_2.png) 39 | ``` 40 | 41 | --- 42 | 43 | ```admonish note title="" 44 | ↪ [USD Glossary - API Schema](https://graphics.pixar.com/usd/release/glossary.html#api-schema) 45 | ``` 46 | -------------------------------------------------------------------------------- /src/terminology/composition.md: -------------------------------------------------------------------------------- 1 | # Composition 2 | 3 | Roughly put, the act of combining layers and their prims, properties and metadata together through various means known as composition arcs. 4 | 5 | While combining layers together could be considered "composing" them, what USD's composition engine actually uses are the layer stacks of each layer. 6 | 7 | ```admonish warning title="" 8 | This is a very important distinction to make as targeting a layer stack also means that any composition within the target layer stack is also taken into account 9 | ``` 10 | 11 | ~~~admonish example title="composition of furniture_workbench01.usda's `/root` prim" 12 | ![](../images/terminology/composition.png) 13 | 14 | The example may look complex and confusing, but all it says is that the prim at path `/root` has contributions from all the layers (specifically, their Layer Stacks) listed. 15 | The `Arc Type` column indicates _how_ those layers contribute to the final "specification" of `/root` (more on that later). 16 | 17 | ~~~ 18 | 19 | --- 20 | 21 | ```admonish note title="" 22 | ↪ [USD Glossary - Composition](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-composition) 23 | ``` -------------------------------------------------------------------------------- /src/terminology/composition_arcs.md: -------------------------------------------------------------------------------- 1 | # Composition Arcs 2 | 3 | USD's composition engine utilizes a few different ways of composing, these are known as Composition Arcs. Simply put, they are a set of operators that determine how layer stacks and their opinions are combined together. 4 | 5 | Let's look in more depth about each different composition arc type. 6 | 7 | --- 8 | 9 | ```admonish note title="" 10 | ↪ [USD Glossary - Composition Arcs](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-compositionarcs) 11 | ``` -------------------------------------------------------------------------------- /src/terminology/default_prim.md: -------------------------------------------------------------------------------- 1 | # Default Prim 2 | 3 | When authoring a layer, it is possible to also define a "default prim" for it. This is a layer metadatum that contains the name of the prim that should be used automatically when the layer is used in a reference or payload composition arc without an explicit prim path. 4 | 5 | This name must point to a root level prim, meaning a direct child of the `PseudoRoot`. Therefore, it is not allowed to point to a path. 6 | 7 | ```admonish example title ="example defaultPrim in layer metadata" 8 | ~~~ 9 | #usda 1.0 10 | ( 11 | defaultPrim = "PrimName" 12 | ) 13 | 14 | def "PrimName" {} 15 | ~~~ 16 | ``` 17 | 18 | ```admonish error title ="Invalid defaultPrim" 19 | ~~~ 20 | #usda 1.0 21 | ( 22 | defaultPrim = "PrimName/NestedPrim" 23 | ) 24 | 25 | def "PrimName" { 26 | def "NestedPrim" {} 27 | } 28 | ~~~ 29 | ``` 30 | 31 | If `defaultPrim` has not been explicitly authored, USD will trigger a "unresolved reference prim path" warning and the target layer will not compose correctly. 32 | 33 | ``` 34 | Warning: ... In : Unresolved reference prim path @.../defaultPrim.usda@ ... 35 | ``` 36 | 37 | ```admonish tip title="" 38 | **It is recommended to always specify `defaultPrim` on layers that will be used as references or payloads** 39 | ``` 40 | 41 | ## Example 42 | Let's take a look at a very simple example case. There are two layers, one that defines multiple prims at its root (`defaultPrim.usda`), and one that references it (`reference.usda`). 43 | 44 | ```admonish example title="defaultPrim.usda" 45 | ~~~ 46 | #usda 1.0 47 | ( 48 | defaultPrim = "CubePrim" 49 | ) 50 | 51 | def Cube "CubePrim" {} 52 | def Sphere "SpherePrim" {} 53 | def Cone "ConePrim" {} 54 | ~~~ 55 | ``` 56 | 57 | Do note that `reference.usda` only references the layer itself and does not specify a particular prim to reference in from `defaultPrim.usda` 58 | ```admonish example title="reference.usda" 59 | ~~~ 60 | #usda 1.0 61 | 62 | def "reference"( 63 | prepend references= @defaultPrim.usda@ 64 | ) { 65 | } 66 | ~~~ 67 | ``` 68 | 69 | When opening the `reference.usda` layer inside a `usdview` stage, we see that only one prim is brought into its Layer Stack, and that is the `Cube`. 70 | 71 | ```admonish example title="" 72 | ![](../images/terminology/defaultPrim_cube.png) 73 | ``` 74 | 75 | When changing the default prim metadatum to for example `defaultPrim = "SpherePrim"`, the `Sphere` will now be referenced in instead. 76 | 77 | ```admonish example title="" 78 | ![](../images/terminology/defaultPrim_sphere.png) 79 | ``` 80 | 81 | Removing the `defaultPrim` metadatum altogether will yield an empty reference arc. The layer itself is still referenced, but none of the prims in it are composed. 82 | 83 | ```admonish example title="" 84 | ![](../images/terminology/defaultPrim_empty.png) 85 | ``` 86 | 87 | --- 88 | 89 | ```admonish error title="" 90 | ↪ No USD Glossary Entry! 91 | ``` -------------------------------------------------------------------------------- /src/terminology/edittarget.md: -------------------------------------------------------------------------------- 1 | # EditTarget 2 | 3 | When opening a layer in a stage, and you make edits to the scene graph, these edits are by default recorded onto the "Root Layer" (the layer used to create the stage). 4 | 5 | In the scenario of a complex composition consisting out of many layers and composition arcs, it is not out of the ordinary to want to make edits to one of those layers. Rather than opening said layer individually and applying the edits there, USD offers something called an `EditTarget`. This `EditTarget` allows you, as the user, to specify to USD which _layer_ edits should get recorded to (edits being: overrides, hierarchy changes, etc...). 6 | 7 | With this mechanism users can work in a fully composed scene, yet still be able to record edits to individual layers used in this composition. Think of it as changing the active layer in a Photoshop document. 8 | 9 | ```admonish tip title="" 10 | This is a core workflow in USD 11 | ``` 12 | 13 | 14 | ```admonish tip="Session Layers" 15 | Usd by default also creates something called a "Session Layer" when creating a stage. 16 | 17 | This is a "scratch space" that can used as an EditTarget where users can record any edits without targeting any of the original layers. 18 | 19 | This Session Layer sits at the top of the stage's layer stack (stages also have layer stacks) and acts as any other layer in a layer stack. If set as an EditTarget, opinions expressed in this session layer are always the strongest. 20 | ``` 21 | 22 | ![](../images/terminology/edittarget.png) 23 | 24 | --- 25 | 26 | ```admonish note title="" 27 | ↪ [USD Glossary - EditTarget](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-edittarget) 28 | ``` -------------------------------------------------------------------------------- /src/terminology/inherits.md: -------------------------------------------------------------------------------- 1 | # Inherits 2 | 3 | Very similar to the concept of "inheritance" in programming. Prims can "inherit" other prims (concrete or abstract), meaning that they reflect the hierarchy and properties defined in the prim that they are inheriting from. This also means that if a change is authored on the base prim or its hierarchy, any prims that inherit it immediately get those changes applied to them. 4 | 5 | Within context of a singular layer, inherits does not offer a noticeable difference between it and a local reference. However, when using inheritance in a multi-layer composition environment, it does differ. References tend to become fully encapsulated within the layer stack they're referenced. Meaning that references loose any sense of "connectivity" to their referred layers outside of their layer stack. Inherits on the other hand are always live, no matter how deeply nested within a composition, or how many redefinitions of its base. A prim is always able to backtrack to its original "base", regardless of composition depth! 6 | 7 | ```admonish warning title="" 8 | Prims cannot inherit from an ancestor or descendant, inherit "bases" should be defined as siblings or outside of the target prim's hierarchy, for example at the root level 9 | ``` 10 | 11 | ## Example → Simple inherits 12 | 13 | `SomeScope`, `SomeMesh` and `SomeTransform` are defined prims of differing types, but all inherit from an abstract class prim named `_Base` . This class prim defines two Xform children, `Foo` and `Bar`. 14 | Due to `_Base` being a class, it does not automatically show up in the hierarchy as class prims are not taken into account in default [Stage Traversal](./stage_traversal.md). So we have to explicitly tell `USDView` to also display `Abstract Prims` 15 | 16 | ~~~admonish example title="Definition of `_Base`" 17 | ![](../images/terminology/inherits_base.png) 18 | ~~~ 19 | 20 | Inheriting from `_Base` results in having its hierarchy grafted underneath each prim that inherits it. 21 | 22 | ```admonish example title="Simple inherits" 23 | ![](../images/terminology/inherits_1.png) 24 | ``` 25 | 26 | Modifying `_Base` would be reflected immediately on all prims that inherit from it, without having to do anything to these prims. In this case, a new child prim was added under `/_Base/Bar` called `Baz` 27 | 28 | ~~~admonish example title="Modified `_base`" 29 | ![](../images/terminology/inherits_2.png) 30 | ~~~ 31 | 32 | --- 33 | 34 | ```admonish note title="" 35 | ↪ [USD Glossary - Inherits](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-inherits) 36 | ``` -------------------------------------------------------------------------------- /src/terminology/instancing.md: -------------------------------------------------------------------------------- 1 | # Instancing 2 | 3 | Instancing is a mechanism in USD where layers can be designed to save memory and composition complexity. 4 | When a layer is for example referenced onto a prim, USD will re-compose the entire hierarchy for each reference in that layer, even if all references point to the same layer. 5 | 6 | With instancing however, USD will create a "Prototype" of this reference's composed result behind the scenes, and every reference to this layer is replaced by a local-reference to this prototype prim instead. Enabling USD to compose the referenced layer's layer stack only once. 7 | 8 | ```admonish warning title="" 9 | This concept does however come with a caveat, _overrides defined on prims underneath the prim that holds the reference are ignored_. 10 | ``` 11 | 12 | ```admonish example title="Many bottles reference the same layer" 13 | ![](../images/terminology/instancing_1.png) 14 | ``` 15 | 16 | All selected prims in the example above reference `chemistry_bottle01.usda`, but are also marked as instanceable via the `instanceable = true` metadatum. 17 | This metadatum tells USD that it should only compose the `chemistry_bottle01.usda` once in a `__Prototype` prim. When having done so, all references _internally_ to `chemistry_bottle01.usda` are actually local prim references to the prototype prim (in this case `__Prototype_37`). 18 | 19 | ```admonish example title="bottle prototype prim" 20 | ![](../images/terminology/instancing_2.png) 21 | ``` 22 | 23 | ```admonish warning title="" 24 | When a prim is marked as an instance, [Stage Traversal](../intermediate/stage_traversal.md) will also halt at this prim! 25 | ``` 26 | 27 | --- 28 | 29 | ```admonish note title="" 30 | ↪ [USD Glossary - Instancing](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-instancing) 31 | ``` -------------------------------------------------------------------------------- /src/terminology/isa_schemas.md: -------------------------------------------------------------------------------- 1 | # IsA (Typed) Schema 2 | 3 | "Is A prim this"-kind of schema. Essentially the schema definition that defines the "type" of prim. 4 | 5 | ```admonish example title="Prim Type Schema" 6 | ![](../images/terminology/schemas_3.png) 7 | ``` 8 | 9 | In the image above, the `Type` column lists which `IsA Schema` the prim subscribes to. 10 | 11 | When looking at the USD "code", the keyword between `def` and the name of the prim signifies which `IsA Schema` the prim should subscribe to. 12 | 13 | ``` 14 | def Xform "MyTransform" {} # MyTransform subscribes to the Xform IsA Schema 15 | def Cube "MyCube" {} # MyCube subscribes to the Cube IsA Schema 16 | def "EmptySpec" {} # EmptySpec is a valid prim, it simply has no default set of properties attached to it. It could literally be anything. 17 | ``` 18 | 19 | ```admonish warning title="" 20 | Prims cannot subscribe to more than _1_ IsA schema! 21 | ``` 22 | 23 | ## IsA Schema Example -> UsdGeomCube 24 | 25 | In the example below you can see the schema definition for our favorite `Cube`. It defines that `Cube` inherits from `Gprim` (a base for all drawable prims), metadata for the type (like documentation string) and two attributes. `size` and `extent`. 26 | 27 | ~~~admonish example title="Cube schema definition" 28 | ``` 29 | class Cube "Cube" ( 30 | inherits = 31 | doc = """Defines a primitive rectilinear cube centered at the origin. 32 | 33 | The fallback values for Cube, Sphere, Cone, and Cylinder are set so that 34 | they all pack into the same volume/bounds.""" 35 | customData = { 36 | dictionary extraPlugInfo = { 37 | bool implementsComputeExtent = true 38 | } 39 | } 40 | ) { 41 | double size = 2.0 ( 42 | doc = """Indicates the length of each edge of the cube. If you 43 | author \\em size you must also author \\em extent. 44 | 45 | \\sa GetExtentAttr()""" 46 | ) 47 | 48 | float3[] extent = [(-1.0, -1.0, -1.0), (1.0, 1.0, 1.0)] ( 49 | doc = """Extent is re-defined on Cube only to provide a fallback value. 50 | \\sa UsdGeomGprim::GetExtentAttr().""" 51 | ) 52 | 53 | } 54 | ``` 55 | ~~~ 56 | 57 | Creating new prim types can be as easy as the above, or as complex as defining an entire `Mesh`. 58 | 59 | --- 60 | 61 | ```admonish note title="" 62 | ↪ [USD Glossary - IsA Schema](https://graphics.pixar.com/usd/release/glossary.html#isa-schema) 63 | ``` 64 | -------------------------------------------------------------------------------- /src/terminology/kind.md: -------------------------------------------------------------------------------- 1 | # Kind 2 | 3 | _Kind_ is a prim-level metadatum that can be used to "categorize" prims and their descendants into higher level concepts than just their definitions (ex. `Mesh`, `Sphere`, `Cube`, etc...). 4 | 5 | ```admonish example title="Example Applied Kind" 6 | ![kind](../images/terminology/kind.png) 7 | ``` 8 | 9 | USD ships with a few different `kind`s that can be used to categorize prims 10 | 11 | | Kind Name | What it does | 12 | |--------------|-----------| 13 | | **model** | base class for all model kinds. `model` is considered an abstract type and should not be assigned as any prim’s kind| 14 | | **group** | models that simply group other models| 15 | | **assembly** | an important group model, often a published asset or reference to a published asset| 16 | | **component** | a "leaf model" that can contain no other models| 17 | | **subcomponent** | an identified, important "sub part" of a component model| 18 | 19 | ```admonish tip title="" 20 | You can add new `kind` types via USD Plugins! 21 | ``` 22 | 23 | 24 | Using kind can greatly speed up finding the "right" types of prims you may be interested in during Stage Traversal. Kind annotations can be used to selectively prune entire prim child-trees for instance. 25 | 26 | 27 | ## How kind can be used 28 | 29 | Taking a look at the root layer of [Animal Logic ALab](https://animallogic.com/alab/), we can see that top-level prims can be annotated as `assembly`, this allows for easily identifying "assets" within the scene. In the example below, both `lab_workbench01_0001` and its parent `alab_set01` are annotated as assemblies. 30 | 31 | ```admonish example title="lab_workbench01_0001" 32 | ![](../images/terminology/kind_assembly.png) 33 | ``` 34 | 35 | An `assembly` annotated prim by itself can contain other prims with varying types of `kind`s. Looking deeper in the example above, we can see that the workbench itself at `/root/alab_set01/lab_workbench01_0001/workbench01` is marked as a `group`. 36 | 37 | ```admonish example title="workbench01" 38 | ![](../images/terminology/kind_group.png) 39 | ``` 40 | 41 | And diving even deeper, `/root/alab_set01/lab_workbench01_0001/workbench01/furniture_workbench01_0001` is a `component`. Component should not contain any other `kind` types that derive from `model`, but it can have `subcomponent` kinds. 42 | 43 | ```admonish example title="furniture_workbench01_0001" 44 | ![](../images/terminology/kind_component.png) 45 | ``` 46 | 47 | These `component`s can then be used for efficient discovery and instancing without having the need to dive deeper into their own hierarchies. 48 | 49 | ```admonish note title="" 50 | Production environments differ, so one studio's idea of an `asset` may differ from another, but the idea of `kind` based categorization is incredibly valuable 51 | ``` 52 | 53 | --- 54 | 55 | ```admonish note title="" 56 | ↪ [USD Glossary - Kind](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-kind) 57 | ``` -------------------------------------------------------------------------------- /src/terminology/layer.md: -------------------------------------------------------------------------------- 1 | # Layer 2 | 3 | A Layer is a collection of Prims and their Properties that can be saved to/loaded from disk or memory. As such, it can be considered a "saveable hierarchy". 4 | 5 | Standard USD Layers can be represented on-disk via 6 | 7 | | Extension | Description | 8 | |--------------|-----------| 9 | | `.usda` | ASCII Text, human-readable format | 10 | | `.usdc` | USD Crate file format. High performance binary not human-readable format | 11 | | `.usd` | either Crate or Text | 12 | | `.usdz` | uncompressed and packaged format (.zip) | 13 | 14 | ```admonish info title="" 15 | USD allows for extending what you can load as a "Layer" via a special kind of plugin (`SdfFileFormat`). In fact, the file types listed above are actually all plugins of this type. 16 | Using this `SdfFileFormat` plugin type, it is for example possible to also support loading `.fbx`, `.abc`, `.obj` (or anything really) in Usd. 17 | ``` 18 | 19 | --- 20 | 21 | ```admonish note title="" 22 | ↪ [USD Glossary - Layer](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-layer) 23 | ``` -------------------------------------------------------------------------------- /src/terminology/layer_stacks.md: -------------------------------------------------------------------------------- 1 | # Layer Stack 2 | 3 | Each layer internally keeps track of a "local" stack of layers that contribute to that layer. This stack is an ordered collection of layers used within this layer that contribute to its hierarchy and [composition](./composition.md). 4 | 5 | ```admonish example title="furniture_workbench01.usda layer stack" 6 | ![](../images/terminology/layer_stack.png) 7 | 8 | In the above, the layer `furniture_workbench01.usda` is made out of three other layers and itself. It adds the layers, `furniture_workbench01_modelling.usda`, `furniture_workbench01_surfacing.usda` and `furniture_workbench01_rigging.usda` in that order to its layer stack. Visually this order will look reversed as it is a stack after all, but the higher on the stack, the more "important" a layer is. 9 | ``` 10 | 11 | ```admonish info title="" 12 | A layer's Layer Stack always has its own data at the top of the stack, making itself the most important. 13 | ``` 14 | 15 | --- 16 | 17 | ```admonish note title="" 18 | ↪ [USD Glossary - LayerStack](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-layerstack) 19 | ``` -------------------------------------------------------------------------------- /src/terminology/list_editing.md: -------------------------------------------------------------------------------- 1 | # List-Editing 2 | 3 | List editing is a feature within USD that allows for non-destructively editing list-typed elements within a scenegraph. You can append, prepend or delete items from a list during composition. Or even explicitly override the entire list. This is generally referring to references, relationships, custom metadata, inherits, specializations and variantsets. Attributes of a list-type cannot be list-edited. 4 | 5 | In the example below, we override the list of references on a prim to also prepend a new reference to another layer. This results in the prim referring to two layers (assuming the original definition only points to a single layer). 6 | 7 | ~~~admonish example title="Example list-editing references" 8 | ``` 9 | #usda 1.0 10 | 11 | over "World" 12 | { 13 | over "Foo" 14 | { 15 | # Override "Bar" to also reference baz.usd in addition to its original references 16 | over "Bar" ( 17 | prepend references = @./baz.usd@ 18 | ) 19 | { 20 | } 21 | } 22 | } 23 | ``` 24 | ~~~ 25 | 26 | --- 27 | 28 | ```admonish note title="" 29 | ↪ [USD Glossary - List-Editing](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-list-editing) 30 | ``` -------------------------------------------------------------------------------- /src/terminology/local_sublayer.md: -------------------------------------------------------------------------------- 1 | # Local/Sublayer 2 | 3 | Layers can sublayer other layers, grafting multiple layer stacks together in order into one. Sublayering is in fact how Layer Stacks are made! 4 | 5 | ```admonish danger title="" 6 | _Order matters_ when sublayering. 7 | ``` 8 | 9 | To emphasize how order matters, given a `Cube` prim at path `/Foo` in `layer_a.usd` and a `Sphere` prim at path `/Foo` in `layer_b.usd`; when sublayering both in `layer_c.usd`, the final type of `/Foo` will depend solely on the _order_ in which `layer_a.usd` and `layer_b.usd` are brought in. 10 | 11 | ```admonish example title="Simple Sublayering Example" 12 | Below we have three layers, `a_cube.usd`, `a_sphere.usd` and `cube_and_sphere.usd` 13 | 14 | `a_cube` and `a_sphere` define a Cube and Sphere prim respectively. `cube_and_sphere` does not define either but sublayers both previous layers, essentially combining the two hierarchies into one defined in `cube_and_sphere`'s layer stack. 15 | 16 | ![](../images/terminology/sublayer.png) 17 | ``` 18 | 19 | ```admonish warning title="" 20 | Sublayering grafts layers together at their roots! If you wish to combine layers at different levels of a hierarchy, use the [reference](./reference.md) composition arc 21 | ``` 22 | 23 | --- 24 | 25 | ```admonish note title="" 26 | ↪ [USD Glossary - SubLayers](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-sublayers) 27 | ``` -------------------------------------------------------------------------------- /src/terminology/metadata.md: -------------------------------------------------------------------------------- 1 | # Metadata 2 | 3 | Prims, their properties and the layers they are part of can have metadata applied to them. This is additional _static_ (as in, it can not change over time) data that USD or a user can read, use or define. 4 | 5 | Metadata can be used to describe behavior, incur meaning, represent documentation, etc. USD comes bundled with an extensive suite of metadata out of the box. 6 | 7 | ```admonish tip title="" 8 | Developers can define new metadata via USD Plugins! 9 | ``` 10 | 11 | ## Simple Metadata Examples 12 | 13 | ### Layer Metadata 14 | 15 | ```admonish example title="" 16 | ![StageMetadata](../images/terminology/metadata_stage.png) 17 | ``` 18 | 19 | In the image above, the [PseudoRoot](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-pseudoroot) at path `/` has been selected and the metadata panel in `usdview` has been highlighted. This root represents the `entry.usda` layer from [Animal Logic ALab](https://animallogic.com/alab/). `entry.usda` defines metadata that can be inspected and presents the following information to the user about itself: 20 | - The linear units used are `0.01` meters (i.e. centimeters) → `metersPerUnit = 0.01` 21 | - The scene's up axis is `Y` → `upAxis = Y` 22 | - Two layers contribute to the scene (more about this later in [Local/Sublayer](./local_sublayer.md)) → `subLayers = [...]` 23 | - Animation is present between time code `1004.0` and `1057.0` with `24.0` frames and time codes per second. 24 | - `startTimeCode = 1004.0` 25 | - `endTimeCode = 1057.0` 26 | - `framesPerSecond = 24.0` 27 | - `timeCodesPerSecond = 24.0` 28 | 29 | ```admonish warning title="" 30 | Do note that while a lot of metadata is just informational data, a large part of the core metadata suite also has side effects that contribute to how USD works internally. 31 | 32 | For example, `metersPerUnit` is purely informative, whereas `subLayers` has profound effects when edited! 33 | ``` 34 | 35 | 36 | ```admonish note title="" 37 | Other USD hosts like Autodesk Maya or Sidefx Houdini may choose to interpret and act on metadata where USD itself does not 38 | ``` 39 | 40 | ### Prim Metadata 41 | 42 | ```admonish example title="" 43 | ![StageMetadata](../images/terminology/metadata.png) 44 | ``` 45 | 46 | Metadata on Prims can infer a lot of information about the prim itself, how it is used in the scene (aka [Composition](./composition.md)), what kind of properties it has, etc. 47 | 48 | From the above we know that the prim at `/root/alab_set01/lab_electronics01_0001/bench01/decor_paper_notej01_0001` 49 | 50 | - Is an `Xform` → `typeName = Xform` 51 | - It is instanced (more about [Instancing](./instancing.md) later) → `instanceable = true` 52 | - Has two VariantSets (more about [VariantSets](./variantset.md) later) → `geo` and `geo_vis` 53 | - Is categorized as a `component` (more about the [Kind](./kind.md) metadatum later) → `kind = component` 54 | - Etc. 55 | 56 | ### Property Metadata 57 | 58 | ```admonish example title="" 59 | ![StageMetadata](../images/terminology/metadata_prop.png) 60 | ``` 61 | 62 | Lastly, there is property metadata. This data is meant to give fine grained information about the property itself. For example 63 | 64 | - What type it is → `typename = double3` 65 | - Whether it can change over time → `variability = Sdf.VariabilityVarying` 66 | - Is it a custom "out-of-schema" (see [Schemas](./schemas.md) later) property → `custom = false` 67 | 68 | --- 69 | 70 | ```admonish note title="" 71 | ↪ [USD Glossary - Metadata](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-metadata) 72 | ``` -------------------------------------------------------------------------------- /src/terminology/opinions.md: -------------------------------------------------------------------------------- 1 | # Opinions 2 | 3 | Circling back to properties, when you set a value on an attribute or metadatum or author a relationship within a layer, you are effectively expressing an opinion on that value. This is named an opinion because value assignments can always be changed by others! _This is a very important concept for composition._ 4 | 5 | A different way of looking at this would be that "setting a value" implies that that action is final and the value itself becomes immutable; whereas with opinions you merely mean 6 | ```admonish quote title="" 7 | "Within this layer, I want the value for this to be ``" 8 | ``` 9 | 10 | If the value already existed before, you are essentially "overriding" it 11 | 12 | --- 13 | 14 | ```admonish note title="" 15 | ↪ [USD Glossary - Opinion](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-opinions) 16 | ``` -------------------------------------------------------------------------------- /src/terminology/overrides.md: -------------------------------------------------------------------------------- 1 | # Overrides 2 | 3 | 4 | When expressing an opinion within a layer, it is possible to "redefine" a previously defined value of the property being edited. This mechanism is known as `overrides` because you are _overriding_ what was there before. 5 | However, it is very important to note that the _original data_ remains unchanged. **The override only exists within the layer where you are defining it** 6 | 7 | This is by far _the most important_ aspect to understand about USD. Opinions and their "value resolution" (resolving which value gets applied in the end) are key to the entire composition mechanism. 8 | 9 | Below is a simple example of overriding a previously defined attribute's opinion. 10 | 11 | ```admonish example title="override example" 12 | [![schematic](../images/terminology/overrides.png)](../images/terminology/overrides.png) 13 | 14 | 1. Shows `cube_sphere_torus.usda` where an attribute's [opinion] is first authored (`/GEO/Cube.size`) 15 | 2. Shows `referenced.usda` where 16 | * The layer `cube_sphere_torus.usda` is brought into the layer `referenced.usda` via a [composition] mechanism called `referencing` 17 | * An opinion is expressed on the already defined attribute `/GEO/Cube.size`, but in context of `cube_sphere_torus.usda`, essentially overriding what was there before 18 | 3. Shows the composed final result, aka the [stage] 19 | ``` 20 | 21 | [composition]: composition.md 22 | [opinion]: opinions.md 23 | [stage]: stage.md 24 | 25 | --- 26 | 27 | ```admonish note title="" 28 | ↪ [USD Glossary - Override](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-override) 29 | ``` 30 | -------------------------------------------------------------------------------- /src/terminology/path.md: -------------------------------------------------------------------------------- 1 | # Path 2 | 3 | Prims and properties are identified by unique `paths` inside the scene hierarchy. They are a textual representation of a hierarchy - similar to folder paths in most operating systems - where each prim is separated from its parent or child via the `/` delimiter. 4 | 5 | Just like folders, paths can be relative or absolute. Absolute paths always start with `/` 6 | 7 | ```admonish info title="" 8 | `/` is a special path in USD. This is known as the [PseudoRoot](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-pseudoroot) 9 | ``` 10 | 11 | In the example below, the highlighted path `/root/remi/head_M_hrc/GEO/head_M_hrc/eyeScrew_L_geo` is a path to a prim with the name `eyeScrew_L_geo`. Constructed from the following hierarchy: `/` → `root` → `remi` → `head_M_hrc` → `GEO` → `head_M_hrc` → `eyeScrew_L_geo`. 12 | 13 | ```admonish example title="Prim Path Example" 14 | ![](../images/terminology/prim_path.png) 15 | ``` 16 | 17 | As for properties, taking the previous example, inspecting the `points` attribute yields the path `/root/remi/head_M_hrc/GEO/head_M_hrc/eyeScrew_L_geo.points`. Property paths are constructed by appending the property name to a prim path, delimited by a `.` character. 18 | 19 | ```admonish example title="Property Path Example" 20 | ![](../images/terminology/property_path.png) 21 | ``` 22 | 23 | ```admonish warning title="" 24 | Paths in USD are name based, and this means you cannot define the same path twice. In practice this means that you cannot have two or more _sibling_ prims with the same name. 25 | ``` 26 | 27 | --- 28 | 29 | ```admonish note title="" 30 | ↪ [USD Glossary - Path](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-path) 31 | ``` 32 | -------------------------------------------------------------------------------- /src/terminology/payload.md: -------------------------------------------------------------------------------- 1 | # Payload 2 | 3 | Payloads are lazily loaded references. When a prim uses a payload, USD can be told to opt out of loading these layers unless the user requests to do so. 4 | 5 | When a referenced layer is heavy due to the amount of data or hierarchy complexity, it is often beneficial to have the user manually load those in after opening the layer in a stage. Generally speaking, non-important layers should be behind payloads. If they're not loaded, they also cannot be traversed and should not contain anything considered "important". 6 | The definition of "important" depends entirely on the use case of course. 7 | 8 | ## Example → Putting a high res model behind a payload 9 | 10 | With unloaded payloads, the resulting hierarchy looks like this 11 | ```admonish example title="Unloaded Payload" 12 | ![unloaded](../images/terminology/payload_1.png) 13 | ``` 14 | 15 | However, the payload can be toggled on/off after the stage has been loaded. 16 | 17 | ```admonish example title="Payload Toggle On/Off" 18 | ![loaded](../images/terminology/payload_example.gif) 19 | ``` 20 | 21 | As a result, the full hierarchy is loaded 22 | 23 | ```admonish example title="Loaded Payload" 24 | ![unloaded](../images/terminology/payload_2.png) 25 | ``` 26 | 27 | ~~~admonish example title="simple_payload_example.usd" collapsible=true 28 | ``` 29 | #usda 1.0 30 | ( 31 | defaultPrim = "Asset" 32 | ) 33 | 34 | def Scope "Asset" 35 | { 36 | def Xform "Geometry" 37 | ( 38 | prepend payload=@./highres_model.usd@ 39 | ) 40 | { 41 | } 42 | } 43 | ``` 44 | ~~~ 45 | 46 | --- 47 | 48 | ```admonish note title="" 49 | ↪ [USD Glossary - Payload](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-payload) 50 | ``` -------------------------------------------------------------------------------- /src/terminology/prims.md: -------------------------------------------------------------------------------- 1 | # Prims 2 | 3 | Short for _Primitive_, and a quintessential component of USD. 4 | Prims are the nodes within a hierarchy and can thus have parent/child relationships with other prims; meaning that prims can have other prims as children or siblings, or have another prim as a parent. 5 | 6 | In the image below, every node in the hierarchy is a prim. 7 | ```admonish example title="Prim Example" 8 | ![Prims in USD View](../images/terminology/prim.png) 9 | ``` 10 | 11 | The keen-eyed will notice that prims can have a _type_. `Xform`, `Mesh`, `Scope` and `Material` are specific prim types. 12 | These types come with default behavior and "data", the mechanism of which is explained in a later chapter. 13 | 14 | ```admonish info title="" 15 | Users are also able to define their own Prim types 16 | ``` 17 | 18 | While Prims themselves indicate what "type" of scene element they are, they do not necessarily possess data themselves. However, they can be considered "containers" for named data, this data is generally expressed as [Properties](./properties.md). 19 | 20 | --- 21 | 22 | ```admonish note title="" 23 | ↪ [USD Glossary - Prim](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-prim) 24 | ``` 25 | -------------------------------------------------------------------------------- /src/terminology/properties.md: -------------------------------------------------------------------------------- 1 | # Properties 2 | 3 | [Prims](./prims.md) can have Properties, which are essentially named and typed data. 4 | 5 | A `Property` within USD is actually a collective term for two distinct types of Properties: 6 | 7 | ```admonish abstract title="Attributes" 8 | Attributes are Properties with direct values that may vary over time 9 | ![](../images/terminology/attributes.png) 10 | ``` 11 | 12 | ```admonish abstract title="Relationships" 13 | Relationships are Properties that point to other properties or [Prims](./prims.md) 14 | ![](../images/terminology/relationships.png) 15 | ``` 16 | 17 | In the above, you can see that properties are made up from a `name` and a typed `value` 18 | 19 | These property names can also be namespaced. A property name can have 1 or more namespace identifiers separated by `:`. 20 | Looking closer at the relationship example, the property name `material:binding` is actually namespaced. The property's name itself is `binding` and it is part of a `material` namespace. 21 | 22 | Namespaces can be used to categorize or group properties together. 23 | 24 | --- 25 | 26 | ```admonish note title="" 27 | ↪ [USD Glossary - Property](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-property) 28 | ``` -------------------------------------------------------------------------------- /src/terminology/purpose.md: -------------------------------------------------------------------------------- 1 | # Purpose 2 | 3 | 4 | _Purpose_ is an attribute that can be used to give a prim and its descendants a high-level "visibility flag" in context of rendering. 5 | 6 | For example, if a prim has its `purpose` attribute set to `render`, it will be excluded from being drawn in a renderer that only wants to draw `proxy` prims. 7 | 8 | In some sense, setting purpose could be considered [Stage Traversal](./stage_traversal.md) but for rendering. 9 | 10 | 11 | Currently, only 4 values are supported by the `purpose` attribute: 12 | 13 | | Purpose | Description | 14 | |--------------|-----------| 15 | | `default` | The prim has no special rendering purpose and it will be included in all rendering paths | 16 | | `guide` | A prim tree marked with `guide` is generally used by interactive applications that have asked to show "guides". Think of it as requesting to visualize controller geometry for rigs, skeleton data, etc | 17 | | `proxy` | Proxy is usually reserved for a lightweight representation of another object to be used in an interactive renderer such as a DCC viewport | 18 | | `render` | The "final quality" data to be imaged. Usually enabled for offline rendering or final quality rendering | 19 | 20 | 21 | ```admonish warning title="" 22 | Unlike [Kind](./kind.md). `purpose` cannot be extended with custom values! 23 | ``` 24 | 25 | 26 | ```admonish example title="Example Switching between proxy and render Purposes" 27 | ![purpose](../images/terminology/purpose.gif) 28 | ``` 29 | 30 | ```admonish note title="" 31 | As seen above, `purpose` is not an exclusive toggle! It is possible to have both `proxy` _and_ `render` purposes active and their contents drawn to the screen. 32 | ``` 33 | 34 | 35 | `/root/GEO` has its purpose set to `render`, it will only be drawn when the active renderer requests prims with a `render` purpose. 36 | ```admonish example title="Render Purpose" 37 | ![renderpurpose](../images/terminology/purpose_render.png) 38 | ``` 39 | 40 | `/root/GEO_PROXY` has its purpose set to `proxy`, it will only be drawn when the active renderer requests prims with a `proxy` purpose. 41 | 42 | ```admonish example title="Proxy Purpose" 43 | ![proxypurpose](../images/terminology/purpose_proxy.png) 44 | ``` 45 | 46 | 47 | 48 | --- 49 | 50 | ```admonish note title="" 51 | ↪ [USD Glossary - Purpose](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-purpose) 52 | ``` 53 | -------------------------------------------------------------------------------- /src/terminology/reference.md: -------------------------------------------------------------------------------- 1 | # Reference 2 | 3 | ## Layer References 4 | Beyond sublayers, layers can also be grafted underneath prims. Using the example Cube and Sphere from [Local/Sublayer](./local_sublayer.md), we can also create prims and have them point to these layers respectively. 5 | 6 | ```admonish example title="Layer referencing" 7 | ![reference_1](../images/terminology/reference_1.png) 8 | ![reference_2](../images/terminology/reference_2.png) 9 | ``` 10 | 11 | ## Local References 12 | While the general use-case is to use layers when referencing, it is not required to do so. It is entirely possible to add a reference to a prim within the same layer. This is known as a local reference 13 | 14 | ```admonish example title="Local referencing" 15 | ![reference_3](../images/terminology/reference_3.png) 16 | ![reference_4](../images/terminology/reference_4.png) 17 | ``` 18 | 19 | You would merely need to add a reference to the target prim and its entire hierarchy will be grafted underneath: 20 | 21 | ``` 22 | def "ReferenceToFoo"( 23 | prepend references= 24 | ) { 25 | } 26 | ``` 27 | 28 | # Layer Prim References 29 | But, this goes even further! Remember, composition acts on layer stacks, not individual layers; so it is also possible to reference specific prims from another layer's layer stack. Even if these prims themselves are the composed result from the target layer's layer stack 30 | 31 | ```admonish example title="Layer Prim referencing" 32 | ![reference_5](../images/terminology/reference_5.png) 33 | ![reference_6](../images/terminology/reference_6.png) 34 | ``` 35 | 36 | ``` 37 | def "ReferenceToPrim"( 38 | prepend references= @./several_prims.usd@ 39 | ) { 40 | float3 xformOp:translate = (3, 0, 0) 41 | uniform token[] xformOpOrder = ["xformOp:translate"] 42 | } 43 | ``` 44 | 45 | --- 46 | 47 | ```admonish note title="" 48 | ↪ [USD Glossary - Reference](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-reference) 49 | ``` -------------------------------------------------------------------------------- /src/terminology/schemas.md: -------------------------------------------------------------------------------- 1 | # Schemas 2 | 3 | Schemas are the "descriptions" of Prims, properties, metadata, etc... Schemas allow USD to have "knowledge" of what a Prim or its attributes mean. 4 | USD can be extended with new schemas via Plugins to define custom sets of properties, whole new prim types, metadata, and more. 5 | 6 | Schemas are built by authoring the schema definition itself in the .usda file format syntax, which can be used to generate the necessary source code and plugin files. 7 | Without diving into the particulars, USD's default prims and properties are in fact Schemas that Pixar has provided in the source code. 8 | 9 | ```admonish tip title="" 10 | Since USD 21.08, schemas do not require to generate code to be usable, so only the plugin is needed. These are known as `codeless schemas` 11 | ``` 12 | 13 | Generally there are two types of schemas users can author. 14 | 15 | ```admonish abstract title="" 16 | [IsA Schemas](./isa_schemas.md) 17 | ``` 18 | 19 | ```admonish abstract title="" 20 | [API Schemas](./api_schemas.md) 21 | ``` 22 | 23 | --- 24 | 25 | ```admonish note title="" 26 | ↪ [USD Glossary - Schema](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-schema) 27 | ``` -------------------------------------------------------------------------------- /src/terminology/specializes.md: -------------------------------------------------------------------------------- 1 | # Specializes 2 | Specializing is taking a base definition of a prim (and its hierarchy) and further refining it into a specialized version of itself. For example taking a Metal material and specializing certain properties to make a CorrodedMetal material. This specialization could refine certain material properties, redefine or add shaders, textures, etc... It is not dissimilar from inherits, however with one key difference. 3 | 4 | ```admonish failure title="" 5 | _Opinions expressed as specializations always win_\ 6 | ``` 7 | 8 | If you try to express an opinion on a specialized property, your opinion will essentially be discarded. This is not the case however with [inherits](./inherits.md). 9 | 10 | ```admonish warning title="" 11 | You cannot specialize an ancestor or descendant of a prim. Only siblings or prims outside of the Specialization's definition are allowed 12 | ``` 13 | 14 | 15 | ## Example → Corroded Material specialization 16 | 17 | There are two layers, `robot.usd` and `world.usd`. 18 | 19 | ### Robot.usd 20 | `robot.usd` defines a `Robot` prim and three Material prims, `Metal`, `CorrodedMetal` and `InheritedMetal`. `Metal` defines two attributes, `inputs:diffuseGain` and `inputs:specularRoughness`. 21 | 22 | ```admonish example title="robot.usd" 23 | ![](../images/terminology/robot_usd.png) 24 | ``` 25 | 26 | `CorrodedMetal` is a specialization of `Metal` where `inputs:specularRoughness` is the specialized attribute, we say it always has a value of `0.2`. 27 | 28 | ```admonish example title="specialized metal" 29 | ![](../images/terminology/specializes_1.png) 30 | ``` 31 | 32 | ``` 33 | def Material "CorrodedMetal" ( 34 | specializes = 35 | ) 36 | { 37 | # specialize roughness... 38 | float inputs:specularRoughness = 0.2 39 | } 40 | ``` 41 | 42 | Whereas `InheritedMetal` is merely an inherits arc to `Metal` . You will notice that regardless of `inherits` or `specializes`, the result is the same. Both `CorrodedMetal` and `InheritedMetal` take over the base properties of `Metal`, but have an opinion on the `inputs:specularRoughness` attribute. 43 | 44 | ```admonish example title="inherited metal" 45 | ![](../images/terminology/specializes_2.png) 46 | ``` 47 | 48 | ### world.usd 49 | 50 | `world.usda` references `robot.usda` and expresses and opinion on the base `Metal` prim. It says that `inputs:diffuseGain` and `inputs:specularRoughness` are to be 0.3 and 0.1 respectively. 51 | 52 | ~~~admonish example title="world.usd" 53 | ``` 54 | #usda 1.0 55 | 56 | def Xform "World" 57 | { 58 | def "RosieTheRobot" ( 59 | references = @./robot.usda@ 60 | ) 61 | { 62 | over "Materials" 63 | { 64 | over "Metal" 65 | { 66 | float inputs:diffuseGain = 0.3 67 | float inputs:specularRoughness = 0.1 68 | } 69 | } 70 | } 71 | } 72 | ``` 73 | ~~~ 74 | 75 | ### Difference between `Inherits` and `Specializes` 76 | When inspecting the resolved opinions in `world.usd`, notice that the overridden values for `inputs:diffuseGain` and `inputs:specularRoughness` on the base `Metal` propagate fully to `InheritedMaterial`, but not to our specialized `CorrodedMaterial`. 77 | 78 | | Base Metal Override | Result on `InheritedMaterial` | Result on `CorrodedMaterial` | 79 | |--------------|-----------|------------| 80 | | 
over "Metal"
{
    float inputs:diffuseGain = 0.3
    float inputs:specularRoughness = 0.1
}
| ![../images/terminology/specializes_3.png](../images/terminology/specializes_3.png) | ![](../images/terminology/specializes_4.png) | 81 | 82 | As seen above, even when we have a stronger opinion on the base `Metal` definition for both properties, _specializations always win_. 83 | 84 | --- 85 | 86 | ```admonish note title="" 87 | ↪ [USD Glossary - Specializes](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-specializes) 88 | ``` -------------------------------------------------------------------------------- /src/terminology/specifier.md: -------------------------------------------------------------------------------- 1 | # Specifier 2 | 3 | When defining a prim in the scene graph, there are three different ways of doing so. 4 | 5 | ```admonish info title="" 6 | The examples below use the text representation of USD as these concepts are not well visualized in `usdview` 7 | ``` 8 | 9 | ~~~admonish abstract title="**def**" 10 | A concrete definition. This is generally used when you want to define a prim for the very first time, or when a prim needs to be redefined. `def`s _always_ contribute to scene composition. 11 | ``` 12 | def Xform "MyTransform" 13 | { 14 | # ... 15 | } 16 | ``` 17 | 18 | `def` can also be `type-less` and is usually used in context of composition, which will fill in the actual type. 19 | ``` 20 | def "MyPrim" { 21 | # ... 22 | } 23 | ``` 24 | ~~~ 25 | 26 | ~~~admonish abstract title="**over**" 27 | This tells USD that a prim is to be overridden. If the composition engine cannot find the prim targeted by the over specification, the override will be ignored and will not contribute to scene composition. 28 | ``` 29 | over "SomethingThatAlreadyExists" 30 | { 31 | # ... 32 | } 33 | ``` 34 | ~~~ 35 | 36 | ~~~admonish abstract title="**class**" 37 | An abstract prim definition that does not contribute to stage traversal by default. Meaning, it does not show up in the stage hierarchy. Other prims can however, inherit from this class (more on that in the next chapters) 38 | ``` 39 | class "_MyClass" 40 | { 41 | # ... 42 | } 43 | ``` 44 | ~~~ 45 | 46 | --- 47 | 48 | ```admonish note title="" 49 | ↪ [USD Glossary - Specifier](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-specifier) 50 | ``` -------------------------------------------------------------------------------- /src/terminology/stage.md: -------------------------------------------------------------------------------- 1 | # Stage 2 | 3 | The composed result of opening a layer. Think of it as a Photoshop canvas when opening a .PSD document. All the Photoshop layers interact with one another to produce a "final image". The layers still exist, they can still be edited, deleted, replaced, etc... but what you see is the result, and that is the Stage in USD. 4 | 5 | This composed result can be "flattened" and saved to a new layer, which would be similar to taking the aforementioned Photoshop document and exporting it to a JPEG. 6 | 7 | --- 8 | 9 | ```admonish note title="" 10 | ↪ [USD Glossary - Stage](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-stage) 11 | ``` -------------------------------------------------------------------------------- /src/terminology/stage_traversal.md: -------------------------------------------------------------------------------- 1 | # Stage Traversal 2 | 3 | Generally a concept used when programming with USD, but it is important to understand for users too. Stage Traversal is essentially iterating over the scene graph of a layer opened in a stage. Traversal can be filtered via "rules" (or predicates), limited to sub-trees, parts of the hierarchy can be pruned during traversal, and so on. 4 | 5 | By default, USD Stage Traversal will only consider prims that are active, defined, loaded and are not abstract. Depending on which tool is used, users may be able to change this behavior. Using the programming interface however, developers have full control over this behavior. 6 | 7 | ```admonish example title="Toggling Abstract prims in USDView" 8 | ![](../images/terminology/stage_traversal.gif) 9 | 10 | The prim `_root_type` is defined as a `class`, which is considered _abstract_ in USD. When opening the layer it is part of in USDView, it will not be shown in the hierarchy. 11 | However, enabling `Abstract Prims (Classes)` in the `Show` menu of the hierarchy view, any abstract prims like `_root_type` will then be displayed in the hierarchy. Internally, this is modifying the Stage Traversal predicate. 12 | ``` 13 | 14 | --- 15 | 16 | ```admonish note title="" 17 | ↪ [USD Glossary - Stage Traversal](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-stage-traversal) 18 | ``` -------------------------------------------------------------------------------- /src/terminology/terminology.md: -------------------------------------------------------------------------------- 1 | # USD Terminology 2 | 3 | With introductions out of the way, the following chapters will focus exclusively on the core terminology needed to be able to understand USD. It will be much easier to follow any tutorial on USD if you understand the fundamental jargon first. 4 | 5 | It is recommended to read the pages within this chapter in order. 6 | 7 | ```admonish warning 8 | The contents within this chapter do not aim to be exhaustive as many concepts are overly simplified and others are simply missing. 9 | 10 | This is in other words **_not a replacement for the [official USD Glossary](https://graphics.pixar.com/usd/release/glossary.html)_** and it is strongly advised to read those pages afterwards. 11 | ``` -------------------------------------------------------------------------------- /src/terminology/variantset.md: -------------------------------------------------------------------------------- 1 | # VariantSet 2 | 3 | VariantSets and variants allow for authoring a "switchable" state of a prim within a layer. In the example below, a top level prim with the name `Implicits` is authored which defines a VariantSet named `Shape`. This VariantSet defines a few different entries (aka variants ) that each do something different. 4 | 5 | When changing the active variant, USD will inject anything that is defined within that variant into the current composition. In our example, each variant adds a child to `Implicits` with differing types. One is a capsule, another a cube, a sphere, and so on. 6 | 7 | ```admonish example title="Variant/VariantSet example" 8 | ![Variant Sets](../images/terminology/variant_switching.gif) 9 | ``` 10 | 11 | Within variant definitions, you are essentially free to do whatever you want. If you wish to define a complete hierarchy in a variant, you can. Add references to other layers? You can. Expressing opinions on values or metadata, you can. However. 12 | 13 | ```admonish warning title="" 14 | There can only ever be one Variant active at a time for a VariantSet. 15 | ``` 16 | 17 | --- 18 | 19 | ```admonish note title="" 20 | ↪ [USD Glossary - VariantSet](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-VariantSet) 21 | ↪ [USD Glossary - Variant](https://graphics.pixar.com/usd/release/glossary.html#usdglossary-Variant) 22 | ``` -------------------------------------------------------------------------------- /src/usd_primer.md: -------------------------------------------------------------------------------- 1 | # So, what even is ![](./images/usd_icon_small.png) USD? 2 | 3 | In short, USD is a way to describe 3D-Scene Hierarchies. 4 | 5 | ```admonish example title="Example USD Scene" 6 | ![](./images/alab2.png) 7 | [Animal Logic ALab](https://animallogic.com/alab/) USD Scene, inside USDView 8 | ``` 9 | 10 | Generally speaking, hierarchies consist of entries (aka. `nodes`) that have parent/child/sibling relationships with other nodes. 11 | In USD, these nodes can have "physicality" (think of Geometry, Animation data, etc...) or be more abstract like grouping items, materials, shaders, and even "settings" can be expressed as a node within a hierarchy. 12 | 13 | Where USD differs greatly from other scene descriptions, is in its ability to combine hierarchies together with varying types of behavior (this is known as [composition](./basic/composition.md)). Within USD you can non-destructively refer to- or graft other hierarchies together, re-define previously defined data, collaborate with many others on the same hierarchy, and much more. 14 | 15 | ```admonish example title="Example USD Scene Composition" 16 | ![](./images/alab_root_layer_stack.png) 17 | Part of the list of USD scenes that make up the composition of [Animal Logic ALab](https://animallogic.com/alab/) USD Scene, inside USDView 18 | ``` 19 | 20 | ## But wait! There's more! 21 | 22 | Beyond non-destructively combining hierarchies, USD is built to be extensible. 23 | For instance, extending USD with a plugin that can parse a bespoke or commercially available file format and use those files directly inside USD. 24 | 25 | ```admonish note title="" 26 | A concrete example would be to support using FBX files directly inside a USD hierarchy 27 | ``` 28 | 29 | All in all, USD aims to be a portable interchange format by defining a shared "language" sort to speak to describe scene and 3D data. 30 | This idea is not new, but USD takes this a step further by also offering a way to consistently draw/render/image scenes. This is made possible through `Hydra`, USD's backend rendering technology. 31 | 32 | ```admonish warning title="" 33 | This book does not currently cover Hydra concepts, but may do so in the future 34 | ``` 35 | -------------------------------------------------------------------------------- /src/what_is_usd_not.md: -------------------------------------------------------------------------------- 1 | # What is it not? 2 | 3 | ## Just a File Format 4 | 5 | While the main "interface" of working with USD for many artists is through its file-on-disk representation, it's important to consider USD more as an ecosystem than another file type on disk. 6 | Given its abilities and what it can offer, calling it a file format would be a disservice to the technology. 7 | 8 | USD can be molded to your needs or it can be used as-is. File-on-disk representations can be omitted altogether. The way you can refer to other USD scenes is extremely flexible. And you can even integrate any custom rendering engine via a simple plugin so it understands how to work with USD data, etc... 9 | 10 | ```admonish tip title="Hot tip!" 11 | If you use USD enough, it becomes a way of life 😄 12 | ``` 13 | 14 | ## A Replacement for Content _Creation_ 15 | 16 | USD can do a lot of things, but it also cannot do quite a few other things. A major component of its architecture does not allow for _interactive values_. Meaning that values are resolved essentially "only once" and do not change unless the entire scene is "re-composed". In reality the way values are computed is a bit more complex than the aforementioned, but it's easier to think of it this way. 17 | 18 | From a design point of view, USD was built with "low-memory footprint, higher-latency data access" in mind. Thus, in order to allow for low memory usage, data access is slower than in a "high-memory footprint, low-latency access to data" paradigm. The latter sacrifices memory footprint in favor of fast data access, allowing for dynamic evaluations. 19 | 20 | Because of this design decision, USD cannot easily express "dynamic" systems like Rigging which relies on fast dynamically computed data access. It can however via its extensibility allow studios to _define_ rigging concepts. But this is merely a _specification_, the rig itself would not be _evaluated_ inside USD and will require the host software (for example Autodesk Maya) to take that information and translate it into a rig that it can understand. 21 | 22 | ---- 23 | ```admonish note title="" 24 | ↪ [USD Intro - What Can't USD Do](https://graphics.pixar.com/usd/release/intro.html#what-can-t-usd-do) 25 | ``` 26 | -------------------------------------------------------------------------------- /theme/catppuccin-highlight.css: -------------------------------------------------------------------------------- 1 | .mocha code, 2 | .mocha .hljs { 3 | background: #181825; 4 | } 5 | .mocha code .hljs-attr, 6 | .mocha code .hljs-string { 7 | color: #a6e3a1; 8 | } 9 | .mocha code .hljs-tag { 10 | color: #f38ba8; 11 | } 12 | .mocha code .hljs-name { 13 | color: #f2cdcd; 14 | } 15 | .mocha pre .hljs { 16 | background: #181825 !important; 17 | } 18 | .mocha pre .hljs-params { 19 | color: #f38ba8 !important; 20 | } 21 | .mocha pre .hljs-built_in, 22 | .mocha pre .hljs-selector-tag, 23 | .mocha pre .hljs-section, 24 | .mocha pre .hljs-link { 25 | color: #74c7ec !important; 26 | } 27 | .mocha pre .hljs-keyword { 28 | color: #cba6f7 !important; 29 | } 30 | .mocha pre .hljs, 31 | .mocha pre .hljs-subst { 32 | color: #a6adc8 !important; 33 | } 34 | .mocha pre .hljs-title { 35 | color: #89b4fa !important; 36 | } 37 | .mocha pre .hljs-attr, 38 | .mocha pre .hljs-meta-keyword { 39 | color: #a6e3a1 !important; 40 | } 41 | .mocha pre .hljs-type { 42 | color: #89b4fa !important; 43 | } 44 | .mocha pre .hljs-string { 45 | color: #a6e3a1 !important; 46 | } 47 | .mocha pre .hljs-tag { 48 | color: #f38ba8 !important; 49 | } 50 | .mocha pre .hljs-meta, 51 | .mocha pre .hljs-name, 52 | .mocha pre .hljs-symbol, 53 | .mocha pre .hljs-bullet, 54 | .mocha pre .hljs-addition, 55 | .mocha pre .hljs-variable, 56 | .mocha pre .hljs-template-tag, 57 | .mocha pre .hljs-template-variable { 58 | color: #f2cdcd !important; 59 | } 60 | .mocha pre .hljs-addition { 61 | background-color: #181825 !important; 62 | color: #a6e3a1 !important; 63 | } 64 | .mocha pre .hljs-deletion { 65 | background-color: #181825 !important; 66 | color: #f38ba8 !important; 67 | } 68 | .mocha pre .hljs-comment, 69 | .mocha pre .hljs-quote { 70 | color: #585b70 !important; 71 | } 72 | .mocha pre .hljs-keyword, 73 | .mocha pre .hljs-selector-tag, 74 | .mocha pre .hljs-literal, 75 | .mocha pre .hljs-title, 76 | .mocha pre .hljs-section, 77 | .mocha pre .hljs-doctag, 78 | .mocha pre .hljs-type, 79 | .mocha pre .hljs-name, 80 | .mocha pre .hljs-strong { 81 | font-weight: bold !important; 82 | } 83 | .mocha pre .hljs-literal, 84 | .mocha pre .hljs-number { 85 | color: #fab387 !important; 86 | } 87 | .mocha pre .hljs-emphasis { 88 | font-style: italic !important; 89 | } 90 | 91 | .macchiato code, 92 | .macchiato .hljs { 93 | background: #1e2030; 94 | } 95 | .macchiato code .hljs-attr, 96 | .macchiato code .hljs-string { 97 | color: #a6da95; 98 | } 99 | .macchiato code .hljs-tag { 100 | color: #ed8796; 101 | } 102 | .macchiato code .hljs-name { 103 | color: #f0c6c6; 104 | } 105 | .macchiato pre .hljs { 106 | background: #1e2030 !important; 107 | } 108 | .macchiato pre .hljs-params { 109 | color: #ed8796 !important; 110 | } 111 | .macchiato pre .hljs-built_in, 112 | .macchiato pre .hljs-selector-tag, 113 | .macchiato pre .hljs-section, 114 | .macchiato pre .hljs-link { 115 | color: #7dc4e4 !important; 116 | } 117 | .macchiato pre .hljs-keyword { 118 | color: #c6a0f6 !important; 119 | } 120 | .macchiato pre .hljs, 121 | .macchiato pre .hljs-subst { 122 | color: #a5adcb !important; 123 | } 124 | .macchiato pre .hljs-title { 125 | color: #8aadf4 !important; 126 | } 127 | .macchiato pre .hljs-attr, 128 | .macchiato pre .hljs-meta-keyword { 129 | color: #a6da95 !important; 130 | } 131 | .macchiato pre .hljs-type { 132 | color: #8aadf4 !important; 133 | } 134 | .macchiato pre .hljs-string { 135 | color: #a6da95 !important; 136 | } 137 | .macchiato pre .hljs-tag { 138 | color: #ed8796 !important; 139 | } 140 | .macchiato pre .hljs-meta, 141 | .macchiato pre .hljs-name, 142 | .macchiato pre .hljs-symbol, 143 | .macchiato pre .hljs-bullet, 144 | .macchiato pre .hljs-addition, 145 | .macchiato pre .hljs-variable, 146 | .macchiato pre .hljs-template-tag, 147 | .macchiato pre .hljs-template-variable { 148 | color: #f0c6c6 !important; 149 | } 150 | .macchiato pre .hljs-addition { 151 | background-color: #1e2030 !important; 152 | color: #a6da95 !important; 153 | } 154 | .macchiato pre .hljs-deletion { 155 | background-color: #1e2030 !important; 156 | color: #ed8796 !important; 157 | } 158 | .macchiato pre .hljs-comment, 159 | .macchiato pre .hljs-quote { 160 | color: #5b6078 !important; 161 | } 162 | .macchiato pre .hljs-keyword, 163 | .macchiato pre .hljs-selector-tag, 164 | .macchiato pre .hljs-literal, 165 | .macchiato pre .hljs-title, 166 | .macchiato pre .hljs-section, 167 | .macchiato pre .hljs-doctag, 168 | .macchiato pre .hljs-type, 169 | .macchiato pre .hljs-name, 170 | .macchiato pre .hljs-strong { 171 | font-weight: bold !important; 172 | } 173 | .macchiato pre .hljs-literal, 174 | .macchiato pre .hljs-number { 175 | color: #f5a97f !important; 176 | } 177 | .macchiato pre .hljs-emphasis { 178 | font-style: italic !important; 179 | } 180 | 181 | .frappe code, 182 | .frappe .hljs { 183 | background: #292c3c; 184 | } 185 | .frappe code .hljs-attr, 186 | .frappe code .hljs-string { 187 | color: #a6d189; 188 | } 189 | .frappe code .hljs-tag { 190 | color: #e78284; 191 | } 192 | .frappe code .hljs-name { 193 | color: #eebebe; 194 | } 195 | .frappe pre .hljs { 196 | background: #292c3c !important; 197 | } 198 | .frappe pre .hljs-params { 199 | color: #e78284 !important; 200 | } 201 | .frappe pre .hljs-built_in, 202 | .frappe pre .hljs-selector-tag, 203 | .frappe pre .hljs-section, 204 | .frappe pre .hljs-link { 205 | color: #85c1dc !important; 206 | } 207 | .frappe pre .hljs-keyword { 208 | color: #ca9ee6 !important; 209 | } 210 | .frappe pre .hljs, 211 | .frappe pre .hljs-subst { 212 | color: #a5adce !important; 213 | } 214 | .frappe pre .hljs-title { 215 | color: #8caaee !important; 216 | } 217 | .frappe pre .hljs-attr, 218 | .frappe pre .hljs-meta-keyword { 219 | color: #a6d189 !important; 220 | } 221 | .frappe pre .hljs-type { 222 | color: #8caaee !important; 223 | } 224 | .frappe pre .hljs-string { 225 | color: #a6d189 !important; 226 | } 227 | .frappe pre .hljs-tag { 228 | color: #e78284 !important; 229 | } 230 | .frappe pre .hljs-meta, 231 | .frappe pre .hljs-name, 232 | .frappe pre .hljs-symbol, 233 | .frappe pre .hljs-bullet, 234 | .frappe pre .hljs-addition, 235 | .frappe pre .hljs-variable, 236 | .frappe pre .hljs-template-tag, 237 | .frappe pre .hljs-template-variable { 238 | color: #eebebe !important; 239 | } 240 | .frappe pre .hljs-addition { 241 | background-color: #292c3c !important; 242 | color: #a6d189 !important; 243 | } 244 | .frappe pre .hljs-deletion { 245 | background-color: #292c3c !important; 246 | color: #e78284 !important; 247 | } 248 | .frappe pre .hljs-comment, 249 | .frappe pre .hljs-quote { 250 | color: #626880 !important; 251 | } 252 | .frappe pre .hljs-keyword, 253 | .frappe pre .hljs-selector-tag, 254 | .frappe pre .hljs-literal, 255 | .frappe pre .hljs-title, 256 | .frappe pre .hljs-section, 257 | .frappe pre .hljs-doctag, 258 | .frappe pre .hljs-type, 259 | .frappe pre .hljs-name, 260 | .frappe pre .hljs-strong { 261 | font-weight: bold !important; 262 | } 263 | .frappe pre .hljs-literal, 264 | .frappe pre .hljs-number { 265 | color: #ef9f76 !important; 266 | } 267 | .frappe pre .hljs-emphasis { 268 | font-style: italic !important; 269 | } 270 | 271 | .latte code, 272 | .latte .hljs { 273 | background: #e6e9ef; 274 | } 275 | .latte code .hljs-attr, 276 | .latte code .hljs-string { 277 | color: #40a02b; 278 | } 279 | .latte code .hljs-tag { 280 | color: #d20f39; 281 | } 282 | .latte code .hljs-name { 283 | color: #dd7878; 284 | } 285 | .latte pre .hljs { 286 | background: #e6e9ef !important; 287 | } 288 | .latte pre .hljs-params { 289 | color: #d20f39 !important; 290 | } 291 | .latte pre .hljs-built_in, 292 | .latte pre .hljs-selector-tag, 293 | .latte pre .hljs-section, 294 | .latte pre .hljs-link { 295 | color: #209fb5 !important; 296 | } 297 | .latte pre .hljs-keyword { 298 | color: #8839ef !important; 299 | } 300 | .latte pre .hljs, 301 | .latte pre .hljs-subst { 302 | color: #6c6f85 !important; 303 | } 304 | .latte pre .hljs-title { 305 | color: #1e66f5 !important; 306 | } 307 | .latte pre .hljs-attr, 308 | .latte pre .hljs-meta-keyword { 309 | color: #40a02b !important; 310 | } 311 | .latte pre .hljs-type { 312 | color: #1e66f5 !important; 313 | } 314 | .latte pre .hljs-string { 315 | color: #40a02b !important; 316 | } 317 | .latte pre .hljs-tag { 318 | color: #d20f39 !important; 319 | } 320 | .latte pre .hljs-meta, 321 | .latte pre .hljs-name, 322 | .latte pre .hljs-symbol, 323 | .latte pre .hljs-bullet, 324 | .latte pre .hljs-addition, 325 | .latte pre .hljs-variable, 326 | .latte pre .hljs-template-tag, 327 | .latte pre .hljs-template-variable { 328 | color: #dd7878 !important; 329 | } 330 | .latte pre .hljs-addition { 331 | background-color: #e6e9ef !important; 332 | color: #40a02b !important; 333 | } 334 | .latte pre .hljs-deletion { 335 | background-color: #e6e9ef !important; 336 | color: #d20f39 !important; 337 | } 338 | .latte pre .hljs-comment, 339 | .latte pre .hljs-quote { 340 | color: #acb0be !important; 341 | } 342 | .latte pre .hljs-keyword, 343 | .latte pre .hljs-selector-tag, 344 | .latte pre .hljs-literal, 345 | .latte pre .hljs-title, 346 | .latte pre .hljs-section, 347 | .latte pre .hljs-doctag, 348 | .latte pre .hljs-type, 349 | .latte pre .hljs-name, 350 | .latte pre .hljs-strong { 351 | font-weight: bold !important; 352 | } 353 | .latte pre .hljs-literal, 354 | .latte pre .hljs-number { 355 | color: #fe640b !important; 356 | } 357 | .latte pre .hljs-emphasis { 358 | font-style: italic !important; 359 | } 360 | -------------------------------------------------------------------------------- /theme/catppuccin.css: -------------------------------------------------------------------------------- 1 | .mocha { 2 | --bg: #1e1e2e; 3 | --fg: #cdd6f4; 4 | --sidebar-bg: #181825; 5 | --sidebar-fg: #cdd6f4; 6 | --sidebar-non-existant: #6c7086; 7 | --sidebar-active: #f5e0dc; 8 | --sidebar-spacer: #6c7086; 9 | --scrollbar: #6c7086; 10 | --icons: #6c7086; 11 | --icons-hover: #7f849c; 12 | --links: #89b4fa; 13 | --inline-code-color: #fab387; 14 | --theme-popup-bg: #181825; 15 | --theme-popup-border: #6c7086; 16 | --theme-hover: #6c7086; 17 | --quote-bg: #181825; 18 | --quote-border: #11111b; 19 | --table-border-color: #11111b; 20 | --table-header-bg: #181825; 21 | --table-alternate-bg: #11111b; 22 | --searchbar-border-color: #11111b; 23 | --searchbar-bg: #181825; 24 | --searchbar-fg: #cdd6f4; 25 | --searchbar-shadow-color: #11111b; 26 | --searchresults-header-fg: #cdd6f4; 27 | --searchresults-border-color: #11111b; 28 | --searchresults-li-bg: #1e1e2e; 29 | --search-mark-bg: #fab387; 30 | } 31 | 32 | .macchiato { 33 | --bg: #24273a; 34 | --fg: #cad3f5; 35 | --sidebar-bg: #1e2030; 36 | --sidebar-fg: #cad3f5; 37 | --sidebar-non-existant: #6e738d; 38 | --sidebar-active: #f4dbd6; 39 | --sidebar-spacer: #6e738d; 40 | --scrollbar: #6e738d; 41 | --icons: #6e738d; 42 | --icons-hover: #8087a2; 43 | --links: #8aadf4; 44 | --inline-code-color: #f5a97f; 45 | --theme-popup-bg: #1e2030; 46 | --theme-popup-border: #6e738d; 47 | --theme-hover: #6e738d; 48 | --quote-bg: #1e2030; 49 | --quote-border: #181926; 50 | --table-border-color: #181926; 51 | --table-header-bg: #1e2030; 52 | --table-alternate-bg: #181926; 53 | --searchbar-border-color: #181926; 54 | --searchbar-bg: #1e2030; 55 | --searchbar-fg: #cad3f5; 56 | --searchbar-shadow-color: #181926; 57 | --searchresults-header-fg: #cad3f5; 58 | --searchresults-border-color: #181926; 59 | --searchresults-li-bg: #24273a; 60 | --search-mark-bg: #f5a97f; 61 | } 62 | 63 | .frappe { 64 | --bg: #303446; 65 | --fg: #c6d0f5; 66 | --sidebar-bg: #292c3c; 67 | --sidebar-fg: #c6d0f5; 68 | --sidebar-non-existant: #737994; 69 | --sidebar-active: #f2d5cf; 70 | --sidebar-spacer: #737994; 71 | --scrollbar: #737994; 72 | --icons: #737994; 73 | --icons-hover: #838ba7; 74 | --links: #8caaee; 75 | --inline-code-color: #ef9f76; 76 | --theme-popup-bg: #292c3c; 77 | --theme-popup-border: #737994; 78 | --theme-hover: #737994; 79 | --quote-bg: #292c3c; 80 | --quote-border: #232634; 81 | --table-border-color: #232634; 82 | --table-header-bg: #292c3c; 83 | --table-alternate-bg: #232634; 84 | --searchbar-border-color: #232634; 85 | --searchbar-bg: #292c3c; 86 | --searchbar-fg: #c6d0f5; 87 | --searchbar-shadow-color: #232634; 88 | --searchresults-header-fg: #c6d0f5; 89 | --searchresults-border-color: #232634; 90 | --searchresults-li-bg: #303446; 91 | --search-mark-bg: #ef9f76; 92 | } 93 | 94 | .latte { 95 | --bg: #eff1f5; 96 | --fg: #4c4f69; 97 | --sidebar-bg: #e6e9ef; 98 | --sidebar-fg: #4c4f69; 99 | --sidebar-non-existant: #9ca0b0; 100 | --sidebar-active: #dc8a78; 101 | --sidebar-spacer: #9ca0b0; 102 | --scrollbar: #9ca0b0; 103 | --icons: #9ca0b0; 104 | --icons-hover: #8c8fa1; 105 | --links: #1e66f5; 106 | --inline-code-color: #fe640b; 107 | --theme-popup-bg: #e6e9ef; 108 | --theme-popup-border: #9ca0b0; 109 | --theme-hover: #9ca0b0; 110 | --quote-bg: #e6e9ef; 111 | --quote-border: #dce0e8; 112 | --table-border-color: #dce0e8; 113 | --table-header-bg: #e6e9ef; 114 | --table-alternate-bg: #dce0e8; 115 | --searchbar-border-color: #dce0e8; 116 | --searchbar-bg: #e6e9ef; 117 | --searchbar-fg: #4c4f69; 118 | --searchbar-shadow-color: #dce0e8; 119 | --searchresults-header-fg: #4c4f69; 120 | --searchresults-border-color: #dce0e8; 121 | --searchresults-li-bg: #eff1f5; 122 | --search-mark-bg: #fe640b; 123 | } 124 | -------------------------------------------------------------------------------- /theme/custom.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --content-max-width: 1200px; 3 | } 4 | 5 | table { 6 | width:100%; 7 | } 8 | 9 | .part-title { 10 | font-size: 120%; 11 | } 12 | 13 | 14 | img[src*='#center'] { 15 | display: block; 16 | margin: auto; 17 | } 18 | 19 | .chapter li { 20 | color: inherit; 21 | } 22 | 23 | /* 24 | .chapter > li.chapter-item > div 25 | { 26 | font-weight: bold; 27 | } 28 | */ 29 | .chapter > .chapter-item:first-child { 30 | font-weight: bold; 31 | font-size: 200%; 32 | } 33 | 34 | .sidebar-scrollbox { 35 | scrollbar-width: thin; 36 | } 37 | 38 | ol.chapter li ol.section li.chapter-item.expanded a.active { 39 | font-size: 1em; 40 | font-weight: 400; 41 | display: inline-block; 42 | border-left: .25rem solid transparent; 43 | border-left-color: var(--inline-code-color); 44 | padding: .35rem 1rem .35rem 1.25rem; 45 | line-height: 1.4; 46 | width: 100%; 47 | box-sizing: border-box; 48 | } -------------------------------------------------------------------------------- /theme/index.hbs: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | {{ title }} 7 | {{#if is_print }} 8 | 9 | {{/if}} 10 | {{#if base_url}} 11 | 12 | {{/if}} 13 | 14 | 15 | 16 | {{> head}} 17 | 18 | 19 | 20 | 21 | 22 | 23 | {{#if favicon_svg}} 24 | 25 | {{/if}} 26 | {{#if favicon_png}} 27 | 28 | {{/if}} 29 | 30 | 31 | 32 | {{#if print_enable}} 33 | 34 | {{/if}} 35 | 36 | 37 | 38 | {{#if copy_fonts}} 39 | 40 | {{/if}} 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | {{#each additional_css}} 49 | 50 | {{/each}} 51 | 52 | {{#if mathjax_support}} 53 | 54 | 55 | {{/if}} 56 | 57 | 58 | 59 | 63 | 64 | 65 | 79 | 80 | 81 | 91 | 92 | 93 | 103 | 104 | 110 | 111 |
112 | 113 |
114 | {{> header}} 115 | 116 | 163 | 164 | {{#if search_enabled}} 165 | 175 | {{/if}} 176 | 177 | 178 | 185 | 186 |
187 |
188 | {{{ content }}} 189 |
190 | 191 | 207 |
208 |
209 | 210 | 223 | 224 |
225 | 226 | {{#if live_reload_endpoint}} 227 | 228 | 243 | {{/if}} 244 | 245 | {{#if google_analytics}} 246 | 247 | 262 | {{/if}} 263 | 264 | {{#if playground_line_numbers}} 265 | 268 | {{/if}} 269 | 270 | {{#if playground_copyable}} 271 | 274 | {{/if}} 275 | 276 | {{#if playground_js}} 277 | 278 | 279 | 280 | 281 | 282 | {{/if}} 283 | 284 | {{#if search_js}} 285 | 286 | 287 | 288 | {{/if}} 289 | 290 | 291 | 292 | 293 | 294 | 295 | {{#each additional_js}} 296 | 297 | {{/each}} 298 | 299 | {{#if is_print}} 300 | {{#if mathjax_support}} 301 | 308 | {{else}} 309 | 314 | {{/if}} 315 | {{/if}} 316 | 317 | 318 | 319 | -------------------------------------------------------------------------------- /theme/mdbook-admonish.css: -------------------------------------------------------------------------------- 1 | @charset "UTF-8"; 2 | :root { 3 | --md-admonition-icon--note: 4 | url("data:image/svg+xml;charset=utf-8,"); 5 | --md-admonition-icon--abstract: 6 | url("data:image/svg+xml;charset=utf-8,"); 7 | --md-admonition-icon--info: 8 | url("data:image/svg+xml;charset=utf-8,"); 9 | --md-admonition-icon--tip: 10 | url("data:image/svg+xml;charset=utf-8,"); 11 | --md-admonition-icon--success: 12 | url("data:image/svg+xml;charset=utf-8,"); 13 | --md-admonition-icon--question: 14 | url("data:image/svg+xml;charset=utf-8,"); 15 | --md-admonition-icon--warning: 16 | url("data:image/svg+xml;charset=utf-8,"); 17 | --md-admonition-icon--failure: 18 | url("data:image/svg+xml;charset=utf-8,"); 19 | --md-admonition-icon--danger: 20 | url("data:image/svg+xml;charset=utf-8,"); 21 | --md-admonition-icon--bug: 22 | url("data:image/svg+xml;charset=utf-8,"); 23 | --md-admonition-icon--example: 24 | url("data:image/svg+xml;charset=utf-8,"); 25 | --md-admonition-icon--quote: 26 | url("data:image/svg+xml;charset=utf-8,"); 27 | --md-details-icon: 28 | url("data:image/svg+xml;charset=utf-8,"); 29 | } 30 | 31 | :is(.admonition) { 32 | display: flow-root; 33 | margin: 1.5625em 0; 34 | padding: 0 1.2rem; 35 | color: var(--fg); 36 | page-break-inside: avoid; 37 | background-color: var(--bg); 38 | border: 0 solid black; 39 | border-inline-start-width: 0.4rem; 40 | border-radius: 0.2rem; 41 | box-shadow: 0 0.2rem 1rem rgba(0, 0, 0, 0.05), 0 0 0.1rem rgba(0, 0, 0, 0.1); 42 | } 43 | @media print { 44 | :is(.admonition) { 45 | box-shadow: none; 46 | } 47 | } 48 | :is(.admonition) > * { 49 | box-sizing: border-box; 50 | } 51 | :is(.admonition) :is(.admonition) { 52 | margin-top: 1em; 53 | margin-bottom: 1em; 54 | } 55 | :is(.admonition) > .tabbed-set:only-child { 56 | margin-top: 0; 57 | } 58 | html :is(.admonition) > :last-child { 59 | margin-bottom: 1.2rem; 60 | } 61 | 62 | a.admonition-anchor-link { 63 | display: none; 64 | position: absolute; 65 | left: -1.2rem; 66 | padding-right: 1rem; 67 | } 68 | a.admonition-anchor-link:link, a.admonition-anchor-link:visited { 69 | color: var(--fg); 70 | } 71 | a.admonition-anchor-link:link:hover, a.admonition-anchor-link:visited:hover { 72 | text-decoration: none; 73 | } 74 | a.admonition-anchor-link::before { 75 | content: "§"; 76 | } 77 | 78 | :is(.admonition-title, summary) { 79 | position: relative; 80 | min-height: 4rem; 81 | margin-block: 0; 82 | margin-inline: -1.6rem -1.2rem; 83 | padding-block: 0.8rem; 84 | padding-inline: 4.4rem 1.2rem; 85 | font-weight: 700; 86 | background-color: rgba(68, 138, 255, 0.1); 87 | display: flex; 88 | } 89 | :is(.admonition-title, summary) p { 90 | margin: 0; 91 | } 92 | html :is(.admonition-title, summary):last-child { 93 | margin-bottom: 0; 94 | } 95 | :is(.admonition-title, summary)::before { 96 | position: absolute; 97 | top: 0.625em; 98 | inset-inline-start: 1.6rem; 99 | width: 2rem; 100 | height: 2rem; 101 | background-color: #448aff; 102 | mask-image: url('data:image/svg+xml;charset=utf-8,'); 103 | -webkit-mask-image: url('data:image/svg+xml;charset=utf-8,'); 104 | mask-repeat: no-repeat; 105 | -webkit-mask-repeat: no-repeat; 106 | mask-size: contain; 107 | -webkit-mask-size: contain; 108 | content: ""; 109 | } 110 | :is(.admonition-title, summary):hover a.admonition-anchor-link { 111 | display: initial; 112 | } 113 | 114 | details.admonition > summary.admonition-title::after { 115 | position: absolute; 116 | top: 0.625em; 117 | inset-inline-end: 1.6rem; 118 | height: 2rem; 119 | width: 2rem; 120 | background-color: currentcolor; 121 | mask-image: var(--md-details-icon); 122 | -webkit-mask-image: var(--md-details-icon); 123 | mask-repeat: no-repeat; 124 | -webkit-mask-repeat: no-repeat; 125 | mask-size: contain; 126 | -webkit-mask-size: contain; 127 | content: ""; 128 | transform: rotate(0deg); 129 | transition: transform 0.25s; 130 | } 131 | details[open].admonition > summary.admonition-title::after { 132 | transform: rotate(90deg); 133 | } 134 | 135 | :is(.admonition):is(.note) { 136 | border-color: #448aff; 137 | } 138 | 139 | :is(.note) > :is(.admonition-title, summary) { 140 | background-color: rgba(68, 138, 255, 0.1); 141 | } 142 | :is(.note) > :is(.admonition-title, summary)::before { 143 | background-color: #448aff; 144 | mask-image: var(--md-admonition-icon--note); 145 | -webkit-mask-image: var(--md-admonition-icon--note); 146 | mask-repeat: no-repeat; 147 | -webkit-mask-repeat: no-repeat; 148 | mask-size: contain; 149 | -webkit-mask-repeat: no-repeat; 150 | } 151 | 152 | :is(.admonition):is(.abstract, .summary, .tldr) { 153 | border-color: #00b0ff; 154 | } 155 | 156 | :is(.abstract, .summary, .tldr) > :is(.admonition-title, summary) { 157 | background-color: rgba(0, 176, 255, 0.1); 158 | } 159 | :is(.abstract, .summary, .tldr) > :is(.admonition-title, summary)::before { 160 | background-color: #00b0ff; 161 | mask-image: var(--md-admonition-icon--abstract); 162 | -webkit-mask-image: var(--md-admonition-icon--abstract); 163 | mask-repeat: no-repeat; 164 | -webkit-mask-repeat: no-repeat; 165 | mask-size: contain; 166 | -webkit-mask-repeat: no-repeat; 167 | } 168 | 169 | :is(.admonition):is(.info, .todo) { 170 | border-color: #00b8d4; 171 | } 172 | 173 | :is(.info, .todo) > :is(.admonition-title, summary) { 174 | background-color: rgba(0, 184, 212, 0.1); 175 | } 176 | :is(.info, .todo) > :is(.admonition-title, summary)::before { 177 | background-color: #00b8d4; 178 | mask-image: var(--md-admonition-icon--info); 179 | -webkit-mask-image: var(--md-admonition-icon--info); 180 | mask-repeat: no-repeat; 181 | -webkit-mask-repeat: no-repeat; 182 | mask-size: contain; 183 | -webkit-mask-repeat: no-repeat; 184 | } 185 | 186 | :is(.admonition):is(.tip, .hint, .important) { 187 | border-color: #00bfa5; 188 | } 189 | 190 | :is(.tip, .hint, .important) > :is(.admonition-title, summary) { 191 | background-color: rgba(0, 191, 165, 0.1); 192 | } 193 | :is(.tip, .hint, .important) > :is(.admonition-title, summary)::before { 194 | background-color: #00bfa5; 195 | mask-image: var(--md-admonition-icon--tip); 196 | -webkit-mask-image: var(--md-admonition-icon--tip); 197 | mask-repeat: no-repeat; 198 | -webkit-mask-repeat: no-repeat; 199 | mask-size: contain; 200 | -webkit-mask-repeat: no-repeat; 201 | } 202 | 203 | :is(.admonition):is(.success, .check, .done) { 204 | border-color: #00c853; 205 | } 206 | 207 | :is(.success, .check, .done) > :is(.admonition-title, summary) { 208 | background-color: rgba(0, 200, 83, 0.1); 209 | } 210 | :is(.success, .check, .done) > :is(.admonition-title, summary)::before { 211 | background-color: #00c853; 212 | mask-image: var(--md-admonition-icon--success); 213 | -webkit-mask-image: var(--md-admonition-icon--success); 214 | mask-repeat: no-repeat; 215 | -webkit-mask-repeat: no-repeat; 216 | mask-size: contain; 217 | -webkit-mask-repeat: no-repeat; 218 | } 219 | 220 | :is(.admonition):is(.question, .help, .faq) { 221 | border-color: #64dd17; 222 | } 223 | 224 | :is(.question, .help, .faq) > :is(.admonition-title, summary) { 225 | background-color: rgba(100, 221, 23, 0.1); 226 | } 227 | :is(.question, .help, .faq) > :is(.admonition-title, summary)::before { 228 | background-color: #64dd17; 229 | mask-image: var(--md-admonition-icon--question); 230 | -webkit-mask-image: var(--md-admonition-icon--question); 231 | mask-repeat: no-repeat; 232 | -webkit-mask-repeat: no-repeat; 233 | mask-size: contain; 234 | -webkit-mask-repeat: no-repeat; 235 | } 236 | 237 | :is(.admonition):is(.warning, .caution, .attention) { 238 | border-color: #ff9100; 239 | } 240 | 241 | :is(.warning, .caution, .attention) > :is(.admonition-title, summary) { 242 | background-color: rgba(255, 145, 0, 0.1); 243 | } 244 | :is(.warning, .caution, .attention) > :is(.admonition-title, summary)::before { 245 | background-color: #ff9100; 246 | mask-image: var(--md-admonition-icon--warning); 247 | -webkit-mask-image: var(--md-admonition-icon--warning); 248 | mask-repeat: no-repeat; 249 | -webkit-mask-repeat: no-repeat; 250 | mask-size: contain; 251 | -webkit-mask-repeat: no-repeat; 252 | } 253 | 254 | :is(.admonition):is(.failure, .fail, .missing) { 255 | border-color: #ff5252; 256 | } 257 | 258 | :is(.failure, .fail, .missing) > :is(.admonition-title, summary) { 259 | background-color: rgba(255, 82, 82, 0.1); 260 | } 261 | :is(.failure, .fail, .missing) > :is(.admonition-title, summary)::before { 262 | background-color: #ff5252; 263 | mask-image: var(--md-admonition-icon--failure); 264 | -webkit-mask-image: var(--md-admonition-icon--failure); 265 | mask-repeat: no-repeat; 266 | -webkit-mask-repeat: no-repeat; 267 | mask-size: contain; 268 | -webkit-mask-repeat: no-repeat; 269 | } 270 | 271 | :is(.admonition):is(.danger, .error) { 272 | border-color: #ff1744; 273 | } 274 | 275 | :is(.danger, .error) > :is(.admonition-title, summary) { 276 | background-color: rgba(255, 23, 68, 0.1); 277 | } 278 | :is(.danger, .error) > :is(.admonition-title, summary)::before { 279 | background-color: #ff1744; 280 | mask-image: var(--md-admonition-icon--danger); 281 | -webkit-mask-image: var(--md-admonition-icon--danger); 282 | mask-repeat: no-repeat; 283 | -webkit-mask-repeat: no-repeat; 284 | mask-size: contain; 285 | -webkit-mask-repeat: no-repeat; 286 | } 287 | 288 | :is(.admonition):is(.bug) { 289 | border-color: #f50057; 290 | } 291 | 292 | :is(.bug) > :is(.admonition-title, summary) { 293 | background-color: rgba(245, 0, 87, 0.1); 294 | } 295 | :is(.bug) > :is(.admonition-title, summary)::before { 296 | background-color: #f50057; 297 | mask-image: var(--md-admonition-icon--bug); 298 | -webkit-mask-image: var(--md-admonition-icon--bug); 299 | mask-repeat: no-repeat; 300 | -webkit-mask-repeat: no-repeat; 301 | mask-size: contain; 302 | -webkit-mask-repeat: no-repeat; 303 | } 304 | 305 | :is(.admonition):is(.example) { 306 | border-color: #7c4dff; 307 | } 308 | 309 | :is(.example) > :is(.admonition-title, summary) { 310 | background-color: rgba(124, 77, 255, 0.1); 311 | } 312 | :is(.example) > :is(.admonition-title, summary)::before { 313 | background-color: #7c4dff; 314 | mask-image: var(--md-admonition-icon--example); 315 | -webkit-mask-image: var(--md-admonition-icon--example); 316 | mask-repeat: no-repeat; 317 | -webkit-mask-repeat: no-repeat; 318 | mask-size: contain; 319 | -webkit-mask-repeat: no-repeat; 320 | } 321 | 322 | :is(.admonition):is(.quote, .cite) { 323 | border-color: #9e9e9e; 324 | } 325 | 326 | :is(.quote, .cite) > :is(.admonition-title, summary) { 327 | background-color: rgba(158, 158, 158, 0.1); 328 | } 329 | :is(.quote, .cite) > :is(.admonition-title, summary)::before { 330 | background-color: #9e9e9e; 331 | mask-image: var(--md-admonition-icon--quote); 332 | -webkit-mask-image: var(--md-admonition-icon--quote); 333 | mask-repeat: no-repeat; 334 | -webkit-mask-repeat: no-repeat; 335 | mask-size: contain; 336 | -webkit-mask-repeat: no-repeat; 337 | } 338 | 339 | .navy :is(.admonition) { 340 | background-color: var(--sidebar-bg); 341 | } 342 | 343 | .ayu :is(.admonition), .coal :is(.admonition) { 344 | background-color: var(--theme-hover); 345 | } 346 | 347 | .rust :is(.admonition) { 348 | background-color: var(--sidebar-bg); 349 | color: var(--sidebar-fg); 350 | } 351 | .rust .admonition-anchor-link:link, .rust .admonition-anchor-link:visited { 352 | color: var(--sidebar-fg); 353 | } 354 | --------------------------------------------------------------------------------