This interface represents light profiles. More...

#include <ilightprofile.h>

Inheritance diagram for mi::neuraylib::ILightprofile:

[legend]

Public Member Functions
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
	Sets the light profile to a file identified by `filename`. More...

virtual Sint32	reset_reader (IReader *reader, Uint32 resolution_phi=0, Uint32 resolution_theta=0, Lightprofile_degree degree=LIGHTPROFILE_HERMITE_BASE_1, Uint32 flags=LIGHTPROFILE_COUNTER_CLOCKWISE)=0
	Sets the light profile to the data provided by a reader. More...

virtual const char *	get_filename () const =0
	Returns the resolved file name of the file containing the light profile. More...

virtual const char *	get_original_filename () const =0
	Returns the unresolved file name as passed to reset_file(). More...

virtual Uint32	get_resolution_phi () const =0
	Returns the resolution of the grid in phi-direction, or 0 after default construction. More...

virtual Uint32	get_resolution_theta () const =0
	Returns the resolution of the grid in theta-direction, or 0 after default construction. More...

virtual Lightprofile_degree	get_degree () const =0
	Returns the interpolation degree that was used to interpolate the grid data, or mi::neuraylib::LIGHTPROFILE_HERMITE_BASE_1 after default construction. More...

virtual Uint32	get_flags () const =0
	Returns flags that were used to interpret the light profile data in the file, or mi::neuraylib::LIGHTPROFILE_COUNTER_CLOCKWISE after default construction. More...

virtual Float32	get_phi (Uint32 index) const =0
	Returns the `index` -th phi value. More...

virtual Float32	get_theta (Uint32 index) const =0
	Returns the `index` -th theta value. More...

virtual const Float32 *	get_data () const =0
	Returns the normalized data of the entire grid. More...

virtual Float32	get_data (Uint32 index_phi, Uint32 index_theta) const =0
	Returns the normalized data for a grid vertex. More...

virtual Float64	get_candela_multiplier () const =0
	Returns the normalization factor. More...

virtual Float32	sample (Float32 phi, Float32 theta, bool candela) const =0
	Samples the light profile. More...

Public Member Functions inherited from mi::neuraylib::IScene_element
virtual Element_type	get_element_type () const =0
	Indicates the actual scene element represented by interfaces derived from this interface. More...

Public Member Functions inherited from mi::neuraylib::IAttribute_set
virtual IData *	create_attribute (const char name, const char type)=0
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char name, const char type)
	Creates a new attribute `name` of the type `type`. More...

template<class T>
T *	create_attribute (const char *name)
	Creates a new attribute `name` of the type `T`. More...

virtual bool	destroy_attribute (const char *name)=0
	Destroys the attribute `name`. More...

virtual const IData *	access_attribute (const char *name) const =0
	Returns a const pointer to the attribute `name`. More...

template<class T>
const T *	access_attribute (const char *name) const
	Returns a const pointer to the attribute `name`. More...

virtual IData *	edit_attribute (const char *name)=0
	Returns a mutable pointer to the attribute `name`. More...

template<class T>
T *	edit_attribute (const char *name)
	Returns a mutable pointer to the attribute `name`. More...

virtual bool	is_attribute (const char *name) const =0
	Indicates existence of an attribute. More...

virtual const char *	get_attribute_type_name (const char *name) const =0
	Returns the type of an attribute. More...

virtual Sint32	set_attribute_propagation (const char *name, Propagation_type value)=0
	Sets the propagation type of the attribute `name`. More...

virtual Propagation_type	get_attribute_propagation (const char *name) const =0
	Returns the propagation type of the attribute `name`. More...

virtual const char *	enumerate_attributes (Sint32 index) const =0
	Returns the name of the attribute indicated by `index`. More...

Public Member Functions inherited from mi::base::IInterface
virtual Uint32	retain () const =0
	Increments the reference count. More...

virtual Uint32	release () const =0
	Decrements the reference count. More...

virtual const IInterface *	get_interface (const Uuid &interface_id) const =0
	Acquires a const interface from another. More...

template<class T>
const T *	get_interface () const
	Acquires a const interface from another. More...

virtual IInterface *	get_interface (const Uuid &interface_id)=0
	Acquires a mutable interface from another. More...

template<class T>
T *	get_interface ()
	Acquires a mutable interface from another. More...

virtual Uuid	get_iid () const =0
	Returns the interface ID of the most derived interface. More...

Additional Inherited Members
Public Types inherited from mi::base::Interface_declare< 0xa4ac11fd, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
using	Self = Interface_declare< id1, ... >
	Own type. More...

using	IID = Uuid_t< id1, ... >
	Declares the interface ID (IID) of this interface. More...

Public Types inherited from mi::base::IInterface
using	IID = Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0>
	Declares the interface ID (IID) of this interface. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0xa4ac11fd, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface and of its ancestors. More...

Static Public Member Functions inherited from mi::base::IInterface
static bool	compare_iid (const Uuid &iid)
	Compares the interface ID `iid` against the interface ID of this interface. More...

Detailed 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::IFunction_call) or default argument of an MDL function definition (see mi::neuraylib::IFunction_definition). The type of such an argument is mi::neuraylib::IType_light_profile or an alias of it.

Member Function Documentation

^◆ get_candela_multiplier()

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. Returns 0 after default construction.

^◆ get_data() [1/2]

virtual const Float32 * mi::neuraylib::ILightprofile::get_data ( ) const

pure virtual

Returns the normalized data of the entire grid.

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). Returns nullptr after default construction.

See also: get_candela_multiplier()

^◆ get_data() [2/2]

virtual Float32 mi::neuraylib::ILightprofile::get_data	(	Uint32	index_phi,
		Uint32	index_theta
	)		const

pure virtual

Returns the normalized data for a grid vertex.

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 or after default construction.

See also: get_candela_multiplier(), sample()

^◆ get_degree()

virtual Lightprofile_degree mi::neuraylib::ILightprofile::get_degree ( ) const

pure virtual

Returns the interpolation degree that was used to interpolate the grid data, or mi::neuraylib::LIGHTPROFILE_HERMITE_BASE_1 after default construction.

^◆ get_filename()

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 nullptr 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()

^◆ get_flags()

virtual Uint32 mi::neuraylib::ILightprofile::get_flags ( ) const

pure virtual

Returns flags that were used to interpret the light profile data in the file, or mi::neuraylib::LIGHTPROFILE_COUNTER_CLOCKWISE after default construction.

See also: mi::neuraylib::Lightprofile_flags.

^◆ get_original_filename()

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 nullptr after default construction.

See also: get_filename()

^◆ get_phi()

virtual Float32 mi::neuraylib::ILightprofile::get_phi ( Uint32 index ) const

pure virtual

Returns the index -th phi value.

Note that the grid is an equidistant grid, i.e., the distance between subsequent phi values is always the same. If index is out of bounds or after default construction, 0 is returned.

^◆ get_resolution_phi()

virtual Uint32 mi::neuraylib::ILightprofile::get_resolution_phi ( ) const

pure virtual

Returns the resolution of the grid in phi-direction, or 0 after default construction.

^◆ get_resolution_theta()

virtual Uint32 mi::neuraylib::ILightprofile::get_resolution_theta ( ) const

pure virtual

Returns the resolution of the grid in theta-direction, or 0 after default construction.

^◆ get_theta()

virtual Float32 mi::neuraylib::ILightprofile::get_theta ( Uint32 index ) const

pure virtual

Returns the index -th theta value.

Note that the grid is an equidistant grid, i.e., the distance between subsequent theta values is always the same. If index is out of bounds or after default construction, 0 is returned.

^◆ reset_file()

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

Sets the light profile to a file identified by filename.

Parameters

filename	The new file containing the light profile data.
resolution_phi	The desired resolution of the equidistant grid in phi-direction. The special value 0 leaves the choice of a suitable resolution to the implementation. Currently, the implementation behaves as follows: If the angles in phi-direction are already equidistant, the resolution in the file itself (after unfolding of symmetries) is kept unchanged. If the angles in phi-direction are not equidistant, a suitable resolution that maintains the angles given in the file is chosen. If that fails, a fixed resolution is chosen.
resolution_theta	The desired resolution of the equidistant grid in theta-direction. The special value 0 leaves the choice of a suitable resolution to the implementation. Currently, the implementation behaves as follows: If the angles in theta-direction are already equidistant, the resolution in the file itself (after unfolding of symmetries) is kept unchanged. If the angles in theta-direction are not equidistant, a suitable resolution that maintains the angles given in the file is chosen. If that fails, a fixed resolution is chosen.
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 (nullptr).
-3: Invalid filename extension (only .ies is supported).
-4: Failure to resolve the given filename, e.g., the file does not exist.
-5: Failure to open the resolved file.
-7: File format error.
-13: flags is invalid (exactly one of mi::neuraylib::LIGHTPROFILE_CLOCKWISE or mi::neuraylib::LIGHTPROFILE_COUNTER_CLOCKWISE must be set).
-14: degree is invalid. set).
-15: resolution_phi or resolution_theta is invalid (must not be 1).

See also: mi::neuraylib::IMdl_factory::create_light_profile() for a way to create a light profile based on an MDL file path instead of a filename.

^◆ reset_reader()

virtual Sint32 mi::neuraylib::ILightprofile::reset_reader	(	IReader *	reader,
		Uint32	resolution_phi = `0`,
		Uint32	resolution_theta = `0`,
		Lightprofile_degree	degree = `LIGHTPROFILE_HERMITE_BASE_1`,
		Uint32	flags = `LIGHTPROFILE_COUNTER_CLOCKWISE`
	)

pure virtual

Sets the light profile to the data provided by a reader.

Parameters

reader	The reader that provides the data for the BSDF measurement in .ies format.
resolution_phi	The desired resolution of the equidistant grid in phi-direction. The special value 0 leaves the choice of a suitable resolution to the implementation. Currently, the implementation behaves as follows: If the angles in phi-direction are already equidistant, the resolution in the file itself (after unfolding of symmetries) is kept unchanged. If the angles in phi-direction are not equidistant, a suitable resolution that maintains the angles given in the file is chosen. If that fails, a fixed resolution is chosen.
resolution_theta	The desired resolution of the equidistant grid in theta-direction. The special value 0 leaves the choice of a suitable resolution to the implementation. Currently, the implementation behaves as follows: If the angles in theta-direction are already equidistant, the resolution in the file itself (after unfolding of symmetries) is kept unchanged. If the angles in theta-direction are not equidistant, a suitable resolution that maintains the angles given in the file is chosen. If that fails, a fixed resolution is chosen.
degree	The interpolation method to use.
flags	Flags to be used when interpreting the data, see mi::neuraylib::Lightprofile_flags for details.

Returns

0: Success.
-1: Invalid parameters (nullptr).
-7: File format error.
-13: flags is invalid (exactly one of mi::neuraylib::LIGHTPROFILE_CLOCKWISE or mi::neuraylib::LIGHTPROFILE_COUNTER_CLOCKWISE must be set).
-14: degree is invalid. set).
-15: resolution_phi or resolution_theta is invalid (must not be 1).

^◆ sample()

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.

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 or after default construction.

See also: get_data()

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ get_candela_multiplier()

◆ get_data() [1/2]

◆ get_data() [2/2]

◆ get_degree()

◆ get_filename()

◆ get_flags()

◆ get_original_filename()

◆ get_phi()

◆ get_resolution_phi()

◆ get_resolution_theta()

◆ get_theta()

◆ reset_file()

◆ reset_reader()

◆ sample()

^◆ get_candela_multiplier()

^◆ get_data() [1/2]

^◆ get_data() [2/2]

^◆ get_degree()

^◆ get_filename()

^◆ get_flags()

^◆ get_original_filename()

^◆ get_phi()

^◆ get_resolution_phi()

^◆ get_resolution_theta()

^◆ get_theta()

^◆ reset_file()

^◆ reset_reader()

^◆ sample()