Meshes, retained scenes, and USD¶
A mesh contains reusable GPU geometry and its layouts. Retained scene
objects provide transforms, material handles, and mobility around that
geometry. Create objects through RenderScene::CreateStaticMeshObject,
modify them through scene setters, and retire them through the same scene.
The scene also accepts transient mesh/render packets for callers that manage
their own frame-local submission.
Retained and transient work¶
Use ERenderMobility to describe which properties can change. Static
enables cache reuse for unchanged data. Stationary keeps spatial identity
while allowing updates the relevant descriptor setter permits. Dynamic can
invalidate spatial work. Creating or modifying a live object is distinct
from preparing the mesh, material variants, and instance capacity needed
by a profile that will draw it.
Keep the runtime, scene, material and mesh handles from a single ownership
domain. Frame submission should consume its prepared layout, material
variant, and logical instance storage. Check for PreparationRequired
after authoring changes that add new combinations.
Publish a USD scene¶
The optional OpenUSD adapter produces import data. The optional OpenUSDScene bridge cooks and publishes supported geometry, scene objects, and material bindings into the ordinary runtime. Use explicit import and publication errors when validating a stage. USD Preview Surface and MaterialX/OpenPBR are distinct authoring inputs. A conversion or fallback has its own coverage and can lose features that the original shading network used.
The USD schema describes the subdivision scheme and surface rules. It does not define a standard subdivision iteration count. In the geometry cooker:
Off uses the source polygon cage.
Auto uses a supported authored numeric level when found. The median of multiple values is truncated, then used as the subdivision level. Projected refinement is used when no supported level is authored.
Manual uses an explicit level for eligible subdivision meshes.
The chosen uniform level is an operation count. It is not passed through the
adaptive error test again. See the public OpenUSDSubdivisionOptions
for configurable error and budget values.
Import a static scene with explicit policy¶
This excerpt accepts the caller’s scene publication policy and Core routes. The selected shading model, material import options, and image preparation must match the stage’s applicable materials.
#include <filesystem>
#include <utility>
#include <Renderer/OpenUSD/OpenUSDSceneImporter.h>
#include <Renderer/OpenUSDScene/OpenUSDScene.h>
namespace SnAPI::Renderer::Docs
{
Core::TTask<TResult<OpenUSDSceneBundle>> ImportStaticScene(
RendererRuntime& runtime, std::filesystem::path path,
OpenUSDSceneCreateInfo policy, PassResourcePreparationContext context)
{
// The caller supplies the selected shading model and image/provider policy.
auto source = co_await Import::OpenUSDSceneImporter::ImportDataAsync(
std::move(path), {}, context.Cancellation);
if (source.Failed())
{
co_return source.Error();
}
co_return co_await OpenUSDScene::CreateAsync(
runtime, std::move(source).Value(), std::move(policy), std::move(context));
}
}
The import result owns selected source data. The publication step consumes that data and returns a bundle of actual renderer objects. Check the result before selecting the scene. Retire a successful publication through the bridge’s Destroy API after its last use. The runtime and preparation routes must live through the joined task.