DI-Guy C++ SDK Reference  13.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguyGraphicsLink.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2014 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 /*********************************************************************/
14 #ifndef __diguyGraphicsLink_H
15 #define __diguyGraphicsLink_H
16 
17 #ifdef SWIG
18 %module diguyGraphicsLink
19 #else
20 #define CPLUSPLUS_ONLY
21 #endif
22 
23 #ifdef CPLUSPLUS_ONLY
24 #include <diguy_constants.h>
25 
26 class bdiLink;
27 class diguyCharacter;
28 class diguyGraphicsLink;
29 class diguyGraphicsShape;
30 class diguyGraphicsShaderInstance;
31 
32 
33 #endif
34 
35 #include <declspec_diguy.h>
36 
37 /****************************************************************************/
38 class BDI_DECLSPEC_diguy diguyGraphicsLink
39 {
40 
41 public:
42 
43 /*****************************************************************************/
56  /*l
57  *b Description:
58  **
59  ** Returns the name of the link. This pointer will
60  ** never be NULL.
61  **
62  *b Returns:
63  **
64  ** name of the link
65  */
66  const char* get_name();
67 
68  /*l
69  *b Description:
70  **
71  ** All links are assigned a unique identifier, or uid. This
72  ** function returns this links's uid.
73  **
74  ** *Note*: unique identifiers will change between DI-Guy runs!
75  **
76  *b Returns:
77  **
78  ** unique identifier of object
79  */
80  long get_uid();
81 
82  /*l
83  *b Returns:
84  **
85  ** index of the link
86  */
87  int get_index();
88 
89  /*l
90  *b Description:
91  **
92  ** Returns a pointer to the diguyCharacter to which this link
93  ** belongs.
94  **
95  *b Returns:
96  **
97  ** pointer of type diguyCharacter
98  */
99  diguyCharacter* get_character();
100 
101  /*l
102  *b Returns:
103  **
104  ** number of shapes on this link
105  */
106  int get_num_shapes();
107 
108  /*l
109  *b Returns:
110  **
111  ** pointer of type diguyGraphicsShape; NULL if no shape at the
112  ** specified index
113  **
114  *b Arguments:
115  **
116  *a index - index of the shape; indices start at 0
117  */
118  diguyGraphicsShape* get_shape_at_index(int index);
119 
120  /*l
121  *b Description:
122  **
123  ** This function returns a pointer to the specified shape.
124  **
125  *b Arguments:
126  **
127  *a name - name of link to be found
128  **
129  *b Returns:
130  **
131  ** pointer of type diguyGraphicsShape; NULL if not found
132  */
133  diguyGraphicsShape* find_shape(const char* name);
134 
135  /*l
136  *b Description:
137  **
138  ** This function returns a pointer to the specified shape.
139  **
140  *b Arguments:
141  **
142  *a name - name of shape with class_type to be found,
143  *a currently works with heads
144  **
145  *b Returns:
146  **
147  ** pointer of type diguyGraphicsShape; NULL if not found
148  */
149  diguyGraphicsShape* find_shape_by_class_type(const char* name);
150 
151  /*l
152  *b Description:
153  **
154  ** Returns the type of joint that attaches this link to its parent.
155  **
156  *b Returns:
157  **
158  ** joint type of the link
159  */
160  diguyGraphicsJointType get_joint_type();
161 
162  /*l
163  *b Description:
164  **
165  ** Returns in the passed variables the translation offset of this
166  ** link from its parent.
167  **
168  ** The offset will always remain fixed once DI-Guy is initialized.
169  **
170  ** Returned values are in meters.
171  **
172  *b Arguments:
173  **
174  *a tx, ty, tz - pointers to floats into which result
175  *a should be placed
176  **
177  *b Returns:
178  **
179  ** 0 on success, -1 on failure
180  */
181  int get_offset_translation(float* tx, float* ty, float* tz);
182 
183  /*l
184  *b Description:
185  **
186  ** Returns in the passed variables the rotational offset of this link
187  ** from its parent.
188  **
189  ** The offset will always remain fixed once DI-Guy is initialized.
190  **
191  ** Returned values are an Euler triple in degrees, and should be
192  ** applied in RZ -> RX -> RY order, after the translation offset.
193  **
194  *b Arguments:
195  **
196  *a rz, rx, ry - pointers to floats into which result
197  *a should be placed
198  **
199  *b Returns:
200  **
201  ** 0 on success, -1 on failure
202  */
203  int get_offset_rotation(float* rz, float* rx, float* ry);
204 
205  /*l
206  *b Description:
207  **
208  ** Returns in the passed variables the translation amount of the
209  ** link's joint.
210  **
211  ** If there is a current render camera set, the position link's
212  ** values will be in the local space of the camera. This is useful
213  ** for rendering far from the origin.
214  **
215  ** The values may or may not stay constant frame to frame; see
216  ** get_translation_is_static().
217  **
218  ** Returned values are in meters, and should be applied after the
219  ** rotational offset (if any).
220  **
221  *b Arguments:
222  **
223  *a tx, ty, tz - pointers to floats into which result
224  *a should be placed
225  **
226  *b Returns:
227  **
228  ** 0 on success, -1 on failure
229  */
230  int get_translation(float* tx, float* ty, float* tz);
231 
232  /*l
233  *b Description:
234  **
235  ** Returns in the passed variables the translation amount of the
236  ** link's joint.
237  **
238  ** The values may or may not stay constant frame to frame; see
239  ** get_translation_is_static().
240  **
241  ** Returned values are in meters, and should be applied after the
242  ** rotational offset (if any).
243  **
244  *b Arguments:
245  **
246  *a tx, ty, tz - pointers to doubles into which result
247  *a should be placed
248  **
249  *b Returns:
250  **
251  ** 0 on success, -1 on failure
252  */
253  int get_translation_double(double* tx, double* ty, double* tz);
254 
255  /*l
256  *b Description:
257  **
258  ** Returns whether the translation returned by get_translation() is
259  ** static (unchanging) or dynamic (can change frame to frame).
260  **
261  ** If the translation is dynamic the translation values will come
262  ** from one or more DI-Guy motion variables; the names of the
263  ** variables are accessible using the functions get_var_name_tx(),
264  ** etc.
265  **
266  ** If the translation is static it will remain so; the value returned
267  ** by this function should not change frame to frame.
268  **
269  *b Returns:
270  **
271  ** 1 if translation is static, 0 if not, -1 on failure
272  */
273  int get_translation_is_static();
274 
275  /*l
276  *b Description:
277  **
278  ** Returns the name of the DI-Guy motion data variable that controls
279  ** translation along the X axis.
280  **
281  ** The returned pointer will be NULL if there is no associated
282  ** variable.
283  **
284  *b Returns:
285  **
286  ** name of the variable; NULL if there is no variable
287  */
288  const char* get_var_name_tx();
289 
290  /*l
291  *b Description:
292  **
293  ** Returns the name of the DI-Guy motion data variable that controls
294  ** translation along the Y axis.
295  **
296  ** The returned pointer will be NULL if there is no associated
297  ** variable.
298  **
299  *b Returns:
300  **
301  ** name of the variable; NULL if there is no variable
302  */
303  const char* get_var_name_ty();
304 
305  /*l
306  *b Description:
307  **
308  ** Returns the name of the DI-Guy motion data variable that controls
309  ** translation along the Z axis.
310  **
311  ** The returned pointer will be NULL if there is no associated
312  ** variable.
313  **
314  *b Returns:
315  **
316  ** name of the variable; NULL if there is no variable
317  */
318  const char* get_var_name_tz();
319 
320  /*l
321  *b Description:
322  **
323  ** Returns in the passed variables the rotation amount of the link's
324  ** joint.
325  **
326  ** The values may or may not stay constant frame to frame; see
327  ** get_rotation_is_static().
328  **
329  ** Returned values are an Euler triple in degrees, and should be
330  ** applied in RZ -> RX -> RY order, after the translation.
331  **
332  *b Arguments:
333  **
334  *a rz, rx, ry - pointers to floats into which result
335  *a should be placed
336  **
337  *b Returns:
338  **
339  ** 0 on success, -1 on failure
340  */
341  int get_rotation(float* rz, float* rx, float* ry);
342 
343  /*l
344  *b Description:
345  **
346  ** Returns in the passed variables the rotation amount of the link's
347  ** joint.
348  **
349  ** The values may or may not stay constant frame to frame; see
350  ** get_rotation_is_static().
351  **
352  ** Returned values are an Euler triple in degrees, and should be
353  ** applied in RZ -> RX -> RY order, after the translation.
354  **
355  *b Arguments:
356  **
357  *a rz, rx, ry - pointers to floats into which result
358  *a should be placed
359  **
360  *b Returns:
361  **
362  ** 0 on success, -1 on failure
363  */
364  int get_rotation_euler(float* rz, float* rx, float* ry);
365 
366  /*l
367  *b Description:
368  **
369  ** Returns in the passed variables the rotation amount of the link's
370  ** joint.
371  **
372  ** The values may or may not stay constant frame to frame; see
373  ** get_rotation_is_static().
374  **
375  ** Returned values are a quaternion and should be applied after
376  ** the translation.
377  **
378  *b Arguments:
379  **
380  *a qx, qy, qz, qw - pointers to floats into which result
381  *a should be placed
382  **
383  *b Returns:
384  **
385  ** 0 on success, -1 on failure
386  */
387  int get_rotation_quat(float* qx, float* qy, float* qz, float* qw);
388 
389  /*l
390  *b Description:
391  **
392  ** Returns whether the rotation returned by get_rotation() is static
393  ** (unchanging) or dynamic (can change frame to frame).
394  **
395  ** If the rotation is dynamic the rotation values will come from one
396  ** or more DI-Guy motion variables; the names of the variables are
397  ** accessible using the functions get_var_name_rz(), etc.
398  **
399  ** If the rotation is static it will remain so; the value returned by
400  ** this function should not change frame to frame.
401  **
402  *b Returns:
403  **
404  ** 1 if rotation is static, 0 if not, -1 on failure
405  */
406  int get_rotation_is_static();
407 
408  /*l
409  *b Description:
410  **
411  ** Returns the name of the DI-Guy motion data variable that controls
412  ** rotation about the Z axis.
413  **
414  ** The returned pointer will be NULL if there is no associated
415  ** variable.
416  */
417  const char* get_var_name_rz();
418 
419  /*l
420  *b Description:
421  **
422  ** Returns the name of the DI-Guy motion data variable that controls
423  ** rotation about the X axis.
424  **
425  ** The returned pointer will be NULL if there is no associated
426  ** variable.
427  */
428  const char* get_var_name_rx();
429 
430  /*l
431  *b Description:
432  **
433  ** Returns the name of the DI-Guy motion data variable that controls
434  ** rotation about the Y axis.
435  **
436  ** The returned pointer will be NULL if there is no associated
437  ** variable.
438  */
439  const char* get_var_name_ry();
440 
441  /*l
442  *b Description:
443  **
444  ** Returns in the passed variables the scale amount of the link's
445  ** joint.
446  **
447  ** The values may or may not stay constant frame to frame; see
448  ** get_scale_is_static().
449  **
450  ** Returned values unitless scale factors, and should be applied
451  ** after the rotation.
452  **
453  *b Arguments:
454  **
455  *a sx, sy, sz - pointers to floats into which result
456  *a should be placed
457  **
458  *b Returns:
459  **
460  ** 0 on success, -1 on failure
461  */
462  int get_scale(float* sz, float* sx, float* sy);
463 
464  /*l
465  *b Description:
466  **
467  ** Returns whether the scale returned by get_scale() is static
468  ** (unchanging) or dynamic (can change frame to frame).
469  **
470  ** If the scale is dynamic the scale values will come from one or
471  ** more DI-Guy motion variables; the names of the variables are
472  ** accessible using the functions get_var_name_sx(), etc.
473  **
474  ** If the scale is static it will remain so; the value returned by
475  ** this function should not change frame to frame.
476  **
477  *b Returns:
478  **
479  ** 1 if scale is static, 0 if not, -1 on failure
480  */
481  int get_scale_is_static();
482 
483  /*l
484  *b Description:
485  **
486  ** Returns the name of the DI-Guy motion data variable that controls
487  ** scale in the Z dimension.
488  **
489  ** The returned pointer will be NULL if there is no associated
490  ** variable.
491  */
492  const char* get_var_name_sx();
493 
494  /*l
495  *b Description:
496  **
497  ** Returns the name of the DI-Guy motion data variable that controls
498  ** scale in the Y dimension.
499  **
500  ** The returned pointer will be NULL if there is no associated
501  ** variable.
502  */
503  const char* get_var_name_sy();
504 
505  /*l
506  *b Description:
507  **
508  ** Returns the name of the DI-Guy motion data variable that controls
509  ** scale in the X dimension.
510  **
511  ** The returned pointer will be NULL if there is no associated
512  ** variable.
513  */
514  const char* get_var_name_sz();
515 
516  /*l
517  *b Description:
518  **
519  ** Returns a pointer to this link's parent link. Parent links are
520  ** always links within the same character. If a link is attached to
521  ** a link in another character (i.e., it is "parented to" another
522  ** link), that link pointer can be obtained by calling
523  ** get_attached_to_link().
524  **
525  ** The returned pointer will be NULL if the link is the position link
526  ** and has no parent.
527  **
528  *b Returns:
529  **
530  ** object of type diguyGraphicsLink
531  */
532  diguyGraphicsLink* get_parent_link();
533 
534  /*l
535  *b Description:
536  **
537  ** Returns a pointer to this link's attached to link. The attached
538  ** to link is different than the parent link in that a parent link is
539  ** always a link in the same character, while an attached to link is
540  ** always a link in a different character.
541  **
542  ** Only position links can be attached to links of another character.
543  **
544  ** The returned pointer will be NULL if the link is not attached to
545  ** the link of another character.
546  **
547  *b Returns:
548  **
549  ** object of type diguyGraphicsLink
550  */
551  diguyGraphicsLink* get_attached_to_link();
552 
553  /*l
554  *b Description:
555  **
556  ** Returns 1 if this link is the position link, or 0 if not. The
557  ** position link is the root link of the DI-Guy character's link and
558  ** shape hierarchy, and has no parent link.
559  **
560  *b Returns:
561  **
562  ** 1 if this link is the position link, 0 if not, -1 on error
563  */
564  int get_is_position_link();
565 
566  /*l
567  *b Description:
568  **
569  ** Returns how many child links this link has. Child links can be
570  ** accessed using the get_child_link_at_index() function.
571  **
572  *b Returns:
573  **
574  ** number of child links
575  */
576  int get_num_child_links();
577 
578  /*l
579  *b Description:
580  **
581  ** Returns a pointer to this link's child link at the specified
582  ** index.
583  **
584  ** The returned pointer will be NULL if there is no link at that
585  ** index.
586  **
587  *b Arguments:
588  **
589  *a index - index of the child link; indices start at 0
590  **
591  *b Returns:
592  **
593  ** object of type diguyGraphicsLink
594  */
595  diguyGraphicsLink* get_child_link_at_index(int index);
596 
597 /*****************************************************************************/
604 #ifdef CPLUSPLUS_ONLY
605 
606  /*l
607  *b Description:
608  **
609  ** This function fills out the passed float array with the
610  ** world-coordinate system transformation matrix of this link.
611  **
612  *b NOTE:
613  **
614  ** If the character's performance level (CPL) is 3 or greater, link
615  ** matrices are not computed or updated, and this call should not be
616  ** used. See diguyCharacter::set_minimum_cpl() for more information.
617  **
618  *b Arguments:
619  **
620  *a matrix_array - two-dimensional array of floats into
621  *a which the matrix should be copied
622  *a transpose - defaults to zero, sets if the matrix should be
623  *a treated as row-major or column-major
624  **
625  *b Returns:
626  **
627  ** 0 on success, -1 on failure
628  */
629  int get_transformation_matrix(float matrix_array[4][4], int transpose = 0);
630 
631  /*l
632  *b Description:
633  **
634  ** Pointer version of get_transformation_matrix(), see for docs.
635  * Some end users might prefer this version to avoid copying data from
636  * an explicit float[4][4].
637  **/
638  int get_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
639 
640  /*l
641  *b Description:
642  **
643  ** This function fills out the passed float array with the
644  ** character-local-coordinate system transformation matrix of this
645  ** link.
646  **
647  *b NOTE:
648  **
649  ** If the character's performance level (CPL) is 3 or greater, link
650  ** matrices are not computed or updated, and this call should not be
651  ** used. See diguyCharacter::set_minimum_cpl() for more information.
652  **
653  *b Arguments:
654  **
655  *a matrix_array - two-dimensional array of floats into
656  *a which the matrix should be copied
657  *a transpose - defaults to 0, sets if the matrix should be treated
658  *a as row-major or column-major
659  **
660  *b Returns:
661  **
662  ** 0 on success, -1 on failure
663  */
664  int get_local_transformation_matrix(float matrix_array[4][4], int transpose = 0);
665 
666  /*l
667  *b Description:
668  **
669  ** Pointer version of get_local_transformation_matrix(), see for docs.
670  * Some end users might prefer this version to avoid copying data from
671  * an explicit float[4][4].
672  **/
673  int get_local_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
674 
675  /*l
676  *b Description:
677  **
678  ** This function fills out the passed float array with the
679  ** link-local-coordinate system transformation matrix of this
680  ** link. This is the same value as the matrix built from
681  ** get_rotation() and get_translation()
682  **
683  *b NOTE:
684  **
685  ** If the character's performance level (CPL) is 3 or greater, link
686  ** matrices are not computed or updated, and this call should not be
687  ** used. See diguyCharacter::set_minimum_cpl() for more information.
688  **
689  *b Arguments:
690  **
691  *a matrix_array - two-dimensional array of floats into
692  *a which the matrix should be copied
693  *a transpose - defaults to 0, sets if the matrix should be treated
694  *a as row-major or column-major
695  **
696  *b Returns:
697  **
698  ** 0 on success, -1 on failure
699  */
700  int get_link_transformation_matrix(float matrix_array[4][4], int transpose = 0);
701 
702  /*l
703  *b Description:
704  **
705  ** Pointer version of get_link_transformation_matrix(), see for docs.
706  * Some end users might prefer this version to avoid copying data from
707  * an explicit float[4][4].
708  **/
709  int get_link_transformation_matrix_4x4_ptr(float* matrix, int transpose = 0);
710 
711 #endif
712 
713 
714 
715 #ifdef CPLUSPLUS_ONLY
716 
717  /*l
718  *b Description:
719  **
720  ** Returns a pointer to the current motion data array. Along with
721  ** data indices returned below, motion data can be directly read from
722  ** this state vector instead of making multiple calls for getting
723  ** transform data.
724  **
725  ** The rotations in this array will be in Euler angles. If
726  ** quaternions are being used, get_quat_data_ptr() should be called
727  ** instead.
728  **
729  ** This function may return NULL, in which case the functions
730  ** get_translation(), get_rotation(), and get_scale() must be used.
731  **
732  ** The pointer returned by this function may change from frame to
733  ** frame, and therefore should not be saved.
734  **
735  ** This function should not be used for the position link (when
736  ** get_is_position_link() returns 1).
737  **
738  ** This function should not be called in a derived class's
739  ** constructor; the pointer will not yet be valid.
740  **
741  *b Returns:
742  **
743  ** pointer to floats; may return NULL if array isn't available
744  **
745  *b Callable From:
746  **
747  *- - C++
748  */
749  const float* get_data_ptr();
750 
751  /*l
752  *b Description:
753  **
754  ** This function is similar to get_data_ptr(), except rotations in
755  ** the returned array will be in quaternions instead of Euler angles.
756  **
757  *b Returns:
758  **
759  ** pointer to floats; may return NULL if array isn't available
760  **
761  *b Callable From:
762  **
763  *- - C++
764  */
765  const float* get_quat_data_ptr();
766 
767 #endif
768 
769  /*l
770  *b Description:
771  **
772  ** Returns the index of this link's translation data in the float
773  ** array returned by get_data_ptr() or get_quat_data_ptr(). The
774  ** translation values are in (tx, ty, tz) order in the array.
775  **
776  ** This function may return -1, in which case this link has no
777  ** translation data.
778  **
779  ** The index returned by this function will not change from frame to
780  ** frame, and can therefore be saved once it has been obtained.
781  **
782  ** This function should not be used for the position link (when
783  ** get_is_position_link() returns 1). Use get_translation() instead.
784  **
785  ** This function should not be called in a derived class's
786  ** constructor; the index will not yet be valid.
787  **
788  *b Returns:
789  **
790  ** index into float array; -1 if no translation data for link
791  */
792  int get_translation_data_index();
793 
794  /*l
795  *b Description:
796  **
797  ** Returns the index of this link's rotation data in the float array
798  ** returned by get_data_ptr(). If quaternion data is being used,
799  ** call get_quat_data_ptr() instead.
800  **
801  ** The rotation values in the data array will be Euler angles in (rz,
802  ** rx, ry) order.
803  **
804  ** This function may return -1, in which case this link has no
805  ** rotation data.
806  **
807  ** This function should not be used for the position link (when
808  ** get_is_position_link() returns 1). Use get_rotation() instead.
809  **
810  ** This function should not be called in a derived class's
811  ** constructor; the index will not yet be valid.
812  **
813  *b Returns:
814  **
815  ** index into float array; -1 if no rotation data for link
816  */
817  int get_rotation_data_index();
818 
819  /*l
820  *b Description:
821  **
822  ** Returns the index of this link's rotation data in the float array
823  ** returned by get_quat_data_ptr(). If Euler angle data is being
824  ** used, call get_data_ptr() instead.
825  **
826  ** The rotation values in the data array will be a quaternion in (qx,
827  ** qy, qz, qw) order.
828  **
829  ** This function may return -1, in which case this link has no
830  ** rotation data.
831  **
832  ** The index returned by this function will not change from frame to
833  ** frame, and can therefore be saved once it has been obtained.
834  **
835  ** This function should not be used for the position link (when
836  ** get_is_position_link() returns 1). Use get_rotation() instead.
837  **
838  ** This function should not be called in a derived class's
839  ** constructor; the index will not yet be valid.
840  **
841  *b Returns:
842  **
843  ** index into float array; -1 if no rotation data for link
844  */
845  int get_quat_data_index();
846 
847  /*l
848  *b Description:
849  **
850  ** Returns the index of this link's scale data in the float array
851  ** returned by get_data_ptr() or get_quat_data_ptr(). The scale
852  ** values are in (sx, sy, sz) order in the array.
853  **
854  ** This function may return -1, in which case this link has no scale
855  ** data.
856  **
857  ** The index returned by this function will not change from frame to
858  ** frame, and can therefore be saved once it has been obtained.
859  **
860  ** This function should not be used for the position link (when
861  ** get_is_position_link() returns 1). Use get_scale() instead.
862  **
863  ** This function should not be called in a derived class's
864  ** constructor; the index will not yet be valid.
865  **
866  *b Returns:
867  **
868  ** index into float array; -1 if no scale data for link
869  */
870  int get_scale_data_index();
871 
872  /*l
873  *b Description:
874  **
875  ** Returns in the passed pointers the unique color of this link. All
876  ** links in a DI-Guy appearance are assigned a unique RGB color that
877  ** can be used in pick/selection operations.
878  **
879  ** Also see diguyScenario::map_color_to_impact().
880  **
881  ** See programming_examples/diguy_graphics_api/ogl_examples/intersection_test
882  ** for an example of its usage.
883  **
884  *b Returns:
885  **
886  ** 0 on success, -1 on failure
887  **
888  ** @TODO Test with lua probably non-functional
889  */
890  int get_unique_color(unsigned char* r,
891  unsigned char* g,
892  unsigned char* b);
893 
894 
895 /*****************************************************************************/
907 #ifdef CPLUSPLUS_ONLY
908 
909  /*l
910  *b Description:
911  **
912  ** This function will be called by DI-Guy when it is time for
913  ** renderer-specific link objects to be created. All information
914  ** necessary to build the link should be available via the Accessor
915  ** Functions above when this function is called.
916  **
917  ** Builds happen in depth-first traversal order, so the parent's
918  ** build() function will always be called before this link's build()
919  ** function.
920  **
921  *i Immediate Mode:
922  **
923  ** Immediate mode renderers usually do not override this function.
924  **
925  *i Scene Graph:
926  **
927  ** Scene graph renderers usually do override this function, to create
928  ** scene graph nodes that allow for the various transformations to
929  ** happen.
930  **
931  ** The following nodes are commonly created:
932  **
933  *- - a static transform node to hold the offsets
934  *- - a dynamic transform node (or DOF) to allow motion data
935  *- to be applied
936  *- - either an LOD or switch node to allow graphics LODs to be
937  *- applied
938  **
939  ** LOD nodes, that automatically handle LOD switching, should be
940  ** created if automatic LOD switching is desired.
941  **
942  ** A switch node should be created if manual setting of the graphics
943  ** LOD is desired.
944  **
945  ** If this link is a position link (it has no parent link), the scene
946  ** graph nodes should not yet be attached to the scene graph; that
947  ** should be done during the call to attach().
948  **
949  ** Otherwise the scene graph nodes should start out attached to their
950  ** attach points (a scene graph node of the parent link).
951  **
952  *b Callable From:
953  **
954  *- - N/A (automatically called by DI-Guy Graphics API during
955  *- the Build Stage)
956  */
957  virtual void build();
958 
959  /*l
960  *b Description:
961  **
962  ** This function will be called by DI-Guy when all links and shapes
963  ** of a DI-Guy character have been built, providing an opportunity
964  ** for final touch-ups to be made to the built hierarchy.
965  **
966  ** This function will be called only for the top-level position link.
967  **
968  *i Immediate Mode:
969  **
970  ** Immediate mode renderers usually do not override this function.
971  **
972  *i Scene Graph:
973  **
974  ** Scene graph renderers sometimes override this function. They
975  ** might to so to do renderer-specific optimizations to the created
976  ** hierarchy.
977  **
978  *b Callable From:
979  **
980  *- - N/A (automatically called by DI-Guy Graphics API during
981  *- the Build Stage)
982  */
983  virtual void post_build();
984 
985  /*l
986  *b Description:
987  **
988  ** This function will be called by DI-Guy when it is time for the
989  ** renderer-specific link objects created during the build() call to
990  ** be destroyed.
991  **
992  ** Unbuilds happen in reverse depth-first traversal order, so this
993  ** link's unbuild() function will always be called before the
994  ** parent's unbuild() function.
995  **
996  *i Immediate Mode:
997  **
998  ** Immediate mode renderers usually do not override this function.
999  **
1000  *i Scene Graph:
1001  **
1002  ** Scene graph renderers usually do override this function, to
1003  ** destroy the scene graph nodes created by build().
1004  **
1005  *b Callable From:
1006  **
1007  *- - N/A (automatically called by DI-Guy Graphics API during
1008  *- the Unbuild Stage)
1009  */
1010  virtual void unbuild();
1011 
1012  /*l
1013  *b Description:
1014  **
1015  ** This function will be called by DI-Guy when it is time for
1016  ** renderer-specific link objects created during the build() call to
1017  ** be attached to their attach points.
1018  **
1019  ** This function will only be called for the position link.
1020  **
1021  *i Immediate Mode:
1022  **
1023  ** Immediate mode renderers usually do not override this function.
1024  **
1025  *i Scene Graph:
1026  **
1027  ** Scene graph renderers usually do override this function, to attach
1028  ** the scene graph nodes created during build() to somewhere on the
1029  ** scene graph.
1030  **
1031  *b Callable From:
1032  **
1033  *- - N/A (automatically called by DI-Guy Graphics API during
1034  *- the Build Stage, and sometimes during the Update Stage)
1035  */
1036  virtual void attach_to_scene();
1037 
1038  /*l
1039  *b Description:
1040  **
1041  ** This function will be called by DI-Guy when it is time for
1042  ** renderer-specific link objects created during the build() call to
1043  ** be detached from their attach points.
1044  **
1045  *i Immediate Mode:
1046  **
1047  ** Immediate mode renderers usually do not override this function.
1048  **
1049  *i Scene Graph:
1050  **
1051  ** Scene graph renderers usually do override this function, to detach
1052  ** the scene graph nodes created during build() from the scene graph.
1053  **
1054  *b Callable From:
1055  **
1056  *- - N/A (automatically called by DI-Guy Graphics API during
1057  *- the Build Stage, and sometimes during the Update Stage)
1058  */
1059  virtual void detach_from_scene();
1060 
1061  /*l
1062  *b Description:
1063  **
1064  ** TODO MARCM
1065  **
1066  *i Immediate Mode:
1067  **
1068  ** Immediate mode renderers usually do not override this function.
1069  **
1070  *i Scene Graph:
1071  **
1072  ** TODO MARCM
1073  **
1074  *b Callable From:
1075  **
1076  *- - N/A (automatically called by DI-Guy Graphics API during
1077  *- the Update Stage)
1078  */
1079  virtual void instancing_state_changed(int instanced);
1080 
1081  /*l
1082  *b Description:
1083  **
1084  ** This function will be called by DI-Guy when it is time for
1085  ** renderer-specific link objects created during the build() call to
1086  ** be updated with new transformation data.
1087  **
1088  ** Updates happen in depth-first traversal order, so the parent's
1089  ** update() function will always be called before this link's
1090  ** update() function.
1091  **
1092  *i Immediate Mode:
1093  **
1094  ** Immediate mode renderers usually do not override this function.
1095  **
1096  *i Scene Graph:
1097  **
1098  ** Scene graph renderers usually do override this function, to update
1099  ** the scene graph nodes created during build() with new values.
1100  **
1101  ** These values should be obtained by calling get_translation(),
1102  ** get_rotation(), and get_scale().
1103  **
1104  *b Callable From:
1105  **
1106  *- - N/A (automatically called by DI-Guy Graphics API during
1107  *- Update Stage)
1108  */
1109  virtual void update();
1110 
1111  /*l
1112  *b Description:
1113  **
1114  ** This function will be called by DI-Guy when it is traversing the
1115  ** link hierarchy to draw.
1116  **
1117  *i Immediate Mode:
1118  **
1119  ** Immediate mode renderers can override this function. Typically
1120  ** some type of transformation matrix stack push operation is
1121  ** performed.
1122  **
1123  *i Scene Graph:
1124  **
1125  ** Scene graph renderers usually do not override this function;
1126  ** transformation states are handled automatically by scene graphs.
1127  **
1128  *b Callable From:
1129  **
1130  *- - N/A (automatically called by DI-Guy Graphics API during
1131  *- Draw Stage)
1132  */
1133  virtual void push();
1134 
1135  /*l
1136  *b Description:
1137  **
1138  ** This function will be called by DI-Guy when it is traversing the
1139  ** link hierarchy to draw.
1140  **
1141  *i Immediate Mode:
1142  **
1143  ** Immediate mode renderers can override this function. Typically
1144  ** some type of transformation matrix stack pop operation is
1145  ** performed.
1146  **
1147  *i Scene Graph:
1148  **
1149  ** Scene graph renderers usually do not override this function;
1150  ** transformation states are handled automatically by scene graphs.
1151  **
1152  *b Callable From:
1153  **
1154  *- - N/A (automatically called by DI-Guy Graphics API during
1155  *- Draw Stage)
1156  */
1157  virtual void pop();
1158 
1159  /*l
1160  *b Description:
1161  **
1162  ** This function will be called by DI-Guy when it is time for the
1163  ** transformations of this link to be applied.
1164  **
1165  *i Immediate Mode:
1166  **
1167  ** Immediate mode renderers usually do override this function, to
1168  ** apply transformations to the transformation stack.
1169  **
1170  *i Scene Graph:
1171  **
1172  ** Scene graph renderers usually do not override this function;
1173  ** transformation states are handled automatically by scene graphs.
1174  **
1175  *b Callable From:
1176  **
1177  *- - N/A (automatically called by DI-Guy Graphics API during
1178  *- Draw Stage)
1179  */
1180  virtual void draw();
1181 
1182  /*l
1183  *b Description:
1184  **
1185  ** This function will be called by DI-Guy when it a shader should be
1186  ** bound to this link. This is important in some scene graph
1187  ** environments, when the scene graph is responsible for binding the
1188  ** shader.
1189  **
1190  *i Immediate Mode:
1191  **
1192  ** Immediate mode renderers usually do not override this function.
1193  **
1194  *i Scene Graph:
1195  **
1196  ** Scene graph renderers can override this function but some don't
1197  ** need to.
1198  **
1199  *b Callable From:
1200  **
1201  *- - N/A (automatically called by DI-Guy Graphics API during
1202  *- Build Stage)
1203  */
1204  virtual void set_shader_instance(diguyGraphicsShaderInstance* shader_instance);
1205 
1206 
1207 
1208 /****************************************************************************/
1213  /*l
1214  *b Description:
1215  **
1216  ** This function will be called by DI-Guy when the drawing of a new
1217  ** character is beginning. This happens when the position link is
1218  ** drawn.
1219  **
1220  *i Immediate Mode:
1221  **
1222  ** Immediate mode renderers can override this function. Typically
1223  ** some type of transformation matrix stack push operation is
1224  ** performed. This is also an appropriate place to do any
1225  ** per-character modifications, such as:
1226  **
1227  *- - applying scale
1228  *- - applying the base translation of the character
1229  *- - picking a current LOD
1230  *- - etc.
1231  **
1232  *i Scene Graph:
1233  **
1234  ** Scene graph renderers usually do not override this function;
1235  ** transformation states are handled automatically by scene graphs.
1236  **
1237  *b Callable From:
1238  **
1239  *- - N/A (automatically called by DI-Guy Graphics API during
1240  *- Draw Stage)
1241  */
1242  virtual void begin_character_draw();
1243 
1244  /*l
1245  *b Description:
1246  **
1247  ** This function will be called by DI-Guy when the drawing traversal
1248  ** of the character's link hierarchy has completed.
1249  **
1250  *i Immediate Mode:
1251  **
1252  ** Immediate mode renderers can override this function. Typically
1253  ** any matrix stack push operation done in begin_character_draw()
1254  ** is undone here by an appropriate pop operation.
1255  **
1256  *i Scene Graph:
1257  **
1258  ** Scene graph renderers usually do not override this function;
1259  ** transformation states are handled automatically by scene graphs.
1260  **
1261  *b Callable From:
1262  **
1263  *- - N/A (automatically called by DI-Guy Graphics API during
1264  *- Draw Stage)
1265  */
1266  virtual void end_character_draw();
1267 
1268 
1269 #endif
1270 
1271  /*l
1272  *b Description:
1273  **
1274  ** This value corresponds to bdiGraphicsInitGraphicsAPI.use_linear_traversal_draw.
1275  ** As of DI-Guy 13 this can only be true.
1276  **
1277  *e
1278  *e //linear draw behavior
1279  *e {
1280  *e // push the base transform of the character in the world
1281  *e // the get_transformation_matrix() of the position link
1282  *e m_position_link->begin_character_draw();
1283  *e int i;
1284  *e for each link in link array
1285  *e {
1286  *e // note the ability to skip links with nothing attached to them
1287  *e if (link->get_num_shapes() > 0 || link->get_is_position_link())
1288  *e {
1289  *e // each link should multiply by the get_local_transformation_matrix
1290  *e // which contains the precalculated concatenated matrix
1291  *e link->push();
1292  *e link->draw();
1293  *e link->pop();
1294  *e }
1295  *e }
1296  *e m_position_link->end_character_draw();
1297  */
1298  static void set_use_linear_traversal_draw(int mode);
1299 
1300  /*l
1301  *b Description:
1302  **
1303  ** This is always true as of DI-Guy 13. See set_use_linear_traversal_draw().
1304  */
1305  static int get_use_linear_traversal_draw();
1306 
1307 
1308 /****************************************************************************/
1309 /****************************************************************************/
1316 /****************************************************************************/
1317 /****************************************************************************/
1318 
1319  // Documentation Pending
1320  int get_inverse_rotation_matrix(float matrix_array[4][4], int transpose = 0,
1321  int include_translation = 1);
1322 
1323  // Documentation Pending
1324  int get_inverse_rotation_matrix_4x4_ptr(float* matrix_array, int transpose = 0,
1325  int include_translation = 1);
1326 
1327 
1328 /****************************************************************************/
1329 /****************************************************************************/
1340 /****************************************************************************/
1341 /****************************************************************************/
1342 /****************************************************************************/
1343 
1344  /*l
1345  *b Description:
1346  **
1347  ** Deprecated as of 9.1.4; use diguyGraphicsLink::get_is_position_link()
1348  ** instead.
1349  */
1350  int get_is_base_link();
1351 
1352  /*l
1353  *b Description:
1354  **
1355  ** Deprecated as of 12.0.0 due to architecture change
1356  */
1357  int get_shader_matrix_index();
1358 
1359 
1360 /****************************************************************************/
1361 /****************************************************************************/
1362 
1367 #ifdef CPLUSPLUS_ONLY
1368 
1369  bdiLink* get_scripted_object() {return m_scripted_object;}
1370 
1371 protected:
1372 
1373  /*l
1374  ** A protected constructor. Constructors are called automatically
1375  ** by DI-Guy.
1376  */
1377  diguyGraphicsLink(void* internal_data);
1378 
1379  /*l
1380  ** A protected destructor. Destructors are called automatically
1381  ** by DI-Guy.
1382  */
1383  virtual ~diguyGraphicsLink();
1384 
1385 private:
1386 
1387  /*l
1388  ** A pointer to internal data.
1389  */
1390  bdiLink* m_scripted_object;
1391 
1392  friend class bdiLink;
1393  friend class bdiGraphicsFactory;
1394 
1395 #endif
1396 
1397 };
1398 
1399 
1400 #endif /* __diguyGraphicsLink_H */
1401