---
title: "Dome Light"
canonical: "https://documentation.chaos.com/space/APPSDK/132781101/Dome%20Light"
format: markdown
---
In this chapter we'll cover slightly more complex light source in V-Ray - the dome light. It represents a light emitting dome encompassing the scene at infinity. It's usually used for HDR image based lighting (IBL) with a spherical texture file.
## **Parameters**
---
Along with the common ones for the lights, the *LightDome* plugin has some specific parameters:
- **dome_spherical** - Set to true to extend the dome to a full sphere. By default it is only a half-dome centered at the scene zenith. SettingsUnitsInfo::scene_upDir needs to be properly set.
- **dome_tex** - A texture plugin to use. Note that this usually requires spherical mapping.
- **use_dome_tex** - You also have to set this to true to use the dome_tex.
- **tex_resolution** - The texture is actually resampled at this resolution. The default is 512, so even if you have a high resolution image, it may look pixelated if you don't increase this. This will consume more memory.
- **dome_targetRadius** - Defines a sphere around the light icon where photons are being shot when photon-mapped caustics or the global photon map are used.
- **dome_emitRadius** - Defines a sphere around the light icon from which photons are being shot towards the target radius area.
- **tex_adaptive** - The adaptivity of the sampling to the texture brightness (0.0 - no adaptivity; 1.0 - full adaptivity).
- **dome_rayDistance** - Allows you to specify the maximum distance to which shadow rays are going to be traced.
- **dome_rayDistanceMode** - Specifies the method of determining the maximum distance to which shadow rays are going to be traced. Could be 0: **None**, 1: **From GI Settings** (the Ray Dist value is determined by the ray distance parameter in the GI settings) and 2: **Explicit** (the ray distance value is determined by the *dome_rayDistance* parameter).
- **affect_alpha** - When this option is enabled, the virtual sphere on which the dome texture is mapped is going to be visible as a solid object in the alpha.
> ℹ️ For the full list of parameters, please refer to the **LightDome **plugin description in [API Reference Guides](https://docs-chaos.atlassian.net/wiki/spaces/APPSDK/pages/132644997).
## **Example**
---
Here we'll show how to add a *LightDome* to a scene.
Python
```python
# Compatibility with Python 2.7.
from __future__ import print_function
# The directory containing the vray shared object should be present in the PYTHONPATH environment variable.
# Try to import the vray module from VRAY_SDK/python, if it is not in PYTHONPATH
import sys, os
VRAY_SDK = os.environ.get('VRAY_SDK')
if VRAY_SDK:
sys.path.append(os.path.join(VRAY_SDK, 'python'))
import vray
SCENE_PATH = os.path.join(os.environ.get('VRAY_SDK'), 'scenes')
# Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
os.chdir(SCENE_PATH)
# The renderer is automatically closed after the `with` block.
with vray.VRayRenderer() as renderer:
# Register a simple log callback. Always useful for debugging.
def dumpMsg(renderer, message, level, instant):
if level == vray.LOGLEVEL_ERROR:
print("[ERROR]", message)
elif level == vray.LOGLEVEL_WARNING:
print("[Warning]", message)
elif level == vray.LOGLEVEL_INFO:
print("[info]", message)
# Uncomment for testing, but you might want to ignore these in real code
#else: print("[debug]", message)
renderer.setOnLogMessage(dumpMsg)
# Load scene from a file.
renderer.load(os.path.join(SCENE_PATH, 'lighting.vrscene'))
# Remove original light source from the scene.
del renderer.plugins["VRayLightDomeShape1"]
# The UVWGenEnvironment allows spherical, cube, etc. textures to be
# mapped on the environment color slot or dome lights.
uvwgen = renderer.classes.UVWGenEnvironment()
# Specify the type and shape of the texture.
# Possible values are:
# angular
# cubic
# mirror_ball
# spherical - default
# screen
# max_spherical
# spherical_vray
# max_cylindrical
# max_shrink_wrap
uvwgen.mapping_type = 'spherical'
# Specify transformation of the input directions.
uvwgen.uvw_matrix = vray.Matrix(
vray.Vector(1, 0, 0),
vray.Vector(0, 0, 1),
vray.Vector(0, -1, 0))
uvwgen.ground_on = 1
bitmap = renderer.classes.BitmapBuffer()
# unlike JPG files, HDR files are linear
bitmap.transfer_function = 0
bitmap.file = os.path.join(SCENE_PATH, 'assets', 'Sea_D.hdr')
texture = renderer.classes.TexBitmap()
# Specify UVW generator for the texture.
texture.uvwgen = uvwgen
# Specify the bitmap that the texture will be using.
texture.bitmap = bitmap
# LightDome is a light source plugin that can be used to create lights that
# shine inward at the scene as if from a spherical or hemispherical light source outside the scene extents.
# This light is frequently used for image-based lighting using panoramic HDR images used as environments.
light = renderer.classes.LightDome()
# Specify the light position, rotation and scale.
light.transform = vray.Transform(
vray.Matrix(
vray.Vector(0, 0, 1),
vray.Vector(1, 0, 0),
vray.Vector(0, 1, 0)),
vray.Vector(0, 0, 0))
# Switches between a hemispherical or (full) spherical shape of the light.
# Possible values are:
# True (Sphere)
# False (Hemisphere)
light.dome_spherical = True
# Specify the light intensity based on the 'units' parameter.
light.intensity = 4
# Specify the light texture.
light.dome_tex = texture
# Enable the use of a light texture.
# If "use_dome_tex = False" the 'color' of the light will be used instead.
light.use_dome_tex = True
# Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
light.shadowBias = 0.02
# Specify that the bumped normal should be used to check if the light direction is below the surface.
light.bumped_below_surface_check = True
# Start rendering.
renderer.startSync()
# Wait for rendering to end.
renderer.waitForRenderEnd()
```
C++
```c++
#define VRAY_RUNTIME_LOAD_PRIMARY
#include "vraysdk.hpp"
#include "vrayplugins.hpp"
#include "utils.h"
using namespace VRay;
using namespace VRay::Plugins;
using namespace std;
const char *BASE_PATH = getenv("VRAY_SDK");
string SCENE_PATH = (BASE_PATH ? string(BASE_PATH) : string(".")) + PATH_DELIMITER + "scenes";
int main() {
// Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
changeCurrentDir(SCENE_PATH.c_str());
// Load V-Ray SDK library.
VRayInit init(NULL, true);
// Create an instance of VRayRenderer with default options. The renderer is automatically closed at the end of the current scope.
VRayRenderer renderer;
// It's recommended to always have a console log
renderer.setOnLogMessage(logMessage);
// Load scene from a file.
renderer.load("lighting.vrscene");
// Remove original light source from the scene.
renderer.deletePlugin("VRayLightDomeShape1");
// The UVWGenEnvironment allows spherical, cube, etc.textures to be mapped on the environment color slot or dome lights.
UVWGenEnvironment uvwgen = renderer.newPlugin();
// Specify the type and shape of the texture.
// Possible values are:
// angular
// cubic
// mirror_ball
// spherical - default
// screen
// max_spherical
// spherical_vray
// max_cylindrical
// max_shrink_wrap
uvwgen.set_mapping_type("spherical");
// Specify transformation of the input directions.
uvwgen.set_uvw_matrix(
Matrix(
Vector(1.0, 0.0, 0.0),
Vector(0.0, 0.0, 1.0),
Vector(0.0, -1.0, 0.0)));
uvwgen.set_ground_on(1);
BitmapBuffer bitmap = renderer.newPlugin();
// unlike JPG files, HDR files are linear
bitmap.set_transfer_function(0);
bitmap.set_file("assets/Sea_D.hdr");
TexBitmap texture = renderer.newPlugin();
// Specify UVW generator for the texture.
texture.set_uvwgen(uvwgen);
// Specify the bitmap that the texture will be using.
texture.set_bitmap(bitmap);
// LightDome is a light source plugin that can be used to create lights that
// shine inward at the scene as if from a spherical or hemispherical light source outside the scene extents.
// This light is frequently used for image-based lighting using panoramic HDR images used as environments.
LightDome light = renderer.newPlugin();
// Specify the light position, rotation and scale.
light.set_transform(Transform(
Matrix(
Vector(0.0, 0.0, 1.0),
Vector(1.0, 0.0, 0.0),
Vector(0.0, 1.0, 0.0)),
Vector(0.0, 0.0, 0.0)));
// Switches between a hemispherical or (full) spherical shape of the light.
// Possible values are:
// true (Sphere)
// false (Hemisphere) - default
light.set_dome_spherical(true);
// Specify the light intensity based on the 'units' parameter.
light.set_intensity(4);
// Specify the light texture.
light.set_dome_tex(texture);
// Enable the use of a light texture.
// If "use_dome_tex = false" the 'color' of the light will be used instead.
light.set_use_dome_tex(true);
// Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
light.set_shadowBias(0.02f);
// Specify that the bumped normal should be used to check if the light direction is below the surface.
light.set_bumped_below_surface_check(true);
// Start rendering.
renderer.startSync();
// Wait for rendering to end.
renderer.waitForRenderEnd();
return 0;
}
```
C#.NET
```csharp
using System;
using System.IO;
using VRay;
using VRay.Plugins;
namespace _04_dome
{
class Program
{
static void Main(string[] args)
{
string SCENE_PATH = Path.Combine(Environment.GetEnvironmentVariable("VRAY_SDK"), "scenes");
// Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
Directory.SetCurrentDirectory(SCENE_PATH);
// Create an instance of VRayRenderer with default options. The renderer is automatically closed after the `using` block.
using (VRayRenderer renderer = new VRayRenderer())
{
// Add a listener for any type of log message.
renderer.LogMessage += new EventHandler((source, e) =>
{
// You can remove the if for testing, but you might want to ignore Debug in real code
if (e.LogLevel != LogLevelType.Debug)
{
Console.WriteLine(String.Format("[{0}] {1}", e.LogLevel.ToString(), e.Message));
}
});
// Load scene from a file.
renderer.Load("lighting.vrscene");
// Remove original light source from the scene.
renderer.DeletePlugin("VRayLightDomeShape1");
// The UVWGenEnvironment allows spherical, cube, etc. textures to be mapped on the environment color slot or dome lights.
UVWGenEnvironment uvwgen = renderer.NewPlugin();
// Specify the type and shape of the texture.
// Possible values are:
// angular
// cubic
// mirror_ball
// spherical - default
// screen
// max_spherical
// spherical_vray
// max_cylindrical
// max_shrink_wrap
uvwgen.MappingType = "spherical";
// Specify transformation of the input directions.
uvwgen.UvwMatrix = new Matrix(
new Vector(1, 0, 0),
new Vector(0, 0, 1),
new Vector(0, -1, 0));
uvwgen.GroundOn = 1;
BitmapBuffer bitmap = renderer.NewPlugin();
// unlike JPG files, HDR files are linear
bitmap.TransferFunction = 0;
bitmap.File = Path.Combine("assets", "Sea_D.hdr");
TexBitmap texture = renderer.NewPlugin();
// Specify UVW generator for the texture.
texture.Uvwgen = uvwgen;
// Specify the bitmap that the texture will be using.
texture.Bitmap = bitmap;
// LightDome is a light source plugin that can be used to create lights that
// shine inward at the scene as if from a spherical or hemispherical light source outside the scene extents.
// This light is frequently used for image-based lighting using panoramic HDR images used as environments.
LightDome light = renderer.NewPlugin();
// Specify the light position, rotation and scale.
light.Transform = new Transform(
new Matrix(
new Vector(0, 0, 1),
new Vector(1, 0, 0),
new Vector(0, 1, 0)),
new Vector(0, 0, 0));
// Switches between a hemispherical or (full) spherical shape of the light.
// Possible values are:
// true (Sphere)
// false (Hemisphere)
light.DomeSpherical = true;
// Specify the light intensity based on the 'units' parameter.
light.Intensity = 4;
// Specify the light texture.
light.DomeTex = texture;
// Enable the use of a light texture.
// If "use_dome_tex = False" the 'color' of the light will be used instead.
light.UseDomeTex = true;
// Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
light.ShadowBias = 0.02F;
// Specify that the bumped normal should be used to check if the light direction is below the surface.
light.BumpedBelowSurfaceCheck = true;
// Specify the number of parameter samples for motion blur.
light.Nsamples = 1;
// Start rendering.
renderer.StartSync();
// Wait for rendering to end.
renderer.WaitForRenderEnd();
}
}
}
}
```
Node.js
```javascript
var path = require('path');
var vray = require(path.join(process.env.VRAY_SDK, 'node', 'vray'));
var SCENE_PATH = path.join(process.env.VRAY_SDK, 'scenes');
// Change process working directory to SCENE_PATH in order to be able to load relative scene resources.
process.chdir(SCENE_PATH);
// Create an instance of VRayRenderer with default options.
var renderer = vray.VRayRenderer();
// It's recommended to always have a console log callback
renderer.on("logMessage", function(message, level, instant) {
if (level == vray.LOGLEVEL_ERROR)
console.log("[ERROR] ", message);
else if (level == vray.LOGLEVEL_WARNING)
console.log("[Warning] ", message);
else if (level == vray.LOGLEVEL_INFO)
console.log("[info] ", message);
// Uncomment for testing, but you might want to ignore these in real code
//else console.log("[debug] ", message);
});
// Load scene from a file asynchronously.
renderer.load("lighting.vrscene", function(err) {
if (err) throw err;
// Remove original light source from the scene.
delete renderer.plugins["VRayLightDomeShape1"];
// The UVWGenEnvironment allows spherical, cube, etc. textures to be mapped on the environment color slot or dome lights.
var uvwgen = renderer.classes.UVWGenEnvironment();
// Specify transformation of the input directions.
uvwgen.uvw_matrix = vray.Matrix(
vray.Vector(1, 0, 0),
vray.Vector(0, 0, 1),
vray.Vector(0, -1, 0));
uvwgen.ground_on = 1;
// Specify the type and shape of the texture.
// Possible values are:
// angular
// cubic
// mirror_ball
// spherical - default
// screen
// max_spherical
// spherical_vray
// max_cylindrical
// max_shrink_wrap
uvwgen.mapping_type = "spherical";
var bitmap = renderer.classes.BitmapBuffer();
// unlike JPG files, HDR files are linear
bitmap.transfer_function = 0;
bitmap.file = path.join(SCENE_PATH, "assets", "Sea_D.hdr");
var texture = renderer.classes.TexBitmap();
// Specify UVW generator for the texture.
texture.uvwgen = uvwgen;
// Specify the bitmap that the texture will be using.
texture.bitmap = bitmap;
// LightDome is a light source plugin that can be used to create lights that
// shine inward at the scene as if from a spherical or hemispherical light source outside the scene extents.
// This light is frequently used for image-based lighting using panoramic HDR images used as environments.
var light = renderer.classes.LightDome();
// Specify the light position, rotation and scale.
light.transform = vray.Transform(
vray.Matrix(
vray.Vector(0, 0, 1),
vray.Vector(1, 0, 0),
vray.Vector(0, 1, 0)),
vray.Vector(0, 0, 0));
// Switches between a hemispherical or (full) spherical shape of the light.
// Possible values are:
// true (Sphere)
// false (Hemisphere)
light.dome_spherical = true;
// Specify the light intensity based on the 'units' parameter.
light.intensity = 4;
// Specify the light texture.
light.dome_tex = texture;
// Enable the use of a light texture.
// If "use_dome_tex = false" the 'color' of the light will be used instead.
light.use_dome_tex = true;
// Specify shadow offset from the surface. Helps to prevent polygonal shadow artifacts on low-poly surfaces.
light.shadowBias = 0.02;
// Specify that the bumped normal should be used to check if the light direction is below the surface.
light.bumped_below_surface_check = true;
// Start rendering.
renderer.start(function(err) {
if (err) throw err;
// Wait for rendering to end.
renderer.waitForRenderEnd(function() {
renderer.close();
});
});
});
```
## **Result**
---
The scene used for this render is called "Lighting_Dome.vrscene" and can be found in the [scene bundle](https://drive.google.com/file/d/1Wdp9M2AO-YcoPbBwiF0MAPKsDm5AxVqw/view?usp=sharing) (comments on the different parameters available inside).
> ⚠️ To test this locally, you'll need to change the absolute path to the dome texture (located in the included scene: "vrscenes/light_dome.vrscene").