diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index 8df85bcfe62..96006f345b9 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -950,19 +950,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * Material entities render as non-scalable spheres if they don't have their parent set.

* * @typedef {object} Entities.EntityProperties-Material - * @property {Vec3} dimensions=0.1,0.1,0.1 - Used when materialMappingMode == "projected". - * @property {string} materialURL="" - URL to a {@link Entities.MaterialResource|MaterialResource}. Alternatively, set the + * @property {Vec3} [dimensions=0.1,0.1,0.1] - Used when materialMappingMode == "projected". + * @property {string} [materialURL=""] - URL to a {@link Entities.MaterialResource|MaterialResource}. Alternatively, set the * property value to "materialData" to use the materialData property for the * {@link Entities.MaterialResource|MaterialResource} values. If you append "#name" to the URL, the material * with that name will be applied to the entity. You can also use the ID of another Material entity as the URL, in which * case this material will act as a copy of that material, with its own unique material transform, priority, etc. - * @property {string} materialData="" - Used to store {@link Entities.MaterialResource|MaterialResource} data as a JSON string. + * @property {string} [materialData=""] - Used to store {@link Entities.MaterialResource|MaterialResource} data as a JSON string. * You can use JSON.parse() to parse the string into a JavaScript object which you can manipulate the * properties of, and use JSON.stringify() to convert the object into a string to put in the property. - * @property {number} priority=0 - The priority for applying the material to its parent. Only the highest priority material is + * @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 * 0. - * @property {string} parentMaterialName="0" - Selects the mesh part or parts within the parent to which to apply the material. + * @property {string} [parentMaterialName="0"] - Selects the mesh part or parts within the parent to which to apply the material. * If in the format "mat::string", all mesh parts with material name "string" are replaced. * If "all", then all mesh parts are replaced. * Otherwise the property value is parsed as an unsigned integer, specifying the mesh part index to modify. @@ -970,18 +970,19 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * at each "," and each element parsed as either a number or a string if it starts with "mat::". * For example, "[0,1,mat::string,mat::string2]" will replace mesh parts 0 and 1, and any mesh parts with * material "string" or "string2". Do not put spaces around the commas. Invalid values are parsed - * to 0.

- * @property {string} materialMappingMode="uv" - How the material is mapped to the entity. Either "uv" or + * to "0".

+ * @property {string} [materialMappingMode="uv"] - How the material is mapped to the entity. Either "uv" or * "projected". In "uv" mode, the material is evaluated within the UV space of the mesh it is * applied to. In "projected" mode, the 3D transform (position, rotation, and dimensions) of the Material * entity is used to evaluate the texture coordinates for the material. - * @property {Vec2} materialMappingPos=0,0 - Offset position in UV-space of the top left of the material, range + * @property {Vec2} [materialMappingPos=0.0,0.0] - Offset position in UV-space of the top left of the material, range * { x: 0, y: 0 } – { x: 1, y: 1 }. - * @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. - * @property {boolean} materialRepeat=true - true if the material repeats, false if it doesn't. If + * @property {Vec2} [materialMappingScale=1.0,1.0] - 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. + * @property {boolean} [materialRepeat=true] - true if the material repeats, false if it doesn't. If * false, fragments outside of texCoord 0 – 1 will be discarded. Works in both "uv" and * "projected" modes. + * * @example Color a sphere using a Material entity. * var entityID = Entities.addEntity({ * type: "Sphere", diff --git a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp index f175a654528..d3385b5ddbc 100644 --- a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp +++ b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp @@ -75,9 +75,9 @@ bool NetworkMaterialResource::parseJSONColor(const QJsonValue& array, glm::vec3& /*@jsdoc * A material or set of materials used by a {@link Entities.EntityType|Material entity}. * @typedef {object} Entities.MaterialResource - * @property {number} materialVersion=1 - The version of the material. Currently not used. - * @property {Entities.Material|Entities.Material[]|string} materials - The details of the material or materials, or the ID of another - * Material entity. + * @property {number} [materialVersion=1] - The version of the material. Currently not used. + * @property {Entities.Material|Entities.Material[]|string} materials - The details of the material or materials, or the ID of + * another Material entity. */ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMaterials(const QJsonDocument& materialJSON, const QUrl& baseUrl) { ParsedMaterials toReturn; @@ -126,107 +126,102 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseMaterialF /*@jsdoc * A material used in a {@link Entities.MaterialResource|MaterialResource}. * @typedef {object} Entities.Material - * @property {string} name="" - A name for the material. Supported by all material models. - * @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes. + * @property {string} [name=""] - A name for the material. Supported by all material models. + * @property {string} [model="hifi_pbr"] - Different material models support different properties and rendering modes. * Supported models are: "hifi_pbr", "hifi_shader_simple". - * @property {ColorFloat|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A - * {@link ColorFloat} value is treated as sRGB and must have component values in the range 0.0 – - * 1.0. A {@link RGBS} value can be either RGB or sRGB. + * @property {ColorFloat|RGBS|string} [emissive] - The emissive color, i.e., the color that the material emits. A + * {@link ColorFloat} value is treated as sRGB and must have component values in the range 0.0 – + * 1.0. A {@link RGBS} value can be either RGB or sRGB. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {number|string} opacity=1.0 - The opacity, range 0.0 – 1.0. + * @property {number|string} [opacity=1.0] - The opacity, range 0.0 – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" and * "hifi_shader_simple" models only. - * @property {boolean|string} unlit=false - true if the material is unaffected by lighting, false if + * @property {boolean|string} [unlit=false] - true if the material is unaffected by lighting, false if * it is lit by the key light and local lights. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {ColorFloat|RGBS|string} albedo - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have + * @property {ColorFloat|RGBS|string} [albedo] - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have * component values in the range 0.0 – 1.0. A {@link RGBS} value can be either RGB or sRGB. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" and * "hifi_shader_simple" models only. - * @property {number|string} roughness - The roughness, range 0.0 – 1.0. + * @property {number|string} [roughness] - The roughness, range 0.0 – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {number|string} metallic - The metallicness, range 0.0 – 1.0. + * @property {number|string} [metallic] - The metallicness, range 0.0 – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {number|string} scattering - The scattering, range 0.0 – 1.0. + * @property {number|string} [scattering] - The scattering, range 0.0 – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} emissiveMap - The URL of the emissive texture image, or an entity ID. An entity ID may be that of an + * @property {string} [emissiveMap] - The URL of the emissive texture image, or an entity ID. An entity ID may be that of an * Image or Web entity. Set to "fallthrough" to fall through to the material below. * "hifi_pbr" model only. - * @property {string} albedoMap - The URL of the albedo texture image, or an entity ID. An entity ID may be that of an Image + * @property {string} [albedoMap] - The URL of the albedo texture image, or an entity ID. An entity ID may be that of an Image * or Web entity. Set to "fallthrough" to fall through to the material below. "hifi_pbr" * model only. - * @property {string} opacityMap - The URL of the opacity texture image, or an entity ID. An entity ID may be that of an Image + * @property {string} [opacityMap] - The URL of the opacity texture image, or an entity ID. An entity ID may be that of an Image * or Web entity. Set the value the same as the albedoMap value for transparency. * "hifi_pbr" model only. - * @property {string} opacityMapMode - The mode defining the interpretation of the opacity map. Values can be: + * @property {string} [opacityMapMode] - The mode defining the interpretation of the opacity map. Values can be: * * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {number|string} opacityCutoff - The opacity cutoff threshold used to determine the opaque texels of the - * opacityMap when opacityMapMode is "OPACITY_MAP_MASK". Range 0.0 + * @property {number|string} [opacityCutoff] - The opacity cutoff threshold used to determine the opaque texels of the + * opacityMap when opacityMapMode is "OPACITY_MAP_MASK". Range 0.0 * – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} cullFaceMode="CULL_BACK" - The mode defining which side of the geometry should be rendered. Values can be: + * @property {string} [cullFaceMode="CULL_BACK"] - The mode defining which side of the geometry should be rendered. Values can + be: * * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} cullFaceMode - The mode defining which side of the geometry should be rendered. Values can be: - * - * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} roughnessMap - The URL of the roughness texture image. You can use this or glossMap, but not - * both. + * @property {string} [roughnessMap] - The URL of the roughness texture image. You can use this or glossMap, but + * not both. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} glossMap - The URL of the gloss texture image. You can use this or roughnessMap, but not - * both. + * @property {string} [glossMap] - The URL of the gloss texture image. You can use this or roughnessMap, but not + * both. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} metallicMap - The URL of the metallic texture image, or an entity ID. An entity ID may be that of an + * @property {string} [metallicMap] - The URL of the metallic texture image, or an entity ID. An entity ID may be that of an * Image or Web entity. You can use this or specularMap, but not both. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} specularMap - The URL of the specular texture image, or an entity ID. An entity ID may be that of an + * @property {string} [specularMap] - The URL of the specular texture image, or an entity ID. An entity ID may be that of an * Image or Web entity. You can use this or metallicMap, but not both. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} normalMap - The URL of the normal texture image, or an entity ID. An entity ID may be that of an Image + * @property {string} [normalMap] - The URL of the normal texture image, or an entity ID. An entity ID may be that of an Image * or Web entity. You can use this or bumpMap, but not both. Set to "fallthrough" to fall * through to the material below. "hifi_pbr" model only. - * @property {string} bumpMap - The URL of the bump texture image, or an entity ID. An entity ID may be that of an Image + * @property {string} [bumpMap] - The URL of the bump texture image, or an entity ID. An entity ID may be that of an Image * or Web entity. You can use this or normalMap, but not both. Set to "fallthrough" to * fall through to the material below. "hifi_pbr" model only. - * @property {string} occlusionMap - The URL of the occlusion texture image, or an entity ID. An entity ID may be that of + * @property {string} [occlusionMap] - The URL of the occlusion texture image, or an entity ID. An entity ID may be that of * an Image or Web entity. Set to "fallthrough" to fall through to the material below. * "hifi_pbr" model only. - * @property {string} scatteringMap - The URL of the scattering texture image, or an entity ID. An entity ID may be that of an + * @property {string} [scatteringMap] - The URL of the scattering texture image, or an entity ID. An entity ID may be that of an * Image or Web entity. Only used if normalMap or bumpMap is specified. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} lightMap - The URL of the light map texture image, or an entity ID. An entity ID may be that of an Image + * @property {string} [lightMap] - The URL of the light map texture image, or an entity ID. An entity ID may be that of an Image * or Web entity. Set to "fallthrough" to fall through to the material below. "hifi_pbr" * model only. - * @property {Mat4|string} texCoordTransform0 - The transform to use for all of the maps apart from occlusionMap - * and lightMap. + * @property {Mat4|string} [texCoordTransform0] - The transform to use for all of the maps apart from occlusionMap + * and lightMap. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {Mat4|string} texCoordTransform1 - The transform to use for occlusionMap and lightMap. + * @property {Mat4|string} [texCoordTransform1] - The transform to use for occlusionMap and lightMap. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} [lightmapParams] - Parameters for controlling how lightMap is used. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {string} lightmapParams - Parameters for controlling how lightMap is used. - * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. *

Currently not used.

- * @property {string} materialParams - Parameters for controlling the material projection and repetition. - * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. + * @property {string} [materialParams] - Parameters for controlling the material projection and repetition. + * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. *

Currently not used.

- * @property {boolean} defaultFallthrough=false - true if all properties fall through to the material below - * unless they are set, false if properties respect their individual fall-through settings. + * @property {boolean} [defaultFallthrough=false] - true if all properties fall through to the material below + * unless they are set, false if properties respect their individual fall-through settings. * "hifi_pbr" and "hifi_shader_simple" models only. - * @property {ProceduralData} procedural - The definition of a procedural shader material. "hifi_shader_simple" model only. + * @property {ProceduralData} [procedural] - The definition of a procedural shader material. "hifi_shader_simple" + * model only. */ // Note: See MaterialEntityItem.h for default values used in practice. std::pair> NetworkMaterialResource::parseJSONMaterial(const QJsonValue& materialJSONValue, const QUrl& baseUrl) {