Skip to main content

Scene

Struct Scene 

Source
#[non_exhaustive]
pub struct Scene { /* private fields */ }
Expand description

The recorded scene graph.

Implementations§

Source§

impl Scene

Source

pub fn geometry_binding( &self, geometry: &str, ) -> Result<Option<Binding>, ResolveError>

Gather the attributes nodes gathered along a geometry’s path, and the surface shader they resolve to.

ɴsɪ routes material through an intermediate node – shader -> attributes -> geometry – that no target renderer has. Mitsuba wants a bsdf on the shape; MoonRay wants a Layer entry. Both need the same walk, so it happens here once.

§Gathering

ɴsɪ gathers attribute values “along the path starting from the geometric primitive, through all the transform nodes it is connected to, until the scene root is reached”, and every attributes node on that path is considered: “one attributes node can set object visibility and another can set the surface shader”. So this returns all of them, nearest the geometry first – ɴsɪ selects “the definition that is the closest to the geometric primitive” – and a backend takes the first that defines the attribute it wants.

That is not the whole rule. ɴsɪ ranks a definition by ATTR.priority, set on an attributes node beside the attribute it applies to; and at equal priority a more specific visibility.<ray> beats visibility. This method applies neither – it orders nodes, not the attributes on them. Ask Scene::attribute_value for one attribute’s value and both rules are applied.

Returns Ok(None) for geometry with nothing bound anywhere on its path.

§Errors

ResolveError::MultipleParents, ResolveError::Cycle or ResolveError::Detached, from walking the path. A motion-sampled transform does not affect which attributes bind, so it is not an error here.

Source

pub fn attribute_value( &self, geometry: &str, name: &str, ) -> Result<Option<AttributeValue<'_>>, ResolveError>

The value of one attribute, gathered along a geometry’s path by ɴsɪ’s full precedence rule.

Binding::attributes hands back the attributes nodes and lets a backend take the first that defines what it wants. That is right only while no node sets ATTR.priority and the attribute is not a visibility one. This applies both rules and returns the answer itself.

§Scope

This resolves attributes nodes reached through geometryattributes. ɴsɪ has a second container with a different rule: a shaderattributes node is gathered along the same path, but “priority is given to nodes attached closest to the geometric primitive, with the highest priority given to attributes set directly on the geometric primitive”, with no ATTR.priority in it at all. Ask Scene::shader_attribute_value for those; this one returns None for them.

§Precedence

ɴsɪ: “When an attribute is defined multiple times along this path, the definition with the highest priority is selected. In case of conflicting priorities, the definition that is the closest to the geometric primitive […] is selected.” A definition’s priority is the ATTR.priority int sitting beside it on the same attributes node, 0 when absent.

For a visibility.<ray> query the default visibility is a candidate too: “When visibility is set both per ray type and with this default visibility, the attribute with the highest priority is used. If their priority is the same, the more specific attribute (i.e. per ray type) is used.”

Candidates therefore rank by priority, then specificity, then the Binding::attributes order.

§Assumptions

Two orderings the specification does not settle. Both are recorded in contracts/resolution.md rather than left implicit:

  • Specificity is compared before proximity, so a distant visibility.camera beats a nearer plain visibility at equal priority. ɴsɪ gives the specificity rule without saying whether it outranks proximity. Confirmed against 3Delight.
  • A priority that is not an int is ignored, leaving 0. That includes int64, which 3Delight also ignores here.
§A priority with no attribute beside it

A node that sets ATTR.priority but not ATTR is a definition too – of ATTR at its ɴsɪ default – and it ranks on that priority like any other. Rendered: an attributes node carrying only visibility.priority makes the geometry visible over a farther visibility 0, at priority 10 and at 0 alike; and one two levels up at priority 10 beats a visibility 0 on the node attached to the primitive itself, so it is not merely winning on proximity. A node with no attributes at all is not a definition, and neither is one whose priority is an int64, which 3Delight cannot read.

§Reading the value is not OwnedArgument::as_i32

3Delight is far looser about an attribute’s value than about its priority. Rendered, on visibility: float 0.4 is visible and float 0 is hidden, so a float is read and non-zero is true; int64 0 hides; int 2 [ 0 0 ] hides, where the same shape as a priority is ignored outright; and a string reads as true.

A wrong-typed value is still a definition: rendered, a string on the nearest node beats a visibility 0 two levels up and the object is visible, so it wins its ranking rather than falling through to the next candidate. The trap therefore has two jaws. A backend that reaches for OwnedArgument::as_i32 here gets None for the numeric three and draws an object the renderer hides; one that reads that None as “not defined” and looks further along the chain draws hidden where the renderer draws visible. This crate hands back the argument rather than a decoded flag precisely because the rule is the renderer’s, and it is not the rule beside it.

Such a winner comes back with AttributeValue::arg None: this crate names the attribute and leaves ɴsɪ’s default for it to the backend, which is the one thing it cannot supply.

§Errors

As Scene::geometry_binding: walking the path can fail.

Source

pub fn attribute_value_along( &self, path: &[String], name: &str, ) -> Option<AttributeValue<'_>>

The same, along one Placement’s path.

A geometry with more than one parent has no single path, so Scene::attribute_value refuses it – and then the rules it applies could not be applied to an instanced object at all. This takes the path from a placement instead.

Infallible: the path has already been walked, so there is nothing left to refuse.

Source

pub fn shader_attribute_value_along( &self, path: &[String], name: &str, ) -> Option<AttributeValue<'_>>

The same, for the shaderattributes container.

Proximity only, as Scene::shader_attribute_value explains, and the path’s first node – the geometry – still outranks every container. This is the body Scene::shader_attribute_value runs over a geometry’s own chain, not a second copy of the rule.

Source

pub fn shader_attributes( &self, geometry: &str, ) -> Result<Vec<String>, ResolveError>

The sources of shader attributes for a geometry, in ɴsɪ’s precedence order.

The first entry is the geometry itself, which is a source in its own right and outranks every container: ɴsɪ gives “the highest priority … to attributes set directly on the geometric primitive”. It is listed unconditionally, so a caller walking this in order and taking the first handle that defines what it wants gets the same answer as Scene::shader_attribute_value. Every later entry is an attributes node.

After it come ɴsɪ’s second attribute container, nearest the geometry first. The same attributes node type reaches it, through the shaderattributes connection rather than geometryattributes, gathered “along the path starting from the geometric primitive, through all the transform nodes it is connected to, until the scene root is reached”.

§Errors

As Scene::geometry_binding: walking the path can fail.

Source

pub fn shader_attribute_value( &self, geometry: &str, name: &str, ) -> Result<Option<AttributeValue<'_>>, ResolveError>

The value of one shader attribute, gathered along a geometry’s path.

§Precedence

Not the rule Scene::attribute_value applies. ɴsɪ gives this container its own, and it is simpler: “Priority is given to nodes attached closest to the geometric primitive, with the highest priority given to attributes set directly on the geometric primitive.” There is no ATTR.priority here and no per-ray fallback – nearest wins, then connection order. Reusing the geometryattributes rule would invent a priority the specification does not give this node.

AttributeValue::priority is therefore always 0.

ɴsɪ adds that attributes on such a node “may only have a single value”; this does not enforce that, and returns what was recorded.

§Scope

ɴsɪ allows these on “geometric primitives, transform nodes or set nodes”. All three are walked; see gathered_containers for where a set ranks.

§Errors

As Scene::geometry_binding: walking the path can fail.

Source

pub fn order_decided( &self, geometry: &str, ) -> Result<Vec<OrderDecided<'_>>, ResolveError>

Every attribute on a geometry’s path that only connection order decides: defined on two or more nodes at the same priority and the same distance from the geometry. See OrderDecided.

Covers the attributes nodes reached through geometryattributes, ranked as Scene::attribute_value ranks them; the three shader slots, ranked by their connection’s priority as Scene::geometry_binding ranks them; and the shaderattributes containers, which rank by distance alone. A definition overridden by priority or by proximity is not reported: that is the scene working as written.

§Errors

As Scene::geometry_binding: walking the path can fail.

Source

pub fn order_decided_along(&self, path: &[String]) -> Vec<OrderDecided<'_>>

The same, along one Placement’s path.

Source§

impl Scene

Source

pub fn world_transform(&self, handle: &str) -> Result<[f64; 16], ResolveError>

Compose the transform chain applying to handle, from the node itself up to .root.

Includes handle’s own matrix when it carries one, so asking about a transform and asking about its child differ by exactly that node’s matrix.

Non-f64 matrices are ignored: ɴsɪ’s transformationmatrix is documented as doublematrix, and silently reinterpreting an f32 one would be worse than skipping it.

§Errors

Every variant of ResolveError. Each is a scene with no single correct world transform, and each would otherwise be answered with a plausible wrong matrix.

Source

pub fn placements(&self, geometry: &str) -> Result<Vec<Placement>, ResolveError>

Every way geometry is placed in the scene.

Scene::world_transform and Scene::geometry_binding answer for the path and refuse a node with more than one parent, because there is no single answer. This enumerates them instead: one Placement per path, in the order the parents were connected, each with the transform and the binding resolved along that path.

A singly-placed geometry yields exactly one placement, agreeing with those two methods, so a backend can use this alone.

§Errors

ResolveError::Cycle for a path that revisits a node, and ResolveError::Detached for a geometry that reaches no root at all. A node reached only through an instances node is skipped rather than refused – an instances node carries one matrix per instance, which Scene::instance_transforms answers; see ResolveError::Instanced.

Source

pub fn placements_at( &self, geometry: &str, time: f64, ) -> Result<Vec<Placement>, ResolveError>

Every placement of geometry, with each transform interpolated at time.

Scene::placements refuses a motion-sampled node and Scene::world_transform_interpolated_at refuses a node with more than one parent, so a geometry with several moving parents had no answer from either. This is that answer.

A geometry animated by an instances node instead – a crowd or a particle system, where the instancer’s transformationmatrices are sampled – is a different question, and Scene::instance_transforms_at answers it. This one returns an empty list for such a prototype, because it has no direct placement.

The end sample is held outside the sampled range, exactly as Scene::world_transform_interpolated_at describes.

§Errors

As Scene::placements, less ResolveError::MotionSampledTransform – the case this exists to answer – plus ResolveError::MissingSampleAtTime for a time that names no sample, such as a NaN.

Source§

impl Scene

Source

pub fn world_transforms(&self) -> WorldTransforms<'_> ⓘ

Every node under .root, with its world transform, composing each matrix once.

Scene::world_transform answers for one geometry by walking up to .root, which is right for one question and quadratic for the whole scene: measured, a twenty-deep chain with 50 000 geometries under it costs 6.2 us per geometry – the same twenty matrices composed fifty thousand times – of which the multiply itself is under a tenth. This descends instead, carrying the accumulated transform down, so each node’s matrix is composed once.

One entry per path, so a geometry under two parents appears twice, as it does in Scene::placements and as it must to a renderer.

Nodes are yielded in no particular order beyond a parent preceding its children. A cycle ends the branch it is on rather than looping; the single-answer accessors refuse it outright.

A motion-sampled transform contributes its static value here, which is None – ask Scene::world_transform_samples per geometry for those. This is the flat pass a backend makes once, not the motion pass.

Source§

impl Scene

Source

pub fn instance_sources(&self, instances: &str) -> Vec<String>

The prototypes an instances node draws from, in connection order.

Mitsuba turns these into a shapegroup referenced by instance shapes; MoonRay into a GeometrySet. Both start from this list. ɴsɪ: connections “must have an integer index attribute if there are several, so the models effectively form an ordered list”, and an instances node’s modelindices “is matched to the index attribute of the model connection”. So the list is ordered by that index, not by connection order – a backend indexes into it. Connections without one share index 0 and keep their relative connection order.

Source

pub fn relative_transform( &self, handle: &str, ancestor: &str, ) -> Result<[f64; 16], ResolveError>

Compose the transform chain from handle up to, but excluding, ancestor.

The transform an instancing prototype needs: its subtree cannot be resolved to world space, because the instances node placing it holds one matrix per instance, but it can be resolved relative to the prototype root that the instance transform is then applied to.

relative_transform(h, ROOT) is Scene::world_transform.

§Errors

ResolveError::NotAnAncestor when ancestor is not on handle’s chain, plus the usual walk errors.

Source

pub fn instances(&self, instances: &str) -> Result<Instances<'_>, ResolveError>

The instancer’s instances, without copying the matrices.

The streaming twin of Scene::instance_transforms, with the same rules: modelindices matched against each connection’s index attribute rather than connection order, disabledinstances applied, and a sampled instancer refused rather than reported empty – ask Scene::instance_transforms_at for that one.

This is the shape a renderer’s own instancer wants: create one object per Scene::instance_sources entry, then feed it (source, transform) pairs. Measured on a million instances, the copying form spends 110 ms and returns 136 MB against the 128 MB the scene already holds; this borrows.

Both per-instance lookups are hashed rather than scanned. The copying form scans the source list and the disabled list for every instance, which is fine for the ten-prototype scene it was written against and quadratic for a set-dressing instancer with thousands.

§Errors

As Scene::instance_transforms.

Source

pub fn instance_transforms( &self, instances: &str, ) -> Result<Vec<Instance>, ResolveError>

The instances an instances node places.

Reads ɴsɪ’s transformationmatrices for the per-instance transforms, modelindices for which prototype each draws, and disabledinstances for the ones to skip. An instance whose model index is negative is omitted too: ɴsɪ says “a negative value will cause an instance to not be rendered”.

Empty when the node carries no transformationmatrices at all.

§Errors

ResolveError::MalformedInstanceMatrices when the matrix buffer is not a whole number of 4x4s, and ResolveError::UnknownModelIndex when a modelindices entry matches no prototype connection. Both were silent drops, which is the failure mode this crate exists to refuse.

ResolveError::MotionSampledTransform when the matrices are sampled rather than static: this read only the static attributes, so a moving instancer – which 3Delight renders – came back as an empty list, indistinguishable from “no instances”. Ask Scene::instance_transforms_at for those.

Source

pub fn instance_transforms_at( &self, instances: &str, time: f64, ) -> Result<Vec<Instance>, ResolveError>

The same, with the instance matrices interpolated at time.

ɴsɪ animates a whole instancer by sampling transformationmatrices, which is how a crowd or a particle system moves. Interpolated element-wise between the bracketing samples and held outside them, exactly as Scene::world_transform_interpolated_at describes.

§Errors

As Scene::instance_transforms, less ResolveError::MotionSampledTransform; plus ResolveError::MissingSampleAtTime for a time that names no sample, such as a NaN.

Source§

impl Scene

Source

pub fn faces(&self, handle: &str) -> Result<Faces<'_>, ResolveError>

The faces of a mesh, with nholes resolved.

§Errors

ResolveError::MissingFaceCounts when the mesh sets no nvertices, which ɴsɪ requires, and ResolveError::MalformedFaceCounts when nholes asks for more or fewer nvertices values than the mesh carries – the case that otherwise renders as a different mesh with no report.

Source§

impl Scene

Source

pub fn motion_times(&self, handle: &str) -> Result<Vec<f64>, ResolveError>

Every time at which a transform in handle’s chain is sampled, ascending, deduplicated.

Empty for a wholly static chain, which is the check a backend makes to decide between Scene::world_transform and Scene::world_transform_samples.

Transforms only. An instances node whose transformationmatrices are sampled reports no motion times here, while Scene::instance_transforms refuses it and says to ask at a time – leaving a backend that used this as its static-or-sampled check with no time to ask at. Use Scene::attribute_times with "transformationmatrices" for an instancer, and Scene::attribute_times with "P" for deforming geometry.

§Errors

ResolveError::MultipleParents or ResolveError::Cycle.

Source

pub fn motion_times_along(&self, path: &[String]) -> Vec<f64>

The same, along a path already walked.

Scene::motion_times refuses a geometry with more than one parent, because it walks the chain itself and there is no single chain. A backend emitting per-sample transforms for an instanced object needs the times of its path, which is what a Placement carries – pass placement.path.

Source

pub fn attribute_times( &self, handle: &str, name: &str, ) -> Result<Vec<f64>, ResolveError>

Every time at which name is sampled on handle, ascending.

Empty when the attribute is static or absent, which is the check a backend makes before asking for Scene::attribute_samples – the same shape as Scene::motion_times and Scene::world_transform_samples.

This is what makes deforming geometry resolvable: a mesh whose P is sampled under a static transform has no motion times at all, so Scene::motion_times answers “static” for something that plainly moves. Ask this for "P", and take the union with Scene::motion_times when a backend needs every time the object changes – ɴsɪ does not require the two to agree.

§Every recorded time, including unreadable ones

Scene::motion_times drops a sample whose type it cannot read, because 3Delight unsets such an attribute and it knows transformationmatrix is a doublematrix. This cannot: name is any attribute, and the crate does not carry ɴsɪ’s type for each one, so “unreadable” has no meaning here. It reports what was recorded and Scene::attribute_samples hands over the arguments for a caller that knows the type to judge.

So the two disagree by design on a scene with a wrong-typed transform sample, and that is the one case worth knowing about.

§Errors

ResolveError::UnknownHandle if no such node exists.

Source

pub fn attribute_samples( &self, handle: &str, name: &str, ) -> Result<Vec<(f64, &OwnedArgument)>, ResolveError>

The recorded samples of name on handle, ascending by time.

Empty on the same terms as Scene::attribute_times. The static value, if any, is not included: a sampled attribute and a static one are separate recordings, and mixing them would invent a sample at a time the caller never set.

§Errors

ResolveError::UnknownHandle if no such node exists.

Source

pub fn sampled_attribute( &self, handle: &str, name: &str, readable: impl Fn(&OwnedArgument) -> bool, ) -> Result<Sampled<'_>, ResolveError>

The same, with ɴsɪ’s typing rule applied.

Scene::attribute_samples reports what was recorded, because name is any attribute and this crate does not carry ɴsɪ’s type for each one. A backend does know: it knows P is a point and N a normal. Hand that knowledge in as readable and this applies the rule the resolver applies to transformationmatrix, rather than making every backend re-derive it.

The rule, rendered on a mesh’s deforming P and identical to the transform case: an unreadable call unsets the attribute at the call, so it discards what was defined before it and only later calls rebuild it. Good at t=0 with a float at t=1 draws nothing (Sampled::Unset); the same two with a good P re-set at t=1 afterwards draws static at that P. A backend that dropped the unreadable sample and kept the rest would sweep through both, which is the answer 3Delight gives to neither.

§What readable should say

3Delight does not type-check every attribute, so the strictest predicate is not always the right one. Rendered: P declared vector, normal, color, float 12 or double 12 is E6007 and the mesh does not draw – there an exact type_tag == Type::Point3F32 matches the renderer. But N declared vector raises no error and renders identically to a normal, so a predicate demanding Type::Normal3F32 reports Unset for a call 3Delight accepts. The rule this applies is proven for the attributes the renderer type-checks; for the others, readable is the backend’s own policy and this crate does not know better.

§Errors

ResolveError::UnknownHandle if no such node exists. A node that exists but never had the attribute set is Sampled::No, not an error.

Source

pub fn world_transform_interpolated_at( &self, handle: &str, time: f64, ) -> Result<[f64; 16], ResolveError>

The world transform at time, interpolating linearly between the samples that bracket it.

Scene::world_transform_at answers only at a recorded sample, which is right for asking “what did the caller say”. A backend rendering motion blur needs a transform at an arbitrary shutter time instead, and this is that.

§Why component-wise is not a guess

Blur moves points. Linearly interpolating a transformed point gives (1-a)·M₀p + a·M₁p, which is ((1-a)·M₀ + a·M₁)·p – so interpolating the matrix element by element is identical to interpolating the moving point, for every point. It is not an approximation of some better decomposition; it is what a renderer blurring geometry already does. Long rotations look wrong under it because they look wrong under blur, not because this differs from the renderer.

Each node on the chain is interpolated from its own samples and the results composed, because each node is animated separately. That is not the same as interpolating the composed world matrices, and it is the accurate model of a hierarchy in motion.

§Outside the sampled range, the end sample is held

Not extrapolated, and not refused – because that is what 3Delight does, and a backend that differed would render a different picture. Rendered with samples at t=0 and t=1 and the shutter open over [-1, 2]: there is zero alpha beyond the two sampled positions, where extrapolation would sweep half again as far each way, and a peak at each end 2.7 times the swept middle, where a third of the shutter is held.

An earlier version of this refused such a time, on the reasoning that clamping “answers for a moment the caller never described”. The caller did describe it: they opened the shutter there.

§Errors

ResolveError::MissingSampleAtTime when time is not a number, which names no sample and brackets no pair.

Also ResolveError::MultipleParents or ResolveError::Cycle from walking the chain.

Source

pub fn world_transform_at( &self, handle: &str, time: f64, ) -> Result<[f64; 16], ResolveError>

Compose the transform chain applying to handle at time.

A node with no motion samples is constant, so its static matrix applies at every time. A node that is sampled contributes the sample at exactly time, and having none there is an error rather than an interpolation; see ResolveError::MissingSampleAtTime.

A wholly static chain resolves at any time, and agrees with Scene::world_transform.

§Errors

Every variant of ResolveError.

Source

pub fn world_transform_samples( &self, handle: &str, ) -> Result<Vec<(f64, [f64; 16])>, ResolveError>

The world transform of handle at each of its Scene::motion_times.

This is the shape a renderer wants for motion blur: the sample times, and the composed matrix at each. Empty for a static chain.

A chain whose nodes are sampled at different times resolves: each node is interpolated from its own samples and the results composed, and the answer agrees with Scene::world_transform_interpolated_at at every time. This paragraph said the opposite – that such a chain was MissingSampleAtTime – for several commits after it stopped being true.

§Errors

Whatever walking the chain refuses, and exactly what Scene::world_transform_interpolated_at refuses for the same scene: the two walk one chain and are held to the same error by the_two_interpolating_accessors_refuse_alike. MissingSampleAtTime cannot arise here – the times come from Scene::motion_times, so every one of them has a sample.

Source§

impl Scene

Source

pub fn render_outputs(&self) -> Vec<RenderOutput>

Resolve ɴsɪ’s output chain into what a renderer actually needs.

ɴsɪ spreads this over four nodes and three connection classes – outputdriver -> outputlayer -> screen -> camera – where both targets want it collapsed: Mitsuba into a Sensor with a Film, MoonRay into RenderOutputs. The walk is the same either way.

One entry per screen, since a screen is what pairs a camera with a resolution. A screen with no layers still yields an entry: the camera and resolution are meaningful on their own.

Layers and drivers come back in connection order, which is insertion order in edges, so AOV order is the order the consumer declared.

Source§

impl Scene

Source

pub fn primitive_variable( &self, handle: &str, name: &str, ) -> Result<Option<PrimitiveVariable<'_>>, ResolveError>

Resolve one primitive variable on a mesh.

§Errors

ResolveError::MissingFaceCounts and ResolveError::MalformedFaceCounts from Scene::faces, ResolveError::MalformedIndices when a <name>.indices is not one entry per face-vertex or points outside the values, and ResolveError::AmbiguousInterpolation when the value count matches none of the four classes. Refusing is deliberate: a guessed interpolation renders, which is how it survives review.

Source§

impl Scene

Source

pub fn weld_table(&self, geometry: &str) -> WeldTable<'_>

The weld table of geometry, read and checked against the geometry’s own boundaries.

Empty, with no problems, for a geometry that declares no welds.

Source

pub fn welds(&self) -> Welds<'_>

Every joined boundary in the scene, grouped by (weld node, id), with every problem in every geometry’s table.

Source§

impl Scene

Source

pub fn take_changes(&mut self) -> Changes

What has changed since this was last called, clearing the record.

ɴsɪ’s NSIRenderControl "synchronize" is where a host asks a renderer to catch up: the specification says “apply all the buffered calls to scene’s state”, so the interval between two synchronises is exactly one batch of edits. Observed on 3Delight: edits made without synchronising change nothing and report nothing; the synchronise then reports Restarted followed by Synchronized, once, for the whole batch.

Taking clears, because the alternative is a record that grows for the life of an interactive session and a caller that must remember where it read up to.

Pass it to Scene::affected for the nodes to re-resolve. This is the half that cannot be reconstructed after the fact – a delete takes its edges with it, and a re-armed connection leaves the graph looking exactly as it did.

Source

pub fn changes(&self) -> &Changes

What has changed, without clearing it.

Source

pub fn affected<'a>(&'a self, changes: &'a Changes) -> Affected<'a>

The nodes a Changes batch may have moved.

Every rule here is the inverse of a walk this crate already does upward. Resolution asks “what applies to this geometry” by climbing objects to .root and gathering containers on the way; a synchronise asks the same question backwards – “given this node changed, whose answers depended on it” – so the indexes that make the climb cheap (by_to_attr) make the descent cheap too, and no new index is needed.

The rules, and what each inverts:

  • a transform’s attribute, or an objects edge: everything below it, and any instancer drawing a prototype found there. Inverts the chain walk. Cameras and lights hang off objects like geometry, so they come along.
  • an attributes node’s attribute, or a shader edge into one: everything below each node it is bound to. Inverts the container gather. A binding onto a set reaches the set’s members.
  • a shader’s own attribute, or a shader-network edge: the shader alone. Nothing about geometry changed.
  • .root or .global: everything.

Over-approximate on purpose – see Affected.

Source

pub fn collapsed_roots<'a>( &'a self, affected: &Affected<'a>, ) -> IndexSet<&'a str>

Everything at or below handle on the objects chain, plus any instancer that draws a prototype found there.

This is what an Affected root stands for. Call it when the list is actually wanted – a backend that is walking its own objects can compare against the roots instead and never build it.

Affected::roots with the roots an ancestor already covers removed.

A root stands for itself and everything below it, so when one root sits under another the union is unchanged – which is why Scene::affected does not do this itself. What it costs is the consumer’s walk: every redundant root is a subtree walked twice.

Opt in when you walk subtrees, not otherwise. Measured on a 1791-node asset hierarchy, release build:

edit batchrootsredundantwalking allcollapsedthis call
a transform and 20 of its descendants21201785 nodes, 200 us597 nodes, 56 us3.6 us
21 unrelated leaves21021 nodes, 2.4 usthe same11.3 us

So a clustered batch – moving an asset and tweaking its parts – returns forty times the check’s cost, and a scattered one pays eleven microseconds for nothing. A consumer that only reads the root names should not call this.

A node with more than one parent is never removed: ɴsɪ’s lightweight instancing puts it under two paths, and a root covering one of them does not cover the other.

Source

pub fn descendants<'a>(&'a self, handle: &'a str) -> IndexSet<&'a str>

Iterative with an explicit stack: an ɴsɪ scene’s depth is the caller’s, not ours, and a recursive walk here would overflow on a deep chain. The insert doubles as the visited set, so a cycle terminates.

Source

pub fn nodes(&self) -> impl Iterator<Item = (&str, &Node)>

The nodes, by handle, in creation order.

Source

pub fn evaluations(&self) -> impl Iterator<Item = &[OwnedArgument]>

The recorded Evaluate calls, in call order.

Each is the argument list as given. A backend that wants archives or procedurals has to execute them itself: this crate records the call and does not define an execution model for it.

Source

pub fn node(&self, handle: &str) -> Option<&Node>

One node by handle.

Source

pub fn edges(&self) -> impl Iterator<Item = &Edge>

The classified connections, in connection order.

Source

pub fn len(&self) -> usize

How many nodes the scene holds.

Source

pub fn is_empty(&self) -> bool

Whether the scene holds no nodes.

Source

pub fn edges_from<'a>( &'a self, handle: &str, ) -> impl Iterator<Item = &'a Edge> + use<'a>

The connections out of handle, in connection order.

Indexed, so this does not scan the scene.

Source

pub fn edges_to<'a>( &'a self, handle: &str, ) -> impl Iterator<Item = &'a Edge> + use<'a>

The connections into handle, in connection order.

Indexed, so this does not scan the scene.

Source

pub fn edges_to_attribute<'a>( &'a self, handle: &str, to_attribute: &str, ) -> impl Iterator<Item = &'a Edge> + use<'a>

The connections into handle through to_attribute, in connection order.

Indexed on both, so this is proportional to the matches rather than to the scene.

Source

pub fn create( &mut self, handle: &str, node_type: &str, ) -> Result<(), RecordError>

Create a node.

§Errors

RecordError::TypeMismatch when the handle exists with a different type. ɴsɪ: “the function does nothing if all other parameters match the call which created that node. Otherwise, it emits an error.” Re-creating with the same type is a no-op, as ɴsɪ says.

Source

pub fn delete(&mut self, handle: &str) -> Result<(), RecordError>

Delete a node and every edge that touches it.

shift_remove rather than swap_remove: insertion order is the replay order and must survive a delete.

§Errors

RecordError::Reserved for .root or .global. ɴsɪ: “it is not possible to delete the root or the global node.” Deleting .root here would strip every membership edge in the scene.

Source

pub fn delete_recursive(&mut self, handle: &str) -> Result<(), RecordError>

Delete a node and, recursively, the nodes that only fed it.

ɴsɪ: “nodes which connect to the specified node are recursively removed, unless they meet one of the following conditions: they also have connections which do not eventually lead to the specified node; their connection to the deleted node was created with a strength greater than 0.” That is what makes deleting a whole shader network one call.

§Errors

RecordError::Reserved for .root or .global.

Source

pub fn set_attribute( &mut self, handle: &str, args: Vec<OwnedArgument>, ) -> Result<(), RecordError>

Set static attributes, overwriting by name.

ɴsɪ: “Setting an attribute using this function replaces any value previously set by NSISetAttribute or NSISetAttributeAtTime.” So this also clears every motion sample of the same name – otherwise a node set static after being sampled would still look motion-blurred to the resolver.

§Errors

RecordError::UnknownHandle when the node does not exist. 3Delight answers the same call with “unknown node handle”. A fabricated node is worse than a rejected one: it joins the scene, satisfies later connect calls, and replays as a Create the renderer never wrote.

Source

pub fn set_attribute_at_time( &mut self, handle: &str, time: f64, args: Vec<OwnedArgument>, ) -> Result<(), RecordError>

Set attributes at one motion sample, keeping samples time-sorted.

§Errors

RecordError::UnknownHandle when the node does not exist.

Source

pub fn delete_attribute(&mut self, handle: &str, name: &str)

Remove one attribute by name, from static and every time sample. Silent when absent, as ɴsɪ is.

Source

pub fn connect( &mut self, from: &str, from_attribute: Option<&str>, to: &str, to_attribute: &str, ) -> Result<(), RecordError>

Classify and record a connection at the default priority.

An unmapped destination propagates rather than being recorded as a guess.

Source

pub fn connect_with_arguments( &mut self, from: &str, from_attribute: Option<&str>, to: &str, to_attribute: &str, args: Vec<OwnedArgument>, ) -> Result<(), RecordError>

Classify and record a connection carrying its ɴsɪ arguments.

ɴsɪ: “It is not an error to create a connection which already exists.” A repeat therefore updates the existing edge’s arguments rather than adding a second one. Recording both would make the node look like it had two parents, which would fail resolution for it and everything beneath it.

Source

pub fn disconnect( &mut self, from: &str, from_attribute: Option<&str>, to: &str, to_attribute: &str, ) -> Result<(), RecordError>

Remove a connection. Silent when absent, as ɴsɪ is.

ɴsɪ: “the handle for either node, as well as any or all of the attributes, may be the special value .all. This will remove all connections which match the other parameters.” So each of the four positions matches everything when it is ALL.

The connection arguments are not part of an edge’s identity: ɴsɪ’s disconnect names four things and priority is not one.

Trait Implementations§

Source§

impl Clone for Scene

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Scene

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for Scene

Source§

fn default() -> Self

Returns the “default value” for a type. Read more
Source§

impl PartialEq for Scene

Two scenes are equal when they describe the same thing.

Written out rather than derived because of what it must exclude: the pending Changes, which say what happened to a scene rather than what it is – a scene that has just been synchronised would otherwise stop being equal to the identical scene that has not – and the three edge indexes, which are a function of the edges they index.

Source§

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

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more

Auto Trait Implementations§

§

impl Forget for Scene

§

impl Freeze for Scene

§

impl Move for Scene

§

impl RefUnwindSafe for Scene

§

impl Send for Scene

§

impl Sync for Scene

§

impl Unpin for Scene

§

impl UnsafeUnpin for Scene

§

impl UnwindSafe for Scene

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.