diff --git a/docfx/articles/en/gltf/0_82_glb_import.md b/docfx/articles/en/gltf/0_82_glb_import.md index 64c6eb6a9..4350f6a7a 100644 --- a/docfx/articles/en/gltf/0_82_glb_import.md +++ b/docfx/articles/en/gltf/0_82_glb_import.md @@ -1,9 +1,133 @@ +This is `0.82.1` API. +If use `0.82.0`, please upgrade. -## GLB +GLB load is below steps. -Set `materialGenerator` argument, Material is replaced by URP version. +1. Parse `GLB` / `GLTF`, get a `GltfData` +2. Load `Unity Hierarchy` from the `GltfData`, get a `RuntimeGltfInstance`, dispose loader. +3. Use the `RuntimeGltfInstance`, destroy the `RuntimeGltfInstance`. + +# 1. Parse + +## Parse glb from file path + +* same as `vrm` ```cs -var data = new GlbFileParser(path).Parse(); -var loader = new UniGLTF.ImporterContext(data, materialGenerator: new GltfUrpMaterialDescriptorGenerator()); +GltfData Load(string path) +{ + return new GlbFileParser(path).Parse(); +} +``` + +## Parse glb byte array + +* same as `vrm` + +```cs +GltfData Load(byte[] bytes) +{ + return new GlbBinaryParser(bytes, "LOAD_NAME").parse(); +} +``` + +## Parse gltf from file path + +```cs +GltfData Load(string path) +{ + return new GltfFileWithResourceFilesParser(path).Parse(); +} +``` + +## Parse gltf in zip archive from file path + +Zip archive that contain gltf and related files can parsed (experimental). + +```cs +GltfData Load(string path) +{ + return new ZipArchivedGltfFileParser(path).Parse(); +} +``` + +## Parse by file extension + +See `SimpleViewer` sample. + +```cs +GltfData Load(string path) +{ + var ext = Path.GetExtension(path).ToLower(); + switch(ext) + { + case ".glb": return new GlbFileParser(path).Parse(); + case ".gltf": return new GltfFileWithResourceFilesParser(path).Parse(); + case ".zip": return new ZipArchivedGltfFileParser(path).Parse(); + default: throw new Exception($"unknown: {ext}"); + } +} +``` + +# 2. Load + +## sync + +```cs +RuntimeGltfInstance Load(GltfData data) +{ + // Call ImporterContext.Dispose after load. + // Automatically load dispose by using. + using(var loader = new UniGLTF.ImporterContext(data) + { + var instance = loader.Load(); + return instance; + } +} +``` + +## async + +```cs +async RuntimeGltfInstance Load(GltfData data) +{ + // Call ImporterContext.Dispose after load. + // Automatically load dispose by using. + using(var loader = new UniGLTF.ImporterContext(data) + { + var instance = await loader.LoadAsync(); + return instance; + } +} +``` + +## Load URP material by materialGenerator argument + +You can load URP materials by setting the `materialGenerator` Argument (optional). + +```cs +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; + } +} +``` + +# 3. Use instance + +```cs +// Setup for SkinnedMeshRenderer +instance.EnableUpdateWhenOffscreen(); +// Show meshes when ready(invisible by default) +instance.ShowMeshes(); +``` + +Destroy after use and discard related assets (textures, materials, meshes, etc.) + +```cs +GameObject.Destroy(instance); ``` diff --git a/docfx/articles/en/vrm0/0_82_runtime_import.md b/docfx/articles/en/vrm0/0_82_runtime_import.md index 82e3a5ec3..65c502f85 100644 --- a/docfx/articles/en/vrm0/0_82_runtime_import.md +++ b/docfx/articles/en/vrm0/0_82_runtime_import.md @@ -5,51 +5,72 @@ Material replacement for URP when Import is implemented . Below step is needed. -1. Parse VRM, and Get VrmData. -1. Create VrmImporter, and load Unity hierarchy. -1. Use loaded instance(ShowMeshes) +1. Parse VRM, and Get `GltfData`. +1. Get `VRMData` from `GltfData`. +1. Load a `RuntimeGltfInstance` from `VRMData`. +1. Use the `RuntimeGltfInstance` -# 1. Parse - -`v0.82.1` VrmData is introduced. +# 1. Get `GltfData` ```cs -var data = new UniGLTF.GlbFileParser(path).Parse(); -VrmData vrm = new VRM.VRMData(data); +GltfData Load(string path) +{ + return new GlbFileParser(path).Parse(); +} ``` -# 2. Load +See [GLB import](../gltf/0_82_glb_import.md). -`v0.82.1` VrmData is introduced. +# 2. Get `VRMData` ```cs -var loader = new VRM.VRMImporterContext(vrm); -RuntimeGltfInstance instance = context.Load(); +VRMData vrm = new VRMData(data); ``` -## Set `materialGenerator` argument for URP +# 3. Load + +```cs +async RuntimeGltfInstance Load(VRMData vrm) +{ + // Dispose VRMImporterContext, after load + using(var loader = new VRMImporterContext(vrm)) + { + var instance = await loader.LoadAsync(); + return instance; + } +} +``` + +## Set `materialGenerator` argument for URP(Experimental) Set `materialGenerator` Argument, material generation is could customized. If omitted, default `materialGenerator` for `built-in` pipeline is used. ```cs -var loader = new VRM.VRMImporterContext(vrm, materialGenerator: new VRMUrpMaterialDescriptorGenerator(vrm.VrmExtension)); +async RuntimeGltfInstance Load(VRMData vrm) +{ + var materialGenerator = new VRMUrpMaterialDescriptorGenerator(vrm.VrmExtension); + using(var loader = new VRM.VRMImporterContext(vrm, materialGenerator: materialGenerator)) + { + var instance = await loader.LoadAsync(); + return instance; + } +} ``` * `MToonShader for URP` has not been implemented yet, fallback to `UniUnlit`. -# 3. Instance -## ShowMeshes +# 4. Instance -`v0.77` ShowMeshes method is move to RuntimeGltfInstance from Importer. ```cs +// Setup for SkinnedMeshRenderer +instance.EnableUpdateWhenOffscreen(); +// Show meshes when ready(invisible by default) instance.ShowMeshes(); ``` -## Destroy - -`v0.77` When destroy, related assets(meshes, materials and textures etc...) is destroyed. +When destroy, related assets(meshes, materials and textures etc...) is destroyed. ```cs GameObject.Destroy(instance); diff --git a/docfx/articles/ja/gltf/0_82_glb_import.md b/docfx/articles/ja/gltf/0_82_glb_import.md index a2ad6a9af..e7dc93c9c 100644 --- a/docfx/articles/ja/gltf/0_82_glb_import.md +++ b/docfx/articles/ja/gltf/0_82_glb_import.md @@ -1,9 +1,132 @@ +`0.82.1` の API です。 +`0.82.0` の場合は更新をお願いします。 -## GLB +以下のステップでロードします。 + +1. `GLB` / `GLTF` をパースして `GltfData` を得る。 +2. `GltfData` から `Unity Hierarchy` を ロード する。`RuntimeGltfInstance` を得る。 ローダーを破棄する。 +3. ロードした `RuntimeGltfInstance` 使う。`RuntimeGltfInstance` を破棄する。 + +# 1. パースする + +## glb ファイルパスからパースする + +* `vrm` もこの関数を使います。 + +```cs +GltfData Load(string path) +{ + return new GlbFileParser(path).Parse(); +} +``` + +## glb バイト列をパースする + +* `vrm` もこの関数を使います。 + +```cs +GltfData Load(byte[] bytes) +{ + return new GlbBinaryParser(bytes, "LOAD_NAME").parse(); +} +``` + +## gltf ファイルパスからパースする + +```cs +GltfData Load(string path) +{ + return new GltfFileWithResourceFilesParser(path).Parse(); +} +``` + +## zip アーカイブからパースする + +gltf と関連するファイルを zip アーカイブしたファイルをパースできます(実験)。 + +```cs +GltfData Load(string path) +{ + return new ZipArchivedGltfFileParser(path).Parse(); +} +``` + +## ファイルパスの拡張子でパースする + +サンプルの `SimpleViewer` を参考にしてください。 + +```cs +GltfData Load(string path) +{ + var ext = Path.GetExtension(path).ToLower(); + switch(ext) + { + case ".glb": return new GlbFileParser(path).Parse(); + case ".gltf": return new GltfFileWithResourceFilesParser(path).Parse(); + case ".zip": return new ZipArchivedGltfFileParser(path).Parse(); + default: throw new Exception($"unknown: {ext}"); + } +} +``` + +# 2. ロードする + +## sync + +```cs +RuntimeGltfInstance Load(GltfData data) +{ + // ImporterContext は使用後に Dispose を呼び出してください。 + // using で自動的に呼び出すことができます。 + using(var loader = new UniGLTF.ImporterContext(data) + { + var instance = loader.Load(); + return instance; + } +} +``` + +## async + +```cs +async RuntimeGltfInstance Load(GltfData data) +{ + // ImporterContext は使用後に Dispose を呼び出してください。 + // using で自動的に呼び出すことができます。 + using(var loader = new UniGLTF.ImporterContext(data) + { + var instance = await loader.LoadAsync(); + return instance; + } +} +``` + +## materialGenerator で URP 用のマテリアルをロードする `materialGenerator` 引き数(省略可能)を指定することで URP マテリアルを生成するようにカスタムできます。 ```cs -var data = new GlbFileParser(path).Parse(); -var loader = new UniGLTF.ImporterContext(data, materialGenerator: new GltfUrpMaterialDescriptorGenerator()); +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; + } +} +``` + +# 3. インスタンスを使用する + +```cs +// SkinnedMeshRenderer に対する指示 +instance.EnableUpdateWhenOffscreen(); +// 準備ができたら表示する(デフォルトでは非表示) +instance.ShowMeshes(); +``` + +使用後に以下のように破棄してください。関連する Asset(Texture, Material, Meshなど)も破棄されます。 +```cs +GameObject.Destroy(instance); ``` diff --git a/docfx/articles/ja/vrm0/0_82_runtime_import.md b/docfx/articles/ja/vrm0/0_82_runtime_import.md index 0eca9234c..79f93f5fb 100644 --- a/docfx/articles/ja/vrm0/0_82_runtime_import.md +++ b/docfx/articles/ja/vrm0/0_82_runtime_import.md @@ -1,56 +1,73 @@ * `Version 0.82.0` `0.82.1` 以降を使ってください。 * `Version 0.82.1~` -Import時の Material 差し替え機能(URP対応)が実装されました。 - 以下の手順で import します。 -1. VRMをパースして、VrmDataを得る -1. VrmImporter 作成して、 Unity のヒエラルキーをロードする -1. ロードされたインスタンスを使う(ShowMeshes) +1. VRMをパースして、`GltfData` を得る。 +1. `GltfData` から `VRMData` を得る。 +1. `VrmData` から `RuntimeGltfInstance` をロードする。 +1. `RuntimeGltfInstance` を使う。 -# 1. Parse - -`v0.82.1` VrmData が導入されます。 +# 1. `GltfData` を得る ```cs -var data = new UniGLTF.GlbFileParser(path).Parse(); -VrmData vrm = new VRM.VRMData(data); +GltfData Load(string path) +{ + return new GlbFileParser(path).Parse(); +} ``` -# 2. Load +[GLB import](../gltf/0_82_glb_import.md) も参照してください。 -`v0.82.1` VrmData が導入されます。 +# 2. `VRMData` を得る ```cs -var loader = new VRM.VRMImporterContext(vrm); -RuntimeGltfInstance instance = context.Load(); +VRMData vrm = new VRMData(data); ``` -## URP 向けに `materialGenerator` を指定する +# 3. Load する + +```cs +async RuntimeGltfInstance Load(VRMData vrm) +{ + // 使用後に Dispose で VRMImporterContext を破棄してください。 + using(var loader = new VRMImporterContext(vrm)) + { + var instance = await loader.LoadAsync(); + return instance; + } +} +``` + +## URP 向けに `materialGenerator` を指定する(実験) `materialGenerator` 引き数(省略可能)を指定することで URP マテリアルを生成するようにカスタムできます。 指定しない場合は `built-in` 向けのデフォルトが使用されます。 ```cs -var loader = new VRM.VRMImporterContext(vrm, materialGenerator: new VRMUrpMaterialDescriptorGenerator(vrm.VrmExtension)); +async RuntimeGltfInstance Load(VRMData vrm) +{ + var materialGenerator = new VRMUrpMaterialDescriptorGenerator(vrm.VrmExtension); + using(var loader = new VRM.VRMImporterContext(vrm, materialGenerator: materialGenerator)) + { + var instance = await loader.LoadAsync(); + return instance; + } +} ``` -* まだ URP 向け MToonShader が作成されていないので、URP 向け `UniUnlit` にフォールバックします。 +* まだ URP 向け MToonShader が作成されていないので、`UniUnlit` にフォールバックします。 -# 3. Instance -## ShowMeshes - -`v0.77` ShowMeshes が loader から instance に移動しました。 +# 4. Instance ```cs +// SkinnedMeshRenderer に対する指示 +instance.EnableUpdateWhenOffscreen(); +// 準備ができたら表示する(デフォルトでは非表示) instance.ShowMeshes(); ``` -## Destroy - -`v0.77` 破棄時に関連する Asset を破棄するようになりました。 - +使用後に以下のように破棄してください。関連する Asset(Texture, Material, Meshなど)も破棄されます。 ```cs GameObject.Destroy(instance); ```