neuray API Programmer's Manual

mi::neuraylib::ISubdivision_surface Class Reference

[Leaf nodes]

Description

Interface representing a subdivision surface. Subdivision surfaces are smooth surfaces that are represented by a coarse control mesh. The smooth surface is the limit surface that results from recursive application of a subdivision process that splits each polygon into smaller polygons that are a better approximation of the limit surface than the input polygon.

The control mesh is represented as a polygon mesh with the limitation that only triangles and quads are supported. Holes are not supported, either. Additionally, vertices may be flagged as smooth (the default) or as corners. For each edge it is possible to set a crease value that defines its sharpness.

Note: If quads have already been added and per-primitive attribute vectors are attached, adding another triangle needs time linear in the number of quads. Thus, it is recommended to either first add the triangles and then the quads, or to detach the per-primitive attribute vectors if a large number of triangles is to be added later.

See also the "approx" attribute on mi::neuraylib::IAttribute_set for information how to control the approximation of the limit surface.

mi::base::Interface_declare\< ..., neuraylib::IPolygon_mesh \>Mixin class template for deriving new interface declarations. Interface representing a polygon mesh.Interface representing a polygon mesh. 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 triangles and quads

virtual Uint32 quads_capacity() const =0
Returns the number of quads for which space is allocated in the mesh. More...
virtual Uint32 quads_size() const =0
Returns the number of quads in the mesh.
virtual void reserve_quads( Uint32 n) =0
Reserves space for at least n quads. More...
virtual void reserve_triangles( Uint32 n) =0
Reserves space for at least n triangles. More...
virtual Uint32 triangles_capacity() const =0
Returns the number of triangles for which space is allocated in the mesh. More...
virtual Uint32 triangles_size() const =0
Returns the number of triangles in the mesh.

Methods related to creases

virtual Float32 get_crease_value( Polygon_handle_struct p, Uint32 index) const =0
Returns crease values for an edge. More...
virtual const Float32* get_crease_values( Polygon_handle_struct p) const =0
Returns crease values for all edges of a polygon. More...
virtual IArray* get_inconsistent_crease_values() const =0
Checks all crease values for consistency and returns inconsistent values. More...
virtual Sint32 set_crease_value( Polygon_handle_struct p, Uint32 index, Float32 value) =0
Sets crease values for an edge. More...
virtual Sint32 set_crease_values( Polygon_handle_struct p, const Float32* values) =0
Sets crease values for all edges of a polygon. More...

Methods related to vertex features

virtual Vertex_feature get_vertex_feature( Uint32 index) const =0
Returns a vertex features. More...
virtual Sint32 set_vertex_feature( Uint32 index, Vertex_feature feature) =0
Sets a vertex feature. More...

Member Functions

virtual Float32 mi::​neuraylib::​ISubdivision_surface::get_crease_value( Polygon_handle_struct p, Uint32 index) const [pure virtual]

Returns crease values for an edge.

Parameters

p
The polygon to return the crease values for.
index
The edge to return the crease value for. Edge i is the edge from vertex i to vertex i+1.

Returns

The requested crease value, or -2.0 if p is out of bounds, or -3.0 if index is out of bounds.

virtual const Float32* mi::​neuraylib::​ISubdivision_surface::get_crease_values( Polygon_handle_struct p) const [pure virtual]

Returns crease values for all edges of a polygon.

Parameters

p
The polygon to return the crease values for.

Returns

A pointer to an array of crease values (3 or 4 values depending on p being a triangle or quad), or NULL if p is out of bounds, or no crease values for the given polygon are specified. The first value is for the edge from vertex 0 to vertex 1, and so on.

virtual IArray* mi::​neuraylib::​ISubdivision_surface::get_inconsistent_crease_values() const [pure virtual]

Checks all crease values for consistency and returns inconsistent values. The array elements are of type "Crease_info[]" and describe all inconsistent crease values for a particular edge. The type "Crease_info" is a structure with the following members:

  • mi::Uint32 polygon_handle,

  • mi::Uint32 edge_index, and

  • mi::Float32 crease_value.

It stores the crease value that was set via the given polygon and its edge index.

Note:

The method always returns NULL if the mesh connectivity is not attached.

virtual Vertex_feature mi::​neuraylib::​ISubdivision_surface::get_vertex_feature( Uint32 index) const [pure virtual]

Returns a vertex features.

Parameters

index
The index of the point to return the vertex feature for.

Returns

The feature of the point index (undefined if index is out of bounds).

virtual Uint32 mi::​neuraylib::​ISubdivision_surface::quads_capacity() const [pure virtual]

Returns the number of quads for which space is allocated in the mesh. One can add quads_capacity() - quads_size() many quads to the mesh before internal reallocation may become necessary.

See also:

reserve_quads().

virtual Uint32 mi::​neuraylib::​ISubdivision_surface::quads_size() const [pure virtual]

Returns the number of quads in the mesh.

virtual void mi::​neuraylib::​ISubdivision_surface::reserve_quads( Uint32 n) [pure virtual]

Reserves space for at least n quads. Sets the internal capacity to at least n quads before reallocation may become necessary. The number of quads currently stored is not changed by this method.

See also:

quads_capacity().

virtual void mi::​neuraylib::​ISubdivision_surface::reserve_triangles( Uint32 n) [pure virtual]

Reserves space for at least n triangles. Sets the internal capacity to at least n triangles before reallocation may become necessary. The number of triangles currently stored is not changed by this method.

See also:

triangles_capacity().

virtual Sint32 mi::​neuraylib::​ISubdivision_surface::set_crease_value( Polygon_handle_struct p, Uint32 index, Float32 value) [pure virtual]

Sets crease values for an edge.

Note:

  • It is the user's responsibility to ensure that crease values are consistent, i.e., that the crease values set for a given edge via different polygons are identical (or not set at all). Inconsistent crease values may lead to wrong results. See also get_inconsistent_crease_values().

  • If no crease values have been set for the other edges of the polygon p, this method sets them to 0.0.

Parameters

p
The polygon to set the crease values for.
index
The edge to set the crease value for. Edge i is the edge from vertex i to vertex i+1.
value
The new crease value.

Returns

  • 0: Success.
  • -2: p is out of bounds.
  • -3: index is out of bounds.
  • -4: value is not in the interval [0, 1].

virtual Sint32 mi::​neuraylib::​ISubdivision_surface::set_crease_values( Polygon_handle_struct p, const Float32* values) [pure virtual]

Sets crease values for all edges of a polygon.

Note:

It is the user's responsibility to ensure that crease values are consistent, i.e., that the crease values set for a given edge via different polygons are identical (or not set at all). Inconsistent crease values may lead to wrong results. See also get_inconsistent_crease_values().

Parameters

p
The polygon to set the crease values for.
values
The array of values (3 or 4 values depending on p being a triangle or quad). The first value is for the edge from vertex 0 to vertex 1, and so on.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: p is out of bounds.
  • -4: At least one value is not in the interval [0, 1].

virtual Sint32 mi::​neuraylib::​ISubdivision_surface::set_vertex_feature( Uint32 index, Vertex_feature feature) [pure virtual]

Sets a vertex feature.

Parameters

index
The index of the point to set the vertex feature for.
feature
The desired feature.

Returns

  • 0: Success.
  • -1: index is out of bounds.
  • -2: Invalid value for feature.

virtual Uint32 mi::​neuraylib::​ISubdivision_surface::triangles_capacity() const [pure virtual]

Returns the number of triangles for which space is allocated in the mesh. One can add triangles_capacity() - triangles_size() many triangles to the mesh before internal reallocation may become necessary.

See also:

reserve_triangles().

virtual Uint32 mi::​neuraylib::​ISubdivision_surface::triangles_size() const [pure virtual]

Returns the number of triangles in the mesh.