Callback functions

Callbacks are a separate type of C3D Solver API function, the peculiarity of which is that they are called from within the C3D Solver and can be defined on the application side. The need for such functions arises when it is necessary to provide the solver with access to data stored on the application side, determine the properties of geometric objects, and also provide feedback to the solver with queries that affect the progress of calculations. Callbacks enhance the ability to integrate the solver with the application by providing another channel of interaction. All functions and data types for organizing callbacks are collected in a separate header file gce_callback.h.

In order for user-defined callback functions to work for a given constraint system, they must be registered using the call{#GCE\_Register}

GCE_result GCE_Register(GCE_system gSys, const GCE_callback_table & cbTable)

Input data:

  • gSys – constraint system that callbacks will serve;

  • cbTable is a callback table that defines the following set of functions:

    • gRegister – a function of the void (*GCE_geom_registered)(GCE_app_geom ag) form called by the solver when a user geometry is registered with gSys using the GCM_Bind call.

    • gUnregister – a function of the void (*GCE_geom_unregistered)(GCE_app_geom ag) form called for the geometric object ag at the moment in time when the geometric solver releases the object ag, stopping all work with it. This event occurs on direct calls such as GCE_RemoveGeom, GCE_RemoveSystem, or GCE_ClearSystem.

    • abortFunc — function for requesting to abort calculations. This is a Boolean function of the form bool (*GCE_abort)(), which is called from time to time in the solver while GCE_Evaluate is running and stops computing if the function returns true. A GCE_Evaluate that is aborted in this way will return the error code GCE_RESULT_Aborted.

    • allowZeroRadius – a callback function of the form bool (*GCE_allow_zero_radius)(GCE_app_geom ag) that tells the constraint system that circle ag allows a solution where its radius is zero.

    • allowZeroLength – a callback function of the form bool (*GCE_allow_zero_length)(GCE_app_geom ag), that tells the constraint system that line segment or bounded curve ag allows a solution where their length is zero. For example, a CAD application can use the zero-length option to prohibit a line segment of zero length if it represents the axis of symmetry in a drawing. To enforce this prohibition, the application should return false when allowZeroLength is called.

    • getLSegDirection – a callback function of the form GCE_vec2d(*GCE_get_lseg_direction)(GCE_app_geom ag), that allows to get the direction of the line segment ag. It is designed so that the application does not forget where the segment L = 0 is “looking” when it needs to return its length again. And also to avoid the effect of “turning out” the line segment when participating in such constraints as “tangency” and “at a distance”.

Return value:

  • GCE_RESULT_Ok if the callback table was successfully registered for the constraint system;

  • GCE_RESULT_None if callback registration fails.

Note

For the solver to work correctly, the GCE_Register call should be called once for the same constraint system, while it is still empty, for example, immediately after GCE_CreateSystem.