Unigine 基础入门

1. 首先要搭建好开发环境：

1)Visual Stodio 已经安装了.

2). Microsoft Windows SDK 7.1 (for Windows 7)：

https://www.microsoft.com/en-us/download/details.aspx?id=8442

3)DirectX redistributive June 2010

http://download.cnet.com/Microsoft-DirectX-Redistributable-June-2010/3000-2121_4-10176490.html

4)Python 2.7

使用的版本是2.7.9

https://www.python.org/downloads/release/python-279/

5) SCon 2.0+

选用最新版的，版本位数和python的对应

http://sourceforge.net/projects/scons/files/scons/2.3.5/

2.一些环境变量

In fact, this script only sets environment variables, which are:

%UNIGINE_DIR% variable pointing to Unigine SDK location.

%WINSDK71_DIR% variable pointing to Windows SDK location.

%PYTHON_DIR% variable pointing to Python location.

Locations of the following directories are added to the %PATH% variable: %UNIGINE_DIR%\externs\bin; %UNIGINE_DIR%\lib; %UNIGINE_DIR%\bin and location of Python binaries (in the mentioned order).

Startup Command-Line Options

对于C:\Unigine evaluation\source\samples\App\D3D9AppQt下的D3D9AppQt实例作为参考：

main -data_path ../../../../ ^

-engine_config ../../../../data/samples/unigine.cfg ^

-system_script ../../../../data/samples/unigine.cpp ^

-video_app direct3d9 -video_resizable 1 -video_mode 3

三种格式：

Shell commands

main_* -command argument

main_* -command "argument,argument"

main_* -console_command "command argument"

The syntax of command-line options is as follows: the full name of the binary executable (32- or 64-bit, development or production version) is specified first and then the start-up options.本实例中是main .

All paths are specified as absolute or relative (to the Unigine executable or data path, as indicated below).

所有的命令行选项都可以通过console来改变。所有可用的选项都会自动的储存在unigine.cfg文件中，Specified CLI options always override the ones stored in the configuration file.

Video Settings

Video_mode 3: Video mode to set window resolution or size.数字3: 1280x720，即设定分辨率为1280*720.

其他的video setting：

-video_resizable 1：即设置窗口大小可调整，而不需要重启程序

Graphics Settings

-video_app direct3d9：选择DirectX9为图形渲染的API

video_vsync：Vertical synchronization (synchronize FPS with monitor's refresh rate)，为开启垂直同步的选项，1为开，0为关，默认为0

video_refresh：图形刷新频率，设置值为0-200

video_multisample：Hardware anti-aliasing mode，硬件抗锯齿模式，0 is no anti-aliasing，1 is 2x anti-aliasing，

2 is 4x anti-aliasing，3 is 8x anti-aliasing，4 is 16x anti-aliasing，默认为0。

video_gamma：Gamma correction value，伽玛校正值，0.5-3.5，默认为1.0.

Data

-system_script ../../../../data/samples/unigine.cpp ^

system_script：Path to the system script (specified relative to the data directory) ，指向系统脚本，使用相对路径指定data路径，默认为：core/unigine.cpp

关于system script的解释：（参考documentation中Execution Sequence的解释）

The system script is loaded and started. Basically, the system script performs housekeeping necessary to start and keep the Unigine-based application going. It stays loaded during the whole Unigine runtime.

engine_log：The log file to be created and used (the path is specified relative to the binary executable)，指定log file，默认为log.html

其他的：

File System

-data_path：Path to the data directory with all resources(specified relative to the binary executable). This is a required command-line option.

指向data文件夹，参数： ../ (????只能用'../'?)

初始化Unigine

在初始化Unigine时直接将参数传递进

Engine::init(UNIGINE_VERSION, &widget, Uargc, Uargv)中。

如下例：

 1 // initialize Engine
 2
 3     int Uargc = 9;
 4
 5     char * agrvString = "main -data_path ./ ^"
 6
 7         "-engine_config %UNIGINE_DIR%/data/samples/unigine.cfg ^"
 8
 9         "-system_script %UNIGINE_DIR%/data/samples/unigine.cpp ^"
10
11         "-video_app direct3d9";// -video_resizable 1 -video_mode 3
12
13     char **Uargv = &agrvString;
14
15     Engine::init(UNIGINE_VERSION, &widget, Uargc, Uargv);
16 

其中，Uargc为参数个数，程序名（即.exe文件）必须包含在其中，为第一个参数。-data_path 指定为data路径，此例将data放在main.exe当前路径下。将data放在上一级目录时不成功！！。可以指定-data_path为绝对路径。

参数总共9个，所以Uargc = 9.

-video_mode 3传进去时会造成启动失败。

将Unigine封装进Qt的QMainWindow中

步骤一：将AppQt.h、AppQt.cpp和D3D9AppQt.cpp、D3D9AppQt.h加入项目中，记得修改.pro文件

步骤二：在pro文件中，要包含Unigine的Include和lib，其次要定义宏UNIGINE_DOUBLE和_CRT_SECURE_NO_WARNINGS，包含lib文件%UNIGINE_DIR%/lib/Unigine_x86d.lib。

步骤三：将Unigine_x86d.lib和Unigine_x86d.dll和Unigine启动文件Unigine.cfg放入到项目的bin/debug下。

Unigine.cfg内要修改data_path为./

修改system_script为C:/Unigine evaluation/data/samples/unigine.cpp

步骤四：将C:/Unigine evaluation/data拷贝至./bin/debug

步骤五：将传入参数在类的构造函数中初始化，不必由命令行传入。

接下来就是移植Unigine 的实例程序到Qt的QMainWindow中了。

Unigine的双精度坐标系统

Chapters

•How to Use Double Precision Coordinates

•How to Manage Your Code to Support Both Single and Double Precision

•Functions Argument Differences

Unigine supports two types of coordinate precision:

◾Single precision coordinates

◾Double precision coordinates

可以创建并使用所有的数据类型来创建应用，但是脚本函数只返回确定的数据类型。单精度在使用Save world/ Save/ Restore state会造成精度的丢失。如果使用了，保存的节点的坐标会被重写为单精度浮点数数据。

Single precision coordinates

Single precision coordinates are suitable for not very large worlds where all meshes are positioned relatively close to the zero of coordinates. Depending on the size of meshes (small objects are more prone to precision artifacts) single precision allows to render worlds up to 10-20 thousands units from the center.

Single precision coordinates适合不是很大的场景，允许从坐标原点外延1-2万个单位。单精度返回的是：float，vec3，vec4，mat4。

Double precision coordinates

Double precision coordinates适合大规模的场景建模，返回类型是：double，dvec3，dvec4，dmat4。

How to Use Double Precision Coordinates

Unigine提供的所有libraries默认使用的是Single precision coodinates。使用double precision，从<UnigineSDK>/lib/double_precision要复制所有你的工程需要的libraries到<UnigineSDK>/lib.

查看是否成功使用; To check what build is used, see Features line in the console or in the log file (look for Double in the list).

Replace arguments for functions that deal with coordinates (see below) with double precision data types or special data types to support both variants of precision (see below)。

How to Manage Your Code to Support Both Single and Double Precision

使用Scalar/Vec3/Vec4/Mat4支持两种数据精度。If you want your code to support both single and double precision builds, use the following data types that start with the capital letter. The engine will automatically substitute these types with appropriate ones in runtime, without having to handle it manually in code.

In case of using special Scalar, Vec3, etc. data types, include core/unigine.h header in your scripts.

Source code (UnigineScript)

#include <core/unigine.h>

Functions Argument Differences

Here is a list of functions that take and return different types of arguments depending on the run build. Functions listed above the line correspond to single precision build, while the bottom ones are used in the double precision build.

Physical Engine Learning

1. 添加形状

   To add a shape, perform the following steps:

• Assign a physical body to the mesh: a rigid body or a dummy body.
• 在Editor环境下的Nodes窗口中的Body栏下的Type选项中选择(a rigid body or a dummy body)
• Go to the Shapes tab. Choose an appropriate type of shape and click Add.
• 在右边的Shapes下选择添加相应的形状。点击Add

You can enable visualization of shapes by checking Tools panel -> Show tab -> Physics shapes option. (Visualizer should be enabled). It will show shapes when physical objects collide

打开碰撞时的形状显示。

Sphere

A sphere is the simplest and the fastest shape, because its only property is a radius.

For spherical shapes continuous collision detection is calculated. Due to that, it will not pass through other physical objects even when moving at a high speed.

As a trick, you can use sphere shapes even for edgy objects. In this case all collisions will always be detected.

Convex Hull 凸壳

holes and cavities of the mesh are ignored when generating a convex hull.

Convex shape is the smallest shape that can enclose vertices of the approximated mesh.在列车与地面摩擦时或者与其他物体发生刚性碰撞，可以尝试将之设置为凸壳模型进行近似的模拟。

Approximation error

阈值越高，则越少的点被包含在凸壳面上。

◾By the value of 0, the shape precisely duplicates the mesh; the whole volume of it is enclosed. It is strongly recommended to create shapes with such

◾The higher the value, the less vertices there are in the created shape, but the more details are skipped .

阈值为0 的时候，是网格的精确的复制，当然只是指局部的网格，因为凹陷和洞将被忽略。阈值越大，这越不精确，但是计算量必然会降低。

Collision Detection 碰撞检测

物理引擎概览

1. Stages of Physics Simulation

   Simulation of physics goes through a number of stages when it is updated each iteration. They are as follows.

   1. Physics flush
   2. Broad phase of collision detection
   3. Narrow phase of collision detection
   4. Simulation
   5. Synchronization of physics

   In the performance profiler, the total time of physics simulation is displayed by the Physics counter.

   1. Physics Flush

   1.Before anything else, a spatial tree is updated. After we have the up-to-date data regarding how all objects with physical bodies are positioned, it would be safe to transform them or calculate collisions.

   2.C++ API Plugin flush() is called, if there is such a function.

   3.Physics module calls the flush() of the world script. Here you can call all functions that handle physics simulation and interactions (and not only that, see the details on flush() usage and limitations).

   2. Collision Detection: Broad Phase

   1.Within the Physical distance, all objects are found that have physical bodies. They will be simulated during the current physics tick. Make sure that the physical distance in your Unigine-based application is not too small, because physical interactions outside of it are not calculated, so objects freeze up. (However, even if one body from the island is found within the physical distance, the whole island would be simulated).

   在物理距离内，所有的对象都要进行仿真计算。要确保物理距离不能够太小(physical distance )，超出物理距离的对象将不被计算和仿真，会被"冻住"，

   Notice

   You can force to update nodes that are outside the Physical distance using addUpdateNode() function.可以使用addUpdateNode()函数强制性的更新位于物理距离外的那些节点。

   2.Checking all pairs of objects for collision is too time consuming, especially if the scene is large. That is why potentially colliding objects are found based on a fast and rough test. If bodies intersect with their bounding volumes (which are shape-sized, and do not depend on nodes bounding volumes), or there are joints that connect them, such bodies are combined in a island. To put it short, all bodies are somehow connected (spatially or with joints), go into one island. That means, bodies inside one island can possibly interact with each other in this frame, while bodies in different islands would not collide for certain.

   Notice

   Non-colliding body dummy is skipped and not simulated unless it interacts with other bodies through joints.

   Basically, broad phase increases the efficiency of collision detection and decreases computational load. Before doing more precise and costly calculations, we can filter out pairs of objects that are positioned too far to collide.

   3.Unigine physics is deterministic. Bodies, shapes and joints are sorted inside islands. By that, we ensure that contacts will always be solved in the predefined order and visualization of physics in the world is fully repetitive (one one computer).

2. Continuous Collision Detection

   If a sphere or a capsule participates in the contact with any other shape or surface, continuous collision detection (CCD) is performed. Unigine takes velocities of the body, radius of its shape and calculates what contacts this body will have (during the current physics tick), assuming it continues its current trajectory. So, unlike the simple collision detection, contacts are analyzed not discretely, once per physics tick, but rather found for the whole frame.

   In the performance profiler you can find:

• The total time of this narrow phase stage is displayed by the PNarrow counter.

The number of contacts is displayed by the PContacts counter.

Script Debugging

1. Compile-Time Errors 编译时错误

   Error Message

   When a compile-time error occurs, it means that the interpreter could not parse and load the script. In this case, the log file will contain an error message with:

   在log文件中，一般提供以下两种错误信息

   1.A source code string with an invalid statement. //错误的原代码语句

   2.An error description from the interpreter. // 解释器给出的错误描述

2. Run-Time Errors 运行是错误

   Error Message

   When a run-time error occurs, it usually means that you are trying to manipulate a corrupt or even a non-existent object. In this case, the log file will contain an error message with:

   在log文件中，一般提供以下三种错误信息

   1.An error description from the interpreter. //解释器的错误描述

   2.Current stack of function calls. // 当前的函数调用堆栈

   3.An assembly dump of an invalid statement. //无效语句的汇编转储

3. Debugger

   The Unigine debugger allows you to:

• Set the breakpoints directly in the script // 直接在脚本中设置断点
• Set and remove the breakpoints via the console // 在console中设置和移除断点
• View memory stack // 查看内存堆
• View function call stack // 查看函数调用的堆栈
• View current variables values // 查看当前变量的值
• Step through instructions // 步进式调试

To run the debug process, you can insert the breakpoint; instruction in your code or set the run-time breakpoint.

Debugger的启动

Notice

Note that the debugger opens in the main (external) console, which is available only in the debug builds.

需要注意的是，debugger只能在debug创建器创建的场景中使用。如下图所示

双击launch_debug.bat后启动调试器，左侧会出现调试器窗口：

相应的也会出现world窗口：

在运行和调试过程中，console窗口不能关闭；如果关闭，则world窗口也会关闭。

Set a Breakpoint

Source code (UnigineScript)

int a = 10;
breakpoint; // the breakpoint instruction
int b = 1;
forloop(int i = 0; a){
    b += i;
    log.message("Iteration: %d\n",i);
    log.message("Value: %d\n",b);
}