# ufbx Documentation(Japanese) ufbx Documentation(Japanese) # OverView # ufbx ![ufbx logo](https://ufbx.github.io/static/ufbx-cube.svg)### 🧩 ufbx — 単䞀゜ヌスファむルの FBX ロヌダヌ ****ufbx**** は、単䞀の゜ヌスファむルで構成された FBX ロヌダヌです。 このラむブラリは、FBX ファむル圢匏を簡単に扱える ****ナヌザヌフレンドリヌなむンタヌフェヌス****を提䟛するこずを目的ずし、必芁に応じお ****高床な機胜にも完党察応****しおいたす。 --- ### 特城 - ****単䞀ファむル構成****C99 / C++11 に察応した1぀の゜ヌスファむルで完結 - ****堅牢な゚ラヌハンドリング****無効なファむルやメモリ䞍足などにも安党に察応 - ****型安党なAPI****C++およびRustバむンディングでは境界チェック付きスラむスを䜿甚 - ****培底したテストずファゞングfuzzing**** による高信頌性 --- ### 💟 ダりンロヌドず䜿甚䟋 ```c ufbx_load_opts opts = { 0 }; // 任意蚭定、デフォルトを䜿う堎合は NULL を枡す ufbx_error error; // 任意、゚ラヌを無芖する堎合は NULL を枡す ufbx_scene *scene = ufbx_load_file("my_scene.fbx", &opts, &error); if (!scene) { fprintf(stderr, "読み蟌みに倱敗したした: %s\n", error.description.data); exit(1); } // 読み蟌たれた `scene` を自由に利甚できたす。 // これはただのプレヌンなデヌタ構造です // 䟋: シヌン内のすべおのオブゞェクトを列挙しお衚瀺 for (size_t i = 0; i < scene->nodes.count; i++) { ufbx_node *node = scene->nodes.data[i]; if (node->is_root) continue; printf("オブゞェクト: %s\n", node->name.data); if (node->mesh) { printf("→ メッシュ%zu 面\n", node->mesh->faces.count); } } ufbx_free_scene(scene); ``` --- ### 💡 補足 䞊蚘コヌドをコンパむルすれば、任意の `.fbx` ファむルを読み蟌み、ノヌドオブゞェクトやメッシュ情報を列挙できたす。 `scene` 構造䜓には、マテリアル、トランスフォヌム、アニメヌションなどの詳现情報も栌玍されおいたす。 # Getting started # Getting started ## Setup ### C / C++ **ufbx**はシングル゜ヌスラむブラリなので、必芁なのは2぀のファむルだけ `ufbx.c` and `ufbx.h`です。最も簡単な方法は、[https://github.com/bqqbarbhg/ufbx](https://github.com/bqqbarbhg/ufbx)からダりンロヌドするこずです。マスタヌブランチには、ラむブラリの最新の安定バヌゞョンが含たれおいたす。 単䞀の**ヘッダヌ**ラむブラリずは異なり、残りのコヌドず䞀緒にコンパむルする必芁がありたす。あるいは、#include "ufbx.c"で単䞀のファむルでコンパむルするこずも可胜です。 *****ufbx**** *は**libc 倖郚に䟝存したせんが、C 暙準数孊ラむブラリ`-``lm`をリンクするために枡す必芁がある堎合がありたす。 ``` gcc -lm ufbx.c main.c -o main clang -lm ufbx.c main.c -o main ``` ## シヌンの読み蟌み **ufbx**を䜿い始めるには、たずシヌンをロヌドする必芁がありたす。シヌンをロヌドした埌は、返された[`ufbx_scene`](https://ufbx.github.io/reference#ufbx_scene)構造䜓を調べるだけで、かなり先の凊理を行うこずができたす。ファむルからシヌンをロヌドし、シヌン階局内のオブゞェクトを衚すすべおのノヌドの名前を出力しおみたしょう。 ```c++ #include #include "ufbx.h" int main() { ufbx_scene *scene = ufbx_load_file("my_scene.fbx", nullptr, nullptr); for (ufbx_node *node : scene->nodes) { printf("%s\n", node->name.data); } ufbx_free_scene(scene); return 0; } ``` 䞊蚘の䟋では、シヌンをデフォルトオプションでロヌドし、゚ラヌ凊理に関しおはかなり厳栌に行いたした。これを修正するには、ロヌド䞭に発生した゚ラヌに関する情報を取埗するために[`ufbx_error`](https://ufbx.github.io/reference#ufbx_error)を䜿甚したす。 オプションを枡すこずもできたす[`ufbx_load_opts`](https://ufbx.github.io/reference#ufbx_load_opts)。FBXシヌンには様々な座暙系ず単䜍系があり、**ufbxは**読み蟌み時にそれらを正芏化するこずをサポヌトしおいたす。ここでは、1メヌトル単䜍の右手Y軞䞊座暙系を芁求しおいたす。 ```c++ #include #include "ufbx.h" int main() { ufbx_load_opts opts = { }; opts.target_axes = ufbx_axes_right_handed_y_up; opts.target_unit_meters = 1.0f; ufbx_error error; ufbx_scene *scene = ufbx_load_file("my_scene.fbx", &opts, &error); if (!scene) { fprintf(stderr, "Failed to load scene: %s\n", error.description.data); return 1; } for (ufbx_node *node : scene->nodes) { printf("%s\n", node->name.data); } ufbx_free_scene(scene); return 0; } ``` 必芁に応じお、 を䜿甚しおメモリからシヌンをロヌドし[`ufbx_load_memory`](https://ufbx.github.io/reference#ufbx_load_memory)`()`たり、 を䜿甚しおカスタム ストリヌムをロヌドするこずもできたす[`ufbx_load_stream`](https://ufbx.github.io/reference#ufbx_load_stream)`()`。 ## デヌタ型 **ufbx は**シヌンをデヌタずしお衚珟するこずを目的ずしおいるため、返されたデヌタを調べるだけで倚くのこずを行うこずができたす[`ufbx_scene`](https://ufbx.github.io/reference#ufbx_scene)。 倚くのCラむブラリずは異なり、**ufbxは**長さ情報のない生のポむンタを公開しないため、C以倖の蚀語でも境界チェックが可胜です。ufbx内の可倉長デヌタはすべお、 **以䞋**の型で衚珟されたす。 ```c++ // UTF-8 encoded string of `length` bytes, always NULL terminated struct ufbx_string { const char *data; size_t length; }; // Arbitrary binary data of `size` bytes struct ufbx_blob { const char *data; size_t size; }; // List of `count` objects of type T struct ufbx_T_list { T *data; size_t count; // Bounds-checked indexing and iterator support in C++ T &operator[](size_t index) const; T *begin() const; T *end() const; }; ``` [`ufbx_string`](https://ufbx.github.io/reference#ufbx_string)、[`ufbx_blob`](https://ufbx.github.io/reference#ufbx_blob)、たたは `ufbx_T_list` に含たれおいないすべおのポむンタは、 ****1぀のオブゞェクトを指す**** か、あるいは [`ufbx_nullable`](https://ufbx.github.io/reference#ufbx_nullable)が指定されおいる堎合には ****NULL**** である可胜性がありたす。 逆に蚀えば、[`ufbx_nullable`](https://ufbx.github.io/reference#ufbx_nullable)が****付いおいないポむンタ****は、必ず ****1぀の有効なオブゞェクト**** を指すこずが保蚌されおいたす。 --- デバッグ時にこれらの構造䜓を芖芚的に確認しやすくするために、[`ufbx.natvis`](https://github.com/bqqbarbhg/ufbx/blob/master/misc/ufbx.natvis) をダりンロヌドしお利甚できたす。 これは少なくずも ****MSVC****Visual Studioおよび ****VS Code**** でサポヌトされおいたす。 # Elements # Elements芁玠 — ufbx ドキュメント日本語蚳 --- ## 抂芁 ufbx のほがすべおは、`struct ufbx_element` のような「基底クラス」颚の衚珟を持぀ ****芁玠element**** で構成されたす。芁玠は `name`名前や、FBX のキヌ/倀プロパティのための `props`プロパティ集合ずいった共通プロパティを含みたす。 `ufbx_node`、`ufbx_mesh`、`ufbx_material` ずいった「掟生」型は、無名 `union` ずしお `ufbx_element` ヘッダを埋め蟌んでおり、`ufbx_element` ぞキャストしたり、`ufbx_element` の共通プロパティぞ盎接アクセスできたす。 --- ## 䟋C ```c++ void list_nodes(ufbx_scene *scene) { for (size_t i = 0; i < scene->nodes.count; i++) { ufbx_node *node = scene->nodes.data[i]; printf("Node: '%s'\n", node->element.name.data); // 同等の省略圢: printf("Node: '%s'\n", node->name.data); } } ``` --- ## Element IDs芁玠ID `ufbx_scene` は利䟿性のためにネストしたポむンタ構造をずりたすが、識別子IDを䜿えるず䟿利なこずがよくありたす - `ufbx_element.element_id`シヌン党䜓で䞀意な連番むンデックス`scene.elements` 内 - `ufbx_element.typed_id`同䞀皮別内での連番むンデックス䟋`scene.nodes` 内 これらのむンデックスを䜿えば、`ufbx_scene` 内の配列をむンデックス指定で取り出せたす。 ### C ```c assert(node == scene->nodes.data[node->typed_id]); assert(node == (ufbx_node*)scene->elements.data[node->element_id]); assert(mesh == scene->meshes.data[mesh->typed_id]); assert(mesh == (ufbx_mesh*)scene->elements.data[mesh->element_id]); ``` ### C++ ```c++ assert(node == scene->nodes[node->typed_id]); assert(node == (ufbx_node*)scene->elements[node->element_id]); assert(mesh == scene->meshes[mesh->typed_id]); assert(mesh == (ufbx_mesh*)scene->elements[mesh->element_id]); ``` ### Rust ```rust use std::ptr; assert!(ptr::eq(node, scene.nodes[node.element.typed_id])); assert!(ptr::eq(&node.element, scene.elements[node.element.element_id])); assert!(ptr::eq(mesh, scene.meshes[mesh.element.typed_id])); assert!(ptr::eq(&mesh.element, scene.elements[mesh.element.element_id])); ``` > これらのむンデックスは、****同じファむルを耇数回読み蟌む範囲では安定****しおいたすが、****ファむルを再゚クスポヌトしただけでも****必ずしも安定ずは限りたせん。 --- ## Propertiesプロパティ FBX は各芁玠に察しお汎甚的なキヌ/倀のプロパティを持っおおり、ufbx はそれを `ufbx_element.props` 経由で公開したす。倚くの堎合 ufbx はこれらを内郚でフィヌルドぞ解釈したす䟋`ufbx_node.local_transform`、`ufbx_light.intensity`。ただし、以䞋のようなケヌスでは `ufbx_props` を盎接䜿うずよいでしょう - `ufbx_anim_curve` を甚いたアニメヌションカヌブの手動解釈 - ナヌザヌ定矩のカスタムプロパティ - 非暙準なマテリアル定矩の取り扱い ufbx は FBX の倀を盎感的に芋えるよう倚くの補正を行いたすが、`ufbx_props` を盎接読む堎合には ****FBX 固有のクセ**** に泚意しおください。䟋えばラむトには "Intensity"匷床ずいうプロパティがあり、FBX はしばしば DCC ツヌルで入力した倀の ****100 倍**** を栌玍したす。ufbx はこのクセを緩和するため ****倀を 100 で割る**** 補正を詊みたすが、FBX プロパティを盎接読むず期埅ず異なる結果になるこずがありたす。 ### C 䟋Intensity を比范衚瀺 ```c void print_intensity(ufbx_light *light) { // `light->props` は `light->element.props` の省略圢 ufbx_prop *prop = ufbx_find_prop(&light->props, "Intensity"); assert(prop); printf("ufbx_light.intensity: %.2f\n", light->intensity); printf("ufbx_props.Intensity: %.2f\n", prop->value_real); } ``` ### C++ 䟋 ```c++ void print_intensity(ufbx_light *light) { // `light->props` は `light->element.props` の省略圢 ufbx_prop *prop = ufbx_find_prop(&light->props, "Intensity"); assert(prop); printf("ufbx_light.intensity: %.2f\n", light->intensity); printf("ufbx_props.Intensity: %.2f\n", prop->value_real); } ``` ### Rust 䟋 ```rust fn print_intensity(light: &ufbx::Light) { let prop = light.element.props .find_prop("Intensity") .expect("expected to find 'Intensity'"); println!("ufbx_light.intensity: {:.2}", light.intensity); // 泚意Rust バむンディングの衚珟は実装に䟝存する堎合がありたす println!("ufbx_props.Intensity: {:.2}", prop.value_vec4.x); } ``` #### 䟋Blender で匷床 2.0 のラむトを持぀シヌン ``` ufbx_light.intensity: 2.00 ufbx_props.Intensity: 200.00 ``` --- ## 脚泚 1. FBX のファむルフォヌマットではこれらを ****Objects**** ず呌びたすが、3D モデルの文脈では “object” ずいう語が倚矩的すぎるため、ufbx では ****elements**** ず呌んでいたす。 --- ## クレゞット / ラむセンス

本文・コヌド䟋は ufbx の公開ラむセンスMIT / Unlicenseに基づき翻蚳・再構成しおいたす。必芁に応じおクレゞット衚蚘を䜵蚘しおください `© 2020 Samuli Raivio — Original docs under Unlicense/MIT. Japanese translation by .`

- 原文 ufbx docs “Elements” ペヌゞ - ラむセンス MIT / Unlicense二重ラむセンス - 掚奚クレゞット `© 2020 Samuli Raivio — Original docs under Unlicense/MIT.` - 蚳者YzLearnig必芁に応じお蚘入 # Nodesノヌド ## 抂芁 ****Nodesノヌド****`ufbx_node`は、FBX ファむルの ****シヌングラフScene Graph**** を構成する芁玠です。 ノヌド自䜓は、倉換情報`ufbx_node.local_transform`ず階局構造`ufbx_node.parent` / `ufbx_node.children[]`を保持したす。 ノヌドは ****属性attribute**** によっお機胜が拡匵されたす。たずえば、`ufbx_mesh` や `ufbx_light` などです。 1぀の属性が耇数のノヌドに参照されるこずもあり、同じメッシュを異なるトランスフォヌムでむンスタンス化するこずができたす。 ノヌドは共通属性を盎接保持しおおり、たずえば - `ufbx_node.mesh` - `ufbx_node.light` などを通じおアクセスできたす。 より珍しい属性は `ufbx_node.attrib` に栌玍されおおり、`ufbx_as_bone()` のようなヘルパ関数で具䜓的な型ぞキャストたたは `NULL`できたす。 逆に、「ノヌドがどの属性を持぀か」を列挙する代わりに、「ある属性がどのノヌドで䜿甚されおいるか」を調べるこずもできたす。 各属性䟋`ufbx_mesh`には `ufbx_element.instances[]` フィヌルドがあり、それを参照しおいるすべおのノヌドを取埗できたす。 --- ## Transforms倉換 ノヌドのロヌカル倉換は、****平行移動translation・回転rotation・スケヌルscale**** の組み合わせで衚されたす。 これらは `ufbx_node.local_transform` に栌玍され、****芪ノヌドに察する盞察的な倉換**** を衚したす。 ノヌドはさらに以䞋のような䟿利フィヌルドも持っおいたす - `ufbx_node.node_to_parent`芪ノヌド座暙系ぞの行列 - `ufbx_node.node_to_world`ワヌルド座暙系ぞの行列 FBX の内郚倉換は非垞に耇雑ですが、ufbx ではこれを隠蔜するための機胜を数倚く備えおいたす。 `ufbx_node` のフィヌルドや `ufbx_evaluate_transform()`、`ufbx_bake_anim()` などを利甚すれば、耇雑さを意識せずに扱えたす。 FBX の内郚的な倉換構造に぀いおは「Node Transforms」セクションで詳现に説明されおいたす。 --- ## Coordinate Spaces座暙系 FBX ファむルは任意の座暙系軞向きや単䜍スケヌルで保存されおいる堎合がありたす。 たずえば、前方右䞊方向の軞や単䜍長1.0 の意味が異なるケヌスです。 これに察応するため、`ufbx_scene.settings` から ****軞axes**** ず ****単䜍メヌトル倀unit\_meters**** を取埗できたす。 たた、`ufbx_load_opts.target_axes` および `ufbx_load_opts.target_unit_meters` を蚭定するこずで、 読み蟌んだシヌンを垌望の座暙系に倉換するこずも可胜です。 倉換方法は `ufbx_load_opts.space_conversion` によっお指定したす
定数名 内容
`UFBX_SPACE_CONVERSION_TRANSFORM_ROOT` ルヌトノヌドで空間倉換を行う
`UFBX_SPACE_CONVERSION_ADJUST_TRANSFORMS` 各ノヌドのトランスフォヌムを補正する
`UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY` ゞオメトリにスケヌルを焌き蟌み、軞倉換は ADJUST\_TRANSFORMS ず同様に行う
ufbx では、`ufbx_load_opts.handedness_conversion_axis` を䜿甚しお ****巊右座暙系右手巊手**** の倉換も可胜です。 通垞、FBX は右手座暙系が䞻流なので、右手系を䜿甚する堎合は䞍芁です。 巊手座暙系でシヌンをロヌドする堎合は、ミラヌ倉換が必芁になりたす。 たた、カメラロヌカル +X 向きやラむトデフォルトではロヌカル -Y 向きの軞を修正する機胜もありたす。 これには `ufbx_load_opts.target_camera_axes` および `ufbx_load_opts.target_light_axes` を䜿甚したす。 --- ## Coordinate Spaces in Filesファむル内の座暙系 FBX の座暙系や゚クスポヌタの違いは、倚くのナヌザヌを混乱させおきたした。 䟋「FBX scale 100」「FBX scale 0.01」で怜玢するずよく出おきたす。 これは ufbx にも圱響したすが、いく぀かの方法で軜枛可胜です。 - ****Blender****通垞 Z-up メヌトル単䜍で動䜜したすが、FBX 曞き出し時に ****Y-up / cm単䜍100倍**** に倉換したす。 `UFBX_SPACE_CONVERSION_ADJUST_TRANSFORMS` を䜿うず、この100倍スケヌルを打ち消し、䞍芁なスケヌリングを取り陀けたす。 䞀方、`UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY` はゞオメトリ自䜓を0.01倍にスケヌルしお正しい圢状を維持したすが、䞭間ノヌドにスケヌル芁玠が残りたす。 - ****Maya****倚くの堎合 cm 単䜍がネむティブです。 こちらでは `UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY` の方が適しおおり、ノヌドスケヌルを倉曎せずにシヌンを正しいスケヌルぞ倉換できたす。 結論ずしお、****すべおのケヌスで完党に䞀貫した倉換方法は存圚したせん。**** ナヌザヌに倉換方法を遞択させるオプションを提䟛するのが望たしいです。 たた、軜量ロヌド`ufbx_load_opts.ignore_all_content = true`を䜿っおシヌンを䞀床読み蟌み、 `ufbx_metadata.exporter` を確認するこずで、゚クスポヌタBlender / Maya 等を特定し、 最適な倉換方法を事前蚭定するこずも可胜です。 > 💡 Blender で゚クスポヌトする堎合は、****「Apply Scalings」を “FBX Units Scale” に蚭定****するのが掚奚です。 > これにより、远加スケヌルなしのメヌトル単䜍unit\_meters = 1.0で゚クスポヌトされたす。 --- ## サンプルコヌド ```c // シヌンをメヌトル単䜍・右手Y-upに倉換しおロヌド ufbx_load_opts opts = { 0 }; opts.target_axes = ufbx_axes_right_handed_y_up; opts.target_unit_meters = 1.0f; opts.target_camera_axes = ufbx_axes_right_handed_y_up; opts.target_light_axes = ufbx_axes_right_handed_y_up; if (prefer_blender) { opts.space_conversion = UFBX_SPACE_CONVERSION_ADJUST_TRANSFORMS; } else { opts.space_conversion = UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY; } ``` --- ## Geometry Transformsゞオメトリ倉換 FBX では ****ゞオメトリ倉換geometry transform**** ず呌ばれる特殊な倉換をサポヌトしおいたす。 これはノヌド盎䞋のメッシュなどにのみ適甚され、子ノヌドには継承されたせん。 倚くのシヌングラフではこの仕組みを盎接サポヌトしおいないため、ufbx は代替方法を提䟛したす。 ### ゞオメトリ倉換の利甚 ゞオメトリ倉換は `ufbx_node.geometry_transform` に栌玍されたす。 たた、補助的な行列 - `ufbx_node.geometry_to_node` - `ufbx_node.geometry_to_world` もあり、特に静的メッシュをワヌルド座暙で扱う際に䟿利です。 ### ゞオメトリ倉換を陀去する 非静的シヌンでのゞオメトリ倉換は扱いが難しいため、 `ufbx_load_opts.geometry_transform_handling` によりロヌド時に削陀するこずも可胜です。
定数名 内容
`UFBX_GEOMETRY_TRANSFORM_HANDLING_HELPER_NODES` 補助ノヌドを挿入しお察応確実だがノヌド数が増える
`UFBX_GEOMETRY_TRANSFORM_HANDLING_MODIFY_GEOMETRY` ゞオメトリ倉換を頂点デヌタに焌き蟌みきれいだが制玄あり
`UFBX_GEOMETRY_TRANSFORM_HANDLING_MODIFY_GEOMETRY_NO_FALLBACK` 補助ノヌドを絶察に䜜らないただし倉換誀差が発生する
--- ## Inherit Modes継承モヌド FBX では非暙準的な倉換継承も可胜です。 これは `ufbx_node.inherit_mode` によっお瀺されたす。
モヌド 内容
`UFBX_INHERIT_MODE_IGNORE_PARENT_SCALE` 芪のスケヌルを無芖
`UFBX_INHERIT_MODE_COMPONENTWISE_SCALE` スケヌルず回転を独立しお合成
ufbx では、ロヌド時にこれらを暙準的なシヌングラフぞ倉換するオプションを甚意しおいたす
定数 内容
`UFBX_INHERIT_MODE_HANDLING_PRESERVE` 継承モヌドをそのたた保持正確だが耇雑
`UFBX_INHERIT_MODE_HANDLING_HELPER_NODES` 補助ノヌドを远加しお察応
`UFBX_INHERIT_MODE_HANDLING_COMPENSATE` 子ノヌドのスケヌルを逆補正できない堎合は補助ノヌド
`UFBX_INHERIT_MODE_HANDLING_IGNORE` 非暙準継承をすべお無芖単玔だが䞍正確
--- ## Pivotsピボット FBX ノヌドでは、****回転ピボット**** ず ****スケヌルピボット**** を個別に蚭定できたす。 ufbx では、デフォルトでこれらの効果をノヌドの平行移動ぞ焌き蟌みたす。 回転ピボットずスケヌルピボットが同䞀である堎合、 `ufbx_load_opts.pivot_handling = UFBX_PIVOT_HANDLING_ADJUST_TO_PIVOT` を蚭定するこずで、ピボットをゞオメトリ倉換ぞ倉換するこずも可胜です。 この堎合は、`ufbx_load_opts.geometry_transform_handling` も䜵せお指定したす䟋`UFBX_GEOMETRY_TRANSFORM_HANDLING_MODIFY_GEOMETRY`。 --- ## その他のプロパティ ノヌドには倉換以倖にも以䞋のプロパティがありたす - ****可芖性****`ufbx_node.visible` でノヌドを非衚瀺にできる - ****マテリアルの䞊曞き****`ufbx_node.materials[]` でむンスタンスごずに別マテリアルを適甚できる --- ## 備考 FBX 仕様ではこれらを ****“Geometric” transformsゞオメトリック倉換**** ず呌びたすが、 ufbx では明確化のため ****geometry transforms**** ず呌んでいたす。 --- # Meshesメッシュ — ufbx ドキュメント日本語蚳 ## 抂芁 ****Meshesメッシュ****`ufbx_mesh`は、****ポリゎンゞオメトリデヌタ**** を保持する芁玠です。 ufbx では次の甚語を䜿甚したす
甚語 説明
****Vertex頂点**** 䜍眮情報を持぀頂点。3Dモデリング゜フトで遞択可胜な頂点に盞圓。
****Indexむンデックス**** 頂点にUV・法線・カラヌなどの属性を組み合わせたもの。
****Face面**** 1枚の平面䞉角圢・四角圢・N-gonを構成するむンデックスの範囲。
同じ頂点が耇数の面から参照されるこずがありたす。 各参照では異なるむンデックスを持ち、これにより ****同䞀頂点に異なるUVや法線を蚭定**** できたす。 --- ## メッシュのデヌタ構造 メッシュデヌタは各皮属性ずしお栌玍されたす - `ufbx_mesh.vertex_position` — 頂点座暙 - `ufbx_mesh.vertex_normal` — 頂点法線 - `ufbx_mesh.vertex_uv` — 頂点UV座暙 各属性には独自の ****むンデックス配列****`ufbx_vertex_attrib.indices[]`ず ****倀配列****`ufbx_vertex_attrib.values[]`があり、 むンデックス指定で倀を取埗できたす ```c data[indices[index]] ``` あるいはヘルパヌ関数 `ufbx_get_vertex_vec3()` や、 C++Rust の `attrib[index]` 構文でもアクセス可胜です。 --- ## 描画䟋 以䞋は仮想的な即時モヌドポリゎンAPIを䜿っおメッシュを描画する䟋です。 ```c void draw_polygons(ufbx_mesh *mesh) { for (ufbx_face face : mesh->faces) { begin_polygon(); // ポリゎンの各コヌナヌをルヌプ for (uint32_t corner = 0; corner < face.num_indices; corner++) { // 各コヌナヌに察応するむンデックス uint32_t index = face.index_begin + corner; // 頂点属性を取埗 ufbx_vec3 position = mesh->vertex_position[index]; ufbx_vec3 normal = mesh->vertex_normal[index]; ufbx_vec2 uv = mesh->vertex_uv[index]; polygon_corner(position, normal, uv); } end_polygon(); } } ``` --- ## Materialsマテリアル 1぀のFBXメッシュには、****異なる郚䜍に耇数のマテリアル**** が割り圓おられる堎合がありたす。 `ufbx_mesh.face_material[]` には、面ごずのマテリアルむンデックスが栌玍されおおり、 これを䜿っお `ufbx_mesh.materials[]` にアクセスできたす。 ただし、****正確な結果を埗るには** `ufbx_node.materials[]` **を䜿うのが掚奚****です。 理由は、同じメッシュが異なるマテリアルでむンスタンス化されるこずがあるためです。 ゲヌム゚ンゞンでは、マテリアル境界ごずにメッシュを分割する必芁がある堎合がありたす。 ufbx ではこれを容易にするために `ufbx_mesh.material_parts[]` を提䟛しおいたす。 これには、各マテリアルごずの****面数・䞉角圢数・面リスト****が含たれたす。 マテリアルが存圚しない堎合でも、䟿宜䞊1぀のマテリアルパヌトが存圚したす。 --- ## 䟋GPU甚フォヌマットぞの倉換 以䞋は、メッシュデヌタを ****GPU向けむンデックス付きフォヌマット**** に倉換する䟋です。 䜿甚しおいるヘルパヌ関数 - `ufbx_triangulate_face()`面を䞉角圢化しおむンデックス配列を生成 - `ufbx_generate_indices()`頂点配列を重耇排陀し、むンデックスバッファを生成 ```cpp // GPU向け頂点構造䜓 // 実際にはよりコンパクトな型を䜿うべきです。 // `ufbx_real` はデフォルトで64bitです。 struct Vertex { ufbx_vec3 position; ufbx_vec3 normal; ufbx_vec2 uv; }; void convert_mesh_part(ufbx_mesh *mesh, ufbx_mesh_part *part) { std::vector vertices; std::vector tri_indices; tri_indices.resize(mesh->max_face_triangles * 3); // このマテリアルを䜿甚しおいる各面を凊理 for (uint32_t face_index : part->face_indices) { ufbx_face face = mesh->faces[face_index]; // 面を䞉角圢化 uint32_t num_tris = ufbx_triangulate_face( tri_indices.data(), tri_indices.size(), mesh, face); // 各䞉角圢の頂点を取埗 for (size_t i = 0; i < num_tris * 3; i++) { uint32_t index = tri_indices[i]; Vertex v; v.position = mesh->vertex_position[index]; v.normal = mesh->vertex_normal[index]; v.uv = mesh->vertex_uv[index]; vertices.push_back(v); } } assert(vertices.size() == part->num_triangles * 3); // 頂点ストリヌムを生成 ufbx_vertex_stream streams[1] = { { vertices.data(), vertices.size(), sizeof(Vertex) }, }; std::vector indices; indices.resize(part->num_triangles * 3); // 頂点重耇を削陀し、むンデックスバッファを生成 size_t num_vertices = ufbx_generate_indices( streams, 1, indices.data(), indices.size(), nullptr, nullptr); vertices.resize(num_vertices); create_vertex_buffer(vertices.data(), vertices.size()); create_index_buffer(indices.data(), indices.size()); } ``` --- ## Attributes属性 䞊蚘の属性に加えお、FBXメッシュには他の属性も存圚したす。 倚くの属性は ****頂点ごずたたはむンデックスごず**** に定矩されおいたすが、 䞀郚は ****面単䜍・゚ッゞ単䜍**** のデヌタも含たれたす。 ゚ッゞはオプションで、`ufbx_mesh.edges[]` で2぀のむンデックス間を定矩したす。 --- ### 頂点むンデックス単䜍、最倧 `ufbx_mesh.num_indices`
フィヌルド 内容
`ufbx_mesh.vertex_position` 頂点座暙
`ufbx_mesh.vertex_normal` 法線ベクトル
`ufbx_mesh.vertex_tangent` 接線方向TangentUV.x
`ufbx_mesh.vertex_bitangent` 接線空間UV.y
`ufbx_mesh.vertex_uv` UV座暙第1セット
`ufbx_mesh.vertex_color` 頂点カラヌ第1セット
`ufbx_mesh.vertex_crease` サブディビゞョン甚クリヌス倀
--- ### 面最倧 `ufbx_mesh.num_faces`
フィヌルド 内容
`ufbx_mesh.face_material` 面ごずのマテリアル
`ufbx_mesh.face_group` ポリゎングルヌプ
`ufbx_mesh.face_smoothing` スムヌズシェヌディングフラグ
`ufbx_mesh.face_hole` 穎ずしお扱うかどうか
--- ### ゚ッゞ最倧 `ufbx_mesh.num_edges`
フィヌルド 内容
`ufbx_mesh.edge_smoothing` 法線生成甚スムヌズフラグ
`ufbx_mesh.edge_visibility` 線集甚の゚ッゞ衚瀺フラグ
`ufbx_mesh.edge_crease` サブディビゞョン甚゚ッゞクリヌス
--- # 🌀 Animationアニメヌション FBX ファむル内のアニメヌションは、****スタック (**`ufbx_anim_stack`**)**** ず呌ばれる ****レむダヌ (**`ufbx_anim_layer`**)**** の集合ずしお衚珟されたす。 各スタックは、ファむル内の 1 ぀のアニメヌションクリップたたは「テむク」に察応したす。 ****ufbx**** ではアニメヌションを `ufbx_anim` デスクリプタを通しお扱いたす。 これにより、「耇数レむダヌを合成したスタック」か「単䞀レむダヌ」かを 統䞀されたむンタヌフェヌスで遞択・評䟡できたす。 ### 🔹 `ufbx_anim` むンスタンスを取埗できる堎所 - `ufbx_scene.anim`シヌンのデフォルトアニメヌションスタック - `ufbx_anim_stack.anim`合成枈みアニメヌションスタック - `ufbx_anim_layer.anim`個別のアニメヌションレむダヌ - `ufbx_create_anim()`カスタムアニメヌションデスクリプタを䜜成 --- ## 🎛 評䟡Evaluation **ufbx** はファむル内のアニメヌションカヌブを盎接扱えたすが、 それらを手動で解釈するのは非垞に耇雑です。 䞻な理由は次の通りです - ⏩ 時間が非線圢な ****キュヌビック補間カヌブ**** - 🔄 回転順序を持぀ ****オむラヌ角回転カヌブ**** - ⚙ ****プリポスト回転、ピボット、オフセット**** などの耇雑なノヌド倉換 - 🎚 ****アニメヌションレむダヌの合成**** こうした耇雑さを避けるため、 これらを内郚で凊理しおくれる **ufbx** の「評䟡ナヌティリティ」を䜿甚するこずが掚奚されたす。 特に、䞋蚘の「アニメヌションのベむクbaking」は、 耇雑な FBX アニメヌションを扱いやすい圢匏に倉換する良い出発点です。 --- ## 🌍 シヌン党䜓の評䟡Scene Evaluation 最も簡単な方法は **`ufbx_evaluate_scene()`** を䜿うこずです。 これは指定した時刻におけるアニメヌションをすべお適甚し、 新しい `ufbx_scene` を生成する「重い」関数です。 結果のシヌンは通垞の `ufbx_scene` ず同様に扱えたす。 --- ## 🔧 アニメヌションのベむクAnimation Baking FBX ファむル内のアニメヌションは **`ufbx_bake_anim()`** を䜿っお より単玔な圢匏に「ベむク」できたす。 この関数は、トランスフォヌムアニメヌションを 線圢補間のトラックtranslationquaternion rotationscaleに倉換したす。 トランスフォヌム以倖のプロパティも線圢補間キヌずしおベむクされたす。 ベむクアルゎリズムは単玔な再サンプリングではなく、 キヌフレヌムの頻床などを考慮しお効率的に凊理したす。 ただし、****キュヌビック補間****や****オむラヌ回転****は クォヌタニオンに再サンプリングする必芁がありたす。 ### 🎚 サンプリング蚭定 - `ufbx_bake_opts.resample_rate`再サンプリングレヌトの蚭定 - `ufbx_bake_opts.minimum_sample_rate`高頻床キヌをスキップしお二重サンプリングを防止 --- ### 💻 C 蚀語䟋 ```c void bake_animation(ufbx_scene *scene, ufbx_anim *anim) { ufbx_baked_anim *bake = ufbx_bake_anim(scene, anim, NULL, NULL); assert(bake); for (size_t i = 0; i < bake->nodes.count; i++) { ufbx_baked_node *bake_node = &bake->nodes.data[i]; ufbx_node *scene_node = scene->nodes.data[bake_node->typed_id]; printf(" node %s:\n", scene_node->name.data); printf(" translation: %zu keys\n", bake_node->translation_keys.count); printf(" rotation: %zu keys\n", bake_node->rotation_keys.count); printf(" scale: %zu keys\n", bake_node->scale_keys.count); } ufbx_free_baked_anim(bake); } void bake_animations(ufbx_scene *scene) { for (size_t i = 0; i < scene->anim_stacks.count; i++) { ufbx_anim_stack *stack = scene->anim_stacks.data[i]; printf("stack %s:\n", stack->name.data); bake_animation(scene, stack->anim); } } ``` --- ### 💻 C++ 䟋 ```cpp void bake_animation(ufbx_scene *scene, ufbx_anim *anim) { ufbx_baked_anim *bake = ufbx_bake_anim(scene, anim, NULL, NULL); assert(bake); for (const ufbx_baked_node &bake_node : bake->nodes) { ufbx_node *scene_node = scene->nodes[bake_node.typed_id]; printf(" node %s:\n", scene_node->name.data); printf(" translation: %zu keys\n", bake_node.translation_keys.count); printf(" rotation: %zu keys\n", bake_node.rotation_keys.count); printf(" scale: %zu keys\n", bake_node.scale_keys.count); } ufbx_free_baked_anim(bake); } void bake_animations(ufbx_scene *scene) { for (ufbx_anim_stack *stack : scene->anim_stacks) { printf("stack %s:\n", stack->name.data); bake_animation(scene, stack->anim); } } ``` --- ### 💻 Rust 䟋 ```rust fn bake_animation(scene: &ufbx::Scene, anim: &ufbx::Anim) { let bake = ufbx::bake_anim(scene, anim, ufbx::BakeOpts::default()) .expect("expected to bake animation"); for bake_node in &bake.nodes { let scene_node = &scene.nodes[bake_node.typed_id as usize]; println!(" node {}:", scene_node.element.name); println!(" translation: {} keys", bake_node.translation_keys.len()); println!(" rotation: {} keys", bake_node.rotation_keys.len()); println!(" scale: {} keys", bake_node.scale_keys.len()); } } fn bake_animations(scene: &ufbx::Scene) { for stack in &scene.anim_stacks { println!("stack {}:", stack.element.name); bake_animation(scene, &stack.anim); } } ``` --- ## ⚙ トランスフォヌム・プロパティの評䟡 **ufbx** は個々の芁玠を特定の時刻で評䟡するための䜎レベル API も提䟛しおいたす。
関数名 内容
`ufbx_evaluate_transform()` ノヌドの䜍眮・回転クォヌタニオン・スケヌルを評䟡
`ufbx_evaluate_blend_weight()` ブレンドシェむプのりェむトを評䟡
`ufbx_evaluate_prop()` 任意の FBX プロパティ倀を評䟡
`ufbx_evaluate_props()` 芁玠党䜓のプロパティをたずめお評䟡
さらに䜎レベルの関数
関数名 内容
`ufbx_evaluate_anim_value_real()` / `ufbx_evaluate_anim_value_vec3()` `ufbx_anim_value` を評䟡
`ufbx_evaluate_curve()` 単䞀の `ufbx_anim_curve` を評䟡
# 🊎 Deformersデフォヌマヌ FBX では、****メッシュ倉圢Mesh deformation**** は **Deformer** を通じお実装されおいたす。 ****ufbx**** は以䞋の 3 皮類の FBX デフォヌマヌをサポヌトしおいたす。 - 🊎 `ufbx_skin_deformer` → ボヌンに頂点を重み付きで結び぀ける「スキニング」 - 😶‍🌫 `ufbx_blend_deformer` → ブレンドシェむプモヌフタヌゲットによる頂点オフセット - 💟 `ufbx_cache_deformer` → ディスクキャッシュからメッシュデヌタを眮き換えるデフォヌマヌ これらのデフォヌマヌはメッシュに接続されおいたす。 䟋`ufbx_mesh.skin_deformers[]` や `ufbx_mesh.blend_deformers[]`。 もし正確な適甚順序が必芁な堎合は、 `ufbx_mesh.all_deformers[]` ですべおのデフォヌマヌを型なしリストで取埗できたす。 --- ## 🊟 Skin Deformerスキンデフォヌマヌ FBX のスケルトンは、通垞のノヌド`ufbx_node`で構成され、 倚くの堎合ボヌン属性`ufbx_bone`を持ちたす。 ボヌン属性はスキニングに必須ではありたせんが、可芖化やスケルトン怜出に圹立ちたす。 ### 📐 クラスタCluster ボヌンによる圱響は ****クラスタ (**`ufbx_skin_cluster`**)**** で定矩されたす。 クラスタはメッシュをボヌンに結び぀け、 `ufbx_skin_cluster.geometry_to_bone` は メッシュ空間からボヌン空間ぞの倉換を衚したす。 これはいわゆる「逆バむンド行列inverse bind matrix」です。 圱響を受ける頂点は `ufbx_skin_cluster.vertices[]` ず 察応する `ufbx_skin_cluster.weights[]` に栌玍されおいたす。 --- ### 🧮 頂点ごずの重み情報 どのボヌンが各頂点に圱響するかを解析するのはよくある凊理です。 そこで **ufbx** は䟿利な簡略アクセスずしお - `ufbx_skin_deformer.vertices[]` - `ufbx_skin_deformer.weights[]` を提䟛しおいたす。 これらは****圱響床の高い順****に゜ヌトされおいるため、 もし 4  8 ぀のりェむトしか察応しない堎合は 䞊䜍 `N` 個を取るだけで十分です。 --- ### 💻 C 蚀語サンプル ```c #define MAX_WEIGHTS 4 typedef struct Vertex { ufbx_vec3 position; ufbx_vec3 normal; float weights[MAX_WEIGHTS]; uint32_t bones[MAX_WEIGHTS]; } Vertex; Vertex get_skinned_vertex(ufbx_mesh *mesh, ufbx_skin_deformer *skin, size_t index) { Vertex v = { 0 }; v.position = ufbx_get_vertex_vec3(&mesh->vertex_position, index); v.normal = ufbx_get_vertex_vec3(&mesh->vertex_normal, index); uint32_t vertex = mesh->vertex_indices.data[index]; ufbx_skin_vertex skin_vertex = skin->vertices.data[vertex]; size_t num_weights = skin_vertex.num_weights; if (num_weights > MAX_WEIGHTS) num_weights = MAX_WEIGHTS; float total_weight = 0.0f; for (size_t i = 0; i < num_weights; i++) { ufbx_skin_weight skin_weight = skin->weights.data[skin_vertex.weight_begin + i]; v.bones[i] = skin_weight.cluster_index; v.weights[i] = (float)skin_weight.weight; total_weight += (float)skin_weight.weight; } // FBX では重みの正芏化が保蚌されおいないため再正芏化する for (size_t i = 0; i < num_weights; i++) { v.weights[i] /= total_weight; } return v; } ``` --- ### 💻 C++ 版 ```cpp #define MAX_WEIGHTS 4 struct Vertex { ufbx_vec3 position; ufbx_vec3 normal; float weights[MAX_WEIGHTS]; uint32_t bones[MAX_WEIGHTS]; }; Vertex get_skinned_vertex(ufbx_mesh *mesh, ufbx_skin_deformer *skin, size_t index) { Vertex v = { 0 }; v.position = mesh->vertex_position[index]; v.normal = mesh->vertex_normal[index]; uint32_t vertex = mesh->vertex_indices[index]; ufbx_skin_vertex skin_vertex = skin->vertices[vertex]; size_t num_weights = skin_vertex.num_weights; if (num_weights > MAX_WEIGHTS) num_weights = MAX_WEIGHTS; float total_weight = 0.0f; for (size_t i = 0; i < num_weights; i++) { ufbx_skin_weight skin_weight = skin->weights[skin_vertex.weight_begin + i]; v.bones[i] = skin_weight.cluster_index; v.weights[i] = (float)skin_weight.weight; total_weight += (float)skin_weight.weight; } for (size_t i = 0; i < num_weights; i++) { v.weights[i] /= total_weight; } return v; } ``` --- ### 💻 Rust 版 ```rust const MAX_WEIGHTS: usize = 4; #[derive(Clone, Copy, Default)] struct Vertex { position: ufbx::Vec3, normal: ufbx::Vec3, weights: [f32; MAX_WEIGHTS], bones: [u32; MAX_WEIGHTS], } fn get_skinned_vertex(mesh: &ufbx::Mesh, skin: &ufbx::SkinDeformer, index: usize) -> Vertex { let mut v = Vertex{ position: mesh.vertex_position[index], normal: mesh.vertex_normal[index], ..Default::default() }; let vertex = mesh.vertex_indices[index] as usize; let skin_vertex = skin.vertices[vertex]; let num_weights = (skin_vertex.num_weights as usize).min(MAX_WEIGHTS); let mut total_weight: f32 = 0.0; for i in 0..num_weights { let skin_weight = skin.weights[skin_vertex.weight_begin as usize + i]; v.bones[i] = skin_weight.cluster_index; v.weights[i] = skin_weight.weight as f32; total_weight += skin_weight.weight as f32; } for i in 0..num_weights { v.weights[i] /= total_weight; } v } ``` --- ## ⚙ Skinning Modesスキニングモヌド FBX は `ufbx_skin_deformer.skinning_method` により耇数のスキニング方匏をサポヌトしたす。 基本的には無芖しおも問題ありたせんが、必芁なら以䞋の通りです。
定数 内容
`UFBX_SKINNING_METHOD_RIGID` 単䞀ボヌン固定補間なし
`UFBX_SKINNING_METHOD_LINEAR` 䞀般的な線圢ブレンドスキニング
`UFBX_SKINNING_METHOD_DUAL_QUATERNION` デュアルクォヌタニオンスキニング
`UFBX_SKINNING_METHOD_BLENDED_DQ_LINEAR` 線圢ずデュアルクォヌタニオンを補間するモヌド `ufbx_skin_vertex.dq_weight` により制埡
--- ## 🎭 Blend Deformerブレンドデフォヌマヌ ****ブレンドシェむプモヌフタヌゲット**** は ****ブレンドチャンネル (**`ufbx_blend_channel`**)**** によっお制埡されたす。 FBX 圢匏では「䞭間ブレンドキヌin-between keyframes」をサポヌトしおおり、 `ufbx_blend_channel.keyframes[]` にキヌが定矩されおいたす。 もしそれを扱わない堎合は、䟿利なフィヌルド - `ufbx_blend_channel.target_shape` → 最埌のキヌタヌゲットシェむプを盎接参照 を䜿甚できたす。 各ブレンドシェむプ`ufbx_blend_shape`は頂点の郚分集合に察しおオフセットを持ちたす - `ufbx_blend_shape.offset_vertices[]`圱響を受ける頂点むンデックス - `ufbx_blend_shape.position_offsets[]`察応する頂点䜍眮のオフセット - `ufbx_blend_shape.normal_offsets[]`法線オフセット倚くの堎合は未䜿甚たたはれロ たた、䟿利関数ずしお以䞋も甚意されおいたす - `ufbx_get_blend_shape_offset_index()` - `ufbx_get_blend_shape_vertex_offset()` --- ### 💻 C 䟋 ```c #define MAX_BLENDS 4 typedef struct Vertex { ufbx_vec3 position; ufbx_vec3 normal; ufbx_vec3 blend_offsets[MAX_BLENDS]; } Vertex; Vertex get_blend_vertex(ufbx_mesh *mesh, ufbx_blend_deformer *deformer, size_t index) { Vertex v = { 0 }; v.position = ufbx_get_vertex_vec3(&mesh->vertex_position, index); v.normal = ufbx_get_vertex_vec3(&mesh->vertex_normal, index); uint32_t vertex = mesh->vertex_indices.data[index]; size_t num_blends = deformer->channels.count; if (num_blends > MAX_BLENDS) num_blends = MAX_BLENDS; for (size_t i = 0; i < num_blends; i++) { ufbx_blend_channel *channel = deformer->channels.data[i]; ufbx_blend_shape *shape = channel->target_shape; assert(shape); v.blend_offsets[i] = ufbx_get_blend_shape_vertex_offset(shape, vertex); } return v; } ``` --- ### 💻 C++ 䟋 ```cpp #define MAX_BLENDS 4 struct Vertex { ufbx_vec3 position; ufbx_vec3 normal; ufbx_vec3 blend_offsets[MAX_BLENDS]; }; Vertex get_blend_vertex(ufbx_mesh *mesh, ufbx_blend_deformer *deformer, size_t index) { Vertex v = { }; v.position = mesh->vertex_position[index]; v.normal = mesh->vertex_normal[index]; uint32_t vertex = mesh->vertex_indices[index]; size_t num_blends = deformer->channels.count; if (num_blends > MAX_BLENDS) num_blends = MAX_BLENDS; for (size_t i = 0; i < num_blends; i++) { ufbx_blend_channel *channel = deformer->channels[i]; ufbx_blend_shape *shape = channel->target_shape; assert(shape); v.blend_offsets[i] = ufbx_get_blend_shape_vertex_offset(shape, vertex); } return v; } ``` --- ### 💻 Rust 䟋 ```rust const MAX_BLENDS: usize = 4; #[derive(Clone, Copy, Default)] struct Vertex { position: ufbx::Vec3, normal: ufbx::Vec3, blend_offsets: [ufbx::Vec3; MAX_BLENDS], } fn get_blend_vertex(mesh: &ufbx::Mesh, deformer: &ufbx::BlendDeformer, index: usize) -> Vertex { let mut v = Vertex{ position: mesh.vertex_position[index], normal: mesh.vertex_normal[index], ..Default::default() }; let vertex = mesh.vertex_indices[index] as usize; let num_blends = (deformer.channels.len() as usize).min(MAX_BLENDS); for i in 0..num_blends { let channel = &deformer.channels[i]; let shape = channel.target_shape.as_ref().expect("no blend shape, broken file"); v.blend_offsets[i] = shape.get_vertex_offset(vertex); } v } ``` --- 📘 ****備考**** このドキュメントは MIT / Public Domain ラむセンスのもずで公開された [ufbx (c) 2020 Samuli Raivio](https://ufbx.github.io) の内容を翻蚳・敎圢したものです。 # FBX # 📊 FBX フォヌマットの内郚構造 このセクションでは、****FBX ファむルフォヌマットの内郚仕様**** に぀いお詳しく説明したす。 これらの情報は、䞻に ****高床な利甚ケヌス**** においおのみ必芁ずなりたす。 なぜなら、****ufbx**** が FBX フォヌマット特有の挙動や癖を 内郚で自動的に凊理するよう蚭蚈されおいるためです。 --- ## ⚠ 泚意 FBX フォヌマットは非垞に耇雑で、 ****あたり䜿われないが存圚する倚くの機胜**** を持っおいたす。 そのため、FBX ファむルを盎接扱う堎合は次の点に泚意が必芁です。 > 💡 新しい FBX ファむルを読み蟌むたびに、 > そのファむルが利甚しおいる未察応の機胜に察応する必芁があるかもしれたせん。 もし自分自身で ****むンポヌタず出力ファむルの䞡方を管理しおいる**** 堎合は、 必芁な機胜だけをサポヌトすれば十分ですが、 そうでない堎合は広範囲な仕様ぞの察応が求められたす。 --- 📘 ****補足**** この内容は MIT / Public Domain ラむセンスのもずで公開された [ufbx (c) 2020 Samuli Raivio](https://ufbx.github.io) のドキュメントを翻蚳・敎圢したものです。 # 🧭 Node Transformsノヌド倉換 FBX のノヌド倉換は、****䞀連の倉換のチェヌン****ずしお構成されおいたす。 もし特別な理由がなければ、FBX 固有の倉換モデルを盎接扱うよりも、 ****ufbx が提䟛する倉換衚珟****を䜿甚するこずを匷く掚奚したす。 詳现は → [Elements / Nodes / Transforms](/elements/nodes/#transforms) を参照しおください。 --- ## 🔩 基本構造Transform Properties FBX 内でのノヌド倉換は、いく぀かの****プロパティ****で構成されおいたす。
プロパティ名 意味
`"Lcl Translation"` 芪ノヌドに察する平行移動
`"Lcl Scaling"` 芪ノヌドに察する非䞀様スケヌル
`"Lcl Rotation"` 芪ノヌドに察する回転オむラヌ角
`"RotationOrder"` `"Lcl Rotation"` のオむラヌ回転順序 `ufbx_rotation_order` 
--- ### 🎯 ピボット・オフセット関連 以䞋のプロパティによっお、回転やスケヌルの䞭心・ずれが定矩されたす。
プロパティ名 内容
`"ScalingPivot"` スケヌリングの䞭心点
`"ScalingOffset"` スケヌル埌のオフセット移動
`"RotationPivot"` 回転の䞭心点
`"RotationOffset"` 回転埌のオフセット移動
さらに `"Lcl Rotation"` 以倖に、****2皮類の補助回転****が存圚したす
プロパティ名 内容
`"PreRotation"` `"Lcl Rotation"` の前に適甚される回転垞に XYZ 順
`"PostRotation"` `"Lcl Rotation"` の埌に適甚される ****逆回転**** 垞に XYZ 順
--- ## ⚙ 倉換チェヌンの蚈算䟋 以䞋は、****ufbx の内郚補正adjust transformを考慮しない**** 基本的なノヌド倉換の蚈算䟋です。 ```cpp // 手動で `ufbx_node.node_to_parent` を蚈算 // ※ ufbx固有の調敎倉換adjust transformは考慮しない Matrix4 get_transform(ufbx_node *node) { ufbx_props *props = &node->props; // 䞻芁プロパティを取埗必芁に応じおカヌブから評䟡 int64_t rotation_order = ufbx_find_int(props, "RotationOrder", 0); Vector3 lcl_translation = ufbx_find_vec3(props, "Lcl Translation", ufbx_zero_vec3); Vector3 lcl_scaling = ufbx_find_vec3(props, "Lcl Scaling", ufbx_zero_vec3); Vector3 lcl_rotation = ufbx_find_vec3(props, "Lcl Rotation", ufbx_zero_vec3); Vector3 rotation_pivot = ufbx_find_vec3(props, "RotationPivot", ufbx_zero_vec3); Vector3 scaling_pivot = ufbx_find_vec3(props, "ScalingPivot", ufbx_zero_vec3); Vector3 rotation_offset = ufbx_find_vec3(props, "RotationOffset", ufbx_zero_vec3); Vector3 scaling_offset = ufbx_find_vec3(props, "ScalingOffset", ufbx_zero_vec3); Vector3 pre_rotation = ufbx_find_vec3(props, "PreRotation", ufbx_zero_vec3); Vector3 post_rotation = ufbx_find_vec3(props, "PostRotation", ufbx_zero_vec3); // オむラヌ角 → クォヌタニオン倉換 Quaternion lcl_quat = Quaternion_euler(lcl_rotation, (EulerOrder)rotation_order); Quaternion pre_quat = Quaternion_euler(pre_rotation, EulerOrder_XYZ); Quaternion post_quat = Quaternion_euler(post_rotation, EulerOrder_XYZ); Matrix4 m = Matrix4_identity; // スケヌル適甚ピボット・オフセット含む m = Matrix4_translate(-scaling_pivot) * m; m = Matrix4_scale_nonuniform(lcl_scaling) * m; m = Matrix4_translate(scaling_pivot) * m; m = Matrix4_translate(scaling_offset) * m; // 回転適甚PostRotation は反転 m = Matrix4_translate(-rotation_pivot) * m; m = Matrix4_rotate(Quaternion_inverse(post_quat)) * m; m = Matrix4_rotate(lcl_quat) * m; m = Matrix4_rotate(pre_quat) * m; m = Matrix4_translate(rotation_pivot) * m; m = Matrix4_translate(rotation_offset) * m; // 最埌に平行移動 m = Matrix4_translate(lcl_translation) * m; return m; } ``` --- ## 🧮 Adjust Transforms調敎倉換 FBX の座暙系やピボットの扱いに応じお、 ufbx は内郚でいく぀かの「調敎倉換adjust transform」を自動的に付䞎したす。 これらを考慮しないず、芋た目䞊の座暙がずれるこずがありたす。 ### 䞻な adjust transform の察応衚
機胜 察応するフィヌルド
`UFBX_SPACE_CONVERSION_ADJUST_TRANSFORMS` `adjust_pre_rotation` , `adjust_pre_scale`
`UFBX_SPACE_CONVERSION_MODIFY_GEOMETRY` `adjust_pre_rotation` , `adjust_translation_scale`
`UFBX_PIVOT_HANDLING_ADJUST_TO_PIVOT` `adjust_pre_translation`
`UFBX_INHERIT_MODE_HANDLING_COMPENSATE` `adjust_post_scale`
`ufbx_load_opts.target_camera_axes` `adjust_post_rotation`
`ufbx_load_opts.target_light_axes` `adjust_post_rotation`
`ufbx_node.has_adjust_transform` が `true` の堎合は、 ノヌドが非単䜍≠ identityの調敎倉換を持っおいたす。 ただし、垞に適甚しおも安党です。 --- ### 💻 Adjust 倉換察応版の完党蚈算䟋 ```cpp // ufbx固有の adjust transform を考慮した `ufbx_node.node_to_parent` の蚈算 Matrix4 get_transform(ufbx_node *node) { ufbx_props *props = &node->props; // プロパティの取埗 int64_t rotation_order = ufbx_find_int(props, "RotationOrder", 0); Vector3 lcl_translation = ufbx_find_vec3(props, "Lcl Translation", ufbx_zero_vec3); Vector3 lcl_scaling = ufbx_find_vec3(props, "Lcl Scaling", ufbx_zero_vec3); Vector3 lcl_rotation = ufbx_find_vec3(props, "Lcl Rotation", ufbx_zero_vec3); Vector3 rotation_pivot = ufbx_find_vec3(props, "RotationPivot", ufbx_zero_vec3); Vector3 scaling_pivot = ufbx_find_vec3(props, "ScalingPivot", ufbx_zero_vec3); Vector3 rotation_offset = ufbx_find_vec3(props, "RotationOffset", ufbx_zero_vec3); Vector3 scaling_offset = ufbx_find_vec3(props, "ScalingOffset", ufbx_zero_vec3); Vector3 pre_rotation = ufbx_find_vec3(props, "PreRotation", ufbx_zero_vec3); Vector3 post_rotation = ufbx_find_vec3(props, "PostRotation", ufbx_zero_vec3); // ufbx 特有の調敎パラメヌタ Vector3 adjust_pre_translation = node->adjust_pre_translation; Quaternion adjust_pre_rotation = node->adjust_pre_rotation; Quaternion adjust_post_rotation = node->adjust_post_rotation; float adjust_pre_scale = (float)node->adjust_pre_scale; float adjust_post_scale = (float)node->adjust_post_scale; float adjust_translation_scale = (float)node->adjust_translation_scale; // クォヌタニオン化 Quaternion lcl_quat = Quaternion_euler(lcl_rotation, (EulerOrder)rotation_order); Quaternion pre_quat = Quaternion_euler(pre_rotation, EulerOrder_XYZ); Quaternion post_quat = Quaternion_euler(post_rotation, EulerOrder_XYZ); Matrix4 m = Matrix4_identity; // 埌凊理post-adjust m = Matrix4_rotate(adjust_post_rotation) * m; m = Matrix4_scale(adjust_post_scale) * m; // スケヌル m = Matrix4_translate(-scaling_pivot) * m; m = Matrix4_scale_nonuniform(lcl_scaling) * m; m = Matrix4_translate(scaling_pivot) * m; m = Matrix4_translate(scaling_offset) * m; // 回転 m = Matrix4_translate(-rotation_pivot) * m; m = Matrix4_rotate(Quaternion_inverse(post_quat)) * m; m = Matrix4_rotate(lcl_quat) * m; m = Matrix4_rotate(pre_quat) * m; m = Matrix4_translate(rotation_pivot) * m; m = Matrix4_translate(rotation_offset) * m; // 平行移動 m = Matrix4_translate(lcl_translation) * m; // 前凊理pre-adjust m = Matrix4_translate(adjust_pre_translation) * m; m = Matrix4_rotate(adjust_pre_rotation) * m; m = Matrix4_scale(adjust_pre_scale) * m; // translation のみスケヌリング m.m03 *= adjust_translation_scale; m.m13 *= adjust_translation_scale; m.m23 *= adjust_translation_scale; return m; } ``` 📘 実際の実装䟋 [`ufbxi_get_transform()` on GitHub](https://github.com/ufbx/ufbx/blob/6dd7771ee215c7489a211b7aa259f1056ce14354/ufbx.c#L21497-L21558) --- ## 🧱 Geometric Transformsゞオメトリ倉換 ゞオメトリ倉換**geometry transforms**は、 ノヌドの****子ノヌドには圱響せず、ノヌド自身の内容䟋メッシュだけを倉換****したす。 詳现は → [Elements / Nodes / Geometry Transforms](/elements/nodes/#geometry-transforms)
プロパティ名 内容
`"GeometricTranslation"` ノヌド内コンテンツの平行移動
`"GeometricScaling"` ノヌド内コンテンツのスケヌル
`"GeometricRotation"` ノヌド内コンテンツの回転垞に XYZ 順
--- ### 💻 Geometry Transform の蚈算䟋 ```cpp // 手動で `ufbx_node.geometry_to_node` を蚈算 Matrix4 get_geometry_transform(ufbx_node *node) { ufbx_props *props = &node->props; Vector3 geo_translation = ufbx_find_vec3(props, "GeometricTranslation", ufbx_zero_vec3); Vector3 geo_scaling = ufbx_find_vec3(props, "GeometricScaling", ufbx_zero_vec3); Vector3 geo_rotation = ufbx_find_vec3(props, "GeometricRotation", ufbx_zero_vec3); Quaternion geo_quat = Quaternion_euler(geo_rotation, EulerOrder_XYZ); Matrix4 m = Matrix4_identity; m = Matrix4_scale_nonuniform(geo_scaling) * m; m = Matrix4_rotate(geo_quat) * m; m = Matrix4_translate(geo_translation) * m; return m; } ``` --- 📘 ****備考**** このドキュメントは MIT / Public Domain ラむセンスのもずで公開された [ufbx (c) 2020 Samuli Raivio](https://ufbx.github.io) の内容を翻蚳・敎圢しおいたす。 # Advanced # ⚙ Advanced応甚線 このセクションでは、****ufbx の高床な利甚方法や特殊なケヌス**** に぀いお解説したす。 暙準的なモデルの読み蟌み・描画に加え、より深い制埡や拡匵を行いたい堎合に参照しおください。 --- 💡 ****この章に含たれるトピック䟋****
項目 抂芁
🧩 ****Custom Load Options**** 読み蟌み時に座暙系・軞蚭定・空間倉換を指定する方法
🔄 ****Memory Management**** 倖郚アロケヌタや独自メモリ管理の統合
🧮 ****Low-level Access**** ファむル内郚のノヌド・プロパティ・カヌブぞの盎接アクセス
🧠 ****Threading / Async Loading**** スレッドセヌフな利甚・非同期読み蟌みの実装䟋
🧱 ****Internal Structures**** ufbx 内郚の構造䜓蚭蚈・評䟡順序の理解
--- 📘 ****備考**** このドキュメントは MIT / Public Domain ラむセンスのもずで公開された [ufbx (c) 2020 Samuli Raivio](https://ufbx.github.io) の内容を翻蚳・敎圢しおいたす。 # 🧩 Build Optionsビルドオプション **ufbx** のビルドは、䞻に ****プリプロセッサマクロ**`#define`****** によっおカスタマむズしたす。 マクロの定矩方法は次のいずれかです。 1. コンパむラオプションでグロヌバルに指定する 2. `"ufbx.h"` や `"ufbx.c"` をむンクルヌドする前にマクロを定矩する 3. たたは以䞋を定矩しお独自蚭定ファむルを読み蟌む ```c #define UFBX_CONFIG_HEADER "my-config.h" #define UFBX_CONFIG_SOURCE "my-source-config.h" ``` これにより、`ufbx.h` および `ufbx.c` 内で指定した蚭定ファむルが自動的にむンクルヌドされたす。 --- ## 📘 ヘッダ蚭定Header 倚くの蚭定マクロは `"ufbx.c"` 内だけで有効にすれば十分です。 ただし、****型やむンラむン関数に圱響を䞎えるマクロ**** は `"ufbx.h"` にも定矩する必芁がありたす。 ```c // アサヌトを独自実装に眮き換える #define ufbx_assert(cond) my_assert(cond) // 浮動小数型を double → float に倉曎 #define UFBX_REAL_IS_FLOAT ``` --- ## ⚙ オプション機胜の無効化 **ufbx** のサむズを小さくしたい堎合、 特定の機胜をマクロで無効化できたす。 ```c // メッシュの现分化 #define UFBX_NO_SUBDIVISION // NURBS のテッセレヌション #define UFBX_NO_TESSELLATION // ゞオメトリキャッシュの読み蟌み #define UFBX_NO_GEOMETRY_CACHE // シヌン評䟡 #define UFBX_NO_SCENE_EVALUATION // スキン評䟡 #define UFBX_NO_SKINNING_EVALUATION // アニメヌションベむク #define UFBX_NO_ANIMATION_BAKING // 面の䞉角化 #define UFBX_NO_TRIANGULATION // むンデックス生成 #define UFBX_NO_INDEX_GENERATION // OBJ 圢匏の読み蟌みを無効化 #define UFBX_NO_FORMAT_OBJ ``` --- ## 💟 メモリアロケヌションMemory Allocation **ufbx** は暙準の `malloc()` / `realloc()` / `free()` を䜿甚したす。 これを独自アロケヌタに眮き換える方法は3通りありたす ### 方法①マクロでフックする ```c #define ufbx_malloc(size) my_alloc(size) #define ufbx_realloc(ptr, old_size, new_size) my_realloc(ptr, old_size, new_size) #define ufbx_free(ptr, size) my_free(ptr, size) #include "ufbx.c" ``` ### 方法②倖郚関数ずしお定矩する ```c #define UFBX_EXTERNAL_MALLOC void *ufbx_malloc(size_t size); void *ufbx_realloc(void *ptr, size_t old_size, size_t new_size); void ufbx_free(void *ptr, size_t size); ``` ### 方法③アロケヌタを完党に無効化する ```c #define UFBX_NO_MALLOC ``` この堎合、ナヌザヌが `ufbx_allocator` を提䟛しない限り、 メモリ確保を行う API はすべお倱敗したす。 --- ## 📂 ファむル入出力File I/O 暙準の `FILE` API を䜿甚しお `ufbx_load_file()` が動䜜したす。 独自のファむルI/Oを䜿いたい堎合は、以䞋の方法で䞊曞き可胜です。 ### 倖郚定矩で差し替え ```c #define UFBX_EXTERNAL_STDIO void *ufbx_stdio_open(const char *path, size_t path_len); size_t ufbx_stdio_read(void *file, void *data, size_t size); bool ufbx_stdio_skip(void *file, size_t size); uint64_t ufbx_stdio_size(void *file); void ufbx_stdio_close(void *file); ``` ### 暙準I/Oを完党に無効化 ```c #define UFBX_NO_STDIO ``` この堎合、`ufbx_load_file()` など `FILE` に䟝存する機胜は利甚できたせん。 代わりに、`ufbx_load_opts.open_file_cb` によるカスタム読み蟌みを利甚したす。 --- ## 🧮 数孊関数Math **ufbx** は `` の䞀郚関数を利甚したすが、 ****ビット単䜍で䞀臎する結果を保蚌したい堎合****や ****暙準ラむブラリを䜿甚できない環境****では、 倖郚定矩で䞊曞きするこずができたす。 ```c #define UFBX_EXTERNAL_MATH double ufbx_sqrt(double x); double ufbx_sin(double x); double ufbx_cos(double x); double ufbx_tan(double x); double ufbx_asin(double x); double ufbx_acos(double x); double ufbx_atan(double x); double ufbx_atan2(double y, double x); double ufbx_pow(double x, double y); double ufbx_fmin(double a, double b); double ufbx_fmax(double a, double b); double ufbx_fabs(double x); double ufbx_copysign(double x, double y); double ufbx_nextafter(double x, double y); double ufbx_rint(double x); double ufbx_ceil(double x); int ufbx_isnan(double x); ``` これらは自前で定矩するか、 [`extra/ufbx_math.c`](https://github.com/ufbx/ufbx/blob/master/extra/ufbx_math.c) を䜿甚可胜です。 --- ## 🧱 暙準ラむブラリの陀去C Standard Library `UFBX_NO_LIBC` を定矩するず、 ほずんどの暙準ラむブラリ䟝存を無効化できたす。 これにより組み蟌み環境などでも利甚可胜になりたす。 ```c #define UFBX_NO_LIBC ``` この定矩により、デフォルトで以䞋が暗黙的に有効になりたす - `UFBX_EXTERNAL_MALLOC` - `UFBX_EXTERNAL_STDIO` - `UFBX_EXTERNAL_MATH` 暙準機胜を完党に䜿わない堎合は ```c #define UFBX_NO_MALLOC #define UFBX_NO_STDIO ``` を䜵甚したす。 --- ### `` 関数の再実装が必芁 暙準ラむブラリを䜿わない堎合、以䞋の関数を提䟛する必芁がありたす。 たたは [`extra/ufbx_libc.c`](https://github.com/ufbx/ufbx/blob/master/extra/ufbx_libc.c) を䜿甚 ```c size_t ufbx_strlen(const char *str); void *ufbx_memcpy(void *dst, const void *src, size_t count); void *ufbx_memmove(void *dst, const void *src, size_t count); void *ufbx_memset(void *dst, int ch, size_t count); const void *ufbx_memchr(const void *ptr, int value, size_t count); int ufbx_memcmp(const void *a, const void *b, size_t count); int ufbx_strcmp(const char *a, const char *b); int ufbx_strncmp(const char *a, const char *b, size_t count); ``` --- ### 📊 最䜎限必芁なヘッダ 以䞋のヘッダは、ラむブラリなしでも通垞利甚可胜です ```c #include #include #include #include ``` もしこれらすら利甚できない環境では ```c #define UFBX_NO_LIBC_TYPES ``` を定矩し、自前でこれらの型定矩を `"ufbx.h"` ず `"ufbx.c"` の䞡方に甚意する必芁がありたす。 --- 📘 ****備考**** このドキュメントは MIT / Public Domain ラむセンスのもずで公開された [ufbx (c) 2020 Samuli Raivio](https://ufbx.github.io) の内容を翻蚳・敎圢しおいたす。 # Reference