Add mjs_getOriginSpec to retrieve the original spec of an element.

The new function mjs_getOriginSpec returns the mjSpec that was used to define a given mjsElement. Unlike mjs_getSpec, this value remains constant even after the element has been attached to a different model.

PiperOrigin-RevId: 911930951
Change-Id: Ia9cd79d9dfabc513d6121eadcffc5d41075224c9

doc/APIreference/functions.rst

@@ -4783,6 +4783,16 @@ Find and get utilities
 
 Get spec from body.
 
+.. _mjs_getOriginSpec:
+
+`mjs_getOriginSpec <#mjs_getOriginSpec>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjs_getOriginSpec
+
+get spec that originally defined an element
+contrary to mjs_getSpec, this does not change after attachment
+
 .. _mjs_getCompiler:
 
 `mjs_getCompiler <#mjs_getCompiler>`__

doc/changelog.rst

@@ -19,6 +19,9 @@ General
   energy gain in the presence of contacts and in fluid media.
 - Added :ref:`mju_sym2dense`, converting a lower-triangular, implicitly symmetric CSR matrix to a dense
   symmetric matrix. The inertia matrix ``mjData.M`` is an example of such a matrix.
+- Added :ref:`mjs_getOriginSpec`, returning the spec that originally defined an element, prior to attachment. This is in
+  contrast to :ref:`mjs_getSpec` which returns the spec currently owning the element. If the element is not the result
+  of an attach operation, the functions are identical.
 
 .. admonition:: Future breaking API changes
    :class: warning

doc/includes/references.h

@@ -3687,6 +3687,7 @@ mjsTexture* mjs_addTexture(mjSpec* s);
 mjsMaterial* mjs_addMaterial(mjSpec* s, const mjsDefault* def);
 int mjs_makeMesh(mjsMesh* mesh, mjtMeshBuiltin builtin, double* params, int nparams);
 mjSpec* mjs_getSpec(const mjsElement* element);
+mjSpec* mjs_getOriginSpec(const mjsElement* element);
 mjsCompiler* mjs_getCompiler(const mjsElement* element);
 mjSpec* mjs_findSpec(const mjSpec* spec, const char* name);
 mjsBody* mjs_findBody(const mjSpec* s, const char* name);