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.
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.
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.
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.
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.
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.
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.
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.
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.
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".
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.
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.
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.
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.
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.
void mi_spectrum_(miSpectrum* s, const miSpectrum* in)
Copies the entire contents of the spectrum referenced by
in to the spectrum referenced by s.
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.
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.
void mi_spectrum_add(miSpectrum* s, const miSpectrum *in)
Adds to each component of the spectrum s the
corresponding component of the in spectrum.
void mi_spectrum_mul(miSpectrum* s, const miSpectrum *in)
Multiplies each component of the spectrum s with
the corresponding component of the in spectrum.
void mi_spectrum_scale(miSpectrum* s, Scalar scale)
Multiplies each component of the spectrum s with
scale.
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.
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.
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.
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.
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.
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.
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.
void mi_spectrum_clear(const miSpectrum* s)
Sets all components of spectrum s to 0.
void mi_spectrum_reset(miSpectrum* s)
Sets the passed in spectrum to the default spectrum.
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(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.
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.
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.
void mi_spectrum_iterator_destroy(miSpectrum_iterator* iter)
Releases all resources associated with the iterator
iter.
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.
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.
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.
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-2010 by mental images GmbH