Overte C++ Documentation
ScriptValueUtils.h
1 //
2 // ScriptValueUtils.h
3 // libraries/shared/src
4 //
5 // Created by Anthony Thibault on 4/15/16.
6 // Copyright 2016 High Fidelity, Inc.
7 // Copyright 2023 Overte e.V.
8 //
9 // Utilities for working with QtScriptValues
10 //
11 // Distributed under the Apache License, Version 2.0.
12 // See the accompanying file LICENSE or http://www.apache.org/licenses/LICENSE-2.0.html
13 // SPDX-License-Identifier: Apache-2.0
14 //
15 
18 
19 #ifndef hifi_ScriptValueUtils_h
20 #define hifi_ScriptValueUtils_h
21 
22 #include <QtCore/QVector>
23 
24 #include <glm/glm.hpp>
25 #include <glm/gtc/quaternion.hpp>
26 
27 #include "ScriptValue.h"
28 
29 bool isListOfStrings(const ScriptValue& value);
30 
31 
32 void registerMetaTypes(ScriptEngine* engine);
33 
34 // Mat4
35 /*@jsdoc
36  * A 4 x 4 matrix, typically containing a scale, rotation, and translation transform. See also the {@link Mat4(0)|Mat4} object.
37  *
38  * @typedef {object} Mat4
39  * @property {number} r0c0 - Row 0, column 0 value.
40  * @property {number} r1c0 - Row 1, column 0 value.
41  * @property {number} r2c0 - Row 2, column 0 value.
42  * @property {number} r3c0 - Row 3, column 0 value.
43  * @property {number} r0c1 - Row 0, column 1 value.
44  * @property {number} r1c1 - Row 1, column 1 value.
45  * @property {number} r2c1 - Row 2, column 1 value.
46  * @property {number} r3c1 - Row 3, column 1 value.
47  * @property {number} r0c2 - Row 0, column 2 value.
48  * @property {number} r1c2 - Row 1, column 2 value.
49  * @property {number} r2c2 - Row 2, column 2 value.
50  * @property {number} r3c2 - Row 3, column 2 value.
51  * @property {number} r0c3 - Row 0, column 3 value.
52  * @property {number} r1c3 - Row 1, column 3 value.
53  * @property {number} r2c3 - Row 2, column 3 value.
54  * @property {number} r3c3 - Row 3, column 3 value.
55  */
56 ScriptValue mat4toScriptValue(ScriptEngine* engine, const glm::mat4& mat4);
57 bool mat4FromScriptValue(const ScriptValue& object, glm::mat4& mat4);
58 
59 /*@jsdoc
60 * A 2-dimensional vector.
61 *
62 * @typedef {object} Vec2
63 * @property {number} x - X-coordinate of the vector. Synonyms: <code>u</code>.
64 * @property {number} y - Y-coordinate of the vector. Synonyms: <code>v</code>.
65 * @example <caption>Vec2s can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
66 * Entities.editEntity(<id>, { materialMappingPos: { x: 0.1, y: 0.2 }}); // { x: 0.1, y: 0.2 }
67 * Entities.editEntity(<id>, { materialMappingPos: { u: 0.3, v: 0.4 }}); // { x: 0.3, y: 0.4 }
68 * Entities.editEntity(<id>, { materialMappingPos: [0.5, 0.6] }); // { x: 0.5, y: 0.6 }
69 * Entities.editEntity(<id>, { materialMappingPos: 0.7 }); // { x: 0.7, y: 0.7 }
70 * var color = Entities.getEntityProperties(<id>).materialMappingPos; // { x: 0.7, y: 0.7 }
71 * color.v = 0.8; // { x: 0.7, y: 0.8 }
72 */
73 ScriptValue vec2ToScriptValue(ScriptEngine* engine, const glm::vec2& vec2);
74 bool vec2FromScriptValue(const ScriptValue& object, glm::vec2& vec2);
75 
76 /*@jsdoc
77 * A 3-dimensional vector. See also the {@link Vec3(0)|Vec3} object.
78 *
79 * @typedef {object} Vec3
80 * @property {number} x - X-coordinate of the vector. Synonyms: <code>r</code>, <code>red</code>.
81 * @property {number} y - Y-coordinate of the vector. Synonyms: <code>g</code>, <code>green</code>.
82 * @property {number} z - Z-coordinate of the vector. Synonyms: <code>b</code>, <code>blue</code>.
83 * @example <caption>Vec3 values can be set in multiple ways and modified with their aliases, but still stringify in the same
84 * way.</caption>
85 * Entities.editEntity(<id>, { position: { x: 1, y: 2, z: 3 }}); // { x: 1, y: 2, z: 3 }
86 * Entities.editEntity(<id>, { position: { r: 4, g: 5, b: 6 }}); // { x: 4, y: 5, z: 6 }
87 * Entities.editEntity(<id>, { position: { red: 7, green: 8, blue: 9 }}); // { x: 7, y: 8, z: 9 }
88 * Entities.editEntity(<id>, { position: [10, 11, 12] }); // { x: 10, y: 11, z: 12 }
89 * Entities.editEntity(<id>, { position: 13 }); // { x: 13, y: 13, z: 13 }
90 * var position = Entities.getEntityProperties(<id>).position; // { x: 13, y: 13, z: 13 }
91 * position.g = 14; // { x: 13, y: 14, z: 13 }
92 * position.blue = 15; // { x: 13, y: 14, z: 15 }
93 * Entities.editEntity(<id>, { position: "red"}); // { x: 255, y: 0, z: 0 }
94 * Entities.editEntity(<id>, { position: "#00FF00"}); // { x: 0, y: 255, z: 0 }
95 */
96 ScriptValue vec3ToScriptValue(ScriptEngine* engine, const glm::vec3& vec3);
97 ScriptValue vec3ColorToScriptValue(ScriptEngine* engine, const glm::vec3& vec3);
98 bool vec3FromScriptValue(const ScriptValue& object, glm::vec3& vec3);
99 
100 /*@jsdoc
101  * A color vector. See also the {@link Vec3(0)|Vec3} object.
102  *
103  * @typedef {object} Color
104  * @property {number} red - Red component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
105  * @property {number} green - Green component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
106  * @property {number} blue - Blue component value. Integer in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
107  * @example <caption>Colors can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
108  * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
109  * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
110  * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
111  * Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
112  * Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
113  * var color = Entities.getEntityProperties(<id>).color; // { red: 13, green: 13, blue: 13 }
114  * color.g = 14; // { red: 13, green: 14, blue: 13 }
115  * color.blue = 15; // { red: 13, green: 14, blue: 15 }
116  * Entities.editEntity(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
117  * Entities.editEntity(<id>, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
118  */
119 /*@jsdoc
120  * A color vector with real values. Values may also be <code>null</code>. See also the {@link Vec3(0)|Vec3} object.
121  *
122  * @typedef {object} ColorFloat
123  * @property {number} red - Red component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>r</code>, <code>x</code>.
124  * @property {number} green - Green component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>g</code>, <code>y</code>.
125  * @property {number} blue - Blue component value. Real in the range <code>0</code> - <code>255</code>. Synonyms: <code>b</code>, <code>z</code>.
126  * @example <caption>ColorFloats can be set in multiple ways and modified with their aliases, but still stringify in the same way</caption>
127  * Entities.editEntity(<id>, { color: { x: 1, y: 2, z: 3 }}); // { red: 1, green: 2, blue: 3 }
128  * Entities.editEntity(<id>, { color: { r: 4, g: 5, b: 6 }}); // { red: 4, green: 5, blue: 6 }
129  * Entities.editEntity(<id>, { color: { red: 7, green: 8, blue: 9 }}); // { red: 7, green: 8, blue: 9 }
130  * Entities.editEntity(<id>, { color: [10, 11, 12] }); // { red: 10, green: 11, blue: 12 }
131  * Entities.editEntity(<id>, { color: 13 }); // { red: 13, green: 13, blue: 13 }
132  * var color = Entities.getEntityProperties(<id>).color; // { red: 13, green: 13, blue: 13 }
133  * color.g = 14; // { red: 13, green: 14, blue: 13 }
134  * color.blue = 15; // { red: 13, green: 14, blue: 15 }
135  * Entities.editEntity(<id>, { color: "red"}); // { red: 255, green: 0, blue: 0 }
136  * Entities.editEntity(<id>, { color: "#00FF00"}); // { red: 0, green: 255, blue: 0 }
137  */
138 ScriptValue u8vec3ToScriptValue(ScriptEngine* engine, const glm::u8vec3& vec3);
139 ScriptValue u8vec3ColorToScriptValue(ScriptEngine* engine, const glm::u8vec3& vec3);
140 bool u8vec3FromScriptValue(const ScriptValue& object, glm::u8vec3& vec3);
141 
142 /*@jsdoc
143  * A 4-dimensional vector.
144  *
145  * @typedef {object} Vec4
146  * @property {number} x - X-coordinate of the vector.
147  * @property {number} y - Y-coordinate of the vector.
148  * @property {number} z - Z-coordinate of the vector.
149  * @property {number} w - W-coordinate of the vector.
150  */
151 ScriptValue vec4toScriptValue(ScriptEngine* engine, const glm::vec4& vec4);
152 bool vec4FromScriptValue(const ScriptValue& object, glm::vec4& vec4);
153 
154 // Quaternions
155 ScriptValue quatToScriptValue(ScriptEngine* engine, const glm::quat& quat);
156 bool quatFromScriptValue(const ScriptValue& object, glm::quat& quat);
157 
158 /*@jsdoc
159  * Defines a rectangular portion of an image or screen, or similar.
160  * @typedef {object} Rect
161  * @property {number} x - Left, x-coordinate value.
162  * @property {number} y - Top, y-coordinate value.
163  * @property {number} width - Width of the rectangle.
164  * @property {number} height - Height of the rectangle.
165  */
166 class QVector2D;
167 ScriptValue qVector2DToScriptValue(ScriptEngine* engine, const QVector2D& qVector2D);
168 bool qVector2DFromScriptValue(const ScriptValue& object, QVector2D& qVector2D);
169 
170 class QVector3D;
171 ScriptValue qVector3DToScriptValue(ScriptEngine* engine, const QVector3D& qVector3D);
172 bool qVector3DFromScriptValue(const ScriptValue& object, QVector3D& qVector3D);
173 
174 class QRect;
175 ScriptValue qRectToScriptValue(ScriptEngine* engine, const QRect& rect);
176 bool qRectFromScriptValue(const ScriptValue& object, QRect& rect);
177 
178 class QRectF;
179 ScriptValue qRectFToScriptValue(ScriptEngine* engine, const QRectF& rect);
180 bool qRectFFromScriptValue(const ScriptValue& object, QRectF& rect);
181 
182 // QColor
183 class QColor;
184 ScriptValue qColorToScriptValue(ScriptEngine* engine, const QColor& color);
185 bool qColorFromScriptValue(const ScriptValue& object, QColor& color);
186 
187 //QTimer
188 class QTimer;
189 ScriptValue qTimerToScriptValue(ScriptEngine* engine, QTimer* const &in);
190 bool qTimerFromScriptValue(const ScriptValue& object, QTimer* &out);
191 
192 class QUrl;
193 ScriptValue qURLToScriptValue(ScriptEngine* engine, const QUrl& url);
194 bool qURLFromScriptValue(const ScriptValue& object, QUrl& url);
195 
196 // vector<vec3>
197 Q_DECLARE_METATYPE(QVector<glm::vec3>)
198 ScriptValue qVectorVec3ToScriptValue(ScriptEngine* engine, const QVector<glm::vec3>& vector);
199 ScriptValue qVectorVec3ColorToScriptValue(ScriptEngine* engine, const QVector<glm::vec3>& vector);
200 bool qVectorVec3FromScriptValue(const ScriptValue& array, QVector<glm::vec3>& vector);
201 QVector<glm::vec3> qVectorVec3FromScriptValue(const ScriptValue& array);
202 
203 // vector<quat>
204 Q_DECLARE_METATYPE(QVector<glm::quat>)
205 ScriptValue qVectorQuatToScriptValue(ScriptEngine* engine, const QVector<glm::quat>& vector);
206 bool qVectorQuatFromScriptValue(const ScriptValue& array, QVector<glm::quat>& vector);
207 QVector<glm::quat> qVectorQuatFromScriptValue(const ScriptValue& array);
208 
209 // vector<bool>
210 ScriptValue qVectorBoolToScriptValue(ScriptEngine* engine, const QVector<bool>& vector);
211 bool qVectorBoolFromScriptValue(const ScriptValue& array, QVector<bool>& vector);
212 QVector<bool> qVectorBoolFromScriptValue(const ScriptValue& array);
213 
214 // vector<float>
215 ScriptValue qVectorFloatToScriptValue(ScriptEngine* engine, const QVector<float>& vector);
216 bool qVectorFloatFromScriptValue(const ScriptValue& array, QVector<float>& vector);
217 QVector<float> qVectorFloatFromScriptValue(const ScriptValue& array);
218 
219 // vector<uint32_t>
220 ScriptValue qVectorIntToScriptValue(ScriptEngine* engine, const QVector<uint32_t>& vector);
221 bool qVectorIntFromScriptValue(const ScriptValue& array, QVector<uint32_t>& vector);
222 
223 ScriptValue qVectorQUuidToScriptValue(ScriptEngine* engine, const QVector<QUuid>& vector);
224 bool qVectorQUuidFromScriptValue(const ScriptValue& array, QVector<QUuid>& vector);
225 QVector<QUuid> qVectorQUuidFromScriptValue(const ScriptValue& array);
226 
227 class AACube;
228 ScriptValue aaCubeToScriptValue(ScriptEngine* engine, const AACube& aaCube);
229 bool aaCubeFromScriptValue(const ScriptValue& object, AACube& aaCube);
230 
231 class PickRay;
232 ScriptValue pickRayToScriptValue(ScriptEngine* engine, const PickRay& pickRay);
233 bool pickRayFromScriptValue(const ScriptValue& object, PickRay& pickRay);
234 
235 class Collision;
236 ScriptValue collisionToScriptValue(ScriptEngine* engine, const Collision& collision);
237 bool collisionFromScriptValue(const ScriptValue& object, Collision& collision);
238 
239 /*@jsdoc
240  * UUIDs (Universally Unique IDentifiers) are used to uniquely identify entities, avatars, and the like. They are represented
241  * in JavaScript as strings in the format, <code>"{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}"</code>, where the "n"s are
242  * hexadecimal digits.
243  * @typedef {string} Uuid
244  */
245 //Q_DECLARE_METATYPE(QUuid) // don't need to do this for QUuid since it's already a meta type
246 ScriptValue quuidToScriptValue(ScriptEngine* engine, const QUuid& uuid);
247 bool quuidFromScriptValue(const ScriptValue& object, QUuid& uuid);
248 
249 //Q_DECLARE_METATYPE(QSizeF) // Don't need to to this becase it's arleady a meta type
250 class QSizeF;
251 ScriptValue qSizeFToScriptValue(ScriptEngine* engine, const QSizeF& qSizeF);
252 bool qSizeFFromScriptValue(const ScriptValue& object, QSizeF& qSizeF);
253 
254 class AnimationDetails;
255 ScriptValue animationDetailsToScriptValue(ScriptEngine* engine, const AnimationDetails& event);
256 bool animationDetailsFromScriptValue(const ScriptValue& object, AnimationDetails& event);
257 
258 class MeshProxy;
259 ScriptValue meshToScriptValue(ScriptEngine* engine, MeshProxy* const& in);
260 bool meshFromScriptValue(const ScriptValue& value, MeshProxy*& out);
261 
262 class MeshProxyList;
263 ScriptValue meshesToScriptValue(ScriptEngine* engine, const MeshProxyList& in);
264 bool meshesFromScriptValue(const ScriptValue& value, MeshProxyList& out);
265 
266 class MeshFace;
267 ScriptValue meshFaceToScriptValue(ScriptEngine* engine, const MeshFace& meshFace);
268 bool meshFaceFromScriptValue(const ScriptValue& object, MeshFace& meshFaceResult);
269 ScriptValue qVectorMeshFaceToScriptValue(ScriptEngine* engine, const QVector<MeshFace>& vector);
270 bool qVectorMeshFaceFromScriptValue(const ScriptValue& array, QVector<MeshFace>& result);
271 
272 enum class StencilMaskMode;
273 ScriptValue stencilMaskModeToScriptValue(ScriptEngine* engine, const StencilMaskMode& stencilMode);
274 bool stencilMaskModeFromScriptValue(const ScriptValue& object, StencilMaskMode& stencilMode);
275 
276 class MiniPromise;
277 bool promiseFromScriptValue(const ScriptValue& object, std::shared_ptr<MiniPromise>& promise);
278 ScriptValue promiseToScriptValue(ScriptEngine* engine, const std::shared_ptr<MiniPromise>& promise);
279 
280 class EntityItemID;
281 ScriptValue EntityItemIDtoScriptValue(ScriptEngine* engine, const EntityItemID& properties);
282 bool EntityItemIDfromScriptValue(const ScriptValue& object, EntityItemID& properties);
283 QVector<EntityItemID> qVectorEntityItemIDFromScriptValue(const ScriptValue& array);
284 
285 #endif // #define hifi_ScriptValueUtils_h
286 
EntityItemID
Abstract ID for editing model items. Used in EntityItem JS API.
Definition: EntityItemID.h:28
ScriptEngine
Provides an engine-independent interface for a scripting engine.
Definition: ScriptEngine.h:93
ScriptValue
[ScriptInterface] Provides an engine-independent interface for QScriptValue
Definition: ScriptValue.h:40