| Element type: | miSCENE_LIGHT |
| Data type: | miLight |
| Sizes: | - |
| Defaults: | as described below |
enum miLight_type {
miLIGHT_ORIGIN,
miLIGHT_DIRECTION,
miLIGHT_SPOT
};
enum miLight_area {
miLIGHT_NONE = 0,
miLIGHT_RECTANGLE,
miLIGHT_DISC,
miLIGHT_SPHERE,
miLIGHT_CYLINDER,
miLIGHT_OBJECT,
miLIGHT_USER
};
typedef struct miLight {
enum miLight_type type; /* light type */
enum miLight_area area; /* area? */
miScalar exponent; /* global illum. 1/r^(2*exp)*/
unsigned int caustic_store_photons;/*caus.photons to store*/
unsigned int global_store_photons; /*glob. photons to store */
miColor energy; /* global illum. intensity */
miTag shader; /* light shader */
miTag emitter; /* photon emitter shader */
miVector origin; /* opt. origin */
miVector direction; /* opt. normalized direction */
float spread; /* size of spot? (cos angle) */
union {
struct miLight_rectangle rectangle;
struct miLight_disc disc;
struct miLight_sphere sphere;
struct miLight_cylinder cylinder;
struct miLight_object object;
} primitive; /* area primitive */
short samples_u; /* area u samples */
short samples_v; /* area v samples */
short low_samples_u; /* low area u samples */
short low_samples_v; /* low area v samples */
short low_level; /* switch to low at this lvl */
miUint1 shadowmap_flags; /* indicate shadow map modes */
miUint1 dirlight_has_org; /* infinite light with org? */
miBoolean use_shadow_maps; /* for this light */
miTag shadowmap_file; /* the shadow map file */
int shadowmap_resolution; /* resolution */
float shadowmap_softness; /* sample region size */
int shadowmap_samples; /* #samples */
miBoolean visible; /* visible? area lights only */
miUint label; /* light label */
miTag userdata; /* optional user data blocks */
unsigned int caustic_emit_photons; /* caus.photons to emit */
unsigned int global_emit_photons; /* glob. photons to emit */
miTag hardware; /* hardware light shader */
short shmap_h_min; /* not used */
short shmap_h_max; /* not used */
short shmap_v_min; /* not used */
short shmap_v_max; /* not used */
float transparent; /* experimental shmap feature */
miScalar shadowmap_bias; /* move shmap Z back by bias */
struct miLight_shmap shmap; /* shadowmap data */
int spare2[2]; /* not used */
} miLight;
struct miLight_shmap {
miTag camera; /* optional camera for shadow maps */
miScalar accuracy; /* detail shadow map min sample dist.*/
miScalar filter_u; /* currently only size 1 supported */
miScalar filter_v; /* currently only size 1 supported */
miSint2 samples; /* n*n samples per pixel */
miUchar filter; /* currently only box 'b' supported */
miUchar type; /* detail shadow map: color or alpha */
};
struct miLight_rectangle {
miVector edge_u;
miVector edge_v;
};
struct miLight_disc {
miVector normal;
miScalar radius;
};
struct miLight_sphere {
miScalar radius;
};
struct miLight_cylinder {
miVector axis;
miScalar radius;
};
struct miLight_object {
miTag object;
};
A translator must provide: type, shader,
origin and/or direction and spread
depending on type, all primitive fields for area light
sources.
type (default miLIGHT_ORIGIN) distinguishes between point lights (origin only), directional lights (direction only), and spot lights (origin, direction, and spread angle).
area (default miLIGHT_NONE describes the type of area light geometry, and is one of miLIGHT_NONE, miLIGHT_RECTANGLE, miLIGHT_DISC, miLIGHT_SPHERE, miLIGHT_CYLINDER, miLIGHT_OBJECT3.1, and miLIGHT_USER3.1.
exponent (default 2) controls the falloff of the light at a given distance. An exponent of 2 is physically correct, but other exponents can be chosen to make the light reach farther or less far than it should. An exponent of 1 means that the light energy does not fall off with distance. Exponents other than 2 disturb the energy balance in the scene.
caustic_store_photons is the maximum number of photons from this light source to store in the caustic photon map. If set to zero, the number of photons to emit must be specified, which then controls the number of emitted photons no matter how many are stored. (The zero value is supported in mental ray 2.1.,37 and later, earlier versions require setting it to a very high number.)
caustic_emit_photons is the maximum number of caustic photons to emit from this light source. Emission of caustic photons from a light stops when either caustic_store_photons or caustic_emit_photons has been reached.
global_store_photons is the maximum number of photons from this light source to store in the global illumination photon map. Again, a value of zero disables the store limit in mental ray 2.1.37 and later.
global_emit_photons is the maximum number of global illumination photons to emit from this light source. Emission of global illumination photons from a light stops when either globillum_store_photons (if nonzero) or globillum_emit_photons has been reached.
energy is the combined energy of all photons emitted by this light source.
shader (default miNULLTAG) is the tag of a database element of type miSCENE_FUNCTION containing the light shader, which computes illumination by this light at render time.
emitter (default miNULLTAG) is the tag of a database element of type miSCENE_FUNCTION containing the light photon emitter shader, which emits photons during the global illumination or caustics preprocessing phase.
origin (default 0, 0, 0) is the origin of the light in object space. It is used only if type is miLIGHT_ORIGIN or miLIGHT_SPOT.
direction (default 0, 0, 0) is the direction of a directional light. It is used only if type is miLIGHT_DIRECTION or miLIGHT_SPOT.
spread is used only by spot lights and it specifies the size of the outer spotlight cone.
primitive contains the size of the area light source if
area is not miLIGHT_NONE. Depending on
area, the width and height of the rectangle are given in
rectangle.edge_u and rectangle.edge_v, or the
orientation and radius of the disc are given in disc.normal
and disc.radius, or the radius of the sphere is given in
sphere.radius, or the axis and radius of the cylinder are
given in cylinder.axis and cylinder.radius. All
defaults are 0. For geometric area
light sources3.1,
primitive→object.object must be an instance that
references an object (not an object
group).
samples_u (default 3) is the number of samples taken in the U direction of the area light source if area is not miLIGHT_NONE.
samples_v (default 3) is the number of samples taken in the V direction of the area light source if area is not miLIGHT_NONE.
low_samples_u (default 2) is the number of samples taken in the U direction of the area light source if area is not miLIGHT_NONE, when the trace depth specified by low_level is reached or exceeded.
low_samples_v (default 2) is the number of samples taken in the V direction of the area light source if area is not miLIGHT_NONE, when the trace depth specified by low_level is reached or exceeded.
low_level (default 3) is the sum of the reflection and refraction trace depth at which area light sampling switches from samples to low_samples. 0 means that no switching takes place and samples are always used. Ignored for user area lights.
shadowmap_flags is a bitmap containing the following settings:
dirlight_has_org3.4 specifies whether the light is a directional light with origin or not.
use_shadow_maps specifies whether shadowmaps are used for this light source.
shadowmap_file is the tag of a string containing the filename for the shadowmap. If the tag is null, no file loading and saving will be done. For point lights and regular shadowmaps, six files will be generated, each with an identifying number (1…6) appended to the filename. If the file name contains the # character, it will be expanded to a hexadecimal number identifying the particular instance of this light. This allows different instances of a light to use different files.
shadowmap_resolution is the resolution of the shadowmap. For point lights, the individual images will have a lower resolution, so that the total number of pixels rendered will be approximately shadowmap_resolution × shadowmap_resolution.
shadowmap_softness when non-zero, enables soft shadows. The value given specifies the rectangular size of the region in the shadow map's projection plane in which samples are placed. If this parameter is 0 only one sample will be used, creating sharp shadows. The size is given in internal space units on the shadowmap projection plane.
shadowmap_samples is the number of samples taken from the shadowmap. When shadowmap_softness is zero, this value is ignored.
visible is miTRUE if the light should be seen in the rendering. This only applies to area light sources.
userdata allows attaching a user data block (miUserdata) or a chain of user data blocks. Shaders can retrieve the data with mi_query.
label is a numeric value assigned by applications.
hardware is the hardware light shader.
shadowmap_bias If this value is zero, then regular shadowmaps will use Woo's method for calculating the depth value for the shadow map. This value is calculated as an average of the two closest intersections. This amounts to using a different bias for each pixel in the shadowmap. If a bias value other than zero is specified, then regular shadowmaps will only use the depth of the closest intersection. The bias will then be subtracted from the ray depth before a shadowmap comparison is made. The bias will only be applied to the ray depth, the shadowmap will store the original intersection depths. This allows to use the same shadowmap in memory or on disk with varying bias values without recomputing the underlying shadowmap. Detail shadowmaps cannot use Woo's method, they always use a bias. If the bias value is set to zero, an internal method is used to compute a local bias. The numerical value of the bias is in internal units.
shmap This struct contains shadowmap information relevant to shadowmaps. The filter related members of this struct are currently not used, but are reserved for future extensions.
shmap.camera An optional camera that may be used for shadow map settings. If used, the miSHADOWMAP_CAMERA flag must be set.
shmap.accuracy Determines how far two depths values within a detail shadowmap need to be apart to be considered different. A value if zero indicates that mental ray should try to determine a reasonable value. The numerical value is in the same internal units as shadowmap_bias.
shmap.samples determines the number of samples per pixel for detail shadowmaps. If samples is set to n, then there will be n × n samples per pixel.
shmap.type selects whether detail shadowmaps should use colored shadows (value 'c') or shadow intensities (value 'a').
The remaining fields are reserved and should not be used.
Copyright © 1986, 2015 NVIDIA ARC GmbH. All rights reserved.