Development

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.

Draw while authored materials prepare

The OpenPBR raster startup package prepares the renderer-owned checker material and its terminal. The USD bridge can publish geometry against that prepared material and later promote authored bindings without creating a separate renderer. OpenPBRProfile::PrepareIntoAsync can add an authored terminal to the existing profile. Keep using ready bindings while pending content prepares. Texture, material, and native pipeline readiness are all part of a promotion. A startup recipe still needs to choose and prepare its profile and resources.

At the low level, PublishRasterMaterialsAsync accepts a group of candidate bindings, prepares its variants, runs the caller’s closed-frame commit, and reserves instance capacity. It does not choose how the importer groups materials. If capacity reservation fails after commit, prepare the current scene before retrying. This matters for viewers that want frequent small promotions.

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.