MobileDragon 3D API Guide

MobileDragon 3D API Guide

Overview

Mobile Dragon 3D API gives the set of functions and classes for the organization and managements of drawing 3D scenes. This API is developed in view of features of graphic subsystems of various mobile platforms and uses the high-speed algorithms optimized for work on “slow” devices. 3D API represents low-level graphic library which is capable to draw various graphic primitives like triangles, lines and points. Mobile Dragon 3D API it is compatible with OpenGL (in the current version software render is supported only).
Support of LOD technology, different types of animation (including joint and texture animation) and lighting is included in the 3D API.

Render3D

The main class which is responsible for drawing is the Render3D class. This class gives all necessary functions for drawing of objects, definition of visibility of objects on the screen, cutting off of hidden objects and many other things. Also this class gives functions for work with illumination, fog, screen and view ports.
An object of Render3D class must be created in every Mobile Dragon 3D application. When application start, it is necessary to create Render3D class object and pass it to System class object before main loop of application will start.
The following example shows how to create Render3D class object:

// Create and store new 3D Render class object.
// Here:
// system – pointer to the System class object.
system->render3d = render = new Render3D;

Lets take up general Render3D features:

1) Work with backbuffer
There are functions for backbuffer clearing and copying control. Render3D has different types of clearing:
– clear color buffer,
– clear depth buffer,
– clear stencil buffer.
You can specify clearing type by flag.
For example:

// Set clear color.
render->SetClearColor(Color(0,0,128,0));

// Clear color buffer and depth buffer of backbuffer.
render->Clear(Render_ClearType_ClearColor|Render_ClearType_ClearDepth);

2) Work with Screen and Viewport
Render3D allow access to the screen properties.
For example:

// Get specified width dimension of display.
Int w = GetScreenWidth();

// Get specified height dimension of display.
Int h = GetScreenHeight();

The viewport is a rectangle on the device screen to which objects are rendered. It is possible to create and use several viewports by switching between them.
The following example shows how to set Viewport for Render3D class object:

// Get display width and height.
Int w = render->GetScreenWidth();
Int h = render->GetScreenHeight();

// Set render viewport to whole display.
render->SetViewport(0,0,w,h);

3) Work with perspective, world ,view and texture matrices
Render3D class allows controlling viewing volume by setting perspective frustum. The Viewing volume is used for clipping invisible objects (or their invisible parts) and for vertex projection on the screen.
The following example shows how to set Perspective for Render3D class object:

// Get display width and height.
Int w = render->GetScreenWidth();
Int h = render->GetScreenHeight();

// Set perspective parameters.
Fixed fovy = DegToRad(70);
Fixed aspect = Fixed(w)/h;
Fixed zNear = F_ONE; // = Fixed(1.0)
Fixed zFar = 500;

// Set render perspective.
render->SetPerspective(fovy,aspect,zNear,zFar);

Also Render3D class provides methods to manipulate world and view matrices. These matrices are used to compute the model coordinates into pixel coordinates on the screen. Texture matrix defines how texture coordinates will be transformed.
Matrices in Mobile Dragon 3D API is defined as 4x4 homogenous matrices. There are special functions in Render3D class to work with matrices.
For example:

// Set view identity matrix.
render->SetView(&IdentityMatrix4<Fixed>());

// Create translate matrix by vector (0,1,0).
Matrix4fx tm = TranslateMatrix4(Vector3fx(0,1,0));

// Set world matrix in created translate matrix.
render->SetWorld(&tm);

4) Work with material
Render3D allow setting material for drawing objects.
For example:

// Set material for object(s) drawing
// Here:
// mat – Material object.
render->SetMaterial(&mat);

// Here must be code of object(s) drawing.
// ...........
// All objects will drew with specified above material.

4) Lighting manage
The Render3D class provides functionality for lighting management. Render3D have list of Lights that affect result object lighting. There is set of functions to manipulate this list. Software 3D render allow adding unlimited count of lights, but only maximum 8 from their can be switched ON simultaneously.
The following example shows how to add light to the Render3D lights list:

// Here:
// light – Light class object.

// Add light to the render.
render->AddLight( light );

5) Render mode flags manage
Render3D class has set of flags that allow manipulating drawing process mode. This mode defined as Int value (4 bytes), where every bit means different mode flag. Render3D has following drawing modes:
– drawing triangles from back to front. By default is OFF.
– drawing without writing and checking Z-buffer. By default is OFF.
– drawing texture with perspective correction. By default is ON.
– fast drawing mode, with lower quality. For future OpenGL compatibility. By default is OFF.
– drawing with lighting mode. By default is ON.
– drawing with fog mode. By default is ON.
– logical pixel operation - COPY. By default is ON.
– logical pixel operation - OR. By default is OFF.
Render3D class has set of functions for work with these flags.
The following example shows how to switch on the texture perspective correction flag and fog drawing flag:

// Set texture perspective correction mode ON
render->SetMode(Render_PerspectiveCorrection_Mode);

// Set fog drawing mode ON
render->SetMode(Render_Fog_Mode);

6) Fog control
Render3D support scene drawing with using fog mode. Render3D creates and draw fog itself. Here is set of functions that allow controlling fog parameters (density, color, mode etc.).
Fog has three modes:
– linear fog modes,
– exponential fog mode,
– exponential squared fog.
For example:

// Set fog mode as linear.
SetFogMode( Render_FogMode_Linear );

// Set fog density as Fixed(0.5).
SetFogDensity( F_HALF );

// Set fog start distance.
SetFogStart( 50 );

// Set fog end distance.
SetFogEnd( 500 );

// Set fog color.
SetFogColor( Color( 0, 0, 255, 0 ) );

// Update fog. Need to call one time after all calls of
// SetFogColor(), SetFogMode(), SetFogDensity(), SetFogStart(), SetFogEnd().
UpdateFog();

7) Texture manage
Render3D provide functionality for texture management.
All loading textures stored into list of textures. Render3D don’t load the same texture twice. All object which has the same texture in material in fact reference to one loaded texture.
For example:

// Find specified texture by ASCII name in texture queue.
ObjRef<Texture> texture_a = render->FindTexture( "texture_a" );

// find specified texture by ASCII name in texture queue
// and if not found than load it from resource.
ObjRef<Texture> texture_b = render->LoadTexture( "texture_b" );

8) Drawing
Render 3D allow drawing various primitives: lines, points, triangles. Object geometry defined as set of triangles which stored in VertexBuffer class object. Therefore Render3D has set of functions to draw lines list, points list and VertexBuffer class objects. Also Render3D provide functions to draw 3D sprites (billboards for example) and check object visibility.
The following example shows how to draw VertexBuffer class object:

// Clipping flag.
Int object3d_clip;

// Set world transform matrix as identity.
render->SetWorldIdentityMatrix();

// Check VertexBuffer (vb) visibility.
object3d_clip = render->IsVisible( vb->center, vb->radius );

// If object is visible – draw them.
if( object3d_clip >= 1 )
{
// Set drawing material.
render->SetMaterial( &material );

// Send VertexBuffer (vb) to the draw queue.
render->Draw( vb, object3d_clip );

// Flush all draw queue for drawing.
render->Flush();
}

9) Other features, which are described below in separate issues (for example LOD Management).

Scene loading

Mobile Dragon API includes class MDMLoad, which provides functionality for loading 3D scenes and models from Mobile Dragon Model (MDM) file format.
It is necessary to init object of class MDMLoad first by calling Init() function. You should init loader independently of type loading scene.
For example:

// 3D data loader.
MDMLoad loader;

// Init loader.
// Here:
// “scene\\scene” is file name of MDM file (without extension “MDM”).
// render – pointer to the Render3D class object.
loader.Init(render,"scene\\scene");

It’s possible to use one loader instance to load different scenes. Every time you call Init() function, loader reset it’s state and can be used again.
After we’ve initialize loader, we can call loading function directly. This is only one function Load(), but it has different prototype and realization for every scene types: static scene, simple animation, joint animation etc.
For example:

1) Loading of static scene:
If type of loading scene is “static”, than all geometrical objects in this scenes will be presented as Object3D class objects.

// Define empty list of objects to store loading scene.
vector< ObjRef<Basic3D> > o3dlist

// Create loader.
MDMLoad mdm_arena;

// Init loader.
// Here:
// “arena\\arena” is file name of MDM file (without extension “MDM”).
// render – pointer to the Render3D class object.
mdm_arena.Init(render,"arena\\arena");

// Load() function will add loaded objects of scene into list.
// Here:
// render – pointer to the Render3D class object.
mdm_arena.Load(render, o3dlist);

2) Loading of static scene with portals:
Static scene may contain portals system. This is aggregate of rooms and passageways between their (portals). The objects that linked to the room belong to this room. The objects that linked to the portal belong to two rooms that linked by this portal.
MDMLoader allow loading portals scene and sort all objects in different lists.
– rooms – list of Room class objects.
– portals – list of portals.
– out_of_portals – list of objects that are not linked to the rooms and portals.
If you want to use portal system in your application, you should copy content of these lists for future usage.
For example:

// Define empty list of objects to store loading scene.
vector< ObjRef<Basic3D> > o3dlist

// Create loader.
MDMLoad mdm_arena;

// Init loader.
// Here:
// “arena\\arena” is file name of MDM file (without extension “MDM”).
// render – pointer to the Render3D class object.
mdm_arena.Init(render,"arena\\arena");

// Load() function will add loaded objects of scene into list.
// Here:
// render – pointer to the Render3D class object.
mdm_arena.Load(render, o3dlist);

// Get portals, rooms and out_of_portals lists.

// List of rooms.
vector< ObjRef<Room> > rooms = mdm_arena.rooms;

// List of portals.
vector< ObjRef<Portal> > portals = mdm_arena.portals;
// List of objects not linked to the rooms.
vector< ObjRef<Basic3D> > out_of_portals = mdm_arena.out_of_portals;

3) Loading of simple animation scene:
If type of loading scene is “simple animation”, than all geometrical objects in this scenes will be presented as Robot3D class objects.

// Define empty list of objects to store loading scene.
vector< ObjRef<Basic3D> > r3dlist

// Create loader.
MDMLoad mdm_simple;

// Init loader.
// Here:
// “simple\\simple” is file name of MDM file (without extension “MDM”).
// render – pointer to the Render3D class object.
mdm_simple.Init(render,"simple\\simple");

// Load() function will add loaded objects of scene into list.
// Here:
// render – pointer to the Render3D class object.
mdm_simple.Load(render, r3dlist);

4) Loading of tweening animation model:

// Here:
// render – pointer to the Render3D class object.

// Construct new animation objects to store animation.
ObjRef<Actor3DAnimation> actor_animation = Actor3DAnimation::Construct(render);

// Create loader.
MDMLoad mdm_anim;

// Init loader by file name of scene.
mdm_anim.Init(render, "tweening\\tweening");

// Load animation into Actor3DAnimation class object.
mdm_anim.Load(render, actor_animation);

5) Loading of joint animation model:
The feature of loading of joint animation is separate loading animation and details collection. Animation and details collection stored in the separate objects.
For example:

// Create joint animation object.
OnjRef<Joint3DAnimation> joint_animation = Joint3DAnimation::Construct(render);

// Load joint animation.
MDMLoad mdm_joint_anim;
mdm_joint_anim.Init(render, "robo_joint\\joint_animation");
mdm_joint_anim.Load(render,joint_animation);

// Create list of joint collection nodes.
vector< ObjRef<Joint3DCollectionNode> > joint_collection;

// Load join collection.
MDMLoad mdm_joint_coll;
mdm_joint_coll.Init(render, "robo_joint\\joint_collection");
mdm_joint_coll.Load(render,joint_collection);

6) Loading scenes with dummy objects.
If loading scene has dummy objects (dummy box and dummy sphere) than all this dummies will stored into separate list of dummy objects. You can directly access to this list.
For example:

// Define empty list of objects to store loading scene.
vector< ObjRef<Basic3D> > o3dlist

// Create loader.
MDMLoad mdm_arena;

// Init loader.
// Here:
// “arena\\arena” is file name of MDM file (without extension “MDM”).
// render – pointer to the Render3D class object.
mdm_arena.Init(render,"arena\\arena");

// Load() function will add loaded objects of scene into list.
// Here:
// render – pointer to the Render3D class object.
mdm_arena.Load(render, o3dlist);

// Get list of dummy objects.
vector< ObjRef<Basic3D> > dummies = mdm_arena.dummies;

LOD Management

The Mobile Dragon 3D API provides functionality for Levels Of Detail (LOD) management. This technology allows automatically switching geometry of drawing objects taking into account distance from camera to these objects. This means that we can draw high quality geometry if it is near from camera and low quality if it is far from camera. This will accelerate drawing process in general. The Render3D load LOD settings from file, which must be distributed with scene
First it is necessary to pass reference to the camera into the Render3D class object:

// Here:
// camera – Camera class object.
// render – pointer to the Render3D class object.

// Pass camera to the render.
render->SetCamera(&camera);

The LOD management allows usage of unlimited count of details levels. Designer should create different scenes with different LOD. All this scenes must be saved into separate files.
3D API uses switch radiuses (personal for every object) to select current LOD for objects. These radiuses are defined in LOD settings file (it that should be created with INI Compiler utility). To apply these settings it is necessary to load all MDM files with different LOD of scene and after this call LoadLODSettings() function of Render3D class object.
For example:

// 3D data loader for high LOD scene.
MDMLoad arena_high;

// Init loader.
// Here:
// “all_arenas\\arena01_high” is file name of MDM file
// (without extension “MDM”).
// render – pointer to the Render3D class object.
arena.Init(render,"all_arenas\\arena01_high");

// Load scene.
// Here:
// o3dlist_high – list of Object3D (geometrical) class objects with high LOD.
// render – pointer to the Render3D class object.
arena.Load(render, o3dlist_high);

// 3D data loader for low LOD scene.
MDMLoad arena_low;

// Init loader.
// Here:
// “all_arenas\\arena01_low” is file name of MDM file
// (without extension “MDM”).
// render – pointer to the Render3D class object.
arena.Init(render,"all_arenas\\arena01_low");

// Load scene.
// Here:
// o3dlist_low – list of Object3D (geometrical) class objects with low LOD.
// render – pointer to the Render3D class object.
arena.Load(render, o3dlist_low);

// Now add all list of objects into common vector.
// It is necessary to add first object list with high detalization,
// next – with lower detalization, next – more lower and so on,
// until will added the object list with lowest detalization.
// In this case there are only two LOD levels: high and low.
vector< vector< ObjRef<Object3D> > > all_objects;
all_objects.push_back(o3dlist_high); // add scene with high LOD
all_objects.push_back(o3dlist_low); // add scene with low LOD

// Now load and apply LOD settings to the loaded scene.
// Here:
// render – pointer to the Render3D class object.
// “all_arenas\\arena01_lod_sett” is file name of file of
// LOD settings (without extension).
render->LoadLODSettings(all_objects, "all_arenas\\arena01_lod_sett” ");

VertexBuffer

Render3D allow drawing special data structure named VertexBuffer. VB describe set of primitives (triangle) and therefore may define geometry of objects. VB contains array of vertex and indices for describing surface of object. Also there is stored information about texture coordinates, vertex and triangle normal.
VertexBuffer contents are defined by format of this VB. VB can include:
1. Vertex geometrical coordinates;
2. Vertex normal;
3. Triangle normal;
4. Texture UV-coordinates for 2 channels (diffuse texture and lightmap or some else);
5. Vertex light intensity;
Also VB’s format defines if VB has linked LOD VB, if VB store index, if this is packed VB.
VB’s format defined as Int value (4 bites), where every bit means, is corresponding format’s flag on or off.
VB allow also recomputing normals, transforming vertex by transformation matrix.
If you want to use VB, you should create and initialize it first. You should know format, vertex count and index count for this VB to do this. For example:

// create VertexBuffer
ObjRef<VertexBuffer> vb = VertexBuffer::Construct();

// define format for VertexBuffer
Int format = VertexBuffer_Format_Vxyz | // VB contains vertex X,Y,Z
VertexBuffer_Format_Nxyz | // VB contains vertex normals
VertexBuffer_Format_UV0 | // VB contains vertex UV coordinates
VertexBuffer_Format_Index; // VB contains indices

// init VertexBuffer
vb->Init( format, vertex_count_, index_count_ );

The code above creates new VertexBuffer and allocates memory for vertex and indices.

Also Vertex Buffer class has set of function, that allow to:
1) Get common geometry info (vertex count, index count, max vertex and index count).
For example:

// Get maximum VB’s vertex count.
// This is count of vertex for which memory was allocated when we call Init().
Int max_vertex_count = vb->GetMaxVertexCount();

// Get current VB’s vertex count.
// This is count of real used vertexes.
Int vertex_count = vb->GetVertexCount();

2) Work with VB format.
For example:

// Get format of VB.
Int format = vb->GetFormat();

// Chect if VB has vertex normals.
if(vb->CheckFormat(VertexBuffer_Format_Nxyz))
{
// VB has vertex normals.
}
else
{
// VB hasn’t vertex normals.
}

3) Access to the Axis Aligned Bounding Box (AABB). Every VB has own axis aligned bounding box and bounding sphere. You can access to its values.
For example:

// Get VB’s bounding box
AABB box = vb->GetAAB();

// Get radius of VB’s bounding sphere.
Fixed radius = vb->GetRadius();

4) Access control.
Every time you want to write or read VB’s content (vertexes, normals, indices), you should lock this VB first. This prevent VB from drawing during changing it’s content. To do this, you must call Lock() function with flag in parameter, that define for what purpose you have lock the VB. After you have change the VB’s content, you should to unlock this VB by calling UnLock() function. You may create Lock/UnLock section inside another Lock/UnLock section. VB has counter of calling of Lock() and UnLock() functions: every calling of Lock() function increment locks-counter, and every calling of UnLock() function decrement this counter. When last UnLock() function will called (locks-counter becomes 0-value) and all VB’s changes will take effect, and this VB can be drew.
For example:

void func_1()
{
// Lock VB for reading. This is first calling of Lock() function.
vb->Lock(VertexBuffer_LockType_Read);

// Here must be VB’s content reading code.
// .................

// Call another function.
func_2();

// Unlock VB. This is second and last calling of UnLock() function.
vb->UnLock();
}

void func_2()
{
// Lock VB for writing. This is second calling of Lock() function.
vb->Lock(VertexBuffer_LockType_Write);

// Here must be VB’s content writing code...
// .................

// Unlock VB. This is first calling of UnLock() function.
vb->UnLock();
}

5) Write and Read Content.
After you have lock VB for reading or writing access, you can read or write VB’s content. There is set functions to do this.
For example:

// Create new VB.
vb = VertexBuffer::Construct();

// Define format for VB.
Int format = VertexBuffer_Format_Vxyz |
VertexBuffer_Format_UV0 |
VertexBuffer_Format_Index;

// Initialize VB.
vb->Init( format, 4, 6 );

// Lock VB for Writing.
vb->Lock( VertexBuffer_LockType_Write );

Fixed uv[2]; // UV-coordinates.
Fixed vxyz[3]; // X,Y,Z – coordinates.
Int index; // Index counter

uv[0]=0;
uv[1]=0;

vxyz[0] = 10.0;
vxyz[1] = 20.0;
vxyz[3] = 30.0;

for(index = 0; index < 4; index++)
{
// Write UV0.
vb->WriteUV0( index, uv );

// Write XYZ.
vb->WriteVxyz( index, vxyz );
}

index = 0;

// Write inices.
vb->Index(index+2) = 0;
vb->Index(index+1) = 1;
vb->Index(index) = 2;

vb->Index(index+5) = 2;
vb->Index(index+4) = 3;
vb->Index(index+3) = 0;

// Unlock VB.
vb->UnLock();

6) LOD manage.
VB can contain link to another VB and switch radius for this VB. This is LOD VB that contains the same geometry only in lower level of details. When Render3D will draw VB, it will get distance between object and camera, and select necessary VB from hierarchy of LOD VB of base VB. There is set of function to work with LOD VBs.
For example:

// Set switch radius for LOD VB.
lod_vb->SetLODSwitchRadius( 30 );

// Link LOD VB to the base VB.
base_vb->AddLODVB( lod_vb );

// Set switch radius for base VB.
base_vb->SetLODSwitchRadius( 15 );

The code above means that when distance from camera to the object (which contains these VBs) will be lower than 15, Render3D will draw base VB, when distance from camera to the object will be between 15 and 30, Render3D will draw linked LOD VB, and when distance from camera to the object will be greater than 30, Render3D will draw no VB (object will disappear).

7) Other operations.
This is copy, transform, update normal operations. Every from these operations has Lock/UnLock section inside itself, you don’t need to include this section to call these functions.
For example:

// Copy only XYZ vertex coordinates and triangles normals from src_vb to dest_vb
dest_vb->Copy(*src_vb, VertexBuffer_Format_Vxyz | VertexBuffer_Format_TriNxyz);

// Transform VB content by transformation matrix (tm).
dest_vb->Transform(&tm);

Common features for 3D objects:

Mobile Dragon 3D API provides few classes for work with objects which relate to 3D objects category: static, dynamic, animated, lighting and dummy objects. All of these classes are inherited from one common class Basic3D. Basic3D class is abstract and provides common functionality for 3D objects.

Every 3D class has own unique ClassID. All 3D classes has GetClassID() function that return ClassID for each of them. All 3D objects can be included into hierarchy of objects. Every object has parent reference and some classes have list of children also. Therefore transformations of 3D objects are computed taking into account all transformations of their parents. Thus Basic3D class provides functionality for 3D objects transformation control. It’s necessary to call UpdateTransform() function after you set new transformation to the 3D object to ensure that this transformation will be composed of parent transformations and it will affect on children transformations. You always can get result transformation for 3D object by calling of GetResultTransform() function and get parent reference by calling GetParent() function.
Also Basic3D class has Draw() function that send object to the draw queue.

Static objects:

For work with static geometrical object Mobile Dragon 3D API provides Object3D class. This class provides functionality for manipulation and drawing of static geometrical objects. Static geometrical object is object, which has constant geometry computed in world coordinates. It’s useful to present objects, which don’t move or transform during application processing. For example: ground, building, sky, constructions. For loading of static objects use the static scene loading method. See conformable issue for more details.
General features of Object3D class object:
1) Is inherited from Basic3D class.
2) Has own VertexBuffer class object.
This VB contains object’s geometry where vertexes have world coordinates.
3) Has own material, including texture reference.
4) Has parent and children references.
5) Has relative transformation matrix.
Used if we need to apply additional transformation to the object (for example, translate it).

Dynamic object:

For work with geometrical object, which can be dynamic transformed Mobile Dragon 3D API provides Robot3D class. This class provides functionality for manipulation and drawing of dynamic geometrical objects. Dynamic geometrical object is object that has constant geometry computed in local model coordinates, but for result transformation of this object used relative transformation matrix of this objects. Model that is constructed from these dynamic objects has own hierarchy, where all nodes are linked. Every node has relative transformation matrix that transforms this node relatively its parent. Root nodes of this model have transformation matrix that transform their relatively world coordinate system center. Also every node in this model has its own transformation matrix. Thus result transformation matrix of every node is computed as product of parent result transformation matrix (if current node has parent node), node relative transformation matrix and node own transformation matrix. This result matrix transform model in world space.

These dynamic objects are useful to present objects (models) in which some parts (nodes) can be animated by using of transformation matrix. For example: tank model (we can turn tower and gun), helicopter (we can turn propeller) etc. For loading of dynamic objects use the static scene loading method. See conformable issue for more details.
General features of Robot3D class object:
1) Is inherited from Object3D class. Therefore it has all features of this Object3D class.
2) Has relative and own transformation matrices.

Simple animated model:

For work with simple animated model Mobile Dragon 3D API provides set of classes: Actor3D, Actor3DNode, Actor3DAnimation, Actor3DAnimationNode. Classes Actor3D and Actor3DNode are inherited from Basic3D class and present 3D objects. Class Actor3D includes list of Actor3DNode class objects. This class provides functionality for manipulation and drawing of simple animated model. Simple animated model is the animated model whose geometry stored only in the key frames (export from 3D Max) and geometry in the intermediate frames computes by morphing (tweening) method. It’s useful to present objects, which move or transform during application processing and their nodes bend and don’t have clear-cut edges at the same time. For example: people, animals.

In fact Actor3D class is container to store and play animation. Directly animation stored in the Actor3DAnimation class objects. Actor3DAnimation class provides functionality for loading and storing animation for simple animated model. It contains list of key frames exported from 3D Max and list of geometry objects (presented as Actor3DAnimationNode class objects) in these key frames.

Therefore Actor3D and Actor3DAnimation classes are necessary to create and manipulate complete simple animation model.
For loading of simple animated model use the loading of tweening animation model method. See conformable issue for more details.
Loaded animation stored into Actor3DAnimation class objects. To create Actor3D class object and to create complete animated model we need to initialize this object first.
For example:

// Here:
// render – pointer to the Render3D class object.

// Construct new animation objects to store animation.
ObjRef<Actor3DAnimation> actor_animation = Actor3DAnimation::Construct(render);

// Create loader.
MDMLoad mdm_anim;

// Init loader by file name of scene.
mdm_anim.Init(render, "tweening\\tweening");

// Load animation into Actor3DAnimation class object.
mdm_anim.Load(render, actor_animation);

// Create and initialize Actor3D class object.
actor = Actor3D::Construct(render);

// Init Actor3D class object by loaded animation.
actor->Create(actor_animation);

After we have created simple animated model, we can manipulate this model and play animation. Actor3D class allows animation playing with different speed and in different directions (forward or backward). It’s necessary update animation phase in every call of game main loop by calling of Set() function.
For example:

// Here:
// actor_animation – Actor3DAnimation class object.

// Set animated model in the time = 0 and set loop play on.
actor->Set(actor_animation,0,1);

Actor3D class will store all parameters of Set() function from last calling of this function. Thus we can update animation by calling Play() function, which take only animation time increment as parameter.
For example:

// Play animation.
// Play() function will increment current animation time on it’s parametr value.
// Thus calling Play(par) is equal calling:
// Set(<current_animation>,<current_time> + par, <current_loop_flag>);
actor->Play(200);

General features of Actor3D class object:
1) Is inherited from Basic3D class.
2) Has list of Actor3DNode class objects.
3) Has transformation matrix to transform whole model.
4) Has set of function for animation playing.

General features of Actor3DNode class object:
1) Is inherited from Basic3D class.
2) Present node of Actor3D model.
3) Has own material, including texture reference.
4) Is linked to the parent Actor3D class object.
5) May have linked objects.
6) Has relative transformation matrix to transform possible linked object.

General features of Actor3DAnimation class object:
1) Contains list of key frames of animation.
2) Contains list of Actor3DAnimationNode class objects.

General features of Actor3DAnimationNode class object:
1) Contains list of transformation matrices in all key frames.
2) Contains list of VertexBuffer class objects which describes geometry of this node in every key frame.

Joint animated model

For work with joint animated model Mobile Dragon 3D API provides set of classes: Joint3D, Joint3DNode, Joint3DAnimation, Joint3DAnimationNode. Class Joint3D is inherited from Basic3D class, and class Joint3DNode is inherited from Object3D class and presents 3D object. Class Joint3D includes list of Joint3DNode and Robot3D class objects. This class provides functionality for manipulation and drawing of joint animated model. Joint animated model has list of transformation matrix for every animation key frame. It must be constructed from set of details which are presented by geometrical objects (Joint3DNode). It’s possible to construct joint animated model from different sets of details and use only one joint animation for animating whole model. It’s useful to present objects, which move or transform during application processing and their nodes don’t bend and have clear-cut edges. For example: robots which can be constructed from different sets of details and may use one common animation.
In fact Joint3D class is container to store sets of details and play animation. Directly animation stored in the Joint3DAnimation class objects. Joint3DAnimation class provides functionality for loading and storing animation for joint animated model. It contains list of key frames exported from 3D Max and list of Joint3DAnimationNode class objects. In one’s turn Joint3DAnimationNode class contains list of transformation matrices for every node from details collection in every key frame. Thus joint animation is set of transformation matrices for whole animated model in every key frame.
Therefore Joint3D, Joint3DAnimation and Joint3DNode classes are necessary to create and manipulate complete joint animation model.
For loading of joint animated model use the loading of joint animation model method. See conformable issue for more details.
Loaded animation stored into Joint3DAnimation class objects and loaded detail collection stored into the list of Joint3DNode class objects.
To create Joint3D class object and to create complete animated model we need to initialize this object first.
For example:

// Create joint animation object.
joint_animation = Joint3DAnimation::Construct(render);

// Load joint animation.
MDMLoad mdm_joint_anim;
mdm_joint_anim.Init(render, "robo_joint\\joint_animation");
mdm_joint_anim.Load(render,joint_animation);

// Load details collection.
MDMLoad mdm_joint_coll;
mdm_joint_coll.Init(render, "robo_joint\\joint_collection");
mdm_joint_coll.Load(render,joint_collection);

// Create and initialize joint model.
joint_model = Joint3D::Construct(render);

// Attach all nodes from collection.
joint_model->Create(joint_collection);

After we have created joint animated model, we can manipulate this model and play animation. Joint3D class allows animation playing with different speed and in different directions (forward or backward). It’s necessary update animation phase in every call of game main loop by calling of Set() function.
For example:

// Here:
// joint_animation – Joint3DAnimation class object.

// Set animated model in the time = 0 and set loop play on.
joint_model->Set(joint_animation,0,1);

Joint3D class will store all parameters of Set() function from last calling of this function. Thus we can update animation by calling Play() function, which take only animation time increment as parameter.
For example:

General features of Joint3D class object:
1) Is inherited from Basic3D class.
2) Has list of Joint3DNode class objects.
3) Has list of Robot3D class objects which present nodes of model.
4) Has transformation matrix to transform whole model.
5) Has set of function for animation playing.

General features of Joint3DNode class object:
1) Is inherited from Object3D class.
2) Present node of collection of details.
3) Has list of joints which define relative transformation for other details that are linked to the current detail.

General features of Joint3DAnimation class object:
1) Contains list of key frames of animation.
2) Contains list of Joint3DAnimationNode class objects.

General features of Joint3DAnimationNode class object:
1) Contains list of transformation matrices in all key frames for every node of model.