diguyGraphicsLink

Generated from diguyGraphicsLink.h

DI-Guy API Version 12.5.1

This file was automatically generated from diguyGraphicsLink.h. Do not edit this file directly; the changes will be lost.

Includes: diguy_constants.h | declspec_diguy.h

Contents:

Alphabetical Index

Link against: libdiguy

class diguyGraphicsLink

class BDI_DECLSPEC_diguy diguyGraphicsLink
{
public:
    const char* get_name();
    long get_uid();
    int get_index();
    diguyCharacter* get_character();
    int get_num_shapes();
    diguyGraphicsShape* get_shape_at_index(int index);
    diguyGraphicsShape* find_shape(const char* name);
    diguyGraphicsShape* find_shape_by_class_type(const char* name);
    diguyGraphicsJointType get_joint_type();
    int get_offset_translation(float* tx, float* ty, float* tz);
    int get_offset_rotation(float* rz, float* rx, float* ry);
    int get_translation(float* tx, float* ty, float* tz);
    int get_translation_double(double* tx, double* ty, double* tz);
    int get_translation_is_static();
    const char* get_var_name_tx();
    const char* get_var_name_ty();
    const char* get_var_name_tz();
    int get_rotation(float* rz, float* rx, float* ry);
    int get_rotation_is_static();
    const char* get_var_name_rz();
    const char* get_var_name_rx();
    const char* get_var_name_ry();
    int get_scale(float* sz, float* sx, float* sy);
    int get_scale_is_static();
    const char* get_var_name_sx();
    const char* get_var_name_sy();
    const char* get_var_name_sz();
    diguyGraphicsLink* get_parent_link();
    diguyGraphicsLink* get_attached_to_link();
    int get_is_position_link();
    int get_num_child_links();
    diguyGraphicsLink* get_child_link_at_index(int index);
#ifdef CPLUSPLUS_ONLY
    int get_transformation_matrix(float matrix_array[4][4], int transpose = 0);
    int get_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
    int get_local_transformation_matrix(float matrix_array[4][4], int transpose = 0);
    int get_local_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
    int get_link_transformation_matrix(float matrix_array[4][4], int transpose = 0);
    int get_link_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
#endif
#ifdef CPLUSPLUS_ONLY
    const float* get_data_ptr();
    const float* get_quat_data_ptr();
#endif
    int get_translation_data_index();
    int get_rotation_data_index();
    int get_quat_data_index();
    int get_scale_data_index();
    int get_unique_color(unsigned char* r,
        unsigned char* g,
        unsigned char* b);
#ifdef CPLUSPLUS_ONLY
    virtual void build();
    virtual void post_build();
    virtual void unbuild();
    virtual void attach_to_scene();
    virtual void detach_from_scene();
    virtual void attach_to_link(diguyGraphicsLink* link);
    virtual void detach_from_link();
    virtual void update();
    virtual void push();
    virtual void pop();
    virtual void draw();
    virtual void set_shader_instance(diguyGraphicsShaderInstance* shader_instance);
    virtual void begin_character_draw();
    virtual void end_character_draw();
#endif
    static void set_use_linear_traversal_draw(int mode);
    static int get_use_linear_traversal_draw();
    int get_inverse_rotation_matrix(float matrix_array[4][4], int transpose = 0,
        int include_translation = 1);
    int get_inverse_rotation_matrix_4x4_ptr(float* matrix_array, int transpose = 0, 
        int include_translation = 1);
    int get_is_base_link();
    int get_shader_matrix_index();

Accessor Functions

The functions in this section provide access to data in this object. They are designed to be called by DI-Guy programmers.

Unless otherwise noted all functions in this class section are callable from:

C++
Script

function diguyGraphicsLink::get_name

Prototype:
const char* get_name();
Description:

Returns the name of the link. This pointer will never be NULL.
Returns:

name of the link

function diguyGraphicsLink::get_uid

Prototype:
long get_uid();
Description:

All links are assigned a unique identifier, or uid. This function returns this links's uid.

Note: unique identifiers will change between DI-Guy runs!
Returns:

unique identifier of object

function diguyGraphicsLink::get_index

Prototype:
int get_index();
Returns:

index of the link

function diguyGraphicsLink::get_character

Prototype:
diguyCharacter* get_character();
Description:

Returns a pointer to the diguyCharacter to which this link belongs.
Returns:

pointer of type diguyCharacter

function diguyGraphicsLink::get_num_shapes

Prototype:
int get_num_shapes();
Returns:

number of shapes on this link

function diguyGraphicsLink::get_shape_at_index

Prototype:
diguyGraphicsShape* get_shape_at_index(int index);
Returns:

pointer of type diguyGraphicsShape; NULL if no shape at the specified index
Arguments:

index index of the shape; indices start at 0

function diguyGraphicsLink::find_shape

Prototype:
diguyGraphicsShape* find_shape(const char* name);
Description:

This function returns a pointer to the specified shape.
Arguments:

name name of link to be found
Returns:

pointer of type diguyGraphicsShape; NULL if not found

function diguyGraphicsLink::find_shape_by_class_type

Prototype:
diguyGraphicsShape* find_shape_by_class_type(const char* name);
Description:

This function returns a pointer to the specified shape.
Arguments:

name name of shape with class_type to be found, currently works with heads
Returns:

pointer of type diguyGraphicsShape; NULL if not found

function diguyGraphicsLink::get_joint_type

Prototype:
diguyGraphicsJointType get_joint_type();
Description:

Returns the type of joint that attaches this link to its parent.
Returns:

joint type of the link

function diguyGraphicsLink::get_offset_translation

Prototype:
int get_offset_translation(float* tx, float* ty, float* tz);
Description:

Returns in the passed variables the translation offset of this link from its parent.

The offset will always remain fixed once DI-Guy is initialized.

Returned values are in meters.
Arguments:

tx, ty, tz pointers to floats into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_offset_rotation

Prototype:
int get_offset_rotation(float* rz, float* rx, float* ry);
Description:

Returns in the passed variables the rotational offset of this link from its parent.

The offset will always remain fixed once DI-Guy is initialized.

Returned values are an Euler triple in degrees, and should be applied in RZ -> RX -> RY order, after the translation offset.
Arguments:

rz, rx, ry pointers to floats into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_translation

Prototype:
int get_translation(float* tx, float* ty, float* tz);
Description:

Returns in the passed variables the translation amount of the link's joint.

If there is a current render camera set, the position link's values will be in the local space of the camera. This is useful for rendering far from the origin.

The values may or may not stay constant frame to frame; see get_translation_is_static().

Returned values are in meters, and should be applied after the rotational offset (if any).
Arguments:

tx, ty, tz pointers to floats into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_translation_double

Prototype:
int get_translation_double(double* tx, double* ty, double* tz);
Description:

Returns in the passed variables the translation amount of the link's joint.

The values may or may not stay constant frame to frame; see get_translation_is_static().

Returned values are in meters, and should be applied after the rotational offset (if any).
Arguments:

tx, ty, tz pointers to doubles into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_translation_is_static

Prototype:
int get_translation_is_static();
Description:

Returns whether the translation returned by get_translation() is static (unchanging) or dynamic (can change frame to frame).

If the translation is dynamic the translation values will come from one or more DI-Guy motion variables; the names of the variables are accessible using the functions get_var_name_tx(), etc.

If the translation is static it will remain so; the value returned by this function should not change frame to frame.
Returns:

1 if translation is static, 0 if not, -1 on failure

function diguyGraphicsLink::get_var_name_tx

Prototype:
const char* get_var_name_tx();
Description:

Returns the name of the DI-Guy motion data variable that controls translation along the X axis.

The returned pointer will be NULL if there is no associated variable.
Returns:

name of the variable; NULL if there is no variable

function diguyGraphicsLink::get_var_name_ty

Prototype:
const char* get_var_name_ty();
Description:

Returns the name of the DI-Guy motion data variable that controls translation along the Y axis.

The returned pointer will be NULL if there is no associated variable.
Returns:

name of the variable; NULL if there is no variable

function diguyGraphicsLink::get_var_name_tz

Prototype:
const char* get_var_name_tz();
Description:

Returns the name of the DI-Guy motion data variable that controls translation along the Z axis.

The returned pointer will be NULL if there is no associated variable.
Returns:

name of the variable; NULL if there is no variable

function diguyGraphicsLink::get_rotation

Prototype:
int get_rotation(float* rz, float* rx, float* ry);
Description:

Returns in the passed variables the rotation amount of the link's joint.

The values may or may not stay constant frame to frame; see get_rotation_is_static().

Returned values are an Euler triple in degrees, and should be applied in RZ -> RX -> RY order, after the translation.
Arguments:

rz, rx, ry pointers to floats into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_rotation_is_static

Prototype:
int get_rotation_is_static();
Description:

Returns whether the rotation returned by get_rotation() is static (unchanging) or dynamic (can change frame to frame).

If the rotation is dynamic the rotation values will come from one or more DI-Guy motion variables; the names of the variables are accessible using the functions get_var_name_rz(), etc.

If the rotation is static it will remain so; the value returned by this function should not change frame to frame.
Returns:

1 if rotation is static, 0 if not, -1 on failure

function diguyGraphicsLink::get_var_name_rz

Prototype:
const char* get_var_name_rz();
Description:

Returns the name of the DI-Guy motion data variable that controls rotation about the Z axis.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_var_name_rx

Prototype:
const char* get_var_name_rx();
Description:

Returns the name of the DI-Guy motion data variable that controls rotation about the X axis.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_var_name_ry

Prototype:
const char* get_var_name_ry();
Description:

Returns the name of the DI-Guy motion data variable that controls rotation about the Y axis.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_scale

Prototype:
int get_scale(float* sz, float* sx, float* sy);
Description:

Returns in the passed variables the scale amount of the link's joint.

The values may or may not stay constant frame to frame; see get_scale_is_static().

Returned values unitless scale factors, and should be applied after the rotation.
Arguments:

sx, sy, sz pointers to floats into which result should be placed
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_scale_is_static

Prototype:
int get_scale_is_static();
Description:

Returns whether the scale returned by get_scale() is static (unchanging) or dynamic (can change frame to frame).

If the scale is dynamic the scale values will come from one or more DI-Guy motion variables; the names of the variables are accessible using the functions get_var_name_sx(), etc.

If the scale is static it will remain so; the value returned by this function should not change frame to frame.
Returns:

1 if scale is static, 0 if not, -1 on failure

function diguyGraphicsLink::get_var_name_sx

Prototype:
const char* get_var_name_sx();
Description:

Returns the name of the DI-Guy motion data variable that controls scale in the Z dimension.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_var_name_sy

Prototype:
const char* get_var_name_sy();
Description:

Returns the name of the DI-Guy motion data variable that controls scale in the Y dimension.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_var_name_sz

Prototype:
const char* get_var_name_sz();
Description:

Returns the name of the DI-Guy motion data variable that controls scale in the X dimension.

The returned pointer will be NULL if there is no associated variable.

function diguyGraphicsLink::get_parent_link

Prototype:
diguyGraphicsLink* get_parent_link();
Description:

Returns a pointer to this link's parent link. Parent links are always links within the same character. If a link is attached to a link in another character (i.e., it is "parented to" another link), that link pointer can be obtained by calling get_attached_to_link().

The returned pointer will be NULL if the link is the position link and has no parent.
Returns:

object of type diguyGraphicsLink

function diguyGraphicsLink::get_attached_to_link

Prototype:
diguyGraphicsLink* get_attached_to_link();
Description:

Returns a pointer to this link's attached to link. The attached to link is different than the parent link in that a parent link is always a link in the same character, while an attached to link is always a link in a different character.

Only position links can be attached to links of another character.

The returned pointer will be NULL if the link is not attached to the link of another character.
Returns:

object of type diguyGraphicsLink

function diguyGraphicsLink::get_is_position_link

Prototype:
int get_is_position_link();
Description:

Returns 1 if this link is the position link, or 0 if not. The position link is the root link of the DI-Guy character's link and shape hierarchy, and has no parent link.
Returns:

1 if this link is the position link, 0 if not, -1 on error

function diguyGraphicsLink::get_num_child_links

Prototype:
int get_num_child_links();
Description:

Returns how many child links this link has. Child links can be accessed using the get_child_link_at_index() function.
Returns:

number of child links

function diguyGraphicsLink::get_child_link_at_index

Prototype:
diguyGraphicsLink* get_child_link_at_index(int index);
Description:

Returns a pointer to this link's child link at the specified index.

The returned pointer will be NULL if there is no link at that index.
Arguments:

index index of the child link; indices start at 0
Returns:

object of type diguyGraphicsLink

Matrix Retrieval Functions

All functions in this class section are restricted to C++.

function diguyGraphicsLink::get_transformation_matrix

Prototype:
int get_transformation_matrix(float matrix_array[4][4], int transpose = 0);
Description:

This function fills out the passed float array with the world-coordinate system transformation matrix of this link.
NOTE:

If the character's performance level (CPL) is 3 or greater, link matrices are not computed or updated, and this call should not be used. See diguyCharacter::set_minimum_cpl() for more information.
Arguments:

matrix_array two-dimensional array of floats into which the matrix should be copied
transpose defaults to zero, sets if the matrix should be treated as row-major or column-major
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_transformation_matrix_4x4_ptr

Prototype:
int get_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
Description:

Pointer version of get_transformation_matrix(), see for docs.

function diguyGraphicsLink::get_local_transformation_matrix

Prototype:
int get_local_transformation_matrix(float matrix_array[4][4], int transpose = 0);
Description:

This function fills out the passed float array with the character-local-coordinate system transformation matrix of this link.
NOTE:

If the character's performance level (CPL) is 3 or greater, link matrices are not computed or updated, and this call should not be used. See diguyCharacter::set_minimum_cpl() for more information.
Arguments:

matrix_array two-dimensional array of floats into which the matrix should be copied
transpose defaults to 0, sets if the matrix should be treated as row-major or column-major
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_local_transformation_matrix_4x4_ptr

Prototype:
int get_local_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
Description:

Pointer version of get_local_transformation_matrix(), see for docs.

function diguyGraphicsLink::get_link_transformation_matrix

Prototype:
int get_link_transformation_matrix(float matrix_array[4][4], int transpose = 0);
Description:

This function fills out the passed float array with the link-local-coordinate system transformation matrix of this link. This is the same value as the matrix built from get_rotation() and get_translation()
NOTE:

If the character's performance level (CPL) is 3 or greater, link matrices are not computed or updated, and this call should not be used. See diguyCharacter::set_minimum_cpl() for more information.
Arguments:

matrix_array two-dimensional array of floats into which the matrix should be copied
transpose defaults to 0, sets if the matrix should be treated as row-major or column-major
Returns:

0 on success, -1 on failure

function diguyGraphicsLink::get_link_transformation_matrix_4x4_ptr

Prototype:
int get_link_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
Description:

Pointer version of get_link_transformation_matrix(), see for docs.

function diguyGraphicsLink::get_data_ptr

Prototype:
const float* get_data_ptr();
Description:

Returns a pointer to the current motion data array. Along with data indices returned below, motion data can be directly read from this state vector instead of making multiple calls for getting transform data.

The rotations in this array will be in Euler angles. If quaternions are being used, get_quat_data_ptr() should be called instead.

This function may return NULL, in which case the functions get_translation(), get_rotation(), and get_scale() must be used.

The pointer returned by this function may change from frame to frame, and therefore should not be saved.

This function should not be used for the position link (when get_is_position_link() returns 1).

This function should not be called in a derived class's constructor; the pointer will not yet be valid.
Returns:

pointer to floats; may return NULL if array isn't available
Callable From:

C++

function diguyGraphicsLink::get_quat_data_ptr

Prototype:
const float* get_quat_data_ptr();
Description:

This function is similar to get_data_ptr(), except rotations in the returned array will be in quaternions instead of Euler angles.
Returns:

pointer to floats; may return NULL if array isn't available
Callable From:

C++

function diguyGraphicsLink::get_translation_data_index

Prototype:
int get_translation_data_index();
Description:

Returns the index of this link's translation data in the float array returned by get_data_ptr() or get_quat_data_ptr(). The translation values are in (tx, ty, tz) order in the array.

This function may return -1, in which case this link has no translation data.

The index returned by this function will not change from frame to frame, and can therefore be saved once it has been obtained.

This function should not be used for the position link (when get_is_position_link() returns 1). Use get_translation() instead.

This function should not be called in a derived class's constructor; the index will not yet be valid.
Returns:

index into float array; -1 if no translation data for link

function diguyGraphicsLink::get_rotation_data_index

Prototype:
int get_rotation_data_index();
Description:

Returns the index of this link's rotation data in the float array returned by get_data_ptr(). If quaternion data is being used, call get_quat_data_ptr() instead.

The rotation values in the data array will be Euler angles in (rz, rx, ry) order.

This function may return -1, in which case this link has no rotation data.

This function should not be used for the position link (when get_is_position_link() returns 1). Use get_rotation() instead.

This function should not be called in a derived class's constructor; the index will not yet be valid.
Returns:

index into float array; -1 if no rotation data for link

function diguyGraphicsLink::get_quat_data_index

Prototype:
int get_quat_data_index();
Description:

Returns the index of this link's rotation data in the float array returned by get_quat_data_ptr(). If Euler angle data is being used, call get_data_ptr() instead.

The rotation values in the data array will be a quaternion in (qx, qy, qz, qw) order.

This function may return -1, in which case this link has no rotation data.

The index returned by this function will not change from frame to frame, and can therefore be saved once it has been obtained.

This function should not be used for the position link (when get_is_position_link() returns 1). Use get_rotation() instead.

This function should not be called in a derived class's constructor; the index will not yet be valid.
Returns:

index into float array; -1 if no rotation data for link

function diguyGraphicsLink::get_scale_data_index

Prototype:
int get_scale_data_index();
Description:

Returns the index of this link's scale data in the float array returned by get_data_ptr() or get_quat_data_ptr(). The scale values are in (sx, sy, sz) order in the array.

This function may return -1, in which case this link has no scale data.

The index returned by this function will not change from frame to frame, and can therefore be saved once it has been obtained.

This function should not be used for the position link (when get_is_position_link() returns 1). Use get_scale() instead.

This function should not be called in a derived class's constructor; the index will not yet be valid.
Returns:

index into float array; -1 if no scale data for link

function diguyGraphicsLink::get_unique_color

Prototype:
int get_unique_color(unsigned char* r,
    unsigned char* g,
    unsigned char* b);
Description:

Returns in the passed pointers the unique color of this link. All links in a DI-Guy appearance are assigned a unique RGB color that can be used in pick/selection operations.

Also see diguyScenario::map_color_to_impact().

See programming_examplesdiguy_graphics_apiogl_examples/intersection_test for an example of its usage.
Returns:

0 on success, -1 on failure
@TODO Test with lua probably non-functional

Virtual Functions

The functions in this section are all virtual functions that will be called by DI-Guy at various times during DI-Guy execution.

Because the functions are all virtual, DI-Guy programmers can create a subclass of this class and override them. Unless otherwise stated, the base class functions do not need to be called.

function diguyGraphicsLink::build

Prototype:
virtual void build();
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects to be created. All information necessary to build the link should be available via the Accessor Functions above when this function is called.

Builds happen in depth-first traversal order, so the parent's build() function will always be called before this link's build() function.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to create scene graph nodes that allow for the various transformations to happen.

The following nodes are commonly created:

a static transform node to hold the offsets
a dynamic transform node (or DOF) to allow motion data to be applied
either an LOD or switch node to allow graphics LODs to be applied

LOD nodes, that automatically handle LOD switching, should be created if automatic LOD switching is desired.

A switch node should be created if manual setting of the graphics LOD is desired.

If this link is a position link (it has no parent link), the scene graph nodes should not yet be attached to the scene graph; that should be done during the call to attach().

Otherwise the scene graph nodes should start out attached to their attach points (a scene graph node of the parent link).
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage)

function diguyGraphicsLink::post_build

Prototype:
virtual void post_build();
Description:

This function will be called by DI-Guy when all links and shapes of a DI-Guy character have been built, providing an opportunity for final touch-ups to be made to the built hierarchy.

This function will be called only for the top-level position link.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers sometimes override this function. They might to so to do renderer-specific optimizations to the created hierarchy.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage)

function diguyGraphicsLink::unbuild

Prototype:
virtual void unbuild();
Description:

This function will be called by DI-Guy when it is time for the renderer-specific link objects created during the build() call to be destroyed.

Unbuilds happen in reverse depth-first traversal order, so this link's unbuild() function will always be called before the parent's unbuild() function.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to destroy the scene graph nodes created by build().
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Unbuild Stage)

function diguyGraphicsLink::attach_to_scene

Prototype:
virtual void attach_to_scene();
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects created during the build() call to be attached to their attach points.

This function will only be called for the position link.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to attach the scene graph nodes created during build() to somewhere on the scene graph.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage, and sometimes during the Update Stage)

function diguyGraphicsLink::detach_from_scene

Prototype:
virtual void detach_from_scene();
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects created during the build() call to be detached from their attach points.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to detach the scene graph nodes created during build() from the scene graph.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage, and sometimes during the Update Stage)

function diguyGraphicsLink::attach_to_link

Prototype:
virtual void attach_to_link(diguyGraphicsLink* link);
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects created during the build() call to be attached to a link of another character.

This function will only be called for the position link.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to attach the scene graph nodes created during build() to somewhere on the scene graph.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage, and sometimes during the Update Stage)

function diguyGraphicsLink::detach_from_link

Prototype:
virtual void detach_from_link();
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects created during the build() call to be detached from a link of another character.

This function will only be called for the position link.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to detach the scene graph nodes created during build() from somewhere on the scene graph.
Callable From:

N/A (automatically called by DI-Guy Graphics API during the Build Stage, and sometimes during the Update Stage)

function diguyGraphicsLink::update

Prototype:
virtual void update();
Description:

This function will be called by DI-Guy when it is time for renderer-specific link objects created during the build() call to be updated with new transformation data.

Updates happen in depth-first traversal order, so the parent's update() function will always be called before this link's update() function.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers usually do override this function, to update the scene graph nodes created during build() with new values.

These values should be obtained by calling get_translation(), get_rotation(), and get_scale().
Callable From:

N/A (automatically called by DI-Guy Graphics API during Update Stage)

function diguyGraphicsLink::push

Prototype:
virtual void push();
Description:

This function will be called by DI-Guy when it is traversing the link hierarchy to draw.
Immediate Mode:

Immediate mode renderers can override this function. Typically some type of transformation matrix stack push operation is performed.
Scene Graph:

Scene graph renderers usually do not override this function; transformation states are handled automatically by scene graphs.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsLink::pop

Prototype:
virtual void pop();
Description:

This function will be called by DI-Guy when it is traversing the link hierarchy to draw.
Immediate Mode:

Immediate mode renderers can override this function. Typically some type of transformation matrix stack pop operation is performed.
Scene Graph:

Scene graph renderers usually do not override this function; transformation states are handled automatically by scene graphs.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsLink::draw

Prototype:
virtual void draw();
Description:

This function will be called by DI-Guy when it is time for the transformations of this link to be applied.
Immediate Mode:

Immediate mode renderers usually do override this function, to apply transformations to the transformation stack.
Scene Graph:

Scene graph renderers usually do not override this function; transformation states are handled automatically by scene graphs.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsLink::set_shader_instance

Prototype:
virtual void set_shader_instance(diguyGraphicsShaderInstance* shader_instance);
Description:

This function will be called by DI-Guy when it a shader should be bound to this link. This is important in some scene graph environments, when the scene graph is responsible for binding the shader.
Immediate Mode:

Immediate mode renderers usually do not override this function.
Scene Graph:

Scene graph renderers can override this function but some don't need to.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Build Stage)

Experimental Functions

function diguyGraphicsLink::begin_character_draw

Prototype:
virtual void begin_character_draw();
Description:

This function will be called by DI-Guy when the drawing of a new character is beginning. This happens when the position link is drawn.
Immediate Mode:

Immediate mode renderers can override this function. Typically some type of transformation matrix stack push operation is performed. This is also an appropriate place to do any per-character modifications, such as:

applying scale
applying the base translation of the character
picking a current LOD
etc.
Scene Graph:

Scene graph renderers usually do not override this function; transformation states are handled automatically by scene graphs.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsLink::end_character_draw

Prototype:
virtual void end_character_draw();
Description:

This function will be called by DI-Guy when the drawing traversal of the character's link hierarchy has completed.
Immediate Mode:

Immediate mode renderers can override this function. Typically any matrix stack push operation done in begin_character_draw() is undone here by an appropriate pop operation.
Scene Graph:

Scene graph renderers usually do not override this function; transformation states are handled automatically by scene graphs.
Callable From:

N/A (automatically called by DI-Guy Graphics API during Draw Stage)

function diguyGraphicsLink::set_use_linear_traversal_draw

Prototype:

static void set_use_linear_traversal_draw(int mode);

Description:

This value corresponds to bdiGraphicsInitGraphicsAPI.use_linear_traversal_draw. This value can be changed at runtime, typically for debugging or performance comparison purposes.

Overview of how the modes differ:

if (!get_use_linear_traversal_draw())
{
    // push the base transform of the character in the world
    // the get_transformation_matrix() of the position link
    m_position_link->begin_character_draw();

    // each link should multiply by the get_link_transformation_matrix concatenating
    // them as the link array is traversed
    m_position_link->push();
    m_position_link->recursive_draw();
    m_position_link->pop();
    m_position_link->end_character_draw();
}

//linear draw behavior
else
{
    // push the base transform of the character in the world
    // the get_transformation_matrix() of the position link
    m_position_link->begin_character_draw();
    int i;
    for each link in link array
    {
        // note the ability to skip links with nothing attached to them
        if (link->get_num_shapes() > 0 || link->get_is_position_link())
        {
            // each link should multiply by the get_local_transformation_matrix
            // which contains the precalculated concatenated matrix
            link->push();
            link->draw();
            link->pop();
        }

        if (link->has_attached_creatures())
        {
            for each attached creature
            {
                attached_creature->draw_as_child();
            }
        }
    }
    m_position_link->end_character_draw();

function diguyGraphicsLink::get_use_linear_traversal_draw

Prototype:
static int get_use_linear_traversal_draw();
Description:

Returns whether recursive draw mode is enabled. See set_use_linear_traversal_draw().

Experimental Functions

The following functions are experimental and may change or disappear with no warning.

function diguyGraphicsLink::get_inverse_rotation_matrix

Prototype:

int get_inverse_rotation_matrix(float matrix_array[4][4], int transpose = 0,
    int include_translation = 1);

function diguyGraphicsLink::get_inverse_rotation_matrix_4x4_ptr

Prototype:

int get_inverse_rotation_matrix_4x4_ptr(float* matrix_array, int transpose = 0, 
    int include_translation = 1);

Deprecated Functions

The following functions are deprecated.

As these functions may disappear in a future version of DI-Guy, it is recommended that you remove calls to these functions from your application.

function diguyGraphicsLink::get_is_base_link

Prototype:
int get_is_base_link();
Description:

Deprecated as of 9.1.4; use diguyGraphicsLink::get_is_position_link() instead.

function diguyGraphicsLink::get_shader_matrix_index

Prototype:
int get_shader_matrix_index();
Description:

Deprecated as of 12.0.0 due to architecture change

Alphabetical Index

These coded instructions, statements, and computer programs contain unpublished proprietary information of Boston Dynamics and are protected by Copyright Laws of the United States. They may not be used, duplicated, or disclosed in any form, in whole or in part, without the prior written consent from Boston Dynamics.

RESTRICTED RIGHTS LEGEND

Use, duplication, or disclosure by the government is subject to restrictions as set forth in FAR 52.227.19(c)(2) or subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Sofware clause at DFARS 252.227-7013 and/or in similar or successor clauses in the FAR, or the DOD or NASA FAR Supplement, or to subparagraphs (c)(1) and (c)(2) of the Commercial Computer Software--Restricted Rights at 48 CFR 52.227-19, as applicable. Unpublished-rights reserved under the Copyright Laws of the United States.

Contractor/Manufacturer is:

Boston Dynamics/78 Fourth Avenue/Waltham MA 02451.

`matrix_array`	two-dimensional array of floats into which the matrix should be copied
`transpose`	defaults to zero, sets if the matrix should be treated as row-major or column-major