neuray API Programmer's Manual

mi::neuraylib::ILightprofile Class Reference

[Miscellaneous]

Description

This interface represents light profiles. IES light profiles ([IES02]) are supplied by lamp vendors to describe their products. They contain a rectangular grid of measured light intensities.

A light profile appears in the scene as an argument of an MDL function call (see mi::neuraylib::IMdl_function_call) or default argument of an MDL function definition (see mi::neuraylib::IMdl_function_definition). The type of such an argument is "Attachable<Ref<Lightprofile>>" (see mi::IRef and mi::IAttachable).

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.

Public Member Functions

virtual Float64 get_candela_multiplier() const =0
Returns the normalization factor. More...
virtual const Float32* get_data() const =0
Returns the normalized data of the entire mesh. More...
virtual Float32 get_data( Uint32 index_phi, Uint32 index_theta) const =0
Returns the normalized data for a grid vertex. More...
virtual Lightprofile_degree get_degree() const =0
Returns the interpolation degree that was used to interpolate the grid data.
virtual const char* get_filename() const =0
Returns the resolved file name of the file containing the light profile. More...
virtual Uint32 get_flags() const =0
Returns flags that were used to interpret the light profile data in the file. More...
virtual const char* get_original_filename() const =0
Returns the unresolved file name as passed to reset_file(). More...
virtual Float32 get_phi( Uint32 index) const =0
Returns the index -th phi value. More...
virtual Uint32 get_resolution_phi() const =0
Returns the resolution of the grid in phi-direction.
virtual Uint32 get_resolution_theta() const =0
Returns the resolution of the grid in theta-direction.
virtual Float32 get_theta( Uint32 index) const =0
Returns the index -th theta value. More...
virtual Sint32 reset_file( const char* filename, Uint32 resolution_phi = 0, Uint32 resolution_theta = 0, Lightprofile_degree degree = LIGHTPROFILE_HERMITE_BASE_1, Uint32 flags = LIGHTPROFILE_COUNTER_CLOCKWISE) =0
Resets the underlying file to a new file given by filename. More...
virtual Float32 sample( Float32 phi, Float32 theta, bool candela) const =0
Samples the light profile. More...

Member Functions

virtual Float64 mi::​neuraylib::​ILightprofile::get_candela_multiplier() const [pure virtual]

Returns the normalization factor. All data is normalized such that the maximum is 1.0. The values returned by methods like get_data() need to be multiplied by this normalization factor to retrieve the true value.

virtual const Float32* mi::​neuraylib::​ILightprofile::get_data() const [pure virtual]

Returns the normalized data of the entire mesh.

See also:

get_candela_multiplier()

Returns

A pointer to the normalized data for all vertices of the grid. The data values are stored as array in column-major order (where all elements of a column have the same phi value).

virtual Float32 mi::​neuraylib::​ILightprofile::get_data( Uint32 index_phi, Uint32 index_theta) const [pure virtual]

Returns the normalized data for a grid vertex.

See also:

get_candela_multiplier(), sample()

Parameters

index_phi
Index in phi-direction of the vertex.
index_theta
Index in theta-direction of the vertex.

Returns

The normalized data for the grid point, or 0 in case of errors.

virtual Lightprofile_degree mi::​neuraylib::​ILightprofile::get_degree() const [pure virtual]

Returns the interpolation degree that was used to interpolate the grid data.

virtual const char* mi::​neuraylib::​ILightprofile::get_filename() const [pure virtual]

Returns the resolved file name of the file containing the light profile. The method returns NULL if there is no file associated with the light profile, e.g., after default construction or failures to resolve the file name passed to reset_file().

See also:

get_original_filename()

virtual Uint32 mi::​neuraylib::​ILightprofile::get_flags() const [pure virtual]

Returns flags that were used to interpret the light profile data in the file.

See also:

mi::neuraylib::Lightprofile_flags.

virtual const char* mi::​neuraylib::​ILightprofile::get_original_filename() const [pure virtual]

Returns the unresolved file name as passed to reset_file(). The method returns NULL after default construction.

See also:

get_filename()

virtual Float32 mi::​neuraylib::​ILightprofile::get_phi( Uint32 index) const [pure virtual]

Returns the index -th phi value. Note that the mesh is an equidistant grid, i.e., the distance between subsequent phi values is always the same. If index is out of bounds, 0 is returned.

virtual Uint32 mi::​neuraylib::​ILightprofile::get_resolution_phi() const [pure virtual]

Returns the resolution of the grid in phi-direction.

virtual Uint32 mi::​neuraylib::​ILightprofile::get_resolution_theta() const [pure virtual]

Returns the resolution of the grid in theta-direction.

virtual Float32 mi::​neuraylib::​ILightprofile::get_theta( Uint32 index) const [pure virtual]

Returns the index -th theta value. Note that the mesh is an equidistant grid, i.e., the distance between subsequent theta values is always the same. If index is out of bounds, 0 is returned.

virtual Sint32 mi::​neuraylib::​ILightprofile::reset_file( const char* filename, Uint32 resolution_phi = 0, Uint32 resolution_theta = 0, Lightprofile_degree degree = LIGHTPROFILE_HERMITE_BASE_1, Uint32 flags = LIGHTPROFILE_COUNTER_CLOCKWISE) [pure virtual]

Resets the underlying file to a new file given by filename.

Parameters

filename
The new file containing the light profile data.
resolution_phi
The desired resolution in phi-direction. The special value 0 represents the resolution from the file itself.
resolution_theta
The desired resolution in theta-direction. The special value 0 represents the resolution from the file itself.
degree
The interpolation method to use.
flags
Flags to be used when interpreting the file data, see mi::neuraylib::Lightprofile_flags for details.

Returns

  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -2: Failure to resolve the given filename, e.g., the file does not exist.
  • -3: degree or flags is invalid (exactly one of mi::neuraylib::LIGHTPROFILE_CLOCKWISE or mi::neuraylib::LIGHTPROFILE_COUNTER_CLOCKWISE must be set).
  • -4: File format error.
virtual Float32 mi::​neuraylib::​ILightprofile::sample( Float32 phi, Float32 theta, bool candela) const [pure virtual]

Samples the light profile. The method computes a bi-linear interpolation of the light profile at (phi,theta) according to the resolution.

See also:

get_data()

Parameters

phi
First dimension of sample point.
theta
Second dimension of sample point.
candela
If false, normalized values are returned, otherwise true values. See get_candela_multiplier().

Returns

The computed sample value, or 0 in case of errors.