Internal Model Definition
Gorilla3D holds model, animation and material data inside of an internal structure for better instancing, abstraction and management.
The so-called DefTypes can be stored and loaded to/from *.G3D file format.
Structure
Take a look at the following schematic structure of a model definition.
-TModelDef // holds a list of TMeshDef instances -List::Meshes -TMeshDef|TVertexGroupDef // a reference to the owner model -@Model::TModelDef -/TMeshDef|TVertexGroupDef -/List::Meshes // holds a list of TMaterialDef instances -List::Materials -TMaterialDef // a reference to the owner model -@Model::TModelDef // holds a list of textures -List::Textures -TTextureDef -/TTextureDef -/List::Textures // holds a list of shader codes -List::Shaders -TShaderDef -/TShaderDef -/List::Shaders // holds a list of sub materials for layered material sources -List::Materials -TMaterialDef [...] -/TMaterialDef -/List::Materials -/TMaterialDef -/List::Materials -List::Lights -TLightDef -/List::Lights -List::Cameras -TCameraDef -/List::Cameras // holds a list of THumanoidDef instances -List::Humanoids -THumanoidDef // a reference to the owner model -@Model::TModelDef // holds a list of TControllerDef references -@List::Controllers // represents a tree of TJointDef nodes -Root::TJointDef -TJointDef -TJointDef -TJointDef -TJointDef -/TJointDef -/TJointDef -/Root::TJointDef -/THumanoidDef -THumanoidDef [...] -/THumanoidDef -/List::Humanoids // holds a list of TControllerDef instances -List::Controllers -TControllerDef // a reference to the mesh, the controller handles -@Mesh::TMeshDef // is a sub component of TSkinDef -Skin::TSkinDef -TSkinDef // the owner controller of the skin definition -@Controller::TControllerDef // holds a list of TJointRefDef instances - these // are referenced objects to TJointDef instances -List::LinkedJoint -TJointRefDef -TJointRefDef -TJointRefDef -TJointRefDef -TJointRefDef [...] -/List::LinkedJoints // contains one or more joints as skeleton roots -List::Skeletons -TJointRefDef -TJointRefDef [...] -/List::Skeletons -/TSkinDef -/Skin::TSkinDef -/TControllerDef -TControllerDef [...] -/TControllerDef -/List::Controllers // holds a list of TAnimationDef instances -List::Animations -TAnimationDef // reference to the owner model -@Model::TModelDef // holds a list of TAnimationStageDef instances -List::Stages -TAnimationStageDef -List::Interpolators -TInterpolatorDef -TInterpolatorDef -TInterpolatorDef [...] -/List::Interpolators -/TAnimationStageDef -TAnimationStageDef [...] -/TAnimationStageDef -/List::Stages -/TAnimationDef -TAnimationDef [...] -/TAnimationDef -/List::Animations -/TModelDef
G3D File Format
The Gorilla3D file format is a representation of the internal model structure defintion. It allows different kinds of storage formats:
Format | Notes |
---|---|
BSON | binary json format: https://en.wikipedia.org/wiki/BSON [wikipedia] |
JSON | default json format: https://en.wikipedia.org/wiki/JSON [wikipedia] |
In addition to those formats we provide different storage options:
Option | Notes |
---|---|
None | The save routine simply stores data plain as BSON or JSON |
Zipped | Store as zipped data stream. You can extend this option by the FastestCompression or MaxCompression option. If none of them is set, the exporter will use default compression. |
Beautified | Compatible with JSON format. Defines data will be exported with linebreaks and indents or not. This option has no influence on bson format. |
FastestCompression | If the Zipped-Option is set, this option will choose the fastest algorithm for packing the data stream. |
MaxCompression | If the Zipped-Option is set, this option will chose the maximum compression algorithm for packing the data stream. |
Depending on your model data you can configure those options to optimize filesize. In most cases a zipped JSON format with MaxCompression provides the best results.
G3D_TEST : TGorillaG3DOptions = [TGorillaG3DOption.Zipped, TGorillaG3DOption.MaxCompression];
File Header
Every G3D file starts with some header information, where is defined which format and options are used. The header format is described below:
TGorillaG3DFormat = (BSONFormat, JSONFormat); TGorillaG3DOption = ( None, Zipped, Beautified, FastestCompression, MaxCompression); TGorillaG3DOptions = Set Of TGorillaG3DOption; TGorillaG3DHeader = record /// DEFAULT-VALUE = "Gorilla3D " /// 10 characters identify the exporter tool Exporter : Array[0..9] of Byte; Version : Cardinal; /// Datetime when the file was generated. (8 byte float value) Timestamp : TDateTime; /// The data format the was stored (bson or json). Format : TGorillaG3DFormat; /// enum with values above Options : TGorillaG3DOptions; end;
TModelDef
The TModelDef structure is representing a scene consisting of meshes, materials, lights, cameras and animations. It does not contain mesh information itself. Instead sub meshes are attached which hold those kind of information.
The model definition is the logical representation of a scenery. By this visual FMX instances are built and rendered.
Meshes
A mesh definition is the most important type inside of a model, which holds all necessary vertex data for rendering.
LMesh := TMeshDef.Create(Self); LMesh.Id := 'Mesh1'; LMesh.Transform := TMatrix3D.CreateTranslation(TPoint3D.Create(-1, -2, 0.5)); // Self = TModelDef Self.AddMesh(LMesh);
TMeshDef instances are able to manage further sub-meshes inside. If no vertex data is applied to them, the functionate as group. A working example for mesh groups is the TModelDef, which doesn't hold any vertex data, but meshes instead.
LSubMesh := TMeshDef.Create(LMesh); LSubMesh.Id := 'SubMesh1'; LSubMesh.Transform := TMatrix3D.CreateTranslation(TPoint3D.Create(1, 2, -0.5)); LMesh.AddMesh(LSubMesh);
Static meshes
Static meshes pushing their vertex information once to the GPU and getting rendered only by switching to the specific MeshBuffer.
This increases performance enormously and allows rendering of models with huge number of vertices.
If “IsStatic” is deactivated, firemonkey pushes vertex data to the GPU on each frame, instead.
Warning: “IsStatic” can only be used for static and none-animated meshes. It's recommended to use it for environmental objects (houses, boxes, …) or other static objects in your scene. Do not use it for characters!
Remark: For animated elements Gorilla3D provides an animation-caching mechanism, taking advantage of that feature. Read more about animation-caching here: Animations
Remark: STL or OBJ import automatically set “IsStatic” to true.
Setup vertex data manually
Read more about this topic here: CustomMesh
There are a lot of applications need to setup vertex data manually. The mesh definition provides a simple to use method AddPolygon(). Have a look at the following example:
TUserMesh = class(TGorillaMesh) public constructor Create(AOwner : TComponent); override; procedure Build(); end; [...] constructor TUserMesh.Create(AOwner: TComponent); begin inherited; FDef := TMeshDef.Create(nil); end; procedure TUserMesh.Build(); begin with TMeshDef(FDef) do begin AddPolygon([PointF(-0.5, -0.5), PointF(0.5, -0.5), PointF(0.5, 0.5), PointF(-0.5, 0.5)]); AddPolygon([PointF(-0.5, -1.5), PointF(0.5, -1.5), PointF(0.5, -0.75), PointF(-0.5, -0.75)]); AddPolygon([PointF(-1.5, -1.5), PointF(-0.75, -1.5), PointF(-0.75, -0.75), PointF(-1.5, -0.75)]); // after all polygon vertices were added // compute tex-coords, normals, tangents and binormals CalcTextureCoordinates(); CalcFaceNormals(); CalcTangentBinormals(); // after vertex data was finally setup - set mesh to static and push data // to GPU IsStatic := true; end; end; [...] // create a visual instance at runtime FUserMesh := TUserMesh.Create(GorillaViewport1); FUserMesh.Parent := GorillaViewport1; FUserMesh.Position.Point := Point3D(3, -1, 3); FUserMesh.RotationAngle.X := -45; FUserMesh.Build(); FUserMesh.MaterialSource := GorillaLambertMaterialSource1;
Fast Ray-Casting
Gorilla3D implements an optimization for fast ray-casting onto triangles inside the model definition and its meshes. By default Firemonkey ray-casting, f.e. by click-detection, only the boundingbox or all triangles are getting scanned. This is extremely slow on large models.
Therefore bounding volume hierarchy (BVH) supported was introduced. To enable this functionality manually, use the following snippet.
Remark: By acquiring a bounding volume hierarchy, vertices are getting duplicated, which increases memory usage.
LModelDef.AcquireBVH(); try [...] finally LModelDef.ReleaseBVH(); end;
If the vertex data changed meanwhile and you need to update BVH tree, use the following method:
LModelDef.UpdateBVH();
Use this functionality, f.e. to ray-cast the height of a terrain at a certain position to place an object onto.
VertexGroups
Since format version 2, TVertexGroupDef instances are supported. A vertex group allows to group a number of triangles, referred in an owner mesh, to a virtual mesh. By this you are able to render only this specific triangle group by a specific material.
In some cases this helps to improve memory usage. While declaring vertex data in a parent mesh, those virtual meshes can reuse the same vertices for their triangle rendering, instead of duplicating them.
Materials
A model manages multiple material definitions which can be referenced multiple times to reduce memory usage.
// Self = TModelDef structure, manages all materials LMatDef := TMaterialDef.Create(Self, 'Material1');
Textures
For better texture management link an TGorillaAssetsPackage to your TModelDef. This allows optimized texture handling and removes duplicated textures. Otherwise you may create an texture-image multiple times, which increases memory-usage a lot.
var LAsset : TGorillaTextureAsset; LChannel : TColorChannelDef; LTexFile : String; begin LTexFile := 'textures\diffuse.jpg'; // we want a texture for the diffuse color channel LChannel := TColorChannelDef.Diffuse; // Self = TModelDef if Assigned(Self.Package) then begin // try to read texture file from assets package // checks if it was already loaded LAsset := TGorillaAssetsPackage(Self.Package).GetOwnerAssetFromFile( Self.Asset as TGorillaAsset, GORILLA_ASSETS_TEXTURE, LTexFile) as TGorillaTextureAsset; // if we have found a texture asset, add it to the material if Assigned(LAsset) then LMatDef.AddTexture(LChannel, LAsset, false); // false == NOT standalone end else begin // we don't want to use an assets package LAsset := TGorillaTextureAsset.Create(nil); // import texture file manually LAsset.ImportFromFile(LTexFile); // afterwards add it to the material LMatDef.AddTexture(LChannel, LAsset, true); // true == STANDALONE end; end;
Lights
Gorilla3D is also able to manage logical instances for lights. It is very common for 3D file formats to export lighting information.
// Self = TModelDef LLightDef := TLightDef.Create(Self); LLightDef.LightType := TLightType.Spot; LLightDef.Direction := Point3D(0, 1, 0); LLightDef.Diffuse := TAlphaColorF.Create(1, 0, 0, 1); LLightDef.Ambient := TAlphaColorF.Create(0.5, 0.5, 0.5, 1); LLightDef.Specular := TAlphaColorF.Create(0.15, 0.15, 0.15, 1); LLightDef.Intensity := 1; // attenuation values are configurable but have no effect on rendering yet, due to FMX limitations LLightDef.ConstantAttenuation := 1.0; LLightDef.LinearAttenuation := 0; LLightDef.QuadraticAttenuation := 0; LLightDef.SpotCutOff := 180; LLightDef.SpotExponent := 0; LLightDef.Transform := TMatrix3D.CreateTranslation(TPoint3D.Create(0, -50, -50));
Cameras
Gorilla3D is also able to manage logical instances for cameras. It is very common for 3D file formats to export camera information.
// Self = TModelDef LCamDef := TCameraDef.Create(Self); LCamDef._Type := TCameraType.PerspectiveCamera; // TCameraType.OrthographicCamera LCamDef.Target := 'Mesh1'; LCamDef.FOV := 45; LCamDef.AspectRatio := 16 / 9; // near and far plane are configurable, but have no effect on rendering // due to hardcoded constant values in FMX framework LCamDef.NearPlane := 1; LCamDef.FarPlane := 1000; LCamDef.Transform := TMatrix3D.CreateTranslation(TPoint3D.Create(0, -5, -10));
Shaders
The TShaderDef class is already defined, but not productive yet. It is planned to be able to define shaders inside the logical G3D format. But further previous steps are necessary to allow this functionality.
Skin/Skeleton Animations
G3D format supports animation export and import of skin and skeleton animations by bone skin structures.
[Source: https://cgi.tutsplus.com/tutorials/building-a-basic-low-poly-character-rig-in-blender--cg-16955]
Skin/Skeleton
A skin and skeleton structure is necessary to animate meshes in modern way by vertex weights. Imagine your model contains a skeleton consisting of bones having certain influence on the vertices surrounding them. When moving a bone all connected vertices are moving with it.
To declare such a structure, a so called humanoid (or armature) definition (THumanoidDef) is defined, which contains a bone hierarchy. Each bone (or joint) is connected to a parent bone or to the root bone of the armature. At this point a humanoid/armature has no connection to a specific mesh.
To create a connection between a mesh and a humanoid, create a TControllerDef structure. It will connect mesh and bone information with each other to allow animation. The controller definition contains references to the humanoid/armature-bone structure and stores weights and affected vertices. This allows to reuse a humanoid/armature by another controller with different values or a different mesh.
Humanoid / Joints
A humanoid or also called armature is a hierarchy of bones or also called joints. This hierarchy allows to represent relations between bones and their dependency. For example, if you move the upper leg, the foot and lower leg should also move.
[Source: https://commons.wikimedia.org/wiki/File:Blender3D_Shuffle-Cycle.png]
A joint (or bone) is defined by a position relative to its parent and is used to define the influence on certain vertices.
The armature contains a root joint which is the starting point and top instance in the hierarchy. A single humanoid can be linked to multiple controller definitions, which define how to animate a humanoid.
When an animation is executed, all humanoids and their controllers are executed. In most cases the controller modifies the joint position by the given [key:value] pair of the animation (TAnimationDef | TAnimationStageDef | TInterpolatorDef).
While the joint is transformed, he knows by its controller information, how to modify the connected mesh and its vertices. And it will change vertex information based on its the weight values and a list of connected vertices.
// Self = TModelDef structure, which manages all humanoids LHuman := THumanoidDef.Create(Self); LHuman.Id := 'Armature1'; Self.AddHumanoid(LHuman);
Controllers
A controller definition is a structure to declare how a humanoid/armature interacts with a specific mesh and its vertices. You can create multiple controllers for a single humanoid, for example to modify different sub-meshes inside a model, but with the same armature behind.
When creating a controller, humanoid joints are linked as reference. You then have to define weights and affected vertices for each joint-reference. The references and mesh link is managed by the TSkinDef sub structure of the controller.
// LMesh = TMeshDef structure LCtrl := TControllerDef.Create(LMesh); LCtrl.Id := 'Armature1Controller'; // Self = TModelDef structure which manages all controllers Self.AddController(LCtrl); // create a skin to manager joints LCtrl.Skin := TSkinDef.Create(LCtrl); LCtrl.Skin.Id := LCtrl.Id + 'Skin';
As mentioned above, we need to reference all humanoid joints by the LinkJoint() method. Besides all sub joints/bones we have to link our root bone manually.
// because it's the root joint, last argument needs to be TRUE (= standalone) LCtrl.Skin.Skeleton := TJointRefDef.Create(LHuman.Root, LCtrl, true); // afterwards we link the root joint, which will create another reference LCtrl.Skin.LinkJoint(LHuman.Root);
In the following go through all humanoid joints and link those explicitly. In case you are writing an importer for a specific 3D file format, this may depend on the given data in your file. Because sometimes not all joints are linked, because they might not affect the mesh.
procedure LinkMyJoints(ASkin : TSkinDef; AJoint : TJointDef); var LEnum : TJointDefMap.TPairEnumerator; begin if not Assigned(AJoint.Joints) then Exit; LEnum := AJoint.Joints.GetEnumator(); try while LEnum.MoveNext() do begin ASkin.LinkJoint(LEnum.Current.Value); LinkMyJoints(ASkin, LEnum.Current.Value); end; finally FreeAndNil(LEnum); end; end; [...] LinkMyJoints(LCtrl.Skin, LHuman.Root);
Animations
TAnimationDef contains information about animating a model and its meshes by various modifiers or so called interpolators. Each animation definition (TAnimationDef) can contain multiple TAnimationStageDef instances, which contain modifiers / interpolators to change specific properties of a referenced object (mesh, joint, …).
// Self = TModelDef structure, which manages all animations LAnimDef := TAnimationDef.Create(Self); LAnimDef.Id := 'Walk-Animation'; Self.AddAnimation(LAnimDef);
AnimationStage
An animation stage is directly referred to a specific object (mesh or joint) inside the parent model structure. It is the container which holds all modifiers / interpolators.
LStage := TAnimationStageDef.Create(LAnimDef); LStage.Id := 'Joint1'; // link the TJointDef (of the humanoid) to the stage, as element to be modified LStage.Reference := LMyJointDef; // finally add the stage to the animation LAnimDef.AddStage(LStage);
Interpolators
Interpolators are modifiers, that are able to change various properties, f.e. joint transformation or vertex data.
Time-Value pairs
An interpolator holds a specific number of keys and their values at a certain point of time. During animation it computes missing values between two keys.
Each interpolator needs to store at least two key values to define start and endpoint of an animation. The key consists of a timestamp and a value depending on the used interpolator datatype. The timestamp values need to be normalized to a range between 0.0 and 1.0. While the length (in seconds) of the animation is stored in the “Duration” property.
Here is an example on how to setup an interpolator to move a joint by 5.0 unit upwards in 3.5 seconds. The values will be computed linearly, but various types are also possible:
TAnimationKeyInterpolationType = (Linear, Quadratic, Cubic, Quartic, Quintic, Sinusoidal, Exponential, Circular, Elastic, Back, Bounce);
var LTimes : TArray<Single>; LValues : TArray<TPoint3D>; LTypes : TAnimationKeyInterpolationDynArray; // setup at least 2 keys SetLength(LTimes, 2); SetLength(LValues, 2); SetLength(LTypes, 2); LTimes[0] := 0.0; LTimes[1] := 3.5; // == 3.5 seconds LValues[0] := TPoint3D.Zero; LValues[1] := TPoint3D.Create(0.0, -5.0, 0.0); // move upwards by 5.0 units LTypes[0] := TAnimationKeyInterpolationType.Linear; LTypes[1] := TAnimationKeyInterpolationType.Linear; // linear interpolation // lets create a TPoint3D interpolator LPt3DInter := TPoint3DInterpolatorDef.Create(LStage); LPt3DInter.Id := 'Joint1PositionInterpolator'; LPt3DInter.Path := 'Position.Point'; LStage.AddInterpolator(LPt3DInter); // add keys to our interpolator LPt3DInter.AddKeys(LTimes, LValues, LTypes); // this method will normalize LTimes value to a range of 0.0 - 1.0 // and stores 3.5 seconds in the "Duration" property LPt3DInter.NormalizeKeyTimeValues();
Supported Datatypes
To allow different datatypes for property modification, the most common interpolators are already predefined and used by various import formats like DAE (Collada), glTF or FBX.
Point3D Interpolator
Allows to animate a TPoint3D property value.
LPt3DInter := TPoint3DInterpolatorDef.Create(LStage); LPt3DInter.Id := 'Joint1PositionInterpolator'; LPt3DInter.Path := 'Position.Point'; LStage.AddInterpolator(LPt3DInter);
Vector3D Interpolator
Allows to animate a TVector3D property value.
LV3DInter := TVector3DInterpolatorDef.Create(LStage); LV3DInter.Id := 'Joint1Position2Interpolator'; LV3DInter.Path := 'Position.Vector'; LStage.AddInterpolator(LV3DInter);
Quaternion3D Interpolator
Allows to animate a TQuaternion3D property value.
LQ3DInter := TQuaternion3DInterpolatorDef.Create(LStage); LQ3DInter.Id := 'Joint1RotationInterpolator'; LQ3DInter.Path := 'Quaternion'; LStage.AddInterpolator(LQ3DInter);
Matrix3D Interpolator
Allows to animate a TMatrix3D property value. This is especially used for joint-transformation animations. A transformation matrix contains information about translation, rotation and scaling. It is recommended to use this interpolator instead of single position, scale and rotation interpolators.
LMat3DInter := TTransformationInterpolatorDef.Create(LStage); LMat3DInter.Id := 'Joint1TransformationInterpolator'; LMat3DInter.Path := ''; // it automatically uses the "TransformMatrix" property LStage.AddInterpolator(LMat3DInter);
MeshData Interpolator
Allows to animate an array of vertex positions. Vertex positions for each vertex inside the array value will be interpolated. CAUTION: A direct vertex manipulation is not managed by a joint/bone. So you have to link the stage to a specific mesh instance.
LVertexInter := TMeshInterpolatorDef.Create(LStage); LVertexInter.Id := 'Mesh1VertexInterpolator'; LVertexInter.Path := 'Coordinates'; LStage.AddInterpolator(LVertexInter);
Optimization
Because many formats like X3D, FBX or DAE export separated interpolators for rotation, translation or scaling, runtime processing is getting very slow. Therefore Gorilla3D provides a helper method to merge those value to a single transformation interpolator. This increases performance and reduces structure complexity.
LAnimDef.UnifyInterpolators( [TUnifyInterpolatorOption.EulerXYZ], procedure(AStage : TAnimationStageDef; var AKey: Single; var AValue: TMatrix3D; var AInterpolation : TAnimationKeyInterpolationType) begin // allows to modify the merged transformation matrix before adding as key:value pair AValue := ConvertToFbxMatrix(AValue); end );
In some formats key time values are not normalized to a range between 0.0 - 1.0. Because Gorilla3D expect those timestamps to be normalized, you have to adjust them by:
LMat3DInter.NormalizeKeyTimeValues();
But carefully, this method modifies the “Duration” property of the specific interpolator.
TODO
- TSamplerDef integration
- TImageDef integration
- TShaderDef integration
Changelog
- Version = 1
- first format introduction with undocumented modification during development process
- Version = 2
- Gorilla.DefTypes.TVertexGroupDef introduced to render an owner-mesh partially
- Gorilla.DefTypes.TCameraDef introduced
- Gorilla.DefTypes.TLightDef extended
- “Type” in every node exporting the qualified delphi class name
- TMaterialDefKind.mkVertexColor introduced for separation between Color and VertexColor rendering
- TMaterialDefKind.mkCustom introduced with new properties: ShadingModel, UseTexturing, UseTexture0, UseLighting, UseVertexColor, UseSpecular
- late resolving of humanoid controllers, because controllers were not registered before creating humanoids (circular reference)
- on loading g3d files, the loader now adds the path of the g3d to texture paths, if they are relative
- multiple skeletons per skindef allowed
Next step: Transparency