Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-04-16 16:26:17 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Material entity JSDoc

Browse source
This commit is contained in:
David Rowe 2018-03-01 09:57:42 +13:00
parent 1bb8a0fb18
commit 3275846882
5 changed files with 122 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

54
libraries/entities/src/EntityItemProperties.cpp
View file

@ -589,6 +589,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* @see {@link Entities.EntityProperties-Box|EntityProperties-Box}
* @see {@link Entities.EntityProperties-Light|EntityProperties-Light}
* @see {@link Entities.EntityProperties-Line|EntityProperties-Line}
* @see {@link Entities.EntityProperties-Material|EntityProperties-Material}
* @see {@link Entities.EntityProperties-Model|EntityProperties-Model}
* @see {@link Entities.EntityProperties-ParticleEffect|EntityProperties-ParticleEffect}
* @see {@link Entities.EntityProperties-PolyLine|EntityProperties-PolyLine}
@ -664,6 +665,59 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* });
*/
/**jsdoc
* The <code>"Material"</code> {@link Entities.EntityType|EntityType} modifies the existing materials on
* {@link Entities.EntityType|Model} entities, {@link Entities.EntityType|Shape} entities (albedo only),
* {@link Overlays.OverlayType|model overlays}, and avatars.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.<br />
* To apply a material to an entity or overlay, set the material entity's <code>parentID</code> property to the entity or
* overlay's ID.
* To apply a material to an avatar, set the material entity's <code>parentID</code> property to the avatar's session UUID.
* To apply a material to your avatar such that it persists across domains and log-ins, create the material as an avatar entity
* by setting the <code>clientOnly</code> parameter in {@link Entities.addEntity} to <code>true</code>.
* Material entities render as non-scalable spheres if they don't have their parent set.
* @typedef {object} Entities.EntityProperties-Material
* @property {string} materialURL="" - URL to a {@link MaterialResource}. If you append <code>?name</code> to the URL, the
* material with that name in the {@link MaterialResource} will be applied to the entity. <br />
* Alternatively, set the property value to <code>"userData"</code> to use the {@link Entities.EntityProperties|userData}
* entity property to live edit the material resource values.
* @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is
* applied, with materials of the same priority randomly assigned. Materials that come with the model have a priority of
* <code>0</code>.
* @property {string|number} parentMaterialName="0" - Selects the submesh or submeshes within the parent to apply the material
* to. If in the format <code>"mat::string"</code>, all submeshes with material name <code>"string"</code> are replaced.
* Otherwise the property value is parsed as an unsigned integer, specifying the mesh index to modify. Invalid values are
* parsed to <code>0</code>.
* @property {string} materialMappingMode="uv" - How the material is mapped to the entity. Either <code>"uv"</code> or
* <code>"projected"</code>. <em>Currently, only <code>"uv"</code> is supported.
* @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range
* <code>{ x: 0, y: 0 }</code> &ndash; <code>{ x: 1, y: 1 }</code>.
* @property {Vec2} materialMappingScale=1,1 - How much to scale the material within the parent's UV-space.
* @property {number} materialMappingRot=0 - How much to rotate the material within the parent's UV-space, in degrees.
* @example <caption>Color a sphere using a Material entity.</caption>
* var entityID = Entities.addEntity({
* type: "Sphere",
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5 })),
* dimensions: { x: 1, y: 1, z: 1 },
* color: { red: 128, green: 128, blue: 128 },
* lifetime: 300 // Delete after 5 minutes.
* });
*
* var materialID = Entities.addEntity({
* type: "Material",
* parentID: entityID,
* materialURL: "userData",
* priority: 1,
* userData: JSON.stringify({
* materials: {
* // Can only set albedo on a Shape entity.
* // Value overrides entity's "color" property.
* albedo: [1.0, 0, 0]
* }
* }),
* });
*/
/**jsdoc
* The <code>"Model"</code> {@link Entities.EntityType|EntityType} displays an FBX or OBJ model.
* It has properties in addition to the common {@link Entities.EntityProperties|EntityProperties}.

3
libraries/entities/src/EntityTypes.h
View file

@ -49,6 +49,9 @@ public:
* <td>{@link Entities.EntityProperties-Light|EntityProperties-Light}</td></tr>
* <tr><td><code>"Line"</code></td><td>A sequence of one or more simple straight lines.</td>
* <td>{@link Entities.EntityProperties-Line|EntityProperties-Line}</td></tr>
* <tr><td><code>"Material"</code></td><td>Modifies the existing materials on Model entities, Shape entities (albedo
* only), {@link Overlays.OverlayType|model overlays}, and avatars.</td>
* <td>{@link Entities.EntityProperties-Material|EntityProperties-Material}</td></tr>
* <tr><td><code>"Model"</code></td><td>A mesh model from an FBX or OBJ file.</td>
* <td>{@link Entities.EntityProperties-Model|EntityProperties-Model}</td></tr>
* <tr><td><code>"ParticleEffect"</code></td><td>A particle system that can be used to simulate things such as fire,

55
libraries/model-networking/src/model-networking/MaterialCache.cpp
View file

@ -26,6 +26,25 @@ void NetworkMaterialResource::downloadFinished(const QByteArray& data) {
finishedLoading(true);
}
/**jsdoc
* <p>An RGB or SRGB color value.</p>
* <table>
* <thead>
* <tr><th>Index</th><th>Type</th><th>Attributes</th><th>Default</th><th>Value</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>number</td><td></td><td></td>
* <td>Red component value. Number in the range <code>0.0</code> &ndash; <code>1.0</code>.</td></tr>
* <tr><td><code>1</code></td><td>number</td><td></td><td></td>
* <td>Green component value. Number in the range <code>0.0</code> &ndash; <code>1.0</code>.</td></tr>
* <tr><td><code>2</code></td><td>number</td><td></td><td></td>
* <td>Blue component value. Number in the range <code>0.0</code> &ndash; <code>1.0</code>.</td></tr>
* <tr><td><code>3</code></td><td>boolean</td><td>&lt;optional&gt;</td><td>false</td>
* <td>If <code>true</code> then the color is an SRGB color.</td></tr>
* </tbody>
* </table>
* @typedef {array} RGBS
*/
bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3& color, bool& isSRGB) {
if (array.isArray()) {
QJsonArray colorArray = array.toArray();
@ -43,6 +62,12 @@ bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3&
return false;
}
/**jsdoc
* A material or set of materials such as may be used by a {@link Entities.EntityType|Material} entity.
* @typedef {object} MaterialResource
* @property {number} materialVersion=1 - The version of the material. <em>Currently not used.</em>
* @property {Material|Material[]} materials - The details of the material or materials.
*/
NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON) {
ParsedMaterials toReturn;
if (!materialJSON.isNull() && materialJSON.isObject()) {
@ -76,6 +101,36 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
return toReturn;
}
/**jsdoc
* A material such as may be used by a {@link Entities.EntityType|Material} entity.
* @typedef {object} Material
* @property {string} name="" - A name for the material.
* @property {string} model="hifi_pbr" - <em>Currently not used.</em>
* @property {Vec3Color|RGBS} emissive - The emissive color. A {@link Vec3Color} value is treated as sRGB. A {@link RGBS} value
* can be either RGB or sRGB.
* @property {number} opacity=1.0 - The opacity, <code>0.0</code> &ndash; <code>1.0</code>.
* @property {boolean} unlit=false - If <code>true</code>, the material is not lit.
* @property {Vec3Color|RGBS} albedo - The albedo color. A {@link Vec3Color} value is treated as sRGB. A {@link RGBS} value can
* be either RGB or sRGB.
* @property {number} roughness - The roughness, <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} metallic - The metallicness, <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} scattering - The scattering, <code>0.0</code> &ndash; <code>1.0</code>.
* @property {string} emissiveMap - URL of emissive texture image.
* @property {string} albedoMap - URL of albedo texture image.
* @property {string} opacityMap - URL of opacity texture image. Set value the same as the <code>albedoMap</code> value for
* transparency.
* @property {string} roughnessMap - URL of roughness texture image.
* @property {string} glossMap - Synonym for <code>roughnessMap</code>.
* @property {string} metallicMap - URL of metallic texture image.
* @property {string} specularMap - Synonym for <code>metallicMap</code>.
* @property {string} normalMap - URL of normal texture image.
* @property {string} bumpMap - Synonym for <code>normalMap</code>.
* @property {string} occlusionMap - URL of occlusion texture image.
* @property {string} scatteringMap - URL of scattering texture image. Only used if <code>normalMap</code> or
* <code>bumpMap</code> is specified.
* @property {string} lightMap - URL of light texture image. <em>Currently not used.</em>
*/
// Note: See MaterialEntityItem.h for default values used in practice.
std::pair<std::string, std::shared_ptr<NetworkMaterial>> NetworkMaterialResource::parseJSONMaterial(const QJsonObject& materialJSON) {
std::string name = "";
std::shared_ptr<NetworkMaterial> material = std::make_shared<NetworkMaterial>();

9
libraries/script-engine/src/Vec3.h
View file

@ -48,6 +48,15 @@
* @property {float} w W-coordinate of the vector.
*/
/**jsdoc
* A color vector.
*
* @typedef {object} Vec3Color
* @property {number} x - Red component value. Integer in the range <code>0</code> - <code>255</code>.
* @property {number} y - Green component value. Integer in the range <code>0</code> - <code>255</code>.
* @property {number} z - Blue component value. Integer in the range <code>0</code> - <code>255</code>.
*/
/// Scriptable interface a Vec3ernion helper class object. Used exclusively in the JavaScript API
class Vec3 : public QObject, protected QScriptable {
Q_OBJECT

1
tools/jsdoc/plugins/hifi.js
View file

@ -25,6 +25,7 @@ exports.handlers = {
'../../libraries/avatars/src',
'../../libraries/controllers/src/controllers/',
'../../libraries/entities/src',
'../../libraries/model-networking/src/model-networking/',
'../../libraries/octree/src',
'../../libraries/networking/src',
'../../libraries/physics/src',