cTrigger::add_trigger

add_trigger is the heart of all the other functions that add a trigger. This function
allocates a sTrigger structure, sets its type, identification number, and enable flag,
and then links the structure into the linked list of triggers. Once you allocate your
program using the add_trigger function, the program can fill in the returned sTrigger
structure with the coordinates, radius, height, or whatever other information the
trigger needs to have defined.

Keeping in mind that the add_trigger function allocates only a sTrigger structure and
fills it with the minimal data as just mentioned.

cTrigger::add_sphere, cTrigger::add_box, cTrigger::add_cylinder, cTrigger::add_triangle

This group of functions adds a trigger of a specific type to the linked list of triggers.
Each function has its own list of arguments to use for creation (you can
check the comments preceding each function to see what each argument does).
Regardless of the type of trigger, each function first calls the add_trigger function
to get a sTrigger structure with which to work.

Let’s start with the add_sphere function, which takes, in addition to the trigger’s identification
number and default enabled state (as each of the four functions here
do), the sphere’s radius and the X-, Y-, and Z-coordinates for the sphere.

Short and to the point, the add_sphere function calls on the add_trigger function to
allocate and link in a sTrigger structure to the linked list. Once created, the sTrigger
structure instance is filled with the sphere trigger’s coordinates and radius.

add_box, add_cylinder, and add_triangle operate in much the same way the add_sphere function
does. The add_box function takes the identification number and default enabled
state, as well as the coordinates for the opposing corners of the box.

The add_cylinder function uses the lower-middle coordinates of the cylinder, the
radius, and height for the trigger.

Wrapping up the bunch is add_triangle, which takes the three pairs of X- and Zcoordinates
that define each of the triangle’s three corners. The Y-coordinate to
use for those three corners, as well as the height of the triangular trigger shape,
follows.

NOTE
All functions that use a radius as an argument square the value when it is stored in the structure.This speeds
up distance checks later on. How does the trigger class speed up distance checks? A standard distance check
uses a sqrt call to calculate the correct distance. Tossing out the sqrt speeds up the engine, but then
you must square the values to match the distance.

cTrigger::remove and cTrigger::free

These two functions remove triggers from the linked list by referring to the identification
number of the trigger to remove in the remove function or by allowing the
class to remove all triggers in the list using the free function.

The remove function operates by scanning the entire linked list—for each trigger
that shares the same identification number as the number passed in the ID argument,
the remove function removes the structure from the linked list and frees the
structure’s memory:

Once it is determined that a structure needs to be removed, the code
alters the linked list’s pointers and releases the structure’s memory resources.

From this point on, the number of triggers stored in the linked list is reduced and the
loop that scans for structures to remove continues until all structures are scanned.

Whereas the remove function removes triggers according to their identification numbers,
the free function can skip all the hoopla and delete the entire linked list in
one fell swoop.