Add a new plugin / extension mechanism called a resource provider along with retrofitting VFS on top of it.

A resource provider provides a mechanism for MuJoCo to read from filesystems other than the OS filesystem or the Virtual File System (VFS).

PiperOrigin-RevId: 525394983
Change-Id: I077ff5a7e2e76806b48b6defb531280aadc8b169

doc/APIreference/functions.rst

@@ -3069,3 +3069,52 @@ mjp_getPluginAtSlot
 
 Look up a plugin by the registered slot number that was returned by mjp_registerPlugin.
 
+.. _mjp_defaultResourceProvider:
+
+mjp_defaultResourceProvider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_defaultResourceProvider
+
+Set default resource provider definition.
+
+.. _mjp_registerResourceProvider:
+
+mjp_registerResourceProvider
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_registerResourceProvider
+
+Globally register a resource provider in a thread-safe manner. The provider must have a prefix
+that is not a sub-prefix or super-prefix of any current registered providers.  This function
+returns a slot number > 0 on success.
+
+.. _mjp_resourceProviderCount:
+
+mjp_resourceProviderCount
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_resourceProviderCount
+
+Return the number of globally registered resource providers.
+
+.. _mjp_getResourceProvider:
+
+mjp_getResourceProvider
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_getResourceProvider
+
+Return the resource provider with the prefix that matches against the resource name.
+If no match, return NULL.
+
+.. _mjp_getResourceProviderAtSlot:
+
+mjp_getResourceProviderAtSlot
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mjp_getResourceProviderAtSlot
+
+Look up a resource provider by slot number returned by mjp_registerResourceProvider.
+If invalid slot number, return NULL.
+

doc/changelog.rst

@@ -20,6 +20,9 @@ General
   equivalent body inertias with ellipsoids instead of the default boxes.
 - Added documentation for :ref:`engine plugins<exPlugin>`.
 - Added struct information to the ``introspect`` module.
+- Added a new extension mechanism called "resource provider" . This extensible mechanism allows MuJoCo
+  to read assets from data sources other than the local OS filesystem or
+  the :ref:`Virtual file system<Virtualfilesystem>`.
 
 Python bindings
 ^^^^^^^^^^^^^^^

doc/includes/references.h

@@ -607,13 +607,25 @@ struct mjLROpt_ {                 // options for mj_setLengthRange()
   mjtNum tolrange;                // convergence tolerance (relative to range)
 };
 typedef struct mjLROpt_ mjLROpt;
-struct mjVFS_ {                   // virtual file system for loading from memory
-  int   nfile;                    // number of files present
+struct mjVFS_ {                            // virtual file system for loading from memory
+  int   nfile;                             // number of files present
   char  filename[mjMAXVFS][mjMAXVFSNAME];  // file name without path
-  int   filesize[mjMAXVFS];       // file size in bytes
-  void* filedata[mjMAXVFS];       // buffer with file data
+  int   filesize[mjMAXVFS];                // file size in bytes
+  void* filedata[mjMAXVFS];                // buffer with file data
 };
 typedef struct mjVFS_ mjVFS;
+struct mjResource_ {
+  char* name;                     // name of resource (filename, etc)
+  void* data;                     // opaque data pointer
+  const void* provider_data;      // opaque resource provider data
+
+  // reading callback from resource provider
+  int (*read)(struct mjResource_* resource, const void** buffer);
+
+  // closing callback from resource provider
+  void (*close)(struct mjResource_* resource);
+};
+typedef struct mjResource_ mjResource;
 struct mjOption_ {                // physics options
   // timing parameters
   mjtNum timestep;                // timestep
@@ -1186,6 +1198,14 @@ struct mjModel_ {
   int*      names_map;            // internal hash map of names               (nnames_map x 1)
 };
 typedef struct mjModel_ mjModel;
+struct mjpResourceProvider_ {
+  const char* prefix;          // prefix for match against a resource name
+  mjfOpenResource open;        // opening callback
+  mjfReadResource read;        // reading callback
+  mjfCloseResource close;      // closing callback
+  void* data;                  // opaque data pointer (resource invariant)
+};
+typedef struct mjpResourceProvider_ mjpResourceProvider;
 typedef enum mjtPluginCapabilityBit_ {
   mjPLUGIN_ACTUATOR = 1<<0,
   mjPLUGIN_SENSOR   = 1<<1,
@@ -2197,4 +2217,9 @@ int mjp_registerPlugin(const mjpPlugin* plugin);
 int mjp_pluginCount();
 const mjpPlugin* mjp_getPlugin(const char* name, int* slot);
 const mjpPlugin* mjp_getPluginAtSlot(int slot);
+void mjp_defaultResourceProvider(mjpResourceProvider* provider);
+int mjp_registerResourceProvider(const mjpResourceProvider* provider);
+int mjp_resourceProviderCount();
+const mjpResourceProvider* mjp_getResourceProvider(const char* resource_name);
+const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
 // NOLINTEND