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