async_loader.h File Reference

Threaded asynchronous file loader for heavy assets (HDR, textures). More...

#include "gl_common.h"
#include <stdbool.h>
#include <stdint.h>

Include dependency graph for async_loader.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	AsyncRequest
	Container for asynchronous load results and metadata. More...

Macros
#define	ASYNC_MAX_PATH   256
	Maximum path length for an asynchronous load request. More...

Enumerations
enum	AsyncState {   ASYNC_IDLE = 0 , ASYNC_PENDING , ASYNC_LOADING , ASYNC_WAITING_FOR_PBO ,   ASYNC_CONVERTING , ASYNC_READY , ASYNC_FAILED }
	Lifecycle states for an individual asynchronous request. More...

Functions
AsyncLoader *	async_loader_create (struct TracyManager *mgr)
	Creates and initializes a new async loader instance. More...
void	async_loader_destroy (AsyncLoader *loader)
	Destroys the async loader and frees resources. More...
bool	async_loader_request (AsyncLoader *loader, const char *path)
	Submits a new file path for background loading. More...
bool	async_loader_poll (AsyncLoader *loader, AsyncRequest *out_req)
	Polls the loader for any completed requests. More...
void	async_loader_provide_pbo (AsyncLoader *loader, void *mapped_ptr, GLuint pbo_id)
	Provides a mapped PBO pointer to the async loader for conversion. More...
void	async_loader_cancel (AsyncLoader *loader)
	Cancels the current request if it is waiting for a PBO. More...

Detailed Description

Threaded asynchronous file loader for heavy assets (HDR, textures).

This module manages a background worker thread that handles I/O and image decoding, preventing main-thread stalls during asset transitions.

Macro Definition Documentation

ASYNC_MAX_PATH

#define ASYNC_MAX_PATH   256

Maximum path length for an asynchronous load request.

Enumeration Type Documentation

AsyncState

enum AsyncState

Lifecycle states for an individual asynchronous request.

Enumerator
ASYNC_IDLE	No active request.
ASYNC_PENDING	Request submitted but not yet picked up by worker.
ASYNC_LOADING	Worker is loading/decompressing file
ASYNC_WAITING_FOR_PBO	Worker waiting for PBO from main thread
ASYNC_CONVERTING	Worker converting floats to mapped PBO
ASYNC_READY	Data is ready in PBO (or half_data if fallback)
ASYNC_FAILED	Loading failed

Function Documentation

async_loader_cancel()

void async_loader_cancel

(

AsyncLoader *

loader

)

Cancels the current request if it is waiting for a PBO.

Use this if the main thread fails to map a PBO and cannot proceed.

Parameters

loader

The loader instance.

async_loader_create()

AsyncLoader* async_loader_create

(

struct TracyManager *

mgr

)

Creates and initializes a new async loader instance.

Parameters

mgr	The Tracy instrumentation manager.

Returns

Pointer to the new loader, or NULL on failure.

Here is the call graph for this function:

async_loader_destroy()

void async_loader_destroy

(

AsyncLoader *

loader

)

Destroys the async loader and frees resources.

Parameters

loader

The loader instance to destroy.

async_loader_poll()

bool async_loader_poll	(	AsyncLoader *	loader,
		AsyncRequest *	out_req
	)

Polls the loader for any completed requests.

This should be called from the main (OpenGL) thread once per frame.

Parameters

	loader	The loader instance.
[out]	out_req	Pointer to store the successfully loaded data.

Returns

true if data was retrieved, false otherwise.

async_loader_provide_pbo()

void async_loader_provide_pbo	(	AsyncLoader *	loader,
		void *	mapped_ptr,
		GLuint	pbo_id
	)

Provides a mapped PBO pointer to the async loader for conversion.

Call this when async_loader_poll returns a request in ASYNC_WAITING_FOR_PBO state.

Parameters

loader	The loader instance.
mapped_ptr	Pointer to the mapped PBO memory.
pbo_id	ID of the PBO being used.

async_loader_request()

bool async_loader_request	(	AsyncLoader *	loader,
		const char *	path
	)

Submits a new file path for background loading.

Parameters

loader	The loader instance.
path	The absolute path to the HDR/texture file.

Returns

true if the request was successfully queued, false if queue is full.

Here is the call graph for this function: