The Fast Texture Loading Rewrite by Wartori54 · Pull Request #1031 · EverestAPI/Everest

Wartori54 · 2025-11-30T00:09:18Z

As the title suggests, this PR attempts to rewrite the entirety of the good old FTL, into a more maintainable and future proof codebase, splitting code into a new class TextureContentHelper to keep file sizes small.
The main intention of this PR is to make VirtualTexture fully thread safe, and re-enginneer an implementation of FTL.

For context FTL has simply the following goal: decode the texture data from disk to a CPU buffer asynchronously, then upload to GPU memory on the main thread. This speeds up loading times and fixes some crashes on Nvidia gpus. Theres a writeup about most of the significant FTL details at the top of the VirtualTexture file diving deep into this and other topics.

As for performance, it should be on par, this PR does not have any intentional speed improvements (in fact, it may be slower due to the heavier synchronization in VirtualTexture but it should be fairly small). I have some plans and some ongoing tests to improve performance and bound memory usage even lower, but those will land in a follow up PR once ready that will build off of this one. (Runtime atlasing is still on the TODO list, I did not forget!)

Finally CI will fail, specifically the SJ TAS test since this is breaking for CollabUtils2. Luckily that mod has been updated already to be compatible and the only required extra steps for local testing are: clone the repo and dotnet build -c Release; mostly because it has not yet been released on gamebanana.
An update has been pushed to CollabUtils2 making it compatible with the changes of this PR.

…emory usage tracking

microlith57

first pass, picking the low hanging fruit first! nothing here is blocking

Celeste.Mod.mm/Celeste.Mod.mm.csproj

Celeste.Mod.mm/Mod/Core/CoreModule.cs

Celeste.Mod.mm/Mod/Everest/Everest.Flags.cs

Celeste.Mod.mm/Mod/Helpers/TextureContentHelper.cs

Celeste.Mod.mm/Patches/GameLoader.cs

Celeste.Mod.mm/Patches/Monocle/VirtualAsset.cs

Celeste.Mod.mm/Patches/Monocle/VirtualContent.cs

Wartori54 · 2025-11-30T22:50:43Z

@microlith57 all feedback has been addressed!

maddie480 · 2025-11-30T23:26:09Z

/azp run

DashingCat

Tested on Linux and works as expected, without significant changes in loading times compared to the previous "Fast Texture Loading" implementation.

DashingCat · 2025-12-22T14:21:57Z

Celeste.Mod.mm/Mod/Core/CoreModuleSettings.cs

+        [SettingNeedsRelaunch]
+        [SettingInGame(false)]
+        [SettingIgnore] // TODO: Show as advanced setting.
+        public bool? FastTextureLoadingPoolUseGC { get; set; } = null;


I believe FastTextureLoadingPoolUseGC should be a bool instead of a bool?, as both null and false are equivalent when using the property in Celeste.Mod.mm/Mod/Helpers/TextureContentHelper.cs.

The idea behind having a default third state is the ability to change what it actually defaults to if we ever need to, because if the default were to be false we would not be able to switch all the users who didn't manually disable the feature (since we could not distinguish that).
And if you look further _FastTextureLoading and ThreadedGL have been doing this for a while now.

Popax21

Didn't have the time (or setup) to test this locally / give it more than a passing glance at times, but still gonna leave my feedback here; in total this is definitively a step in the right direction, but I am still against merging this in its current state, and think a more "radical" rewrite is needed to fully address all the shortcomings of the old system.

Popax21 · 2026-01-17T17:57:14Z

Celeste.Mod.mm/Patches/GameLoader.cs

+            // Flush the main thread queue to make sure all tasks related to FTL are completed
+            // Note: this will often be empty already but on extreme scenarios (massive amount of textures or 
+            // very old hardware) it may not
+            MainThreadHelper.Schedule(() => MainThreadHelper.Boost = 0, true).AsTask().Wait();


This does not actually "flush" the queue, since tasks enqueued before this one may enqueue continuations which would run after this one.

Popax21 · 2026-01-17T17:59:20Z

Celeste.Mod.mm/Patches/Monocle/VirtualContent.cs


 namespace Monocle {
+    // We may have concurrent usage of this class due to FTL
+    [MakeAllMethodsSynchronized]


I am not exactly sure what this is protecting against, but this seems like an incredibly jank workaround at the best of times. If the issue is FNA not being able to cope with concurrent asset creation, add explicit locks / checks to ensure it only happens from the main thread. If the issue is something Monocle-internal, add explicit locks to said accesses. Relying on implicit synchronization like that should be an absolute last resort, and only with thorough documentation why it is needed & the best solution.

The only concern here is the static member assets which is a simple List<T>. Making VirtualTexture completely thread-safe implies that methods called CreateVirtualTexture should also be thread-safe to me, and this was the easiest way out to make it safe, other than patching every single method here to add locking around that list. Changing the type of assets to a thread-safe collection felt risky due to it being from the vanilla game already.

I will clarify the motivation behind this change in the comment.

Popax21 · 2026-01-17T17:59:52Z

Celeste.Mod.mm/Patches/Celeste.cs

                mod.LoadContent(firstLoad);

-            patch_VirtualTexture.StopFastTextureLoading();
+            // There's no need to stop Ftl if it started in the first place ;)


That comment will make little sense outside of blames once the PR lands.

Popax21 · 2026-01-17T18:03:32Z

Celeste.Mod.mm/Mod/Helpers/TextureContentHelper.cs

+         * -ade
+         */
+        if (patch_VirtualTexture.FtlToggle) return true;
+        if (CoreModule.Settings.FastTextureLoading ?? Environment.ProcessorCount >= 4) {


This entire logic should probably be revisited given that it seems to have mainly been intended for / designed to prevent OOMs on 32bit .NET FW installs.

I thought that since it had not caused any trouble for a long time (that we know of) it might be worth to not worry about and roll with it. It is just a heuristic, maybe we can fine tune it after the rewrite is settled.

Popax21 · 2026-01-17T18:04:07Z

Celeste.Mod.mm/Mod/Helpers/TextureContentHelper.cs

+            inGC = CoreModule.Settings.FastTextureLoadingPoolUseGC ?? false;
+        } else {
+            inGC = false;
+            // Looking for a cleaner way, adding an Initialize method would make ugly the other methods and fields (need to check if init-ed on each call)


Yuck.
(also a bunch of typos in the comments here)

Popax21 · 2026-01-17T18:15:03Z

Celeste.Mod.mm/Mod/Helpers/TextureContentHelper.cs

+        }
+        return false;
+    }
+


Stopped giving this a look at this point; first impression is that is replacing one really jank, obtuse system, for another extremely jank, obtuse system, that retains a bunch of smelly code fragments from the old system while also reinventing the wheel a bunch (custom memory management without any actual justification for it, reinventions of System.Buffers.[Array|Memory]Pool<T>, trying to support both GCed and unmanaged memory even tho the only performance difference would be during (de)allocation and not during actual texture loading, etc etc).

IMHO this is definitely the wrong path / approach, and an FTL rewrite should not include any attempts at whatever this is when the STL already supports a lot of what we need. If it turns out that we do need custom memory management for performance reason this is definitively not the way to do it, and instead it should actually be a system that gets dedicated pages and applies some sort of simple bump/slab allocator tuned for our use case, not just further divide system heap chunks handed out by AllocHGlobal.

May you point out the smelly code fragments that you are referring to? As far as I'm aware everything I kept from the old code base is just code that already was good as is (reading the ".data" file format, reading a png through FNA's APIs, redirecting to the correct loader method when loading from a path), or was the FTL heuristics, which I kept as is because of what I said in my other comment.
Design wise, one of the old similarities to the old system is defining a solid upper bound to the FTL memory usage: for PNG textures we cannot really know how memory will be used because stb_image wont allow us to pass in a custom allocator or get any insight on it, for the .data textures we use that memory manager to utilize preallocated buffers and not rely on the GC to allocate the memory for us. This felt like a nice way to guarantee that FTL can be as aggressive as possible while also not overloading the system, compared limiting the amount of textures loaded asynchronously at any point in time, which wont be nearly as optimal. (But, if you come up with any other way to limit FTL's aggressiveness I'm open to discussing that.)
Limiting the maximum amount of memory used by FTL also motivates writing my own simplistic allocator, AFAIR I could not find anything in the standard library that fulfilled all my requirements so I just made my own. (As a side note, currently most textures that are loaded are in a PNG format, but I was planning and hoping for that to change with followup PRs about per-mod atlasing to load all mod textures from a single atlas, which would be stored in a ".data" file for decoding speed and to allow better memory management, this is still on the testing phase though.)
And with that came wanting to be able to switch between managed or unmanaged memory, in case that could matter for performance (reducing GC stress?) but benchmarks turned out to be very similar in either case. I can strip this functionality away if you think it is just code bloat, I kept it in case it could matter for other systems.

Popax21 · 2026-01-17T18:19:13Z

Celeste.Mod.mm/Patches/Monocle/VirtualAsset.cs

-        public int Width { get; internal set; }
-        public int Height { get; internal set; }
+
+        // Making Width and Height virtual is a breaking change, so lets just add new virtual properties and make the


Instead of replacing the properties with virtual ones (which kills performance on hot paths), instead introduce a virtual HandleSizeChange() method that gets called from within the non-virtual setters (if that's even needed, I am 99% sure that the size of assets does not actually change post-creation).

Popax21 · 2026-01-17T18:23:00Z

Celeste.Mod.mm/Patches/Monocle/VirtualTexture.cs

+// 
+// Finally, this class is also tasked with the headless mode loading optimizations, where all textures which can be preloaded
+// will have its Texture2D set to a 1x1 texture, this is purely for performance’s sake. Textures which cannot be preloaded will
+// be loaded as usual.


We also definitively want to introduce a helper method somewhere to "force" the load of a lazy-loaded texture as well.

IMO the whole API surface here needs some simplifying / nailing down: ideally we want to give modders a way to say "hey, don't load this (set of) texture(s) ahead of time; I'll tell you when you need to load it" (with a logged warning + stutter from on-demand lazy loading when they forget to do so). In a hypothetical future world this API could then also be extended to allow for auto-atlas-ification of these texture sets, which should AFAICT also hold a much bigger performance boost than lazy loading should provide (since the overhead of uploading textures over the bus is almost certainly gonna be our bottleneck on discrete GPUs, so minimizing the amount of unique textures is a much bigger deal - I assume this PR was tested on those, and not just on iGPUs where texture uploads are really cheap because of unified memory).

There is already an API for that, currently it is an event that's fired on each VirtualTexture creation that allows any mod to force the lazy loading of the texture, it was mainly designed to be directly compatible with CU2.
I'm open to suggestions on this API, are you referring to some sort of similar system to MonoMod's using-DetourConfigContext (as seen here)?

Popax21 · 2026-01-17T18:24:45Z

Celeste.Mod.mm/Patches/Monocle/VirtualTexture.cs

+            }
+        }

        private static extern void orig_cctor();


Remove this MonoMod override now that it's unused.

Popax21 · 2026-01-17T18:34:22Z

Celeste.Mod.mm/Patches/Monocle/VirtualTexture.cs

+        /// <exception cref="AggregateException">Thrown if the reload happened asynchronously and there was an exception during it.</exception>
        [MonoModLinkFrom("Microsoft.Xna.Framework.Graphics.Texture2D Monocle.VirtualTexture::Texture")]
-        public Texture2D Texture_Safe {
+        public Texture2D? Texture_Safe {


Similar comments to TextureContentHelper; while this is no doubts better than the old (undocumented) code, it still replaces one jank, obtuse system with another similarly jank, obtuse, but this time documented / slightly better structured system. IMO it still inherits a lot of design baggage related to somehow constructing its own mechanisms for synchronizing concurrent loads without making proper use of the available STL primitives.

I don't have the time to give all of this a full proper read, so I don't doubt that in practice it's gonna be more complicated than I will describe, but it should be possible to boil down all of this sync / locking logic down into a single [Value]Task stored in the VirtualTexture that is running either on the main thread or an FTL thread(pool) / might just be a Task.FromResult, which should greatly simplify the logic / remove a ton of jank.

Wartori54 added 26 commits November 30, 2025 00:27

Remove last MonoModIfFlag("XNA") dependent code

7244c68

Remove superfluous MonoMod patching

8bf1c81

Go back to an unoptimized and single threaded texture loading

d484b99

Fix some bugs and polish code

1db69f4

Make VirtualTexture thread-safe

5c88d3d

Initial FTL reimpl

c98c1ff

Fix out of bounds read and reduce unsafe scopes

eabee40

Fix memory leak, locking and logging

c591480

Add main thread timeout for unmanaged allocations

3953836

Add force lazy load event

9173b30

Fix wrong usage of memory limit

c00ce39

Add tracing for gc and over budget allocs

8679173

Add exception handling to FTL

76720b1

Fix Stopwatch not being started, and forceQueue not doing anything

ae14123

Remove FTL timer

de004e5

Move FTL startup into a method so that it can be started earlier/later

886f192

Disallow changing Path of VirtualTexture and make resizes thread-safe

660e7be

Remove leftover TODO

bc793aa

Use TextureKind for more clear code and some cleanups

4cbf209

Make texture overrides possible, safe and consistent

48c0193

(Try to) Get headless right again

f851c21

Fix remaining TODOs

068ac8c

Add extra logging preprocessor directives for managed and unmanaged m…

ed32736

…emory usage tracking

Add event for lazy loads on texture access

015f4fa

Add documentation to VirtualTexture

4d81295

Add documentation to TextureContentHelper

33040ff

maddie480-bot added the 1: review needed This PR needs 2 approvals to be merged (bot-managed) label Nov 30, 2025

microlith57 reviewed Nov 30, 2025

View reviewed changes

Wartori54 added 2 commits November 30, 2025 23:15

Fix some typos and leftover comments

4ad0a29

Add timing and logging for the MainThreadHelper queue flush

18b309c

Make VirtualContent synchronized

888e0ca

Rerun pipeline

f232dea

maddie480 force-pushed the ftl-rewrite branch from 6d31720 to f232dea Compare December 1, 2025 07:10

Make vTex.Reload(); vTex.Unload(); deterministic

5ecc0b4

DashingCat approved these changes Dec 22, 2025

View reviewed changes

maddie480-bot added the review needed label Jan 8, 2026

maddie480 removed the review needed label Jan 8, 2026

Wartori54 added the rewrite An existing feature needs a rewrite label Jan 8, 2026

Popax21 requested changes Jan 17, 2026

View reviewed changes

maddie480-bot added 2: changes requested This PR cannot be merged because changes were requested (bot-managed) and removed 1: review needed This PR needs 2 approvals to be merged (bot-managed) labels Jan 17, 2026

Conversation

Wartori54 commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

microlith57 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Wartori54 commented Nov 30, 2025

Uh oh!

maddie480 commented Nov 30, 2025

Uh oh!

DashingCat left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Popax21 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Wartori54 Jan 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Wartori54 commented Nov 30, 2025 •

edited

Loading

Wartori54 Jan 22, 2026 •

edited

Loading