MDL SDK API nvidia_logo_transpbg.gif Up
mi::neuraylib::ILightprofile Class Referenceabstract

This interface represents light profiles. More...

#include <ilightprofile.h>

Inheritance diagram for mi::neuraylib::ILightprofile:

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 Float32get_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 IDatacreate_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 IDataaccess_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 IDataedit_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 IInterfaceget_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 IInterfaceget_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, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x8a2a4da9, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::Interface_declare< 0x1bcb8d48, ... >
typedef Interface_declare< id1, ... > Self
 Own type. More...
 
typedef Uuid_t< id1, ... > IID
 Declares the interface ID (IID) of this interface. More...
 
- Public Types inherited from mi::base::IInterface
typedef Uuid_t<0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0> IID
 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 NULL 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_phiIndex in phi-direction of the vertex.
index_thetaIndex 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 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()

 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 NULL 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
filenameThe new file containing the light profile data.
resolution_phiThe 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_thetaThe 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.
degreeThe interpolation method to use.
flagsFlags to be used when interpreting the file data, see mi::neuraylib::Lightprofile_flags for details.
Returns
  • 0: Success.
  • -1: Invalid parameters (NULL pointer).
  • -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
readerThe reader that provides the data for the BSDF measurement in .ies format.
resolution_phiThe 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_thetaThe 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.
degreeThe interpolation method to use.
flagsFlags to be used when interpreting the data, see mi::neuraylib::Lightprofile_flags for details.
Returns

 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
phiFirst dimension of sample point.
thetaSecond dimension of sample point.
candelaIf 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()