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

include/mujoco/mjmodel.h

@@ -369,15 +369,31 @@ typedef struct mjLROpt_ mjLROpt;
 
 //---------------------------------- mjVFS ---------------------------------------------------------
 
-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;
 
 
+//---------------------------------- mjResource ----------------------------------------------------
+
+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;
+
+
 //---------------------------------- mjOption ------------------------------------------------------
 
 struct mjOption_ {                // physics options

include/mujoco/mjplugin.h

@@ -20,6 +20,33 @@
 #include <mujoco/mjvisualize.h>
 
 
+//---------------------------------- Resource Provider ---------------------------------------------
+
+#define mjVFS_PREFIX    "vfs://"  // prefix for VFS providers
+
+// callback for opeing a resource, returns zero on failure
+typedef int (*mjfOpenResource)(mjResource* resource);
+
+// callback for reading a resource
+// return number of bytes stored in buffer, return -1 if error
+typedef int (*mjfReadResource)(mjResource* resource, const void** buffer);
+
+// callback for closing a resource (responsible for freeing any allocated memory)
+typedef void (*mjfCloseResource)(mjResource* resource);
+
+// struct describing a single resource provider
+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;
+
+
+//---------------------------------- Plugins -------------------------------------------------------
+
 typedef enum mjtPluginCapabilityBit_ {
   mjPLUGIN_ACTUATOR = 1<<0,
   mjPLUGIN_SENSOR   = 1<<1,

include/mujoco/mujoco.h

@@ -1192,6 +1192,25 @@ MJAPI const mjpPlugin* mjp_getPlugin(const char* name, int* slot);
 // Look up a plugin by the registered slot number that was returned by mjp_registerPlugin.
 MJAPI const mjpPlugin* mjp_getPluginAtSlot(int slot);
 
+// Set default resource provider definition.
+MJAPI void mjp_defaultResourceProvider(mjpResourceProvider* provider);
+
+// 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.
+MJAPI int mjp_registerResourceProvider(const mjpResourceProvider* provider);
+
+// Return the number of globally registered resource providers.
+MJAPI int mjp_resourceProviderCount();
+
+// Return the resource provider with the prefix that matches against the resource name.
+// If no match, return NULL.
+MJAPI const mjpResourceProvider* mjp_getResourceProvider(const char* resource_name);
+
+// Look up a resource provider by slot number returned by mjp_registerResourceProvider.
+// If invalid slot number, return NULL.
+MJAPI const mjpResourceProvider* mjp_getResourceProviderAtSlot(int slot);
+
 
 #if defined(__cplusplus)
 }