Naming Convention Redesign

Status: Draft

Rationale

The current ɴsɪ attribute names grew organically and suffer from several inconsistencies that make the API harder to learn and use than it needs to be.

No word separation. Most multi-word names are run together, forcing users to mentally parse where words begin and end — and the conventions are unpredictable:

Inconsistent grouping. Some attributes use dot-separated groups, others don’t — even for closely related settings:

Cryptic abbreviations alongside verbose names. Single-letter names coexist with long compound words:

Node type names baked into attributes. Some attributes redundantly include the node type, others don’t:

This document proposes a systematic naming convention that resolves these inconsistencies. The complete mapping from current to proposed names is in the attribute mapping below.

Why Separate Words at All?

Concatenated names like maximumraylength or importancesamplefilter are hard to read — especially for non-native English speakers, who may not immediately see where one word ends and the next begins. Word separators make attribute names accessible to a wider audience without any downside: attribute name strings are interned by the renderer, so separators have zero runtime cost. They add a few bytes to the source but nothing to render time.

A common objection is that separators mean more typing. In practice this matters less than it used to: code is increasingly written with AI assistance and autocompletion, so keystroke count is a non-issue. What matters is how easily a human can read and review the code — and depth-of-field.focal-length is unambiguously clearer than depthoffield.focallength.

Redesign Proposal

Hyphenate Multi-Word Attributes

Attribute names use hyphens (-) as word separators, not underscores (_). This is a deliberate choice: almost no programming language allows hyphens in identifiers (variable-name is invalid in C, C++, Python, Rust, Lua, etc.), so attribute name strings are instantly distinguishable from code identifiers in any language. When you see reflection.ray-depth-max in source code, it can only be an attribute name — never a variable, function, or type.

Core Convention

• . (dots) separate hierarchy levels — these correspond to what would be groups/rollouts/sections in UI/attribute editor.
• - (hyphens) separate words within a single label.
• Singular nouns when used as modifiers in compound names (English compound noun rule).
  • Example: point-grid not points-grid — “point” modifies “grid”.
• Plain English over jargon (governing principle — R9).
  • Example field-of-view not fov.
• Compound node type names also use hyphens: vdb-particles, output-driver, output-layer, face-set, perspective-camera, fisheye-camera, etc.
• Example: subdivision.corner-sharpness — group “Subdivision”, label “Corner Sharpness”.

Rulings

R1: Type-first grouping for ray settings

Ray depth/length settings on the global node are grouped by ray type, since each type has multiple related attributes (depth + length):

reflection.ray-depth-max
reflection.ray-length-max
diffuse.ray-depth-max
diffuse.ray-length-max

R2: 2+ related attributes required to form a dot-group

Only use dot-separated hierarchy when there are 2 or more related attributes that form a logical group. Single standalone attributes use flat hyphenated naming:

Groups (dot-separated):

subdivision.scheme
subdivision.corner-index
subdivision.corner-sharpness
visibility.camera
visibility.diffuse
visibility.reflection

Flat (hyphen-separated):

vertex-count
hole-count
clockwise
reference-time
quadratic-motion

R3: The grouping level is context-dependent, not concept-fixed

The same concept (e.g., “reflection”) can be a group in one context and a leaf in another. The rule is: whichever level has 2+ siblings becomes the group.

On the global node — each ray type has 2+ settings (depth + length), so the ray type is the group:

reflection.ray-depth-max
reflection.ray-length-max

On the attributes node — each ray type has only ONE visibility flag, but “visibility” has 8+ flags, so visibility is the group:

visibility.reflection
visibility.diffuse
visibility.camera

The alternative (type-first everywhere: reflection.visibility, diffuse.visibility, etc.) would create 8 singleton groups, violating R2. The 2+ rule takes precedence over concept consistency.

R4: Node type is an implicit top-level group

The node type itself provides context, so attribute names should not redundantly include the node type. On a curves node, the attribute is basis, not curve-basis. On a particles node, the attribute is id, not particle-id.

R5: Rename everything, including legacy single-letter names

No grandfather clause for industry-standard abbreviations:

• P → position
• N → normal
• nvertices → vertex-count
• nholes → hole-count

Single-word names that are already clear stay as-is: width, basis, id, matte, clockwise.

R6: Hyphen-separate compound domain terms

No concatenated words. All multi-word terms get hyphens:

• depthoffield → depth-of-field
• fstop → focal-stop
• focallength → focal-length
• focaldistance → focal-distance

This applies within both group names and leaf labels:

depth-of-field.enable
depth-of-field.focal-stop
depth-of-field.focal-length
depth-of-field.aperture.enable    ← sub-group (3 attrs: enable, sides, angle)
depth-of-field.aperture.sides
depth-of-field.aperture.angle

R7: Connection attribute plurality matches cardinality

If a connection attribute accepts multiple connections, use plural. If it accepts only one, use singular.

Plural (multi-connection):

objects              (root, transform — multiple geometry nodes)
attributes           (root, transform — multiple attribute nodes)
members              (set — multiple objects)
screens              (camera — multiple screen nodes)
output-layers        (screen — multiple layer nodes)
output-drivers       (output-layer — multiple driver nodes)

Singular (single-connection):

shader.surface       (attributes — one surface shader)
shader.displacement  (attributes — one displacement shader)
shader.volume        (attributes — one volume shader)
background-layer     (output-layer — one background layer)

R8: Group by concern, not by concept

Attributes are grouped by what kind of setting they are, not by what rendering concept they relate to. This keeps groups semantically coherent:

• quality.* = how much effort the renderer spends (sampling counts, performance)
• shading.* = which shading features are enabled/disabled (feature toggles)
• {type}.* = per-ray-type limits (depth, length)

quality.shading-samples           ← sampling effort
quality.volume-samples            ← sampling effort
quality.denoise                   ← quality toggle
quality.volume-emission-sampling  ← quality toggle
quality.preview.global-update     ← preview/IPR quality
quality.preview.interpolate       ← preview/IPR quality
quality.preview.speed-multiplier  ← preview/IPR quality

shading.displacement              ← feature toggle
shading.atmosphere                ← feature toggle
shading.multiple-scattering       ← feature toggle
shading.osl-subsurface            ← feature toggle

volume.ray-depth-max              ← ray limit
volume.ray-length-max             ← ray limit

This avoids scattering quality-related attrs across concept groups (which would make it hard to find “all the knobs that affect render speed”).

R9: Plain English over jargon (governing principle)

This is a governing principle that applies across all naming decisions. When choosing between a technical abbreviation/jargon term and a plain English equivalent, always prefer plain English. Names should be understandable without domain-specific knowledge.

• ipr → preview (Interactive Progressive Rendering → just “preview”)
• fov → field-of-view
• fstop → focal-stop (kept because it’s the actual name of the unit, not jargon)

The group quality.ipr.* becomes quality.preview.*:

quality.preview.global-update
quality.preview.interpolate
quality.preview.speed-multiplier

R10: Use .enable suffix for booleans in mixed groups

When a boolean on/off attribute belongs to a group that also has non-boolean attrs, append .enable to distinguish the toggle from the group:

depth-of-field.enable         ← mixed group (has focal-stop, focal-length, etc.)
depth-of-field.focal-stop
depth-of-field.focal-length

cryptomatte.enable            ← mixed group (has level)
cryptomatte.level

When the group is all-toggles or the boolean is standalone, no .enable needed:

shading.displacement          ← all-toggle group, obviously a toggle
shading.atmosphere

quality.denoise               ← obviously a toggle from context

R11: Unify callbacks under callback.* group

All callback/handler function pointers across the API follow a consistent pattern: callback.{purpose} for the function pointer and callback.{purpose}.data for the associated userdata.

This applies across different API calls — the callback group is a cross-cutting convention:

# NSIBegin
callback.error               ← error handler function (was: errorhandler)
callback.error.data          ← error handler userdata (was: errorhandler.data)

# NSIRenderControl
callback.stop                ← stopped callback function (was: stoppedcallback)
callback.stop.data           ← stopped callback userdata (was: stoppedcallbackdata)

R12: Singular nouns as modifiers in compound names

When a noun serves as a modifier (adjective) in a compound name, use its singular form. This follows standard English compound noun formation: “dog house” not “dogs house”, “vertex count” not “vertices count”.

vertex-count         ✓  (not vertices-count)
hole-count           ✓  (not holes-count)
face-index           ✓  (not faces-index)
point-grid           ✓  (not points-grid)
object-index         ✓  (not objects-index)

Plurals are reserved for R7 (connection cardinality), where the attribute name IS the thing, not a modifier:

objects              ✓  (the attribute is multiple objects, not a modifier)
members              ✓
output-layers        ✓

Open Question: Node Granularity

The convention above renames attributes consistently, but it doesn’t resolve a deeper inconsistency in how ɴsɪ models primitives. Three different patterns are in play across the existing node types:

mesh collapses polygons and subdivision surfaces behind a subdivision.scheme attribute. Cameras do the opposite — five separate node types that differ only in their projection function. Volumes name themselves generically while only one backend is implemented. Particles are split by the data format their control points hold, not by what the renderer sees.

Three coherent resolutions, from least to most invasive:

Option 1 — Honest names, same shape

Keep one node per concern and rename for honesty. The mapping later in this document already adopts these names:

• volume → vdb-volume (it only renders OpenVDB).
• vdbparticles → vdb-particles (hyphenated).
• Cameras keep their five hyphenated names (perspective-camera, …).
• mesh stays as the one merged exception.

The inconsistency with mesh remains. This is a pure rename — no API change.

Option 2 — Collapse to one canonical primitive

Bring volumes, particles, and cameras in line with mesh’s “one node, type attribute” pattern:

• vdb-volume and vdb-particles collapse into a single vdb node with kind = "volume" | "particles" (or distinguished by which data attribute is supplied).
• The five camera nodes collapse into one camera node with projection = "perspective" | "fisheye" | "cylindrical" | "spherical" | "orthographic". Projection-specific attributes live behind the projection’s prefix (e.g. fisheye.mapping).

Every scene-graph entity ends up with a single canonical primitive. Migration is “rename node type, add a kind / projection attribute”. The renderer’s dispatch table has to flatten, but no user-side attribute is lost.

Option 3 — Split mesh to match the rest

Adopt the honest renames from Option 1 — volume → vdb-volume, vdbparticles → vdb-particles — and additionally replace mesh with polygon-mesh and subdivision-mesh. Each mesh node carries only the attributes meaningful for its surface kind; subdivision.scheme disappears entirely.

This is the most invasive option: every existing scene using subdivision surfaces has to re-target the new node, and the subdivision.* attributes migrate from prefix-grouped on mesh to top-level on subdivision-mesh.

Trade-offs

• Option 1 is cheapest to deliver; it preserves the inconsistency under prettier names.
• Option 2 matches the mesh pattern. Requires backend dispatch work but no user-facing data loss.
• Option 3 is the cleanest in isolation but invalidates the largest existing-asset footprint.

No recommendation in this draft. The decision belongs in the API roadmap, not in a renaming pass.

Open Question: ᴏsʟ Built-In Variable Alignment

ɴsɪ is designed to feed ᴏsʟ shaders. When the renderer puts the control-point position into an attribute named P on a mesh node, an ᴏsʟ shader reads it as the built-in global variable P without any plumbing in between. That 1:1 mapping is part of what makes ᴏsʟ shaders portable across renderers, and it directly conflicts with R5.

R5 currently renames the legacy single-letter attribute names:

Adopting R5 as written means the attribute name and the ᴏsʟ global diverge. The renderer either has to translate position → P at the ᴏsʟ binding step — hidden machinery that surprises anyone debugging by attribute name — or the cross-renderer ᴏsʟ contract has to break for ɴsɪ specifically.

The ᴏsʟ globals that overlap with current ɴsɪ attribute names are: P, N, Ng, u, v, dPdu, dPdv, I.

Option A — Carve out an exception in R5

Legacy single-letter names that match an ᴏsʟ global stay as-is, even where the surrounding convention would rename them. This preserves the ɴsɪ ↔ ᴏsʟ alignment.

Affected rows revert in the rename mapping:

• mesh: P stays.
• nurbs: P stays. Pw stays (semantics flow into the same ᴏsʟ binding).
• curves: P stays.
• particles: P stays, N stays.

nvertices, nholes, clockwisewinding etc. still rename — they aren’t ᴏsʟ globals.

Option B — Rename and translate

Adopt R5 as written. The renderer translates position → P (and normal → N, …) when binding attributes to ᴏsʟ shader globals.

This keeps ɴsɪ-level naming uniform but introduces hidden translation. Shader authors writing portable code now read about P in the ᴏsʟ docs and position in the ɴsɪ docs and have to internalise the mapping. Debugging tools that show attribute names won’t match what the shader sees.

Trade-off

The decision turns on which contract matters more:

• ᴏsʟ portability (Option A) — the convention that “the attribute named P is what the shader reads as P” is sacred.
• ɴsɪ-internal consistency (Option B) — single-letter names are jargon and R5’s reasoning applies uniformly; the ᴏsʟ binding layer can absorb the cost.

No recommendation in this draft.

Complete Attribute Mapping

Every attribute across all node types, with current → new name and the ruling(s) that apply. Attributes where current = new are omitted.

global Node

Unchanged: license.server, license.wait, license.hold, frame, statistics.progress, statistics.filename, verbose

root Node

Unchanged: objects

set Node

Unchanged: members

mesh Node

Unchanged: subdivision.scheme

nurbs Node

The u and v axes each have five related attributes (count, order, knot, min, max), so per R3 each axis becomes a group.

Consolidation note (API change, not pure rename). The current API stores trim-curve control points as three parallel arrays (trimcurves.u, trimcurves.v, trimcurves.w) — a structure-of-arrays layout. The surface stores its control points as one interleaved array (P or Pw) — an array-of-structures layout. The redesign aligns the two:

• trim-curves.position — float[2], non-rational (u, v) pairs. Replaces trimcurves.u and trimcurves.v.
• trim-curves.weighted-position — float[3], rational (u, v, w) triples. Replaces trimcurves.u, trimcurves.v, and trimcurves.w.

Supply one of the two; never both. This is the same supply-one-of pattern the surface uses for position / weighted-position.

face-set Node

curves Node

Unchanged: width, basis, extrapolate

particles Node

Unchanged: width, id

procedural Node

environment Node

Unchanged: angle

shader Node

attributes (geometry) Node

Unchanged: ATTR.priority, visibility.camera, visibility.diffuse, visibility.hair, visibility.reflection, visibility.refraction, visibility.shadow, visibility.specular, visibility.volume, visibility, matte, bounds

transform Node

Unchanged: objects

instances Node

output-driver Node

output-layer Node

Unchanged: dithering, cryptomatte.enable, cryptomatte.level

screen Node

Unchanged: resolution, oversampling, crop, overscan

vdb-particles Node

Unchanged: width

volume Node

Camera Nodes (perspective-camera, fisheye-camera, cylindrical-camera)

Common (all cameras):

perspective-camera:

fisheye-camera:

Unchanged: mapping

cylindrical-camera:

API Parameter Mapping

NSIBegin

Unchanged: type

NSIDelete

Unchanged: recursive

NSIConnect

Unchanged: value, priority, strength

NSIEvaluate

Unchanged: type, filename, script, buffer, size

NSIRenderControl

Unchanged: action, progressive, interactive, frame

Open question — action as a positional argument: Every meaningful NSIRenderControl call needs an action value — one of start, wait, synchronize, suspend, resume, stop. The call is a no-op without it. Yet the current signature carries action inside the optional-parameter bag, peer to the genuinely-optional progressive / interactive / callback parameters.

Promoting action to a required positional argument would make intent visible at the call site:

typedef enum {
    NSIRenderStart,
    NSIRenderWait,
    NSIRenderSynchronize,
    NSIRenderSuspend,
    NSIRenderResume,
    NSIRenderStop,
} NSIRenderAction;

void NSIRenderControl(
    NSIContext_t        ctx,
    NSIRenderAction     action,
    int                 nparams,
    const NSIParam_t   *params);

A string overload can be kept for the Lua and Python bindings, where "start" / "wait" / "stop" read idiomatically. The enum form catches typos at compile time and surfaces the closed set of allowed values to IDE completion.

If adopted, action leaves this rename table entirely — there is nothing left to rename.