Merge tag 'release/5.2.0' into openupm

Release 5.2.0

CODE_OF_CONDUCT.md

@@ -69,10 +69,9 @@ members of the project's leadership.
 ## Attribution
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
-available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
-
-[homepage]: https://www.contributor-covenant.org
+available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
 
 For answers to common questions about this code of conduct, see
-https://www.contributor-covenant.org/faq
+<https://www.contributor-covenant.org/faq>
 
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -20,7 +20,6 @@ feedback on how to optimally perform your changes or reasons for not doing it.
 Lastly, if you're looking for input on what to contribute browse the GitHub
 issues, especially ones with the `help wanted` or `good first issue` label.
 
-
 ## Git Branches
 
 The main branch corresponds to the most recent version of the project. Note
@@ -36,8 +35,8 @@ contains the following:
 
 ## Contributor License Agreements
 
-When you open a pull request, you will be asked to acknolwedge our Contributor
+When you open a pull request, you will be asked to acknowledge our Contributor
 License Agreement. You will have to confirm that your Contributions are your
 original creation and that you have complete right and authority to make your
 Contributions. We allow both individual contributions and contributions made on
-behalf of companies. 
+behalf of companies.

Documentation~/ExportEditor.md

@@ -18,3 +18,12 @@ Clicking any of these will open a file selection dialog. If additional files are
 ## Export via Script
 
 Exporting via script works exactly the same as [Runtime Export](ExportRuntime.md), with the exception that you don't need to [include the required shaders](ExportRuntime.md#include-required-shaders).
+
+## Trademarks
+
+*Unity®* is a registered trademark of [Unity Technologies][unity].
+
+*Khronos®* is a registered trademark and *glTF™* is a trademark of [The Khronos Group Inc][khronos].
+
+[khronos]: https://www.khronos.org
+[unity]: https://unity.com

Documentation~/ExportRuntime.md

@@ -1,6 +1,6 @@
 # Runtime Export
 
-You can export individual GameObjects or entire scenes to glTF files at runtime.
+You can export individual GameObjects or entire scenes to glTF™ files at runtime.
 
 ## Include Required Shaders
 
@@ -12,7 +12,7 @@ The easiest way to include them is to add `glTFExport.shadervariants` to the lis
 
 > Note: The `GLTFast.Export` namespace can only be used if you reference both `glTFast` and `glTFast.Export` Assemblies in your [Assembly Definition][asmdef].
 
-Here's a step-by-step guilde to export a GameObject hierarchy/scene from script
+Here's a step-by-step guide to export a GameObject hierarchy/scene from script
 
 - Create an instance of `GLTFast.Export.GameObjectExport`
 - Add content via `AddScene`
@@ -22,7 +22,6 @@ Here's a step-by-step guilde to export a GameObject hierarchy/scene from script
 
 glTF export might create more than one file. For example the binary buffer is usually a separate `.bin` file and textures might be separate files as well.
 
-
 ```c#
 using UnityEngine;
 using GLTFast.Export;
@@ -71,7 +70,7 @@ public class TestExport : MonoBehaviour {
 
     async void AdvancedExport() {
 
-        // CollectingLogger lets you programatically go through
+        // CollectingLogger lets you programmatically go through
         // errors and warnings the export raised
         var logger = new CollectingLogger();
 
@@ -123,7 +122,7 @@ public class TestExport : MonoBehaviour {
 
 ### Draco Compression
 
-glTFast supports applying [Google Draco 3D Data compression][Draco] to meshes. This requires the [DracoUnity][DracoUnity] package to be installed.
+*Unity glTFast* supports applying [Google Draco™ 3D Data compression][Draco] to meshes. This requires the [DracoUnity][DracoUnity] package to be installed.
 
 ```csharp
 // ExportSettings provides generic export settings
@@ -138,6 +137,17 @@ var exportSettings = new ExportSettings {
 };
 ```
 
+## Trademarks
+
+*Unity®* is a registered trademark of [Unity Technologies][unity].
+
+*Khronos®* is a registered trademark and *glTF™* is a trademark of [The Khronos Group Inc][khronos].
+
+*Draco™* is a trademark of [*Google LLC*][GoogleLLC].
+
 [asmdef]: https://docs.unity3d.com/Manual/ScriptCompilationAssemblyDefinitionFiles.html
 [Draco]: https://google.github.io/draco/
-[DracoUnity]: https://github.com/atteneder/DracoUnity
+[DracoUnity]: https://github.com/atteneder/DracoUnity
+[GoogleLLC]: https://about.google/
+[khronos]: https://www.khronos.org
+[unity]: https://unity.com

Documentation~/ImplementationDetails.md

@@ -1,5 +1,14 @@
 # Implementation Details
 
-*glTFast* uses [JsonUtility](https://docs.unity3d.com/ScriptReference/JsonUtility.html) for parsing, which has little overhead, is fast and memory-efficient (See <https://docs.unity3d.com/Manual/JSONSerialization.html>).
+*Unity glTFast* uses [JsonUtility](https://docs.unity3d.com/ScriptReference/JsonUtility.html) for parsing, which has little overhead, is fast and memory-efficient (See <https://docs.unity3d.com/Manual/JSONSerialization.html>).
 
 It also uses fast low-level memory copy methods, the [C# Job System](https://docs.unity3d.com/Manual/JobSystem.html), [Mathematics](https://docs.unity3d.com/Packages/com.unity.mathematics@1.0/manual/index.html), the [Burst compiler](https://docs.unity3d.com/Packages/com.unity.burst@1.6/manual/index.html) and the [Advanced Mesh API](https://docs.unity3d.com/ScriptReference/Mesh.html).
+
+## Trademarks
+
+*Unity&reg;* is a registered trademark of [Unity Technologies][unity].
+
+*Khronos&reg;* is a registered trademark and *glTF&trade;* is a trademark of [The Khronos Group Inc][khronos].
+
+[khronos]: https://www.khronos.org
+[unity]: https://unity.com

Documentation~/ImportEditor.md

@@ -1,6 +1,6 @@
 # Editor Import
 
-You can move/copy *glTF* files into your project's *Assets* folder, similar to other 3D formats. *glTFast* will import them to native Unity prefabs and add them to the asset database.
+You can move/copy *glTF™* files into your project's *Assets* folder, similar to other 3D formats. *Unity glTFast* will import them to native Unity prefabs and add them to the asset database.
 
 ![Editor Import][import-gif]
 
@@ -10,14 +10,23 @@ Select a glTF in the Project view to see its import settings and eventual warnin
 
 ## Default Importer Selection
 
-*glTFast* uses Unity's `ScriptedImporter` interface. For any given file format (file extension) there has to be one default importer and there can be additional, alternative importers. *glTFast* will register itself as the default importer for the `.gltf` and `.glb` extensions.
+*Unity glTFast* uses Unity's `ScriptedImporter` interface. For any given file format (file extension) there has to be one default importer and there can be additional, alternative importers. *Unity glTFast* will register itself as the default importer for the `.gltf` and `.glb` extensions.
 
 You can install any number of alternative importers, but if any of those registers itself as default importer as well, this will result in an error like this:
 
 > Multiple scripted importers are targeting the extension 'glb' and have all been rejected: …
 
 The recommended solution is to move other importers from default to alternative (consult their respective documentations how to do that)
 
-If that's not possible or wanted, you can de-prioritize *glTFast* from default to alternative importer by adding the `GLTFAST_FORCE_DEFAULT_IMPORTER_OFF` to your project's scripting defines.
+If that's not possible or wanted, you can de-prioritize *Unity glTFast* from default to alternative importer by adding the `GLTFAST_FORCE_DEFAULT_IMPORTER_OFF` to your project's scripting defines.
 
 [import-gif]: Images/import.gif  "Video showing glTF files being copied into the Assets folder and imported"
+
+## Trademarks
+
+*Unity®* is a registered trademark of [Unity Technologies][unity].
+
+*Khronos®* is a registered trademark and *glTF™* is a trademark of [The Khronos Group Inc][khronos].
+
+[khronos]: https://www.khronos.org
+[unity]: https://unity.com

Documentation~/ImportRuntime.md

@@ -1,6 +1,6 @@
 # Runtime Loading
 
-You can load a glTF asset from an URL or a file path.
+You can load a glTF™ asset from an URL or a file path.
 
 > Note: glTFs are loaded via [UnityWebRequests](https://docs.unity3d.com/ScriptReference/Networking.UnityWebRequest.html). File paths have to be prefixed with `file://` in the Unity Editor and on certain platforms (e.g. iOS).
 
@@ -43,12 +43,12 @@ async void LoadGltfBinaryFromMemory() {
 
 Loading via script allows you to:
 
-- Custom download or file loading behaviour (see [`IDownloadProvider`][IDownload])
-- Customize loading behaviour (like texture settings) via [`ImportSettings`](#import-settings)
+- Custom download or file loading behavior (see [`IDownloadProvider`][IDownload])
+- Customize loading behavior (like texture settings) via [`ImportSettings`](#import-settings)
 - Custom material generation (see [`IMaterialGenerator`][IMaterialGenerator]])
 - Customize [instantiation](#instantiation)
-- Load glTF once and instantiate its scenes many times (see example [below](#custom-post-loading-behaviour))
-- Access data of glTF scene (for example get material; see example [below](#custom-post-loading-behaviour))
+- Load glTF once and instantiate its scenes many times (see example [below](#custom-post-loading-behavior))
+- Access data of glTF scene (for example get material; see example [below](#custom-post-loading-behavior))
 - [Logging](#logging) allow reacting and communicating incidents during loading and instantiation
 - Tweak and optimize loading performance
 
@@ -80,9 +80,9 @@ async void Start()
 }
 ```
 
-### Custom Post-Loading Behaviour
+### Custom Post-Loading Behavior
 
-The async `Load` method can be awaited and followed up by custom behaviour.
+The async `Load` method can be awaited and followed up by custom behavior.
 
 ```C#
 async void Start() {
@@ -142,7 +142,7 @@ You can disable this by setting `SkinUpdateWhenOffscreen` to false.
 
 ##### `Layer`
 
-Instantated `GameObject`s will be assigned to this [layer](https://docs.unity3d.com/Manual/Layers.html).
+Instantiated `GameObject`s will be assigned to this [layer](https://docs.unity3d.com/Manual/Layers.html).
 
 ##### `Mask`
 
@@ -157,7 +157,7 @@ Two common use-cases are
 1. Scale-down (physically correct) intensities to compensate for the missing exposure control (or high sensitivity) of a render pipeline (e.g. Universal or Built-in Render Pipeline)
 2. Boost implausibly low light intensities
 
-See [Physical Light Units in glTF](./LightUnits.md) for a detailed explaination.
+See [Physical Light Units in glTF](./LightUnits.md) for a detailed explanation.
 
 ##### `SceneObjectCreation`
 
@@ -213,23 +213,23 @@ async void Start()
 
 ### Logging
 
-When loading a glTF file, glTFast logs messages of varying severity (errors, warnigns or infos). Developers can choose what to make of those log messages. Examples:
+When loading a glTF file, *Unity glTFast* logs messages of varying severity (errors, warnings or infos). Developers can choose what to make of those log messages. Examples:
 
 - Log to console in readable form
 - Feed the information into an analytics framework
 - Display details to the users
 
 The provided component `GltfAsset` logs all of those messages to the console by default.  
 
-You can customize logging by providing an implementation of [`ICodeLogger`][ICodeLogger] to methods like `GltfImport.Load` or `GltfImport.InstanciateMainScene`.
+You can customize logging by providing an implementation of [`ICodeLogger`][ICodeLogger] to methods like `GltfImport.Load` or `GltfImport.InstantiateMainScene`.
 
 There are two common implementations bundled. The `ConsoleLogger`, which logs straight to console (the default) and `CollectingLogger`, which stores messages in a list for users to process.
 
 Look into [`ICodeLogger`][ICodeLogger] and [`LogMessages`][LogMessages] for details.
 
 ### Tune loading performance
 
-When loading glTFs, *glTFast* let's you optimize towards one of two diametrical goals
+When loading glTFs, *Unity glTFast* let's you optimize towards one of two diametrical goals
 
 - A stable frame rate
 - Fastest loading time
@@ -238,7 +238,7 @@ By default each `GltfAsset` instance tries not to block the main thread for long
 
 If you load many glTF files at once, by default they won't be aware of each other and collectively might block the main game loop for too long.
 
-You can solve this by using a common "defer agent". It decides if work should continue right now or at the next game loop iteration. *glTFast* comes with two defer agents
+You can solve this by using a common "defer agent". It decides if work should continue right now or at the next game loop iteration. *Unity glTFast* comes with two defer agents
 
 - `TimeBudgetPerFrameDeferAgent` for stable frame rate
 - `UninterruptedDeferAgent` for fastest, uninterrupted loading
@@ -277,13 +277,19 @@ async Task CustomDeferAgentPerGltfImport() {
 ```
 
 > Note 1: Depending on your glTF scene, using the `UninterruptedDeferAgent` may block the main thread for up to multiple seconds. Be sure to not do this during critical game play action.
-
+>
 > Note2 : Using the `TimeBudgetPerFrameDeferAgent` does **not** guarantee a stutter free frame rate. This is because some sub tasks of the loading routine (like uploading a texture to the GPU) may take too long, cannot be interrupted and **have** to be done on the main thread.
 
 ### Disposing Resources
 
 When you no longer need a loaded instance of a glTF scene you might want to remove it and free up all its resources (mainly memory). For that purpose [`GltfImport`][GltfImport] implements `IDisposable`. Calling [`GltfImport.Dispose`][GltfImportDispose] will destroy all its resources, regardless whether there's still an instance that might references them.
 
+## Trademarks
+
+*Unity®* is a registered trademark of [Unity Technologies][Unity].
+
+*Khronos®* is a registered trademark and *glTF™* is a trademark of [The Khronos Group Inc][Khronos].
+
 [GltfImport]: xref:GLTFast.GltfImport
 [GltfImportDispose]: xref:GLTFast.GltfImport.Dispose
 [GameObjectInstantiator]: xref:GLTFast.GameObjectInstantiator
@@ -294,6 +300,8 @@ When you no longer need a loaded instance of a glTF scene you might want to remo
 [IMaterialGenerator]: xref:GLTFast.Materials.IMaterialGenerator
 [ImportSettings]: xref:GLTFast.ImportSettings
 [InstantiationSettings]: xref:GLTFast.InstantiationSettings
+[Khronos]: https://www.khronos.org
 [LogMessages]: xref:GLTFast.Logging.LogMessages
 [GameObjectSceneInstance]: xref:GLTFast.GameObjectSceneInstance
 [SceneObjectCreation]: xref:GLTFast.SceneObjectCreation
+[Unity]: https://unity.com

Documentation~/KnownIssues.md

@@ -8,4 +8,12 @@
 
 <sup>1</sup>: A Unity API limitation.
 
-[SamplerFilter]: https://github.com/atteneder/glTFast/issues/61 
+## Trademarks
+
+*Unity&reg;* is a registered trademark of [Unity Technologies][Unity].
+
+*Khronos&reg;* is a registered trademark and *glTF&trade;* is a trademark of [The Khronos Group Inc][Khronos].
+
+[Khronos]: https://www.khronos.org
+[SamplerFilter]: https://github.com/atteneder/glTFast/issues/61
+[Unity]: https://unity.com

Documentation~/LightUnits.md

@@ -1,14 +1,14 @@
-# Physical Light Units in glTF
+# Physical Light Units in glTF™
 
 Material emission and light intensities in glTF have physical units.
 
-| Light type        | Unit                                  | 
+| Light type        | Unit                                  |
 |-------------------| ------------------------------------- |
 | Point/Spot        | [Candela (lumen per steradian)][cd]   |
 | Directional       | [Lux (lumen per square meter)][lx]    |
 | Emissive Material | [Nit (candela per square meter)][nit] |
 
-But these units are only a part of the equation, since the perceived brightness of a light depends on the sensitivity of the viewer. In case of a physical camera, the sensitivity is controlled by its aperture, exposure time and film sensititity (ISO). For example, a candle might light up an entire dark room, but is barely noticable on a bright, sunny day. That's because the camera settings are adjusted to the overall brightness of the scene. This is called exosure control.
+But these units are only a part of the equation, since the perceived brightness of a light depends on the sensitivity of the viewer. In case of a physical camera, the sensitivity is controlled by its aperture, exposure time and film sensitivity (ISO). For example, a candle might light up an entire dark room, but is barely noticeable on a bright, sunny day. That's because the camera settings are adjusted to the overall brightness of the scene. This is called exposure control.
 
 Unfortunately exposure control is not yet specified in glTF. Also, many render pipelines (e.g. Universal and Built-in Render Pipeline) do not integrate this concept. They can be thought of having a fixed exposure with a high sensitivity, so that a light with low, single-digit intensity value is enough to bring a scene to full illumination. The implication is that in those exposure-unaware render pipelines correct, physical light units have to be scaled down in order not to overexpose the scene.
 
@@ -18,7 +18,7 @@ An additional problem is, hardly any glTF viewer that lacks exposure control adj
 
 ### Adjusting Values
 
-*glTFast* lets you multiply light intensities by an arbitrary factor (which defaults to 1.0) to make them fit your scene's lighting.
+*Unity glTFast* lets you multiply light intensities by an arbitrary factor (which defaults to 1.0) to make them fit your scene's lighting.
 
 #### Physically Plausible Values in exposure-unaware Render Pipelines
 
@@ -74,9 +74,17 @@ Source: [Wikipedia][lux-illuminance]
 
 Source: [Wikipedia][lum-flux]
 
+## Trademarks
+
+*Unity®* is a registered trademark of [Unity Technologies][unity].
+
+*Khronos®* is a registered trademark and *glTF™* is a trademark of [The Khronos Group Inc][khronos].
+
 [cd]: https://en.wikipedia.org/wiki/Candela
 [hdrp-plu]: https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@13.1/manual/Physical-Light-Units.html
+[khronos]: https://www.khronos.org
 [lx]: https://en.wikipedia.org/wiki/Lux
 [lux-illuminance]: https://en.wikipedia.org/wiki/Lux#Illuminance
 [lum-flux]: https://en.wikipedia.org/wiki/Luminous_flux#Examples
 [nit]: https://en.wikipedia.org/wiki/Candela_per_square_metre
+[unity]: https://unity.com

Documentation~/Original.md

@@ -0,0 +1,21 @@
+# Original glTFast
+
+This package's original identifier was `com.atteneder.gltfast` (see [Unity Fork][fork] for details). You can still use/install it with that identifier.
+
+## Via [OpenUPM][OpenUPM]
+
+The recommended way to install is to download and open the [Installer Package](https://package-installer.glitch.me/v1/installer/OpenUPM/com.atteneder.gltfast?registry=https%3A%2F%2Fpackage.openupm.com&scope=com.atteneder)
+
+It runs a script that installs *glTFast* via the [OpenUPM][OpenUPM] [scoped registry](https://docs.unity3d.com/Manual/upm-scoped.html).
+
+Afterwards *glTFast* and further, optional packages are listed in the *Package Manager* (under *My Registries*) and can be installed and updated from there.
+
+## Using GIT
+
+If you want to clone the GIT repository and installed the package locally (which is useful if you intend to develop glTFast itself), you have to checkout the branch `openupm`.
+
+The package identifier in the `main` branch was changed, which likely leads to errors if you've cloned it before and pulled that change. In that case either switch to the `openupm` branch or [transition to the new package identifier][transition].
+
+[fork]: ./UpgradeGuides#unity-fork
+[transition]: ./UpgradeGuides#transition-to-unity-gltfast
+[OpenUPM]: https://openupm.com/