neuray API Programmer's Manual

mi::neuraylib::IFibers Class Reference

[Leaf nodes]

Description

Interface representing a collection of fibers. Fibers are represented as cylindrical curves in 3d space, specified by a set of control points and a cylinder radius in object space. The radius can be specified for the whole fiber or per control point.

Four different types of fibers are supported: Uniform cubic b-Splines, Catmull-Rom Splines, cubic Bezier curves and curves made up of linear segments. In case of Catmull-Rom, uniform cubic b-Spline and cubic Bezier curves a minimum of 4 control points need to be specified per fiber, which specify the first segment. Each additional control point for Catmull-Rom and uniform cubic b-Splines specifies a new segment, as 3 control points are shared with the previous segment, while for cubic Bezier curves 3 new control points are needed to specify a new segment, as only one point is shared with the previous segment. In case of linear curves a minimum of 2 control points need to be specified per fiber; each additional control point specifies a new segment, as one control point is shared with the previous segment.

Per-fiber (mi::neuraylib::FIBER_ATTRIBUTE_PER_PRIMITIVE) and per-control point (mi::neuraylib::FIBER_ATTRIBUTE_PER_VERTEX) attributes can be directly used with the methods of this interface, namely create_attribute_vector(), access_attribute_vector(), edit_attribute_vector(), and attach_attribute_vector().

Currently, the following attributes are supported:

  • mi::neuraylib::ATTR_TEXTURE: Both per fiber and per-control point, but only the first texture space may be set. Texture coordinates may be 1, 2, or 3 dimensional.

  • mi::neuraylib::ATTR_USER: Per-control point, up to 4 userdata sets can be provided. The userdata arrays may be 1, 2, or 3 dimensional.

  • mi::neuraylib::ATTR_MOTION: Per-control point motion vectors. A motion vector is of type mi::Float32_3[].

mi::base::Interface_declare\< ..., neuraylib::IScene_element \>Mixin class template for deriving new interface declarations. Common base interface for all scene elements.Common base interface for all scene elements. mi::base::Interface_declare\< ..., neuraylib::IAttribute_set \>Mixin class template for deriving new interface declarations. The attribute set comprises all attributes attached to a database element.The attribute set comprises all attributes attached to a database element. mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

General methods

virtual Size get_fibers_size() const =0
Returns the number of fibers.
virtual Fiber_type get_type() const =0
Returns the fiber type.
virtual Sint32 set_type( Fiber_type fiber_type) =0
Sets the fiber type. More...

Methods related to fibers

virtual Fiber_handle_struct add_fiber( Size vertices) =0
Adds a fiber with the given number of vertices. More...
virtual Sint32 set_radius( Fiber_handle_struct s, Float32 radius) =0
Sets the radius of all vertices of a fiber. More...
virtual Sint32 set_radius( Fiber_handle_struct s, Float64 radius) =0
Sets the radius of all vertices of a fiber. More...

Methods related to vertices

virtual Sint32 get_control_point( Fiber_handle_struct s, Size index, Float32_3_struct& p) const =0
Returns a control point. More...
virtual Sint32 get_control_point( Fiber_handle_struct s, Size index, Float64_3_struct& p) const =0
Returns a control point. More...
virtual Sint32 get_radius( Fiber_handle_struct s, Size index, Float32& radius) const =0
Returns a radius. More...
virtual Sint32 get_radius( Fiber_handle_struct s, Size index, Float64& radius) const =0
Returns a radius. More...
virtual Size get_vertices_size( Fiber_handle_struct s) const =0
Returns the number of vertices. More...
virtual Sint32 set_control_point( Fiber_handle_struct s, Size index, Float32_3_struct p) =0
Sets a control point. More...
virtual Sint32 set_control_point( Fiber_handle_struct s, Size index, Float64_3_struct p) =0
Sets a control point. More...
virtual Sint32 set_radius( Fiber_handle_struct s, Size index, Float32 radius) =0
Sets a radius. More...
virtual Sint32 set_radius( Fiber_handle_struct s, Size index, Float64 radius) =0
Sets a radius. More...

Methods related to per-fiber and per-control point attributes

virtual const IAttribute_vector* access_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) const =0
Returns a fiber object attribute. More...
virtual Sint32 attach_attribute_vector( IAttribute_vector* attribute_vector) =0
Attaches an attribute to the fiber object. More...
virtual IAttribute_vector* create_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name, Uint32 dim = 1) =0
Creates a fiber object attribute. More...
virtual IAttribute_vector* edit_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) =0
Detaches and returns a fiber object attribute. More...
virtual bool  has_attribute( Fiber_attribute_type type, Mesh_attribute_name name) const =0
The attribute vectors that can be created are per-fiber or per-control point. More...
virtual Sint32 remove_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) =0
Removes a fiber object attribute. More...

Methods related to the bounding box

virtual Bbox3_struct get_bbox() const =0
Returns the bounding box of the fibers.
virtual Bbox3_struct get_tight_bbox( const Float64_4_4_struct& transformation_matrix) const =0
Returns the bounding box of the fibers after transformation. More...

Other methods

virtual Sint32 set_data( const Uint32* fibers, Size n, const Float32_4_struct* data, Size m) =0
Sets an array of fibers, control points and radii that describes the whole fiber object. More...
virtual Sint32 set_data( const Float32_4_struct* data, Size n) =0
Sets an array of control points and radii for the whole fiber object. More...
virtual Sint32 set_fiber_data( Fiber_handle_struct s, Size index, const Float32_4_struct* data, Size n) =0
Sets an array of control points and radii per fiber. More...

Member Functions

virtual const IAttribute_vector* mi::​neuraylib::​IFibers::access_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) const [pure virtual]

Returns a fiber object attribute.

Parameters

type
The type of the attribute to query, see Fiber_attribute_type
name
The name of the attribute, see above.

Returns

The requested attribute vector, or NULL in case of failure.

virtual Fiber_handle_struct mi::​neuraylib::​IFibers::add_fiber( Size vertices) [pure virtual]

Adds a fiber with the given number of vertices.

Parameters

vertices
The number of vertices for the new fiber. Needs to be at least 4 for cubic curves and 2 for linear ones.

Returns

A handle for the new fiber, or a default-constructed handle if the number of vertices is not right for fibers type.

virtual Sint32 mi::​neuraylib::​IFibers::attach_attribute_vector( IAttribute_vector* attribute_vector) [pure virtual]

Attaches an attribute to the fiber object. The attribute vector must not be used any longer after it has been attached.

See also:

create_attribute_vector(), edit_attribute_vector()

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -3: The attribute vector is not one of the supported types.
  • -4: The number of elements does not match the number of fibers of the object (if it is a per-fiber attribute vector) or it does not match the number of vertices of the object (if it is a per-control point attribute vector)
  • -5: An attribute of the same name is already attached to the fiber object.

virtual IAttribute_vector* mi::​neuraylib::​IFibers::create_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name, Uint32 dim = 1) [pure virtual]

Creates a fiber object attribute. The attribute is not yet attached to the fiber object. It needs to be attached before it is released.

See also:

attach_attribute_vector()

Parameters

type
The type of the attribute to query, see Fiber_attribute_type
name
The name of the attribute, see above.
dim
Dimension of an attribute value. Only used for those attributes that have user specifiable dimensions.

Returns

The requested attribute vector, or NULL in case of failure.

virtual IAttribute_vector* mi::​neuraylib::​IFibers::edit_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) [pure virtual]

Detaches and returns a fiber object attribute. The attribute needs to be reattached before it is released. Otherwise, the attribute is effectively removed from the fiber object.

See also:

attach_attribute_vector()

Parameters

type
The type of the attribute to query, see Fiber_attribute_type
name
The name of the attribute, see above.

Returns

The requested attribute vector, or NULL in case of failure.

virtual Bbox3_struct mi::​neuraylib::​IFibers::get_bbox() const [pure virtual]

Returns the bounding box of the fibers.

virtual Sint32 mi::​neuraylib::​IFibers::get_control_point( Fiber_handle_struct s, Size index, Float32_3_struct& p) const [pure virtual]

Returns a control point.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
p
The coordinates of the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::get_control_point( Fiber_handle_struct s, Size index, Float64_3_struct& p) const [pure virtual]

Returns a control point.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
p
The coordinates of the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Size mi::​neuraylib::​IFibers::get_fibers_size() const [pure virtual]

Returns the number of fibers.

virtual Sint32 mi::​neuraylib::​IFibers::get_radius( Fiber_handle_struct s, Size index, Float32& radius) const [pure virtual]

Returns a radius.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
radius
The radius of the fiber at the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::get_radius( Fiber_handle_struct s, Size index, Float64& radius) const [pure virtual]

Returns a radius.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
radius
The radius of the fiber at the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Bbox3_struct mi::​neuraylib::​IFibers::get_tight_bbox( const Float64_4_4_struct& transformation_matrix) const [pure virtual]

Returns the bounding box of the fibers after transformation.

Parameters

transformation_matrix
The world-to-object space transformation matrix that is applied to the object before the bounding box is computed.
virtual Fiber_type mi::​neuraylib::​IFibers::get_type() const [pure virtual]

Returns the fiber type.

virtual Size mi::​neuraylib::​IFibers::get_vertices_size( Fiber_handle_struct s) const [pure virtual]

Returns the number of vertices.

Returns

The number of vertices of the given fiber, or 0 if s is out of bounds.

virtual bool mi::​neuraylib::​IFibers::has_attribute( Fiber_attribute_type type, Mesh_attribute_name name) const [pure virtual]

The attribute vectors that can be created are per-fiber or per-control point. They are distinguished by the Fiber_attribute_type and by the following names (see mi::neuraylib::Mesh_attribute_name):

mi::neuraylib::ATTR_TEXTURE : type mi::Float32, 1D, 2D or 3D mi::neuraylib::ATTR_USER : type mi::Float32, 1D, 2D or 3D mi::neuraylib::ATTR_MOTION : type mi::Float32_3[]

All other names are not supported at the moment. Indicates whether the fiber object has a particular attribute.

Parameters

type
The type of the attribute to query, see Fiber_attribute_type
name
The name of the attribute to query, see above.

Returns

true if the fiber object has this attribute, false otherwise.

virtual Sint32 mi::​neuraylib::​IFibers::remove_attribute_vector( Fiber_attribute_type type, Mesh_attribute_name name) [pure virtual]

Removes a fiber object attribute.

Parameters

type
The type of the attribute to query, see Fiber_attribute_type
name
The name of the attribute, see above.

Returns

  • 0: Success.
  • -1: There is no attribute of the given type and name.

virtual Sint32 mi::​neuraylib::​IFibers::set_control_point( Fiber_handle_struct s, Size index, Float32_3_struct p) [pure virtual]

Sets a control point.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
p
The new coordinates of the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_control_point( Fiber_handle_struct s, Size index, Float64_3_struct p) [pure virtual]

Sets a control point.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
p
The new coordinates of the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_data( const Uint32* fibers, Size n, const Float32_4_struct* data, Size m) [pure virtual]

Sets an array of fibers, control points and radii that describes the whole fiber object.

Note:

Calling this function will reset the fiber object.

Parameters

fibers
An array containing the number of control points per fiber.
n
Number of fibers, needs to equal the size of fibers.
data
An array containing the coordinates and radii of all fiber control points.
m
The size of data.

Returns

  • 0: Success.
  • -1: Invalid input data (NULL or zero-length array).
  • -2: One of the fibers has not enough control points for the current interpolation type.
  • -3: m does not match the sum of all control points given in fibers.
  • -4: An attribute vector with non-matching element size is attached to the fibers object.

virtual Sint32 mi::​neuraylib::​IFibers::set_data( const Float32_4_struct* data, Size n) [pure virtual]

Sets an array of control points and radii for the whole fiber object.

Parameters

data
An array containing the coordinates and radii of all fiber control points.
n
The size of data.

Returns

  • 0: Success.
  • -1: Invalid input data (NULL or zero-length array).
  • -2: n does not match the size of the control point array currently given in this fibers object.

virtual Sint32 mi::​neuraylib::​IFibers::set_fiber_data( Fiber_handle_struct s, Size index, const Float32_4_struct* data, Size n) [pure virtual]

Sets an array of control points and radii per fiber.

Parameters

s
The fiber the control points and radii belong to.
index
The index of the first control point on the given fiber (the valid range is 0 to number of vertices-1) that should be overridden by this data.
data
The new coordinates and radii of the control points.
n
The number of control points to be set.

Returns

  • 0: Success.
  • -1: Invalid input data (NULL or zero-length array).
  • -2: Fiber handle s is out of bounds.
  • -3: The control point indices are out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_radius( Fiber_handle_struct s, Float32 radius) [pure virtual]

Sets the radius of all vertices of a fiber.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_radius( Fiber_handle_struct s, Float64 radius) [pure virtual]

Sets the radius of all vertices of a fiber.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_radius( Fiber_handle_struct s, Size index, Float32 radius) [pure virtual]

Sets a radius.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
radius
The new radius of the fiber at the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_radius( Fiber_handle_struct s, Size index, Float64 radius) [pure virtual]

Sets a radius.

Parameters

s
The fiber the control point belongs to.
index
The index of the control point on the given fiber (the valid range is 0 to number of vertices-1).
radius
The new radius of the fiber at the control point.

Returns

  • 0: Success.
  • -1: Fiber handle s is out of bounds.
  • -2: The control point index index is out of bounds.

virtual Sint32 mi::​neuraylib::​IFibers::set_type( Fiber_type fiber_type) [pure virtual]

Sets the fiber type. The default type is mi::neuraylib::FIBER_TYPE_BSPLINE.

Returns

  • 0: Success.
  • -1: The current number of control points does not fit the requested fiber type for at least one fiber.
  • 1: The fiber type was already set to the requested type.