Merge pull request #1336 from ousttrue/doc/update_20211022

Doc/update 20211022

.github/workflows/sphinx.yml

@@ -17,6 +17,7 @@ jobs:
       - run: pip install sphinx-rtd-theme
       - run: sudo apt install gettext
       - run: pip install sphinx-intl
+      - run: pip install gitinclude
       - name: sphinx build(ja)
         working-directory: ./docs
         run: sphinx-build . ../public/ja

docs/_static/custom.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1200px !important;
+}

docs/conf.py

@@ -25,7 +25,7 @@ author = 'VRM Consortium'
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['myst_parser']
+extensions = ['myst_parser', 'gitinclude']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

docs/gltf/0_82_glb_import.md

@@ -97,19 +97,7 @@ async RuntimeGltfInstance Load(GltfData data)
 
 ### materialGenerator で URP 用のマテリアルをロードする
 
-`materialGenerator` 引き数(省略可能)を指定することで URP マテリアルを生成するようにカスタムできます。
-
-```csharp
-async RuntimeGltfInstance Load(GltfData data)
-{
-    var materialGenerator = new GltfUrpMaterialDescriptorGenerator();
-    using(var loader = new UniGLTF.ImporterContext(data, materialGenerator: materialGenerator)
-    {
-        var instance = await loader.LoadAsync();
-        return instance;
-    }
-}
-```
+{doc}`Import 時に生成される Material をカスタマイズする </gltf/how_to_customize_material_import>`
 
 ## 3. インスタンスを使用する
 

docs/gltf/how_to_customize_material_import.md

@@ -0,0 +1,21 @@
+# Import 時に生成される Material をカスタマイズする
+
+`IMaterialDescriptorGenerator` を実装することで import 時に適用されるマテリアルを差し替えることができます。
+
+## materialGenerator で URP 用のマテリアルをロードする
+
+URP マテリアルを生成するようにカスタムする例です。
+
+<https://github.com/vrm-c/UniVRM/issues/1214>
+
+```csharp
+async RuntimeGltfInstance Load(GltfData data)
+{
+    IMaterialDescriptorGenerator materialGenerator = new GltfUrpMaterialDescriptorGenerator();
+    using(var loader = new UniGLTF.ImporterContext(data, materialGenerator: materialGenerator)
+    {
+        var instance = await loader.LoadAsync();
+        return instance;
+    }
+}
+```

docs/gltf/index.md

@@ -12,7 +12,12 @@
 :maxdepth: 1
 
 0_82_glb_import
-how_to_impl_extension
+how_to_customize_material_import
 0_36_update
-format
+```
+
+```{toctree}
+:maxdepth: 1
+format
+how_to_impl_extension
 ```

docs/implementation/index.md

@@ -8,4 +8,5 @@ texture_manipulation
 coordinate
 fast_spring_bone
 first_person
+scripted_importer
 ```

docs/implementation/scripted_importer.md

@@ -0,0 +1,39 @@
+# ScriptedImporter の実装
+
+`v0.68.0` 以降 の `glb/gltf editor importer` と `VRM-1.0 editor importer` の実装で使用している [ScriptedImporter](https://docs.unity3d.com/ja/2019.4/ScriptReference/Experimental.AssetImporters.ScriptedImporter.html) に関して。
+
+> `VRM-1.0` の実装と拡張子がぶつかってしまうので `VRM-0.x` への `ScriptedImporter` 実装はしません
+
+## ScriptedImporter 採用の利点
+
+### Texture の Asset化 が楽
+
+`AssetPostprocessor` だと普通の方法では実装できない Texture のバイト列を出力して Asset 化して、
+これを参照する Material をアセット化するということが、
+`ScriptedImporter.GetExternalObjectMap` により無理をせずに実装できます。
+
+> UniVRM では抜け道として `EditorApplication.delayCall` を使用しています。
+
+### Import 設定を作れる
+
+`ScriptedImporter` を継承したクラスの `public member` や `[SerializeField]` に情報を保存できます。
+
+```cs
+// 例
+[ScriptedImporter(1, "cube")]
+public class CubeImporter : ScriptedImporter
+{
+    public float m_Scale = 1; // これを Asset の Inspector で変更して Apply すると、新しい設定で再importできる
+
+    // 省略
+}
+```
+
+### ForceText 時に import が低速化するのを回避できる
+
+`ScriptedImporter` の SubAsset にすることで、 `mesh` などがテキスト(yaml)で Asset 化されることを回避できます。
+巨大なアセットで差が出ます。
+
+## ScriptedImporter 実装
+
+TODO: ExternalObjectMap の扱い

docs/vrm0/sample/FirstPersonSample.md

@@ -8,3 +8,11 @@ VR アプリで FistPerson の設定に合わせて、可視設定を反映す
 * その他のカメラ
 
 の描画を例示します。
+
+```{gitinclude} v0.87.0 Assets/VRM_Samples/FirstPersonSample/VRMRuntimeLoader.cs
+:language: csharp
+:linenos:
+:lines: 31-53
+:emphasize-lines: 15
+:caption:
+```

docs/vrm0/sample/RuntimeExporterSample.md

@@ -1,3 +1,10 @@
 # RuntimeExporter
 
 VRM を Runtime Export するサンプルです。
+
+```{gitinclude} v0.87.0 Assets/VRM_Samples/RuntimeExporterSample/VRMRuntimeExporter.cs
+:language: csharp
+:linenos:
+:lines: 106-127
+:caption:
+```

docs/vrm0/sample/SimpleViewer.md

@@ -1,3 +1,10 @@
 # SimpleViewer
 
 Runtime ローダーのサンプルです。
+
+```{gitinclude} c89e Assets/VRM_Samples/SimpleViewer/ViewerUI.cs
+:language: csharp
+:linenos:
+:caption:
+:emphasize-lines" 434-485
+```