DI-Guy C++ SDK Reference  13.0
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
diguyCharacterPoseOverride.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  **
10  *t diguyCharacterPoseOverride
11  **
12  */
13 
14 #ifndef __diguyCharacterPoseOverride_H
15 #define __diguyCharacterPoseOverride_H
16 
17 
18 #ifdef SWIG
19 %module diguyCharacterPoseOverride
20 #else
21 #define CPLUSPLUS_ONLY
22 #endif
23 
24 #ifdef CPLUSPLUS_ONLY
25 #include <stdlib.h>
26 
27 class bdiPoseOverride;
28 class bdiScenarioCharacter;
29 class bdiTopology;
30 #endif
31 
32 
33 #include <declspec_diguy.h>
34 
35 /****************************************************************************/
36 class BDI_DECLSPEC_diguy diguyCharacterPoseOverride
37 {
38 
39 public:
40 
41 #ifdef CPLUSPLUS_ONLY
42 
43  /*l
44  *b Description:
45  **
46  ** Allocates an array of floats to hold the joint angles for
47  ** each degree of freedom, or weights to specify how pose angles
48  ** will affect a character. The size of the array will be equal
49  ** to the value returned by get_num_vars().
50  **
51  ** The allocated array should be freed by calling free_pose_array().
52  **
53  ** The allocated array will contain uninitialized values.
54  **
55  ** If the array is to hold weights, each entry in the array
56  ** should be set to a valid value between 0.0 and 1.0.
57  **
58  ** If the array is to hold pose angles, each pose variable whose
59  ** corresponding weight is going to be non-0 should be set to a
60  ** valid value.
61  **
62  *b Returns:
63  **
64  ** pointer to array of floats, NULL if the array cannot be allocated
65  **
66  *b Callable From:
67  **
68  *- - C++
69  **
70  *b C++ Example:
71  **
72  ** See example for set_pose_in_radians().
73  */
74  float* allocate_pose_array();
75 
76  /*l
77  *b Description:
78  **
79  ** Frees an array allocated with allocate_pose_array().
80  **
81  *b Arguments:
82  **
83  *a array - array of pose angles to be freed
84  **
85  *b Returns:
86  **
87  ** 0 on success, -1 on failure
88  **
89  *b Callable From:
90  **
91  *- - C++
92  */
93  int free_pose_array(float* array);
94 
95 #endif
96 
97  /*l
98  *b Description:
99  **
100  ** This function returns the number of the variables
101  ** representing joint angles.
102  **
103  *b Returns:
104  **
105  ** an integer representing the number of joint angles
106  **
107  *b Callable From:
108  **
109  *- - C++
110  *- - Script
111  */
112  int get_num_vars();
113 
114 #ifdef CPLUSPLUS_ONLY
115 
116  /*l
117  *b Description:
118  **
119  ** This function allocates an array of pointer to char*s
120  ** (i.e., C-style strings).
121  **
122  ** This array can then be passed to get_var_names().
123  **
124  ** It should be freed using the function free_var_names().
125  ** The size of the array will be equal to the value returned
126  ** by get_num_vars().
127  **
128  *b Returns:
129  **
130  ** an array of pointers to char*'s (i.e. pointers to strings)
131  **
132  *b Callable From:
133  **
134  *- - C++
135  **
136  *b C++ Example:
137  **
138  ** See example for get_var_names().
139  */
140  char** allocate_var_names();
141 
142  /*l
143  *b Description:
144  **
145  ** This function fills out the passed array of strings with
146  ** the list of the names of the variables representing joint
147  ** angles.
148  **
149  *b Arguments:
150  **
151  *a var_names - an array of strings as allocated by
152  *a allocate_var_names()
153  **
154  *b Returns:
155  **
156  ** 0 on success, -1 on failure
157  **
158  *b Callable From:
159  **
160  *- - C++
161  **
162  *b C++ Example:
163  **
164  *e //
165  *e // Create a pose override for character.
166  *e //
167  *e pose_override = character1->create_pose_override();
168  *e
169  *e //
170  *e // Allocate a list of joint angle names and fill it.
171  *e // Print the joint angle names, then destroy the array.
172  *e //
173  *e char** varnames = pose_override->allocate_var_names();
174  *e pose_override->get_var_names(varnames);
175  *e
176  *e for (i = 0; i < character1->get_pose_array_size(); i++)
177  *e bdi_log_printf(BDI_LOG_INFO, "%s\n", varnames[i]);
178  *e
179  *e pose_override->free_var_names(varnames);
180  */
181  int get_var_names(char** var_names);
182 
183  /*l
184  *b Description:
185  **
186  ** This function frees the array of strings allocated by
187  ** allocate_var_names().
188  **
189  *b Arguments:
190  **
191  *a var_names - an array of strings as allocated by
192  *a allocate_var_names()
193  **
194  *b Returns:
195  **
196  ** 0 on success, -1 on failure
197  **
198  *b Callable From:
199  **
200  *- - C++
201  */
202  int free_var_names(char** var_names);
203 
204  /*l
205  *b Description:
206  **
207  ** Get the index of the given variable in the array of pose angles.
208  **
209  *b Arguments:
210  **
211  *a varname - the name of the pose angle variable whose index is desired
212  **
213  *b Returns:
214  **
215  ** index of the pose variable, if it exists, -1 if not
216  **
217  *b Callable From:
218  **
219  *- - C++
220  **
221  *b C++ Example:
222  **
223  ** See example for set_pose_in_radians().
224  */
225  int get_var_index(const char* varname);
226 
227  /*l
228  *b Description:
229  **
230  ** This function fills out the passed array of floats with the most
231  ** recent values passed in a call to set_pose_in_radians().
232  **
233  ** Note that this may not be the actual pose of the character; this
234  ** is only the pose angles for this specific pose override. Other
235  ** pose overrides, gazing, etc., will also affect the pose of the
236  ** character. Use the function diguyCharacter::get_pose_in_radians()
237  ** to read the "real" pose of the character, as computed by the DI-Guy
238  ** motion engine.
239  **
240  *b Arguments:
241  **
242  *a pose_array - array of floats allocated by allocate_pose_array()
243  **
244  *b Returns:
245  **
246  ** 0 on success, -1 on failure
247  **
248  *b Callable From:
249  **
250  *- - C++
251  */
252  int get_pose_in_radians(float* pose_array);
253 
254  /*l
255  *b Description:
256  **
257  ** This function specifies the joint angle data that will modify
258  ** or override the joint angles the character normally computes.
259  ** The replacement data is in pose_array.
260  **
261  ** If weights array is non-NULL, then each element specifies the
262  ** proportion of the value on pose array to mix in with the value
263  ** normally computed by the character. A weight of 0.0 means to
264  ** ignore the value in pose_array. A weight of 1.0 means fully
265  ** override the value computed by the character.
266  **
267  ** If weights_array is NULL, then default_weight will be used for
268  ** *all* of the joint angles.
269  **
270  ** Note that all weights for an Euler triple (e.g. -
271  ** q.cervical_rz/rx/ry) must be equal to ensure proper
272  ** interpolation.
273  **
274  ** Also note that the first six variables that contain the character's
275  ** overall position and orientation cannot be changed using a pose
276  ** override. These values must be changed using the functions
277  ** diguyCharacter::set_position() and
278  ** diguyCharacter::set_orientation().
279  **
280  *b Arguments:
281  **
282  *a pose_array - the array containing the pose angles for this
283  *a override object
284  *a weight_array - the multiplier used to determine how the new
285  *a pose_array values are to be combined with the
286  *a existing pose
287  *a default_weight - the value to be used to set the weights if
288  *a weights_array is NULL
289  **
290  *b Returns:
291  **
292  ** 0 on success, -1 on failure
293  **
294  *b Callable From:
295  **
296  *- - C++
297  **
298  *b C++ Example:
299  **
300  *e //
301  *e // Create a pose override for character.
302  *e //
303  *e pose_override = character1->create_pose_override();
304  *e
305  *e //
306  *e // Allocate an array for pose angles.
307  *e //
308  *e pose_array = pose_override->allocate_pose_array();
309  *e for (i=0; i<pose_override->get_num_vars(); i++)
310  *e pose_array[i] = 0.0f;
311  *e
312  *e //
313  *e // Allocate a weights_array, and initialize it to all 0s.
314  *e //
315  *e weights_array = pose_override->allocate_pose_array();
316  *e for (i=0; i<pose_override->get_num_vars(); i++)
317  *e weights_array[i] = 0.0f;
318  *e
319  *e //
320  *e // Find the indices of the character's back angles. Set the
321  *e // weights for these angles in weights_array to 1.0. This
322  *e // means that when we call set_pose_in_radians(), the values
323  *e // in pose_array will completely override the original
324  *e // data for the back.
325  *e //
326  *e back_rz_index = pose_override->get_var_index("q.back_rz");
327  *e back_rx_index = pose_override->get_var_index("q.back_rx");
328  *e back_ry_index = pose_override->get_var_index("q.back_ry");
329  *e
330  *e pose_array[back_rz_index] = 0.57f; // angle measured in radians
331  *e pose_array[back_rx_index] = 0.0f; // angle measured in radians
332  *e pose_array[back_ry_index] = 0.0f; // angle measured in radians
333  *e
334  *e weights_array[back_rz_index] = 1.0f;
335  *e weights_array[back_rx_index] = 1.0f;
336  *e weights_array[back_ry_index] = 1.0f;
337  *e
338  *e pose_override->set_pose_in_radians(pose_array,
339  *e weights_array,
340  *e 0.0f);
341  */
342  int set_pose_in_radians(float* pose_array,
343  float* weights_array = NULL,
344  float default_weight = 1.0f);
345 
346 #endif
347 
348  /*l
349  *b Description:
350  **
351  ** Get the default weight for pose angles.
352  **
353  *b Returns:
354  **
355  ** the default pose angle weight
356  **
357  *b Callable From:
358  **
359  *- - C++
360  *- - Script
361  */
362  float get_default_weight();
363 
364  /*l
365  *b Description:
366  **
367  ** Set the default weight for pose angles.
368  **
369  ** The default weight will be used to set values in a pose's weights
370  ** array if the array passed in, for instance, set_pose_in_radians(),
371  ** is NULL.
372  **
373  *b Arguments:
374  **
375  *a default_weight - the desired default weight
376  **
377  *b Returns:
378  **
379  ** 0 on success, -1 on failure
380  **
381  *b Callable From:
382  **
383  *- - C++
384  *- - Script
385  */
386  int set_default_weight(float default_weight);
387 
388 
393 #ifdef CPLUSPLUS_ONLY
394 
395  bdiPoseOverride* get_scripted_object() {return m_scripted_object;}
396 
397 private:
398 
399  /*
400  * private constructor
401  */
402  diguyCharacterPoseOverride(bdiPoseOverride* scripted_object,
403  bdiScenarioCharacter* character);
404 
405  /*
406  * private destructor
407  */
408  virtual ~diguyCharacterPoseOverride();
409 
410  /*
411  * internal data
412  */
413  bdiPoseOverride* m_scripted_object;
414  bdiScenarioCharacter* m_character;
415 
416  friend class bdiPoseOverride;
417  friend class diguyCharacter;
418  friend class bdiScenarioCharacter;
419 
420 #endif
421 
422 };
423 
424 
425 #endif /* __diguyCharacterPoseOverride_H */
426 
427 
428 /*********************************************************************
429  ** Copyright (c) 1992-2014 VT MAK
430  ** All rights reserved.
431  *********************************************************************/
432 
433 
434 
435 
436 
437 
438 
439