neuray API Programmer's Manual

mi::neuraylib::IFreeform_surface Class Reference

[Leaf nodes]

Description

Interface representing a freeform surface. Conceptually, a freeform surface object consists of several surfaces (see mi::neuraylib::ISurface). Due to a current limitation, only one surface is supported.

Surfaces are stored with consecutive indices, starting with the index 0. For type safety, surface indices are represented using mi::neuraylib::Surface_handle instead of plain integers.

In addition to regular attributes (see mi::neuraylib::IAttribute_set), freeform surfaces can also have mesh attributes. In contrast to regular attributes which exist only once per object, mesh attributes are always a vector of values with one vector element per primitive, per point, or per vertex (see mi::neuraylib::Mesh_attribute_name and mi::neuraylib::IAttribute_vector for details).

For freeform surfaces, only per-primitive mesh attributes are supported (the primitives are the the individual surfaces). Texture spaces are represented via so-called texture surfaces. Other per-point or per-vertex mesh attributes are not supported for freeform surfaces.

See also the "approx" and "approx_curve" attributes on mi::neuraylib::IAttribute_set for information how to control the tessellation of the freeform surface.

See also:

mi::neuraylib::IAttribute_vector

mi::neuraylib::ISurface

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.

Methods related to surfaces

virtual const ISurface* access_surface( Surface_handle_struct s) const =0
Returns a surface (const).
virtual ISurface* add_surface() =0
Adds and returns a new surface. More...
virtual ISurface* edit_surface( Surface_handle_struct s) =0
Returns a surface (mutable).
virtual Uint32 get_surfaces_size() const =0
Returns the number of surfaces.
virtual Sint32 remove_surface( Surface_handle_struct s) =0
Removes a surface. More...

Methods related to per-primitive attributes

virtual const IAttribute_vector* access_attribute_vector( Mesh_attribute_name name) const =0
Returns a per-primitive mesh attribute. More...
virtual Sint32 attach_attribute_vector( IAttribute_vector* attribute_vector) =0
Attaches a given per-primitive mesh attribute to the freeform surface. More...
virtual IAttribute_vector* create_attribute_vector( Mesh_attribute_name name, Uint32 dim = 1) =0
Creates a per-primitive mesh attribute. More...
virtual IAttribute_vector* edit_attribute_vector( Mesh_attribute_name name) =0
Detaches and returns a per-primitive mesh attribute. More...
virtual bool  has_attribute( Mesh_attribute_name name) const =0
Indicates whether the freeform surface has a particular mesh attribute. More...
virtual Sint32 remove_attribute_vector( Mesh_attribute_name name) =0
Removes a per-primitive mesh attribute. More...

Methods related to the bounding box

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

Methods related to displacement

virtual Float32 get_maximum_displacement() const =0
Returns the maximum displacement of the freeform surface. More...
virtual void set_maximum_displacement( Float32 displacement) =0
Sets the maximum displacement of the freeform surface. More...

Member Functions

virtual const IAttribute_vector* mi::​neuraylib::​IFreeform_surface::access_attribute_vector( Mesh_attribute_name name) const [pure virtual]

Returns a per-primitive mesh attribute.

See also:

methods on mi::neuraylib::ISurface for texture spaces

Parameters

name
The name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.

Returns

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

virtual const ISurface* mi::​neuraylib::​IFreeform_surface::access_surface( Surface_handle_struct s) const [pure virtual]

Returns a surface (const).

virtual ISurface* mi::​neuraylib::​IFreeform_surface::add_surface() [pure virtual]

Adds and returns a new surface.

Note:

Currently only one surface is supported.

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

Attaches a given per-primitive mesh attribute to the freeform surface. 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).
  • -2: The attribute vector has not been acquired from this freeform surface.
  • -3: The attribute vector is not a per-primitive attribute vector.
  • -4: The attribute vector is a per-primitive attribute vector and the number of elements does not match the number of surfaces of the freeform surface.
  • -5: An attribute of the same name is already attached to the freeform surface.

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

Creates a per-primitive mesh attribute. The attribute is not yet attached to the freeform surface. It needs to be attached before it is released.

Note:

It is possible to create multiple attribute vectors on the same connectivity. If this connectivity is not the mesh connectivity, i.e., the attribute is not per point, but per vertex, then the connectivity information will eventually be duplicated such that each attribute vector has its own copy. This duplication happens after re-attaching the connectivity, but before it is stored in the database or the edit cycle ends.

See also:

methods on mi::neuraylib::ISurface for texture spaces

attach_attribute_vector()

Parameters

name
The name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.
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::​IFreeform_surface::edit_attribute_vector( Mesh_attribute_name name) [pure virtual]

Detaches and returns a per-primitive mesh attribute. The attribute needs to be reattached before it is released. Otherwise, the attribute is effectively removed from the freeform surface.

See also:

methods on mi::neuraylib::ISurface for texture spaces

attach_attribute_vector()

Parameters

name
The name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.

Returns

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

virtual ISurface* mi::​neuraylib::​IFreeform_surface::edit_surface( Surface_handle_struct s) [pure virtual]

Returns a surface (mutable).

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

Returns the bounding box of the freeform surface.

virtual Float32 mi::​neuraylib::​IFreeform_surface::get_maximum_displacement() const [pure virtual]

Returns the maximum displacement of the freeform surface.

See also:

set_maximum_displacement()

virtual Uint32 mi::​neuraylib::​IFreeform_surface::get_surfaces_size() const [pure virtual]

Returns the number of surfaces.

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

Returns the bounding box of the freeform surface 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 bool mi::​neuraylib::​IFreeform_surface::has_attribute( Mesh_attribute_name name) const [pure virtual]

Indicates whether the freeform surface has a particular mesh attribute.

Parameters

name
The name of the attribute to query, see Mesh_attribute_name.

Returns

true if the freeform surface has this attribute, false otherwise.

virtual Sint32 mi::​neuraylib::​IFreeform_surface::remove_attribute_vector( Mesh_attribute_name name) [pure virtual]

Removes a per-primitive mesh attribute.

Parameters

name
The name of the attribute, see Mesh_attribute_name. The attribute must be a per-primitive attribute.

Returns

  • 0: Success.
  • -1: There is no per-primitive attribute of the given name.

virtual Sint32 mi::​neuraylib::​IFreeform_surface::remove_surface( Surface_handle_struct s) [pure virtual]

Removes a surface. Note that the surface IDs of the following surfaces are decreased by 1.

virtual void mi::​neuraylib::​IFreeform_surface::set_maximum_displacement( Float32 displacement) [pure virtual]

Sets the maximum displacement of the freeform surface. This value is the maximum absolute value of any displacement applied to the object (defaults to 0.0). The bounding box of the object will be expanded all around by this value.