Spectrum Interface

Unlike with the miColor structure, it is not possible to access the members of the miSpectrum structure directly. All manipulations of spectra have to be performed with the help of interface routines. If these routines create new spectra or spectrum iterators, then they will be created within thread-local memory pools. Hence, these structures cannot be shared between several threads. This issue becomes important for init shaders. Spectra and spectrum iterators in init shaders that will be used by the regular shaders should therefore be created with the mi_spectrum_create_inheap routine and deleted with the mi_spectrum_delete_fromheap routine. This approach requires mental ray to perform a memory locking and therefore is detremental to parallel performance. As a result it is recommended to avoid allocating on the heap whenever possible.

Spectrum Utility Routines

mi_spectrum_enabled
const char* mi_spectrum_enabled()

If spectra have been enabled for this rendering, then the routine will return a pointer to character string identifying the spectrum implemention in use. If spectra are not enabled, then a null pointer is returned.

mi_spectrum_ensure
miSpectrum* mi_spectrum_ensure(miSpectrum* s)

The routine checks if the passed in spectrum is a valid spectrum. If it is not, then the spectrum will be initizalized. The routine is used in the mi_eval_spectrum macro to ensure that passed in spectra are valid.

mi_spectrum_check
miBoolean mi_spectrum_check(miSpectrum* s)

The routine takes a pointer to a spectrum as an argument. It returns miTRUE if the pointer refers to a valid spectrum. Else it returns miFALSE.

mi_spectrum_size
unsigned int mi_spectrum_size(const miSpectrum* s)

Returns the size of the spectrum referenced by the argument pointer. If the pointer is null, then the size of a default spectrum structure is returned.

mi_spectrum_range_get
void mi_spectrum_range_get(const miSpectrum* s, miScalar*
lo, miScalar* hi)

Retrieves the lowest and highest wavelengths values lo and hi associated with the spectrum s.

mi_spectrum_linewidth
miScalar mi_spectrum_linewidth(const miSpectrum* s, miScalar w)

Retrieves the width of the spectrum line at the given wavelength (given in nanometers) of the spectrum represented by s.

mi_spectrum_visible_range
void mi_spectrum_visible_range(miScalar* min_lambda, miScalar* max_lambda)

Returns the wavelength range representable by the the current spectrum representation. For the default mental ray spectrum representation the range is from 400 to 700 nano-meters.

mi_spectrum_blackbody
void mi_spectrum_blackbody(miSpectrum* bbody, miScalar temperature, miScalar intensity)

Stores a spectrum corresponding to a black body radiator at the given temperature (in Kelvin) in bbody. The spectrum is scaled such that the total intensity in the visible domain is the requested intensity.

mi_spectrum_cie
void mi_spectrum_cie(miSpectrum* cie, miScalar intensity, const char* illuminant)

Stores a spectrum corresponding to one of the CIE A, B, C, or D65 standard illuminants, scaled to the given intensity in cie. Valid illuminants are selected by one of the strings "A", "B", "C" or "D65".

mi_spectrum_cie_sky
void mi_spectrum_cie_sky(miSpectrum* sky, miScalar temperature, miScalar intensity)

Stores a spectrum corresponding to a CIE D spectrum at the given correlated color temperature, scaled to the given intensity, in sky.

Spectrum Manipulation Routines

mi_spectrum_blueprint
miSpectrum* mi_spectrum_blueprint()

Returns a pointer to a reference spectrum. This routine may be used to obtain information about spectra by passing the pointer returned to other routines. The spectrum referenced by this pointer may not be altered.

mi_spectrum_create
miSpectrum* mi_spectrum_create(miSpectrum_data* sd)

Creates a copy of the blueprint spectrum and returns a pointer to it. If the miSpectrum_data pointer passed in is non-null, then this data is used to initialize the spectrum. Otherwise the new spectrum is initialized with the contents of the blueprint.

mi_spectrum_create_inheap
miSpectrum* mi_spectrum_create_inheap(miSpectrum_data* sd)

Creates a copy of the blueprint spectrum and returns a pointer to it. If the miSpectrum_data pointer passed in is non-null, then this data is used to initialize the spectrum. Otherwise the new spectrum is initialized with the contents of the blueprint. Unlike all other routines creating spectra, this routine allocates the spectum memory on the heap. Hence, this routine should be used if the spectrum is to be shared between several threads. A typicial situation requiring this appoach is the creation of a spectrum within an init shader. Note that allocating memory on the heap requires memory locking and therfore is detremental to parallel efficiency. This routine should only be used sparingly - in general mi_spectrum_create should be preferred.

mi_spectrum_clone
miSpectrum* mi_spectrum_clone(const miSpectrum* s)

Creates a one-to-one copy of the spectrum passed in and returns a pointer to this copy.

mi_spectrum_copy
void mi_spectrum_(miSpectrum* s, const miSpectrum* in)

Copies the entire contents of the spectrum referenced by in to the spectrum referenced by s.

mi_spectrum_assign
void mi_spectrum_assign(miSpectrum* s, const miSpectrum* in)

Assigns the spectrum values of the in spectrum to the corresponding wavelength values of the spectrum s. Only values are assigned, the wavelengths of spectrum s are unchanged. If the wavelength ranges of the in and s spectrum do not coincide, then values present within in but not in s will not be assigned. values present within s but outside the wavelength range of in will be assigned a zero value.

mi_spectrum_assign_data
void mi_spectrum_assign_data(miSpectrum *s, const miSpectrum_data* data)

Retrieves for each relevant wavelength within the wavelength range of the spectrum s a value from the spectrum data referenced by the data pointer. This assignment may be expensive. Hence, if possible this routine should be called in an init shader.

mi_spectrum_add
void mi_spectrum_add(miSpectrum* s, const miSpectrum *in)

Adds to each component of the spectrum s the corresponding component of the in spectrum.

mi_spectrum_mul
void mi_spectrum_mul(miSpectrum* s, const miSpectrum *in)

Multiplies each component of the spectrum s with the corresponding component of the in spectrum.

mi_spectrum_scale
void mi_spectrum_scale(miSpectrum* s, Scalar scale)

Multiplies each component of the spectrum s with scale.

mi_spectrum_scale_add
void mi_spectrum_scale_add(miSpectrum* s, const miSpectrum* in, Scalar scale)

Adds to each component of the spectrum s the corresponding component of the in spectrum, scaled by the factorscale.

mi_spectrum_lerp
void mi_spectrum_lerpe(miSpectrum* s, const miSpectrum* in, Scalar lerp)

Multiplies each component of the spectrum s with the factor (1-lerp) and adds to it the corresponding component of the in spectrum, multiplied by the factor lerp.

mi_spectrum_color_add
void mi_spectrum_color_color_add(miSpectrum* s, const miColor* in)

Associates with the given CIE XYZ color in a spectrum. This choice of spectrum is based on a heuristic, since there are infinitely many spectra resulting in the same color. This spectrum is then added on a per component basis to spectrum s.

mi_spectrum_rgb
void mi_spectrum_rgb(miColor* c, const miSpectrum* s)

Computes a tristimulus color representation of the provided spectrum in mental rays BoxRGB color space. The routine may be used to obtain a color representation that can be passed to shaders that do not understand spectra. Such shaders may not trace any rays or sample lights.

mi_spectrum_value_get
miScalar mi_spectrum_value_get(const miSpectrum* s, miScalar w)

Evaluates spectrum s at wavelength w, where the wavelength is given in nanometers. If the given wavelength is outside the range of wavelengths associated with the spectrum, then a value of 0 is returned.

mi_spectrum_value_set
miScalar mi_spectrum_value_set(const miSpectrum* s, miScalar w, miScalar v)

Sets the value of spectrum s at wavelength w to the provided value v. Again, the wavelength is given in nanometers. If the given wavelength is outside the range of wavelengths associated with the spectrum, then no value is assigned to the spectrum. The routine returns the previous value of the spectrum at this wavelength.

mi_spectrum_value_add
miScalar mi_spectrum_value_add(const miSpectrum* s, miScalar w, miScalar v)

Adds to the value of spectrum s at wavelength w the provided value v. Again, the wavelength is given in nanometers. If the given wavelength is outside the range of wavelengths associated with the spectrum, then no value is added to the spectrum. The routine returns the previous value of the spectrum at this wavelength.

mi_spectrum_clear
void mi_spectrum_clear(const miSpectrum* s)

Sets all components of spectrum s to 0.

mi_spectrum_reset
void mi_spectrum_reset(miSpectrum* s)

Sets the passed in spectrum to the default spectrum.

mi_spectrum_delete
void mi_spectrum_delete(const miSpectrum* s)

Releases all resources associated with spectrums. After this call the contents of s are no longer available. Calls to interface routines that would acccess these contents will fail.

mi_spectrum_delete_fromheap
mi_spectrum_delete_fromheap(miSpectrum* s)

Releases all resources associated with spectrums. After this call the contents of s are no longer available. Calls to interface routines that would acccess these contents will fail. This routine is the counter part to mi_spectrum_create_inheap. It may only be used to release spectra that had been allocated with mi_spectrum_create_inheap. For all other spectra mi_spectrum_delete is the appropriate call.

mi_spectrum_ciexyz
miScalar mi_spectrum_ciexyz( miColor* c, const miSpectrum* s)

Computes the "CIE XYZ" coordinates of the spectrum s and writes them into the color c. The scalar value returned by the routine contains the unweighted integral of the spectrum.

Spectrum Iterators

Since it is not possible to access the spectrum components directly we need iterators to perform some manipulations on spectra.
mi_spectrum_iterator_create
miSpectrum_iterator* mi_spectrum_iterator_create(const miSpectrum* s, miScalar quality)

Returns a pointer to a spectrum iterator appropriate for spectrum s. The quality parameter may affect the number of spectra used begin the begin and the end of the iteratations performed. The value of the quality parameter is between 0 and 1.

mi_spectrum_iterator_destroy
void mi_spectrum_iterator_destroy(miSpectrum_iterator* iter)

Releases all resources associated with the iterator iter.

mi_spectrum_iterator_begin
miSpectrum* mi_spectrum_iterator_begin(miSpectrum_iterator* iter)

Returns a pointer to the first spectrum containing components used to iterate over the original spectrum used to generate the iterator iter. The contents of the returned spectrum pointer become invalid after a call to mi_spectrum_iterator_next.

mi_spectrum_iterator_next
miSpectrum* mi_spectrum_iterator_next(miSpectrum_iterator* iter)

Returns a pointer to the next spectrum in the list of spectra to be used to iterate over the spectrum passed to iterator iter during its construction. The returned pointer will usually reference the same memory as the pointer returned by the mi_spectrum_iterator_begin routine. Hence, the contents of the previous spectrum pointer of the iteration become invalid after a call to this routine. If the returned pointer is the same as the one obtained by the mi_spectrum_iterator_end routine, then the pointer will no refer to any valid spectrum and access to its contents is illegal.

mi_spectrum_iterator_end
miSpectrum* mi_spectrum_iterator_end(miSpectrum_iterator* iter)

Returns a pointer to a spectrum struct. This pointer will not reference valid data. Hence, it may only be used to compare against another spectrum pointer obtained from mi_spectrum_iterator_begin or mi_spectrum_iterator_next. If such a comparision yields equality, then no further iterations are required.

mi_spectrum_iterator_size
unsigned int mi_spectrum_iterator_size(void)

Yields the size occupied by a miSpectrum_iterator structure. This size does not inlcude the size of any spectra internally maintained by the iterator.

Copyright © 1986-2009 by mental images GmbH