Struct nsi::context::Context

pub struct Context<'a> { /* fields omitted */ }

An ɴsɪ Context.

A context is used to describe a scene to the renderer and request images to be rendered from it.

Thread Safety

A context may be used in multiple threads at once.

Lifetime

A context can be used without worrying about its lifetime until you want to store it somewhere, e.g. in a struct.

The reason a context has an explicit lifetime is so that it can take References. These references must be valid until the context is dropped and this guarantee requires explicit lifetimes. When you use a context directly this is not an issue but when you want to reference it somewhere the same rules as with all references apply.

Further Reading

See the ɴsɪ docmentation on context handling.

Implementations

impl<'a> Context<'a>

pub fn new(args: &ArgSlice<'_, 'a>) -> Option<Self>

Creates an ɴsɪ context.

Contexts may be used in multiple threads at once.

Example

// Create rendering context that dumps to stdout.
let ctx = nsi::Context::new(&[nsi::string!("streamfilename", "stdout")])
    .expect("Could not create ɴsɪ context.");

Error

If this method fails for some reason, it returns None.

pub fn create(
    &self,
    handle: impl Into<Vec<u8>>,
    node_type: impl Into<Vec<u8>>,
    args: &ArgSlice<'_, 'a>
)

Creates a new node.

Arguments

• handle - A node handle. This string will uniquely identify the node in the scene.

  If the supplied handle matches an existing node, the function does nothing if all other parameters match the call which created that node. Otherwise, it emits an error. Note that handles need only be unique within a given Context. It is acceptable to reuse the same handle inside different Contexts.

• node_type – The type of node to create. You can use NodeType to create nodes that are in the official NSI specificaion. As this parameter is just a string you can instance other node types that a particualr implementation may provide and which are not part of the official specification.

• args – A [slice] of optional Arg arguments. There are no optional arguments defined as of now.

// Create a context to send the scene to.
let ctx = nsi::Context::new(&[]).unwrap();

// Create an infinte plane.
ctx.create("ground", nsi::NodeType::Plane, &[]);

pub fn delete(&self, handle: impl Into<Vec<u8>>, args: &ArgSlice<'_, 'a>)

This function deletes a node from the scene. All connections to and from the node are also deleted.

Note that it is not possible to delete the .root or the .global nodes.

Arguments

• handle – A handle to a node previously created with create().

• args – A [slice] of optional Arg arguments.

Optional Arguments

• "recursive" (Integer) – Specifies whether deletion is recursive. By default, only the specified node is deleted. If a value of 1 is given, then 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 node to be deleted was created with a strength greater than 0.

  This allows, for example, deletion of an entire shader network in a single call.

pub fn set_attribute(&self, handle: impl Into<Vec<u8>>, args: &ArgSlice<'_, 'a>)

This functions sets attributes on a previously node. All optional arguments of the function become attributes of the node.

On a NodeType::Shader, this function is used to set the implicitly defined shader arguments.

Setting an attribute using this function replaces any value previously set by set_attribute() or set_attribute_at_time().

To reset an attribute to its default value, use delete_attribute().

Arguments

• handle – A handle to a node previously created with create().

• args – A [slice] of optional Arg arguments.

pub fn set_attribute_at_time(
    &self,
    handle: impl Into<Vec<u8>>,
    time: f64,
    args: &ArgSlice<'_, 'a>
)

This function sets time-varying attributes (i.e. motion blurred).

The time argument specifies at which time the attribute is being defined.

It is not required to set time-varying attributes in any particular order. In most uses, attributes that are motion blurred must have the same specification throughout the time range.

A notable exception is the P attribute on NodeType::Particles which can be of different size for each time step because of appearing or disappearing particles. Setting an attribute using this function replaces any value previously set by set_attribute().

Arguments

• handle – A handle to a node previously created with create().

• time – The time at which to set the value.

• args – A [slice] of optional Arg arguments.

pub fn delete_attribute(
    &self,
    handle: impl Into<Vec<u8>>,
    name: impl Into<Vec<u8>>
)

This function deletes any attribute with a name which matches the name argument on the specified object. There is no way to delete an attribute only for a specific time value.

Deleting an attribute resets it to its default value.

For example, after deleting the transformationmatrix attribute on a NodeType::Transform, the transform will be an identity. Deleting a previously set attribute on a NodeType::Shader will default to whatever is declared inside the shader.

Arguments

• handle – A handle to a node previously created with create().

• name – The name of the attribute to be deleted/reset.

pub fn connect(
    &self,
    from: impl Into<Vec<u8>>,
    from_attr: impl Into<Vec<u8>>,
    to: impl Into<Vec<u8>>,
    to_attr: impl Into<Vec<u8>>,
    args: &ArgSlice<'_, 'a>
)

Create a connection between two elements.

It is not an error to create a connection which already exists or to remove a connection which does not exist but the nodes on which the connection is performed must exist.

Arguments

• from – The handle of the node from which the connection is made.

• from_attr – The name of the attribute from which the connection is made. If this is an empty string then the connection is made from the node instead of from a specific attribute of the node.

• to – The handle of the node to which the connection is made.

• to_attr – The name of the attribute to which the connection is made. If this is an empty string then the connection is made to the node instead of to a specific attribute of the node.

Optional Arguments

• "value" – This can be used to change the value of a node's attribute in some contexts. Refer to guidelines on inter-object visibility for more information about the utility of this parameter.

• "priority" (Integer) – When connecting attribute nodes, indicates in which order the nodes should be considered when evaluating the value of an attribute.

• "strength" (Integer) – A connection with a strength greater than 0 will block the progression of a recursive delete().

pub fn disconnect(
    &self,
    from: impl Into<Vec<u8>>,
    from_attr: impl Into<Vec<u8>>,
    to: impl Into<Vec<u8>>,
    to_attr: impl Into<Vec<u8>>
)

This function removes a connection between two elements.

The handle for either node may be the special value ".all". This will remove all connections which match the other three arguments.

Example

// Create a rendering context.
let ctx = nsi::Context::new(&[]).unwrap();
// [...]
// Disconnect everything from the scene's root.
ctx.disconnect(".all", "", ".root", "");

pub fn evaluate(&self, args: &ArgSlice<'_, 'a>)

This function includes a block of interface calls from an external source into the current scene. It blends together the concepts of a file include, commonly known as an archive, with that of procedural include which is traditionally a compiled executable. Both are the same idea expressed in a different language.

Note that for delayed procedural evaluation you should use a Procedural node.

The ɴsɪ adds a third option which sits in-between — Lua scripts. They are more powerful than a simple included file yet they are also easier to generate as they do not require compilation.

For example, it is realistic to export a whole new script for every frame of an animation. It could also be done for every character in a frame. This gives great flexibility in how components of a scene are put together.

The ability to load ɴsɪ commands from memory is also provided.

Optional Arguments

• "type" (String) – The type of file which will generate the interface calls. This can be one of:

  • "apistream" – Read in an ɴsɪ stream. This requires either "filename" or "buffer"/"size" arguments to be specified too.

  • "lua" – Execute a Lua script, either from file or inline. See also how to evaluate a Lua script.

  • "dynamiclibrary" – Execute native compiled code in a loadable library. See dynamic library procedurals for an implementation example in C.

• "filename" (String) – The name of the file which contains the interface calls to include.

• "script" (String) – A valid Lua script to execute when "type" is set to "lua".

• "buffer" (Pointer)

• "size" (Integer) – These two parameters define a memory block that contain ɴsɪ commands to execute.

• "backgroundload" (Integer) – If this is nonzero, the object may be loaded in a separate thread, at some later time. This requires that further interface calls not directly reference objects defined in the included file. The only guarantee is that the file will be loaded before rendering begins.

pub fn render_control(&self, args: &ArgSlice<'_, 'a>)

This function is the only control function of the API.

It is responsible of starting, suspending and stopping the render. It also allows for synchronizing the render with interactive calls that might have been issued.

Optional Arguments

• "action" (String) – Specifies the operation to be performed, which should be one of the following:

  • "start" – This starts rendering the scene in the provided context. The render starts in parallel and the control flow is not blocked.

  • "wait" – Wait for a render to finish.

  • "synchronize" – For an interactive render, apply all the buffered calls to scene’s state.

  • "suspend" – Suspends render in the provided context.

  • "resume" – Resumes a previously suspended render.

  • "stop" – Stops rendering in the provided context without destroying the scene.

• "progressive" (Integer) – If set to 1, render the image in a progressive fashion.

• "interactive" (Integer) – If set to 1, the renderer will accept commands to edit scene’s state while rendering. The difference with a normal render is that the render task will not exit even if rendering is finished. Interactive renders are by definition progressive.

• "frame" – Specifies the frame number of this render.

impl<'a> Context<'a>

pub fn append<'b, 'c>(
    &self,
    to: &'b str,
    slot: Option<&str>,
    handle: &'c str
) -> (&'b str, &'c str) where
    'a: 'b,
    'a: 'c, 

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Append node handle to node to.

Arguments

• to – Node to connect to downstream.

• slot – Slot on target node to connect to. If None, "objects" is used.

• handle – Handle of node to append.

Returns (to, handle).

Example

// Create a scaling transform node and append to the scene root.
let scale = ctx.append(
    ".root",
    // Use "objects" slot.
    None,
    // Append the node "tetrahedron", which we created earlier,
    // to the scale node.
    &ctx.append(
        &ctx.scaling(None, &[10., 10., 10.]),
        // Use "objects" slot.
        None,
        "tetrahedron",
    )
    .0,
);

pub fn insert<'b, 'c>(
    &self,
    to: &'b str,
    to_slot: Option<&str>,
    handle: &'c str,
    handle_slot: Option<&str>,
    from: &str
) -> (&'b str, &'c str) where
    'a: 'b,
    'a: 'c, 

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Insert node handle in-between to and from.

Arguments

• to – Node to connect to downstream.

• to_slot – Slot on to node to connect to. If None, "objects" is used. .

• handle – Handle of node to insert.

• handle_slot – Slot on handle node to connect to. If None, "objects" is used.

• from – Node to connect tp upstream.

Returns (to, handle).

Example

// Insert the node "tetrahedron" between the ".root" and
// "terahedron_attrib" nodes.
ctx.insert(
    ".root",
    None,
    "tetrahedron",
    Some("geometryattributes"),
    "terahedron_attrib",
);

pub fn node(
    &self,
    handle: Option<&str>,
    node_type: impl Into<Vec<u8>>,
    args: &ArgSlice<'_, 'a>
) -> String

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

The same as create() but with support for autmatic handle generation.

If handle is None a random handle is generated.

Returns handle for convenience.

pub fn scaling(&self, handle: Option<&str>, scale: &[f64; 3]) -> String

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Create a scaling transform node.

If handle is None a random handle is generated.

Returns handle for convenience.

pub fn translation(&self, handle: Option<&str>, translate: &[f64; 3]) -> String

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Create a traslation transform node.

If handle is None a random handle is generated.

Returns handle for convenience.

pub fn rotation(
    &self,
    handle: Option<&str>,
    angle: f64,
    axis: &[f64; 3]
) -> String

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Create a traslation transform node.

If handle is None a random handle is generated.

The angle is specified in degrees.

Returns handle for convenience.

pub fn look_at_camera(
    &self,
    handle: Option<&str>,
    eye: &[f64; 3],
    to: &[f64; 3],
    up: &[f64; 3]
)

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

pub fn look_at_bounding_box_perspective_camera(
    &self,
    handle: Option<&str>,
    direction: &[f64; 3],
    up: &[f64; 3],
    vertical_fov: f32,
    aspect_ratio: Option<f32>,
    bounding_box: &[f64; 6]
) -> String

This is supported on crate feature toolbelt only.

Convenience method; not part of the official ɴsɪ API.

Creates a transformation matrix that can be used to position a camera. Its view will contains the perspective-projected bounding box under the specified field-of-view and aspect ratio (with÷height).

Arguments

• direction – The axis the camera should be looking along. Does not need to be normalized.
• up – A direction to look
• bounding_box – Axis-aligned bounding box in the form [x_min, y_min, z_min, x_max, y_max, z_max].

Trait Implementations

impl<'a> Debug for Context<'a>

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

Formats the value using the given formatter.

impl<'a> Drop for Context<'a>

pub fn drop(&mut self)

Executes the destructor for this type.

impl<'a> From<Context<'a>> for NSIContext_t

pub fn from(context: Context<'a>) -> Self

Performs the conversion.

impl<'a> Hash for Context<'a>

pub fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

pub fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl<'a> PartialEq<Context<'a>> for Context<'a>

pub fn eq(&self, other: &Context<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

pub fn ne(&self, other: &Context<'a>) -> bool

This method tests for !=.

impl<'a> StructuralPartialEq for Context<'a>