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 {AttachmentData[]} attachmentData - Information on the avatar's attachments.
62  * <p class="important">Deprecated: This property is deprecated and will be removed. Use avatar entities instead.</p>
63  * @property {string[]} jointNames - The list of joints in the avatar model.
64  *
65  * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the
66  * domain.
67  * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting into
68  * the domain.
69  *
70  * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the
71  * avatar's size, orientation, and position in the virtual world.
72  * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar.
73  * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the
74  * avatar.
75  *
76  * @property {Vec3} skeletonOffset - The rendering offset of the avatar.
77  */
78 class ScriptAvatar : public ScriptAvatarData {
79  Q_OBJECT
80 
81  Q_PROPERTY(glm::vec3 skeletonOffset READ getSkeletonOffset)
82 
83 public:
84  ScriptAvatar(AvatarSharedPointer avatarData);
85 
86 public slots:
87 
88  /*@jsdoc
89  * Gets the default rotation of a joint in the avatar relative to its parent.
90  * <p>For information on the joint hierarchy used, see
91  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
92  * @function ScriptAvatar.getDefaultJointRotation
93  * @param {number} index - The joint index.
94  * @returns {Quat} The default rotation of the joint if avatar data are available and the joint index is valid, otherwise
95  * {@link Quat(0)|Quat.IDENTITY}.
96  */
97  glm::quat getDefaultJointRotation(int index) const;
98 
99  /*@jsdoc
100  * Gets the default translation of a joint in the avatar relative to its parent, in model coordinates.
101  * <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
102  * <p>For information on the joint hierarchy used, see
103  * <a href="https://docs.overte.org/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
104  * @function ScriptAvatar.getDefaultJointTranslation
105  * @param {number} index - The joint index.
106  * @returns {Vec3} The default translation of the joint (in model coordinates) if avatar data are available and the joint
107  * index is valid, otherwise {@link Vec3(0)|Vec3.ZERO}.
108  */
109  glm::vec3 getDefaultJointTranslation(int index) const;
110 
111 
112  /*@jsdoc
113  * Gets the offset applied to the avatar for rendering.
114  * @function ScriptAvatar.getSkeletonOffset
115  * @returns {Vec3} The skeleton offset if avatar data are available, otherwise {@link Vec3(0)|Vec3.ZERO}.
116  */
117  glm::vec3 getSkeletonOffset() const;
118 
119 
120  /*@jsdoc
121  * Gets the position of a joint in the avatar.
122  * @function ScriptAvatar.getJointPosition
123  * @param {number} index - The index of the joint.
124  * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
125  * available.
126  */
127  glm::vec3 getJointPosition(int index) const;
128 
129  /*@jsdoc
130  * Gets the position of a joint in the current avatar.
131  * @function ScriptAvatar.getJointPosition
132  * @param {string} name - The name of the joint.
133  * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
134  * available.
135  */
136  glm::vec3 getJointPosition(const QString& name) const;
137 
138  /*@jsdoc
139  * Gets the position of the current avatar's neck in world coordinates.
140  * @function ScriptAvatar.getNeckPosition
141  * @returns {Vec3} The position of the neck in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
142  * available.
143  */
144  glm::vec3 getNeckPosition() const;
145 
146 
147  /*@jsdoc
148  * Gets the current acceleration of the avatar.
149  * @function ScriptAvatar.getAcceleration
150  * @returns {Vec3} The current acceleration of the avatar, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't available..
151  */
152  glm::vec3 getAcceleration() const;
153 
154 
155  /*@jsdoc
156  * Gets the ID of the entity or avatar that the avatar is parented to.
157  * @function ScriptAvatar.getParentID
158  * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid(0)|Uuid.NULL} if not parented
159  * or avatar data aren't available.
160  */
161  QUuid getParentID() const;
162 
163  /*@jsdoc
164  * Gets the joint of the entity or avatar that the avatar is parented to.
165  * @function ScriptAvatar.getParentJointIndex
166  * @returns {number} The joint of the entity or avatar that the avatar is parented to. <code>65535</code> or
167  * <code>-1</code> if parented to the entity or avatar's position and orientation rather than a joint, or avatar data
168  * aren't available.
169  */
170  quint16 getParentJointIndex() const;
171 
172 
173  /*@jsdoc
174  * Gets information on all the joints in the avatar's skeleton.
175  * @function ScriptAvatar.getSkeleton
176  * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton.
177  */
178  QVariantList getSkeleton() const;
179 
180 
181  /*@jsdoc
182  * @function ScriptAvatar.getSimulationRate
183  * @param {AvatarSimulationRate} [rateName=""] - Rate name.
184  * @returns {number} Simulation rate in Hz, or <code>0.0</code> if avatar data aren't available.
185  * @deprecated This function is deprecated and will be removed.
186  */
187  float getSimulationRate(const QString& rateName = QString("")) const;
188 
189 
190  /*@jsdoc
191  * Gets the position of the left palm in world coordinates.
192  * @function ScriptAvatar.getLeftPalmPosition
193  * @returns {Vec3} The position of the left palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
194  * available.
195  */
196  glm::vec3 getLeftPalmPosition() const;
197 
198  /*@jsdoc
199  * Gets the rotation of the left palm in world coordinates.
200  * @function ScriptAvatar.getLeftPalmRotation
201  * @returns {Quat} The rotation of the left palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
202  * aren't available.
203  */
204  glm::quat getLeftPalmRotation() const;
205 
206  /*@jsdoc
207  * Gets the position of the right palm in world coordinates.
208  * @function ScriptAvatar.getLeftPalmPosition
209  * @returns {Vec3} The position of the right palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't
210  * available.
211  */
212  glm::vec3 getRightPalmPosition() const;
213 
214  /*@jsdoc
215  * Gets the rotation of the right palm in world coordinates.
216  * @function ScriptAvatar.getLeftPalmRotation
217  * @returns {Quat} The rotation of the right palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data
218  * aren't available.
219  */
220  glm::quat getRightPalmRotation() const;
221 
222 private:
223  std::shared_ptr<Avatar> lockAvatar() const;
224 };
225 
226 #endif // hifi_ScriptAvatar_h