Функции обратного вызова

Обратные вызовы – это отдельный вид функций API C3D Solver, особенность которых в том, что они вызываются изнутри C3D Solver и могут быть определены на стороне приложения. Необходимость в таких функциях возникает, когда требуется предоставить решателю доступ к данным, хранящимся на стороне приложения, определить свойства геометрических объектов, а также в порядке обратной связи обеспечить решатель запросами, влияющими на ход вычислений. Обратные вызовы расширяют возможности для интеграции решателя с приложением, предоставляя еще один канал взаимодействия. Все функции и типы данных для организации обратных вызовов собраны в отдельном заголовочном файле gce_callback.h.

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

GCE_result GCE_Register(      GCE_system            gSys, 
                        const GCE_callback_table &  cbTable)

Входные данные:

  • gSys – система ограничений, которую будут обслуживать обратные вызовы;

  • cbTable – таблица обратных вызовов, определяющая следующий набор функций:

    • gRegister – функция вида void (*GCE_geom_registered)(GCE_app_geom ag), вызывается решателем, когда геометрический объект пользователя регистрируется в системе gSys с помощью вызова GCM_Bind;

    • gUnregister – функция вида void (*GCE_geom_unregistered)(GCE_app_geom ag), вызывается для геометрического объекта ag в тот момент времени, когда геометрический решатель освобождает объект ag, прекращая с ним всякую работу. Данное событие наступает при таких прямых вызовах, как GCE_RemoveGeom, GCE_RemoveSystem или GCE_ClearSystem.

    • abortFunc – функция запроса на прерывание вычислений. Это булевозвратная функция вида bool (*GCE_abort)(), которая время от времени вызывается в решателе в процессе работы GCE_Evaluate и прекращает вычисления, если функция вернет значение true. Функция GCE_Evaluatе, работа которого была прервана таким образом, вернет код ошибки GCE_RESULT_Aborted.

    • allowZeroRadius – функция обратного вызова вида bool (*GCE_allow_zero_radius)(GCE_app_geom ag), которая сообщает системе ограничений о том, что окружность ag допускает решение, при котором ее радиус равен нулю.

    • allowZeroLength – функция обратного вызова вида bool (*GCE_allow_zero_length)(GCE_app_geom ag), которая сообщает системе ограничений о том, что отрезок или ограниченная кривая ag допускает решение, при котором их длина равна нулю. Например, приложение САПР с помощью опции нулевой длины может запретить отрезок нулевой длины, если он изображает на чертеже ось зеркальной симметрии. Для такого запрета приложению следует вернуть false при вызове allowZeroLength.

    • getLSegDirection – функция обратного вызова вида GCE_vec2d(*GCE_get_lseg_direction)(GCE_app_geom ag), позволяет получить направляющий вектор отрезка ag. Она предназначена для того, чтобы приложение не забывало куда смотрит отрезок L=0, когда потребуется снова вернуть ему длину. А также, чтобы избежать эффекта выворачивания отрезка при участии в таких ограничениях, как касание и на расстоянии.

Возвращаемое значение:

  • GCE_RESULT_Ok, если таблица обратных вызовов была успешно зарегистрирована для системы ограничений;

  • GCE_RESULT_None, если регистрация обратных вызовов не выполнена.

Замечание:

Для корректной работы решателя вызов GCE_Register следует вызвать однократно для одной и той же системы ограничений, в тот момент, пока она еще пуста, например сразу после GCE_CreateSystem.