Fly2 Training (NTU) 王銓彰 [email protected] [email protected] 2014 Build 1

Fly2 Training

(NTU)

王銓彰[email protected]

[email protected] 2014 Build 1

■ Setup Working Environment■ The Game Loop■ Hello World■ Basics in Coding Using Fly2■ Viewports & Scenes■ Objects■ Cameras & Lights■ Materials■ Characters■ Movements and Terrain Following■ Sprites■ Write Shaders■ Rendering■ More Functions (Text, Audio)■ File Formats■ Game FX System

Contents

■ Chuan-Chang Wang. (王銓彰 , Kevin)■ BlackSmith Technology (墨匠科技 )■ 壹傳媒動畫多媒體實驗室；昱泉國際；西基電腦動畫；數位內容學院；國家高速電腦與網路中心；台大土木系

■ Game Engine Training (2)■ Game System Analysis ■ Terrain & Game Control■ Character Motion■ Scene Management■ Game Physics■ Game FXs (2)

Introduction Before Doing Anything

■ Development Environment :■ Use Visual Studio 2010 & C/C++■ Create a “Win32 Application” project■ Install APIs

■ Win32 + DirectX 9.0c■ DirectX 9.0c SDK■ OpenAL 1.1 SDK

Development Environment

■ Configuration Properties (DirectX 9.0c as example)■ General

■ Character Set■ Use Multi-Byte Character Set

■ C/C++■ General

■ Additional Include Directories■ Add Fly2 API “Include” folder location

Setup Working Environment (1)

■ Linker■ General

■ Additional Library Directories■ Add OpenAL & DirectX9.0c API library location■ Add Fly2 API “LibWin32” folder location

■ Input■ Additional Dependencies

■ d3d9.lib / d3dx9.lib / OpenAL32.lib / XInput.lib ■ LibFly2DX9W32.lib

Setup Working Environment (2)

■ We always implement an infinitive loop as the game main loop.■ Two types of jobs must be doing in the loop :

■ Check if there are incoming events from system■ Then handle the events and do the necessary jobs

■ Check the timing and do something in regular time step.■ Timers

■ Incoming events■ Keyboard input■ Mouse movement or dragging■ Losing/getting the input focus■ Language input method changed■ Someone insert CD■ Window re-draw flag is dirty■ Gamepad input■ …

Game Loop (1)

■ Timers■ The sub-system to handle timing.■ It must be precise to at least 1ms or less.

■ 30 frames per second = 30 fps = 33.33333 ms■ We need to complete the main game loop for each frame within 33 ms.

■ Typical main game loop :

Game Loop (2)

Check inputs

Game Logics

Computation

Graphics Update

Renderingwithin 33 ms

■ Two types of callbacks■ In regular time step

■ Timer callbacks■ It will be called once every 1/30 or 1/60 second.

■ A game is time-bound.■ We lock the game running in 30 fps or 60 fps.

■ By request from system■ Event callbacks

■ It will be called when happening.■ A game is interactive.■ Game interface to humans.

Callbacks

■ Check “win or lose”■ Check “quit” flag■ Control objects’ movement■ Play character’s motion to next frame■ Play animation to next frame

■ Vertex animation / texture animation / object’s animation / …■ Perform game logic calculation■ Perform NPC AI (finite state machine, steering behavior, path finding, …)■ Perform geometry associated computation (LOD, collision detection, …)■ Play game FXs (particle system, dynamics simulation, …)■ …■ 3D rendering

■ Last step

Typical Jobs Doing in Timer Callback

■ Fly2 is a cross-platform real-time 3D game engine.■ Fly Engine version 2■ Cross-platform

■ Win32■ DirectX 9.0c / DirectX 11 / OpenGL 4.0 / OpenGL/ES 2.0

■ iOS■ Android■ SONY PSP2 Vita

■ Owned by BlackSmith Technology Inc.■ Current version 2.0 Build 1004 (1/6, 2013)

Introduction to Fly2 Game Engine

■ Steps■ Initialize the Fly2■ Create a viewport■ Create a scene■ Create 3D objects

■ A camera■ A light source■ A 3d object loading a teapot object

■ Setup the scene■ Move the camera and light source

■ Bind callbacks for keyboard and mouse■ Control the camera■ Hotkey to quit the program

■ Setup a timer to run the program in 30fps■ Render the scene in timer callback

Hello World – 1st Fly2 Program

Hello World – Main Program

#include “FlyWin32.h”void FyMain(int argc, char **argv){ // create a new world FyStartFlyWin32("Hello Fly2 !", 0, 0, 800, 600, FALSE);

// create a viewport, a 3D scene and the 3D objects …

// set Hotkeys FyDefineHotKey(FY_ESCAPE, QuitGame, FALSE);

// define some mouse functions FyBindMouseFunction(LEFT_MOUSE, InitPivot, PivotCam, NULL, NULL); FyBindMouseFunction(MIDDLE_MOUSE, InitZoom, ZoomCam, NULL, NULL); FyBindMouseFunction(RIGHT_MOUSE, InitMove, MoveCam, NULL, NULL);

// bind a timer, frame rate = 30 fps FyBindTimer(0, 30.0f, GameAI, TRUE);

// invoke the Fly2 and give program control to Fly2 FyInvokeFly(TRUE);}

Main Program name

1st line for Fly2

Hotkey callbacks

Mouse callbacksTimer callbacks

Give the program control to Fly2 and timers are ON

Hello World – Create 3D

void FyMain(int argc, char **argv){ // create a new world ...

// create a viewport vID = FyCreateViewport(0, 0, 800, 600);

// create a scene sID = FyCreateScene(1);

// create 3D objects FnScene scene; scene.ID(sID); nID = scene.CreateObject(OBJECT); cID = scene.CreateObject(CAMERA); lID = scene.CreateObject(LIGHT);

// set Hotkeys // define some mouse functions // bind a timer, frame rate = 30 fps …}

Create a viewport for displaying 3D result

Create a scene object to manage 3D objects

Create 3D objects by a scene

Hello World – Hotkey Callback

/*------------------ quit the program-------------------*/void QuitGame(BYTE code, // the key code BOOL4 value) // TRUE for pressing the hotkey, FALSE for releasing{ if (code == FY_ESCAPE) { if (value) { // press Escape key to quit the Fly2 FyQuitFlyWin32(); } }}

Hello World – Mouse Callback

/*-------------------------- initialize camera’s pivot----------------------------*/void InitPivot(int x, int y) // mouse position{ oldX = x; oldY = y;}

/*------------------ pivot the camera-------------------*/void PivotCam(int x, int y){ FnObject model;

if (x != oldX) { model.ID(cID); model.Rotate(Z_AXIS, (float) (x - oldX), GLOBAL); oldX = x; }

if (y != oldY) { model.ID(cID); model.Rotate(X_AXIS, (float) (y - oldY), GLOBAL); oldY = y; }}

Hello World – Timer Callback

/*---------------------------------------------------------------- timer callback function called by Fly2 System every 1/30 second C.Wang 0308, 2004 -----------------------------------------------------------------*/void GameAI(int skip){ // render the scene FnViewport vp; vp.ID(vID); vp.Render3D(cID, TRUE, TRUE);

// perform double-buffering FySwapBuffers();}

■ No Win32 or DirectX background needed for programmers■ Fly2 is cross-platform

■ Standard ANSI C/C++■ SDK / DDK design■ DDK

■ Platform dependency■ Win32, Linux, iOS, Android, SONY PSP2

■ Graphics APIs■ DirectX 9.0c, DirectX 11■ OpenGL 4.0, OpenGL/ES 2.0 (1.1 included)■ SONY libgxm

■ Multi-threading■ Audio

■ OpenAL (most platforms)■ SONY PSP2 audio

Basics in Using Fly2 (1)

■ Main program entry is■ void FyMain(int argc, char *argv[])

■ Take Win32 platform as an example■ Only one Fly2 header file included in most cases

■ #include "FlyWin32.h“■ But “Fly2.h” is major include file

■ The 1st Fly2 function to call on Win32■ FyStartFlyWin32(caption, ox, oy, width, height, beFullScreen)

■ char *Caption is the window’s caption■ (int ox, int oy) is the window position■ (int width, int height) is the window size

■ In full screen mode, width/height should be supported by hardware driver


■ To render the program in fullscreen mode, set BOOL4 beFullScreen to TRUE, otherwise it runs on window mode.

■ BOOL4 is a boolean variable type in 32-bit.■ The last function to call using Fly2 on Win32

■ FyQuitFlyWin32();


■ ID and Function Class■ Fly2 uses function class to hide the internal data structure of the engine to

programmers to keep the usage of Fly2 clear and well-defined.■ All entities created by Fly2 are returned to users’ program with an ID.■ ID has the naming rule : XXXXXid

■ XXXXX is the name/type of the entity.■ For examples:

■ OBJECTid, SCENEid, GAMEFXid, …■ All entities created by Fly2 are owned by Fly2.■ The game program owns rights to use it.■ To manipulate the entity, use the associated function class.

■ Function class is the same idea as Microsoft COM object.■ Only release member functions to game program

■ FnObject is the function class for OBJECTid.■ FnScene is the function class for SCENEid.

■ Function class with the naming rule : FnXXXXX


■ The usage of ID and function class, taking FnScene as example■ To Create a scene by Fly2 system

■ SCENEid mainSceneID = FyCreateScene();■ And use it by a FnScene function class

■ FnScene scene(mainSceneID);■ Or

■ FnScene scene; ■ scene.ID(mainSceneID);

■ For most of entities have the dedicated host entity to create it :■ For examples :

■ A camera is created by a scene■ FnScene scene;■ Scene.ID(mainSceneID);■ OBJECTid cameraID = scene.CreateObject(CAMERA);■ A camera is a 3D object with camera features, so it uses OBJECTid.


■ To control a camera, we design FnCamera function class to inherit FnObject function class

■ class FnCamera : public FnObject■ Only the host scene creating the camera can delete the camera.

■ scene.DeleteObject(cameraID);■ But some entities are created by Fly2 system directly

■ Scenes■ FyCreateScene() / FyDeleteScene()

■ Viewports■ FyCreateViewport() / FyDeleteViewport()

■ Materials■ FyCreateMaterial() / FyDeleteMaterial()

■ Text objects■ FyCreateText() / FyDeleteText()

■ Audio■ FyCreateAudio() / FyDeleteAudio()


■ You can inherit FnXXXXX to create your own class using in your game.■ For example:

■ class MyCharacter : public FnCharacter■ Then your character is acting as the standard Fly2 character but with

your own data and member function


■ A viewport is a 2D area for a 3D scene to render on.■ A viewport is in the size of (width, height) and located at (ox, oy) which is the

upper-left corner of the viewport.■ The unit for viewport is in pixels■ Viewports are created/deleted by Fly2 system by

Viewports (1)

window

viewport

(ox, oy) width

height

origin

VIEWPORTid vID = FyCreateViewport(ox, oy, width, height);FyDeleteViewport(vID);

■ After success to create the viewport, Fly2 will return the viewport ID to game program. Use FnViewport() to use the viewport.

■ Fly2 supports multiple viewports and is no limits for the number of viewports.■ To render a 3D scene, use FnViewport::Render3D()

■ To render the 3D scene, you need a camera

Viewports (2)

FnViewport vp(vID);

// camID is the camera ID (OBJECTid camID)// 2nd argument is TRUE to clear viewport background// 3rd argument is TRUE to clear z buffervp.Render3D(camID, beClearBackground, beClearZBuffer);

■ To render the depth only, use FnViewport::RenderDepth();■ To render sprite system, use FnViewport::RenderSprites();

■ Use FnViewport::GetSize() to get the viewport size■ Use FnViewport::SetSize() & FnViewport::SetPosition() to position and size the

viewport.

■ The viewport is rendering to backbuffer in default. ■ But Fly2 supports rendering to multiple rendering targets (textures).

■ You can set the rendering target by : ■ FnViewport::SetRenderTarget(int iOne, TEXTUREid tID);

■ If you are using DX9 version of Fly2, maximum number of rendering targets is 4 (for DirectX11 it’s 8)

■ iOne = 0 ~ 3 for DX9 version■ Use FnViewport::SetBackgroundColor(r, g, b, a = 1.0f);

■ (float r, float g, float b, float a) is the background color, (r,g,b,a) is in the range (0.0 – 1.0)

Viewports (3)

■ A 3D scene is a set of 3D objects including■ 3D models■ Light sources■ Cameras■ 3D audios■ Force

■ To create a scene, use FyCreateScene(int max_renderGroup) system function

Scenes (1)

Camera3D Models

Lights

Backdrop

Board

A 3D Scene

SCENEid sID = FyCreateScene(max_renderGroup);FyDeleteScene(sID);

■ You can specify the number of rendering groups defined in the scene.■ The objects in the scene can be assigned a rendering group ID.■ Objects are rendered in order from 0 to (maximum – 1) rendering group ID

■ There are four object lists in each rendering group:■ Opaque object list

■ Rendered at the first.■ Alpha object list (semi-transparent objects)

■ Sorted from back to front before rendered to make sure alpha blending effect us correct.

■ Invisible object list■ The objects are invisible and not rendered.

■ Trash object list■ Objects are temporarily deleted.■ Used for tool development

■ There is a current rendering group in any scene. The objects are assigned to current rendering group when created and not specified any rendering group.

■ Use FnScene::SetCurrentRenderGroup() to assign the ID.

Scenes (2)

■ After success to create a scene, Fly2 will return a SCENEid to the game.■ Then you can use FnScene() function class to access the scene.■ Fly2 can create multiple scenes but only one scene rendered simultaneously.■ Use the scene to create all 3D objects used in the game.

■ FnScene::CreateObject(DWORD type, int renderGroupID = NONE)■ DWORD type can be OBJECT, CAMERA, LIGHT, AUDIO, FORCE, SPRITE■ NONE means no specified which rendering group

■ Fly2 uses z-up as default upward direction. (you can change it)■ Fly2 has the file formats to save the scene in ASCII (.cwn) and in binary (.cw4)■ A scene can create rooms for collision calculation, dynamics simulation, and

space partition. It will be discussed in later chapters.■ A scene can create the particle system and game FX system which will be

discussed in the game FX chapter.■ A scene can create characters by loading from the character files. This will be

discussed in the character chapter.

Scenes (3)

■ The real-time 3D rendering is using double-buffering technique to make the 3D rendering in smooth visually on graphics hardware.

■ There are two frame buffers :■ Front buffer for displaying on screen■ Back buffer for rendering

■ Switch them when all renderings are finished■ We call this process, the swap-buffer!

■ On Fly2, just simply call FySwapBuffers() to do it.

Double Buffering

■ Fly2 supports global paths for searching 3D models, textures, audio, shaders, characters, game FXs and so on.

■ Fly2 will search a common global path, named extra data path, and then search the defined associated path.

■ To set/get the extra data path use :■ void FySetDataPath(char *path);■ char *FyGetDataPath(void);

■ Fly2 searches binary file format before search the ASCII format.■ To set the path :

■ For 3D models : void FySetModelPath(char *path);■ For audio files : void FySetAudioPath(char *path);■ For scene files : void FySetScenePath(char *path);■ For textures : void FySetTexturePath(char *path);■ For shaders: void FySetShaderPath(char *path);■ For system shaders: void FySetSystemShaderPath(*path);■ For characters: void FySetCharacterPath(char *path);■ For game FXs: void FySetGameFXPath(char *path);

Searching Paths for Loading Data

■ Fly2 objects are major 3D data used in games.■ An object has the following features :

■ With geometric data■ Keep an hierarchical relationship with the objects

■ Fly2 Scene Tree■ Can be transformed (translation, scaling, and rotation)■ Can be cloned■ With animation data■ Skin deformation (with skin weights on vertices)■ Visibility culling (viewing check)■ Multiple materials■ Level-of-detail■ Temporarily show and hide■ Movement control on terrains■ Can be modified in-game

Introduction to Fly2 Objects

■ Fly2 uses right-handed coordinate space■ Z axis is the up direction in default.■ Coordinate system

■ Local space (model space)■ All geometric data are in local space.

■ Global space■ The parent object’s local space.

■ World space■ The unique coordinate system used in game.

■ View space (eye space)■ The camera’s local space

■ Screen space■ Physical screen space = viewport (left-handed)■ Logical screen space = camera projection space

Fly2 Coordinate system

x

y

z

■ There are three affine transformations used in Fly2 to control object’s movement in 3D space.

■ Translation■ Rotation■ Scale

■ The transformation in Fly2 is in matrix form.■ Every object in Fly2 keeps one 4x3 matrix to save its transformation in its

parent’s space.■ In Fly2 documents, we call this type of matrix, M12, an 12-element

transformation matrix.

Fly2 Transformations

a0 a1 a2 0a3 a4 a5 0a6 a7 a8 0a9 a10 a11 1

4x3

■ Fly2 use the following matrix multiplication rule :■ v’ = v M0 M1 …

■ The translation matrix

Translation

■ FnObject::Translate(x, y, z, op, beLocalOnly = FALSE)■ Translation vector (float x, float y, float z)■ DWORD op is the matrix multiplication operator

■ op = REPLACE■ Use the translation matrix to replace the current matrix of the

object■ op = LOCAL

■ The translation is in local space.■ op = GLOBAL

■ The translation is in global space.■ BOOL4 beLocalOnly = TRUE means the matrix will not influence the

object’s child objects.

1 0 0 00 1 0 00 0 1 0x y z 1

Rotation with X, Y, or Z Axis■ FnObject::Rotate(axis, angle, op, beLocalOnly = FALSE)

■ DWORD axis is the axis ID of rotation■ axis = X_AXIS, Y_AXIS, or Z_AXIS

■ float angle is the rotation angle in degree unit■ Fly2 uses degree unit in all rotations.

■ DWORD op is the matrix multiplication operator■ op = REPLACE

■ Use the rotation matrix to replace the current matrix of the object■ op = LOCAL

■ The rotation is in local space.■ op = GLOBAL

■ The rotation is in global space.■ BOOL4 beLocalOnly = TRUE means the matrix will not influence its child

objects.

Rotation with Quaternion■ FnObject::Quaternion(w, x, y, z, op, beLocalOnly = FALSE)

■ Fly2 can use a quaternion to perform the rotation with an arbitrary axis.■ float w is the scalar part of the quaternion vector.■ (float x, float y, float z) is the vector part of the quaternion vector.■ DWORD op is the matrix multiplication operator

■ op = REPLACE■ Use the rotation matrix to replace the current matrix of the object

■ op = LOCAL■ The rotation is in local space.

■ op = GLOBAL■ The rotation is in global space.

■ BOOL4 beLocalOnly = TRUE means the matrix will not influence its child objects.

Linear Scale■ FnObject::Scale(sx, sy, sz, op, beLocalOnly = FALSE)

■ (float sx, float sy, float sz) is the scale factor in x, y, z axes.■ DWORD op is the matrix multiplication operator

■ op = REPLACE■ Use the scaling matrix to replace the current matrix of the object




Apply a Transformation Matrix Directly to Fly2 Object■ We can apply a transformation directly to an object.■ The matrix is a M12 matrix.■ FnObject::SetMatrix(M12, op, beLocalOnly = FALSE)

■ float *M12 is the 12-element floating-point array■ DWORD op is the matrix multiplication operator

■ op = REPLACE■ Use the matrix to replace the current matrix of the object




Get the Transformation Matrix from Fly2 Object■ We can get the transformation matrix from an object.■ FnObject::GetMatrix(M, beGlobal = FALSE, beWithObjectLocal = FALSE)

■ float *M is the 12-element or 16-element floating-point array.■ If beGlobal = TRUE, M is the 16-element world matrix of the object.■ If beGlobal = FALSE, M is the 12-element local matrix of the object.■ The game programmer must prepare the matrix before calling this

function.■ BOOL4 beGlobal = TRUE mean the returned matrix is a world matrix,

otherwise it is a local matrix.■ BOOL4 beWithObjectLocal = TRUE means the returned matrix will multiply

the private local matrix which affects the object only.

Fly2 Scene Tree■ Each scene in Fly2 is a scene tree.■ Use FnObject::SetParent(OBJECTid pID) function to control the scene tree.

■ OBJECTid pID is the object ID of the parent object.■ Use OBJECTid FnObject::GetParent() to know the parent object.

■ The function will return the parent’s object ID.■ An object has its host scene which creates the object.■ But you can change the host scene in the game.

■ Use FnObject::ChangeScene(SCENEid newSceneID);■ SCENEid newSceneID is new host scene’s ID.

nID

pID

Object Cloning (1)■ You can clone an object.■ Use FnObject::Clone() to clone an object■ The cloned object should look the same as the original one but can be

accessed independently.■ In default, the cloned object shares the geometric data, materials, textures,

and motion data with its host object.

■ OBJECTid FnObject::Clone(beGeoCopy = FALSE, beMatCopy = FALSE, beTexCopy = FALSE);

■ The function will return the cloned object’s ID.

nID nID1

geometry motion

Clone

Object Cloning (2)■ There are three flags to specify the cloning :

■ BOOL4 beGeoCopy is TRUE to duplicate the geometric data when cloning (not sharing). Then you can modify the geometric data individually. The default is FALSE.

■ BOOL4 beMatCopy is TRUE to duplicate the material data when cloning (not sharing). Then you can modify the material data individually. The default is FALSE.

■ BOOL4 beTexCopy is TRUE to duplicate the texture data when cloning (not sharing). Then you can modify the texture data individually. The default is FALSE.

Object with Motion Data■ The motion data are the animation data prepared by the graphic artists using

3D animation tool.■ The motion data are saved in object’s file in CW3 (.cw3, ASCII format) or CW4

(.cw4, binary format).■ In object cloning, motion data are shared by cloned objects.■ You can play the motion data in-game.

■ “Play motion data” means convert motion data to transformation matrix and apply to the object run-timely.

■ Besides motion, Fly2 can have the other types of “animation” :■ Vertex animation

■ Fly2 has a simple scheme to play object motion.■ If you need a more complicated solution to control the motion playing,

export the object in character format and load the object as a character in Fly2. For more details, please reference the character chapter.

■ The basic unit for playing motion is “frame”.■ Basically we use 30 frames per second for the game. This means 30 frames

= one second. The artists are following 30 fps to prepare the motion data.

Play Object’s Motion■ Use BOOL4 FnObject::PlayFrame(float frame, float *M12 = NULL) to play

object’s motion■ This function will return the playing result.

■ TRUE for success to play the frame. FALSE for failed to play it.■ float frame is the frame that needs to play. If frame is in between the data

of artists prepared. Fly2 will interpolate it.■ You can apply an M12 matrix to get the transformation matrix of the

motion data to be played if you give the matrix. The default is NULL for the matrix. This mean the motion data will apply to the object directly.

■ After the playing, Fly2 will keep on tracking the playing by save the frame as the current frame. You can retrieve it in the game by :

■ float FnObject::GetCurrentFrame();

Object with Vertex Animation■ Fly2 can assign multiple vertex dataset for one model.■ Use this technique to achieve complicated animation data that can be

prepared by the artists but can not be performing in-game.■ To query if the object has multiple vertex dataset :

■ BOOL4 FnObject::CheckVertexAnimation();■ If the object has the multiple vertex dataset, use the following function to play

the animation.■ BOOL4 FnObject::NextVertexArray(int skipFrame, DWORD playMode);■ This function will return TRUE if playing is successful. FALSE means failed to

play. Most of failure is playing to the end.■ int skipFrame is the frame count for this playing to progress. This number

should be a positive number. But if you set skipFrame = 0, Fly2 will reset the playing from the first frame. Vertex animation can not be interpolated.

■ DWORD playMode is the playing mode.■ playMode = LOOP means the playing will loop again if the playing to

the end.■ playMode = ONCE means the playing will end if playing to the last

vertex array.

More Object Functions (1)■ Show/hide the object

■ void FnObject::Show(BOOL4 beShow);■ Set object’s opacity

■ void FnObject::SetOpacity(float o);■ Fly2 will automatically set alpha blending ON/OFF according to the opacity

value.■ For semi-transparent object, the z-buffer-writing rendering option will be

off during the rendering■ Change rendering group

■ void FnObject::ChangeRenderGroup(int rg);■ Set rendering mode

■ void FnObject::SetRenderMode(DWORD mode);■ DWORD mode can be WIREFRAME, POINT_CLOUD or SOLID.

■ Load the model from files■ BOOL4 FnObject::Load(char *fileName, int LOD_level = NONE);■ No file extension is need for the file name, fileName.■ LOD_level is the LOD level assigned to the loaded data

More Object Functions (2)■ Force to set alpha blending ON/OFF

■ void FnObject::SetAlphaFlag(BOOL4 beAlpha, BOOL4 beChangeZBufferWrite = TRUE);

■ BOOL4 beAlpha = alpha blending ON/OFF■ BOOL4 beChangeZBufferWrite is used to specify whether we will update z-

buffer-write render option when alpha flag is changed. TRUE is for changing automatically. Basically when alpha blending is ON, we will turn off the z-buffer-write flag for semi-transparent objects.

■ Set rendering options■ void FnObject::SetRenderOption(DWORD item, DWORD value);■ Some rendering options can be setup with this function■ item = Z_BUFFER

■ Turn ON/OFF z buffer checking■ item = Z_BUFFER_WRITE

■ Turn ON/OFF z buffer update when rendering

More Object Functions (3)■ item = FOG

■ Turn ON/OFF fog (only valid in fixed function rendering pipeline)■ item = SPECULAR

■ Turn ON/OFF the specular lighting (only valid in fixed function rendering pipeline)

■ item = LIGHTING■ Turn ON/OFF the lighting (only valid in fixed function rendering

pipeline)■ item = VIEWING_CHECK

■ Turn ON/OFF the visibility culling flag during the rendering■ item = SOURCE_BLEND_MODE

■ Setup the blending method of front pixels during the alpha blending■ The value can be BLEND_ZERO, BLEND_ONE, BLEND_SRC_COLOR,

BLEND_INV_SRC_COLOR, BLEND_SRC_ALPHA, BLEND_INV_SRC_ALPHA, BLEND_DEST_ALPHA, BLEND_INV_DEST_ALPHA, BLEND_DEST_COLOR, BLEND_INV_DEST_COLOR, or BLEND_SRC_ALPHA_SAT

More Object Functions (4)■ item = DESTINATION_BLEND_MODE

■ Setup the blending method of backbuffer pixels during the alpha blending

■ The value can be BLEND_ZERO, BLEND_ONE, BLEND_SRC_COLOR, BLEND_INV_SRC_COLOR, BLEND_SRC_ALPHA, BLEND_INV_SRC_ALPHA, BLEND_DEST_ALPHA, BLEND_INV_DEST_ALPHA, BLEND_DEST_COLOR, BLEND_INV_DEST_COLOR, or BLEND_SRC_ALPHA_SAT

■ item = CULLING_MODE■ Setup the back-face culling mode■ The value can be CULL_NONE, CULL_CW, or CULL_CCW

■ Load the model from files■ BOOL4 FnObject::Load(char *fileName, int LOD_level = NONE);■ No file extension is need for the file name, fileName.■ Fly2 will search binary file (.cw4) at first and then ASCII file (.cw3) from

extra data path to model data path.

More Object Functions (5)■ int LOD_level is the LOD level assigned to the loaded data. The default

value is no LOD. LOD technology will be discussed in the later chapter.■ The loaded data will be appended to the object.

■ Save the model to a file■ void FnObject::Save(char *fileName);■ char *fileName should specify with file extension (.cw3 or .cw4).

■ Another easy way to show/hide the object :■ void FnObject::Twiddle(BOOL4 beON);

■ This function will keep the object in visible list but no rendering in runtime. It’s designed for show/hide the object frequently.

■ An object can be dropped to trashcan to discard. The objects in scene trashcan will not be accessed and not be saved when saving the scene. We can say that they are “deleted” but not really removed from memory. You can restore objects from the scene trashcan.

■ FnObject::DropToTrashCan(BOOL4 beDrop);■ TRUE for drop to trashcan.■ FALSE for restore from trashcan

Fly2 Camera Objects■ A camera is a 3D object with camera features.■ A camera object is using OBJECTid.■ FnCamera is the camera function class inheriting from FnObject.■ A camera has full functions of an object besides the camera features.■ To create a camera, use :

■ OBJECTid FnScene::CreateObject(CAMERA);

camera

View space

Near plane

Far plane

Fly2 Camera Features (1)■ There are two projection types supported by Fly2 cameras.

■ PERSPECTIVE and ORTHOGONAL■ PERSPECTIVE is the default.■ ORTHOGONAL is used for 2D objects (for example, the sprites).■ Use FnCamera::SetProjectionType(DWORD type) to change the it.

■ For a perspective projection camera, you can change the rate of perspective by change its FOV angle (field-of-view)

■ void FnCamera::SetFOV(float fov)■ float fov is the fov angle in degree unit.

■ You can change the near and far plane distances by■ void FnCamera::SetNearPlane(float d);■ void FnCamera::SetFarPlane(float d);

■ Setup the aspect rate of rendering area :■ void FnCamera::SetAspectRatio(float rate)■ float rate is the ratio of width/height.

■ The default value is 1.333 for NTSC format.

Fly2 Camera Features (2)■ For an orthogonal camera, you can change the scale factor to do the zoom

in/out :■ void FnCamera::SetScaleFactor(float *scaleFactor);

■ float *scaleFactor is a 2-element floating-point array for width and height scaling.

■ This function is only working for an orthogonal projection camera.■ The default rendering screen range is area centered at camera with (-1.0, 1.0)

in range. We define the range in (ox, oy) = (-1.0, -1.0) and size = (2.0, 2.0).■ You can change with

■ void FnCamera::SetScreenRange(float ox, float oy, float w, float h);■ (float ox, float oy) is the left-corner of the rendering area■ (float w, float h) is the size of the rendering area.

(0, 0)-1

-1

1

1

(ox, oy) w

h

Fly2 Camera Features (3)■ There are two transformation matrices from the camera.

■ Viewing matrix and projection matrix■ Use void FnCamera::GetProjectionMatrix(float *P) to get the projection

matrix.■ float *P is a 16-element (4x4) floating-point array to get the matrix

back to game program.■ Use void FnCamera::ReplaceProjectionMatrix(float *P) to replace it.

■ float *P is a 16-element (4x4) floating-point array to set the new matrix

■ Use void FnCamera::GetViewingMatrix(float *V) to get the viewing matrix.■ float *V is a 16-element (4x4)floating-point array to get the matrix back

to game program.

Fly2 Light Objects■ A light is a 3D object with lighting features.■ A light object is using OBJECTid.■ FnLight is the light function class inheriting from FnObject.■ A light has full functions of an object besides the lighting features.■ To create a light, use :

■ OBJECTid FnScene::CreateObject(LIGHT);■ Most of the light functions are designed for fixed function rendering pipeline.

If you are using shaders for material rendering, you need to import the lighting data to shaders and do the lighting in shaders by your shader code.

■ The fixed function rendering pipeline supports only at maximum 8 light sources can be used at the same time but no limits in programmable rendering pipeline.

Fly2 Light Features (1)■ There are three geometric lighting types supported in Fly2 :

■ POINT_LIGHT, PARALLEL_POINT, and SOPT_LIGHT■ These three lighting types are corresponding to most fixed function

rendering pipelines. But they are meaningless in shaders.■ Use FnLight::SetLightType(DWORD type) to change the lighting type with

the above values.■ Set light source color

■ void FnLight::SetColor(float r, float g, float b)■ (float r, float g, float b) is light color.■ For fixed function rendering pipeline the range for RGB value is from

0.0 to 1.0, but for shader, it’s no limit.■ Set light source intensity

■ void FnLight::SetIntensity(float intensity);■ Set lighting range

■ void FnLight::SetRange(float range);

Fly2 Light Features (2)■ Set spot light data

■ void FnLight::SetSpotCone(float innerAngle, float outerAngle, float fallOff);■ float innerAngle is inner angle of cone of the spot light. From here the

lighting is starting to fall off to outer angle.■ float outerAngle is the maximum angle for the spot light area.■ float fallOff is the fall off rate of the soft-lighting area of the spot light.

■ Turn ON/OFF a light source■ void FnLight::TurnLight(BOOL4 beON);

■ Use FnObject’s function of transformation to control lighting position and directions.

Property on 3D Model Surface■ Materials■ Textures■ Shaders

Fly2 Materials■ A material in Fly2 is a data structure to define how the looks and the lighting

behavior of the object will be.■ Material components related with lighting

■ Ambient■ Diffuse■ Specular and shininess■ Emissive

■ Texture slots■ Shaders■ Opacity

■ Only local illumination■ Compatible with fixed function rendering pipeline■ Material data can be passed to shaders

Create a Material■ To create a material use :

■ MATERIALid FyCreateMaterial(float *ambient = NULL, float *diffuse = NULL, float *specular = NULL, float shininess = 100.0f, float *emissive = NULL, float opacity = NONE);

■ ambient, diffuse, specular and emissive all are 3-element floating-point array defined the color components (r, g, b) of the component.

■ Just pass NULL to the components that you are not going to specify. Fly2 will use the default values.

■ When success to define a material, material ID will be returned.■ Use FyDeleteMaterial(MATERIALid mID) to delete a material.■ Use FnMaterial() to manipulate the material.

Textures■ A texture is used to describe model surface color and property.

■ On modern hardware, a texture is a buffer/data array in video memory.■ A texture = an image + addressing + filtering

■ Fragment processing■ A texture can be saved in system memory, video memory or “managed”

memory■ A “managed” memory = a system memory (for editing/restoring) + a video

memory (for rendering)

Material or vertex colors

Base color texture

Texture Issues in Games (1)■ Multiple layers of textures

■ Texture blending■ Cost of multi-texturing = cost of single texturing

■ Texture coordinate system■ Texture coordinate animation■ Texture transformation matrix

■ Texture animation■ “texture slot” in Fly2, introduced later

■ Alpha channel in texture : (r, g, b, a)■ Texture formats

■ Texture size in 2mx2n (not necessary but for optimization)■ Un-compressed format

■ A8R8G8B8■ Compressed (for win32 platform)

■ DirectX DDS format (DirectDraw Surface)■ Floating-point texture data

Texture Issues in Games (2)■ Colorkeying

■ Alpha blending ON + alpha test ON + Z-buffer Write ON■ Mipmap

■ Reduce aliasing or Moire effect when rendering

Texture Slots in Fly2 Material■ Fly2 designs a texture slot system for managing texture animation.■ There is only one texture slot for rendering (current texture)■ In one texture slot, there are textures in layers for multiple texture blending.

slot slot slot

layers

Textures As Material’s Components (1)■ Fly2 uses material function class to manage textures.■ To initialize texture slot system use FnMaterial::InitializeTextures(nSlot,

nLayer);■ int nSlot : number of slots■ int nLayer : number of layers for each slot

■ Use TEXTUREid FnMaterial::LoadTexture(int slot, int layer, char *texName,BOOL4 beColorkey = FALSE, BYTE *keyValue = NULL, int mipMap = 0,

DWORD pool = MANAGED_MEMORY) to load a texture from a file.■ (int slot, int layer) : texture slot and layer■ char *texName : texture file name (no extension). On win32 platform, Fly2

will search a texture in the following file formats: DDS, BMP, JPG, TGA■ BOOL4 beColorkey = TRUE for specifying the texture has a colorkeying

value in BYTE array, keyValue. The loader is no colorkeying in default.■ int mipMap setups the mipmap level. mipMap = 0 is the default value that

means all mipmap levels will be generated when loading the texture.■ DWORD pool specifies the memory pool that texture will be in. There are

three memory pools, MANAGED_MEMORY (default), SYSTEM_MEMORY and VIDEO_MEMORY.

Textures As Material’s Components (2)■ After success to load the texture, a texture ID (in TEXTUREid) is returned

for game programmers to use FnTexture function class to access the texture.

■ Before loading a texture, Fly2 will check the texture whether it was loaded or not by checking the texture name. In default if the texture has been loaded, Fly2 will not load it but share the texture with the other material.

■ To get a texture from material, use TEXTUREid FnMaterial::GetTexture(int slot, int number);

■ To share a texture with the other material, use FnMaterial::AddTexture(slot, layer, TEXTUREid tID) or FnMaterial::AddTexture(sloat, layer, char *texName)

■ To remove a texture from material, use FnMaterial::RemoveTexture(slot, layer, BOOL4 beDelete = TRUE);

■ (int slot, int layer) specifies the texture to be removed.■ BOOL4 beDelete = TRUE (default value) means that Fly2 will check whether

there are materials share the texture after removing the texture form the material. If no materials use the texture, the texture will be deleted.

■ You can use BOOL4 FnMaterial::SetCurrentTexture(int iFrame) to set current texture. Fly2 will return TRUE if success. iFrame is the frame number of new current texture.

Textures As Material’s Components (3)■ Another method to set current texture is BOOL4 FnMaterial::NextTexture(int

skip, DWORD mode). Use this function to do texture animation.■ int skip is the skip frame from last calling of this function. skip is always

larger than 1. But if you set skip to 0, Fly2 will reset the current texture slot to frame 0.

■ DWORD mode is the playing mode : ONCE or LOOP. In LOOP mode, when the texture animation to the last frame, the system will reset to first frame as the next frame. The return value of this function will be always TRUE. If the playing mode is ONCE, the function return value will be FALSE if the system is to the last frame.

■ Use int FnMaterial::GetTextureSlotNumber() to check number of texture slots.

Textures As Rendering Targets■ A texture can be a rendering target of 3D rendering. By assigning textures to a

viewport we can render the 3D results on textures.■ To create a texture as a rendering target, use TEXTUREid

FnMaterial::AddRenderTarget(in slot, int layer, char *texName, DWORD format, int w, int h, BOOL4 beAlpha = FALSE, BOOL4 beZ = FALSE);

■ The function will return a texture ID if success.■ (int slot, int layer) is the texture position in texture slots.■ char *texName is the texture name used by the rendering target texture.■ DWORD format is the texture format. (check next page for details)■ (int w, int h) is the texture size.■ BOOL4 beAlpha indicates the texture is in semi-transparent or not. FALSE is

default.■ BOOL4 beZ = TRUE will create a z buffer with the rendering target. FALSE is

default. Fly2 uses default z buffer for rendering each time. The size of default z buffer is the same as the back buffer. But if the size of rendering target is larger than back buffer, you need a z buffer in larger size. Use this flag to solve this problem.

Texture Format Supported in Fly2■ Fly2 supports the following texture formats :

■ TEXTURE_32 : true color, A8R8G8B8■ TEXTURE_16 : hi-color in 16-bit■ TEXTURE_COMPRESSED_1 : DDS DXT1■ TEXTURE_COMPRESSED_3 : DDS DXT3■ TEXTURE_L16I : luminance in 16-bit integer■ TEXTURE_1F32 : R channel only in 32-bit floating-point■ TEXTURE_FP16 : R16B16G16A16 RGBA color in 16-bit floating-point each■ TEXTURE_2F16 : G & R channels in 16-bit floating-point each■ TEXTURE_64 : R16G16B16A16 RGBA color in 16-bit unsigned integer each■ TEXTURE_32A : true color : A8R8G8B8 (alpha blending ON)■ TEXTURE_2F32 : G & R channels in 32-bit floating-point each■ TEXTURE_COMPRESSD_5 : DDS DXT5■ TEXTURE_FP32 : R32B32G32A32 RGBA color in 32-bit floating-point each

Shaders As Material’s Components■ You can assign a shader to a material. Fly2 will use this shader to render the

objects that use this material.■ For more details about shaders, please reference the shader chapter.■ SHADERid FnMaterial::AddShaderEffect(char *cwsFile, char *techName =

NULL);■ char *cwsFile is the file name of shader description file with .cws extension■ char *techName is the shader effect name. If you use nVidia Cg, DX11

HLSL, or OpenGL GLSL, please set this argument to NULL.■ This function will return the shader ID (SHADERId).■ You can use FnShader function class to access the shader.

■ SHADERid FnMaterial::ReplaceShaderEffect(SHADERid newShader, BOOL4 beD = TRUE);

■ Use this function to change the shader used by the material.■ SHADERid newShader is the new shader ID.■ BOOL4 beD = TRUE for deleting the shader being replaced.

More Material Functions (1)■ Get/Set material name :

■ char *FnMaterial::GetName();■ void FnMaterial::SetName(char *name);

■ Get/Set ambient component value :■ float *FnMaterial::GetAmbient();■ void FnMaterial::SetAmbient(float *amb);

■ Get/Set diffuse component value :■ float *FnMaterial::GetDiffuse();■ void FnMaterial::SetDiffuse(float *dif);

■ Get/Set specular component value :■ float *FnMaterial::GetSpecular();■ void FnMaterial::SetSpecular(float *spe);

■ Get/Set specular shininess value■ float FnMaterial::GetShininess();■ void FnMaterial::SetShininess(float s);

More Material Functions (2)■ Get/Set emissive component value :

■ float *FnMaterial::GetEmissive();■ void FnMaterial::SetEmissive(float *emi);

■ Clone a material :■ MATERIALid FnMaterial::Clone(BOOL4 beTexCopy = FALSE);■ BOOL4 beTexCopy = TRUE for duplicating the textures when cloning the

material. FALSE is the default.

Texture Functions (1)■ We will add more FnTexture function class member functions very soon.■ Now we have the following functions

■ Get texture size :■ void FnTexture::GetTextureSize(int *w, int *h);■ (int *w, int *h) is the returned result.

■ Set texture addressing mode■ void FnTexture::SetAddressMode(DWORD mode);■ DWORD mode can be WRAP_TEXTURE, MIRROR_TEXTURE,

CLAMP_TEXTURE, MIRROR_ONCE_TEXTURE or BORDER_TEXTURE■ Set texture filter

■ void FnTexture::SetFilterType(DWORD type);■ DWORD type can be FILTER_NONE, FILTER_POINT, FILTER_LINEAR,

FILTER_ANSOTROPIC, FILER_FLAT_CUBIC, FILTER_GAUSSIAN_CUBIC■ Save a texture to a file

■ BOOL4 Save(char *texName, DWORD fileFormat)■ This texture will be saved to the current texture folder.

Texture Functions (2)■ char *texName is the texture file name.■ DWORD format is the file format in FILE_BMP, FILE_JPG, FILE_PNG

or FILE_DDS.

Fly2 Characters■ A character in Fly2 is a set of objects in hierarchical structure and can be

controlled by playing its motion data to perform its behavior in game.■ A character is a skeleton with some skins and

attachments. All components of a character are objects. Programmers can control each object by FnObject function class.

■ A character is loaded via FnScene()::LoadCharacter() from an ASCII character description file (.cwa). A character ID is returned if the loading is successful.

■ Use FnCharacter() function class to access the character.

■ A skeleton can have geometric data.

■ A character in Fly2 uses the root-base scheme. This is based on a biped character concept. Fly2 adds a dummy object (base object of the character, the blue box of the picture above) as the parent object of whole skeleton to control the character’s movement.

The Skeleton■ A skeleton is a tree of objects to construct the “bones” of the character.■ A bone is an object to construct the skeleton.

■ A bone can have geometric data to construct a rigid character (ie., a car)■ Each bone of the character has the motion data.■ Fly2 defines the motion data in poses. (raw poses)

■ For example, the idle pose, walk pose, attack pose, …■ Fly2 uses frame 0 as the natural pose (or reset pose, T pose).

■ The natural pose is matching to the skin geometry.

Base

Root(groin)

Base

Fly2 Skeleton Functions■ Get number of bones and object ID of each bone :

■ int FnCharacter::GetBoneNumber();■ This function will return the bone number. Use this number to run a loop

to get the object ID of each bone by calling■ char *FnCharacter::FindBoneName(int i);■ OBJECTid FnCharacter::GetBoneObject(char *name);

■ Get number of skins and object ID of each skin :■ int FnCharacter::GetSkinNumber();■ This function will return the number of skin. Use this number to run a loop

to get all skins’ object ID.■ OBJECTid FnCharacter::GetSkin(int i);

■ Get number of attachments and object ID of each attachment :■ int FnCharacter::GetAttachmentNumber();■ This function will return the number of attachment. Use this number to

run a loop to get all attachments’ object ID.■ OBJECTid FnCharacter::GetAttachment(int i);

Root-base Scheme■ A character has several root objects that can move individually.■ Except the root objects, the other bones will join together.■ We design a single object, the base object, to be the parents of all roots.■ The skeleton will perform the animation created by artists or procedurally.■ The base object will do the movement controls of the character.■ The easiest way to control the character :

■ Call FnCharacter::Play() to play character animation.■ Call FnCharacter::MoveForward() to move the character.

■ Use OBJECTid FnCharacter::GetBaseObject() to get object ID of the base.

The Body and the Bones■ A body is a set of bones.■ We can assign the motion to play for each body.■ Bodies are constructed in a hierarchical form. (body tree)■ Body functions :

■ Get number of bodies :■ int FnCharacter::GetBodyNumber();

■ Create a body■ int FnCharacter::CreateBody(char *bodyName, char *boneName);■ This function returns an integer as a reference number for the body.■ char *bodyName is the name of body.■ char *boneName is the first bone of the body.

Fly2 Action System■ Fly2 action system is a system to manage the playing of the character motion.■ There are four types of actions supported now :

■ SIMPLE_ACTION■ Play a pose

■ CROSS_BLEND_ACTION■ Play two poses with a zone of overlapping

■ FULL_BLEND_ACTION■ Play two poses as layers with weight for each other

■ CONNECTION_ACTION■ Play two poses with a length of gap between these poses

fNode

rNode

len

fNoderNode

len

Create an Action (1)■ An action has an action ID and can be accessed with FnAction() .■ Create a simple action

■ ACTIONid FnCharacter::CreateAction(char *bodyName, char *actionName, char *poseName, BOOL4 beDelete = TRUE);

■ This function returns an action ID if success.■ char *bodyName is the body using this action. Set NULL for first root body.■ char *actionName is the name of the action.■ char *poseName is the pose that will be playing by this action.■ BOOL4 beDelete = TRUE will delete the action that uses the same action

name. TRUE is the default value.■ Create a cross-fade action

■ ACTIONid FnCharacter::CreateCrossBlendAction(char *bodyName, char *actionName, char *frontPoseName, char *rearPoseName, float length, BOOL4 beDelete = TRUE);

■ This function returns an action ID if success.■ char *bodyName is the body using this action. Set NULL for first root body.

Create an Action (2)■ char *actionName is the name of the action.■ char *frontPoseName is the front pose.■ char *rearPoseName is the rear pose.■ float length is the length of overlapping.■ BOOL4 beDelete = TRUE will delete the action that uses the same action

name. TRUE is the default value.■ Create a connected pose action

■ ACTIONid FnCharacter::CreateConnectAction(char *bodyName, char *actionName, char *frontPoseName, char *rearPoseName, int length, BOOL4 beDelete = TRUE);

■ This function returns an action ID if success.■ char *bodyName is the body using this action. Set NULL for first root body.■ char *actionName is the name of the action.■ char *frontPoseName is the front pose.■ char *rearPoseName is the rear pose.■ float length is the length of the time gap.

Create an Action (3)■ BOOL4 beDelete = TRUE will delete the action that uses the same action

name. TRUE is the default value.■ Create a full blended action

■ ACTIONid FnCharacter::CreateFullBlendAction(char *bodyName, char *actionName, char *poseName0, char *poseName1, float w0, float w1, BOOL4 beDelete = TRUE);

■ This function returns an action ID if success.■ char *bodyName is the body using this action. Set NULL for first root body.■ char *actionName is the name of the action.■ char *poseName0 is the first pose.■ char *poseName1 is the second pose.■ float w0 is the blending weight of first pose.■ float w1 is the blending weight of second pose.■ BOOL4 beDelete = TRUE will delete the action that uses the same action

name. TRUE is the default value.■ Delete an action.

■ void FnCharacter::DeleteAction(ACTIONid actionID);

Play an Action (1)■ Fly2 designs multiple channels for the body to play motions.■ But most of the cases only one channel is enough (channel 0).■ We can assign current actions for each body to play :

■ ACTIONid FnCharacter::SetCurrentAction(char *bodyName, int channel, ACTIONid actionID, float length = 0.0f, BOOL4 bePlay = TRUE);

■ This function will return the action ID that has been replaced.■ char *bodyName is the body name. Set NULL for the first root body.■ int channel is the channel ID.■ ACTIONid actionID is the action to play.■ float length is the blending length from last current action.■ BOOL4 bePlay = TRUE means Fly2 will play the action immediately.

TRUE is the default value.■ Use ACTIONid FnCharacter::GetCurrentAction(char *bodyName, int channel =

0) to get current action of the body.

Play an Action (2)■ Use FnCharacater::Play() to play actions.

■ BOOL4 FnCharacter::Play(DWORD mode, float frame, BOOL4 beBase = TRUE, BOOL4 beSkinDeform = FALSE, BOOL4 beCollide = FALSE);

■ This function returns TRUE for playing successfully. Otherwise it returns FALSE.

■ DWORD mode has three selections :■ START

■ Start to play the actions. Next argument, frame, is the exact frame position to start.

■ ONCE■ Play the action once and then stop.

■ LOOP■ Play the action in loop.

■ float frame■ If mode = START, frame is the exact frame position to start.■ Otherwise, frame is the number of skip frames from last play.

Play an Action (3)■ BOOL4 beBase = TRUE to play base object’s animation. TRUE is default.■ BOOL4 beSkinDeform = TRUE will make skin deformation just right

after playing the actions. FALSE is the default. If this value is FALSE, skin deformation will be performed when this character is in rendering.

■ BOOL4 beCollide = TRUE will check collision detection with the other objects. FALSE is the default value.

More Character Functions (1)■ Clone a character

■ CHARACTERid FnCharacter::Clone(BOOL4 beGeoCopy = FALSE, BOOL4 beMatCopy = FALSE, BOOL4 beTexCopy = FALSE);

■ The function will return the cloned character’s ID.■ There are three flags to specify the cloning :

■ BOOL4 beGeoCopy is TRUE to duplicate the geometric data when cloning (not sharing). Then you can modify the geometric data individually. The default is FALSE.

■ BOOL4 beMatCopy is TRUE to duplicate the material data when cloning (not sharing). Then you can modify the material data individually. The default is FALSE.

■ BOOL4 beTexCopy is TRUE to duplicate the texture data when cloning (not sharing). Then you can modify the texture data individually. The default is FALSE.

■ Change scene■ We can move the character to another scene.■ void FnCharacter::ChangeScene(SCENEid newSceneID);

More Character Functions (2)■ Define a pose for whole character

■ int FnCharacter::DefinePose(const char *poseName, int startFrame, int endFrame, int cutFrame, char *motionDatabaseName = NULL);

■ The function will return an integer for reference.■ const char *poseName is the pose name.■ int startFrame is starting frame of the pose.■ int endFrame is the ending frame of the pose.■ int cutFrame is the cut frame when using motion blending. This number is

not using any more.■ char *motionDatabaseName is the motion database name and set NULL as

default. The default motion database is the one coming with the character file.

■ Define a pose for a body■ void FnCharacter::DefineBodyPose(const char *bodyName, const char

*poseName, int startFrame, int endFrame, int cutFrame, char *motionDatabaseName = NULL);

More Character Functions (3)■ char *bodyName is the body name. Set NULL for the first root body.■ const char *poseName is the pose name.■ int startFrame is starting frame of the pose.■ int endFrame is the ending frame of the pose.■ int cutFrame is the cut frame when using motion blending. This number is

not using any more.■ char *motionDatabaseName is the motion database name and set NULL as

default. The default motion database is the one coming with the character file.

■ Delete a body pose■ BOOL4 FnCharacter::DeleteBodyPose(const char *bodyName, const char

*poseName);

Movements■ The transformation is the term used for 3D computer graphics but not friendly

to control an object’s movement for the games.■ Movement :

■ Move forward / move right / Move up■ Turn right / turn left / tilt

■ We need to define the orientation of an object :■ Object position■ Its facing direction■ Its up direction

Move forward

Move up

Move right

Turn right / left

Facing Direction and Up Direction■ Facing direction is used for moving forward■ The default facing direction of a Fly2 object is local “-y” axis.

■ Except that the camera faces to local “-z” axis■ The default up direction of a Fly2 object is local “z” axis.

■ Except that the camera uses local “y” axis as up direction.■ The character’s orientation is the same as the object.

Move forward

Move up

Move right

Turn right / left

Position Functions (1)■ For objects

■ Use FnObject::SetPosition(float *pos, BOOL4 beWorld = TRUE) to set object’s position.

■ float *pos is the position.■ BOOL4 beWorld = TRUE means the position is in world space. FALSE

means in local space. TRUE is the default value.■ Use FnObject::GetPosition(float *pos, BOOL4 beWorld = TRUE) to get

object’s position.■ float *pos is the returned object’s position■ BOOL4 beWorld = TRUE means to get the position in world space.

FALSE is for local space. TRUE is the default value.■ For characters

■ Use FnCharacter::SetPosition(float *pos, BOOL4 beWorld = TRUE) to set character’s position.

■ float *pos is the position.■ BOOL4 beWorld = TRUE means the position is in world space. FALSE

means in local space. TRUE is the default value.

Position Functions (2)■ Use FnCharacter::GetPosition(float *pos, BOOL4 beWorld = TRUE) to get

character’s position.■ float *pos is the returned character’s position■ BOOL4 beWorld = TRUE means to get the position in world space.

FALSE is for local space. TRUE is the default value.

Orientation Functions (1)■ For objects

■ Use FnObject::SetDirection(float *fDIr, float *uDir, BOOL4 beWorld = TRUE) to set object’s facing and up directions.

■ float *fDir is the facing direction.■ float *uDir is the up direction.■ BOOL4 beWorld = TRUE means the directions are in world space. FALSE

means in local space. TRUE is the default value.■ Facing direction doesn’t need to perfectly perpendicular.■ With this function, Fly2 will set the facing direction at first and then set the

up direction. If the programmers need to set the up direction first and then the facing direction. Please call this function twice in the following order :

■ FnObject::SetDirection(NULL, uDir);■ FnObject::SetDirection(fDir, NULL);

Orientation Functions (2)■ Use FnObject::GetDirection(float *fDir, float *uDir, BOOL4 beWorld =

TRUE) to get object’s facing and up directions.■ float *fDir is the returned object’s facing direction■ float *uDir is the returned object’s up direction■ BOOL4 beWorld = TRUE means to get the directions in world space.

FALSE is for local space. TRUE is the default value.■ For characters

■ Use FnCharacter::SetDirection(float *fDir, float *uDir, , BOOL4 beWorld = TRUE) to set character’s facing and up directions.

■ float *fDir is the facing direction.■ float *uDir is the up direction.■ BOOL4 beWorld = TRUE means the directions are in world space. FALSE

means in local space. TRUE is the default value.

Orientation Functions (3)■ Use FnCharacter::GetDirection(float *fDir, float *uDir, BOOL4 beWorld =

TRUE) to get character’s facing and up directions.■ float *fDir is the returned character’s facing direction■ float *uDir is the returned character’s up direction■ BOOL4 beWorld = TRUE means to get the directions in world space.

FALSE is for local space. TRUE is the default value.

Rooms■ A scene can create rooms to group objects together for the following purposes

:■ Collision detection■ Terrain following■ Implement BSP tree (in developing)

■ Use ROOMid FnScene::CreateRoom(type, numObject) to create a room■ DWORD type is the room type. Currently Fly2 has two types of rooms :

SIMPLE_ROOM and BSP_ROOM. BSP_ROOM is in development for binary space partition.

■ int numObject is the maximum number of objects in the room.■ When success to create the room, a room ID (ROOMid) is returned.■ Use FnRoom function class to access the room

■ To delete a room, use void FnScene::DeleteRoom(ROOMid roomID).■ To add an object to the room, use FnRoom::AddObject(OBJECTid oID);■ To remove an object from a room, use FnRoom::RemoveObject(OBJECTid oID);

Terrain Following (1)■ A terrain is a place for 3D objects or characters to walk on.■ Add all terrain objects into a room.■ Use this room as the “terrain room” for the characters or the objects to walk

on.■ Steps : (for an object)

■ Create a room■ Insert all terrains to the room■ Call FnObject::SetTerrainRoom() to assign the object walking on the

terrains in the room.■ Put the object on terrain with FnObject::PutOnTerrain();

■ void FnObject::SetTerrainRoom(ROOMid rID, float heightLimit, float angle, float frontDIstance, float backDistance);

■ ROOMid rID is the room ID with all terrains.■ float heightLimit is the relative height limit that the object can move

on.■ float angle is the probe angle for the object to check terrain.■ float frontDIstance is the probe length in the front of the object.

Terrain Following (2)■ float backDistance is the probe length in the back of the object.■ These two distances are calculated from the local center of the objects.

■ BOOL4 FnObject::PutOnTerrain(float *pos = NULL, float height = 100.0f, BOOL4 be3D);

■ This function will return the result to put the object on terrains. TRUE for success.

■ float *pos is the position that programmers want to start to put on terrain. The position should be above the terrain.

■ float height is the height of the object above the terrain before putting on terrain.

■ BOOL4 be3D specifies the object is on terrain in 2D or 3D form.

Terrain Following (3D)

offset

Terrain Following (2D)

offset

Terrain Following (3)■ For a character, the steps are the same:

■ void FnCharacter::SetTerrainRoom(ROOMid rID, float heightLimit, float angle, float frontDIstance, float backDistance);

■ BOOL4 FnCharacter::PutOnTerrain(float *pos, float height, BOOL4 be3D);

■ To make an object move on terrain :■ Move forward :

■ int FnObject::MoveForward(float dist, BOOL4 beTF = FALSE, BOOL4 be3D = FALSE, float offset = 0.0f, BOOL4 beCollide = FALSE);

■ This function returns the move result in■ WALK : success to move■ BOUNDARY : hit the terrain boundary and fail to move■ BLOCK : hit another object and blocked■ DO_NOTHING : something wrong

■ float dist is the moving distance.■ BOOL4 beTF = TRUE for terrain following, FALSE is default.

Terrain Following (3)■ BOOL4 be3D indicates it’s 2D or 3D terrain following. FALSE (2D) is the

default.■ float offset is the height offset from the terrain if the object is doing

terrain following. FALSE is the default.■ BOOL4 beCollide indicates the object will perform collision detection

during the moving. This flag works only when the object is in a collision room. FALSE is the default.

■ Move right :■ int FnObject::MoveRight(float dist, BOOL4 beTF = FALSE, BOOL4 be3D =

FALSE, float offset = 0.0f, BOOL4 beCollide = FALSE);■ Same arguments as the move forward except moving to the right.

■ Move up :■ int FnObject::MoveUp(float dist, BOOL4 beCollide = FALSE);■ This function returns the move result in

■ WALK : success to move■ BLOCK : hit another object and blocked■ DO_NOTHING : something wrong

Terrain Following (4)■ float dist is the moving distance.■ BOOL4 beCollide indicates the object will perform collision detection

during the moving. This flag works only when the object is in a collision room. FALSE is the default.

■ Turn the object to its right side■ int FnObject::TurnRight(float angle);■ This function returns the move result in

■ WALK : success to move■ DO_NOTHING : something wrong

■ float angle is the turning angle in degree. Given negative value to turn the object to the left side.

■ For a character to move, the methods are the same■ FnCharacter::MoveForward();■ FnCharacter::MoveRight();■ FnCharacter::MoveUp();■ FnCharacter::TurnRight();

A Special Issue about a Character’s Movement■ Usually we ask artists to create characters’ animation with no movements.

And use move forward command to move the character.■ But with this method, the character will not move on terrain without slipping.■ We can ask artists to create no slipping movement of the characters.■ And use FnCharacter::MakeBaseMove() function to transfer the root’s

movements to the base object (usually in the preprocessing using the tool).■ Then we don’t need to move the character. Just turn on the base object’s

animation flag to on when calling FnCharacter::Play().■ In default, Fly2 will move the character using artists’ setting in 3D animation

tool. But you can scale the movement with FnCharacter::SetTerrainParameters(sF, sR, sU);

■ (floa sF, float sR, float sU) is the scale factors in facing, right, and up directions.

■ With this method, you can call FnCharacter::QueryLastMoveResult(int *f, int *r, int *u) to check the movement result.

Sprites (1)■ A sprite is a primitive designed for 2D user interface.■ A sprite can display a set of image sequence to perform as a character’s

animation.■ In Fly2, a sprite object is implemented by inheriting from an object except that

:■ They are using a built-in orthogonal camera for sprite rendering.■ The sprites have an origin located in the left-bottom corner of the

viewport.■ The size of the sprite world (sprite scene) is defined with

FnScene::SetSpriteWorldSize(int w, int h, int z = 1000);■ (int w, int h) is the size of sprite space. We suggest that the size should

be the same as the one of viewport for sprite rendering.■ int z is the maximum z value. The default value is 1000.

■ The sprites should be rendered using FnViewport::RenderSprites(SCENEid sID, BOOL4 beClear = TRUE. BOOL4 beClearZ = TRUE);

■ SCENEid sID is the scene that creates the sprites.■ BOOL4 beClear = TRUE indicates to clear the viewport background

before rendering the sprites. TRUE is the default.

Sprites (2)■ BOOL4 beClearZ = TRUE indicates to clear the z buffer before rendering

the sprites. TRUE is the default.■ We will not sort sprites before rendering (most of 2D game engine do sorting).

■ We utilize the hardware z buffering to make the sprite rendering in correct order. Therefore the sprite position is defined in 3D (x, y, z);

■ Semi-transparent sprites will be sorted from far to near position to the camera.

■ A sprite is created by a scene with■ OBJECTid FnScene::CreateObject(SPRITE);

■ This function will return an object ID for the sprite. (OBJECTid)■ A sprite uses FnSprite function class to access a sprite object. FnSprite

inherits from FnObject. We can treat a sprite as an object with sprite features.

Sprite World

A sprite

Sprite Functions (1)■ Set sprite position

■ void FnSprite::SetPosition(int ox, int oy, int z);■ (int ox, int oy) is the position of the sprite.■ int z is the layer of the sprite.

■ Set sprite size■ void FnSprite::SetSize(int w, int h);■ (int w, int h) is the sprite size.

■ Set sprite background color■ void FnSprite::SetColor(float *rgbColor);■ float *rgbColor is the background color of the sprite in (r, g, b).

■ Set the image displaying on the sprite :■ TEXTUREid FnSprite::SetImage(char *texName, int nTex = 0, float *uv =

NULL, BOOL4 beColorkey = FALSE, BYTE *keyValue = NULL, DWORD poolType = MANAGED_MEMORY, BOOL4 beAlpha = FALSE, DWORD filter = FILETER_NONE, BOOL4 beInvUV = FALSE);

Sprite Functions (2)■ char *texName : texture file name or file header (no extension).■ int nTex is the number of textures. If nTex = 0, texName is the full file

name of the texture and only one image on the sprite. If nTex is larger than 0, there are textures in sequence on the sprite (texture animation). The textures are in name of “texName0000, texName0001, …)

■ BOOL4 beColorkey = TRUE for specifying the texture has a colorkeying value in BYTE array, keyValue. The loader is no color-keying in default.

■ DWORD poolType specifies the memory pool that textures will be in. There are three memory pools, MANAGED_MEMORY (default), SYSTEM_MEMORY and VIDEO_MEMORY.

■ BOOL4 beAlpha indicates the sprite is in semi-transparent or not. FALSE is default.

■ DWORD filter can be FILTER_NONE, FILTER_POINT, FILTER_LINEAR, FILTER_ANSOTROPIC, FILER_FLAT_CUBIC, FILTER_GAUSSIAN_CUBIC. FILTER_NONE is the default value.

Shader■ Fly2 is designed to use programmable rendering pipeline with multi-pass

rendering management.■ Fly2 supports DX9 HLSL, DX11 HLSL, nVidia cg, OpenGL GLSL on different

platforms.■ To make it easier to communicate between Fly2 with shader programs, Fly2

has an ASCII shader description file with file extension .cws to control multi-pass shader effect and to pass the engine data to shader code.

Fly2 Game Engine

Shader Descriptor

.cwsShader Code

Shader Description (.cws) Structure for HLSL Shader

Effect PhongTex1.fx

VertexType position normal texture 1 2

Technique 3 0 PhongTex1 1 colorMap 0 0 1 PhongTex1Alpha 1 colorMap 0 0

Constant 14 0 E Matrix LocalToScreen mWVP 1 E Matrix Global mWorld 2 E Light Position MainLight mainLightPosition 3 E Light Color MainLight mainLightColor 4 … … 13 E BeTexture 0 beColormap

HLSL in D3D effect file (.fx)

Vertex type used in shader

Technique declaration

Constants definition for shaders

Shader Technique Declaration in CWS File

Technique 2

0 PhongTex1 1 colorMap C 0 1 Phongtex2 2 colorMap 0 1

TechniqueID

Technique nameIn .fx file

Texture layersUsed in the technique

Texture name in the shader

TechniqueSlot

C = current texture

Texture layer

Shader Constants in CWS File

Constant 4

0 E Matrix LocalToScreen mWVP 1 E Matrix Global mWorld 2 E Light Position MainLight mainLightPosition 3 E Light Color MainLight mainLightColor

ConstantID

ShaderType

ConstantCategory

ConstantType

ObjectName

InFly2

VariableName

InShader

Use HLSL Effect Shader in Fly2■ In the code, call FnMaterial::AddShaderEffect(char *cwsFileName);■ In the material definition in the CW3 model file :

Material 2

ShaderEffect Phong_tex1 Phong Texture box Ambient 0.3 0.3 0.3 … ShaderEffect Phong_texNo Phong2 Ambient 0.3 0.4 0.3 …

KeywordTo

UseShader

CWSFile

Name

Techniqueused

Multi-pass Rendering in Fly2■ Fly2 supports hybrid rendering pipeline if the hardware platform supports

both fixed rendering pipeline and programmable rendering pipeline.■ On Win32 + DX9 and Win32 + OpenGL, Fly2 supports hybrid rendering.■ On Win32 + DX11, Fly2 supports programmable rendering only.■ On Linux, Fly2 supports hybrid rendering.■ On iOS, Fly2 supports programmable rendering only.■ On Android, Fly2 supports programmable rendering only.■ On SONY PSP2, Fly2 supports programmable rendering only.

■ To do multi-pass rendering with Fly2, you need■ Create multiple rendering targets

■ Output for rendering■ Input for next rendering

■ Set rendering targets to a viewport

Rendering Functions in Fly2■ For different rendering purpose, FnViewport supports several rendering

functions :■ General 3D rendering :

■ FnViewport::Render3D(OBJECTid cameraID, BOOL4 beC, BOOL4 beCZ);■ Sprite rendering :

■ FnViewport::RenderSprites(SCENEid sceneID, BOOL4 beC, BOOL4 beCZ);

■ If you want to use one specific shader to render your data :■ FnShader::Render(VIEWPORTid vID, OBJECT cameraID, int numObj,

OBJECTid *allObj, BOOL4 beC, BOOL4 beCZ, MATERIALid inputMaterialID = FAILED_ID);

■ Render Textures to textures■ FnShader::Rdner(VIEWPOTRid vID, MATERIALid inputMaterialID);

Fly2 Geometric Data (1)■ You can create geometric elements in Fly2 :

■ Lines■ Indexed triangles■ NURBS curves and surfaces■ Billboard■ Label

■ Label is an integer to mark the geometric element in FnObject.■ When successfully creating a geometric element, FnObject will return a

geometry ID (GEOMETRYid). You can use this id with FnGeometry / FnLine / FnTriangle to access it. (We will add FnBillboard in the near future)

■ Each geometric element uses one material.■ If you load a model file with multiple materials, Fly2 will sort the geometric

data into several geometric elements and each element has one material.■ You can call FnObject::GetGeometryNumber() to know the number of

geometric element.■ Then write a loop to use GEOMETRYid FnObject::GetGeometryID(int i) to

get all geometric element.

Fly2 Geometric Data (2)■ Or prepare an array (in GEOMETRYid type) to get the all geometries.

■ int FnObject::GetGeometries(GEOMETRYid *geo, int length_of_geo);■ This function returns the number of geometries in geo array.■ GEOMETRYid *geo is the geometry id array to get the result.■ int length_of_geo is the length of geo array.

■ Call void FnObject::RemoveAllGeometries() to delete all geometric data.■ Call BOOL4 FnObject::RemoveGeometry(GEOMETRYid gID) to remove one

geometric element.

Fly2 Lines■ GEOMETRYid FnObject::Lines(int type, MATERIALid mID, float *v, int nV,

BOOL4 beUpdate = TRUE, BOOL4 *beVC = FALSE)■ This function returns the geometry id of the lines.■ int type is type of lines: LINE_SEGMENTS, OPEN_POLYLINE, or

CLOSE_POLYLINE

■ MATERIALid mID is the material id for the lines■ float *v is the vertex data.■ int nV is the number of vertices.■ BOOL4 beUpdate = TRUE means this function will update object’s

bounding box after generating the lines. TRUE is the default.■ BOOL4 beVC = TRUE means the vertex with vertex color in (r, g, b). FALSE is

the default.

LINE_SEGMENTS OPEN_POLYLINE CLOSE_POLYLINE

Fly2 Indexed Triangles (1)■ GEOMETRYid FnObject::Triangles(int vType, MATERIALid mID, int nVA, int nV,

int nTex, int *texLen, float *v, int nT, int *triTable, int tangent = 0, BOOL4 beUpdate = TRUE, BOOL4 *beRV = NULL)

■ This function returns the geometry id of the triangles.■ int vType is type of vertices: XYZ, XYZ_RGB, XYZ_NORM

■ XYZ is the vertex with vertex position (x, y, z) only■ XYZ_RGB is the vertex with vertex position (x, y, z) and vertex color (r,

g, b)■ XYZ_NORM is the vertex with vertex position (x, y, z) and vertex

normal (nx, ny, nz)■ MATERIALid mID is the material id for the lines■ int nVA is the number of vertex arrays. nVA > 1 means the object has

vertex animation.■ int nV is the number of vertices in each vertex array■ int nTex is number of texture coordinates for each vertex.■ int *texLen is the array saving the vector length for each texture

coordinate.■ float *v is the vertex data.

Fly2 Indexed Triangles (2)■ int nT is number of triangles.■ int *triTable is the index table of triangles. Its length is nT*3.■ int tangent is a number to indicate if there’re tangent and bi-normal data

with the vertex. tangent = 0 is no tangent and bi-normal vectors. tangent = 1 is tangent vector only. tangent = 2 is tangent and bi-normal vectors. Tangent and bi-normal vectors are used for tangent-based normal map rendering.

■ BOOL4 beUpdate = TRUE means this function will update object’s bounding box after generating the triangles. TRUE is the default.

■ BOOL4 *beRV is the boolean array saving if we need to reverse the v-component for texture coordinates. NULL is the default.

■ Fly2 uses right-handed coordinate system for texture mapping as the same as the most 3D animation software but DirectX does not (left-handed). To make the texture mapping rendering correct, we need to reverse the v-component of the texture coordinates. (v = 1 – v)

■ But if the texture coordinate is not used for rendering, we don’t need to reverse it.

Fly2 Billboards (1)■ Fly2 Billboards are always facing to the camera and in rectangle form.■ GEOMETRYid FnObject::Billboard(float *pos, float *size, char *tex, int nTex = 0,

float *color = NULL, BOOL4 beKey = FALSE, BYTE *rgb = NULL, int bType = INDEPENDENT, BOOL4 beUpdate = TRUE)

■ This function returns a geometry id of the billboard.■ float *pos is the local origin of the billboard. The default is the center.■ float *size is the billboard size (width, height).■ char *tex is the texture file name (with no file extension)■ int nTex is the number of textures. nTex = 0 means “tex” is the full file

name of the texture. If nTex >= 1, the texture files are in the naming format : tex0000, tex0001, …

■ float *color is the background color of the board in (r, g, b) format.■ BOOL4 beKey = TRUE means the billboard with color-keying. FALSE is the

default.■ BYTE *rgb is the color-keying value. NULL is the default.■ int bType is the billboard type : INDEPENDENT or DEPENDENT.

INDEPENDENT is the default.

Fly2 Billboards (2)■ Basically a billboard will rotate itself to facing camera independently. If

you need to make all billboards rotate with the first billboard in the same object. Please assign the first billboard of the object as INDEPENDENT and the other billboards in the same object as DEPENDENT.

■ BOOL4 beUpdate = TRUE means this function will update object’s bounding box after generating the billboard. TRUE is the default.

■ Fly2 has another type of billboard, “billboard cloud”, which is used for particle rendering.

Fly2 Label■ A label geometric element is an integer inserted into geometric elements for

game programmers to control the structure of the object geometry.■ GEOMETRYid FnObject::Label(int lable);■ You can remove or show/hide some geometric elements in game by:

■ FnObject::RemoveGeometryBetweenLabel(int label1, int label2);■ FnObject::ShowGeometryBetweenLabel(int label1, int label2, BOOL4

beShow);

Access the Geometry (1)■ You can use FnGeometry() function class to access all geometric data.■ Get geometric element type :

■ DWORD FnGeometry::Type();■ The return values will be INDEXED_TRIANGLES, BILLBOARD, LINES,

NURBS_CURVE, NURBS_SURFACE, BILLBOARD_CLOUD or LABEL■ Show/hide a geometric element individually

■ void FnGeometry::Show(BOOL4 beShow);■ Get material used by the element

■ MATERIALid FnGeometry::GetMaterial();

Access the Geometry (2)■ Lock the vertex array to get the vertex data from rendering engine

■ You need to lock the vertex array before access the vertex data.■ float *FnGeometry::LockVertexArray(int *vLen = NULL, int *nV = NULL, int

vID = 0, BOOL4 beReadOnly = FALSE);■ This function will return the address of vertex array for editing. If Fly2

fails to lock the vertex array, NULL will be returned.■ int *vLen is the variable pointer to get the returned vertex length.■ int *nV is the variable pointer to get the returned number of vertices.■ int vID indicates which vertex buffer will be locked. 0 is the default.■ BOOL4 beReadOnly = TRUE means the lock operation is going to read

the vertex data only. FALSE is the default.■ Use FnGeometry::UnlockVertexArray() to finish the access to the vertices.

■ You must unlock the vertex array when finishing the job.

Access the Geometry (3)■ Lock the index array to get the primitive data from rendering engine

■ You need to lock the index array before access the topology data.■ int *FnGeometry::LockIndexArray(int *tLen = NULL, int *nT = NULL, BOOL4

beReadOnly = FALSE, BOOL4 *beRV = NULL);■ This function will return the address of index array for editing. If Fly2

fails to lock the index array, NULL will be returned.■ int *tLen is the variable pointer to get the returned primitive length.■ int *nT is the variable pointer to get the returned number of primitives.■ BOOL4 beReadOnly = TRUE means the lock operation is going to read

the index data only. FALSE is the default.■ BOOL4 *beRV is a variable pointer to check the index table is in right-

handed or left-handed. Since Fly2 is using right-handed, you need to reverse the index table if *beRV = FALSE for a left-handed rendering API, for example, Direct3D.

■ Use FnGeometry::UnlockIndexArray() to finish the access to the primitives.■ You must unlock the index array when finishing the job.

Fly2 Text (1)■ Fly2 can utilize the hardware supported true type font to render text.■ You can use TEXTid FyCreateText(const char *fontName, int size, BOOL4

beBold, BOOL4 beItalic) to create the font for rendering.■ This function returns an id for programmers to show text on screen.■ Use FnText() member function to access the text object.■ const char *fontName is the name of the font■ int size is the font size■ BOOL4 beBold = TRUE for bolded font■ BOOL4 beItalic = TRUE for italic font

■ Use FyDeleteText(TEXTid textID) to delete a font object.■ Use void FnText::Begin(VIEWPORTid vID) to start the rendering of the text

■ vID is the viewport for text rendering■ Use void FnText::End() to finish the text rendering■ Use int FnText::Write(char *text, int ox, int oy, BYTE r, BYTE g, BYTE b, BYTE a =

255) to render the text.■ A text must be rendered between the Begin() and End() commands.

Fly2 Text (2)■ Use int FnText::Write(char *text, int ox, int oy, BYTE r, BYTE g, BYTE b, BYTE

a = 255) to render the text.■ char *text is the string to be rendered.■ (int ox, int oy) is the position to render, which the left-bottom corner of the

text block.■ (r, g, b, a) is the font color used, which is ranging from 0 – 255. a is the

alpha value with default value 255 (opaque).■ This function will return the x position of the last pixel of the text block for

next writing reference.

Fly2 Audio (1)■ Fly2 supports playing the WAV audio in game.■ To create an audio object, use

■ AUDIOid FyCreateAudio(void)■ This function returns an audio ID (in AUDIOid).■ Use FnAudio() function class to access the audio object.

■ Use void FyDeleteAudio(AUDIOid aID) to delete an audio object.■ To load a WAV sound file:

■ BOOL4 FnAudio::Load(char fileName);■ This function will search current audio path to find the audio file.■ And return TRUE if the loading is successful.

■ To play the audio :■ void FnAudio::Play(DWORD mode)

■ DWORD mode can be ONCE or LOOP.■ void FnAudio::Stop() to stop the audio playing■ void FnAudio::Pause() to pause the playing■ BOOL4 FnAudio::IsPlaying() to check if the audio is playing or not.

Fly2 Audio (2)■ Use FnAudio::SetVolume(float v) to set the sound volume. float v is volume

value. This value should be different in unit and range on different hardware platforms. Be careful to use it.

■ An audio object can clone another audio object to share the same audio buffer.

■ AUDIOid FnAudio::Clone();■ Fly2 supports 3D audio. These functions will be released in next build version.

Fly2 Object Data■ Fly2 object can keep customer-defined data structure inside the object :

■ Initialize a block of memory inside the object :■ void *FnObject::InitData(int length_in_byte);

■ Get data pointer :■ void *FnObject::GetData();

■ Release the data■ void FnObject::ReleaseData();■ When deleting the object, the data will be deleted automatically.

For example :

Struct MyData{ …};

MyData *data = (MyData *) object.InitData(sizeof(MyData));memset(data, 0, sizeof(MyData));…

Fly2 LOD (Level-Of-Detail)■ Fly2 builds discrete LOD in the Fly2 object :■ To define the LOD levels :

■ void FnObject::UseLOD(int numberLevel);■ int numberLevel is the number of LOD levels

■ To assign the LOD level to the model when loading the model file :■ BOOL4 FnObject::Load(char *file, int lodLevel = NONE);

■ To set the distance for LOD level switching :■ void FnObject::SetLODData(int level, float distance);

■ Perform the LOD checking before rendering■ void FnObject::PerformLOD(float *camera_position);

■ float *camera_position is the position of the camera used for rendering.

Fly2 Files■ ASCII files

■ 3D models■ Fly2 model file .cw3■ Wavefront OBJ file .obj

■ Fly2 scene file .cwn■ Characters

■ Fly2 character files .cwa/.cwc/.cwk/.cw3■ Shader description file .cws■ Game FX file .cwf (.cfx is old version)

■ Binary files■ .cw4 is the only one binary file format■ For 3D models, scenes, characters(.cwc + .cwk + all .cw3)■ Backward compatibility

Fly2 CW3 Model File■ For 3D models

# CW3 model file, designed by Chuan-Chang Wang# Created : 0616, 2004#

Model v 1

VertexType position normal texture 1 2

Material 1 ShaderEffect Phong_tex1 Phong Texture bbb02 Vertex 1 6 -20.0 20.0 0.0 0.0 0.0 1.0 0.0 1.0 -20.0 -20.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 -20.0 0.0 0.0 0.0 1.0 0.5 0.0 20.0 -20.0 0.0 0.0 0.0 1.0 1.0 0.0 20.0 20.0 0.0 0.0 0.0 1.0 1.0 1.0 0.0 20.0 0.0 0.0 0.0 1.0 0.5 1.0

Polygon 2 4 0 0 1 2 5 4 0 2 3 4 5

Comments

Version

Vertex type

Materials

Vertices

Primitives

Fly2 CWN Scene File – Simplified Version■ For a 3D Scene :

# TheFly3D 3D scene log file - exported from 3dsMax, Chuan-Chang Wang# Date : 1027, 2005#

Scene v 1.0

Object 7 ObjectFile 1 Cylinder01 ObjectFile 2 Bone01 ObjectFile 3 Bone02 ObjectFile 4 Bone03 ObjectFile 5 Bone04 ObjectFile 6 Bone05 ObjectFile 7 Bone06

Comments

Version

All models in the sceneSaved in cw3 files

Fly2 CWN Scene File – Full Version

# TheFly3D 3D scene log file - exported from 3dsMax, Chuan-Chang Wang# Date : 1027, 2005#

Scene v 1.0

Object 7

BeginObject 1 Model …EndObject

…

BeginRelationship o 1 0 o 2 1 …

EndRelationship

Comments

VersionObject number

Object blockwith the sameformat as CW3

All objects

Scene tree

Fly2 Character Files (1)■ CWA (.cwa)

■ A character description file■ Body and bone structure■ Actions and poses used by bodies■ Character file (.cwc or .cw4)■ Skin and attachment files (.cw3 or .cw4)■ Game FXs linked to the character (in development)■ Character behavior (in development)

■ CWC (.cwc)■ Old version character file■ Graphics only

■ A skeleton (.cwk)■ Skin and attachment files (.cw3 or .cw4)

Fly2 Character Files (2)■ CWK (.cwk)

■ A character skeleton file used by .cwc■ Skeleton structure■ Poses exported from 3D animation tools■ All motion data for each bone in the skeleton

■ CW4 (.cw4)■ The binary version of (.cwc + .cwk + all skins and attachments)

Fly2 Binary Files■ Fly2 binary files use the same file extension .cw4.■ Fly2 uses data chunk to manage the data type and version :■ Data chunk header :

■ Data chunk type reserved for Fly2 system :■ From 0 - 65535

struct iFDataChunkHead{ DWORD type; DWORD id; int len;};

Introduction to Fly2 GameFX■ Fly2 built-in Game FX system including (Fly2 Build version 1004)

■ Plate FX■ Particle FX■ Audio FX■ Force FX■ Geometry FX■ Force FX

■ A game FX system is a combination of FXs.■ Use Fly2 “Fly2Toolkit” Toolkit to edit the FXs.■ Fly2 data searching path for game FXs is FySetGameFXPath(char *path).■ A game FX system is managed by a scene object.

■ To create a game FX, use FnScene::CreateGameFXSystem(). Fly2 will return a gameFX ID (type = GAMEFX_SYSTEMid).

■ Use FnGameFXSystem() function class to access the game FX system object.

■ To delete a game FX, use FnScene::DeleteGameFXSystem(GAMEFX_SYSTEMid gxID);

Use Fly2 Game FX (1) – Load FX■ A game FX system is always using Fly2 Toolkit to create/edit the FXs.■ .cwf is the file extension for a game FX file.■ We suggest (at least current version) all assets for a game FX system should be

located at the same file folder.■ To load a game FX file (.cwf), please use FnGameFXSystem::Load().

■ BOOL4 FnGameFXSystem::Load(char *fileName, BOOL4 beReset, GAMEFXid *fxArray = NULL, int numFX = 0);

■ This function will return TRUE if loading is successful.■ char *fileName is the name of the game FXs.■ BOOL4 beReset = TRUE to reset the game FXs after the loading.■ GAMEFXid *fxArray is an array (in GAMEFXid) to get all game FX IDs in

the game FX file. The default value is NULL means no return.■ int numFX is the array length of fxArray.■ Basically, if you want to get all FXs during the loading, you can call

FnGameFXSystem::QueryFXNumberInFile(char *fileName) to get number of FXs saving in the FX file. Then provide an game FX ID array to get all of them when calling FnGameFXSystem::Load().

Use Fly2 Game FX (2) - Play■ Use FnGameFXSystem::Play() to play FXs continuously.

■ BOOL4 FnGameFXSystem::Play(float skipFrame, DWORD playMode);■ This function will return FALSE if playing to the end of all FXs.■ float skipFrame is the skip frame count after last playing.■ DWORD mode is the playing mode : ONCE or LOOP. In LOOP mode, FXs will

playing in loop.■ Basically if you stop calling this function, all FXs will be paused except that

the audio FXs. To pause the audio FXs’ playing, use FnGameFXSystem::Pause(). Call Play() to continue the playing.

■ Use FnGameFXSystem::Reset() to reset the playing to the 1st frame (frame 0).■ Use FnGameFXSystem::PlayFrame() to play the FXs in a specific frame.

■ BOOL4 FnGameFXSystem::PlayFrame(float iFrame);■ This function will return FALSE if the playing is failed.■ float iFrame is the absolute frame position.

■ Use FnGameFXSystem::SetParentObjectForAll(OBJECTid pID) to assign the parent object all FXs. Then the FXs will follow the parent object’s transformation.

Use Fly2 Game FX (3) – Get FX■ Use FnGameFXSystem::GetFXNumber() to get number of FXs in a game FX

system.■ int FnGameFXSystem::GetFXNumber() will return the number of FXs.

■ Use FnGameFXSystem::GetFX() or FnGameFXSystem::GetFXByName(). These functions will return the GAMEFXid of the game FX. For example,

■ GAMEFXid is the ID of a game FX. Use FnBaseGameFX() to access the general functions of the game FX and use the associated function class (inherited from FnBaseGameFX()) to access the other FX functions.

GAMEFXSYSTEMid gxID;…int i;FnGameFXSystem gx(gxID);GAMEFXid allFX[1024];

int numFX = gx.GetFXNumber();for (i = 0; i < numFX; i++) { allFX[i] = gx.GetFX(i);}

FnBaseGameFX() (1)■ The common used functions of FnBaseGameFX() are

■ To get the FX’s parent object’s name, use■ char *FnBaseGameFX::GetParentObjectName()■ Basically in FX editing tool, the tool can assign the parent object name

to the FX and temporary link the FX to that object (in the tool) to show the result. But in your game, you need to link the FX to the object by your code. The method to do it is that if the FX has a parent object, use this function to get the name of the FX’s parent object. Use the name with FnScene or FnCharacter associated member function to get the object ID. Then use FnBaseGameFX::SetParentObject(OBJECTid pID) to finish the linking.

■ To Check the FX type, use■ DWORD FnBaseGameFX::GetFXType();■ There’re six types of FX supporting by Fly2 (Build 1004) :

■ PLATE_FX : playing texture animation on plate on the ground or billboard.

■ AUDIO_FX : sound FX

FnBaseGameFX() (2)■ PARTICLES_FX : particle system and can be controlled by FORCE_FX■ FORCE_FX : create force fields to control the particles■ GEOMETRY_FX : use the geometry objects (with animation)

created by the artists in animation tools(for example, the 3ds Max) to playing the texture animation.

■ SWORD_FX : tracking two dummy objects in game to simulate the weapon motion blur effect.

■ To get the FX Type of the FX, use■ DWORD FnBaseGameFX::GetFXType();

■ There is one dummy object as the parent of the game FX. You can get its object ID and control manually in game :

■ OBJECTid FnBaseGameFX::GetBaseObject();■ Each FX has its life which should be edited in Fly2 FX editing tool

(cwViewer). You can adjust it in game by using :■ float FnBaseGameFX::GetLife(); to get the FX’s life.■ FnBaseGameFX::AdjustLife(float newLifeValue) to adjust the life. This

function in default will automatically adjust the FX’s key-frame .

FnPlateGameFX() ■ PLATE_FX is a plate on the ground or billboard object to playing texture

animation.■ To check the plate type use : DWORD FnPlateGameFX::GetPlateType().

■ Return value should be BILLBOARD, PLATE_ZUP, or PLATE_YUP.■ Use OBJECTid FnPlateGameFX::GetPlateObject() to get the object ID of the

plate.

FnGeometryGameFX() ■ GEOMETRY_FX is a FX type to playing texture animation on a geometric model.

The model is created by the artists with animation tools (for example, Autodesk 3ds Max) and exported by Fly2 exporters.

■ To get the model, use OBJECTid FnGeometryGameFX::GetModelObject();

FnParticlesGameFX() ■ PARTICLES_FX is a FX type to generate particles as game FXs.■ All features and functions of particle system can be edited in Fly2 tool.■ But you still can use FnParticlesGameFX::GetParticleSystem() to get the

particle system in the FX. This function will get the ID of the particle system in PARTICLE_SYSTEMid. You can use FnParticleSystem function class to use more advanced features and functions.

FnForceGameFX() ■ FORCE_FX is a FX type to generate the force field data for particle system.■ Fly2 provides gravity, parallel forces, sinking forces, vortex forces, and viscosity

in the following types :■ GRAVITY, PARALLEL, SINK, SPHERE, VORTEX, VORTEX_2D, VISCOSITY

■ The best way to experience these force types is learning the Fly2 FX editing tool.

FnAudioGameFX() ■ AUDIO_FX is a FX type to simulate the weapon effect in motion blur.■ We implement this motion blur effect in geometry solution.■ This effect needs two dummy objects existing in the scene and moving in-

game.■ This FX will trace the positions of these two dummies and form a ribbon in

fading transparency.■ In the Fly2 FX editing, you can assign the names of these two dummy objects

and save in the FX file. In the game when you need to use the sword FX, you should have the dummy objects in games and connect them to the FX manually.

■ The dummy objects can be attachments of a character or some objects in the scenes. If the dummy objects are attachments of a character, you can use FnSwordGameFX::GetCharacterName() to get the name of the character.

■ Use FnSwordGameFX::GetDummyObject1Name() to get the name of the 1st dummy object. Use FnSwordGameFX::GetDummyObject2Name() to get the name of the 2nd dummy object.

■ In game, you can use these two names to find the object IDs of the dummy objects. And use FnSwordGameFX::SetDummyObject1(OBJECTid oID) and FnSwordGameFX::SetDummyObject2() to link the FX to game objects.

FnAudioGameFX() ■ AUDIO_FX is a FX type to play sound FX in game.■ Fly2 plays WAV sound FX in almost game platform.

Documents

Fly2 Training (NTU) 王銓彰 [email protected] [email protected] 2014 Build 1