View source for Mesh Converter/en

== Scope ==
The W4 game engine uses its own asset storage format. Therefore, before using any fbx asset, it must be converted. You can do this using the Mesh Converter tool that comes with the W4 SDK.

Mesh Converter converts assets from Autodesk FBX (.fbx) format. Other formats are not supported.

== Technical limitations ==
Mesh Converter converts any fbx with the following restrictions:

Due to the hardware and software features of some popular device models, a skinned mesh may contain:
* no more than 28 bones
* no more than 8 vertices per bone

== How to use ==
The procedure for obtaining the project repository is described in the article [[Quick Start]].
The W4MeshConverter.bin file is located in the w4framework/tools directory.
The conversion should be started from the command line, as described in the section [http://wiki.w4-dev.ciliz.com/index.php/Mesh_Converter#Short_manual Short manual] and in the following example.

=== Mesh Exmple ===
==== Preparing ====
Take the [http:\\ Utah teapot] as an example.
If you view the file using the utility [https://www.autodesk.com/products/fbx/fbx-review Autodesk FBX Review], you will see something like the following figure.

[[File:D1b94d56-cb70-428b-ac1c-65701c690238.png|500px]] 

Pay attention to the orientation of the teapot spout when viewing fbx, we will return to this later.

==== Converting ====
Copy the model file to the directory where the file W4MeshKonverter.bin is located.

To convert the model to the W4 Engine format (asset), you should execute the following command:

 ./W4MeshConverter utah-teapot.fbx teapot

As a result, the 'teapot' directory will appear. It contains asset data.
==== Adding to the project structure ====
To work with an asset, you need to copy its directory (in our case, it is 'teapot') into the directory 'resources' of the project. The 'resources' directory is located at the same level of the project structure as the 'sources' directory. Thus, the structure of the project will become similar to the following:

 .
 └── W4TemplateGame
     ├── resources
     │   └── teapot
     │       ├── Animations
     │       ├── BoneInfo
     │       ├── Materials
     │       │   ├── defaultMaterial.matInst
     │       │   └── defaultSkinnedMaterial.matInst
     │       ├── Splines
     │       ├── teapot.asset
     │       └── VertexData
     │           ├── Utah Teapot Quads_0.ib
     │           └── Utah Teapot Quads.vb
     └── sources
         └── main.cpp

==== Code example ====
Loading:

 auto asset = Asset::load(Path("resources/teapot", "teapot.asset"));

Adding to the Render:

 auto root = RootNode::make();
 root->addChild(asset->getRoot());
 Render::instance().getPass(0)->setRoot(root);

Full source code of the example:

 #include "W4Framework.h"
 
 W4_USE_UNSTRICT_INTERFACE
 
 class AssetSample : public w4::IGame
 {
 public:
 
     AssetSample() = default;
     ~AssetSample() = default; 
 
     void onStart() override
     {
         auto cam = Render::instance().getScreenCamera();
         cam->setWorldTranslation({0.f, 0, -50.f});
 
         auto asset = Asset::load(Path("resources/teapot", "teapot.asset"));
 
         auto root =  RootNode::make();
         root->addChild(asset->getRoot());
         Render::instance().getPass(0)->setRoot(root);
     }
 };
 
 W4_RUN(AssetSample)

==== Result ====
As a result of execution, the same teapot should be displayed, but with a slight difference.

[[File:1b952599-fc03-428f-96e8-ae86935b46d8.png|500px]]

If you compare the drawings, you will notice that the spout of the teapot in the FBX Review is directed in other side. This happens due to differences in coordinate systems.

The FBX coordinate system [https://help.autodesk.com/view/FBX/2017/ENU/?guid=__files_GUID_CC93340E_C4A1_49EE_B048_E898F856CFBF_htm Scene Axis and Unit Conversion] is right-handed (with the Y coordinate direction up), whereas W4 coordinate system is left-sided (the Y axis is also directed up).

=== Animated mesh Exmple ===
Working with animated meshes is not much different from [http://wiki.w4-dev.ciliz.com/index.php/Mesh_Converter#Mesh_Exmple the simple meshes].
==== Preparing ====
Take, for example, [http:// Rigged Hand].

If you view it using [https://www.autodesk.com/products/fbx/fbx-review Autodesk FBX Review] you will see something like the following:

[[file:hand.mov|500px]]

==== Converting ====
Copy the model file to the directory where the file W4MeshKonverter.bin is located.

Convert the model to the W4 Engine format (asset), using the following command:

 ./W4MeshConverter Hand_rigged.FBX hand

As a result, the 'hand' directory will appear. It contains asset data.
==== Adding to the project structure ====
To work with an asset, you need to copy its directory (in our case, it is 'hand') into the directory 'resources' of the project. The 'resources' directory is located at the same level of the project structure as the 'sources' directory. Thus, the structure of the project will become similar to the following:

 .
 └── W4TemplateGame
     ├── resources
     │   └── hand
     │       ├── Animations
     │       │   └── Take 001.ssa
     │       ├── BoneInfo
     │       │   ├── bone_main_hande.skeleton
     │       │   └── Hand_rigged.skin
     │       ├── hand.asset
     │       ├── Materials
     │       │   ├── defaultMaterial.matInst
     │       │   └── defaultSkinnedMaterial.matInst
     │       ├── Splines
     │       └── VertexData
     │           ├── Hand_rigged_0.ib
     │           └── Hand_rigged.vb
     └── sources
         └── main.cpp

==== Code example ====
Download asset and add it to the render tree:

 auto asset = Asset::load(Path("resources/hand", "hand.asset"));
 render::getRoot()->addChild(asset->getRoot());

If you build the project now, you probably will not see anything. Because the camera located "inside" the asset.

Move the camera away (you may need to set other values, depending on the size of the browser window, the size of the object, etc.):

 auto cam = render::getScreenCamera();
 cam->setWorldTranslation({0.f, 125.f, -300.f});
  
Now if you build the project, a hand will appear on the screen, but it will not be animated.

Run the animator on the corresponding skinned mesh. In this example it is known that we have one skinned mesh and it has one animation, so in a loop we go through the entire asset tree and all skinned meshes in it and we will play the animation (in our example - the first one):

 asset->getRoot()->traversal([&](Node& node)
 {
   if(node.is<SkinnedMesh>())
   {
     auto skinned = node.as<SkinnedMesh>();
     skinned->getAnimator(0).setIsLooped(true);
     skinned->play(0);
   }
 });

Full source code for the example:

 #include "W4Framework.h"
 
 W4_USE_UNSTRICT_INTERFACE
 
 class MeshAnimatedSample : public w4::IGame
 {
 public:
     MeshAnimatedSample() = default;
 
     void onStart() override
     {
         auto asset = Asset::load(Path("resources/hand", "hand.asset"));
         render::getRoot()->addChild(asset->getRoot());
 
         auto cam = render::getScreenCamera();
         cam->setWorldTranslation({0.f, 150.f, -300.f});
 
         asset->getRoot()->traversal([&](Node &node)
         {
             if (node.is<SkinnedMesh>())
             {
                 auto skinned = node.as<SkinnedMesh>();
                 skinned->getAnimator(0).setIsLooped(true);
                 skinned->play(0);
             }
         });
     }
 };
 
 W4_RUN(MeshAnimatedSample)

==== Result ====
As a result of the program, the animation will be shown:

[[File:Hand engine.mov|500px]]

== Short manual ==
=== Basics ===
Convert utah-teapot.fbx to asset with the name 'asset' (current directory):

 ./W4MeshConverter utah-teapot.fbx

Convert utah-teapot.fbx to asset with the name 'teapot' (current directory):

 ./W4MeshConverter utah-teapot.fbx teapot

Convert utah-teapot.fbx to asset with the name 'teapot' which will be saved in the directory ~/some/dir:

 ./W4MeshConverter utah-teapot.fbx teapot ~/some/dir 

=== Common keys ===
Show manual:

 -h, --help

Scene statistics output:

 -v, --verbose

Example of statistics:

 (DEBUG) ==================== Scene statistics ====================
 (DEBUG) Nodes: 2
 (DEBUG) Geometries: 1
 (DEBUG) Poses: 0
 (DEBUG) Materials: 1
 (DEBUG) Textures: 0
 (DEBUG) ====================== Axis & Scale ======================
 (DEBUG) Up: +Y, Front: +ParityOdd, System: RightHanded
 (DEBUG) Scale: 1.000000
 (DEBUG) ================ Mesh: Red_label ================
 (DEBUG) Vertex count: 404
 (DEBUG) Index count: 2118
 (DEBUG) All polygons are triangles: 1
 (DEBUG) ==========================================================
 (DEBUG) create default material...
 (DEBUG) create default skinned material...

Size control (scale). Where 'arg' is the value. For example (10, 1, 0.1):

 --scale arg

Flip vertical axis V of texture coordinates. If the flag is specified, then a transformation 'V = 1.0 - V' will be applied to the texture coordinates:

 --uv-flip

=== Setting limitations ===
For all meshs, limit of the maximum number of vertices and indices can be set. For Skinned Meshs, limit of the maximum number of bones and the maximum number of bones per vertex can be set. 

A model that does not meet the specified restrictions can be forcedly converted using the flag 'force', however, performance is not guaranteed in this case:

 -f, --force

Setting a limit on the maximum number of vertices per object, where 'arg' is the value (it is not specified by default):

 --max-vertex arg

Setting a limit on the maximum number of indices per object, where 'arg' is the value (it is not specified by default):

 --max-index arg

Setting a limit on the maximum number of bones for Skinned Mesh, where 'arg' is value. The default is 28. When setting the value higher than the default value, operability is not guaranteed:

 --max-bones arg

Setting a limit on the maximum number of bones per vertex for Skinned Mesh, where 'arg' is the value. Default is 8. When setting the value higher than the default, operability is not guaranteed:

 --max-bones-per-vertex arg