VRAD: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(→‎Debugging: Option -rederrors : Appears as "rederror" in VRAD help but "rederrors" in the code.)
(various tweaks)
Line 1: Line 1:
{{toc-right}}
{{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.
'''VRAD''' is the [[command-line]] tool that takes a compiled BSP map and embeds lighting data into it. VRAD's static and pre-compiled light is bounced around the world with a [[Wikipedia:Radiosity (3D computer graphics)|radiosity]] algorithm.


==Speed==
VRAD will:


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).
* Generate [[lightmap]]s
* Generate [[Ambient light|ambient samples]]
* Generate per-object or per-vertex [[prop_static]] and [[detail prop]] lighting


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.
VRAD is the generally the slowest of the three compilers due to the many, many calculations it must perform. [[Lighting optimization]] can help, as can ensuring your map is free of [[leak]]s.
 
{{tip|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.}}
 
{{bug|Ep1 and L4D users seeing crashes when VRAD compiles HDR lighting should read [[VRAD HDR Crash Fix]].}}
 
== Syntax ==
 
vrad [options...] <bsp file>
 
For example:
 
"%sourcesdk%\bin\orangebox\bin\vrad" -both -StaticPropLighting sdk_trainstation_01
 
This will generate and embed both standard and [[HDR|High Dynamic Range]] lighting data, at per-vertex detail for prop_static entities.
 
{{bug|To find resources in GCF files, VRAD ''must'' be started in <code>%sourcesdk%\bin\orangebox\</code> (or ep1 as the case may be). You can do this with the <code>cd</code> command, or by setting the "Start In" value of a Windows shortcut. In [[Batch Compiler]], set the BinRoot variable.}}


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


=== Effects ===
=== Effects ===


;<code>-both</code>
<div style="-moz-column-count: 2;-webkit-column-count:2;">
:Compiles lightmaps for both Low Dynamic Range and [[HDR|High Dynamic Range]] lighting models. Causes the compiler to run twice.
; <code>-ldr</code>
;<code>-ldr</code>
; <code>-hdr</code>
:Compile only LDR lightmaps.
; <code>-both</code>
;<code>-hdr</code>
: Whether to compile standard or [[HDR|High Dynamic Range]] lighting, or both.
:Compile only HDR lightmaps.
;<code>-fast</code>
;<code>-fast</code>
: Quick and dirty lighting. Has been known to leave dark lines around displacements.
: Quick and dirty lighting. Don't ship with this.
;<code>-final</code>
;<code>-final</code>
: Increases the quality of [[light_environment]] and indirect lighting by spending more time firing rays.
: Increases the quality of [[light_environment]] and indirect lighting by spending more time firing rays.
;<code>-lights <filename></code>
;<code>-lights <filename>.rad</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>.
:Load a custom [[#Lights_files|lights file]] in addition to <code>lights.rad</code> and map-specific lights file.
;<code>-bounce #</code>
;<code>-bounce <[[int]]></code>
: Set the maximum number of light ray bounces (default: 10).
: Set the maximum number of light ray bounces (default: 10).
;<code>-smooth #</code>
;<code>-smooth <int></code>
:Set the threshold for [[smoothing group]]s, in degrees (default: 45).
:Set the threshold for [[smoothing group]]s, in degrees (default: 45).
;<code>-luxeldensity #</code>
;<code>-luxeldensity <[[normal]]></code>
:Scale down all luxels. Default (and maximum) value is 1.
:Scale down all luxels. Default (and maximum) value is 1.
;<code>-softsun <n></code>
;<code>-softsun <[[float]]></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.
:Treat the sun as an area light source of this many degrees. Produces soft shadows. Recommended values are 0-5, default is 0.
;<code>-StaticPropLighting</code>
;<code>-StaticPropLighting</code>
:Generate per-vertex <code>[[prop_static]]</code> lighting. This is always enabled for [[light_spot]] entities.
:Generate per-vertex [[prop_static]] lighting; always enabled for [[light_spot]] entities. Disables [[info_lighting]] 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.}}
:{{note|When using this setting, it disables all [[info_lighting]] entities in your level and it will light models as if there wasn't one linked to them.}}
;{{EP2 add|<code>-StaticPropPolys</code>}}
;{{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.)''
:Perform shadow tests of <code>prop_static</code>s at polygon precision. Default is to use [[collision mesh]]es.
;{{EP2 add|<code>-TextureShadows</code>}}
;{{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.
:Generates lightmap shadows from [[$translucent]] surfaces of models (NOT brushes) 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.}}
:{{note|A surface will need a low [[lightmap]] scale for most texture shadows to be recognisable.}}
:{{note|-TextureShadows will cast shadows from models using a [[$translucent]] material, this however does not work when a [[$translucent]] material is placed on a brush surface. As for now this only applies to models, hopefully this will change in the near future.}}
</div>


=== Performance ===
=== Performance ===


<div style="-moz-column-count: 2;-webkit-column-count:2;">
;<code>-low</code>
;<code>-low</code>
:Run as an low-priority process. Allows you to use your computer for other things during compiles.
:Run as an low-priority process.
;<code>-threads</code>
;<code>-threads <[[int]]></code>
:Control the number of threads used (defaults to the number of processors on your machine, doubled for CPUs with hyperthreading).
:Override the number of CPU threads used.
;<code>-mpi</code>
;<code>-mpi</code>
:Use [[Vmpi|VMPI]] to distribute computations.
:Use [[Vmpi|VMPI]] to distribute computations.
;<code>-mpi_pw <pw></code>
;<code>-mpi_pw <[[string]]></code>
:Use a password to choose a specific set of VMPI workers.
:Use a password to choose a specific set of VMPI workers.
;<code>-noextra</code>
;<code>-noextra</code>
:Disable supersampling.
:Disable supersampling.
;<code>-chop</code>
;<code>-chop <int></code>
:Smallest number of [[luxel]] widths for a bounce patch, used on edges.
:Smallest number of [[luxel]] widths for a bounce patch, used on edges.
;<code>-maxchop</code>
;<code>-maxchop <int></code>
:Coarsest allowed number of luxel widths for a patch, used in face interiors.
:Coarsest allowed number of luxel widths for a patch, used in face interiors.
;<code>-LargeDispSampleRadius</code>
;<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.
: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>
;<code>-compressconstant <int></code>
:Compress [[lightmap]]s whose color variation is less than n units.
:Compress [[lightmap]]s whose color variation is less than this many units.
</div>


=== Debugging ===
=== Debugging ===


<div style="-moz-column-count: 2;-webkit-column-count:2;">
;<code>-rederrors</code>
;<code>-rederrors</code>
:Emit red light when "a luxel has no samples".
:Emit red light when "a luxel has no samples".
Line 101: Line 120:
:Write large minidumps on crash.
:Write large minidumps on crash.
;<code>-OnlyStaticProps</code>
;<code>-OnlyStaticProps</code>
:Only perform direct static prop lighting (vrad debug option)
:Only perform direct static prop lighting
;<code>-StaticPropNormals</code>
;<code>-StaticPropNormals</code>
:When lighting static props, just show their normal vector
:When lighting static props, just show their normal vector
</div>


==Lights files==
==Lights files==

Revision as of 11:33, 2 January 2010

VRAD is the command-line tool that takes a compiled BSP map and embeds lighting data into it. VRAD's static and pre-compiled light is bounced around the world with a radiosity algorithm.

VRAD will:

VRAD is the generally the slowest of the three compilers due to the many, many calculations it must perform. Lighting optimization can help, as can ensuring your map is free of leaks.

Tip.pngTip:If you are watching the compile dialog and it looks like it has hung at 9... this is usually because VRAD takes longer with each light bounce calculation.
Icon-Bug.pngBug:Ep1 and L4D users seeing crashes when VRAD compiles HDR lighting should read VRAD HDR Crash Fix.  [todo tested in ?]

Syntax

vrad [options...] <bsp file>

For example: 

"%sourcesdk%\bin\orangebox\bin\vrad" -both -StaticPropLighting sdk_trainstation_01

This will generate and embed both standard and High Dynamic Range lighting data, at per-vertex detail for prop_static entities.

Icon-Bug.pngBug:To find resources in GCF files, VRAD must be started in %sourcesdk%\bin\orangebox\ (or ep1 as the case may be). You can do this with the cd command, or by setting the "Start In" value of a Windows shortcut. In Batch Compiler, set the BinRoot variable.  [todo tested in ?]

Options

Use these in combination with expert compile mode or a batch file.

Effects

-ldr
-hdr
-both
Whether to compile standard or High Dynamic Range lighting, or both.
-fast
Quick and dirty lighting. Don't ship with this.
-final
Increases the quality of light_environment and indirect lighting by spending more time firing rays.
-lights <filename>.rad
Load a custom lights file in addition to lights.rad and map-specific lights file.
-bounce <int>
Set the maximum number of light ray bounces (default: 10).
-smooth <int>
Set the threshold for smoothing groups, in degrees (default: 45).
-luxeldensity <normal>
Scale down all luxels. Default (and maximum) value is 1.
-softsun <float>
Treat the sun as an area light source of this many degrees. Produces soft shadows. Recommended values are 0-5, default is 0.
-StaticPropLighting
Generate per-vertex prop_static lighting; always enabled for light_spot entities. Disables info_lighting entities.
Template:EP2 add
Perform shadow tests of prop_statics at polygon precision. Default is to use collision meshes.
Template:EP2 add
Generates lightmap shadows from $translucent surfaces of models (NOT brushes) that are specified in a lights file and being used with prop_static. Usually requires -StaticPropPolys to have any effect.
Note.pngNote:A surface will need a low lightmap scale for most texture shadows to be recognisable.

Performance

-low
Run as an low-priority process.
-threads <int>
Override the number of CPU threads used.
-mpi
Use VMPI to distribute computations.
-mpi_pw <string>
Use a password to choose a specific set of VMPI workers.
-noextra
Disable supersampling.
-chop <int>
Smallest number of luxel widths for a bounce patch, used on edges.
-maxchop <int>
Coarsest allowed number of luxel widths for a patch, used in face interiors.
-LargeDispSampleRadius
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.
-compressconstant <int>
Compress lightmaps whose color variation is less than this many units.

Debugging

-rederrors
Emit red light when "a luxel has no samples".
-vproject <directory>
-game <directory>
Override the VPROJECT environment variable.
v
-verbose
Turn on verbose output.
-novconfig
Don't bring up graphical UI on vproject errors.
-dump
Write debugging .txt files.
-dumpnormals
Write normals to debug files.
-debugextra
Places debugging data in lightmaps to visualize supersampling.
-dlightmap
Force direct lighting into different lightmap than radiosity.
-stoponexit
Wait for a keypress on exit.
-nodetaillight
Don't light detail props.
-centersamples
Move sample centers.
-loghash
Log the sample hash table to samplehash.txt.
-onlydetail
Only light detail props and per-leaf lighting.
-maxdispsamplesize #
Set max displacement sample size (default: 512).
-FullMinidump
Write large minidumps on crash.
-OnlyStaticProps
Only perform direct static prop lighting
-StaticPropNormals
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 handles given materials 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:

  1. lights.rad, the global file.
  2. An auto-loaded map light file, using the format <map name>.rad.
  3. Any number of additional lights files that can be added with the -lights parameter.

Rules

Lights files perform these functions, one rule per line:

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

See also

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=VRAD&oldid=129075"