Add checksums (used as a timestamp) to VFS.

Deprecate mj_makeEmptyFileVFS in favor of mj_addBufferVFS.

PiperOrigin-RevId: 608915388
Change-Id: Id9e9b042799bc1bf547f0795ae6f386447d53cdd

doc/APIreference/functions.rst

@@ -1109,14 +1109,14 @@ mj_addFileVFS
 Add file to VFS. The directory argument is optional and can be NULL or empty. Returns 0 on success, 1 when VFS is full,
 2 on name collision, or -1 when an internal error occurs.
 
-.. _mj_makeEmptyFileVFS:
+.. _mj_addBufferVFS:
 
-mj_makeEmptyFileVFS
-~~~~~~~~~~~~~~~~~~~
+mj_addBufferVFS
+~~~~~~~~~~~~~~~
 
-.. mujoco-include:: mj_makeEmptyFileVFS
+.. mujoco-include:: mj_addBufferVFS
 
-Make empty file in VFS, return 0: success, 1: full, 2: repeated name.
+Add file to VFS from buffer, return 0: success, 1: full, 2: repeated name, -1: failed to load.
 
 .. _mj_findFileVFS:
 
@@ -1145,6 +1145,15 @@ mj_deleteVFS
 
 Delete all files from VFS.
 
+.. _mj_makeEmptyFileVFS:
+
+mj_makeEmptyFileVFS
+~~~~~~~~~~~~~~~~~~~
+
+.. mujoco-include:: mj_makeEmptyFileVFS
+
+deprecated: use mj_copyBufferVFS.
+
 .. _Initialization:
 
 Initialization

doc/changelog.rst

@@ -12,20 +12,25 @@ General
    :at:`ctrlrange` or :at:`actrange` (respectively), according to the range of the transmission
    target (joint or tendon). See :ref:`position/inheritrange<actuator-position-inheritrange>` for
    details.
+2. Deprecated :ref:`mj_makeEmptyFileVFS` in favor of :ref:`mj_addBufferVFS`. :ref:`mjVFS` now computes checksums of
+   its internal file buffers. :ref:`mj_addBufferVFS` allocates an empty buffer with a given name in an mjVFS and
+   copies the data buffer into it, combining and replacing the deprecated two-step process of calling
+   :ref:`mj_makeEmptyFileVFS` followed by a direct copy into the given mjVFS internal file buffer.
 
 MJX
 ^^^
-2. Improved performance of getting and putting device data.
+
+3. Improved performance of getting and putting device data.
 
    - Use ``tobytes()`` for numpy array serialization, which is orders of magnitude faster than converting to tuples.
    - Avoid reallocating host ``mjData`` arrays when array shapes are unchanged.
    - Speed up calculation of ``mjx.ncon`` for models with many geoms.
    - Avoid calling ``mjx.ncon`` in ``mjx.get_data_into`` when ``nc`` can be derived from ``mjx.Data``.
-3. Fixed a bug in ``mjx-viewer`` that prevented it from running.  Updated ``mjx-viewer`` to use newer
+4. Fixed a bug in ``mjx-viewer`` that prevented it from running.  Updated ``mjx-viewer`` to use newer
    ``mjx.get_data_into`` function call.
-4. Fixed a bug in ``mjx.euler`` that applied incorrect damping when using dense mass matrices.
-5. Fixed a bug in ``mjx.solve`` that was causing slow convergence when using ``mjSOL_NEWTON`` in :ref:`mjtSolver`.
-6. Added support for :ref:`mjOption.impratio<mjOption>` to ``mjx.Model``.
+5. Fixed a bug in ``mjx.euler`` that applied incorrect damping when using dense mass matrices.
+6. Fixed a bug in ``mjx.solve`` that was causing slow convergence when using ``mjSOL_NEWTON`` in :ref:`mjtSolver`.
+7. Added support for :ref:`mjOption.impratio<mjOption>` to ``mjx.Model``.
 
 Python bindings
 ^^^^^^^^^^^^^^^

doc/includes/references.h

@@ -691,11 +691,12 @@ 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
-  char   filename[mjMAXVFS][mjMAXVFSNAME];  // file name without path
-  size_t filesize[mjMAXVFS];                // file size in bytes
-  void*  filedata[mjMAXVFS];                // buffer with file data
+struct mjVFS_ {                               // virtual file system for loading from memory
+  int      nfile;                             // number of files present
+  char     filename[mjMAXVFS][mjMAXVFSNAME];  // file name without path
+  size_t   filesize[mjMAXVFS];                // file size in bytes
+  void*    filedata[mjMAXVFS];                // buffer with file data
+  uint64_t filestamp[mjMAXVFS];               // checksum of the file data
 };
 typedef struct mjVFS_ mjVFS;
 struct mjOption_ {                // physics options
@@ -1375,6 +1376,7 @@ typedef struct mjModel_ mjModel;
 struct mjResource_ {
   char* name;                                   // name of resource (filename, etc)
   void* data;                                   // opaque data pointer
+  char timestamp[512];                          // timestamp of the resource
   const struct mjpResourceProvider* provider;   // pointer to the provider
 };
 typedef struct mjResource_ mjResource;
@@ -2406,10 +2408,11 @@ typedef struct mjvSceneState_ mjvSceneState;
 //----------------------------- MJAPI FUNCTIONS --------------------------------
 void mj_defaultVFS(mjVFS* vfs);
 int mj_addFileVFS(mjVFS* vfs, const char* directory, const char* filename);
-int mj_makeEmptyFileVFS(mjVFS* vfs, const char* filename, int filesize);
+int mj_addBufferVFS(mjVFS* vfs, const char* name, const void* buffer, int nbuffer);
 int mj_findFileVFS(const mjVFS* vfs, const char* filename);
 int mj_deleteFileVFS(mjVFS* vfs, const char* filename);
 void mj_deleteVFS(mjVFS* vfs);
+int mj_makeEmptyFileVFS(mjVFS* vfs, const char* filename, int filesize);
 mjModel* mj_loadXML(const char* filename, const mjVFS* vfs, char* error, int error_sz);
 int mj_saveLastXML(const char* filename, const mjModel* m, char* error, int error_sz);
 void mj_freeLastXML(void);