diff --git a/doc/APIreference/APItypes.rst b/doc/APIreference/APItypes.rst index fba959b2..3f11ee5e 100644 --- a/doc/APIreference/APItypes.rst +++ b/doc/APIreference/APItypes.rst @@ -1143,7 +1143,7 @@ behavior. .. _mjsCompiler: mjsCompiler -~~~~~~~~~~ +~~~~~~~~~~~ Compiler options. diff --git a/doc/XMLreference.rst b/doc/XMLreference.rst index 8c3e72de..f2b030db 100644 --- a/doc/XMLreference.rst +++ b/doc/XMLreference.rst @@ -1247,19 +1247,16 @@ The full list of processing steps applied by the compiler to each mesh is as fol :at:`inertia`: :at-val:`[convex, exact, legacy], "legacy"` This attribute controls how the mesh is used when mass and inertia are - :ref:`inferred from geometry<_compiler-inertiafromgeom>`. The current default value :at-val:`legacy` will be changed + :ref:`inferred from geometry`. The current default value :at-val:`legacy` will be changed to :at-val:`convex` in a future release. - :at-val:`convex` - Use the mesh's convex hull to compute volume and inertia. + :at-val:`convex`: Use the mesh's convex hull to compute volume and inertia. - :at-val:`exact` - Use an exact algorithm to compute volume and inertia. This algorithm requires a well-oriented, watertight mesh and - will error otherwise. + :at-val:`exact`: Use an exact algorithm to compute volume and inertia. This algorithm requires a well-oriented, + watertight mesh and will error otherwise. - :at-val:`legacy` - Use the legacy algorithm, which is similar to :at-val:`convex`, but leads to volume overcounting for non-convex - meshes. + :at-val:`legacy`: Use the legacy algorithm, which is similar to :at-val:`convex`, but leads to volume overcounting + for non-convex meshes. .. _asset-mesh-smoothnormal: @@ -1710,9 +1707,9 @@ properties are grouped together. loaded explicitly via the :ref:`texture ` element and then referenced here. The texture referenced here is used for specifying the RGB values. For advanced rendering (e.g., Physics-Based Rendering), more texture types need to be specified (e.g., roughness, metallic). In this case, this texture attribute should be omitted, and - the texture types should be specified explicitly via the specific role child elements, e.g., - :ref:`texture `. Note however that the built-in renderer does not support PBR properties, so these - advanced rendering features are only available when using an external renderer. + the texture types should be specified using :ref:`layer ` child elements. Note however that the + built-in renderer does not support PBR properties, so these advanced rendering features are only available when using + an external renderer. .. _asset-material-texrepeat: @@ -1784,116 +1781,59 @@ properties are grouped together. model element which defines its own local rgba attribute, the local definition has precedence. Note that this "local" definition could in fact come from a defaults class. The remaining material properties always apply. -.. _material-rgb: +.. _material-layer: -:el-prefix:`material/` |-| **rgb** (?) -'''''''''''''''''''''''''''''''''''''' +:el-prefix:`material/` |-| **layer** (?) +'''''''''''''''''''''''''''''''''''''''' -This element references a texture asset used to specify base color / albedo values. +If multiple textures are needed to specify the appearance of a material, the :ref:`texture ` +attribute cannot be used, and :el:`layer` child elements must be used instead. Specifying both the :at:`texture` +attribute and :el:`layer` child elements is an error. -.. _material-rgb-texture: +.. _material-layer-texture: :at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. + Name of the texture, like the :ref:`texture ` attribute. -.. _material-normal: +.. _material-layer-role: -:el-prefix:`material/` |-| **normal** (?) -''''''''''''''''''''''''''''''''''''''''' +:at:`role`: :at-val:`string, required` + Role of the texture. The valid values, expected number of channels, and the role semantics are: -This element references a texture asset used to specify the bump map (surface normals). - -.. _material-normal-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. - -.. _material-occlusion: - -:el-prefix:`material/` |-| **occlusion** (?) -'''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify ambient occlusion. - -.. _material-occlusion-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-roughness: - -:el-prefix:`material/` |-| **roughness** (?) -'''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the roughness map. - -.. _material-roughness-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-metallic: - -:el-prefix:`material/` |-| **metallic** (?) -''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the metallic map. - -.. _material-metallic-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-opacity: - -:el-prefix:`material/` |-| **opacity** (?) -'''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify the opacity map (alpha channel, transparency). - -.. _material-opacity-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly one channel. - -.. _material-emissive: - -:el-prefix:`material/` |-| **emissive** (?) -''''''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify light emission. - -.. _material-emissive-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 4 channels. - -.. _material-orm: - -:el-prefix:`material/` |-| **orm** (?) -'''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify a packed ORM map, where occlusion, roughness, and metallic -are joined into the corresponding RGB values of a single texture. - -.. _material-orm-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 3 channels. - -.. _material-rgba: - -:el-prefix:`material/` |-| **rgba** (?) -''''''''''''''''''''''''''''''''''''''' - -This element references a texture asset used to specify a packed map where albedo and opacity are joined into the same -4-channel texture. - -.. _material-rgba-texture: - -:at:`texture`: :at-val:`string, required` - Name of the texture, expected to have exactly 4 channels. + .. list-table:: + :widths: 1 1 8 + :header-rows: 1 + * - value + - channels + - description + * - :at:`rgb` + - 3 + - base color / albedo [red, green, blue] + * - :at:`normal` + - 3 + - bump map (surface normals) + * - :at:`occlusion` + - 1 + - ambient occlusion + * - :at:`roughness` + - 1 + - roughness + * - :at:`metallic` + - 1 + - metallicity + * - :at:`opacity` + - 1 + - opacity (alpha channel) + * - :at:`emissive` + - 4 + - RGB light emmision intensity, exposure weight in 4th channel + * - :at:`orm` + - 3 + - packed 3 channel [occlusion, roughness, metallic] + * - :at:`rgba` + - 4 + - packed 4 channel [red, green, blue, alpha] .. _asset-model: diff --git a/doc/XMLschema.rst b/doc/XMLschema.rst index 4b45b68b..72df2be3 100644 --- a/doc/XMLschema.rst +++ b/doc/XMLschema.rst @@ -178,66 +178,10 @@ | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`rgb | ? | :class: mjcf-attributes | -| ` | | | +| :ref:`layer | \* | :class: mjcf-attributes | +| ` | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`occlusion | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`roughness | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`metallic | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`normal | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`opacity | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`emissive | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`rgba | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -+------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ -| |_2| material |br| |_2| |L| | | .. table:: | -| :ref:`orm | ? | :class: mjcf-attributes | -| ` | | | -| | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | -| | | | :ref:`texture` | | | | | +| | | | :ref:`texture` | :ref:`role` | | | | | | | +-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+-----------------------------------------------------------------+ | +------------------------------------+----+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |_| asset |br| |_| |L| | | .. table:: | diff --git a/doc/changelog.rst b/doc/changelog.rst index 109c54f9..920cff46 100644 --- a/doc/changelog.rst +++ b/doc/changelog.rst @@ -10,6 +10,9 @@ General - The global compiler flag ``exactmeshinertia`` has been removed and replaced with the mesh-specific :ref:`inertia` attribute. - Removed the deprecated ``mju_rotVecMat`` and ``mju_rotVecMatT`` functions. +- Sorting now uses a faster, native sort function (fixes :github:issue:`1638`). +- The PBR texture layers introduced in 3.2.1 were refactored from seperate sub-elements to a single + :ref:`layer` sub-element. MJX ^^^ @@ -169,7 +172,7 @@ General 2. Added a new :ref:`autoreset` flag to disable automatic reset when NaNs or infinities are detected. 3. Added sub-elements to the MJCF :ref:`material` element, to allow specification of multiple textures - for rendering (e.g., :ref:`occlusion-roughness-metallic`). Note that the MuJoCo renderer doesn't + for rendering (e.g., ``occlusion, roughness, metallic``). Note that the MuJoCo renderer doesn't support these new features, and they are made available for use with external renderers. 4. Sorting (``mjQUICKSORT``) now calls ``std::sort`` when building with C++ (:github:issue:`1638`). diff --git a/src/xml/xml_native_reader.cc b/src/xml/xml_native_reader.cc index 854459cb..6fc675c5 100644 --- a/src/xml/xml_native_reader.cc +++ b/src/xml/xml_native_reader.cc @@ -247,15 +247,7 @@ const char* MJCF[nMJCF][mjXATTRNUM] = { {"material", "*", "12", "name", "class", "texture", "texrepeat", "texuniform", "emission", "specular", "shininess", "reflectance", "metallic", "roughness", "rgba"}, {"<"}, - {"rgb", "?", "1", "texture"}, - {"occlusion", "?", "1", "texture"}, - {"roughness", "?", "1", "texture"}, - {"metallic", "?", "1", "texture"}, - {"normal", "?", "1", "texture"}, - {"opacity", "?", "1", "texture"}, - {"emissive", "?", "1", "texture"}, - {"rgba", "?", "1", "texture"}, - {"orm", "?", "1", "texture"}, + {"layer", "*", "2", "texture", "role"}, {">"}, {"model", "*", "3", "name", "file", "content_type"}, {">"}, @@ -1590,17 +1582,18 @@ void mjXReader::OneMaterial(XMLElement* elem, mjsMaterial* material) { tex_attributes_found = true; } - XMLElement* tex_elem = FirstChildElement(elem); - while (tex_elem) { + XMLElement* layer = FirstChildElement(elem); + while (layer) { if (tex_attributes_found) { - throw mjXError(tex_elem, "A material with a texture attribute cannot have texture sub-elements"); + throw mjXError(layer, "A material with a texture attribute cannot have layer sub-elements"); } - // texture sub-element - int role = FindKey(texrole_map, texrole_sz, tex_elem->Name()); - string texmat; - ReadAttrTxt(tex_elem, "texture", texmat, true); - mjs_setInStringVec(material->textures, role, texmat.c_str()); - tex_elem = NextSiblingElement(tex_elem); + + // layer sub-element + ReadAttrTxt(layer, "role", text, true); + int role = FindKey(texrole_map, texrole_sz, text); + ReadAttrTxt(layer, "texture", text, true); + mjs_setInStringVec(material->textures, role, text.c_str()); + layer = NextSiblingElement(layer); } if (MapValue(elem, "texuniform", &n, bool_map, 2)) { diff --git a/src/xml/xml_native_reader.h b/src/xml/xml_native_reader.h index c9f456bf..62488b97 100644 --- a/src/xml/xml_native_reader.h +++ b/src/xml/xml_native_reader.h @@ -101,7 +101,7 @@ class mjXReader : public mjXBase { }; // MJCF schema -#define nMJCF 245 +#define nMJCF 237 extern const char* MJCF[nMJCF][mjXATTRNUM]; #endif // MUJOCO_SRC_XML_XML_NATIVE_READER_H_ diff --git a/test/xml/xml_native_reader_test.cc b/test/xml/xml_native_reader_test.cc index 8f902565..4eed4735 100644 --- a/test/xml/xml_native_reader_test.cc +++ b/test/xml/xml_native_reader_test.cc @@ -805,10 +805,10 @@ TEST_F(XMLReaderTest, MaterialTextureTest) { - - - - + + + + @@ -873,8 +873,8 @@ TEST_F(XMLReaderTest, MaterialTextureFailTest) { - - + + @@ -887,7 +887,7 @@ TEST_F(XMLReaderTest, MaterialTextureFailTest) { mjModel* m = LoadModelFromString(xml, error.data(), error.size()); EXPECT_THAT(m, IsNull()); EXPECT_THAT(error.data(), HasSubstr("A material with a texture attribute " - "cannot have texture sub-elements")); + "cannot have layer sub-elements")); } TEST_F(XMLReaderTest, LargeTextureTest) {