"environment"
Class	Light
Synopsis	Uses environment map to light scene (for Image Based Lighting).
Arguments	"intensity" Type: LtFloat Default: 1.0 Range: [ 0, inf ] Hint: - "intensity units" Type: LtEnum Default: LI_INTEN_UNITS_EMPIRICAL Range: 0, 5, 6, 8 Hint: - "shadows" Type: LtBoolean Default: FALSE Range: - Hint: - "shadow type" Type: LtEnum Default: LI_SHADOW_TYPE_HARD Range: 1, 2 Hint: - "shadow transparency" Type: LtBitfield Default: LI_TRANS_SHADOW_GLOBAL Range: 15 Hint: - "shadow acceleration" Type: LtBitfield Default: LI_SHADOW_ACC_NONE Range: 31 Hint: - "shadow resolution" Type: LtInt32 Default: 256 Range: [ 0, 8000 ] Hint: [ 50, 2048 ] "shadow quality" Type: LtInt32 Default: 4 Range: [ 1, 16 ] Hint: [ 4, 9 ] "shadow softness" Type: LtFloat Default: 1.0 Range: [ 0.1, 20 ] Hint: [ 1, 4 ] "shadow tolerance" Type: LtFloat Default: 0.0 Range: [ 0, 1 ] Hint: [ 0, 0.1 ] "number of samples" Type: LtNat32 Default: 10 Range: [ 1, 8000 ] Hint: [ 10, 2000 ] "noise factor" Type: LtFloat Default: 0 Range: [ 0, 1 ] Hint: - "use global environment" Type: LtBoolean Default: TRUE Range: - Hint: - "environment" Type: LtInterface Default: LI_NULL_INTERFACE Range: 16, 111 Hint: - "use upper hemisphere only" Type: LtBoolean Default: FALSE Range: - Hint: - "saturation" Type: LtFloat Default: 0.0 Range: [ -1, 1 ] Hint: - "lighting components" Type: LtBitfield Default: LI_LIGHTING_COMPONENT_GATHER_DIRECT Range: - Hint: -
Location	lishpro
Description	A light shader that uses an environment map to light a scene. By default the environment map used is the one set as the current scene's environment map (i.e., set using LiEnvironmentSet when using core~LightWorks or the environment entity attached to the current scene entity when using Session Manager)---in other words the same one which would be used by the "environment" reflectance shader. This environment map (when "use global environment" is TRUE) or the local environment described via the "environment" argument (when "use global environment" is FALSE) is used to produce a temporary environment map with panorama layout used to light the scene. This shader is designed to be used mainly with HDRI (High Dynamic Range Image) images ( .exr, .hdr), but will also work with standard (low dynamic range) images (such as .jpg, .tif, .lwi, etc.). The brightness of images used as environment map may vary. To adjust the brightness of the scene being rendered, use the argument "intensity". By default this has the value 1.0; the best value for this parameter should be found empirically. The same "intensity" for different environment maps may vary from correct to completely inappropriate. Larger values make rendered images brighter, lower make them dimmer. The default value should give more of less correct results and it is a good starting point for adjusting. When a rendered image is too dark (even black) or too bright (almost white) this is the first place which should be checked. Changing "number of samples" makes the lighting more accurate but doesn't change an overall image brightness. Note that when using regular (low dynamic range) images, setting inappropriate values of "intensity" (too small or too big) can result in the loss of certain subtle lighting effects. The brightness of the scene can be specified in either non-physical, `empirical' units , or by physically accurate units of light intensity (such as lux or candela) as used by the lighting industry (this is especially useful when using HDRI images prepared using such units; for example some lighting manufacturers may provide physically accurate HDRI images). The "noise factor" allows users to exchange sampling artifacts for noise, when using hard shadows. This parameter gives the possibility to make shadow boundaries less visible. Its default value of 0.0 means that no jittering of visibility rays takes place. A value of 1.0 means that all visibility rays undergo jittering. Intermediate values result in some rays being jittered, and others not. The argument "intensity units" is used to specify what units the argument "intensity" is given in. By default the units are assumed to be empirical (arbitrary) units. The full list of possible values for "intensity units" for this light shader is: LI_INTEN_UNITS_EMPIRICAL---Intensity specified in arbitrary empirical units (the default) LI_INTEN_UNITS_LUX---Intensity specified in Lux LI_INTEN_UNITS_KILOLUX---Intensity specified in Kilolux LI_INTEN_UNITS_FOOTCANDLE---Intensity specified in Footcandles The "shadows" argument specifies whether or not the sky will cast shadows on the scene. The argument "shadow type" is used to specify whether hard-edged shadows or soft-edged shadows are created. By default the value of this parameter is LI_SHADOW_TYPE_HARD for this shader (and also for "simple sky"), whereas it is LI_SHADOW_TYPE_SOFT for "distant" (and most other lights). The reason for this is that calculating a large number of shadow maps can take some time, prior to rendering (and quickly use up memory). If transparent objects make up part of the scene, then the "shadow transparency" argument can be utilized to ensure that appropriate shadows result. A value of 0 means that the light will not cast transparent shadows. The default "shadow transparency" value is LI_TRANS_SHADOW_GLOBAL, which means that the shader will look at the value of LI_CONTROL_TRANSPARENT_SHADOW when deciding whether to cast transparent shadows. Three other "shadow transparency" values are possible: LI_TRANS_SHADOW_ON -- switch on most basic functionality LI_TRANS_SHADOW_INTERPOLATE -- switch on more advanced functionality, for those blockers whose transparency shaders require the initialisation of more than the default set of shader globals. LI_TRANS_SHADOW_DISPLACEMENT -- switch on most advanced functionality, for those blockers whose transparency shaders include effects due to displacement. When choosing either of the last two options, ensure that the LI_TRANS_SHADOW_ON bit is also set. It is also possible to make use of a previously generated shadow map to speed up calculation of hard-edged (ray cast) shadows. In order to do this, the "shadow acceleration" argument should be set to LI_SHADOW_ACC_MAPS. By default this argument is set to LI_SHADOW_ACC_NONE, meaning no such acceleration is performed. The quality of the shadows is specified by "shadow quality": a value of 1 corresponds to low quality, and a larger value such as 9 gives higher quality. A value that determines how soft the boundaries of shadows appear is specified in argument "shadow softness". The "number of samples" argument provides an easy to understand and predictable trade-off between accuracy and speed. The actual number of generated lights can be a bit smaller than requested by this parameter. It is a consequence of used algorithm which skips insignificant light sources. Important fact is that setting the very small "number of samples" (below 10) in some cases may cause all light sources from an environment map to be treated as insignificant. In consequence an image appears unlit. This can be corrected by increasing the number of samples. By default the whole environment is sampled, thus, the scene is lit from all directions. This may be changed by setting "use upper hemisphere only" argument to TRUE resulting in sampling of only the upper hemisphere of the environment. This option may be useful if you don't want geometry of your scene to be lit from below by the environemnt e.g. you may have an environment map depicting a meadow applied to a geometry of a car on a road in which case you wouldn't like the car to be lit by the green grass. However, in most cases that shouldn't be a problem because usually environment maps contain only a few dominating light sources like the sun or lamps and illumination from other parts is quite weak contributing mostly to the amibient light and such places are not creating shadows. Additionally, in the described example you could set geometry of the road to be double sided which would make is block the lights which are below the car. If the "use global environment" is TRUE then the shader uses the global environment (returned by LiEnvironmentGet) to create a panoramic image, otherwise the local environment (described by the "environment" argument) is used to create a panoramic image. The "environment" argument is an LtInterface. It is used to produce an environment map when "use global environment" is FALSE. New! The "lighting components" argument is a bitfield which allows the end user to specify how the contribution of a `dome' light (i.e., a "sky", "simple sky", "environment" or "simple environment" light) should be modelled, during any final gather processing: GATHER_DIRECT: Model the dome light's direct contribution using the final gather module. So, when a final gather sample ray misses all the geometry in the scene, establish how bright (and what colour) the dome light is, in that direction, and return that radiance. If, for a particular final gather sample point, many such rays miss all the geometry in the scene, a correspondingly bright 'sky' contribution will result. If most sample rays hit opaque geometry in the scene, then the 'sky' contribution will be small. When it comes to visiting each light source shader, for a given shading point, the dome light will be ignored, since its contribution has already come via the final gather plugin light. Sampling artifacts are avoided, in this way. The dome lights can thus benefit from the speed/quality trade-off which the final gather method offers. The fastest renders come from setting this bit, but not setting the ... INDIRECT bit. GATHER_INDIRECT: Model the dome light's indirect contribution using the final gather module. So, when final gathering on the ceiling of a room, spray out sample rays to find the floor and walls and so on, and establish how the dome light illuminates each of these points using the dome light's own parameters. So the dome source will bounce light of the floor and walls, onto the ceiling, where it is captured by the final gather module. Illuminating any point with a dome light can be expensive, so it is worth noting that a very coarse illumination is probably enough for the final gather to do a good job. Whilst such settings would produce a very poor render, if used in the absence of the irradiance cache, they are usually perfectly adequate for indirect illumination: shining a mud-splattered torch onto a white wall might give a circle of light containing lots of dots and splashes, but the ceiling that receives the indirect contribution will show so such artifacts. The same process works here. See section~\ref{globillum:concepts:fg:domelights:section} of the `Light Sourceingman' manual. The highest quality renders come from setting this bit, and setting the ... DIRECT bit. USE_GLOBAL: Look to the "domelight components" parameter of the parent object (whether that is the { "final gather"} render style, or the "final gather controller" interface) to decide what to do. The { "domelight components"} parameter can take either of the 2 bits outlined above. It allows global control over the { "lighting components"} of any dome lights that happen to be in use. Perhaps there is an archive of dome lights, all of which have "lighting components" set to {\bf USE_GLOBAL}... the user can they explore different settings and light sources, without having to constantly mess with the individual lights. Previous page alphabetically (environment) Next page alphabetically (envmapbackground) Index
Copyright © 1990-2005, 2006 LightWork Design Limited. All rights reserved