View source for VRAD

{{toc-right}}

'''VRAD''' is the [[command-line]] tool that compiles a map's [[lightmap]]s and per-leaf ambient lighting. It gives parts of the map, called patches, a certain amount of brightness depending on how much light it calculates it should receive.

==Speed==

VRAD is the generally the slowest of the three compilers due to the many, many calculations it must perform. [[Optimization (level design)|Map optimization]] can reduce the speed of this tool somewhat, especially reducing the number of unique names given to lights (which reduces the number of dynamic light combinations for which radiosity must be calculated).

If you are watching the compile dialog and it looks like it has hung at ''<code>9...</code>'' this is usually because Vrad takes longer with each light bounce calculation. Be patient.

==Options==
Use these in combination with [[expert compile mode]] or a batch file:

=== Effects ===

;<code>-both</code>
:Compiles lightmaps for both Low Dynamic Range and [[HDR|High Dynamic Range]] lighting models. Causes the compiler to run twice.
;<code>-ldr</code>
:Compile only LDR lightmaps.
;<code>-hdr</code>
:Compile only HDR lightmaps.
;<code>-fast</code>
: Quick and dirty lighting. Has been known to leave dark lines around displacements.
;<code>-final</code>
: Increases the quality of [[light_environment]] and indirect lighting by spending more time firing rays.
;<code>-lights <file></code>
:Load a custom [[#Lights_files|lights file]] in addition to <code>lights.rad</code> and map-specific lights file. The file specified must be <code><filename>.rad</code>.
;<code>-bounce #</code>
: Set the maximum number of light ray bounces (default: 10).
;<code>-smooth #</code>
:Set the threshold for [[smoothing group]]s, in degrees (default: 45).
;<code>-luxeldensity #</code>
:Scale down all luxels. Default (and maximum) value is 1.
;<code>-softsun <n></code>
:Treat the sun as an area light source of size <n> degrees. Produces soft shadows. Recommended values are between 0 and 5. Default is 0.
;<code>-StaticPropLighting</code>
:Generate per-vertex <code>[[prop_static]]</code> lighting. This is always enabled for [[light_spot]] entities.
:{{note|Depending on the number of static props in the level, this can dramatically increase the size of the .bsp file and the length of time needed for vrad to finish.}}
;{{EP2 add|<code>-StaticPropPolys</code>}}
:Perform shadow tests of <code>prop_static</code>s at polygon precision. ''('''Very''' processor-intensive - default is to use collision models.)''
;{{EP2 add|<code>-TextureShadows</code>}}
:Generates lightmap shadows from [[$translucent]] surfaces of models that are specified in a [[#Lights_files|lights file]] and being used with [[prop_static]]. Usually requires <code>-StaticPropPolys</code> to have any effect.
:{{note|A surface will need a low [[lightmap]] scale for most texture shadows to be recognisable.}}

=== Performance ===

;<code>-low</code>
:Run as an low-priority process. Allows you to use your computer for other things during compiles.
;<code>-threads</code>
:Control the number of threads used (defaults to the number of processors on your machine, doubled for CPUs with hyperthreading).
;<code>-mpi</code>
:Use [[Vmpi|VMPI]] to distribute computations.
;<code>-mpi_pw <pw></code>
:Use a password to choose a specific set of VMPI workers.
;<code>-noextra</code>
:Disable supersampling.
;<code>-chop</code>
:Smallest number of [[luxel]] widths for a bounce patch, used on edges.
;<code>-maxchop</code>
:Coarsest allowed number of luxel widths for a patch, used in face interiors.
;<code>-LargeDispSampleRadius</code>
:This can be used if there are splotches of bounced light on terrain. The compile will take longer, but it will gather light across a wider area.
;<code>-compressconstant <n></code>
:Compress [[lightmap]]s whose color variation is less than n units.

=== Debugging ===

;<code>-rederror</code>
:Emit bright red light from error locations?
;<code>-vproject <directory></code>
;<code>-game <directory></code>
:Override the VPROJECT environment variable.
;<code>v</code>
;<code>-verbose</code>
: Turn on verbose output.
;<code>-novconfig</code>
:Don't bring up graphical UI on vproject errors.
;<code>-dump</code>
:Write debugging .txt files.
;<code>-dumpnormals</code>
:Write normals to debug files.
;<code>-debugextra</code>
:Places debugging data in lightmaps to visualize supersampling.
;<code>-dlightmap</code>
:Force direct lighting into different lightmap than radiosity.
;<code>-stoponexit</code>
:Wait for a keypress on exit.
;<code>-nodetaillight</code>
:Don't light detail props.
;<code>-centersamples</code>
:Move sample centers.
;<code>-loghash</code>
:Log the sample hash table to samplehash.txt.
;<code>-onlydetail</code>
:Only light detail props and per-leaf lighting.
;<code>-maxdispsamplesize #</code>
:Set max displacement sample size (default: 512).
;<code>-FullMinidump</code>
:Write large minidumps on crash.
;<code>-OnlyStaticProps</code>
:Only perform direct static prop lighting (vrad debug option)
;<code>-StaticPropNormals</code>
:When lighting static props, just show their normal vector

==Lights files==

A light file is a plain text file that can be used to manipulate the way [[Vrad|VRAD]] handles given [[material]]s when compiling static lighting. All lights files must have the .rad file extension and must be in the same folder as your [[gameinfo.txt]].

There are:

#'''<code>light.rad</code>''', the global file.
#'''An auto-loaded map light file''', using the format <code><map name>.rad</code>.
#'''Any number of additional lights files''' that can be added with [[#Effects|the <code>-lights</code> parameter]].

=== Rules ===

Lights files perform these functions, one rule per line:

;<code><material> <red> <green> <blue> <intensity> <hdr_red> <hdr_green> <hdr_blue> <hdr_intensity></code>
:Makes the material emit the given light value when applied to a [[brush]] face (<code>hdr_</code> values are optional). Texture scale has an effect on final intensity. {{note|materials that aren't in a folder must have a slash before their name.}}
;<code>noshadow <material name></code>
:Prevents the named material from casting shadows.
;<code>forcetextureshadow <model name>.mdl</code>
:Enables translucency shadow testing for a model when VRAD is run with <code>[[#Effects|-TextureShadows]]</code>.
;<code><nowiki>ldr:</nowiki></code>
;<code><nowiki>hdr:</nowiki></code>
:Prefixes to make any rule only apply to LDR or HDR lighting.

==See also ==
* [[Map Compiling Theory]]
* [[HDR Lighting Basics]]
* [[Vbsp|VBSP]]
* [[Vvis|VVIS]]

[[Category:Tools]]
[[Category:Level Design]]
[[Category:Glossary]]