Merge tag 'release/6.5.0' into openupm

Release 6.5.0
atteneder · May 27, 2024 · 561c9fd · 561c9fd
2 parents ef121f3 + 1147edf
commit 561c9fd
Show file tree

Hide file tree

Showing 259 changed files with 16,382 additions and 1,934 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -3,3 +3,4 @@
 *.glb filter=lfs diff=lfs merge=lfs -text
 *.bin filter=lfs diff=lfs merge=lfs -text
 *.gif filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
diff --git a/.github/codecov.yml b/.github/codecov.yml
@@ -29,7 +29,7 @@ comment:
   require_base: false
   require_head: false
   # Set this to the number of coverage jobs run in the PR
-  after_n_builds: 3
+  after_n_builds: 4
 
 flag_management:
   default_rules:

diff --git a/.yamato/package-test.yml b/.yamato/package-test.yml
@@ -37,13 +37,20 @@ test_{{ platform.name }}_{{ editor }}:
 {% endfor -%}
 
     - npm install {% if platform.name == "win" %}"%UPMCI_PKG%"{% else %}"$UPMCI_PKG"{% endif %} -g --registry {{ registry.npm }}
-    - |
+    - >
 {% if platform.name == "win" -%}
       set GLTF_TEST_ASSET_DIR={{ os.yamato_source_dir }}\Assets
 {% else -%}
       export GLTF_TEST_ASSET_DIR="{{ os.yamato_source_dir }}/Assets"
 {% endif -%}
-      upm-ci package test -u {{ editor }} --package-path Packages/gltfast --type package-tests --extra-create-project-arg=-upmNoDefaultPackages
+
+      upm-ci package test
+      -u {{ editor }}
+      --package-path Packages/gltfast
+      --type package-tests
+      --extra-create-project-arg=-upmNoDefaultPackages
+      --extra-utr-arg='--category="{{ test_categories }}"'
+
   artifacts:
     logs:
       paths:
@@ -93,13 +100,21 @@ validate_{{ platform.name }}_{{ editor }}:
 {% endfor -%}
 
     - npm install {% if platform.name == "win" %}"%UPMCI_PKG%"{% else %}"$UPMCI_PKG"{% endif %} -g --registry {{ registry.npm }}
-    - |
+    - >
 {% if platform.name == "win" -%}
       set GLTF_TEST_ASSET_DIR={{ os.yamato_source_dir }}\Assets
 {% else -%}
       export GLTF_TEST_ASSET_DIR="{{ os.yamato_source_dir }}/Assets"
 {% endif -%}
-      upm-ci package test -u {{ editor }} --package-path Packages/gltfast --type vetting-tests --platform editmode --extra-create-project-arg=-upmNoDefaultPackages
+
+      upm-ci package test
+      -u {{ editor }}
+      --package-path Packages/gltfast
+      --type vetting-tests
+      --platform editmode
+      --extra-create-project-arg=-upmNoDefaultPackages
+      --extra-utr-arg='--category="{{ test_categories }}"'
+
   artifacts:
     logs:
       paths:

diff --git a/.yamato/package.metafile b/.yamato/package.metafile
@@ -46,6 +46,17 @@ test_setups:
       # default for coverage: windows + current LTS
       - platform: win
         editor: 2022
+  - project_setup: hdrp
+    render_pipeline: HDRP-Deferred
+    editor_versions: [2022,trunk]
+    platforms: [win]
+    pr_sets:
+      - platform: win
+        editor: 2022
+    coverage_sets:
+      # default for coverage: windows + current LTS
+      - platform: win
+        editor: 2022
 
 editor_versions:
   - 2020
@@ -171,6 +182,7 @@ registry:
   artifactory: https://artifactory.prd.cds.internal.unity3d.com/artifactory
 
 generic_project_path: Projects/TestProject
+test_categories: "!Performance"
 
 # Operating system specific variables
 os_variables:

diff --git a/.yamato/project-test.yml b/.yamato/project-test.yml
@@ -176,12 +176,12 @@ test_{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }}:
       --extra-editor-arg="-enablePackageManagerTraces -upmNoDefaultPackages"
       --suite=editor
       --suite=playmode
+      --category="{{ test_categories }}"
 {% if is_coverage_set -%}
       --enable-code-coverage
-      --coverage-results-path={{ results_path }}
-      --coverage-options='generateAdditionalMetrics;generateHtmlReport;assemblyFilters:+glTFast*,+Unity.Cloud.Gltfast*,-glTFast*Tests*;pathReplacePatterns:**/PackageCache/com.unity.cloud.gltfast@*/,;sourcePaths:{{ os.yamato_source_dir }}/Packages/gltfast'
-      --coverage-results-path={{ os.yamato_source_dir }}/test-results~/CoverageResults
-      --coverage-upload-options="reportsDir:{{ os.yamato_source_dir }}/test-results~/CoverageResults;reports:*.xml;sourceDir:Packages/gltfast;repo:unity/com.unity.cloud.gltfast.src;changeset:{{ os.git_revision }};name:{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }};flags:{{ test_setup.project_setup }};verbose"
+      --coverage-results-path={{ results_path }}/CoverageResults
+      --coverage-options='generateAdditionalMetrics;generateHtmlReport;assemblyFilters:+glTFast*,-glTFast*Tests*;pathReplacePatterns:**/PackageCache/com.unity.cloud.gltfast@*/,;sourcePaths:{{ os.yamato_source_dir }}/Packages/gltfast'
+      --coverage-upload-options="reportsDir:{{ results_path }}/CoverageResults;reports:*.xml;sourceDir:Packages/gltfast;repo:unity/com.unity.cloud.gltfast.src;changeset:{{ os.git_revision }};name:{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }};flags:{{ test_setup.project_setup }};verbose"
 {% endif -%}
 {{ job_artifacts }}
 {% endif -%}
@@ -315,6 +315,7 @@ build_and_run_{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }}:
       --verbose
       --extra-editor-arg="-enablePackageManagerTraces -upmNoDefaultPackages"
       --suite=playmode
+      --category="{{ test_categories }}"
       --scripting-backend=Il2Cpp
       --platform={% if platform.platform -%}{{ platform.platform }}{% else -%}{{ platform_id }}{% endif %}
 {{ job_artifacts }}
@@ -449,6 +450,7 @@ build_{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }}:
       --verbose
       --extra-editor-arg="-enablePackageManagerTraces -upmNoDefaultPackages"
       --suite=playmode
+      --category="{{ test_categories }}"
       --scripting-backend=Il2Cpp
       --platform={% if platform.platform -%}{{ platform.platform }}{% else -%}{{ platform_id }}{% endif %}
       --build-only
@@ -586,6 +588,7 @@ run_{{ test_setup.project_setup }}_{{ platform_id }}_{{ editor }}:
       --verbose
       --extra-editor-arg="-enablePackageManagerTraces -upmNoDefaultPackages"
       --suite=playmode
+      --category="{{ test_categories }}"
       --scripting-backend=Il2Cpp
       --platform={% if platform.platform -%}{{ platform.platform }}{% else -%}{{ platform_id }}{% endif %}
       --player-load-path={{ results_path }}/player

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,34 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.5.0] - 2024-05-15
+
+### Added
+- (Export) Support for exporting glTFast shader based materials. This reduces data loss on import-export round trips considerably.
+- (Export) Support for setting a custom scene origin via transform matrix.
+- Dependency on [Unity Collections package][Collections].
+- Added Apple Privacy Manifest documentation.
+- Export sample code.
+- XML documentation comments.
+- `float4x4.Decompose` overload that outputs rotation as type `quaternion`.
+
+### Changed
+- Faster buffer conversion jobs due to batching via [`IJobParallelForBatch`](https://docs.unity3d.com/Packages/[email protected]/api/Unity.Jobs.IJobParallelForBatch.html).
+- (Export) Material exporter implementation is chosen based on used shader by default.
+- (Export) Vertex attributes are discarded if they are not used/referenced.
+- (Export) Root level nodes' positions are based on their GameObject's world positions (and not their local position anymore).
+
+### Fixed
+- (Export) Discrepancy in color due to export of unused vertex colors.
+- Incorrect copyright text in some SPDX headers.
+
+### Deprecated
+- `float4x4.Decompose` overload that outputs rotation as type `float4` (quaternion values).
+
+### Removed
+- Soft dependency on deprecated [Unity Jobs package][JobsPkg].
+- Legacy code for Unity versions older than the minimum required 2020 LTS.
+
 ## [6.4.0] - 2024-04-17
 
 ### Added
@@ -1126,6 +1154,8 @@ This release contains multiple breaking changes. Please read the [upgrade guide]
 - initial version
 
 [Entities1.0]: https://docs.unity3d.com/Packages/[email protected]
+[Collections]: https://docs.unity3d.com/Packages/com.unity.collections@latest/
+[JobsPkg]: https://docs.unity3d.com/Packages/com.unity.jobs@latest/
 [KtxUnity]: https://github.com/atteneder/KtxUnity
 [KtxForUnity]: https://docs.unity3d.com/Packages/com.unity.cloud.ktx@latest/
 [DanDovi]: https://github.com/DanDovi

diff --git a/Documentation~/ExportRuntime.md b/Documentation~/ExportRuntime.md
@@ -10,132 +10,55 @@ The easiest way to include them is to add `glTFExport.shadervariants` to the lis
 
 ## Export via Script
 
-> Note: The `GLTFast.Export` namespace can only be used if you reference both `glTFast` and `glTFast.Export` Assemblies in your [Assembly Definition][asmdef].
+> **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 guide to export a GameObject hierarchy/scene from script
 
-- Create an instance of `GLTFast.Export.GameObjectExport`
-- Add content via `AddScene`
+- Create an instance of [GameObjectExport](xref:GLTFast.Export.GameObjectExport)
+- Add content via [AddScene](xref:GLTFast.Export.GameObjectExport.AddScene*)
 - Two options for the final export
-  - Call `SaveToFileAndDispose` to export a glTF to a file(s)
-  - Call `SaveToStreamAndDispose` to export to a `System.IO.Stream`
+  - Call [SaveToFileAndDispose](xref:GLTFast.Export.GameObjectExport.SaveToFileAndDispose*) to export a glTF to a file(s)
+  - Call [SaveToStreamAndDispose](xref:GLTFast.Export.GameObjectExport.SaveToStreamAndDispose*) to export to a [Stream][Stream]
 
 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;
+[!code-cs [simple-export](../Samples/Documentation/Manual/SimpleExport.cs#SimpleExport)]
 
-public class TestExport : MonoBehaviour {
+After calling [SaveToFileAndDispose](xref:GLTFast.Export.GameObjectExport.SaveToFileAndDispose*) the GameObjectExport instance becomes invalid. Do not re-use it.
 
-    [SerializeField]
-    string path;
+Further, the export can be customized by passing [ExportSettings](xref:GLTFast.Export.ExportSettings), [GameObjectExportSettings](xref:GLTFast.Export.GameObjectExportSettings) and injectables to [GameObjectExport](xref:GLTFast.Export.GameObjectExport)'s constructor:
 
-    async void SimpleExport() {
+[!code-cs [advanced-export](../Samples/Documentation/Manual/ExportSamples.cs#AdvancedExport)]
 
-        // Example of gathering GameObjects to be exported (recursively)
-        var rootLevelNodes = GameObject.FindGameObjectsWithTag("ExportMe");
+> **NOTE:** Exporting to a [Stream][Stream] currently only works for self-contained glTF-Binary files (where the binary buffer and all textures are included in the `.glb` file). Trying other export settings will fail.
 
-        // GameObjectExport lets you create glTFs from GameObject hierarchies
-        var export = new GameObjectExport();
+### Scene Origin
 
-        // Add a scene
-        export.AddScene(rootLevelNodes);
+When adding GameObjects to a glTF scene, the resulting glTF root nodes' positions will be their original GameObjects' world position in the Unity scene. That might be undesirable (e.g. if the scene is far off the origin and thus not centered), so [AddScene](xref:GLTFast.Export.GameObjectExport.AddScene(ICollection{UnityEngine.GameObject},Unity.Mathematics.float4x4,System.String)) allows you to provide an inverse scene origin matrix that'll be applied to all root-level nodes.
 
-        // Async glTF export
-        bool success = await export.SaveToFileAndDispose(path);
+Here's an example how to export a GameObject, discarding its transform:
 
-        if(!success) {
-            Debug.LogError("Something went wrong exporting a glTF");
-        }
-    }
-}
-```
+[!code-cs [local-transform](../Samples/Documentation/Manual/ExportSamples.cs#LocalTransform)]
 
-After calling `SaveToFileAndDispose` the GameObjectExport instance becomes invalid. Do not re-use it.
+### Vertex Attribute Discarding
 
-Further, the export can be customized by passing `ExportSettings`, `GameObjectExportSettings` and injectables to the `GameObjectExport`'s
-constructor:
+In certain cases glTFast discards mesh vertex attributes that are not used or required. This not only reduces the resulting glTF's file size, but in case of vertex colors, is necessary to preserve visual consistency.
 
-```c#
-using GLTFast;
-using UnityEngine;
-using GLTFast.Export;
-using GLTFast.Logging;
+This behavior might be undesirable, for example in authoring workflows where the resulting glTF will be further edited. In that case vertex attribute discarding can be disabled on a per-attribute basis by setting [ExportSettings' PreservedVertexAttributes](xref:GLTFast.Export.ExportSettings.PreservedVertexAttributes) mask.
 
-public class TestExport : MonoBehaviour {
+Examples of vertex attribute discarding:
 
-    [SerializeField]
-    string path;
+- Vertex colors, when the assigned material(s) do not use them.
+- Normals and tangents, when the assigned material is unlit and does not require them for shading.
+- When no material was assigned, a default fallback material will be assumed. This does not require tangents nor texture coordinates, hence those are discarded.
 
-    async void AdvancedExport() {
-
-        // CollectingLogger lets you programmatically go through
-        // errors and warnings the export raised
-        var logger = new CollectingLogger();
-
-        // ExportSettings and GameObjectExportSettings allow you to configure the export
-        // Check their respective source for details
-
-        // ExportSettings provides generic export settings
-        var exportSettings = new ExportSettings {
-            Format = GltfFormat.Binary,
-            FileConflictResolution = FileConflictResolution.Overwrite,
-            // Export everything except cameras or animation
-            ComponentMask = ~(ComponentType.Camera | ComponentType.Animation),
-            // Boost light intensities
-            LightIntensityFactor = 100f,
-        };
-
-        // GameObjectExportSettings provides settings specific to a GameObject/Component based hierarchy
-        var gameObjectExportSettings = new GameObjectExportSettings {
-            // Include inactive GameObjects in export
-            OnlyActiveInHierarchy = false,
-            // Also export disabled components
-            DisabledComponents = true,
-            // Only export GameObjects on certain layers
-            LayerMask = LayerMask.GetMask("Default", "MyCustomLayer"),
-        };
-
-        // GameObjectExport lets you create glTFs from GameObject hierarchies
-        var export = new GameObjectExport( exportSettings, gameObjectExportSettings, logger: logger);
-
-        // Example of gathering GameObjects to be exported (recursively)
-        var rootLevelNodes = GameObject.FindGameObjectsWithTag("ExportMe");
-
-        // Add a scene
-        export.AddScene(rootLevelNodes, "My new glTF scene");
-
-        // Async glTF export
-        var success = await export.SaveToFileAndDispose(path);
-
-        if(!success) {
-            Debug.LogError("Something went wrong exporting a glTF");
-            // Log all exporter messages
-            logger.LogAll();
-        }
-    }
-}
-```
-
-> Exporting to a `Stream` currently only works for self-contained glTF-Binary files (where the binary buffer and all textures are included in the `.glb` file). Trying other export settings will fail.
+> **NOTE:** Not all cases of potential discarding are covered at the moment (e.g. unused texture coordinates when no textures are assigned).
 
 ### Draco Compression
 
 *Unity glTFast* supports applying [Google Draco&trade; 3D Data compression][Draco] to meshes. This requires the [Draco for Unity][DracoForUnity] package to be installed.
 
-```csharp
-// ExportSettings provides generic export settings
-var exportSettings = new ExportSettings {
-    ...
-    // Enable Draco compression
-    Compression = Compression.Draco,
-    // Tweak the Draco compression settings
-    DracoSettings = new DracoExportSettings {
-        positionQuantization = 12
-    }
-};
-```
+[!code-cs [draco-export](../Samples/Documentation/Manual/ExportSamples.cs#ExportSettingsDraco)]
 
 ## Trademarks
 
@@ -151,3 +74,4 @@ var exportSettings = new ExportSettings {
 [GoogleLLC]: https://about.google/
 [khronos]: https://www.khronos.org
 [unity]: https://unity.com
+[Stream]: https://learn.microsoft.com/en-us/dotnet/api/system.io.stream
diff --git a/Documentation~/KnownIssues.md b/Documentation~/KnownIssues.md
@@ -1,12 +1,12 @@
 # Known Issues
 
-- <sup>1</sup>Vertex accessors (positions, normals, etc.) that are used across meshes are duplicated and result in higher memory usage and slower loading (see [this comment](https://github.com/atteneder/glTFast/issues/52#issuecomment-583837852))
-- <sup>1</sup>When using more than one sampler on one image, that image is duplicated and results in higher memory usage
+- ¹Vertex accessors (positions, normals, etc.) that are used across meshes are duplicated and result in higher memory usage and slower loading (see [this comment](https://github.com/atteneder/glTFast/issues/52#issuecomment-583837852))
+- ¹When using more than one sampler on one image, that image is duplicated and results in higher memory usage
 - Texture sampler minification/magnification filter limitations (see [issue][SamplerFilter]):
-  - <sup>1</sup>There's no differentiation between `minFilter` and `magFilter`. `minFilter` settings are prioritized.
-  - <sup>1</sup>`minFilter` mode `NEAREST_MIPMAP_LINEAR` is not supported and will result in `NEAREST`.
+  - ¹There's no differentiation between `minFilter` and `magFilter`. `minFilter` settings are prioritized.
+  - ¹`minFilter` mode `NEAREST_MIPMAP_LINEAR` is not supported and will result in `NEAREST`.
 
-<sup>1</sup>: A Unity API limitation.
+¹: A Unity API limitation.
 
 ## Trademarks
 

diff --git a/Documentation~/TableOfContents.md b/Documentation~/TableOfContents.md
@@ -15,3 +15,4 @@
   * [Known Issues](KnownIssues.md)
   * [Physical Light Units in glTF](LightUnits.md)
   * [Implementation Details](ImplementationDetails.md)
+  * [Apple Privacy Manifest](apple-privacy-manifest.md)
diff --git a/Documentation~/apple-privacy-manifest.md b/Documentation~/apple-privacy-manifest.md
@@ -0,0 +1,21 @@
+# Apple privacy manifest
+To publish applications for iOS, iPadOS, tvOS, and visionOS platforms on the App Store, you must include a [privacy manifest file](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) in your application as per [Apple’s privacy policy](https://www.apple.com/legal/privacy/en-ww/).
+
+> [!NOTE]
+> **Note**:
+For information on creating a privacy manifest file to include in your application, refer to [Apple’s privacy manifest policy requirements](https://docs.unity3d.com/Manual/apple-privacy-manifest-policy.html).
+
+The PrivacyInfo.xcprivacy manifest file outlines the required information, ensuring transparency in accordance with user privacy practices. This file lists the [types of data](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_data_use_in_privacy_manifests) that your Unity applications, third-party SDKs, packages, and plug-ins collect, and the reasons for using certain [required reason API](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api) (Apple documentation) categories. Apple also requires that certain domains be declared as [tracking](https://developer.apple.com/app-store/user-privacy-and-data-use/) (Apple documentation); these domains might be blocked unless a user provides consent.
+> [!WARNING]
+> **Important**: If your privacy manifest doesn’t declare the use of the required reason API by you or third-party SDKs, the App Store might reject your application. Read more about the [required reason API](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files/describing_use_of_required_reason_api) in Apple’s documentation.
+
+The Unity Cloud gltFast package does not collect data or engage in any data practices requiring disclosure in a privacy manifest file.
+
+> [!NOTE]
+> Note: The Unity Cloud gltFast package is dependent on the following services. Refer to their manifest files for applicable data practices.
+>
+> * `com.unity.burst`
+> * `com.unity.mathematics`
+> * `com.unity.collections`
+> * `com.unity.modules.unitywebrequest`
+> * `com.unity.modules.jsonserialize`