Работа с движком Newton (Blitz 3D)

nwphx.dll - это библиотека, предназначения для симуляции физического взаимодействия жестких тел.

Основные характеристики библиотеки:

* Жесткие тела с произвольной массой, моментом инерции и центром масс
* Форма тела - прямоугольний параллелепипед, эллипсоид, цилиндр, конус, выпуклый объект произвольной формы, объединение выпуклых объектов для движущихся тел. Для статических, кроме вышеописанных, еще и произвольная форма, задаваемая набором треугольников(Level) или картой высот(Terrain)
* Материалы - различные коэффициенты трения, жесткости и упругости для разных тел
* Соединения - шарик-в-разьеме (ball in socket), ось вращения (hinge), скольжение (slider), спица (Cork), универсальное (universal), пружина(Spring), подвеска(Suspension) для соединения двух тел, и для одного тела - фиксированное направление(UpVector), движение по плоскости (Plane), контакт с трением качения(Dry rolling friction). Кроме того, соединение для симуляции автомобиля(Vehicle) и фиксированное соединение для отладки(Fixed).
* Расчет Архимедовой силы, продолжительного столкновения и точки пересечения произвольного луча с объектами всего мира.
* Три метода симуляции движения тел и два метода симуляции трения. В версии 0.8 предоставлены только самые точные (и самые медленные) из этих методов.
* Учет особенностей архитектуры. В версии 0.8 не предоставлен

Установка библиотеки состоит из следующих этапов:

1) Загрузка архива NEWTON.ZIP
2) Копирование файлов nwphx.decls и nwphx.dll из директории nwphx из архива в директорию userlibs
3) Копирование справки из директории help и примеров из директории sample в удобную директорию

Основные понятия и определения

Твердое тело характеризируется следующими постоянными параметрами:
* Масса тела
* Матрица инерции, задаваемой тремя главными моментами инерции
* Положение центра масс
* Форма тела - геометрия Материал (его номер в массиве), из которого изготовлено тело.

и переменными параметрами:

* Положение тела в пространстве - координаты x,y,z
* Ориентация тела в пространстве - углы поворота pitch, yaw, roll
* Линейная скорость - вектор, вдоль которого движется тело velx,vely,velz
* Угловая скорость - вектор, вокруг которого вращается тело

Твердое тело может быть включено или выключено из обсчета. Выключенные тела, во время шагов симуляции не обрабатываются. Выключение тел это эффективный способ сократить время вычислений в тех случаях, когда точно известно что тела не подвижны или оказывают несущественное влияние на симуляцию.
Процесс симуляции системы жестких тел во времени называется интегрированием(integration). Каждый шаг интегрирования увеличивает текущее время на заданный шаг и устанавливает новые значения состояний для всех жестких тел.
Между каждым шагом интегрирования пользователь может вызывать функции приложения сил и моментов вращения к жесткому телу. Эти величины накапливаются в "аккумуляторе силы” и "аккумуляторе момента" объекта жесткое тело. Когда происходит следующий шаг интегрирования, сумма всех приложенных сил вызывает перемещение тела. Аккумуляторы устанавливаются в ноль после каждого шага интегрирования.
Сочленение - это такое взаимоотношение между двумя телами, при котором тела могут занимать определенную позицию и ориентацию друг относительно друга. Такое взаимоотношение называется соединением(constraint) – слова сочленение и соединение часто взаимозаменяемы.
Когда сочленение присоединяется к двум телам, необходимо чтобы тела занимали определенное положение и ориентацию друг относительно друга. Тем не менее возможно такое расположение тел, что сочленения не будет соединено. Такая "ошибка в сочленении”(joint error) может случиться в двух случаях

Если пользователь установил позицию/ориентацию одного тела некорректно по отношению к позиции/ориентации другого тела.
Во время симуляции могут появляться ошибки, что приведет к смещению тел от необходимых позиций.

Механизм уменьшения ошибок в сочленении следующий: во время каждого шага симуляции каждому сочленению прилаживаются специальные силы, чтобы вернуть тела на правильные позиции. Эта сила контролируется параметром уменьшения ошибки(Stiffness) и принимает значение от 0 до 1.
Stiffness определяет пропорцию, в которой ошибка в сочленении будет исправляться в следующем шаге симуляции. Если Stiffness равно 0, то корректирующая сила прилагаться не будет и тела будут перемещаться в соответствии с ходом симуляции. Если Stiffness равно 1, то будет предприниматься попытка исправить все ошибки в сочленениях на следующем шаге симуляции. Тем не менее устанавливать Stiffness=1 не рекомендуется поскольку ошибки в сочленении нельзя полностью устранить из-за различных внутренних округлений. Рекомендуется устанавливать значения от 0.1 до 0.8.
Для корректной симуляции тел, изготовленных из различных веществ (например, дерево и сталь), вводится понятие материала. Материал - это просто некий номер. Для материалов можно задавать параметры их столкновения (коэффициент трения в контакте, например), а каждому телу назначить соответсвующий материал.

Физический мир (World)

Физический мир - это контейнер для всех жестких тел и сочленений. Всего может быть создан только один физический мир.

phWorldCreate(plane%)

Создает физический мир. Эта команда должны быть выполнения до любой другой команды работы с физикой. Если параметр plane% равен 1, то создается горизонтальная плоскость в точке 0,0,0.

phWorldSetSize(x1#,y1#,z1#,x2#,y2#,z2#)

Устанавливает размер мира. Тела будут обновляться только внутри параллелепипеда от точки (x1,y1,z1) до точки (x2,y2,z2). Не стоит задавать необоснованно большие значения, т.к. это может сказать на скорости симуляции. По умолчанию - от (-10000.0,-10000.0,-10000.0) до (10000.0,10000.0,10000.0).

phWorldSetGravity(gx#,gy#,gz#)

Устанавливает значение вектора гравитации. Значение по умолчанию - (0, -9.81, 0). Ненулевое значение вектора гравитации означает что ко всем телам будет добавляться сила притяжения, равная произведению массы тела на вектор гравитации.

phWorldStep(timestep#)

Шаг симуляции.Рассчитывает изменение положения всех тел за время timestep#. Учитываются приложенные силы и возникшие столкновения между телами. Величина переменной timestep# должна лежаит в пределах от 1/60.0 до 1/600.0, в противном случае она будет ограничена этими величинами.

phWorldDestroy()

Разрушает физический мир, все созданные в нем тела, соединения и материалы. Материалы (Mat)

phMatCreate%()

Создает новый материал. Возвращает номер созданного материала.

phMatSetDefCollidable(IsColl%)
phMatSetDefFriction(stFric#,dynFric#)
phMatSetDefElasticity(elas#)
phMatSetDefSoftness(soft#)

Задают значения по умолчанию между всеми материалами (см. следующие функции).

phMatSetCollidable(mat1%,mat2%,IsColl%)
phMatSetFriction(mat1%,mat2%,stFric#,dynFric#)
phMatSetElasticity(mat1%,mat2%,elas#)
phMatSetSoftness(mat1%,mat2%,soft#)

Устанавливает значения параметров материалов. mat1% и mat2% - номера материалов, между которыми устанавливается параметр. IsColl - определяет, будут ли тела, обладающие данными материалами сталкиваться друг с другом (или проходить друг сквозь друга) stFric, dynFric - значения статического и динамического коэффициентов трения. Допустимый интревал значений - (0.0, 2.0); рекомедуемый - (0.0, 1.0). Статический коэффициент должен быть больше динамического. elas# - коэффициент упругости (0 - абсолютно неупругое столкновение, 1 - абсолютно упругое). soft# - жесткость столкновения. Твердые тела (Body)
Создание и удаление. Тела с простой геометрией.

phBodyCreateNull%(mass#)

Создает тело, не имеющее геометрии (и поэтому не сталкивающееся ни с чем) с массой mass и приведенным моментом инерции (1.0,1.0,1.0). Возвращает идентификатор тела.

phBodyCreateBox%(dx#,dy#,dz#,mass#)

Создает тело с геометрией прямоугольного параллелепипеда с размерами dx,dy,dz и массой mass. Возвращает идентификатор тела.

phBodyCreateSphere%(rx#,ry#,rz#,mass#)

Создает тело с геометрией эллипсоида с полуосями rx,ry,rz и массой mass. Возвращает идентификатор тела.

phBodyCreateCyl%(r#,h#,mass#)

Создает тело с геометрией цилиндра радиусом r, высотой h, массой mass. Возвращает идентификатор тела.

phBodyCreateCone%(r#,h#,mass#)

Создает тело с геометрией конуса с радиусом основания r, высотой h и массой mass. Возвращает идентификатор тела.

phBodyDestroy(body%)

Удаляет тело с идентификатором body% из физического мира. Дальнейшие попытки обратиться по идентификатору удаленного тела могут привести к падению программы. Создание тел со сложной геометрией

phBodyCreateHull%(Vertices*, VertexCount%,mass#)

Создает тело с выпуклой геометрией произвольной формы. Выпуклая геометрия задается набором точек из массива Vertices*{x0,y0,z0,x1,y1,z1,x2,...}. Общее число точек задается переменной VertexCount.
После того, как геометрия будет создана, для нее рассчитывается положение центра масс и моментов инерции.

Построение геометрии по заданный точкам можно наглядно представить следующим образом. Представьте тело, состоящее только из точек, которые сохраняют расстояния друг до друга и не движутся относительно друг друга. Уроним это тело на плоскость и покатаем его по этой плоскости. В каждый момент времени какие-то три точки будут касаться плоскости. Между этими тремя точками создается плоский треугольник. Когда тело прокатится всеми сторонами, мы получим выпуклую геометрию.

phBodyCompoundBegin()
phBodyCompoundAddHull(Vertices*, VertexCount%)
phBodyCompoundEnd%(mass#)

Эти функции позволяют создать тело с геометрией, составленной из выпуклых форм. Перед началом создания тела необходимо вызвать функцию phBodyCompoundBegin(). Добавление выпуклой геометрии к телу происходит с помощью phBodyCompoundAddHull(Vertices*, VertexCount%), аналогично созданию выпуклой геометрии. Наконец, функция phBodyCompoundEnd(mass#) завершает построение тела, задает ему массу mass#, рассчитывает значения моментов инерции и положения центра масс. Эта функция возвращает идентификатор созданного тела. Положение тела в пространстве.

Позиция и ориентация.

Положение тела в пространстве задается координатами x,y,z точки привязки тела (точки 0,0,0 в локальной системе) и тремя углами поворота pitch,yaw,roll. При создании тела все эти величины устанавливаются в 0, поэтому после создания необходимо расположить тела в нужных метсах. Не рекомендуется использовать команды установки координат и углов тела во время симуляции (за исключением, конечно же, создания новых тел). Ну а функции, возвращающие координаты и углы поворота, используются постоянно для синхронизации положения трехмерного объекта и соответсвующего ему физического тела.

phBodyGetX#(body%)
phBodyGetY#(body%)
phBodyGetZ#(body%)

Эти функции возвращают координаты тела.

phBodySetPos(body%,x#,y#,z#)

Устанавливает координаты тела.

phBodyGetPitch#(body%)
phBodyGetYaw#(body%)
phBodyGetRoll#(body%)

Возвращают углы поворота тела.

phBodySetRot(body%,pitch#,yaw#,roll#)

Устанавливает углы поворота тела. Скорости тела.

Кроме положения тел, результатом симуляции является также и их скорость. Линейная скорость показывает вектор движения центра масс тела, угловая скорость (omega) - вектор, вокруг которого вращается тело. Установка скоростей телам (за исключением только что созданных тел) не рекомендуется, т.к. может нарушить физическую корректность симуляции. Однако это не настолько критично, как в случае с установкой координат.

phBodyGetVelX#(body%)
phBodyGetVelY#(body%)
phBodyGetVelZ#(body%)

Возвращают линейную скорость тела.

phBodySetVel(body%,vx#,vy#,vz#)

Устанавливает линейную скорость тела.

phBodyGetOmegaX#(body%)
phBodyGetOmegaY#(body%)
phBodyGetOmegaZ#(body%)

Возвращет угловую скорость тела.

phBodySetOmega(body%,ox#,oy#,oz#)

Устанавливает угловую скорость тела. Воздействия на тела.

Единственный корректный с точки зрения физики способ воздействия на симуляцию жесктих тел - это приложение к ним сил и моментов вращения. Следующие функции предоставляют основные возможности для приложения сил и моментов вращения.

phBodyAddForce(body%,fx#,fy#,fz#)

Добавляет к силу (fx,fy,fz) к центру масс тела. Компоненты силы (fx,fy,fz) считаются в глобальной системе координат.

phBodyAddRelForce(body%,fx#,fy#,fz#)

Добавляет к силу (fx,fy,fz) к центру масс тела. Компоненты силы (fx,fy,fz) считаются в локальной системе координат, связанном с телом.

phBodyAddForceAtPos(body%,fx#,fy#,fz#,x#,y#,z#)

Прикладывает к телу силу (fx,fy,fz) в точке (x,y,z). Компоненты силы и координаты точки приложения считаются в глобальной системе координат.

phBodyAddRelForceAtRelPos(body%,fx#,fy#,fz#,x#,y#,z#)

Прикладывает к телу силу (fx,fy,fz) в точке (x,y,z). Компоненты силы и координаты точки приложения считаются в локальной системе координат, связанной с телом.

phBodyAddImpulse(body%,x#,y#,z#,vx#,vy#,vz#)

Передает телу импульс. В результате применения этой команды скорость точки (x,y,z) изменится на (vx,vy,vz). Компоненты вектора изменения скорости (vx,vy,vz) и координаты точки приложения импульса (x,y,z) считаются в глобальной системе координат. Эквивалентом этой команды может быть phBodyAddForceAtPos(body,x,y,z,vx*mass/timestep,vy*mass/timestep,vz*mass/timestep), где mass - масса тела, а timestep - текущий шаг времени.

phBodyAddTorque(body%,tx#,ty#,tz#)

Прикладывает к телу момент импульса. Компоненты момента импульса считаются в глобальной системе отсчета.

phBodyAddRelTorque(body%,tx#,ty#,tz#)

Прикладывает к телу момент импульса. Компоненты момента импульса считаются в локальной системе отсчета, связанной с телом. Операции с массой и объемом.

Масса тела и ее распределение по телу - главный статический параметр тела. При приложении сил к центру инерции тела, результат зависит только от массы тела, но если сила прикладывается не к центру масс, то на результат влияет и распределение масс. Распределение масс задается значениями моментов инерции вокруг локальных осей x,y,z тела. Аналогично тому, как значение массы показывает, наскольку трудно разгонять тело, момент инерции относительно какой-то оси показывает, насколько трудно тело раскручивать вокруг этой оси. Если рассмотреть два цилиндра одинаковой массы, но с разным радиусом, то цилиндр с большим радиусом будет иметь больший момент инерции вокрус оси цилиндра, т.к. "толстый" цилиндр труднее раскручивать, чем "тонкий".
При создании тела, момент инерции для него считается автоматически, используя геометрию тела и значение массы.
Следующие команды позволяют считывать и устанавливать значения массы, моментов инерции, положения центра масс тела.

phBodySetMass(body%,mass#)

Устанавливает массу тела. Моменты инерции вдоль каждой оси изменяются пропорционально, т.е. приведенный момент инерции (момент инерции, деленный на массу тела) остается постоянным.

phBodySetMassMatrix(body%,mass#,Ixx#,Iyy#,Izz#)

Устанавливает матрицу инерции тела (набор чисел, включающий массу тела и моменты инерции относительно осей x,y,z. Моменты инерции считаются относительно осей локальной системы отсчета тела.

phBodyGetMass#(body%)
phBodyGetMassIxx#(body%)
phBodyGetMassIyy#(body%)
phBodyGetMassIzz#(body%)

Эти функции возвращают значения массы и моментов инерции тела относительно локальный осей x,y,z тела.

phBodySetMassCentre(body%,x#,y#,z#)

Задает положение центра масс тела. Координаты центра масс считаются в локальной системе координат тела. Значение по умолчанию (0,0,0).

phBodyGetMassCentreX#(body%)
phBodyGetMassCentreY#(body%)
phBodyGetMassCentreZ#(body%)

Возвращают координаты центра масс тела в локальной системе отсчета.

phBodyGetVolume#(body%)

Возвращает объем тела. Включение и выключение тел.

Следующие команды позволяют управлять состоянием тела (включено/выключено).

phBodySetSleep(body%,state%)

Устанавливает состояние тела. Если state=1, то тело переводится в выключенное состояние, если state=0, то тело включается.

phBodyGetSleep%(body%)

Возвращает сотояние тела. Если возвращаемое значение равно 1, то тело выключено, если 0 - включено.

phBodySetAutoSleep(body%,state%)

Определяет возможность автовыключения тела. Если state=1, то тело будет само выключаться при достижении предельно маленьких значений скорости, если state=0, то состояние тела не будет самопроизвольно меняться.

phBodySetAutoSleepTreshold(body%,vel#,omega#,frames%)

Задает предельные значения скоростей тела для автовыключения. Тело выключится, если в течение frames тактов значение его линейной скорости будет меньше vel#, а значение уголовой - меньше omega#.

Информация о столкновениях.

На каждой шаге для каждого тела заполняется информация обо всех столкновениях(контактах) этого тела за этот шаг. Все координаты и компоненты векторов считаются в глобальной системе отсчета. phBodyGetCollNum%(body%)

Возвращает число столкновений тела.

phBodyGetCollX#(body%,coll%)
phBodyGetCollY#(body%,coll%)
phBodyGetCollZ#(body%,coll%)

Возвращает координаты контакта с номером coll.

phBodyGetCollNX#(body%,coll%)
phBodyGetCollNY#(body%,coll%)
phBodyGetCollNZ#(body%,coll%)

Возвращает нормаль контакта с номером coll. Нормаль зависит от геометрий сталкивающихся тел.

phBodyGetCollFX#(body%,coll%)
phBodyGetCollFY#(body%,coll%)
phBodyGetCollFZ#(body%,coll%)

Возвращает силу, возникающую при столкновении с номером coll. Эта сила прикладывается к телу в точке контакта. Значение силы зависит от материалов тел.

phBodyGetCollNVel#(body%,coll%)
phBodyGetCollTVel#(body%,coll%)
phBodyGetCollBVel#(body%,coll%)

Возвращает нормальную, тангенциальную и бинормальную составляющие скорости контакта с номером coll. Скорость контакта зависит от относительной линейной и угловой скорости тел. Разноообразные функции тела.
phBodySetGravityMode(body%,mode%)
phBodyGetGravityMode%(body%)

Устанавливает и возвращает режим гравитации для тела. Если режим mode равен 1, то к телу будет прикладываться сила притяжения, если равен 0, то нет.

phBodySetWater(body%,x#,y#,z#,nx#,ny#,nz#,density#,lin_damping#,ang_damping#)

Устанавливает плоскость жидкости для тела. Если плоскость тела была установлена, то каждый такт к телу будет прикладываться Архимедова сила, как на погруженное (или частично погруженное) в жидкость, поверхность которой была задана. Функция имеет следующие параметры: body% - тело, для которого устанавливается плоскость жидкости. x#,y#,z# - точка, принадлежащая плоскости жидкости (любая). nx#,ny#,nz# - нормаль к поверхности жидкости. density# - плотность жидкости. lin_damping# - коэффициент гашения линейной скорости в жидкости (из-за вязкости). ang_damping# - аналогично коэффициент гашения угловой скорости.

phBodyDisableWater(body%)

Отменяет расчет и приложение к телу Архимедовой силы.

phBodySetDamping(body%,linear#,angular#)

Устанавливает коэффициенты гашения линейной и уголовой скоростей тела.

phBodySetContinuousCollisionMode(body%,mode%)
phBodyGetContinuousCollisionMode%(body%)

Устнавливает и возвращает режим продолжительного столкновения для тела. Этот режим помогает предотвратить проскакивание быстродвижущихся тел. Однако в этом случае обсчет тела может занимать да 40% больше времени, поэтому этот режим рекомендуется устанавливать только быстродвижущимся телам небольших размеров.

phBodySetData(body%,data%)
phBodyGetData%(body%)

Устанавливает и возвращает пользовательские данные для тела.

phBodySetEntity(body%,ent%)
phBodyGetEntity%(body%)

Устанавливает и возвращает Entity для тела. Если телу установлена entity, то она автоматически будет выставляться в позицию тела. Но - дети (child) этой entity не поменяют своего положения. Статические(неподвижные) тела.

Любое подвижное тело можно сделать статическим, если установить ему массу, равную 0.
Кроме того, существуют еще 2 способа создать статические тела с произвольной геометрией.

Статический уровень (Level)

Уровень - это статическое тело с произвольной геометрией, задаваемой набором треугольников. Для создания такого тела применяются несколько функций. phLevelBuildBegin()

Начинает построение уровня.

phLevelAddFace(x1#,y1#,z1#,x2#,y2#,z2#,x3#,y3#,z3#)

Добавляет треугольник к геометрии уровня. x1#,y1#,z1#,x2#,y2#,z2#,x3#,y3#,z3# - координаты трех вершин треугольника.

phLevelBuildEnd%()

Завершает построение уровня. Возвращает идентификатор созданного тела.

Карта высот (Terrain)
phTerrainCreate%(nSize%,CellWidth#,height*)

Создает тело с геометрией, задаваемой картой высот. Функция имеет следующие параметры nSize% - размер массива карты высот (по одному измерению) CellWidth# - размер квадрата клетки, т.е. расстояние между "столбцами" в карте высот height* - массив размера nSize*nSize, содержащий карту высот