Overte C++ Documentation
ScriptAvatar.h
1 //
2 // ScriptAvatar.h
3 // interface/src/avatars
4 //
5 // Created by Stephen Birarda on 4/10/17.
6 // Copyright 2017 High Fidelity, Inc.
7 // Copyright 2021 Vircadia contributors.
8 //
9 // Distributed under the Apache License, Version 2.0.
10 // See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
11 //
12 
13 #ifndef hifi_ScriptAvatar_h
14 #define hifi_ScriptAvatar_h
15 
16 #include <ScriptAvatarData.h>
17 
18 #include "Avatar.h"
19 
20 /*@jsdoc
21  * Information about an avatar.
22  *
23  * <p>Create using {@link MyAvatar.getTargetAvatar} or {@link AvatarList.getAvatar}.</p>
24  *
25  * @class ScriptAvatar
26  * @hideconstructor
27  *
28  * @hifi-interface
29  * @hifi-client-entity
30  * @hifi-avatar
31  * @hifi-assignment-client
32  * @hifi-server-entity
33  *
34  * @property {Vec3} position - The avatar's position.
35  * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the
36  * domain.
37  * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar but
38  * is otherwise not used or changed by Interface.
39  * @property {number} bodyPitch - The pitch of the avatar's body, in degrees.
40  * @property {number} bodyYaw - The yaw of the avatar's body, in degrees.
41  * @property {number} bodyRoll - The roll of the avatar's body, in degrees.
42  * @property {Quat} orientation - The orientation of the avatar's body.
43  * @property {Quat} headOrientation - The orientation of the avatar's head.
44  * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees.
45  * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees.
46  * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees.
47  *
48  * @property {Vec3} velocity - The linear velocity of the avatar.
49  * @property {Vec3} angularVelocity - The angular velocity of the avatar.
50  *
51  * @property {Uuid} sessionUUID - The avatar's session ID.
52  * @property {string} displayName - The avatar's display name.
53  * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer.
54  * It is unique among all avatars present in the domain at the time.
55  * @property {boolean} isReplicated - <span class="important">Deprecated: This property is deprecated and will be
56  * removed.</span>
57  * @property {boolean} lookAtSnappingEnabled - <code>true</code> if the avatar's eyes snap to look at another avatar's eyes
58  * when the other avatar is in the line of sight and also has <code>lookAtSnappingEnabled == true</code>.
59  *
60  * @property {string} skeletonModelURL - The avatar's FST file.
61  * @property {string[]} jointNames - The list of joints in the avatar model.
62  *
63  * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the
64  * domain.
65  * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting into
66  * the domain.
67  *
68  * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the
69  * avatar's size, orientation, and position in the virtual world.
70  * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar.
71  * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the
72  * avatar.
73  *
74  * @property {Vec3} skeletonOffset - The rendering offset of the avatar.
75  */
76 class ScriptAvatar : public ScriptAvatarData {
77  Q_OBJECT
78 
79  Q_PROPERTY(glm::vec3 skeletonOffset READ getSkeletonOffset)
80 
81 public:
82  ScriptAvatar(AvatarSharedPointer avatarData);
83 
84 public slots:
85 
86  /*@jsdoc
87  * Gets the default rotation of a joint in the avatar relative to its parent.
88  * <p>For information on the joint hierarchy used, see
89  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
90  * @function ScriptAvatar.getDefaultJointRotation
91  * @param {number} index - The joint index.
92  * @returns {Quat} The default rotation of the joint if avatar data are available and the joint index is valid, otherwise
93  * {@link Quat(0)|Quat.IDENTITY}.
94  */
95  glm::quat getDefaultJointRotation(int index) const;
96 
97  /*@jsdoc
98  * Gets the default translation of a joint in the avatar relative to its parent, in model coordinates.
99  * <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
100  * <p>For information on the joint hierarchy used, see
101  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
102  * @function ScriptAvatar.getDefaultJointTranslation
103  * @param {number} index - The joint index.
104  * @returns {Vec3} The default translation of the joint (in model coordinates) if avatar data are available and the joint
105  * index is valid, otherwise {@link Vec3(0)|Vec3.ZERO}.
106  */
107  glm::vec3 getDefaultJointTranslation(int index) const;
108 
109 
110  /*@jsdoc
111  * Gets the offset applied to the avatar for rendering.
112  * @function ScriptAvatar.getSkeletonOffset
113  * @returns {Vec3} The skeleton offset if avatar data are available, otherwise {@link Vec3(0)|Vec3.ZERO}.
114  */
115  glm::vec3 getSkeletonOffset() const;
116 
117 
118  /*@jsdoc
119  * Gets the position of a joint in the avatar.
120  * @function ScriptAvatar.getJointPosition
121  * @param {number} index - The index of the joint.
122  * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
123  * available.
124  */
125  glm::vec3 getJointPosition(int index) const;
126 
127  /*@jsdoc
128  * Gets the position of a joint in the current avatar.
129  * @function ScriptAvatar.getJointPosition
130  * @param {string} name - The name of the joint.
131  * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
132  * available.
133  */
134  glm::vec3 getJointPosition(const QString& name) const;
135 
136  /*@jsdoc
137  * Gets the position of the current avatar's neck in world coordinates.
138  * @function ScriptAvatar.getNeckPosition
139  * @returns {Vec3} The position of the neck in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
140  * available.
141  */
142  glm::vec3 getNeckPosition() const;
143 
144 
145  /*@jsdoc
146  * Gets the current acceleration of the avatar.
147  * @function ScriptAvatar.getAcceleration
148  * @returns {Vec3} The current acceleration of the avatar, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't available..
149  */
150  glm::vec3 getAcceleration() const;
151 
152 
153  /*@jsdoc
154  * Gets the ID of the entity or avatar that the avatar is parented to.
155  * @function ScriptAvatar.getParentID
156  * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid(0)|Uuid.NONE} if not parented
157  * or avatar data aren't available.
158  */
159  QUuid getParentID() const;
160 
161  /*@jsdoc
162  * Gets the joint of the entity or avatar that the avatar is parented to.
163  * @function ScriptAvatar.getParentJointIndex
164  * @returns {number} The joint of the entity or avatar that the avatar is parented to. <code>65535</code> or
165  * <code>-1</code> if parented to the entity or avatar's position and orientation rather than a joint, or avatar data
166  * aren't available.
167  */
168  quint16 getParentJointIndex() const;
169 
170 
171  /*@jsdoc
172  * Gets information on all the joints in the avatar's skeleton.
173  * @function ScriptAvatar.getSkeleton
174  * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton.
175  */
176  QVariantList getSkeleton() const;
177 
178 
179  /*@jsdoc
180  * @function ScriptAvatar.getSimulationRate
181  * @param {AvatarSimulationRate} [rateName=""] - Rate name.
182  * @returns {number} Simulation rate in Hz, or <code>0.0</code> if avatar data aren't available.
183  * @deprecated This function is deprecated and will be removed.
184  */
185  float getSimulationRate(const QString& rateName = QString("")) const;
186 
187 
188  /*@jsdoc
189  * Gets the position of the left palm in world coordinates.
190  * @function ScriptAvatar.getLeftPalmPosition
191  * @returns {Vec3} The position of the left palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
192  * available.
193  */
194  glm::vec3 getLeftPalmPosition() const;
195 
196  /*@jsdoc
197  * Gets the rotation of the left palm in world coordinates.
198  * @function ScriptAvatar.getLeftPalmRotation
199  * @returns {Quat} The rotation of the left palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
200  * aren't available.
201  */
202  glm::quat getLeftPalmRotation() const;
203 
204  /*@jsdoc
205  * Gets the position of the right palm in world coordinates.
206  * @function ScriptAvatar.getLeftPalmPosition
207  * @returns {Vec3} The position of the right palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
208  * available.
209  */
210  glm::vec3 getRightPalmPosition() const;
211 
212  /*@jsdoc
213  * Gets the rotation of the right palm in world coordinates.
214  * @function ScriptAvatar.getLeftPalmRotation
215  * @returns {Quat} The rotation of the right palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
216  * aren't available.
217  */
218  glm::quat getRightPalmRotation() const;
219 
220 private:
221  std::shared_ptr<Avatar> lockAvatar() const;
222 };
223 
224 #endif // hifi_ScriptAvatar_h