Assets

Host-owned textures and the store they are loaded from.

Open a store, load textures from it, keep them in the model, and draw them. All three steps happen in init! in most apps:

init! = App.init(
    App.default,
    |_startup| {
        store = Assets.Store.open!(Assets.working_directory("assets"))?
        Ok({ logo: Assets.load_texture!(store, "logo.png")?, store })
    },
)

render! = |model, frame| {
    frame.texture!(Draw.texture_at(model.logo, { x: 32, y: 32 }))
    Ok({})
}

A store is an explicitly located directory the host holds a handle to, so every relative asset path means the same thing however the process was launched. The host never calls chdir, and a path that would escape the store is refused rather than rewritten.

Textures are the shared texture type from the companion roc-ray-types package, re-exported here as Assets.Texture. Releasing the final reference to one unloads the native texture automatically, so there is no unload to remember.

The two effects that read the disk -- Store.open! and load_texture! -- wait: each is legal in init!, where it blocks startup, and in tasks, where it parks the task; both are refused in update! and render!. Everything else here builds a texture from bytes the app already holds -- texture_from_bytes!, generate_color_texture!, generate_checked_texture!, update_texture! -- and is legal in init!, update!, and tasks, and refused in render!, where a decode or an upload would land in the middle of drawing a frame.

That split is what a texture loaded after startup goes through: read the file on a task with Files.read_bytes!, return the bytes as the task's message, and call texture_from_bytes! from update! when the message arrives. Calling load_texture! inside the task itself does the same in one step, which is what a hot reload wants -- poll Files.metadata! on a task, and load again when the modification time moves.

ResourceLimit on any of them means the host's fixed texture table is full. It is a bound on how many textures exist at once, not on how fast they are made, so it is answered rather than retried: release a texture the app no longer draws, or load fewer.

beside_executable : Str -> StoreConfig

Start from an application/executable-relative asset directory. This is the normal packaged-app choice: the assets travel with the executable, so the store resolves the same way however the app was launched.

working_directory : Str -> StoreConfig

Start from a directory relative to the process working directory. This is what running an example from the repository root wants, and what a tool invoked from a project directory wants; it moves with the shell rather than with the executable.

absolute_directory : Str -> StoreConfig

Start from an absolute path, for a store the app was told about at runtime -- a mod directory, or a content pack chosen from argv.

with_manifest : StoreConfig, ManifestExpectation -> StoreConfig

Require this store's roc-assets.manifest to match an expectation, so a mismatched or half-updated asset set fails at startup rather than as a missing texture later.

rgba_byte_size : List(Rgba) -> U64

How many bytes an RGBA pixel list occupies on the wire: four per pixel.

An upload borrows the list rather than copying it, so this is what an app measures a update_texture! or update_texture_region! against when it is budgeting per-frame pixel traffic.

load_texture! : Store, Str => Try(Texture, [PathInvalid, NotFound, ReadFailed, TextureLoadFailed, ResourceLimit, ..])

Load an image relative to an explicit store.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!. The file is read off the frame thread; the decode and the GPU upload happen when the bytes are back. To load after startup, call this inside Task.spawn!, or read the bytes on a task and call texture_from_bytes! from update!.

path must be relative; PathInvalid is an absolute path, one holding a NUL, or a lexical .. escape, and is answered before any file I/O. NotFound is no such file under the store, ReadFailed is a file that is there and could not be read, and TextureLoadFailed is bytes raylib would not decode as an image.

texture_from_bytes! : TextureBytes => Try(Texture, [TextureLoadFailed, ResourceLimit, ..])

Decode an authored image embedded with a compile-time file import.