Merge pull request #28 from vrm-c/merge/2024-02-19

Merge/2024 02 19

blog/2024-02-19-api.md

@@ -0,0 +1,10 @@
+---
+title: 開発ドキュメントの移動
+authors: [vrmc]
+tags: [maintenance]
+---
+
+https://vrm-c.github.io/UniVRM/ のドキュメントを本サイトに移動しました。
+おもに [/api/](/api/) フォルダー配下になります。
+
+今後はこちらで更新していきます。

docs/api/0_95_highlevel.md

@@ -3,26 +3,67 @@
 API が複雑化してきたので、よくある用途を簡単にできる高レベル API を追加しました。
 `GltfUtility` と `VrmUtility` が中で using してくれるので await で呼び出すだけで使えます。
 
+:::warning 以下の例は Unity-2023.1向けです
+
+古いUnityでは GetAwaiter を自前で用意すると動きます。
+
+[UnityWebRequestでasync awaitする メモ](https://qiita.com/satotin/items/579fa3b9da0ad0d899e8)
+
+:::
+
 ## GLTF
 
-```{gitinclude} v0.95.0 Assets/UniGLTF/Runtime/UniGLTF/IO/GltfUtility.cs
-:language: csharp
-:linenos:
+```cs title="SendWebRequest から bytes を得る例"
+using System.IO;
+using UniGLTF;
+using UnityEngine;
+using UnityEngine.Networking;
+
+public class VrmLoader : MonoBehaviour
+{
+    public string Url = "https://raw.GithubUserContent.com/KhronosGroup/glTF-Sample-Assets/main/./Models/DamagedHelmet/glTF-Binary/DamagedHelmet.glb";
+
+    // Start is called before the first frame update
+    async void Start()
+    {
+        var req = UnityWebRequest.Get(Url);
+        await req.SendWebRequest();
+
+        var bytes = req.downloadHandler.data;
+        var loaded = await GltfUtility.LoadBytesAsync(Path.GetFileName(Url), bytes);
+
+        loaded.ShowMeshes();
+    }
+}
 ```
 
 ## VRM
 
-```{gitinclude} v0.95.0 Assets/VRM/Runtime/IO/VrmUtility.cs
-:language: csharp
-:linenos:
+```cs title="SendWebRequest から bytes を得る例"
+using System.IO;
+using UnityEngine;
+using UnityEngine.Networking;
+using VRM;
+
+public class VrmLoader : MonoBehaviour
+{
+    public string Url = "https://raw.GithubUserContent.com/vrm-c/UniVRM/master/./Tests/Models/Alicia_vrm-0.51/AliciaSolid_vrm-0.51.vrm";
+
+    // Start is called before the first frame update
+    async void Start()
+    {
+        var req = UnityWebRequest.Get(Url);
+        await req.SendWebRequest();
+
+        var bytes = req.downloadHandler.data;
+
+        var loaded = await VrmUtility.LoadBytesAsync(Path.GetFileName(Url), bytes);
+
+        loaded.ShowMeshes();
+    }
+}
 ```
 
 ## 使用例
 
-```{gitinclude} v0.95.0 Assets/VRM_Samples/SimpleViewer/ViewerUI.cs
-:language: csharp
-:linenos:
-:lines: 370-392
-:emphasize-lines: 10, 20
-:caption:
-```
+`Assets/VRM_Samples/SimpleViewer/ViewerUI.cs`

docs/api/index.mdx

@@ -0,0 +1,6 @@
+import DocCardList from '@theme/DocCardList';
+
+# UniVRM API
+
+<DocCardList />
+

docs/api/load/index.md

@@ -2,38 +2,4 @@
 
 `v0.118`
 
-`UniGLTF.GltfData` の生成、
-`UniGLTF.GltfData` からシーンを構築するの 2 ステップになっています。
-
-## `UniGLTF.GltfData` の生成
-
-:::info UniGLTF.GltfData は vrm-0, vrm-1, glb, gltf で共通です
-:::
-
-:::tip UniGLTF.GltfData の生成はスレッドセーフです
-Unity にアクセスしません。
-:::
-
-[glb_import](/api/0_82_glb_import)
-
-## `UniGLTF.GltfData` からシーンを構築する
-
-### glb(gltf)
-
-[glb_import](/api/0_82_glb_import)
-
-### vrm-0.x
-
-GltfData から VrmData を生成し、
-VrmData から シーンを構築します。
-
-TODO:
-
-`Assets/VRM/Runtime/IO/VrmUtility.cs` に使用例があります。
-
-### vrm-1.0
-
-GltfData から Vrm10Data を生成し、
-Vrm10Data から シーンを構築します。
-
-[vrm-1.0](/api/vrm1_load)
+[RuntimeImport](/api/runtime-import/)

docs/api/runtime-import/RuntimeGltfInstance.md

@@ -0,0 +1,56 @@
+# RuntimeGltfInstane
+
+ヒエラルキーの root にアタッチされます。
+リソースの破棄について。
+
+## ShowMeshes
+
+```cs
+        public void ShowMeshes()
+        {
+            foreach (var r in VisibleRenderers)
+            {
+                r.enabled = true;
+            }
+        }
+```
+
+## EnableUpdateWhenOffscreen
+
+```cs
+        public void EnableUpdateWhenOffscreen()
+        {
+            foreach (var skinnedMeshRenderer in SkinnedMeshRenderers)
+            {
+                skinnedMeshRenderer.updateWhenOffscreen = true;
+            }
+        }
+```
+
+## Dispose
+
+関連するリソースを破棄します。
+
+```cs
+        public void Dispose()
+        {
+            if (this != null && this.gameObject != null)
+            {
+                UnityObjectDestroyer.DestroyRuntimeOrEditor(this.gameObject);
+            }
+        }
+```
+
+:::tip GameObject.Destory でも破棄できます
+
+```cs
+        void OnDestroy()
+        {
+            foreach (var (_, obj) in _resources)
+            {
+                UnityObjectDestroyer.DestroyRuntimeOrEditor(obj);
+            }
+        }
+```
+
+:::

docs/api/runtime-import/await_caller.md

@@ -0,0 +1,41 @@
+# import の最適化について
+
+## GltfData
+
+:::tip UniGLTF.GltfData の生成はスレッドセーフです
+Unity にアクセスしません。
+Parse を別スレッドで実行可能です。
+
+```cs
+// 使用例
+var task = Task.Run(()=>{
+  // スレッド OK
+  return new GlbBinaryParser(bytes, path).Parse();
+});
+
+using(var data = await task){
+
+}
+```
+
+:::
+
+## IAwaitCaller
+
+Task を小出しにすることでフレームレートの低下に対策できます。
+
+[0_87_runtime_import](/api/0_87_runtime_import)
+
+### ImmediateCaller
+
+小出しにせずに普通に処理します。
+UnityEditor や UnitTest など Unity の frame が回っていない環境でも
+動くように作られています。
+
+### RuntimeOnlyAwaitCaller
+
+Unity の `yield return` と似た感じです。
+後続の処理を次のフレームに先送りします。
+
+:::tip フレーム当りの処理量は減るがトータルで必要な時間は長くなります
+:::

docs/api/runtime-import/gltfdata.md

@@ -0,0 +1,37 @@
+# GltfData
+
+`.glb`, `.vrm`, `.vrma` など から GltfData をロードします。
+
+GltfData が入手できたら中身に合わせた GameObject 生成へと分岐してください。
+
+## `byte[]` からロードする
+
+```cs
+public sealed class GlbBinaryParser
+{
+    public GlbBinaryParser(byte[] data, string uniqueName)
+}
+
+// 使用例
+using (GltfData data = new GlbBinaryParser(bytes, path).Parse())
+{
+}
+```
+
+## filepath からロードする
+
+```cs
+public sealed class GlbFileParser
+{
+    public GlbFileParser(string glbFilePath)
+}
+
+// 使用例
+using (GltfData data = new GlbFileParser(path).Parse())
+{
+}
+```
+
+## Dispose
+
+- [0_95_dispose](/api/0_95_dispose)

docs/api/runtime-import/import_glb.md

@@ -0,0 +1,17 @@
+# load glb
+
+[GltfData](/api/runtime-import/gltfdata) から Unity ヒエラルキーを構築します。
+
+<!-- truncate -->
+
+:::info glTF形式
+glTF は glb と比べてアプリケーションからの扱いが煩雑です。
+複数のファイルへのアクセスが発生するためです。
+mobile 環境、webgl 環境などディレクトリへの自由なアクセスが制限される環境で
+は特に難しくなります。
+
+特別な目的が無い場合は gltf よりも glb をお勧めします。
+(vrm や vrma は glb の拡張子を変更したものです)
+:::
+
+[glb_import](/api/0_82_glb_import)

docs/api/runtime-import/import_urp.md

@@ -0,0 +1,5 @@
+# import URP
+
+オプションで urp material への差し替えができます。
+
+[0_112_urp](/api/0_112_urp)

docs/api/runtime-import/import_vrm0.md

@@ -0,0 +1,13 @@
+# load vrm-0.x
+
+[GltfData](/api/runtime-import/gltfdata) から vrm-0.x ヒエラルキーを構築します。
+
+<!-- truncate -->
+
+:::warning
+
+vrm-1.0 のモデルはロードできません。
+
+:::
+
+[0_82_runtime_import](/api/0_82_runtime_import)

docs/api/runtime-import/index.mdx

@@ -0,0 +1,21 @@
+import DocCardList from '@theme/DocCardList';
+
+# Runtime Import
+
+glb vrm vrma などのファイルを入力、
+UnityEngine.GameObject のヒエラルキーを出力とする手順です。
+2ステップに別れています。
+
+はじめにファイルから中間データ[UniGLTF.GltfData](/api/runtime-import/gltfdata)  の生成をします。この手順は glb, vrm-0.x, vrm-1.0, vrm-animation で共通です。
+
+次に glb, vrm-0.x, vrm-1.0, vrm-animation などの glTF 拡張に応じた
+GameObject 構築手順を実行します。
+
+:::info 便利関数
+
+[0_95_highlevel](/api/0_95_highlevel)
+
+:::
+
+<DocCardList />
+

docs/api/sample/index.mdx

@@ -0,0 +1,6 @@
+import DocCardList from '@theme/DocCardList';
+
+# Samples
+
+<DocCardList />
+

docs/api/sample/sample_install.md

@@ -0,0 +1,44 @@
+# UniVRM サンプルをインストールする
+
+このセクションでは、[UniVRM パッケージをインストール](/univrm/install/univrm_install)したことを想定しています。
+
+## UniVRM サンプルのパッケージ
+
+`v0.81.0` から UniVRM サンプルは UniVRM パッケージに含まれています。  
+最新の UniVRM バージョンがインストールされている場合は、**UniVRM サンプルのシーンを実行する**セクションをご覧ください。
+
+### ~ v0.80.0
+
+https://github.com/vrm-c/UniVRM/releases
+
+`UniVRM-samples-0.XX.X_XXXX.unitypackage`
+
+です。
+
+### インポート
+
+メニューから `Assets -> Import Package -> Custom Package` で `UniVRM-samples-0.XX.X_XXXX.unitypackage` を選択します。
+
+以下の画像ようにインポートウィンドウを見たら、`Import`ボタンをクリックしてください：
+
+![sample_package_import](/images/vrm/sample_package_import.jpg)
+
+## UniVRM サンプルのシーンを実行する
+
+`VRM.Samples`フォルダは`Assets`にあります。プロジェクトウィンドウに`SampleViewer`を選択します：
+
+![sample_scene](/images/vrm/sample_scene.jpg)
+
+`Game`タブをクリックして、`SampleViewer`のインタフェースを表示させます：
+
+![sample_viewer](/images/vrm/sample_viewer.jpg)
+
+`Play`ボタンをクリックして`SampleViewer`を有効になります。実行時に`Open`ボタンをクリックして VRM モデルをシーンにインポートします：
+
+![play_mode](/images/vrm/play_mode.jpg)
+
+![sample_viewer_activate](/images/vrm/sample_viewer_activate.jpg)
+
+`VRM.Samples`に[ランタイム VRM エクスポート](https://github.com/vrm-c/UniVRM/tree/master/Assets/VRM/Samples/RuntimeExporterSample)と[一人称レンダリング](https://github.com/vrm-c/UniVRM/tree/master/Assets/VRM/Samples/FirstPersonSample)のサンプルがあります。
+
+Alicia モデルは[こちら](https://github.com/vrm-c/UniVRM/blob/master/Tests/Models/Alicia_vrm-0.51/AliciaSolid_vrm-0.51.vrm)。