ernie-renderer 0.2.0.dev21__tar.gz → 0.2.0.dev22__tar.gz

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/CMakeLists.txt

@@ -15,7 +15,7 @@ project(
 )
 
 # Pre-release suffix such as .dev12, written by CI.
-set(ERNIE_VERSION_SUFFIX ".dev21" CACHE STRING "Pre-release suffix of Ernie's version")
+set(ERNIE_VERSION_SUFFIX ".dev22" CACHE STRING "Pre-release suffix of Ernie's version")
 set(ERNIE_VERSION "${PROJECT_VERSION}${ERNIE_VERSION_SUFFIX}")
 
 option(ERNIE_BUILD_TESTS "Build Ernie's tests" OFF)

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ernie-renderer
-Version: 0.2.0.dev21
+Version: 0.2.0.dev22
 Summary: Efficient Renderer for Natural and Interplanetary Environments: a physically based, spectral Vulkan ray tracer
 Author: Alex Maietta
 License-Expression: BSD-3-Clause

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/CMakeLists.txt

@@ -8,7 +8,9 @@ add_library(
     storage.cpp
     view.cpp
     xform.cpp
+    schemas/collection.cpp
     schemas/geom.cpp
     schemas/registry.cpp
+    schemas/shade.cpp
 )
 target_link_libraries(ernie_scene PUBLIC ernie_physics ernie_io PRIVATE ernie_build_options)

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/scene.cpp

@@ -7,6 +7,7 @@
 #include "ernie/scene/schemas/geom.h"
 #include "ernie/scene/tokens.h"
 #include "ernie/scene/xform.h"
+#include "ernie/util/algorithm.h"
 
 #include <algorithm>
 #include <stdexcept>
@@ -15,9 +16,9 @@
 namespace ernie {
 namespace {
 
-/// @return A column layout holding `fallback` in unauthored rows.
-ColumnLayout MakeLayout(PathTable& paths, const AttributeDef& def) {
-    const AttributeId attribute = paths.Names().Intern(def.name);
+/// @return A column layout for the attribute `name` holding `def`'s fallback in unauthored rows.
+ColumnLayout MakeLayout(PathTable& paths, const AttributeDef& def, std::string_view name) {
+    const AttributeId attribute = paths.Names().Intern(name);
     return WithColumnType(def.type, [&]<typename T>(std::type_identity<T>) {
         if constexpr (std::is_same_v<T, Tensor>) {
             return ColumnLayout::Of<T>(attribute);
@@ -38,7 +39,7 @@ std::string Describe(const Scene& scene, PrimId prim) {
 Scene::Scene()
     : invisible_(store_.Tokens().Intern(tokens::kInvisible)),
       defaultPurpose_(store_.Tokens().Intern(tokens::kDefault)) {
-    BucketFor(nullptr);
+    FindOrAddBucket(nullptr, {});
 }
 
 PrimId Scene::Define(const Path& path, std::string_view type) {
@@ -57,12 +58,11 @@ PrimId Scene::Define(const Path& path, std::string_view type) {
             store_.Define(above, 0);
         }
     }
-    const BucketId bucket = BucketFor(schema);
     if (const std::optional<PrimId> existing = store_.Find(id)) {
-        store_.Move(*existing, bucket);
+        MoveTo(*existing, schema, Apis(*existing));
         return *existing;
     }
-    return store_.Define(id, bucket);
+    return store_.Define(id, FindOrAddBucket(schema, {}));
 }
 
 bool Scene::Remove(const Path& path) {
@@ -138,7 +138,7 @@ void Scene::Set(PrimId prim, std::string_view attribute, const Value& value) {
     const AttributeId token = store_.Tokens().Intern(attribute);
     const AttributeDef* def = Declared(prim, token);
     if (def != nullptr) {
-        Validate(*def, value, PrimPath(prim));
+        Validate(*def, attribute, value, PrimPath(prim));
     }
     const ColumnType type = def != nullptr ? def->type : TypeForUndeclared(prim, attribute, value);
     WithColumnType(type, [&]<typename T>(std::type_identity<T>) {
@@ -258,26 +258,68 @@ PrimId Scene::Require(const Path& path) const {
     return *prim;
 }
 
-BucketId Scene::BucketFor(const SchemaDef* schema) {
-    if (const auto found = bucketBySchema_.find(schema); found != bucketBySchema_.end()) {
-        return found->second;
-    }
+BucketId Scene::FindOrAddBucket(const SchemaDef* schema, std::vector<Token> apis) {
     PathTable& paths = store_.Paths();
+    const BucketKey key{paths.Names().Intern(schema != nullptr ? schema->name : ""),
+                        std::move(apis)};
+    if (const std::optional<BucketId> found = store_.FindBucket(key)) {
+        return *found;
+    }
     BucketSchema entry{schema, {}};
     std::vector<ColumnLayout> layout;
-    for (const AttributeDef* def :
-         schema != nullptr ? schema->AllAttributes() : std::vector<const AttributeDef*>{}) {
-        layout.push_back(MakeLayout(paths, *def));
-        entry.declared.emplace(layout.back().attribute, def);
+    const auto add = [&](const SchemaDef& declaring, const ApiName& api) {
+        for (const AttributeDef* def : declaring.AllAttributes()) {
+            layout.push_back(MakeLayout(paths, *def, api.Attribute(def->name)));
+            entry.declared.emplace(layout.back().attribute, def);
+        }
+    };
+    if (schema != nullptr) {
+        add(*schema, {});
+    }
+    for (const Token token : key.apiSchemas) {
+        const ApiName api = ApiName::Parse(paths.Names().Text(token));
+        add(*api.schema, api);
     }
-    const Token type = paths.Names().Intern(schema != nullptr ? schema->name : "");
-    const BucketId bucket = store_.AddBucket({type, {}}, layout);
+    const BucketId bucket = store_.AddBucket(key, layout);
     buckets_.resize(std::max<std::size_t>(buckets_.size(), bucket + 1));
     buckets_[bucket] = std::move(entry);
-    bucketBySchema_.emplace(schema, bucket);
     return bucket;
 }
 
+void Scene::MoveTo(PrimId prim, const SchemaDef* schema, std::vector<Token> apis) {
+    store_.Move(prim, FindOrAddBucket(schema, std::move(apis)));
+}
+
+const std::vector<Token>& Scene::Apis(PrimId prim) const {
+    return store_.GetBucket(store_.PrimBucket(prim)).key.apiSchemas;
+}
+
+void Scene::ApplyApi(PrimId prim, std::string_view api) {
+    ApiName::Parse(api);
+    std::vector<Token> apis = Apis(prim);
+    apis.push_back(store_.Tokens().Intern(api));
+    MoveTo(prim, Schema(prim), std::move(apis));
+}
+
+bool Scene::RemoveApi(PrimId prim, std::string_view api) {
+    if (!HasApi(prim, api)) {
+        return false;
+    }
+    std::vector<Token> apis = Apis(prim);
+    std::erase(apis, *store_.Tokens().Find(api));
+    MoveTo(prim, Schema(prim), std::move(apis));
+    return true;
+}
+
+bool Scene::HasApi(PrimId prim, std::string_view api) const {
+    const std::optional<Token> token = store_.Tokens().Find(api);
+    return token && std::ranges::find(Apis(prim), *token) != Apis(prim).end();
+}
+
+std::vector<std::string> Scene::AppliedApis(PrimId prim) const {
+    return Map(Apis(prim), [&](Token token) { return std::string(store_.Tokens().Text(token)); });
+}
+
 bool Scene::LeavesOutOfBounds(PrimId prim) const {
     const auto token = [&](std::string_view attribute) -> std::optional<Token> {
         const Column* column = AuthoredColumn(prim, attribute);
@@ -302,10 +344,17 @@ const AttributeDef* Scene::Declared(PrimId prim, AttributeId attribute) const {
     return found != declared.end() ? found->second : nullptr;
 }
 
+bool Scene::TakesUndeclared(PrimId prim, std::string_view attribute) const {
+    const SchemaDef* schema = Schema(prim);
+    return schema == nullptr || schema->IsOpen(attribute) ||
+           std::ranges::any_of(Apis(prim), [&](Token api) {
+               return ApiName::Parse(store_.Tokens().Text(api)).schema->IsOpen(attribute);
+           });
+}
+
 ColumnType Scene::TypeForUndeclared(PrimId prim, std::string_view attribute,
                                     const Value& value) const {
-    const SchemaDef* schema = Schema(prim);
-    if (schema != nullptr && !schema->IsOpen(attribute)) {
+    if (!TakesUndeclared(prim, attribute)) {
         throw std::invalid_argument(Describe(*this, prim) + " has no attribute '" +
                                     std::string(attribute) + "'");
     }

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/scene.h

@@ -47,6 +47,17 @@ class Scene {
     /// @return Every prim whose type is `type` or derives from it; every prim for `""`.
     std::vector<Path> Prims(std::string_view type = {}) const;
 
+    /// @brief Applies an API schema, `"MaterialBindingAPI"`, or an instance of a multiple-apply
+    /// one, `"CollectionAPI:lights"`, adding its attributes at their fallbacks.
+    /// @throws std::invalid_argument for an unknown API schema or a missing or extra instance.
+    void ApplyApi(PrimId prim, std::string_view api);
+    /// @brief Removes an applied API schema with the values of its attributes.
+    /// @return Whether it was applied.
+    bool RemoveApi(PrimId prim, std::string_view api);
+    bool HasApi(PrimId prim, std::string_view api) const;
+    /// @return The applied API schemas, as `ApplyApi` names them.
+    std::vector<std::string> AppliedApis(PrimId prim) const;
+
     /// @brief Authors an attribute: a declared one converted to its type and checked, or an
     /// undeclared one, typed by its first value, in a namespace the type leaves open or on a prim
     /// without a type.
@@ -86,10 +97,17 @@ class Scene {
         std::unordered_map<AttributeId, const AttributeDef*> declared;
     };
 
-    BucketId BucketFor(const SchemaDef* schema);
+    /// @return The bucket of a type and applied API schemas, made if new.
+    BucketId FindOrAddBucket(const SchemaDef* schema, std::vector<Token> apis);
+    /// Moves a prim to the bucket of its type and `apis`.
+    void MoveTo(PrimId prim, const SchemaDef* schema, std::vector<Token> apis);
+    const std::vector<Token>& Apis(PrimId prim) const;
     /// @return The attribute's column when the prim authors it, or null.
     const Column* AuthoredColumn(PrimId prim, std::string_view attribute) const;
     const AttributeDef* Declared(PrimId prim, AttributeId attribute) const;
+    /// @return Whether the prim's type or an applied API schema leaves the attribute's namespace
+    /// open; any attribute for a prim without a type.
+    bool TakesUndeclared(PrimId prim, std::string_view attribute) const;
     ColumnType TypeForUndeclared(PrimId prim, std::string_view attribute, const Value& value) const;
     /// @return Whether the prim and its subtree are invisible or of a purpose bounds leave out.
     bool LeavesOutOfBounds(PrimId prim) const;
@@ -100,7 +118,6 @@ class Scene {
     Token invisible_ = 0;
     Token defaultPurpose_ = 0;
     std::vector<BucketSchema> buckets_;
-    std::unordered_map<const SchemaDef*, BucketId> bucketBySchema_;
 };
 
 }  // namespace ernie

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/schema.cpp

@@ -114,9 +114,39 @@ const SchemaDef* FindSchema(std::string_view name) {
     return found != schemas.end() ? *found : nullptr;
 }
 
-void Validate(const AttributeDef& def, const Value& value, const Path& path) {
+ApiName ApiName::Parse(std::string_view api) {
+    const std::size_t colon = api.find(':');
+    const std::string_view name = api.substr(0, colon);
+    const ApiName parsed{FindSchema(name), colon == std::string_view::npos ? std::string_view()
+                                                                           : api.substr(colon + 1)};
+    const bool single = parsed.schema != nullptr && parsed.schema->kind == SchemaKind::SingleApply;
+    const bool multiple =
+        parsed.schema != nullptr && parsed.schema->kind == SchemaKind::MultipleApply;
+    if (!(single && parsed.instance.empty()) && !(multiple && IsIdentifier(parsed.instance))) {
+        throw std::invalid_argument(
+            "'" + std::string(api) + "' is no API schema" +
+            (multiple ? ": a multiple-apply one takes an instance name, as CollectionAPI:lights"
+                      : ""));
+    }
+    return parsed;
+}
+
+std::string ApiName::Attribute(std::string_view declared) const {
+    std::string name(declared);
+    if (const std::size_t at = name.find(kInstanceName); at != std::string::npos) {
+        name.replace(at, kInstanceName.size(), instance);
+    }
+    return name;
+}
+
+std::string ApiName::ToString() const {
+    return std::string(schema->name) + (instance.empty() ? "" : ":" + std::string(instance));
+}
+
+void Validate(const AttributeDef& def, std::string_view attribute, const Value& value,
+              const Path& path) {
     if (const std::string problem = Problem(def, value); !problem.empty()) {
-        throw std::invalid_argument("'" + path.String() + "': '" + std::string(def.name) + "' " +
+        throw std::invalid_argument("'" + path.String() + "': '" + std::string(attribute) + "' " +
                                     problem);
     }
 }

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/schema.h

@@ -168,10 +168,28 @@ std::span<const SchemaDef* const> Schemas();
 /// @return The schema named `name`, or null.
 const SchemaDef* FindSchema(std::string_view name);
 
+/// What a multiple-apply schema's attribute names hold in place of the instance's name.
+inline constexpr std::string_view kInstanceName = "__INSTANCE_NAME__";
+
+/// @brief An applied API schema: `"MaterialBindingAPI"`, or `"CollectionAPI:lights"`.
+struct ApiName {
+    const SchemaDef* schema = nullptr;
+    std::string_view instance;
+
+    /// @throws std::invalid_argument for an unknown API schema or a missing or extra instance.
+    static ApiName Parse(std::string_view api);
+    /// @return A declared name with the instance's name in place of `kInstanceName`.
+    std::string Attribute(std::string_view declared) const;
+    /// @return The name `Parse` reads.
+    std::string ToString() const;
+};
+
 /// @brief Checks a value against a declared attribute's limits and options; the scene checks its
 /// type as it converts it.
+/// @param attribute The attribute's name, an instance's for a multiple-apply schema's.
 /// @throws std::invalid_argument naming the prim, the attribute and the reason.
-void Validate(const AttributeDef& def, const Value& value, const Path& path);
+void Validate(const AttributeDef& def, std::string_view attribute, const Value& value,
+              const Path& path);
 
 /// @brief The tokens of an enum a token attribute takes, in enumerator order.
 template <typename E> struct ChoiceTokens;

ernie_renderer-0.2.0.dev22/ernie/scene/schemas/collection.cpp

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file collection.cpp
+/// @brief CollectionAPI's registry entry.
+#include "ernie/scene/schemas/collection.h"
+
+namespace ernie {
+
+ERNIE_DEFINE_SCHEMA(CollectionAPI, "CollectionAPI", nullptr, MultipleApply, kInheritExtent,
+                    "A named set of prims.", ERNIE_COLLECTION_API_ATTRIBUTES)
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev22/ernie/scene/schemas/collection.h

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file collection.h
+/// @brief Usd's CollectionAPI: named sets of prims, applied once per collection.
+///
+/// References:
+/// - Pixar, UsdCollectionAPI, https://openusd.org/release/api/class_usd_collection_a_p_i.html
+#pragma once
+
+#include "ernie/scene/view.h"
+
+#include <array>
+#include <string_view>
+#include <vector>
+
+// clang-format off
+#define ERNIE_COLLECTION_API_ATTRIBUTES(X)                                                         \
+    X(Choice<ExpansionRule>, ExpansionRule, "collection:__INSTANCE_NAME__:expansionRule",          \
+      ExpansionRule::ExpandPrims,                                                                  \
+      "explicitOnly: the targets alone; expandPrims: their descendants too; "                      \
+      "expandPrimsAndProperties: and their properties.",                                           \
+      .group = "Collection")                                                                       \
+    X(bool, IncludeRoot, "collection:__INSTANCE_NAME__:includeRoot", false,                        \
+      "Whether the root prim is a member.", .group = "Collection")                                 \
+    X(std::vector<Path>, Includes, "collection:__INSTANCE_NAME__:includes", std::vector<Path>{},  \
+      "The prims, with their descendants per the rule, in the collection.", .group = "Collection") \
+    X(std::vector<Path>, Excludes, "collection:__INSTANCE_NAME__:excludes", std::vector<Path>{},  \
+      "The prims, with their descendants, left out.", .group = "Collection")
+// clang-format on
+
+namespace ernie {
+
+enum class ExpansionRule { ExplicitOnly, ExpandPrims, ExpandPrimsAndProperties };
+
+template <> struct ChoiceTokens<ExpansionRule> {
+    static constexpr std::array<std::string_view, 3> kTokens{"explicitOnly", "expandPrims",
+                                                             "expandPrimsAndProperties"};
+};
+
+ERNIE_SCHEMA_ACCESSORS(CollectionAPI, SchemaView, ERNIE_COLLECTION_API_ATTRIBUTES);
+
+/// A named set of prims, as light linking and material collections use them.
+class CollectionAPI : public CollectionAPIAccessors<CollectionAPI, SchemaView> {
+    ERNIE_API_SCHEMA_BODY(CollectionAPI)
+};
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev22/ernie/scene/schemas/registry.cpp

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file registry.cpp
+/// @brief The list of every registered schema.
+#include "ernie/scene/schemas/collection.h"
+#include "ernie/scene/schemas/geom.h"
+#include "ernie/scene/schemas/shade.h"
+
+namespace ernie {
+
+std::span<const SchemaDef* const> Schemas() {
+    static const std::array kSchemas{
+        &Imageable::Definition(),     &Xformable::Definition(),
+        &Boundable::Definition(),     &Gprim::Definition(),
+        &Xform::Definition(),         &Scope::Definition(),
+        &Cube::Definition(),          &Sphere::Definition(),
+        &Cylinder::Definition(),      &Cone::Definition(),
+        &Capsule::Definition(),       &Plane::Definition(),
+        &CollectionAPI::Definition(), &MaterialBindingAPI::Definition(),
+    };
+    return kSchemas;
+}
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev22/ernie/scene/schemas/shade.cpp

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file shade.cpp
+/// @brief UsdShade's registry entries.
+#include "ernie/scene/schemas/shade.h"
+
+namespace ernie {
+
+ERNIE_DEFINE_SCHEMA(MaterialBindingAPI, "MaterialBindingAPI", nullptr, SingleApply, kInheritExtent,
+                    "Binds a material to a prim and its descendants.",
+                    ERNIE_MATERIAL_BINDING_API_ATTRIBUTES, "material:binding:")
+
+}  // namespace ernie

ernie_renderer-0.2.0.dev22/ernie/scene/schemas/shade.h

@@ -0,0 +1,27 @@
+// SPDX-License-Identifier: BSD-3-Clause
+/// @file shade.h
+/// @brief UsdShade's schemas.
+///
+/// References:
+/// - Pixar, UsdShade, https://openusd.org/release/api/usd_shade_page_front.html
+#pragma once
+
+#include "ernie/scene/view.h"
+
+// clang-format off
+#define ERNIE_MATERIAL_BINDING_API_ATTRIBUTES(X)                                                   \
+    X(Path, MaterialBinding, "material:binding", Path(),                                           \
+      "The Material the prim and its descendants are drawn with.", .label = "Material",            \
+      .group = "Material", .dirty = Dirty::Material)
+// clang-format on
+
+namespace ernie {
+
+ERNIE_SCHEMA_ACCESSORS(MaterialBindingAPI, SchemaView, ERNIE_MATERIAL_BINDING_API_ATTRIBUTES);
+
+/// Binds a material to a prim; `material:binding:<purpose>` binds one for a purpose.
+class MaterialBindingAPI : public MaterialBindingAPIAccessors<MaterialBindingAPI, SchemaView> {
+    ERNIE_API_SCHEMA_BODY(MaterialBindingAPI)
+};
+
+}  // namespace ernie

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/storage.cpp

@@ -25,11 +25,21 @@ std::size_t PrimStore::KeyHash::operator()(const BucketKey& key) const {
     return static_cast<std::size_t>(hash);
 }
 
+BucketKey BucketKey::Normalized() const {
+    BucketKey sorted = *this;
+    std::ranges::sort(sorted.apiSchemas);
+    const auto [last, end] = std::ranges::unique(sorted.apiSchemas);
+    sorted.apiSchemas.erase(last, end);
+    return sorted;
+}
+
+std::optional<BucketId> PrimStore::FindBucket(const BucketKey& key) const {
+    const auto found = bucketIndex_.find(key.Normalized());
+    return found != bucketIndex_.end() ? std::optional(found->second) : std::nullopt;
+}
+
 BucketId PrimStore::AddBucket(const BucketKey& key, std::span<const ColumnLayout> layout) {
-    BucketKey sorted = key;
-    std::sort(sorted.apiSchemas.begin(), sorted.apiSchemas.end());
-    sorted.apiSchemas.erase(std::unique(sorted.apiSchemas.begin(), sorted.apiSchemas.end()),
-                            sorted.apiSchemas.end());
+    BucketKey sorted = key.Normalized();
     if (const auto found = bucketIndex_.find(sorted); found != bucketIndex_.end()) {
         return found->second;
     }

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/storage.h

@@ -194,6 +194,8 @@ struct BucketKey {
     Token type = 0;
     std::vector<Token> apiSchemas;
 
+    /// @return The key with its API schemas sorted and without repeats.
+    BucketKey Normalized() const;
     bool operator==(const BucketKey&) const = default;
 };
 
@@ -308,6 +310,7 @@ class PrimStore {
 
     /// @return The bucket of `key`, made with `layout`'s columns if new.
     BucketId AddBucket(const BucketKey& key, std::span<const ColumnLayout> layout);
+    std::optional<BucketId> FindBucket(const BucketKey& key) const;
     const Bucket& GetBucket(BucketId bucket) const {
         return *buckets_[bucket];
     }

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/view.cpp

@@ -9,8 +9,20 @@
 namespace ernie {
 namespace {
 
-PrimId Check(const Scene& scene, const Path& path, const SchemaDef& schema) {
+bool IsApi(const SchemaDef& schema) {
+    return schema.kind == SchemaKind::SingleApply || schema.kind == SchemaKind::MultipleApply;
+}
+
+PrimId Check(const Scene& scene, const Path& path, const SchemaDef& schema,
+             std::string_view instance) {
     const PrimId prim = scene.Require(path);
+    if (IsApi(schema)) {
+        const std::string api = ApiName{&schema, instance}.ToString();
+        if (!scene.HasApi(prim, api)) {
+            throw std::invalid_argument("'" + path.String() + "' has no " + api + " applied");
+        }
+        return prim;
+    }
     const SchemaDef* type = scene.Schema(prim);
     if (type == nullptr || !type->IsA(schema)) {
         const std::string_view name = type != nullptr ? type->name : "a prim without a type";
@@ -22,11 +34,15 @@ PrimId Check(const Scene& scene, const Path& path, const SchemaDef& schema) {
 
 }  // namespace
 
-SchemaView::SchemaView(const Scene& scene, const Path& path, const SchemaDef& schema)
-    : scene_(&scene), prim_(Check(scene, path, schema)), schema_(&schema) {}
+SchemaView::SchemaView(const Scene& scene, const Path& path, const SchemaDef& schema,
+                       std::string_view instance)
+    : scene_(&scene), prim_(Check(scene, path, schema, instance)), schema_(&schema),
+      instance_(instance) {}
 
-SchemaView::SchemaView(Scene& scene, const Path& path, const SchemaDef& schema)
-    : scene_(&scene), mutable_(&scene), prim_(Check(scene, path, schema)), schema_(&schema) {}
+SchemaView::SchemaView(Scene& scene, const Path& path, const SchemaDef& schema,
+                       std::string_view instance)
+    : scene_(&scene), mutable_(&scene), prim_(Check(scene, path, schema, instance)),
+      schema_(&schema), instance_(instance) {}
 
 Scene& SchemaView::Edit() const {
     if (mutable_ == nullptr) {

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/ernie/scene/view.h

@@ -98,26 +98,50 @@ class SchemaView {
         return *schema_;
     }
 
+    /// The instance name of a multiple-apply API schema's view; empty otherwise.
+    std::string_view Instance() const {
+        return instance_;
+    }
+
   protected:
-    SchemaView(const Scene& scene, const Path& path, const SchemaDef& schema);
-    SchemaView(Scene& scene, const Path& path, const SchemaDef& schema);
+    /// @throws std::invalid_argument if the prim is missing, is not of `schema`'s type or lacks
+    /// the applied API schema.
+    SchemaView(const Scene& scene, const Path& path, const SchemaDef& schema,
+               std::string_view instance = {});
+    SchemaView(Scene& scene, const Path& path, const SchemaDef& schema,
+               std::string_view instance = {});
+
+    /// Calls `use` with a declared attribute's name, its instance's for a multiple-apply schema.
+    template <typename Use> decltype(auto) Named(std::string_view declared, const Use& use) const {
+        if (instance_.empty()) {
+            return use(declared);
+        }
+        const std::string name = ApiName{schema_, instance_}.Attribute(declared);
+        return use(std::string_view(name));
+    }
 
-    template <typename T> typename AttributeTraits<T>::Result Read(std::string_view name) const {
-        using Traits = AttributeTraits<T>;
-        const PrimStore& store = scene_->Store();
-        const Token token = *store.Paths().Names().Find(name);
-        const auto column = store.Read<typename Traits::Stored>(store.PrimBucket(prim_), token);
-        return Traits::Load(store.Paths(), column[store.PrimRow(prim_)]);
+    template <typename T>
+    typename AttributeTraits<T>::Result Read(std::string_view declared) const {
+        return Named(declared, [&](std::string_view name) {
+            using Traits = AttributeTraits<T>;
+            const PrimStore& store = scene_->Store();
+            const Token token = *store.Tokens().Find(name);
+            const auto column = store.Read<typename Traits::Stored>(store.PrimBucket(prim_), token);
+            return Traits::Load(store.Paths(), column[store.PrimRow(prim_)]);
+        });
     }
     template <typename T>
-    void Write(std::string_view name, const typename AttributeTraits<T>::Result& value) {
-        Edit().Set(prim_, name, AttributeTraits<T>::Save(value));
+    void Write(std::string_view declared, const typename AttributeTraits<T>::Result& value) {
+        Named(declared, [&](std::string_view name) {
+            Edit().Set(prim_, name, AttributeTraits<T>::Save(value));
+        });
     }
-    bool Has(std::string_view name) const {
-        return scene_->IsAuthored(prim_, name);
+    bool Has(std::string_view declared) const {
+        return Named(declared,
+                     [&](std::string_view name) { return scene_->IsAuthored(prim_, name); });
     }
-    void Unset(std::string_view name) {
-        Edit().Clear(prim_, name);
+    void Unset(std::string_view declared) {
+        Named(declared, [&](std::string_view name) { Edit().Clear(prim_, name); });
     }
     Scene& Edit() const;
 
@@ -126,6 +150,7 @@ class SchemaView {
     Scene* mutable_ = nullptr;
     PrimId prim_;
     const SchemaDef* schema_ = nullptr;
+    std::string instance_;
 };
 
 /// The root of every generated accessor chain.
@@ -197,6 +222,23 @@ template <typename Self, typename Base> class SchemaViewAccessors : public Base
         return Class(scene, path);                                                                 \
     }
 
+/// The constructors, `Apply` and registry entry of an API schema's view; a multiple-apply
+/// schema's take its instance name.
+#define ERNIE_API_SCHEMA_BODY(Class)                                                               \
+  public:                                                                                          \
+    using Self = Class;                                                                            \
+    /** @throws std::invalid_argument if the prim is missing or lacks the API schema. */           \
+    Class(const ::ernie::Scene& scene, const ::ernie::Path& path, std::string_view instance = {})  \
+        : Class##Accessors<Class, ::ernie::SchemaView>(scene, path, Definition(), instance) {}     \
+    Class(::ernie::Scene& scene, const ::ernie::Path& path, std::string_view instance = {})        \
+        : Class##Accessors<Class, ::ernie::SchemaView>(scene, path, Definition(), instance) {}     \
+    static const ::ernie::SchemaDef& Definition();                                                 \
+    static Class Apply(::ernie::Scene& scene, const ::ernie::Path& path,                           \
+                       std::string_view instance = {}) {                                           \
+        scene.ApplyApi(scene.Require(path), ::ernie::ApiName{&Definition(), instance}.ToString()); \
+        return Class(scene, path, instance);                                                       \
+    }
+
 /// Defines `Class::Definition()`, the schema's registry entry.
 #define ERNIE_DEFINE_SCHEMA(Class, name, base, kind, extentRule, text, OWN_ATTRIBUTES, ...)        \
     const ::ernie::SchemaDef& Class::Definition() {                                                \

{ernie_renderer-0.2.0.dev21 → ernie_renderer-0.2.0.dev22}/tests/CMakeLists.txt

@@ -55,6 +55,7 @@ ernie_add_test_suite(
 ernie_add_test_suite(
     scene
     SOURCES
+        scene/api_test.cpp
         scene/path_test.cpp
         scene/scene_test.cpp
         scene/schema_test.cpp