[−][src]Struct nsi::Context
An ɴsɪ context.
Also see the ɴsɪ docmentation on context handling.
Implementations
impl Context
[src]
pub fn new(args: &ArgSlice) -> Option<Self>
[src]
Creates an ɴsɪ context.
Contexts may be used in multiple threads at once.
Example
// Create rendering context that dumps to stdout. let c = 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: Node,
args: &ArgSlice
)
[src]
&self,
handle: impl Into<Vec<u8>>,
node_type: Node,
args: &ArgSlice
)
This function is used to create 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 interface context. It is acceptable to reuse the same handle inside different contexts.
-
node_type
– The type of node to create. -
args
– Astd::slice
of optionalarg::Arg
arguments. There are no optional parameters defined as of now.
pub fn delete(&self, handle: impl Into<Vec<u8>>, args: &ArgSlice)
[src]
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 withContext::create()
. -
args
– Astd::slice
of optionalarg::Arg
arguments.
Optional Arguments
-
"recursive"
(arg::ArgData::Integer
) – Specifies whether deletion is recursive. By default, only the specified node is deleted. If a value of1
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 deleted node was created with a
strength
greater than0
.
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)
[src]
This functions sets attributes on a previously node. All optional arguments of the function become attributes of the node.
On a Node::Shader
, this function is used to set the implicitly
defined shader arguments.
Setting an attribute using this function replaces any value
previously set by Context::set_attribute()
or
Context::set_attribute_at_time()
.
To reset an attribute to its default value, use
Context::delete_attribute()
).
Arguments
-
handle
– A handle to a node previously created withContext::create()
. -
args
– Astd::slice
of optionalarg::Arg
arguments.
pub fn set_attribute_at_time(
&self,
handle: impl Into<Vec<u8>>,
time: f64,
args: &ArgSlice
)
[src]
&self,
handle: impl Into<Vec<u8>>,
time: f64,
args: &ArgSlice
)
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 (particles)Node::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 NSISetAttribute()
.
Arguments
-
handle
– A handle to a node previously created withContext::create()
. -
time
– The time at which to set the value. -
args
– Astd::slice
of optionalarg::Arg
arguments.
pub fn delete_attribute(
&self,
handle: impl Into<Vec<u8>>,
name: impl Into<Vec<u8>>
)
[src]
&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 Node::Transform
, the transform will be an identity.
Deleting a previously set attribute on a Node::Shader
will
default to whatever is declared inside the shader.
Arguments
-
handle
– A handle to a node previously created withContext::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
)
[src]
&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
)
These two function creates 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"
(arg::ArgData::Integer
) – When connecting attribute nodes, indicates in which order the nodes should be considered when evaluating the value of an attribute. -
"strength"
(arg::ArgData::Integer
) – A connection with astrength
greater than0
will block the progression of a recursiveContext::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>>
)
[src]
&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)
[src]
This function includes a block of interface calls from an
external source into the current scene. It blends together the
concepts of a straight file include, commonly known as an
archive, with that of procedural include which is traditionally
a compiled executable. Both are really the same idea expressed
in a different language (note that for delayed procedural
evaluation one should use a (Node::Procedural
) node).
The ɴsɪ adds a third option which sits in-between — (Lua scripts)[https://nsi.readthedocs.io/en/latest/lua-api.html] They are much more powerful than a simple included file yet they are also much easier to generate as they do not require compilation. It is, for example, very 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 straight from memory is also provided.
Optional Arguments
-
"type"
(arg::ArgData::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"
(arg::ArgData::String
) – The name of the file which contains the interface calls to include. -
"script"
(arg::ArgData::String
) – A valid Lua script to execute when"type"
is set to"lua"
. -
"buffer"
(arg::ArgData::Pointer
) -
"size"
(arg::ArgData::Integer
) – These two parameters define a memory block that contain ɴsɪ commands to execute. -
"backgroundload"
(arg::ArgData::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)
[src]
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"
(arg::ArgData::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"
(arg::ArgData::Integer
) – If set to1
, render the image in a progressive fashion. -
"interactive"
(arg::ArgData::Integer
) – If set to1
, 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.
Trait Implementations
impl Drop for Context
[src]
impl From<i32> for Context
[src]
fn from(context: NSIContext_t) -> Self
[src]
Auto Trait Implementations
impl RefUnwindSafe for Context
impl Send for Context
impl Sync for Context
impl Unpin for Context
impl UnwindSafe for Context
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,