byte_engine / rendering / resource_loading

Module `resource_loading`

Shared asynchronous render-resource loading and GPU upload lifecycle.

This module solves the parts every renderer needs: stable request identity, duplicate coalescing, bounded client/server queues, retry-safe completion routing, exclusive staging memory, and GPU-frame lifetime tracking. It does not define a universal GPU resource or storage layout. The renderer keeps that policy by defining its RenderResource::Prepared value and implementing ResourceUploadStore.

Build a renderer integration

Work from the renderer toward the shared lifecycle:

Implement RenderResource as the protocol for one renderer. Keep logical identity in RenderResource::Key, owned worker input in RenderResource::Request, and storage-independent results in RenderResource::Prepared.
Implement ResourcePreparer for resource I/O and CPU conversion. A preparer may create detached factory resources, but it must not assign renderer buffer offsets, bindless slots, or other resident identities. For a baked 2D texture, use PreparedTextureTransfer to share mip, staging, and native-I/O mechanics without sharing image or sampler policy.
Create a ResourceLoader on the render thread. Convert its ResourceLoadingEndpoint into one or more ResourceLoadingServer values, and run each server on an application-owned async task.
At crate::rendering::PipelineManager::begin_frame, submit queued requests and drain ResourceCompletion values. Publish results that need no GPU work with ResourceLoader::mark_ready. Enqueue transfer work in a FrameUploadQueue.
At crate::rendering::PipelineManager::record_frame_uploads, pass the queue to the renderer's ResourceUploadStore. The store chooses the destination objects, memory layout, offsets, table slots, and resident handle.
At the next matching frame completion, call FrameUploadQueue::retire_frame. Only then publish its (token, resident) values to scene rendering.

Follow one request back to the renderer

The reverse direction explains who calls renderer code and why:

ResourceLoader::submit_requests transfers owned requests to a server without waiting on the render thread.
ResourceLoadingServer::run calls ResourcePreparer::prepare on its own sequential lane. Clone the endpoint when independent lanes should compete for work; give every lane its own preparer state.
ResourceLoader::take_completion returns only the current request revision. Cancelled and superseded work is discarded before it can reach renderer storage.
FrameUploadQueue::record_frame calls ResourceUploadStore::record while recording transfer commands. This is the deliberate policy seam: two renderers can load the same logical mesh and still choose unrelated GPU layouts.
FrameUploadQueue::retire_frame returns the store's resident value only after the exact frame that used its upload data has completed.

Ownership and thread placement

Keep ResourceLoader, FrameUploadQueue, and the renderer store on the render thread. Move each ResourceLoadingServer and its ResourcePreparer to an async task. Share UploadStagingArena with preparers, but run its single UploadStagingWorker on an async task. This arrangement keeps synchronization and task ownership above GHI while the queue retains StagingLease values for the complete GPU-use interval.

The application must stop and join loading tasks before dropping the renderer, its GHI context, or the mapped upload buffer. Dropping the loader closes the request side; servers then finish or stop, dropping every arena client closes the staging worker, and completed upload values return their leases automatically.

Choose a GPU creation path

Use FrameUploadQueue when a render-thread command recording writes the resident resource. A preparer can also create detached GHI factory objects; the render thread interns them before queueing their transfer. Native GPU I/O may bypass the queue, but it must use the same lifecycle contract: call ResourceLoader::mark_uploading before submission, then ResourceLoader::mark_ready only after the native completion makes the resident usable. Call ResourceLoader::mark_failed when adoption or native I/O cannot finish.

Failure, cancellation, and retry

A ResourceRef identifies the logical resource for the lifetime of one loader. A ResourceToken adds a revision so late work cannot publish over a retry. Cancel only ResourceState::Queued or ResourceState::Loading work. Once storage or GPU I/O claims a resource as ResourceState::Uploading, cleanup belongs to the renderer because the shared lifecycle cannot undo implementation-specific allocation. Retry failed or cancelled references with ResourceLoader::retry; dependent resources remain a renderer concern because only that renderer knows its material, texture, mesh, or environment graph.

Minimal protocol

use std::future::Future;
use byte_engine::rendering::resource_loading::{
    RenderResource, ResourceLoader, ResourcePreparer, ResourceUploadStore,
};

enum MeshResource {}

impl RenderResource for MeshResource {
    type Key = &'static str;
    type Request = &'static str;
    type Prepared = Vec<u8>;
    type Error = String;
}

struct MeshPreparer;

impl ResourcePreparer<MeshResource> for MeshPreparer {
    fn prepare(
        &mut self,
        request: &'static str,
    ) -> impl Future<Output = Result<Vec<u8>, String>> + '_ {
        async move { Ok(request.as_bytes().to_vec()) }
    }
}

struct MeshStore;

impl ResourceUploadStore for MeshStore {
    type Upload = Vec<u8>;
    type Resident = usize;
    type Error = String;

    fn record(
        &mut self,
        _recording: &mut byte_engine::ghi::implementation::CommandBufferRecording<'_>,
        upload: &Self::Upload,
    ) -> Result<Self::Resident, Self::Error> {
        // This renderer chooses the destination buffers, offsets, and resident ID.
        Ok(upload.len())
    }
}

let (mut loader, endpoint) = ResourceLoader::<MeshResource>::new(4_096, 64);
let server = endpoint.server(MeshPreparer);
let mesh = loader.request("scene.mesh", "scene.mesh").expect("resource capacity");
loader.submit_requests(64);

// Run `server.run()` on an application-owned async task. At frame
// boundaries, call `loader.take_completion()` and adopt its result.
let _ = (mesh, server);

Quick Reference

Item	Kind	Description
`ResourceCompletion`	struct
`ResourceLoader`	struct
`ResourceLoadingEndpoint`	struct
`ResourceLoadingServer`	struct
`ResourceRef`	struct
`ResourceToken`	struct
`NativeTextureUpload`	struct
`PreparedTextureTransfer`	struct
`StagedTextureUpload`	struct
`TextureMetadata`	struct
`FrameUploadQueue`	struct
`StagingLease`	struct
`UploadStagingArena`	struct
`UploadStagingWorker`	struct
`ResourceState`	enum
`PreparedTextureSource`	enum
`TexturePreparationError`	enum
`RenderResource`	trait
`ResourcePreparer`	trait
`ResourceUploadStore`	trait

Structs

`ResourceCompletion<R: RenderResource>`

struct ResourceCompletion<R: RenderResource> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:132-135

The ResourceCompletion struct returns one current preparation result to the renderer thread.

Consume completions at a frame boundary. On success, either publish an immediately usable value with ResourceLoader::mark_ready or enqueue GPU work. Preparation failures are already marked ResourceState::Failed by ResourceLoader::take_completion.

Implementations

```
fn token(&self) -> ResourceToken
```
Related: ResourceToken

Returns the exact request revision associated with this result.
```
fn into_result(self) -> Result<<R as >::Prepared, <R as >::Error>
```
Related: RenderResource

Moves the renderer-specific prepared value or error out of the completion.

Trait Implementations

`impl ArchivePointee for ResourceCompletion<R>`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceCompletion<R>`

`impl Downcast for ResourceCompletion<R>`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceCompletion<R>`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceCompletion<R>`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ResourceCompletion<R>`

`impl LayoutRaw for ResourceCompletion<R>`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceCompletion<R>`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ResourceCompletion<R>`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceCompletion<R>`

```
type Metadata = ()
```

`impl Read for ResourceCompletion<R>`

`impl WithSubscriber for ResourceCompletion<R>`

`ResourceLoader<R: RenderResource>`

struct ResourceLoader<R: RenderResource> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:156-164

The ResourceLoader struct keeps render-thread request identity and lifecycle changes nonblocking.

This is a client and registry, not renderer storage. Keep it beside the renderer's resident map and super::FrameUploadQueue. Request from scene adoption, drain completions in crate::rendering::PipelineManager::begin_frame, and record queued GPU work in crate::rendering::PipelineManager::record_frame_uploads.

Implementations

```
fn new(max_resources: usize, queue_capacity: usize) -> (Self, ResourceLoadingEndpoint<R>)
```
Related: ResourceLoadingEndpoint

Creates a loader with equal bounded request and completion capacities.

Use the returned loader on the render thread. Convert the endpoint with

ResourceLoadingEndpoint::server and run the server on an

application-owned async task. Use Self::with_capacity when preparation

bursts and render-thread adoption need different bounds.
```
fn with_capacity(max_resources: usize, request_capacity: usize, completion_capacity: usize) -> (Self, ResourceLoadingEndpoint<R>)
```
Related: ResourceLoadingEndpoint

Creates a loader with independent request and completion backpressure bounds.

The render thread retains unsent requests locally when the request channel

is full. Completion backpressure waits only in server tasks. This keeps

frame work nonblocking while bounding cross-thread memory. Next, attach at

least one server with ResourceLoadingEndpoint::server.
```
fn request(&mut self, key: <R as >::Key, request: <R as >::Request) -> Result<ResourceRef, <R as >::Request>
```
Related: RenderResource, ResourceRef

Coalesces one logical request and queues new work without touching a channel.

An existing key returns its original reference and ignores the new request

value, regardless of current state. Call Self::retry explicitly for a

failed or cancelled resource. On capacity failure, ownership of request

is returned so the renderer can report or retain it.
```
fn submit_requests(&mut self, max: usize) -> usize
```
Examines up to max queued entries and submits current work without blocking.

The budget counts examined entries, including stale entries skipped after

cancellation. Call this from bounded frame work; a full channel leaves the

first unsent request queued for a later call.
```
fn take_completion(&mut self) -> Option<ResourceCompletion<R>>
```
Related: ResourceCompletion

Returns the next current completion and discards cancelled or superseded work.

This method never waits. It marks an error result failed before returning

it. A successful result remains loading so the renderer can choose

Self::mark_ready for immediate adoption or let

super::FrameUploadQueue::record_frame claim it as uploading.
```
fn reference(&self, key: &<R as >::Key) -> Option<ResourceRef>
```
Related: RenderResource, ResourceRef

Finds a previously registered logical resource for scene-side coalescing.
```
fn key(&self, reference: ResourceRef) -> Option<&<R as >::Key>
```
Related: ResourceRef, RenderResource

Returns the logical key used to publish a completion into renderer maps.
```
fn token(&self, reference: ResourceRef) -> Option<ResourceToken>
```
Related: ResourceRef, ResourceToken

Returns the slot's current revision token for renderer-side asynchronous work.
```
fn state(&self, reference: ResourceRef) -> ResourceState
```
Related: ResourceRef, ResourceState

Returns the slot's current renderer-visible lifecycle state.

A reference issued by another loader reports ResourceState::Failed

because it cannot name usable state in this registry.
```
fn retry(&mut self, reference: ResourceRef) -> Option<ResourceToken>
```
Related: ResourceRef, ResourceToken

Queues a fresh revision after a failure or cancellation.

The loader reuses its retained canonical request and stable reference, but

increments the token revision. Any older completion then becomes stale.

Returns None when the reference is foreign or its state is not retryable.
```
fn cancel(&mut self, reference: ResourceRef) -> bool
```
Related: ResourceRef

Cancels queued or loading work so any preparation completion already in flight becomes stale.

Uploading and ready resources stay renderer-owned because the shared

lifecycle has no authority to reclaim an implementation's storage.
```
fn mark_uploading(&mut self, token: ResourceToken) -> bool
```
Related: ResourceToken

Claims current loading work before renderer storage or native GPU I/O changes.

Call this before the first irreversible renderer-specific action. After it

succeeds, cancellation is intentionally unavailable because only the

renderer knows how to reclaim partially assigned storage.
```
fn mark_ready(&mut self, token: ResourceToken) -> bool
```
Related: ResourceToken

Publishes current loading or uploading work after its resident state is usable.

For uploads, prefer super::FrameUploadQueue::retire_frame so readiness

cannot precede GPU completion. Direct use is appropriate for CPU-only

adoption, interned objects needing no transfer, or completed native I/O.
```
fn mark_failed(&mut self, token: ResourceToken) -> bool
```
Related: ResourceToken

Marks current loading or uploading work as failed after adoption cannot finish.

The renderer must first release or quarantine any storage it already

assigned. Call Self::retry later when recovery is appropriate.
```
fn is_current(&self, token: ResourceToken) -> bool
```
Related: ResourceToken

Returns whether a completion, upload, or native callback belongs to the current revision.

Trait Implementations

`impl ArchivePointee for ResourceLoader<R>`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceLoader<R>`

`impl Downcast for ResourceLoader<R>`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceLoader<R>`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceLoader<R>`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ResourceLoader<R>`

`impl LayoutRaw for ResourceLoader<R>`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceLoader<R>`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ResourceLoader<R>`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceLoader<R>`

```
type Metadata = ()
```

`impl Read for ResourceLoader<R>`

`impl WithSubscriber for ResourceLoader<R>`

`ResourceLoadingEndpoint<R: RenderResource>`

struct ResourceLoadingEndpoint<R: RenderResource> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:446-449

The ResourceLoadingEndpoint struct lets independent server lanes consume one loader's work.

Clone this value to add parallel preparation lanes. Receivers compete for requests rather than broadcasting them, and every server sends results to the same completion queue. Give each server its own ResourcePreparer so thread-local factories and conversion state do not need locks.

Implementations

```
fn server<P: ResourcePreparer<R>>(self, preparer: P) -> ResourceLoadingServer<R, P>
```
Related: ResourceLoadingServer

Attaches one renderer preparer without spawning its application-owned task.

Move the returned server into the application's task system and call

ResourceLoadingServer::run.

Trait Implementations

`impl ArchivePointee for ResourceLoadingEndpoint<R>`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceLoadingEndpoint<R>`

`impl<R: RenderResource> Clone for ResourceLoadingEndpoint<R>`

```
fn clone(&self) -> Self
```

`impl Downcast for ResourceLoadingEndpoint<R>`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceLoadingEndpoint<R>`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceLoadingEndpoint<R>`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ResourceLoadingEndpoint<R>`

`impl LayoutRaw for ResourceLoadingEndpoint<R>`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceLoadingEndpoint<R>`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ResourceLoadingEndpoint<R>`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceLoadingEndpoint<R>`

```
type Metadata = ()
```

`impl Read for ResourceLoadingEndpoint<R>`

`impl WithSubscriber for ResourceLoadingEndpoint<R>`

`ResourceLoadingServer<R: RenderResource, P>`

struct ResourceLoadingServer<R: RenderResource, P> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:493-496

The ResourceLoadingServer struct provides one sequential worker lane for a renderer preparer.

The application owns task placement and shutdown. Run Self::run on an async executor; add throughput by creating more servers from cloned ResourceLoadingEndpoint values instead of sharing one preparer.

Implementations

```
async fn run(self)
```
Prepares requests sequentially and applies completion backpressure only on this async lane.

The loop stops when the render-side loader is dropped or the endpoint is

otherwise closed. In-flight preparation is allowed to finish before its

completion send observes shutdown.

Trait Implementations

`impl ArchivePointee for ResourceLoadingServer<R, P>`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceLoadingServer<R, P>`

`impl Downcast for ResourceLoadingServer<R, P>`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceLoadingServer<R, P>`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceLoadingServer<R, P>`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for ResourceLoadingServer<R, P>`

`impl LayoutRaw for ResourceLoadingServer<R, P>`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceLoadingServer<R, P>`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for ResourceLoadingServer<R, P>`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceLoadingServer<R, P>`

```
type Metadata = ()
```

`impl Read for ResourceLoadingServer<R, P>`

`impl WithSubscriber for ResourceLoadingServer<R, P>`

`ResourceRef`

struct ResourceRef {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:45-48

The ResourceRef struct provides stable logical identity within one renderer loader.

Store this in pending scene state to follow a resource across preparation, cancellation, and retry. It is deliberately not a GPU handle or renderer slot. Use ResourceLoader::key to recover the logical key and ResourceLoader::token when starting revision-specific work.

Implementations

```
fn index(self) -> usize
```
Returns the stable registry index for compact renderer-side lookup tables.

The index is meaningful only to the loader that issued this reference. It

must not be used as a GPU buffer offset, texture slot, or resident handle.

Trait Implementations

`impl ArchivePointee for ResourceRef`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceRef`

`impl Clone for ResourceRef`

```
fn clone(&self) -> ResourceRef
```
Related: ResourceRef

`impl Copy for ResourceRef`

`impl Debug for ResourceRef`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for ResourceRef`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceRef`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceRef`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for ResourceRef`

`impl<K> Equivalent for ResourceRef`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Hash for ResourceRef`

fn hash<__H: hash::Hasher>(&self, state: &mut __H)

`impl Instrument for ResourceRef`

`impl LayoutRaw for ResourceRef`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceRef`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for ResourceRef`

fn eq(&self, other: &ResourceRef) -> bool

Related: ResourceRef

`impl Pointable for ResourceRef`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceRef`

```
type Metadata = ()
```

`impl Read for ResourceRef`

`impl StructuralPartialEq for ResourceRef`

`impl WithSubscriber for ResourceRef`

`ResourceToken`

struct ResourceToken {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:74-77

The ResourceToken struct prevents stale work from publishing over a newer request revision.

Pass the token beside prepared, upload, or native-I/O work. Before changing renderer storage, validate it through ResourceLoader::mark_uploading. The stable Self::reference remains the same when ResourceLoader::retry creates a newer token.

Implementations

```
fn reference(self) -> ResourceRef
```
Related: ResourceRef

Returns the stable registry slot shared by every revision.
```
fn revision(self) -> u64
```
Returns the revision used to reject late preparation or upload results.

Trait Implementations

`impl ArchivePointee for ResourceToken`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceToken`

`impl Clone for ResourceToken`

```
fn clone(&self) -> ResourceToken
```
Related: ResourceToken

`impl Copy for ResourceToken`

`impl Debug for ResourceToken`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for ResourceToken`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceToken`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceToken`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for ResourceToken`

`impl<K> Equivalent for ResourceToken`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Hash for ResourceToken`

fn hash<__H: hash::Hasher>(&self, state: &mut __H)

`impl Instrument for ResourceToken`

`impl LayoutRaw for ResourceToken`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceToken`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for ResourceToken`

fn eq(&self, other: &ResourceToken) -> bool

Related: ResourceToken

`impl Pointable for ResourceToken`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceToken`

```
type Metadata = ()
```

`impl Read for ResourceToken`

`impl StructuralPartialEq for ResourceToken`

`impl WithSubscriber for ResourceToken`

`NativeTextureUpload`

struct NativeTextureUpload {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:189-192

The NativeTextureUpload struct retains a persisted GPU source and decoded mip ranges.

Open Self::path with Self::compression, then pass the resulting file handle to Self::requests. Retain the renderer's native ticket until it reports completion before publishing the destination image.

Implementations

```
fn path(&self) -> &std::path::Path
```
Returns the persisted file consumed by the native storage queue.
```
fn compression(&self) -> Result<ghi::io::ResourceIoCompression, TexturePreparationError>
```
Related: TexturePreparationError

Returns the native decompression method declared by resource storage.

fn requests(&self, metadata: TextureMetadata, file: ghi::io::ResourceIoFileHandle, image: ghi::BaseImageHandle) -> Result<SmallVec<[ghi::io::ResourceIoRequest; 16]>, TexturePreparationError>

Builds one native request per persisted mip for a renderer-selected image.

Trait Implementations

`impl ArchivePointee for NativeTextureUpload`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for NativeTextureUpload`

`impl Downcast for NativeTextureUpload`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for NativeTextureUpload`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for NativeTextureUpload`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for NativeTextureUpload`

`impl LayoutRaw for NativeTextureUpload`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for NativeTextureUpload`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for NativeTextureUpload`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for NativeTextureUpload`

```
type Metadata = ()
```

`impl Read for NativeTextureUpload`

`impl WithSubscriber for NativeTextureUpload`

`PreparedTextureTransfer`

struct PreparedTextureTransfer {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:79-82

The PreparedTextureTransfer struct pairs validated texture metadata with one delivery path.

The value remains storage-independent. Use Self::into_parts after your preparer builds renderer-specific detached objects, then carry both parts to render-thread adoption.

Implementations

```
async fn prepare(reference: Reference<ResourceImage>, staging: Arc<UploadStagingArena>) -> Result<Self, TexturePreparationError>
```
Related: UploadStagingArena, TexturePreparationError

Prepares all persisted mips without choosing a renderer destination.

CPU-readable resources receive one exclusive staging lease with rows

already padded for GHI copies. GPU-backed resources retain their native

file and stream metadata without decoding on the CPU. The caller supplies

logical identity when reporting TexturePreparationError.
```
fn metadata(&self) -> TextureMetadata
```
Related: TextureMetadata

Returns validated metadata without consuming the prepared source.
```
fn into_parts(self) -> (TextureMetadata, PreparedTextureSource)
```
Related: TextureMetadata, PreparedTextureSource

Splits preparation into the renderer-creation metadata and delivery source.

Trait Implementations

`impl ArchivePointee for PreparedTextureTransfer`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for PreparedTextureTransfer`

`impl Downcast for PreparedTextureTransfer`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for PreparedTextureTransfer`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for PreparedTextureTransfer`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for PreparedTextureTransfer`

`impl LayoutRaw for PreparedTextureTransfer`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for PreparedTextureTransfer`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for PreparedTextureTransfer`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for PreparedTextureTransfer`

```
type Metadata = ()
```

`impl Read for PreparedTextureTransfer`

`impl WithSubscriber for PreparedTextureTransfer`

`StagedTextureUpload`

struct StagedTextureUpload {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:156-159

The StagedTextureUpload struct retains row-padded mip bytes through GPU frame completion.

Move this value into a super::FrameUploadQueue. Its staging lease returns to the arena only when the queue drops it after the matching frame retires.

Implementations

```
fn copy_descriptors(&self, staging_buffer: ghi::BaseBufferHandle, image: ghi::BaseImageHandle) -> SmallVec<[ghi::BufferImageCopyDescriptor; 16]>
```
Builds every buffer-to-image copy for the renderer-selected destination.

The returned descriptors borrow no source state, but the caller must keep

this complete value alive until GPU completion so its lease remains valid.
```
fn is_empty(&self) -> bool
```
Returns whether preparation produced at least one validated mip copy.

Trait Implementations

`impl ArchivePointee for StagedTextureUpload`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for StagedTextureUpload`

`impl Downcast for StagedTextureUpload`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for StagedTextureUpload`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for StagedTextureUpload`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for StagedTextureUpload`

`impl LayoutRaw for StagedTextureUpload`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for StagedTextureUpload`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for StagedTextureUpload`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for StagedTextureUpload`

```
type Metadata = ()
```

`impl Read for StagedTextureUpload`

`impl WithSubscriber for StagedTextureUpload`

`TextureMetadata`

struct TextureMetadata {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:51-55

The TextureMetadata struct describes the GPU-independent shape of one baked 2D texture.

Use this metadata to create the renderer's destination image and sampler. Next, match the corresponding PreparedTextureSource to populate that destination through staging or native resource I/O.

Implementations

```
fn format(self) -> ghi::Formats
```
Returns the GHI format that preserves the baked resource encoding.
```
fn extent(self) -> Extent
```
Returns the validated two-dimensional image extent.
```
fn mip_count(self) -> u32
```
Returns the validated number of persisted mip levels.

Trait Implementations

`impl ArchivePointee for TextureMetadata`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for TextureMetadata`

`impl Clone for TextureMetadata`

```
fn clone(&self) -> TextureMetadata
```
Related: TextureMetadata

`impl Copy for TextureMetadata`

`impl Debug for TextureMetadata`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for TextureMetadata`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for TextureMetadata`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for TextureMetadata`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for TextureMetadata`

`impl<K> Equivalent for TextureMetadata`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Instrument for TextureMetadata`

`impl LayoutRaw for TextureMetadata`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for TextureMetadata`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for TextureMetadata`

fn eq(&self, other: &TextureMetadata) -> bool

Related: TextureMetadata

`impl Pointable for TextureMetadata`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for TextureMetadata`

```
type Metadata = ()
```

`impl Read for TextureMetadata`

`impl StructuralPartialEq for TextureMetadata`

`impl WithSubscriber for TextureMetadata`

`FrameUploadQueue<U, Resident>`

struct FrameUploadQueue<U, Resident> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/upload_queue.rs:44-47

The FrameUploadQueue struct connects prepared values to renderer storage without shortening GPU lifetimes.

The forward path is Self::enqueue then Self::record_frame. The return path is Self::retire_frame then renderer publication. Keep this queue on the render thread beside its ResourceLoader and ResourceUploadStore. It deliberately knows neither the upload layout nor the resident representation.

Implementations

```
fn enqueue(&mut self, token: ResourceToken, upload: U)
```
Related: ResourceToken

Queues one prepared value for the next transfer recording.

Enqueue only successful current completions from

ResourceLoader::take_completion. The resource remains loading until

Self::record_frame claims the token.
```
fn has_pending(&self) -> bool
```
Returns whether at least one current or stale upload is waiting to be examined.

A pipeline manager can return this from

crate::rendering::PipelineManager::begin_frame to request an upload

command recording. Stale work is filtered during recording.
```
fn record_frame<R, S>(&mut self, frame: ghi::FrameKey, recording: &mut ghi::implementation::CommandBufferRecording<'_>, loader: &mut ResourceLoader<R>, store: &mut S) -> Vec<(ResourceToken, <S as >::Error)>
```
Related: ResourceLoader, ResourceToken, ResourceUploadStore

Records every current upload and retains its source data until frame completes.

Call this from

crate::rendering::PipelineManager::record_frame_uploads with the same

frame key submitted for this command buffer. The queue claims each token

before invoking the store, drops stale revisions without touching storage,

and marks store errors failed. Report returned failures before retrying.
```
fn retire_frame<R: RenderResource>(&mut self, completed_frame: Option<ghi::FrameKey>, loader: &mut ResourceLoader<R>) -> Vec<(ResourceToken, Resident)>
```
Related: ResourceLoader, ResourceToken

Returns current residents and drops their upload values after the matching frame completes.

Call this early in crate::rendering::PipelineManager::begin_frame with

the renderer's completed frame key. Batches for other frame keys remain

retained. Dropping each upload returns any staging lease before the

resident is marked ready and returned for scene publication.

Trait Implementations

`impl ArchivePointee for FrameUploadQueue<U, Resident>`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for FrameUploadQueue<U, Resident>`

`impl<U, Resident> Default for FrameUploadQueue<U, Resident>`

```
fn default() -> Self
```

`impl Downcast for FrameUploadQueue<U, Resident>`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for FrameUploadQueue<U, Resident>`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for FrameUploadQueue<U, Resident>`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for FrameUploadQueue<U, Resident>`

`impl LayoutRaw for FrameUploadQueue<U, Resident>`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for FrameUploadQueue<U, Resident>`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for FrameUploadQueue<U, Resident>`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for FrameUploadQueue<U, Resident>`

```
type Metadata = ()
```

`impl Read for FrameUploadQueue<U, Resident>`

`impl<R> ReadPrimitive for FrameUploadQueue<U, Resident>`

`impl WithSubscriber for FrameUploadQueue<U, Resident>`

`StagingLease`

struct StagingLease {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/upload_staging.rs:222-225

The StagingLease struct ties exclusive mapped bytes to their GPU-use lifetime.

Fill the region through Self::bytes_mut, use Self::offset when recording a copy from the arena's backing buffer, and move the lease into the prepared upload. Do not free it manually. Dropping the lease returns the region to the worker, so the frame upload queue should own it until the exact transfer frame completes.

Implementations

```
fn offset(&self) -> usize
```
Returns the lease's absolute byte offset in the GPU upload buffer.

Add renderer-specific subrange offsets to this value when building copy

descriptors.
```
fn bytes_mut(&mut self) -> &mut [u8]
```
Returns exclusive CPU access to the persistently mapped region.

Finish all writes before handing the lease to the render thread. The

exclusive borrow prevents concurrent safe access through this lease.

Trait Implementations

`impl ArchivePointee for StagingLease`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for StagingLease`

`impl Downcast for StagingLease`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for StagingLease`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for StagingLease`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Drop for StagingLease`

```
fn drop(&mut self)
```

`impl Instrument for StagingLease`

`impl LayoutRaw for StagingLease`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for StagingLease`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for StagingLease`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for StagingLease`

```
type Metadata = ()
```

`impl Read for StagingLease`

`impl WithSubscriber for StagingLease`

`UploadStagingArena`

struct UploadStagingArena {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/upload_staging.rs:14-18

The UploadStagingArena struct gives preparers exclusive regions of one persistently mapped transfer buffer.

Share this lightweight client with asynchronous preparers. Request a StagingLease with Self::allocate, load or convert directly into its bytes, and move the lease inside the prepared upload. The reverse path is automatic: when the frame upload queue drops the lease after GPU completion, its region returns to UploadStagingWorker for coalescing and reuse.

The arena owns raw access transferred from one GHI mapping, not the backing buffer or context. Keep the GHI context and mapped buffer alive until the arena, its worker, and every lease have been dropped.

Implementations

```
fn new(mapping: ghi::buffer::Mapping) -> (Arc<Self>, UploadStagingWorker)
```
Related: UploadStagingWorker

Creates the client and worker halves for one transferred GHI buffer mapping.

The mapping must cover the upload buffer used as the source in the

renderer's super::ResourceUploadStore. Next, run

UploadStagingWorker::run on an application-owned task and retain the

mapped buffer handle in the renderer that records copies.
```
async fn allocate(self: &Arc<Self>, byte_count: usize, alignment: usize) -> Option<StagingLease>
```
Related: StagingLease

Waits for one aligned exclusive region or rejects a request larger than the complete arena.

Allocation requests are served in FIFO order. A large request at the head

can therefore hold smaller requests until returned regions coalesce; this

favors predictable ordering over opportunistic reordering. alignment

must be a non-zero power of two. None means the complete arena is too

small or its worker has stopped.

Trait Implementations

`impl ArchivePointee for UploadStagingArena`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for UploadStagingArena`

`impl Downcast for UploadStagingArena`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for UploadStagingArena`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for UploadStagingArena`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for UploadStagingArena`

`impl LayoutRaw for UploadStagingArena`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for UploadStagingArena`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for UploadStagingArena`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for UploadStagingArena`

```
type Metadata = ()
```

`impl Read for UploadStagingArena`

`impl WithSubscriber for UploadStagingArena`

`UploadStagingWorker`

struct UploadStagingWorker {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/rendering/resource_loading/upload_staging.rs:27-31

The UploadStagingWorker struct serializes allocation and reclamation for one mapped staging arena.

Run one worker per UploadStagingArena on an application-owned async task. Keeping free-region state here lets preparers share the arena without placing synchronization inside GHI or exposing mapped pointers across the public allocation API. The worker exits after every arena client and lease return channel has been dropped.

Implementations

```
async fn run(self)
```
Serves allocation and return messages until every staging client is dropped.

Move this future to the same application-owned runtime as resource loading

servers. Do not run two workers for one arena because this value is the

exclusive owner of free-region state.

Trait Implementations

`impl ArchivePointee for UploadStagingWorker`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for UploadStagingWorker`

`impl Downcast for UploadStagingWorker`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for UploadStagingWorker`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for UploadStagingWorker`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for UploadStagingWorker`

`impl LayoutRaw for UploadStagingWorker`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for UploadStagingWorker`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for UploadStagingWorker`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for UploadStagingWorker`

```
type Metadata = ()
```

`impl Read for UploadStagingWorker`

`impl WithSubscriber for UploadStagingWorker`

Enums

`ResourceState`

enum ResourceState {
    Queued,
    Loading,
    Uploading,
    Ready,
    Failed,
    Cancelled,
}

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:99-112

The ResourceState enum defines which subsystem owns one current resource revision.

The render-thread client owns Self::Queued, a server lane owns Self::Loading, and renderer storage or native GPU I/O owns Self::Uploading. Self::Ready, Self::Failed, and Self::Cancelled are terminal until ResourceLoader::retry creates a new revision.

Variants

Queued

The request is waiting for bounded client submission capacity.
Loading

A server lane owns or is waiting to receive the preparation work.
Uploading

Renderer storage or native GPU I/O owns the prepared work.
Ready

The renderer has published the resident resource.
Failed

Preparation, storage adoption, or GPU I/O failed.
Cancelled

Preparation was invalidated before renderer storage claimed it.

Trait Implementations

`impl ArchivePointee for ResourceState`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for ResourceState`

`impl Clone for ResourceState`

```
fn clone(&self) -> ResourceState
```
Related: ResourceState

`impl Copy for ResourceState`

`impl Debug for ResourceState`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Downcast for ResourceState`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for ResourceState`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for ResourceState`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for ResourceState`

`impl<K> Equivalent for ResourceState`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Instrument for ResourceState`

`impl LayoutRaw for ResourceState`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for ResourceState`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for ResourceState`

fn eq(&self, other: &ResourceState) -> bool

Related: ResourceState

`impl Pointable for ResourceState`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for ResourceState`

```
type Metadata = ()
```

`impl Read for ResourceState`

`impl StructuralPartialEq for ResourceState`

`impl WithSubscriber for ResourceState`

`PreparedTextureSource`

enum PreparedTextureSource {
    Staged(StagedTextureUpload),
    Native(NativeTextureUpload),
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:145-150

The PreparedTextureSource enum selects CPU staging or native GPU resource I/O.

Match this only after the render thread interns the renderer's destination objects. The selected variant then follows its own completion mechanism before the loader token becomes ready.

Variants

Staged

CPU-readable bytes arranged for transfer command recording.
Native

Persisted GPU backing arranged for native resource-I/O submission.

Trait Implementations

`impl ArchivePointee for PreparedTextureSource`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for PreparedTextureSource`

`impl Downcast for PreparedTextureSource`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for PreparedTextureSource`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for PreparedTextureSource`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Instrument for PreparedTextureSource`

`impl LayoutRaw for PreparedTextureSource`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for PreparedTextureSource`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl Pointable for PreparedTextureSource`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for PreparedTextureSource`

```
type Metadata = ()
```

`impl Read for PreparedTextureSource`

`impl WithSubscriber for PreparedTextureSource`

`TexturePreparationError`

enum TexturePreparationError {
    Dimensions,
    MipCount,
    Layout,
    StagingCapacity,
    Streams,
    Payload,
    NativeBacking,
    NativeEncoding,
}

Defined in crates/byte-engine/src/rendering/resource_loading/texture.rs:317-334

Errors produced while validating or preparing baked texture transfer data.

Variants

Dimensions

The resource is zero-sized or is not a 2D image.
MipCount

The declared mip count exceeds the image dimensions.
Layout

Size arithmetic or staging placement overflowed.
StagingCapacity

The complete padded mip chain does not fit the supplied staging arena.
Streams

Named mip stream metadata is missing or inconsistent.
Payload

CPU-readable payload bytes could not be decoded or read.
NativeBacking

GPU-backed storage did not return its persisted native source.
NativeEncoding

Native backing declared a CPU-only resource encoding.

Trait Implementations

`impl ArchivePointee for TexturePreparationError`

```
type ArchivedMetadata = ()
```

fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata

`impl<ST> CastableFrom for TexturePreparationError`

`impl Clone for TexturePreparationError`

fn clone(&self) -> TexturePreparationError

Related: TexturePreparationError

`impl Copy for TexturePreparationError`

`impl Debug for TexturePreparationError`

fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

`impl Display for TexturePreparationError`

fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result

`impl Downcast for TexturePreparationError`

fn into_any(self: Box<T>) -> Box<dyn Any>

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

```
fn as_any(&self) -> &dyn Any
```

fn as_any_mut(&mut self) -> &mut dyn Any

`impl DowncastSend for TexturePreparationError`

fn into_any_send(self: Box<T>) -> Box<dyn Any + Send>

`impl DowncastSync for TexturePreparationError`

fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Sync + Send>

`impl Eq for TexturePreparationError`

`impl<K> Equivalent for TexturePreparationError`

```
fn equivalent(&self, key: &K) -> bool
```

`impl Error for TexturePreparationError`

`impl Instrument for TexturePreparationError`

`impl LayoutRaw for TexturePreparationError`

fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>

`impl<T, N1> Niching for TexturePreparationError`

unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool

fn resolve_niched(out: Place<NichedOption<T, N1>>)

`impl PartialEq for TexturePreparationError`

fn eq(&self, other: &TexturePreparationError) -> bool

Related: TexturePreparationError

`impl Pointable for TexturePreparationError`

```
const ALIGN: usize
```
```
type Init = T
```

unsafe fn init(init: <T as Pointable>::Init) -> usize

unsafe fn deref<'a>(ptr: usize) -> &'a T

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

```
unsafe fn drop(ptr: usize)
```

`impl Pointee for TexturePreparationError`

```
type Metadata = ()
```

`impl Read for TexturePreparationError`

`impl StructuralPartialEq for TexturePreparationError`

`impl ToString for TexturePreparationError`

```
fn to_string(&self) -> String
```

`impl WithSubscriber for TexturePreparationError`

Traits

`RenderResource`

trait RenderResource: 'static { ... }

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:18-36

The RenderResource trait defines one renderer's loading protocol without defining its storage policy.

Implement this once for a renderer or for one independently scheduled resource family. The associated values form two boundaries: Self::Key and Self::Request travel from the render thread to a preparer, while Self::Prepared and Self::Error travel back. After implementing this trait, implement ResourcePreparer for worker-side preparation and super::ResourceUploadStore when the result needs transfer recording.

Associated Types

```
type Key: 5
```
```
type Request: 3
```
```
type Prepared: 2
```
```
type Error: 2
```

`ResourcePreparer<R: RenderResource>`

trait ResourcePreparer<R: RenderResource> { ... }

Defined in crates/byte-engine/src/rendering/resource_loading/loader.rs:480-486

The ResourcePreparer trait defines worker-side I/O and conversion for one renderer protocol.

A preparer owns lane-local services such as a resource-manager handle, staging arena, decoder, or detached GHI factory. It must not borrow or mutate the renderer's resident storage. Return enough metadata for the render thread to make placement decisions through super::ResourceUploadStore.

Required Methods

fn prepare(&mut self, request: <R as >::Request) -> impl Future<Output = Result<<R as >::Prepared, <R as >::Error>> + '_

Resolves and converts one request without accessing renderer-thread storage.

`ResourceUploadStore`

trait ResourceUploadStore { ... }

Defined in crates/byte-engine/src/rendering/resource_loading/upload_queue.rs:17-35

The ResourceUploadStore trait keeps GPU placement and resident identity under renderer control.

Implement this beside the renderer's buffers, images, allocation tables, and bindless slots. FrameUploadQueue::record_frame calls Self::record only after it has claimed the resource revision as uploading. Validate every capacity needed by one upload before recording commands or committing allocation metadata: an error cannot roll back commands already recorded.

The shared queue owns Self::Upload until the submitted frame completes, so staging leases and detached upload metadata remain alive for the complete GPU-use interval. After recording, it returns each Self::Resident with its token; publish that value into scene-visible maps only then.

Associated Types

```
type Upload
```
```
type Resident
```
```
type Error
```

Required Methods

fn record(&mut self, recording: &mut ghi::implementation::CommandBufferRecording<'_>, upload: &<Self as >::Upload) -> Result<<Self as >::Resident, <Self as >::Error>

Records one upload and reserves the renderer-owned value published after GPU completion.