DI-Guy C++ SDK Reference  13.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguySceneObject.h
Go to the documentation of this file.
1 
2 /*********************************************************************
3  ** Copyright (c) 1992-2014 VT MAK
4  ** All rights reserved.
5  *********************************************************************/
6 
7 /*********************************************************************
8  **
9  *t diguySceneObject
10  **
11  *b Link against: libdiguy
12  */
13 
14 #ifndef __diguySceneObject_H
15 #define __diguySceneObject_H
16 
17 #ifdef SWIG
18 %module diguySceneObject
19 #else
20 #define CPLUSPLUS_ONLY
21 #endif
22 
23 #ifdef CPLUSPLUS_ONLY
24 class bdiScenarioSceneObject;
25 #endif
26 
27 #include <declspec_diguy.h>
28 #include <diguy_constants.h>
29 #include <stdio.h> // for NULL
30 
31 class diguyGraphicsShaderInstance;
32 class diguyGraphicsShaderProgram;
33 class diguyGraphicsShaderTechnique;
34 
35 /****************************************************************************/
36 class BDI_DECLSPEC_diguy diguySceneObject
37 {
38 
39 public:
40 
41  /*l
42  *b Description:
43  **
44  ** Returns the name of the scene object. This pointer will
45  ** never be NULL.
46  **
47  *b Returns:
48  **
49  ** name of the scene object
50  **
51  *b Callable From:
52  **
53  *- - C++
54  *- - Script
55  */
56  const char* get_name();
57 
58  /*l
59  *b Description:
60  **
61  ** This function sets the name of this object.
62  **
63  *b Returns:
64  **
65  ** 0 on success, -1 on failure
66  **
67  *b Callable From:
68  **
69  *- - C++
70  *- - Script
71  */
72  int set_name(const char* name);
73 
74  /*l
75  *b Description:
76  **
77  ** All scene objects are assigned a unique identifier, or uid. This
78  ** function returns this scene object's uid.
79  **
80  ** *Note*: unique identifiers will change between DI-Guy runs!
81  **
82  *b Returns:
83  **
84  ** unique identifier of object
85  **
86  *b Callable From:
87  **
88  *- - C++
89  *- - Script
90  */
91  long get_uid();
92 
93  /*l
94  *b Description:
95  **
96  ** Returns the filename of the scene object. This pointer will
97  ** never be NULL.
98  **
99  ** The returned filename may be relative to another directory,
100  ** such as $DIGUY/geometry/sets. Call get_fully_resolved_filename()
101  ** to have DI-Guy search for the fully resolved filename.
102  **
103  *b Returns:
104  **
105  ** filename of the scene object
106  **
107  *b Callable From:
108  **
109  *- - C++
110  *- - Script
111  */
112  const char* get_filename();
113 
114  /*l
115  *b Returns:
116  **
117  ** node within the scene object file; returned string is 0 length if
118  ** contents of entire file should be used
119  **
120  *b Callable From:
121  **
122  *- - C++
123  *- - Script
124  */
125  const char* get_nodename();
126 
127  /*l
128  *b Returns:
129  **
130  ** alternate filename of the scene object
131  **
132  *b Callable From:
133  **
134  *- - C++
135  *- - Script
136  */
137  const char* get_alternate_filename();
138 
139  /*l
140  *b Description:
141  **
142  ** Returns the fully resolved filename of the scene object. Returns
143  ** NULL if the file cannot be found.
144  **
145  *b Returns:
146  **
147  ** fully resolved filename of the scene object; NULL if not found
148  **
149  *b Callable From:
150  **
151  *- - C++
152  *- - Script
153  */
154  const char* get_fully_resolved_filename();
155 
156  /*l
157  *b Description:
158  **
159  ** Attempts to load the file returned by get_filename() and
160  ** construct an object that can be rendered in the current
161  ** graphics environment by the call draw_visual().
162  **
163  *b Returns:
164  **
165  ** 0 on success, -1 on failure
166  **
167  *i OpenGL Version:
168  **
169  ** Function will create OpenGL display lists.
170  **
171  *i Direct3D Version:
172  **
173  ** Function will have no effect. User must load and display object.
174  **
175  *b Callable From:
176  **
177  *- - C++
178  *- - Script
179  */
180  int show();
181 
182  /*l
183  *b Description:
184  **
185  ** Hides the scene object. See show() for notes on which
186  ** platforms do not yet display scene objects.
187  **
188  *b Returns:
189  **
190  ** 0 on success, -1 on failure
191  **
192  *b Callable From:
193  **
194  *- - C++
195  *- - Script
196  */
197  int hide();
198 
199  /*l
200  *b Description:
201  **
202  ** Adds a vertex to a user defined scene object.
203  **
204  *b Returns:
205  **
206  ** 0 on success, -1 on failure
207  */
208  int add_vertex_to_user_defined(float x, float y, float z);
209 
210  /*l
211  *b Description:
212  **
213  ** Adds a triangle to a user defined scene object.
214  ** Indices refer to vertices added with a add_vertex_* call.
215  **
216  *b Returns:
217  **
218  ** 0 on success, -1 on failure
219  */
220  int add_triangle_to_user_defined(int index0, int index1, int index2);
221 
222 #ifdef CPLUSPLUS_ONLY
223  /*l
224  *b Description:
225  **
226  ** Adds an array of vertices to a user defined scene object.
227  **
228  *b Arguments:
229  **
230  *a skipBytes - bytes between vertex position information
231  **
232  *b Returns:
233  **
234  ** 0 on success, -1 on failure
235  */
236  int add_vertex_array_to_user_defined(const float* const vertices,
237  int num_vertices, int skipBytes = 12);
238 
239  /*l
240  *b Description:
241  **
242  ** Adds an array of triangles to a user defined scene object.
243  ** The array should contain indices to vertices added with add_vertex_* calls.
244  **
245  *b Arguments:
246  **
247  *a num_indices - Number of indices (3 indices per triangle).
248  **
249  *b Returns:
250  **
251  ** 0 on success, -1 on failure
252  */
253  int add_triangle_array_to_user_defined(const int* const indices, int num_indices);
254 
255  /*l
256  *b Description:
257  **
258  ** Adds a triangle to a user defined object.
259  ** Positions are expected to be float[3].
260  **
261  *b Returns:
262  **
263  ** 0 on success, -1 on failure
264  */
265  int add_triangle_to_user_defined(const float* const pos0,
266  const float* const pos1, const float* const pos2);
267 #endif
268 
269  /*l
270  *b Description:
271  **
272  ** Builds the geometry of the user defined scene object
273  ** from data passed via add_vertex_* and add_triangle_* calls.
274  **
275  *b Returns:
276  **
277  ** 0 on success, -1 on failure
278  */
279  int build_user_defined();
280 
281 
282 /*****************************************************************************/
288  /*l
289  *b Description:
290  **
291  ** This function is essentially the same as the function
292  ** diguyCharacter::set_render_mode_shader(), but applies to this
293  ** scene object.
294  **
295  *b Returns:
296  **
297  ** 0 on success, -1 on failure
298  **
299  *b Callable From:
300  **
301  *- - C++
302  *- - Script
303  */
304  int set_render_mode_shader(const char* shader_name,
305  const char* render_mode = NULL);
306 
307  /*l
308  *b Description:
309  **
310  ** This function is essentially the same as the function
311  ** diguyCharacter::reset_render_mode_shader_to_default(), but
312  ** applies to this scene object.
313  **
314  *b Callable From:
315  **
316  *- - C++
317  *- - Script
318  */
319  void reset_render_mode_shader_to_default(const char* render_mode = NULL);
320 
321  /*l
322  *b Description:
323  **
324  ** This function is essentially the same as the function
325  ** diguyCharacter::get_render_mode_shader(), but applies to this to
326  ** this scene object.
327  **
328  *b Returns:
329  **
330  ** name of shader program; NULL if none
331  **
332  *b Callable From:
333  **
334  *- - C++
335  *- - Script
336  */
337  const char* get_render_mode_shader(const char* render_mode = NULL);
338 
339  /*l
340  *b Description:
341  **
342  ** This function is essentially the same as the function
343  ** diguyCharacter::get_shader_program(), but applies to this to
344  ** this scene object. It's here for backwards compatibility DI-Guy 12
345  ** now uses shader techniques as wrappers for shader programs.
346  **
347  *b Returns:
348  **
349  ** object of type diguyGraphicsShaderProgram; NULL if none
350  **
351  *b Callable From:
352  **
353  *- - C++
354  *- - Script
355  */
356  diguyGraphicsShaderProgram* get_shader_program();
357 
358  /*l
359  *b Description:
360  **
361  ** This function is essentially the same as the function
362  ** diguyCharacter::get_shader_technique(), but applies to this to
363  ** this scene object.
364  **
365  *b Returns:
366  **
367  ** object of type diguyGraphicsShaderTechnique; NULL if none
368  **
369  *b Callable From:
370  **
371  *- - C++
372  *- - Script
373  */
374  diguyGraphicsShaderTechnique* get_shader_technique();
375 
376  /*l
377  *b Description:
378  **
379  ** This function is essentially the same as the function
380  ** diguyCharacter::set_temporary_current_shader_program(), but
381  ** applies to this to this scene object.
382  **
383  *b Returns:
384  **
385  ** 0 on success, -1 on failure
386  **
387  *b Callable From:
388  **
389  *- - C++
390  *- - Script
391  */
392  int set_temporary_current_shader(const char* shader_name);
393 
394  /*l
395  *b Description:
396  **
397  ** This function is essentially the same as the function
398  ** diguyCharacter::reset_current_shader_to_default(), but
399  ** applies to this to this scene object.
400  **
401  *b Callable From:
402  **
403  *- - C++
404  *- - Script
405  */
406  void reset_current_shader_to_default();
407 
408  /*l
409  *b Description:
410  **
411  ** This function is essentially the same as the function
412  ** diguyCharacter::get_shader_instance(), but applies to this to
413  ** this scene object.
414  **
415  ** Note that the shader instance of a scene object can change over
416  ** the lifetime of the scene object. Therefore the returned pointer
417  ** should not be stored, but should be re-read each time it is
418  ** needed.
419  **
420  *b Returns:
421  **
422  ** object of type diguyGraphicsShaderInstance; NULL if none
423  **
424  *b Callable From:
425  **
426  *- - C++
427  *- - Script
428  */
429  diguyGraphicsShaderInstance* get_shader_instance();
430 
431  /*l
432  *b Description:
433  **
434  ** This function is essentially the same as the function
435  ** diguyCharacter::reset_shader_instance_variables_to_initial_values(),
436  ** but applies to this scene object.
437  **
438  *b Callable From:
439  **
440  *- - C++
441  *- - Script
442  */
443  void reset_shader_instance_variables_to_initial_values();
444 
445  /*l
446  *b Description:
447  **
448  ** This function is essentially the same as the function
449  ** diguyCharacter::reset_shader_instance_variables_to_program_defaults(),
450  ** but applies to this scene object.
451  **
452  *b Callable From:
453  **
454  *- - C++
455  *- - Script
456  */
457  void reset_shader_instance_variables_to_program_defaults();
458 
459 
460 /*****************************************************************************/
465  /*l
466  *b Description:
467  **
468  ** Set the state of a switch belonging to this scene object.
469  ** Currently only supported on OpenGL platform.
470  **
471  *b Arguments:
472  **
473  *a switch_name - the name of the switch element
474  *a state - the state, i.e. active sub-element, of the switch
475  **
476  *b Returns:
477  **
478  ** 0 on success, -1 on failure
479  **
480  *b Callable From:
481  **
482  *- - C++
483  *- - Script
484  */
485  int set_switch_state(const char* switch_name,
486  int state);
487 
488  /*l
489  *b Description:
490  **
491  ** Get the state of a switch belonging to this scene object.
492  ** Currently only supported on OpenGL platform.
493  **
494  *b Arguments:
495  **
496  *a switch_name - the name of the switch element
497  **
498  *b Returns:
499  **
500  ** The state of the switch, -1 if fails.
501  **
502  *b Callable From:
503  **
504  *- - C++
505  *- - Script
506  */
507  int get_switch_state(const char* switch_name);
508 
509  /*l
510  *b Description:
511  **
512  ** Set the state of a DOF element belonging to this scene object.
513  ** Currently only supported on OpenGL platform.
514  **
515  *b Arguments:
516  **
517  *a dof_name - the name of the DOF element
518  *a tx, ty, tz - the x, y, and z displacements of the DOF
519  *a rz, rx, ry - the rotation of the DOF about the z, x, and y axes
520  **
521  ** The DOF will be rotated in ZXY order. For rotation in XYZ order,
522  ** use set_dof_state_flt().
523  **
524  *b Returns:
525  **
526  ** 0 on success, -1 on failure
527  **
528  *b Callable From:
529  **
530  *- - C++
531  *- - Script
532  */
533  int set_dof_state(const char* dof_name,
534  float tx, float ty, float tz,
535  float rz, float rx, float ry);
536 
537  /*l
538  *b Description:
539  **
540  ** Set the state of a DOF element belonging to this scene object.
541  ** Currently only supported on OpenGL platform.
542  **
543  *b Arguments:
544  **
545  *a dof_name - the name of the DOF element
546  *a tx, ty, tz - the x, y, and z displacements of the DOF
547  *a rz, rx, ry - the rotation of the DOF about the z, x, and y axes
548  **
549  ** The DOF will be rotated in XYZ order.
550  ** For rotation in ZXY order, use set_dof_state().
551  **
552  *b Returns:
553  **
554  ** 0 on success, -1 on failure
555  **
556  *b Callable From:
557  **
558  *- - C++
559  *- - Script
560  */
561  int set_dof_state_flt(const char* dof_name,
562  float tx, float ty, float tz,
563  float rx, float ry, float rz);
564 
565  /*l
566  *b Description:
567  **
568  ** Get the state of a DOF element belonging to this scene object.
569  ** Currently only supported on OpenGL platform.
570  **
571  *b Arguments:
572  **
573  *a dof_name - the name of the DOF element
574  *a tx, ty, tz - the x, y, and z displacements of the DOF
575  *a rz, rx, ry - the rotation of the DOF about the z-, x-, and y-axes
576  **
577  ** The returned rotation values assume ZXY order. For XYZ order, use
578  ** get_dof_state_flt().
579  **
580  *b Returns:
581  **
582  ** 0 on success, -1 on failure
583  **
584  *b Callable From:
585  **
586  *- - C++
587  *- - Script
588  */
589  int get_dof_state(const char* dof_name,
590  float* tx, float* ty, float* tz,
591  float* rz, float* rx, float* ry);
592 
593  /*l
594  *b Description:
595  **
596  ** Get the state of a DOF element belonging to this scene object.
597  ** Currently only supported on OpenGL platform.
598  **
599  *b Arguments:
600  **
601  *a dof_name - the name of the DOF element
602  *a tx, ty, tz - the x, y, and z displacements of the DOF
603  *a rx, ry, rz - the rotation of the DOF about the z-, x-, and y-axes
604  **
605  ** The returned rotation values assume ZXY order. For XYZ order, use
606  ** get_dof_state_flt().
607  **
608  *b Returns:
609  **
610  ** 0 on success, -1 on failure
611  **
612  *b Callable From:
613  **
614  *- - C++
615  *- - Script
616  */
617  int get_dof_state_flt(const char* dof_name,
618  float* tx, float* ty, float* tz,
619  float* rx, float* ry, float* rz);
620 
621  /*l
622  *b Description:
623  **
624  ** Set a trigger to change the state of a switch at a given time.
625  ** Currently only supported on OpenGL platform.
626  **
627  *b Arguments:
628  **
629  *a switch_name - the name of the switch to be triggered
630  *a state - the state the switch should be in after time t
631  *a t - the time at which the switch should switch
632  **
633  *b Returns:
634  **
635  ** 0 on success, -1 on failure
636  **
637  *b Callable From:
638  **
639  *- - C++
640  *- - Script
641  */
642  int add_switch_target(const char* switch_name,
643  int state,
644  float t);
645 
646  /*l
647  *b Description:
648  **
649  ** Abort all the targets states for a given switch
650  ** which have been set either using the DI-Guy function,
651  ** add_dof_target() or using a behavior file.
652  ** Currently only supported on OpenGL platform.
653  **
654  *b Arguments:
655  **
656  *a switch_name - the name of the switch whose targets are to be
657  *a aborted
658  **
659  *b Returns:
660  **
661  ** 0 on success, -1 on failure
662  **
663  *b Callable From:
664  **
665  *- - C++
666  *- - Script
667  */
668  int abort_all_switch_targets(const char* switch_name);
669 
670  /*l
671  *b Description:
672  **
673  ** Set a trigger to change the state of a DOF at a given time.
674  ** Currently only supported on OpenGL platform.
675  **
676  *b Arguments:
677  **
678  *a dof_name - the name of the DOF element
679  *a tx, ty, tz - the x, y, and z displacements of the DOF
680  *a rz, rx, ry - the rotation of the DOF about the z-, x-, and y-axes
681  *a blend_tin - the time at which the DOF should begin changing states
682  *a blend_tout - the time at which the DOF should stop changing states
683  *a blend_function_name - the type of interpolation to be used between
684  *a the current and desired DOF states
685  **
686  ** Currently, valid function names are "Linear", "HalfSine", and
687  ** "QuarterSine".
688  **
689  ** The DOF will be rotated in ZXY order. For rotation in XYZ order,
690  ** use set_dof_state_flt().
691  **
692  *b Returns:
693  **
694  ** 0 on success, -1 on failure
695  **
696  *b Callable From:
697  **
698  *- - C++
699  *- - Script
700  */
701  int add_dof_target(const char* dof_name,
702  float tx, float ty, float tz,
703  float rz, float rx, float ry,
704  float blend_tin, float blend_tout,
705  const char* blend_function_name = 0);
706 
707  /*l
708  *b Description:
709  **
710  ** Set a trigger to change the state of a DOF at a given time.
711  ** Currently only supported on OpenGL platform.
712  **
713  *b Arguments:
714  **
715  *a dof_name - the name of the DOF element
716  *a tx, ty, tz - the x, y, and z displacements of the DOF
717  *a rx, ry, rz - the rotation of the DOF about the z-, x-, and y-axes
718  *a The DOF will be rotated in XYZ order.
719  *a For rotation in ZXY order, use add_dof_target().
720  *a blend_tin - the time at which the DOF should begin changing states
721  *a blend_tout - the time at which the DOF should stop changing states
722  *a blend_function_name - the type of interpolation to be used between
723  *a the current and desired DOF states
724  **
725  ** Currently, valid function names are "Linear", "HalfSine", and
726  ** "QuarterSine".
727  **
728  ** The DOF will be rotated in XYZ order. For rotation in ZXY order,
729  ** use set_dof_state_flt().
730  **
731  *b Returns:
732  **
733  ** 0 on success, -1 on failure
734  **
735  *b Callable From:
736  **
737  *- - C++
738  *- - Script
739  */
740  int add_dof_target_flt(const char* dof_name,
741  float tx, float ty, float tz,
742  float rx, float ry, float rz,
743  float blend_tin, float blend_tout,
744  const char* blend_function_name = 0);
745 
746  /*l
747  *b Description:
748  **
749  ** Abort all the targets states for a given DOF
750  ** which have been set either using the DI-Guy function,
751  ** add_dof_target() or using a behavior file.
752  ** Currently only supported on OpenGL platform.
753  **
754  *b Arguments:
755  **
756  *a dof_name - the name of the DOF whose targets are to be aborted
757  **
758  *b Returns:
759  **
760  ** 0 on success, -1 on failure
761  **
762  *b Callable From:
763  **
764  *- - C++
765  *- - Script
766  */
767  int abort_all_dof_targets(const char* dof_name);
768 
769  /*l
770  ** Deprecated as of 10.5.2. Use set_shader_program_name() instead.
771  */
772  int set_shader_program(const char* shader_name);
773 
774 
775 /****************************************************************************/
776 /****************************************************************************/
777 /****************************************************************************/
784 /****************************************************************************/
785 /****************************************************************************/
786 /****************************************************************************/
787 
788  /*
789  * Documentation Pending.
790  */
791  int set_position(float x, float y, float z);
792  int get_position(float* x, float* y, float* z);
793 
794  int set_orientation(float rz, float rx, float ry);
795  int get_orientation(float* rz, float* rx, float* ry);
796 
797  int set_scale(float sx, float sy, float sz);
798  int get_scale(float* sx, float* sy, float* sz);
799 
800  int set_filename(const char* file_name);
801  int get_is_sky_box();
802  int set_is_sky_box(int skybox);
803 
804  /*l
805  * Documentation Pending
806  * should be a member of diguyGraphicsTextureLoadingBehavior
807  * DIGUY_LOAD_INSTANTLY, DIGUY_LOAD_PRIORITY_ASYNC, DIGUY_LOAD_ASYNC
808  */
809  static int set_texture_load_behavior(diguyGraphicsTextureLoadingBehavior mode);
810  static diguyGraphicsTextureLoadingBehavior get_texture_load_behavior();
811 
812 
813 #ifdef CPLUSPLUS_ONLY
814 
815  /*l
816  *b Description:
817  **
818  ** Draws the scene object.
819  **
820  *i Currently OpenGL only.
821  **
822  *b Returns:
823  **
824  ** 0 on success, -1 on failure
825  **
826  *b Callable From:
827  **
828  *- - C++
829  */
830  int draw_visual();
831 
832 #endif
833 
834  int get_include_in_octtree();
835  int set_include_in_octtree(int val);
836 
837  int set_include_in_physics_sim_scene(int include_in_simulation_terrain);
838  int get_include_in_physics_sim_scene();
839 
840  int set_physics_collision_group(diguyPhysicsCollisionGroup collision_group);
841  diguyPhysicsCollisionGroup get_physics_collision_group();
842 
843  int get_min(float* x, float* y, float* z);
844  int get_max(float* x, float* y, float* z);
845 
846  /*
847  * DI-Guy doesn't use these masks internally, but they can be useful
848  * for some DI-Guy Graphics API scene graph implementations.
849  */
850  void set_scene_graph_mask(unsigned int mask);
851  unsigned int get_scene_graph_mask();
852 
853  int get_enabled();
854  int set_enabled(int enabled);
855 
856  int get_visible();
857  int set_visible(int visible);
858 
863 #ifdef CPLUSPLUS_ONLY
864 
865 public:
866 
867  bdiScenarioSceneObject* get_scripted_object() {return m_scripted_object;}
868 
869 
870 
871 private:
872 
873  /*l
874  ** A private constructor.
875  */
876  diguySceneObject(bdiScenarioSceneObject* scene_object);
877 
878  /*l
879  ** A private destructor.
880  */
881  ~diguySceneObject();
882 
883  /*l
884  ** A pointer to internal data.
885  */
886  bdiScenarioSceneObject* m_scripted_object;
887 
888  friend class bdiScenarioSceneObject;
889 
890 #endif
891 
892 };
893 
894 #endif /* __diguySceneObject_H */
895