From 1ebc6a575e1fe7f8b38d22de0957a57cfba0c298 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 20 Dec 2019 13:33:48 +1300 Subject: [PATCH 1/2] Model API JSDoc --- .../src/ModelScriptingInterface.h | 60 +++++++++++++++++++ libraries/shared/src/RegisteredMetaTypes.cpp | 5 ++ 2 files changed, 65 insertions(+) diff --git a/libraries/script-engine/src/ModelScriptingInterface.h b/libraries/script-engine/src/ModelScriptingInterface.h index 3c239f006f..39170bb370 100644 --- a/libraries/script-engine/src/ModelScriptingInterface.h +++ b/libraries/script-engine/src/ModelScriptingInterface.h @@ -17,19 +17,79 @@ #include class QScriptEngine; +/**jsdoc + * The Model API provides the ability to manipulate meshes. You can get the meshes for an entity using + * {@link Entities.getMeshes}, or create a new mesh using {@link Model.newMesh}. + *

See also, the {@link Graphics} API.

+ * + * @namespace Model + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * @hifi-server-entity + * @hifi-assignment-client + * + * @deprecated This API is deprecated. Use the {@link Graphics} API instead. + */ class ModelScriptingInterface : public QObject { Q_OBJECT public: ModelScriptingInterface(QObject* parent); + /**jsdoc + * Exports meshes to an OBJ format model. + * @function Model.meshToOBJ + * @param {MeshProxy[]} meshes - The meshes to export. + * @returns {string} The OBJ format representation of the meshes. + */ Q_INVOKABLE QString meshToOBJ(MeshProxyList in); + + /**jsdoc + * Combines multiple meshes into one. + * @function Model.appendMeshes + * @param {MeshProxy[]} meshes - The meshes to combine. + * @returns {MeshProxy} The combined mesh. + */ Q_INVOKABLE QScriptValue appendMeshes(MeshProxyList in); + + /**jsdoc + * Transforms the vertices in a mesh. + * @function Model.transformMesh + * @param {Mat4} transform - The transform to apply. + * @param {MeshProxy} mesh - The mesh to apply the transform to. + * @returns {MeshProxy|boolean} The transformed mesh, if valid. false if an error. + */ Q_INVOKABLE QScriptValue transformMesh(glm::mat4 transform, MeshProxy* meshProxy); + + /**jsdoc + * Creates a new mesh. + * @function Model.newMesh + * @param {Vec3[]} vertices - The vertices in the mesh. + * @param {Vec3[]} normals - The normals in the mesh. + * @param {MeshFace[]} faces - The faces in the mesh. + * @returns {MeshProxy} A new mesh. + */ Q_INVOKABLE QScriptValue newMesh(const QVector& vertices, const QVector& normals, const QVector& faces); + + /**jsdoc + * Gets the number of vertices in a mesh. + * @function Model.getVertexCount + * @param {MeshProxy} mesh - The mesh to count the vertices in. + * @returns {number|boolean} The number of vertices in the mesh, if valid. false if an error. + */ Q_INVOKABLE QScriptValue getVertexCount(MeshProxy* meshProxy); + + /**jsdoc + * Gets the position of a vertex in a mesh. + * @function Model.getVertex + * @param {MeshProxy} mesh - The mesh. + * @param {number} index - The index of the vertex to get. + * @returns {Vec3|boolean} The local position of the vertex relative to the mesh, if valid. false if an error. + */ Q_INVOKABLE QScriptValue getVertex(MeshProxy* meshProxy, int vertexIndex); private: diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index 87cd269c97..7c30d4f205 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1306,6 +1306,11 @@ void meshesFromScriptValue(const QScriptValue& value, MeshProxyList &out) { } +/**jsdoc + * A triangle in a mesh. + * @typedef {object} MeshFace + * @property {number[]} vertices - The indexes of the three vertices that make up the fase. + */ QScriptValue meshFaceToScriptValue(QScriptEngine* engine, const MeshFace &meshFace) { QScriptValue obj = engine->newObject(); obj.setProperty("vertices", qVectorIntToScriptValue(engine, meshFace.vertexIndices)); From 8255a50cdec0fe1229bb2539fc780a17ad168107 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 20 Dec 2019 13:34:21 +1300 Subject: [PATCH 2/2] Update MeshProxy and Entities.getMeshes() JSDoc --- libraries/entities/src/EntityScriptingInterface.h | 6 ++++-- libraries/shared/src/RegisteredMetaTypes.h | 9 +++++---- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h index fb1ec56503..d1e83dccc2 100644 --- a/libraries/entities/src/EntityScriptingInterface.h +++ b/libraries/entities/src/EntityScriptingInterface.h @@ -1867,7 +1867,8 @@ public slots: * @function Entities.getMeshes * @param {Uuid} entityID - The ID of the Model or PolyVox entity to get the meshes of. * @param {Entities~getMeshesCallback} callback - The function to call upon completion. - * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead. + * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the + * {@link Graphics} API instead. */ /**jsdoc * Called when a {@link Entities.getMeshes} call is complete. @@ -1876,7 +1877,8 @@ public slots: * Model or PolyVox entity; otherwise undefined. * @param {boolean} success - true if the {@link Entities.getMeshes} call was successful, false * otherwise. The call may be unsuccessful if the requested entity could not be found. - * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead. + * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the + * {@link Graphics} API instead. */ // FIXME move to a renderable entity interface Q_INVOKABLE void getMeshes(const QUuid& entityID, QScriptValue callback); diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3b47bb70c6..b8c2e9b1db 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -687,7 +687,8 @@ namespace graphics { using MeshPointer = std::shared_ptr; /**jsdoc - * A handle for a mesh in an entity, such as returned by {@link Entities.getMeshes}. + * A mesh, such as returned by {@link Entities.getMeshes} or {@link Model} API functions. + * * @class MeshProxy * * @hifi-interface @@ -705,16 +706,16 @@ public: virtual MeshPointer getMeshPointer() const = 0; /**jsdoc - * Get the number of vertices in the mesh. + * Gets the number of vertices in the mesh. * @function MeshProxy#getNumVertices * @returns {number} Integer number of vertices in the mesh. */ Q_INVOKABLE virtual int getNumVertices() const = 0; /**jsdoc - * Get the position of a vertex in the mesh. + * Gets the position of a vertex in the mesh. * @function MeshProxy#getPos - * @param {number} index - Integer index of the mesh vertex. + * @param {number} index - Integer index of the vertex. * @returns {Vec3} Local position of the vertex relative to the mesh. */ Q_INVOKABLE virtual glm::vec3 getPos(int index) const = 0;