Lagoon

Lagoon

[GameMaker library]  Deferred and batched surface readbacks.

With this library, you can collect several small readback request into single large readback. You can also collect requests over the frames.

In GameMaker, you can only read back the whole full surface, you cannot take portions of it. Lagoon allows you to read small portion of surface. Under the hood Lagoon has own surface, where it copies requested items.

This can be useful for example whenever you are faking compute shaders with Fragment shaders and floating-point textures, and need to read small portion from surface, which is acting like your compute buffer. 

---

To use the Lagoon, you can either use structures directly or use simplified version. The simplified version wraps Lagoon usage, so it acts more akin to "buffer_get_surface". In simplified, the readback is "async"ish, done at the end of frame.

Using Lagoon-handle directly you can collect however many requests you want before readback and have more control overall. You need to handle readback timing yourself, as it is not automatic like in simplified version. Though you can just make instance which does "lagoon.Await()".

---

How it actually works

With each request, requested item is placed on the accumulator surface, waiting to be read back. Accumulator surface has initial capacity. When you keep adding new requests, the capacity might be exceeded, so Lagoon handles surface resizing without losing previously accumulated requests. Whenever user is ready, they can "synchronize" by calling ".Await()" -method. This makes Lagoon to do actual readback. The accumulator might have too large size compared actually accumulated items, so there is unnecessary "garbage data". In these cases Lagoon handles moving accumulator data into smaller surface before readback.

The readback is done into single buffer. After the readback is done, buffer contains data for all requests. Lagoon executes request callbacks, passing request and buffer as arguments. The request handle contains information, which can be used to access buffer at right position and right amount. The surface might have used several different formats, such as rgba32float or r8unorm. The request contains information for reading the buffer correctly, such as how many components pixel had, and what buffer datatype should be used. The simplified lagoon_submit mimics buffer_get_surface, and just copies contents into target buffer.

Made for Cookbook Jam #5

https://github.com/HannulaTero/Lagoon