Drake
Drake C++ Documentation
RenderEngineVtkParams Struct Reference

Detailed Description

Construction parameters for the RenderEngineVtk.

#include <drake/geometry/render_vtk/render_engine_vtk_params.h>

Public Member Functions

template<typename Archive >
void Serialize (Archive *a)
 Passes this object to an Archive. More...
 

Public Attributes

std::optional< Eigen::Vector4d > default_diffuse {}
 The (optional) rgba color to apply to the (phong, diffuse) property when none is otherwise specified. More...
 
Eigen::Vector3d default_clear_color {204 / 255., 229 / 255., 255 / 255.}
 The rgb color to which the color buffer is cleared (each channel in the range [0, 1]). More...
 
std::vector< render::LightParameterlights
 Lights in the scene. More...
 
std::optional< EnvironmentMapenvironment_map
 An optional environment map. More...
 
std::optional< doubleexposure {}
 Exposure is an aspect of "tone mapping" (as described in VTK's description of its PBR capabilities). More...
 
bool cast_shadows {false}
 If true, all lights that are able to cast shadows will do so. More...
 
int shadow_map_size {256}
 The size of texture map (in pixels) to use for shadow maps. More...
 
string_map< GltfExtensiongltf_extensions
 Map from the name of a glTF extension (e.g., "KHR_materials_sheen") to render engine settings related to that extension. More...
 

Member Function Documentation

◆ Serialize()

void Serialize ( Archive *  a)

Passes this object to an Archive.

Refer to YAML Serialization for background.

Member Data Documentation

◆ cast_shadows

bool cast_shadows {false}

If true, all lights that are able to cast shadows will do so.

Several important notes when designing your lighting:

- Point lights do not cast shadows.
- Directional lights will create a shadow map that spans the whole scene.
  If your scene includes a geometry that is significantly larger than
  the locale you're rendering, this will significantly reduce the
  efficacy of the directional light's shadows. Consider truncating that
  larger geometry. A common case would be to use a HalfSpace to define
  a ground. A half space has infinite extent, so any reasonable
  approximation would be quite large. Better to use a box targeted to
  where you need it.
- Transparent objects cast no shadows at all, but they do receive them.

Currently, there is no way to enable/disable shadows on a per-light basis.

◆ default_clear_color

Eigen::Vector3d default_clear_color {204 / 255., 229 / 255., 255 / 255.}

The rgb color to which the color buffer is cleared (each channel in the range [0, 1]).

The default value (in byte values) would be [204, 229, 255].

◆ default_diffuse

std::optional<Eigen::Vector4d> default_diffuse {}

The (optional) rgba color to apply to the (phong, diffuse) property when none is otherwise specified.

Note: currently the alpha channel is unused by RenderEngineVtk.

◆ environment_map

std::optional<EnvironmentMap> environment_map

An optional environment map.

When providing the environment map, the render engine will be configured for physically-based rendering (PBR); all materials will be promoted to be a PBR material. This may change the appearance of any geometries introduced as primitives or .obj meshes.

Furthermore, if an environment map is specified, it replaces the default lighting (the map itself illuminates the scene). The usual camera head lamp will not be present. Lights can be explicitly added to combine with the environment map.

◆ exposure

std::optional<double> exposure {}

Exposure is an aspect of "tone mapping" (as described in VTK's description of its PBR capabilities).

Drake uses the GenericFilmic tone mapper and this value maps to its exposure property.

By default, exposure is undefined and no tone mapping is applied to the image. Providing any value at all will enable tone mapping and can be done so whether your scene uses default Phong illumination model or physically-based rendering (e.g., such as when an environment map is present or a glTF model has been added).

This property is analogous to the concept of "exposure" in traditional photography. Exposure controls how much the film material is exposed to the light in the scene. Too little exposure and the scene is dark and muddy. Too much exposure, and the image becomes over saturated. As the amount of radiant energy in the scene increases, reducing the exposure may be necessary. In essence, exposure serves as a scale factor on the radiant energy. When thinking about it as a scale factor, it may seem that setting exposure to one would leave the image unchanged (with respect to the images that RenderEngineVtk has historically produced). This is not the case. As noted above, setting any value, including one, enables tone mapping. Without tone mapping enabled, there is a direct correlation between radiant energy on the surface and the final pixel colors. Tone mapping defines a non-linear relationship between illumination levels and pixel color.

The most common use for the exposure parameter is to combine an environment map with shadow-casting lights. If the environment map contains a great deal of light energy, it may overpower the strength of your lights. By reducing the exposure (below one), the shadows caused by the lights will become more distinct.

If you plan on working with shadows and environment maps, best practice will be to set exposure to one and enable tone mapping. You can increase the value if your image seems too dark, or reduce the value if it seems "washed out".

◆ gltf_extensions

string_map<GltfExtension> gltf_extensions
Initial value:
{
{"KHR_texture_basisu", {.warn_unimplemented = false}},
}

Map from the name of a glTF extension (e.g., "KHR_materials_sheen") to render engine settings related to that extension.

◆ lights

std::vector<render::LightParameter> lights

Lights in the scene.

If no lights are defined, a single directional light, fixed to the camera frame, is used.

Note: RenderEngineVtk does not have a hard-coded limit on the number of lights; but more lights increases rendering cost. Note: the attenuation values have no effect on VTK directional lights.

◆ shadow_map_size

int shadow_map_size {256}

The size of texture map (in pixels) to use for shadow maps.

Note: this is a global setting. All shadow casting lights will use a map of the same size. Larger map sizes increase GPU memory usage and rendering times but improve shadow fidelity (less obvious pixelation).

See the note on cast_shadows for the warning on directional lights and shadow maps.


The documentation for this struct was generated from the following file: