Expose mju resource functions to public header.

Many of these functions are useful when writing a custom decoder.

PiperOrigin-RevId: 868321921
Change-Id: I7e0dd285e0559b6f486acf8cbf4376ff8d91943d

doc/APIreference/APIfunctions.rst

@@ -29,6 +29,7 @@ API function can be classified as:
    - :ref:`Printing<Printing>` of various quantities.
    - :ref:`Virtual file system<Virtualfilesystem>`, used to load assets from memory.
    - :ref:`Asset cache<Assetcache>`, used to speed up model compilation.
+   - :ref:`Resources<Resources>`, interfacing with resource providers to load assets.
    - :ref:`Initialization<Initialization>` of data structures.
    - :ref:`Error and memory<Errorandmemory>`.
    - :ref:`Miscellaneous<Miscellaneous>` functions.

doc/APIreference/functions.rst

@@ -1551,6 +1551,77 @@ Get the internal asset cache used by the compiler.
 
 Clear the asset cache.
 
+.. _Resources:
+
+Resources
+^^^^^^^^^
+
+Resources are the interface between :ref:`resource providers <exProvider>` and MuJoCo model compilation code.
+These functions provide the means to query the resource provider and obtain resources.
+.. _mju_openResource:
+
+`mju_openResource <#mju_openResource>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_openResource
+
+Open a resource; if the name doesn't have a prefix matching a registered resource provider,
+then the OS filesystem is used.
+
+*Nullable:* ``dir``, ``vfs``, ``error``
+
+.. _mju_closeResource:
+
+`mju_closeResource <#mju_closeResource>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_closeResource
+
+Close a resource; no-op if resource is NULL.
+
+.. _mju_readResource:
+
+`mju_readResource <#mju_readResource>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_readResource
+
+Set buffer to bytes read from the resource and return number of bytes in buffer;
+return negative value if error.
+
+.. _mju_getResourceDir:
+
+`mju_getResourceDir <#mju_getResourceDir>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_getResourceDir
+
+For a resource with a name partitioned as {dir}{filename}, get the dir and ndir pointers.
+
+.. _mju_isModifiedResource:
+
+`mju_isModifiedResource <#mju_isModifiedResource>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_isModifiedResource
+
+Compare resource timestamp to provided timestamp.
+
+Return 0 if timestamps match, >0 if resource is newer, <0 if resource is older.
+
+.. _mju_decodeResource:
+
+`mju_decodeResource <#mju_decodeResource>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mju_decodeResource
+
+Find the decoder for a resource and return the decoded spec.
+
+The caller takes ownership of the spec and is responsible for cleaning it up.
+
+*Nullable:* ``vfs``
+
 .. _Initialization:
 
 Initialization

doc/APIreference/functions_override.rst

@@ -816,3 +816,8 @@ Note that derivatives depend only on :math:`h` and :math:`v` (in fact, on :math:
 All outputs are optional.
 
 *Nullable:* ``Dquat``, ``Dvel``, ``Dscale``
+
+.. _Resources:
+
+Resources are the interface between :ref:`resource providers <exProvider>` and MuJoCo model compilation code.
+These functions provide the means to query the resource provider and obtain resources.

doc/includes/references.h

@@ -3579,6 +3579,14 @@ const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
 void mjp_registerDecoder(const mjpDecoder* decoder);
 void mjp_defaultDecoder(mjpDecoder* decoder);
 const mjpDecoder* mjp_findDecoder(const mjResource* resource, const char* content_type);
+mjResource* mju_openResource(const char* dir, const char* name,
+                             const mjVFS* vfs, char* error, size_t nerror);
+void mju_closeResource(mjResource* resource);
+int mju_readResource(mjResource* resource, const void** buffer);
+void mju_getResourceDir(mjResource* resource, const char** dir, int* ndir);
+int mju_isModifiedResource(const mjResource* resource, const char* timestamp);
+mjSpec* mju_decodeResource(mjResource* resource, const char* content_type,
+                           const mjVFS* vfs);
 mjThreadPool* mju_threadPoolCreate(size_t number_of_threads);
 void mju_bindThreadPool(mjData* d, void* thread_pool);
 void mju_threadPoolEnqueue(mjThreadPool* thread_pool, mjTask* task);