neuray API Programmer's Manual

mi::neuraylib::ISurface Class Reference

[Leaf nodes]

Description

A surface of a freeform surface. Surfaces are defined by their basis type, degree (in U and V direction), number of patches (in U and V direction), the parameter vector (in U and V direction), and the 2-dimensional grid of control points. In case of rational surfaces, an additional weight is associated with each control point.

Two basis types are currently supported: Bezier and B-Spline.

Note the distinction between surfaces and patches. A patch is the smallest unit that can be described with a given basis. For example, a patch for a cubic Bezier bases has 4 x 4 control points. A surface consists of one or more patches. Neighboring patches share control points. For example, a patch in a B-Spline surface of degrees d in a given parameter space dimension shares its last d control points with the next patch in that dimension.

The degree, the number of patches, the length of the parameter vector, and the number of control points in a given parameter space dimension are related as follows:

Bezier basis

B-Spline basis

#parameters

#patches + 1

#patches + 2*degree + 1

#control points

#patches * degree + 1

#patches + degree

The degree and the number of patches can be explicitly controlled (see set_degree() and set_patches_size()). The numbers of parameters and controls points are automatically computed based on the degree and the number of patches.

Furthermore, surfaces can be trimmed by parametric curves (see mi::neuraylib::ICurve). Texture surfaces can be attached to specify how surface vertices are mapped to texture coordinates (see mi::neuraylib::ITexture_surface).

Curves and texture surfaces are stored with consecutive indices, starting with the index 0. For type safety, indices of curves and textures surfaces are represented using mi::neuraylib::Curve_handle and mi::neuraylib::Texture_surface_handle instead of plain integers.

See also:

mi::neuraylib::IFreeform_surface

mi::neuraylib::ICurve

mi::neuraylib::ITexture_surface

mi::neuraylib::Parameter_space_dimension

mi::neuraylib::Basis_type

mi::base::Interface_declare\< ... \>Mixin class template for deriving new interface declarations. The basic extensible interface.The basic extensible interface.

Methods related to bases

virtual Basis_type get_basis_type() const =0
Returns the basis type.
virtual Uint32 get_degree( Parameter_space_dimension dim) const =0
Returns the basis degree. More...
virtual Sint32 set_basis_type( Basis_type type) =0
Sets the basis type. More...
virtual Sint32 set_degree( Parameter_space_dimension dim, Uint32 degree) =0
Sets the basis degree. More...

Methods related to the patches

virtual Uint32 get_patches_size( Parameter_space_dimension dim) const =0
Returns the number of patches. More...
virtual Sint32 set_patches_size( Parameter_space_dimension dim, Uint32 count) =0
Sets the number of patches. More...

Methods related to the parameter vector

virtual Float64 get_parameter( Parameter_space_dimension dim, Uint32 index) const =0
Returns a parameter. More...
virtual Uint32 get_parameters_size( Parameter_space_dimension dim) const =0
Returns the size of the parameter vector. More...
virtual Sint32 set_parameter( Parameter_space_dimension dim, Uint32 index, Float64 value) =0
Sets a parameter. More...

Methods related to control points and weights

virtual Sint32 get_control_point( Uint32 index_u, Uint32 index_v, Float32_3_struct& p) const =0
Returns a control point. More...
virtual Sint32 get_control_point( Uint32 index_u, Uint32 index_v, Float64_3_struct& p) const =0
Returns a control point. More...
virtual Uint32 get_control_points_size( Parameter_space_dimension dim) const =0
Returns the number of control points. More...
virtual bool  get_rational() const =0
Returns the rational flag.
virtual Sint32 get_weight( Uint32 index_u, Uint32 index_v, Float32& weight) const =0
Returns a weight. More...
virtual Sint32 get_weight( Uint32 index_u, Uint32 index_v, Float64& weight) const =0
Returns a weight. More...
virtual Sint32 set_control_point( Uint32 index_u, Uint32 index_v, Float32_3_struct p) =0
Sets a control point. More...
virtual Sint32 set_control_point( Uint32 index_u, Uint32 index_v, Float64_3_struct p) =0
Sets a control point. More...
virtual void set_rational( bool rational) =0
Sets the rational flag. More...
virtual Sint32 set_weight( Uint32 index_u, Uint32 index_v, Float32 weight) =0
Sets a weight. More...
virtual Sint32 set_weight( Uint32 index_u, Uint32 index_v, Float64 weight) =0
Sets a weight. More...

Methods related to ranges

virtual Sint32 get_range( Parameter_space_dimension dim, Float64& range_min, Float64& range_max) const =0
Returns the parameter range. More...
virtual Sint32 set_range( Parameter_space_dimension dim, Float64 range_min, Float64 range_max) =0
Sets the parameter range. More...

Methods related to curves

virtual const ICurve* access_curve( Curve_handle_struct c) const =0
Returns a curve (const).
virtual ICurve* add_curve() =0
Adds and returns a new curve.
virtual Uint32 curves_size() const =0
Returns the number of curves.
virtual ICurve* edit_curve( Curve_handle_struct c) =0
Returns a curve (mutable).
virtual Sint32 remove_curve( Curve_handle_struct c) =0
Removes a curve. More...

Methods related to texture surfaces

virtual const ITexture_surface* access_texture_surface( Texture_surface_handle_struct t) const =0
Returns a texture surface (const).
virtual ITexture_surface* add_texture_surface() =0
Adds and returns a new texture surface.
virtual ITexture_surface* edit_texture_surface( Texture_surface_handle_struct t) const =0
Returns a texture surface (mutable).
virtual Sint32 remove_texture_surface( Texture_surface_handle_struct t) =0
Removes a texture surface. More...
virtual Uint32 texture_surfaces_size() const =0
Returns the number of texture surfaces.

Member Functions

virtual const ICurve* mi::​neuraylib::​ISurface::access_curve( Curve_handle_struct c) const [pure virtual]

Returns a curve (const).

virtual const ITexture_surface* mi::​neuraylib::​ISurface::access_texture_surface( Texture_surface_handle_struct t) const [pure virtual]

Returns a texture surface (const).

virtual ICurve* mi::​neuraylib::​ISurface::add_curve() [pure virtual]

Adds and returns a new curve.

virtual ITexture_surface* mi::​neuraylib::​ISurface::add_texture_surface() [pure virtual]

Adds and returns a new texture surface.

virtual Uint32 mi::​neuraylib::​ISurface::curves_size() const [pure virtual]

Returns the number of curves.

virtual ICurve* mi::​neuraylib::​ISurface::edit_curve( Curve_handle_struct c) [pure virtual]

Returns a curve (mutable).

virtual ITexture_surface* mi::​neuraylib::​ISurface::edit_texture_surface( Texture_surface_handle_struct t) const [pure virtual]

Returns a texture surface (mutable).

virtual Basis_type mi::​neuraylib::​ISurface::get_basis_type() const [pure virtual]

Returns the basis type.

virtual Sint32 mi::​neuraylib::​ISurface::get_control_point( Uint32 index_u, Uint32 index_v, Float32_3_struct& p) const [pure virtual]

Returns a control point.

Parameters

index_u
The index of the control point in u-direction.
index_v
The index of the control point in v-direction.
p
The current value of the control point.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::get_control_point( Uint32 index_u, Uint32 index_v, Float64_3_struct& p) const [pure virtual]

Returns a control point.

Parameters

index_u
The index of the control point in u-direction.
index_v
The index of the control point in v-direction.
p
The current value of the control point.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Uint32 mi::​neuraylib::​ISurface::get_control_points_size( Parameter_space_dimension dim) const [pure virtual]

Returns the number of control points.

Note:

The number of control points is determined by the basis degree and the number of patches.

Parameters

dim
The affected dimension.

Returns

The number of control points, or 0 in case of an invalid dimension.

virtual Uint32 mi::​neuraylib::​ISurface::get_degree( Parameter_space_dimension dim) const [pure virtual]

Returns the basis degree.

Parameters

dim
The affected dimension.

Returns

The basis degree, or 0 in case of an invalid dimension.

virtual Float64 mi::​neuraylib::​ISurface::get_parameter( Parameter_space_dimension dim, Uint32 index) const [pure virtual]

Returns a parameter.

Parameters

dim
The affected dimension.
index
The index of the requested parameter.

Returns

The parameter, or 0.0f in case of invalid dimension or index.

virtual Uint32 mi::​neuraylib::​ISurface::get_parameters_size( Parameter_space_dimension dim) const [pure virtual]

Returns the size of the parameter vector.

Note:

The size of the parameter vector is determined by the basis degree and the number of patches.

Parameters

dim
The affected dimension.

Returns

The number of parameters, or 0 in case of an invalid dimension.

virtual Uint32 mi::​neuraylib::​ISurface::get_patches_size( Parameter_space_dimension dim) const [pure virtual]

Returns the number of patches.

Parameters

dim
The affected dimension.

Returns

The number of patches, or 0 in case of an invalid dimension.

virtual Sint32 mi::​neuraylib::​ISurface::get_range( Parameter_space_dimension dim, Float64& range_min, Float64& range_max) const [pure virtual]

Returns the parameter range. The parameter range basically is a trimming curve of rectangular shape in the parameter space.

Parameters

dim
The affected dimension.
range_min
The lower bound of the parameter range.
range_max
The upper bound of the parameter range.

Returns

  • 0: Success.
  • -1: Invalid dimension.
virtual bool mi::​neuraylib::​ISurface::get_rational() const [pure virtual]

Returns the rational flag.

virtual Sint32 mi::​neuraylib::​ISurface::get_weight( Uint32 index_u, Uint32 index_v, Float32& weight) const [pure virtual]

Returns a weight.

Parameters

index_u
The index of the weight in u-direction.
index_v
The index of the weight in v-direction.
weight
The current value of the weight.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::get_weight( Uint32 index_u, Uint32 index_v, Float64& weight) const [pure virtual]

Returns a weight.

Parameters

index_u
The index of the weight in u-direction.
index_v
The index of the weight in v-direction.
weight
The current value of the weight.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::remove_curve( Curve_handle_struct c) [pure virtual]

Removes a curve. Note that the curve IDs of the following curves are decreased by 1.

virtual Sint32 mi::​neuraylib::​ISurface::remove_texture_surface( Texture_surface_handle_struct t) [pure virtual]

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

virtual Sint32 mi::​neuraylib::​ISurface::set_basis_type( Basis_type type) [pure virtual]

Sets the basis type.

Note:

This method resets the parameter vector, and all control points and weights.

Parameters

type
The desired basis type.

Returns

  • 0: Success.
  • -1: Invalid basis type.
virtual Sint32 mi::​neuraylib::​ISurface::set_control_point( Uint32 index_u, Uint32 index_v, Float32_3_struct p) [pure virtual]

Sets a control point.

Parameters

index_u
The index of the control point in u-direction.
index_v
The index of the control point in v-direction.
p
The new value of the control point.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::set_control_point( Uint32 index_u, Uint32 index_v, Float64_3_struct p) [pure virtual]

Sets a control point.

Parameters

index_u
The index of the control point in u-direction.
index_v
The index of the control point in v-direction.
p
The new value of the control point.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::set_degree( Parameter_space_dimension dim, Uint32 degree) [pure virtual]

Sets the basis degree.

Note:

This method resets the parameter vector, and all control points and weights.

Parameters

dim
The affected dimension.
degree
The desired basis degree.

Returns

  • 0: Success.
  • -1: Invalid dimension.
  • -2: Invalid degree (zero).
virtual Sint32 mi::​neuraylib::​ISurface::set_parameter( Parameter_space_dimension dim, Uint32 index, Float64 value) [pure virtual]

Sets a parameter.

Parameters

dim
The affected dimension.
index
The index of the parameter to update.
value
The new value of the parameter.

Returns

  • 0: Success.
  • -1: Invalid dimension.
  • -2: index is out of bounds.
virtual Sint32 mi::​neuraylib::​ISurface::set_patches_size( Parameter_space_dimension dim, Uint32 count) [pure virtual]

Sets the number of patches.

Note:

This method resets the parameter vector, and all control points and weights.

Parameters

dim
The affected dimension.
count
The desired number of patches.

Returns

  • 0: Success.
  • -1: Invalid dimension.
  • -2: Invalid count (zero).
virtual Sint32 mi::​neuraylib::​ISurface::set_range( Parameter_space_dimension dim, Float64 range_min, Float64 range_max) [pure virtual]

Sets the parameter range. The parameter range basically is a trimming curve of rectangular shape in the parameter space.

Parameters

dim
The affected dimension.
range_min
The lower bound of the parameter range.
range_max
The upper bound of the parameter range.

Returns

  • 0: Success.
  • -1: Invalid dimension.
  • -2: range_min is larger than range_max.
virtual void mi::​neuraylib::​ISurface::set_rational( bool rational) [pure virtual]

Sets the rational flag.

Parameters

rational
Indicates whether weights should be used (rational surfaces) or not (non-rational surfaces). If false, all weights are removed. If true, all weights are set to 1.0f (if they did not already exist).
virtual Sint32 mi::​neuraylib::​ISurface::set_weight( Uint32 index_u, Uint32 index_v, Float32 weight) [pure virtual]

Sets a weight.

Note:

This method implicitly calls set_rational() with true as argument.

Parameters

index_u
The index of the weight in u-direction.
index_v
The index of the weight in v-direction.
weight
The new value of the weight.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
  • -2: weight has an invalid value (0.0f).
virtual Sint32 mi::​neuraylib::​ISurface::set_weight( Uint32 index_u, Uint32 index_v, Float64 weight) [pure virtual]

Sets a weight.

Note:

This method implicitly calls set_rational() with true as argument.

Parameters

index_u
The index of the weight in u-direction.
index_v
The index of the weight in v-direction.
weight
The new value of the weight.

Returns

  • 0: Success.
  • -1: index_u or index_v is out of bounds.
  • -2: weight has an invalid value (0.0f).
virtual Uint32 mi::​neuraylib::​ISurface::texture_surfaces_size() const [pure virtual]

Returns the number of texture surfaces.