Lights

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_OBJECT^3.1, and miLIGHT_USER^3.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 sources^3.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:

miSHADOWMAP_MERGE merge the shadowmap on disk with the one being computed. Not available for detail shadowmaps.
miSHADOWMAP_CAMERA there is a camera attached to the shadowmap.
miSHADOWMAP_DETAIL This is a detail shadowmap.
miSHADOWMAP_ONLY Only create shadowmaps, do not render. This is deprecated. Not available for detail shadowmaps.

dirlight_has_org^3.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.