Merge pull request #437 from unitALG/v2.0

V2.0 - Edits for com.unity.formats.fbx only

Author: vkovec

Packages/com.autodesk.fbx/Documentation~/com.autodesk.fbx.md

@@ -1,12 +1,12 @@
-# About the FBX SDK C# Bindings package 
+# FBX SDK C# Bindings 
 
 __Version__: 2.0.0-preview
 
-The FBX SDK C# Bindings provide access from Unity C# scripts to a subset of the Autodesk FBX SDK, version 2018.1.
+The FBX SDK C# Bindings package provides access to a subset of the Autodesk® FBX® SDK, version 2018.1 from Unity C# scripts.
 
-The Autodesk® FBX® SDK is a free, easy-to-use, C++ software development platform and API toolkit that allows application and content vendors to transfer existing content into the FBX format with minimal effort.
+The Autodesk® FBX® SDK is a C++ software development platform and API toolkit that is free and easy-to-use. It allows application and content vendors to transfer existing content into the FBX format with minimal effort.
 
-The FBX SDK C# Bindings support the FBX Exporters package. The subset or the API that is exposed is geared towards exporting; import is not guaranteed to be possible yet.
+> ***Note:*** The FBX SDK C# Bindings package exposes only a subset of the API. That subset enables exporter tools, such as the [FBX Exporter](https://docs.unity3d.com/Packages/com.autodesk.fbx@latest) package. Using the FBX SDK C# Bindings package for importing is not recommended. See [Known issues](#issues) below for more information.
 
 ## Requirements
 
@@ -21,15 +21,25 @@ The FBX SDK C# Bindings package contains:
 * C# bindings
 * Compiled binaries for MacOS and Windows that include the FBX SDK
 
-## Known Issues
+## Known issues
 
-* In this version, you cannot downcast the C# objects, which limits the use of the bindings for an importer. For example, if the FBX SDK declares in C++ that it will return an FbxDeformer, on the C++ side if you happen to know it is in fact an FbxSkinDeformer you could safely cast the deformer to a skin deformer. However, on the C# side, this is not permitted.
-* While there are guards against some common errors, it is possible to crash Unity by writing C# code that directs the FBX SDK to perform invalid operations. For example, if you have an FbxProperty in C# and you delete the FbxNode that contains the property, if you try to use the FbxProperty, that will have undefined behaviour which may include crashing the Unity Editor. Make sure to read the editor log if you have unexplained crashes when writing FBX SDK C# code.
-* The FBX SDK C# Bindings package is not supported if you build using the IL2CPP backend.
+### Importing
 
-## API Documentation
+In this version, you cannot downcast the C# objects, which limits the use of the bindings for an importer. For example, if the FBX SDK declares in C++ that it will return an `FbxDeformer`, you could safely cast the deformer to a skin deformer on the C++ side if you happen to know it is an `FbxSkinDeformer`. However, on the C# side, this is not permitted.
 
-There is no API documentation in the preview package. Refer to the <a href="http://help.autodesk.com/view/FBX/2018/ENU/">Autodesk FBX SDK API documentation</a>.
+### Invalid operations
+
+While there are guards against some common errors, it is possible to crash Unity by writing C# code that directs the FBX SDK to perform invalid operations. For example, if you have an `FbxProperty` in C# and you delete the `FbxNode` that contains the property, using the `FbxProperty` may produce undefined behavior This may even include crashing the Unity Editor. Make sure to read the editor log if you have unexplained crashes when writing FBX SDK C# code.
+
+### IL2CPP backend
+
+The FBX SDK C# Bindings package is not supported if you build using the IL2CPP backend.
+
+
+
+## API documentation
+
+There is no API documentation in the preview package. See the <a href="http://help.autodesk.com/cloudhelp/2018/ENU/FBX-Developer-Help/cpp_ref/annotated.html">Autodesk® FBX® SDK API documentation</a>.
 
 The bindings are in the `Autodesk.Fbx` namespace:
 

Packages/com.unity.formats.fbx/Documentation~/TableOfContents.md

@@ -0,0 +1,6 @@
+* [FBX Exporter](index)
+    * [Exporting FBX files from Unity](exporting)
+    * [Converting GameObjects to Linked Prefabs](prefabs)
+    * [Integrating Unity with 3D modeling software](integration)
+    * [Setting FBX Export options](options)
+    * [Developer's guide](devguide)

Packages/com.unity.formats.fbx/Documentation~/com.unity.formats.fbx.md

@@ -0,0 +1,88 @@
+# Developer’s Guide
+
+As a developer you have access to the FBX Exporter from C# scripting. You can use the basic API by providing a single GameObject or a list of GameObjects. Note that default export settings are used for exporting the GameObjects to the FBX file.
+
+You can call the FBX Exporter from C# using methods found in the [**UnityEditor.Formats.Fbx.Exporter** ](../api/UnityEditor.Formats.Fbx.Exporter.html) namespace, for example:
+
+```
+using System.IO;
+using UnityEngine;
+using UnityEditor;
+using UnityEditor.Formats.Fbx.Exporter;
+
+public static void ExportGameObjects(Object[] objects)
+{
+    string filePath = Path.Combine(Application.dataPath, "MyGame.fbx");
+    ModelExporter.ExportObjects(filePath, objects);
+    
+    // ModelExporter.ExportObject can be used instead of 
+    // ModelExporter.ExportObjects to export a single game object
+}
+```
+
+## Runtime
+
+The FBX SDK bindings can be executed during gameplay allowing import and export at runtime. Currently a custom importer/exporter needs to be written in order to do so, as the FBX Exporter is Editor only.
+
+### Basic Exporter:
+
+```
+using Autodesk.Fbx;
+using UnityEngine;
+using UnityEditor;
+
+protected void ExportScene (string fileName)
+{
+    using(FbxManager fbxManager = FbxManager.Create ()){
+        // configure IO settings.
+        fbxManager.SetIOSettings (FbxIOSettings.Create (fbxManager, Globals.IOSROOT));
+        
+        // Export the scene
+        using (FbxExporter exporter = FbxExporter.Create (fbxManager, "myExporter")) {
+
+            // Initialize the exporter.
+            bool status = exporter.Initialize (fileName, -1, fbxManager.GetIOSettings ());
+
+            // Create a new scene to export
+            FbxScene scene = FbxScene.Create (fbxManager, "myScene");
+
+            // Export the scene to the file.
+            exporter.Export (scene);
+        }
+    }
+}
+```
+
+### Basic Importer:
+
+```
+using Autodesk.Fbx;
+using UnityEngine;
+using UnityEditor;
+
+protected void ImportScene (string fileName)
+{
+    using(FbxManager fbxManager = FbxManager.Create ()){
+        // configure IO settings.
+        fbxManager.SetIOSettings (FbxIOSettings.Create (fbxManager, Globals.IOSROOT));
+        
+        // Import the scene to make sure file is valid
+        using (FbxImporter importer = FbxImporter.Create (fbxManager, "myImporter")) {
+
+            // Initialize the importer.
+            bool status = importer.Initialize (fileName, -1, fbxManager.GetIOSettings ());
+
+            // Create a new scene so it can be populated by the imported file.
+            FbxScene scene = FbxScene.Create (fbxManager, "myScene");
+
+            // Import the contents of the file into the scene.
+            importer.Import (scene);
+        }
+    }
+}
+```
+
+### Limitations
+
+* IL2CPP is not supported
+* Only 64 bit Windows and MacOS standalone player builds are supported

Packages/com.unity.formats.fbx/Documentation~/devguide.md

@@ -0,0 +1,248 @@
+# Exporting FBX files from Unity
+
+Use __Export To FBX__ (menu: __GameObject__ > __Export To FBX__) to manually export GameObject hierarchies to an FBX file. The FBX Exporter exports selected objects and their descendants to a single FBX file. However, if you select both a parent and a descendant, only the parent’s hierarchy is exported.
+
+The FBX Exporter exports the following objects:
+
+* GameObject hierarchies and their transforms
+* [Meshes](#meshes) 
+* SkinnedMeshRenderers with the following exceptions:
+    * Humanoid rigs are not supported
+    * Meshes in bone hierarchies are not supported
+* Materials as Phong if the material has specular; Lambert in all other cases
+* Textures
+* [Cameras](#cameras)
+* [Lights](#lights)
+* [Contraints](#constraints)
+* [Animation](#animation)
+* Blendshapes
+
+
+
+<a name="meshes"></a>
+
+## Mesh support
+
+The FBX Exporter exports multiple copies of the same Mesh as instances. The FBX Exporter also exports the following mesh attributes:
+
+- Normals
+- Binormals
+- Tangents
+- Vertex Colors
+- All 8 Mesh UVs, if present
+- Quads or Triangles
+
+
+
+<a name="cameras"></a>
+
+## Cameras
+
+The FBX Exporter exports both Game Cameras and Physical Cameras.
+
+> ***Note:*** In Unity's Inspector, a Camera's **Physical Camera** property determines whether it is a *Physical Camera* or a *Game Camera*.
+
+### Physical Cameras
+
+The FBX Exporter exports Physical Cameras, including these properties:
+
+- **Focal Length**
+- **Lens Shift**
+
+### Game Cameras
+
+On export, the FBX Exporter sets the **Aperture Height** to 0.612 inches, and calculates the **Aperture Width** using this sensor back relative to the Camera's Aspect Ratio. For example:
+
+    * Full 1024 4:3 (1024x768) 
+       *  Aspect Ratio 4:3 
+       *  Aperture Width = 0.612 * (1024/768)
+
+The Aperture Width and Height values appear in Unity's Inspector as the **Sensor Size** property in millimeters. 
+
+The FBX Exporter derives the **Focal Length** from the vertical Field of View (FOV) and the sensor back settings (Aperture Width and Aperture Height). The FBX Exporter uses the default FBX setting for Aperture Mode: Vertical.
+
+**Film Resolution Gate** is set to Horizontal so that the importing software fits the resolution gate horizontally within the film gate. 
+
+The **Near & Far** Clipping Plane values have a range of 30 cm to 600000 cm.
+
+In addition, the **Projection** type (perspective/orthographic) and **Aspect Ratio** are also exported.
+
+
+
+<a name="lights"></a>
+
+## Lights
+
+The FBX Exporter exports Lights of type *Directional*, *Spot* , *Point*, and *Area*.
+
+It also exports the following Light attributes:
+
+- Spot Angle (for Spot lights)
+
+- Color
+
+- Intensity
+
+- Range
+
+- Shadows (either On or Off)
+
+  
+
+<a name="constraints"></a>
+
+## Constraints
+
+The FBX Exporter exports these types of Constraints:
+
+- [Rotation](#cns_rotation)
+- [Aim](#cns_aim)
+- [Position](#cns_position)
+- [Scale](#cns_scale)
+- [Parent](#cns_parent)
+
+In addition, the FBX Exporter also exports the following attributes for all Constraint types:
+
+- Sources
+- Source Weight
+- Weight
+- Active
+
+<a name="cns_rotation"></a>
+
+### Rotation
+
+The FBX Exporter exports the following attributes for the Rotation Constraint type:
+
+- Affected axes (X,Y,Z)
+- Rotation Offset
+- Rest Rotation
+
+<a name="cns_aim"></a>
+
+### Aim
+
+The FBX Exporter exports the following attributes for the Rotation Constraint type:
+
+- Affected axes (X,Y,Z)
+
+- Rotation Offset
+- Rest Rotation
+- World Up Type
+- World Up Object
+- World Up Vector
+- Up Vector
+- Aim Vector
+
+<a name="cns_position"></a>
+
+### Position
+
+The FBX Exporter exports the following attributes for the Position Constraint type:
+
+- Affected axes (X,Y,Z)
+- Translation Offset
+- Rest Translation
+
+<a name="cns_scale"></a>
+
+### Scale
+
+The FBX Exporter exports the following attributes for the Scale Constraint type:
+
+- Affected axes (X,Y,Z)
+- Scale Offset
+- Rest Scale
+
+<a name="cns_parent"></a>
+
+### Parent
+
+The FBX Exporter exports the following attributes for the Parent Constraint type:
+
+- Source Translation Offset (animated)
+- Source Rotation Offset (animated)
+- Affect Rotation Axes
+- Affect Translation Axes
+- Rest Translation
+- Rest Rotation
+
+
+
+<a name="animation"></a>
+
+## Animation
+
+The FBX Exporter exports Legacy and Generic Animation from Animation and Animator components, or from a Timeline clip. 
+
+In addition, it also exports the following animated attributes:
+
+- Transforms
+- Lights:
+  - Intensity
+  - Spot Angle (for Spot lights)
+  - Color
+- Cameras:
+  - Field of View
+- Constraints:
+  - Weight
+  - Source Weight
+  - Translation Offset (Position Constraint)
+  - Rotation Offset (Rotation Constraint and Aim Constraint)
+  - Scale Offset (Scale Constraint)
+  - Source Translation Offset (Parent Constraint)
+  - Source Rotation Offset (Parent Constraint)
+  - World Up Vector (Aim Constraint)
+  - Up Vector (Aim Constraint)
+  - Aim Vector (Aim Constraint)
+
+
+
+## Export Options window
+
+When exporting an FBX file, the following Export Options window opens, displaying options for specifying what gets exported.
+
+![Export Options window](images/FBXExporter_ExportOptionsWindow.png)
+
+
+### Export Options Properties
+
+| Property:                 | Function:                                                    |
+| :------------------------ | :----------------------------------------------------------- |
+| __Export Name__           | Specify the name of the FBX file to export.                  |
+| __Export Path__           | Specify the location where the FBX Exporter will save the FBX file. |
+| __Source__                | Transfer the transform animation from this object to the __Destination__ transform. <br/><br/>**Notes:**<br/> - __Source__ must be an ancestor of __Destination__<br/> - __Source__ may be an ancestor of the selected object. |
+| __Destination__           | Which object to transfer the transform animation to.<br/><br/>This object receives the transform animation on objects between __Source__ and __Destination__ as well as the animation on the Source itself. |
+| __Export Format__         | Select the format to use in the FBX file (ASCII or Binary).  |
+| __Include__               | Choose whether to export both Models and Animation, only Models, or only Animations. |
+| __LOD level__             | For level of detail (LOD) groups, choose the desired level of detail to export (all, highest, or lowest). <br/><br/>**Notes:** - The FBX Exporter ignores LODs outside of selected hierarchy.<br/> - The FBX Exporter does not filter out objects that are used as LODs and doesn't export them if they aren’t direct descendants of their respective LOD Group |
+| __Object(s) Position__    | Choose whether to reset the exported objects to world center, or keep world transforms during export.<br/><br/>If you select multiple objects for export, and you choose __Local Centered__ from this drop-down menu, the FBX Exporter centers objects around a shared root while keeping their relative placement unchanged. |
+| __Animated Skinned Mesh__ | Check this option to export animation on objects with skinned meshes.<br/><br/>If unchecked, the FBX Exporter does not export animation on skinned meshes. |
+| __Compatible Naming__     | Check this option to control renaming the GameObject and Materials during export. <br/><br/>The FBX Exporter ensures compatible naming with Autodesk® Maya® and Autodesk® Maya LT™ to avoid unexpected name changes between Unity and Autodesk® Maya® and Autodesk® Maya LT™. During export the FBX Exporter replaces characters in Unity names as follows:<br/> - Replaces invalid characters with underscores ("_"). Invalid characters are all non-alphanumeric characters, except for the colon (":").<br/> - Adds an underscore ("_") to names that begin with a number.<br/> - Replaces diacritics. For example, replaces "é" with “e”.<br/><br/>For FBX Model filenames, the FBX Exporter ensures that names do not contain invalid characters for the file system. The set of invalid characters may differ between file systems.<br/><br/>**Note:** If you have a Material with a space in its name, the space is replaced with an underscore ("_"). This results in a new Material being created when it is imported. For example, the Material named "Default Material" is exported as "Default_Material" and is created as a new Material when it is imported. If you want the exported Material to match an existing Material in the scene, you must manually rename the Material before exporting. |
+| __Export Unrendered__     | Check this option to export meshes that either don't have a renderer component, or that have a disabled renderer component. For example, a simplified mesh used as a Mesh collider. |
+
+
+
+## Exporting animation from the Timeline
+
+In order to export an animation clip from the timeline, in the Timeline editor select the desired clip, then from the top menu select __GameObject__ > __Export Selected Timeline Clip__.
+
+
+## Exporting with relevant system units
+
+The FBX Exporter exports in centimeter units (cm) with the Mesh set to real world meter (m) scale. For example, if vertex[0] is at [1, 1, 1] m., it is converted to [100, 100, 100] cm. 
+
+In Autodesk® 3ds Max®, it is recommended to set the system units to centimeters to avoid any scaling on Model import and export.
+
+There are no specific import options to adjust between Unity and Autodesk® Maya® and Autodesk® Maya LT™. When working in Autodesk® Maya® and Autodesk® Maya LT™, you can set the working units to meters if you prefer. 
+
+For example, when working with large models in Autodesk® Maya® and Autodesk® Maya LT™, to ensure that the models clip to meters, adjust the scale of the near and far clipping planes for all cameras by 100x. In addition, you should scale lights by 100x so that objects display in the viewport.
+
+## Known issues
+
+* Bind pose of animated skinned mesh is lost on export. For example, if you export an animated skinned mesh from Unity and import it into Autodesk® Maya® and Autodesk® Maya LT™ you will not be able to set the character into the bind pose using the **Rigging** > **Skin** > **Go to Bind Pose** command.
+
+* Animated skinned meshes may not export with the correct skinning if they are not in the bind pose on export (that is, not being previewed in the Animation or Timeline windows, and the original Rig's FBX must not contain animation)
+
+* For skinned meshes all bones must be descendants of the root bone. For example, if the root bone is "hips" and the right leg for the same skinned mesh is not a descendant of hips, export will fail.
+