Resources, native content, and caching¶
Declare dimensions, formats, usage, and sampling explicitly. The runtime owns objects created through its canonical resource systems. Vulkan interop, when available, has a separate backend contract and lifetime. A public descriptor or logical graph reference carries no ownership of the backing GPU storage.
Use native cooked content¶
CookedTextureArtifact
describes texture uploads in the declared GPU format. Read the header/index
first and request a specific mip and layer through ReadMipAsync. The
reader checks the indexed range and limits. Choose the native storage format
for the target device or provide an available alternate cook. The artifact
keeps the sampled RGB basis separate from the storage format and its
transfer decode. Data maps can omit a color basis.
The artifact and upload contracts live in renderer modules. A consumer of these contracts can read the cooked payload without taking a dependency on the broader asset pipeline. Indexed reads let it schedule its own streaming and residency policy. Consult the declared artifact kind before interpreting a byte range. Mesh instance layouts, native pipeline data, textures, and shader binaries have separate payload contracts.
Prepare and retire resources¶
Async buffer and texture preparation uses the caller’s Core routes. Use the owned input form when the caller may change or free an upload before the operation starts. Keep the stream and required backing inputs alive through the async read or preparation join as applicable.
A successful CPU API result and a completed GPU use are separate events. Retain borrowed external resources and descriptors until GPU completion. Resize and replacement often create a second generation, which keeps the old resource alive until the work that referenced it has retired.
Understand cache layers¶
Generated modules, compiled program artifacts, pipeline descriptions, and opaque native pipeline cache data represent different work. A compatible program binary can avoid source compilation and still require creation of a native pipeline. Native cache data is constrained by backend, device, and driver compatibility. Cache misses are actionable preparation results on a ready-only or compiler-free configuration. See Materials and typed shader graphs.
Read one mip¶
This function excerpt accepts an open seekable stream and the expected cook key. It reads metadata and one verified subresource from layer zero. The caller can schedule this read independently and pass the ordinary upload record into its texture preparation workflow.
#include <Renderer/ResourceArtifacts/CookedTextureArtifact.h>
namespace SnAPI::Renderer::Docs
{
Core::TTask<TResult<TextureUploadData>> ReadOneMip(
Core::AnyIOStreamBackend& stream, Core::Sha256Digest expectedKey,
std::uint32_t mip, Core::CancellationToken cancel)
{
constexpr std::uint64_t payloadBudget = 128ull * 1024 * 1024;
// A join owns the exclusive stream cursor across both metadata and payload reads.
auto index = co_await CookedTextureArtifact::ReadIndexAsync(
stream, expectedKey, payloadBudget, cancel);
if (index.Failed())
{
co_return index.Error();
}
co_return co_await CookedTextureArtifact::ReadMipAsync(
stream, index.Value(), 0, mip, cancel);
}
}
Keep the stream alive through join and avoid other operations on the same cursor during the read. The limit is a payload bound for admitting the file. A failed key or index check is a cache miss or input error that can be handled according to the caller’s cook policy.