Document the VRAM loading process

game/src/utilities/datastore.rs

@@ -1,7 +1,8 @@
-use std::io::Write;
+use std::{io::Write, path::Path};
 
 use raylib::{texture::Texture2D, RaylibHandle, RaylibThread};
-use tempfile::{NamedTempFile};
+use tempfile::{tempdir, NamedTempFile};
+use tracing::debug;
 
 /// Contains all game assets.
 ///
@@ -21,13 +22,26 @@ pub enum ResourceLoadError {
     Generic(String),
 }
 
+/// Loads an embedded texture into VRAM.
+///
+/// # Technical Info
+/// In this application, we are using `rust_embed` to embed static assets directly inside the executable.
+/// This has the limitation of none of the assets being "real files", which causes an issue with Raylib.
+/// Raylib requires a "real file" in order to load data into VRAM (without digging into `unsafe` dark magic).
+/// The solution is to temporarily write the assets to disk, and then load them from disk.
+/// We must also preserve the file extension, so the Raylib file loader can parse them correctly.
 pub fn load_texture_from_internal_data(
     raylib_handle: &mut RaylibHandle,
     thread: &RaylibThread,
     path: &str,
 ) -> Result<Texture2D, ResourceLoadError> {
     // Create a temp file path to work with
-    let tmp_path = NamedTempFile::new()?.into_temp_path();
+    let temp_dir = tempdir()?;
+    debug!(
+        "Created temporary directory for passing embedded data to Raylib: {}",
+        temp_dir.path().display()
+    );
+    let tmp_path = temp_dir.path().join(Path::new(path).file_name().unwrap());
 
     // Unpack the raw image data to a real file on the local filesystem so raylib will read it correctly
     std::fs::write(
@@ -38,10 +52,16 @@ pub fn load_texture_from_internal_data(
     )?;
 
     // Call through via FFI to re-load the file
-    let texture = raylib_handle.load_texture(thread, tmp_path.to_str().unwrap()).map_err(ResourceLoadError::Generic)?;
+    let texture = raylib_handle
+        .load_texture(thread, tmp_path.to_str().unwrap())
+        .map_err(ResourceLoadError::Generic)?;
 
     // Close the file
-    tmp_path.close()?;
+    debug!(
+        "Dropping temporary directory: {}",
+        temp_dir.path().display()
+    );
+    temp_dir.close()?;
 
     Ok(texture)
 }