Labels

   If you want a pointer to an object other than the object the Affect is applied to the object must be labeled.

Also you may want to know the position of an object in the scene. To retrieve a pointer to an object or the position of an object the object must be labeled when it is created.

NB. If you have several copies of an object in a scene you must bind each copy and label them separately as a label can only refer to one copy of an object. See the HugHeightfieldAffect example in section 17.1 for an example.

Objects are labeled when they are constructed using the command

  obj->label("the object");

To get the labeled object and its position back within an Affect subclass, use the function find on world_label_list.

  // Retrieve a label from the list. Returns TRUE on success.
  int find(char *findname, object *findplace, transform findtrans);

  //Example
  foundobject = world_label_list->find("the object", &the_obj, 
                                      obj_trans);

This will try to find the name ``the object'', place the object that was labeled into the_obj, and the position of the object in obj_trans.

The transform is two matrices FORE and AFT. FORE is a transformation from the objects position in primitive space to its position in worldspace. AFT is a transformation from the objects position in world space back to its position in primitive space.

The primitivespace of the object means the position the object was in when it was last bound before the label was applied. The worldspace position of the object means the position the object was in when the call to create_animation() was made (in the main procedure).

The transform allows you to calculate the worldspace value from the primitive space value of any point on the object, any vector in the object and any normals to the object.

    // Location of a point on the object
    // calculates p_worldspace from point p_primitivespace
    Matrix::apply(obj_trans[FORE], p_primitivespace, p_worldspace);

    // Direction of a vector in the object
    // calculates v_worldspace from vector v_primitivespace
    Matrix::applynoshift(obj_trans[FORE], v_primitivespace, v_worldspace);

    // Direction of a normal to the object
    // calculates n_worldspace from normal n_primitivespace
    Matrix::applytranspose(obj_trans[AFT], n_primitivespace, n_worldspace);