HLRAD

HLCSG ▶ HLBSP ▶ HLVIS ▶ HLRAD

HLRAD is the command-line tool that generates and applies all lighting effects for the map, such as light entities and the sky, and makes it look good. This is usually the slowest of the four tools to run. It replaces QRAD from the original compile tools.

Options

-ambient r g b

Set ambient world light (0.0 to 1.0, r g b). This option sets a minimum light value to every face so that nothing comes out pitch black. The values are red green blue, scaled from 0.0 to 1.0

-blur #

Blur the lightmap, which will lessen GoldSrc's blocky look of shadows (default 1.5). If you want to return to the old look of lightmap, compile hlrad with the parameter '-blur 1.0'.

-bounce #

Set maximum number of radiosity bounces (default 8). This option sets the number of times light bounces in the radiosity pass. By the time the code gets to this point, all the data is precomputed, and extra bounces are very fast. It will make the shadows less harsh using more bounces, but can help light up dark areas much more naturally.

-chop #

Set radiosity patch size for normal textures. Each face in the world has a grid projected onto it, and chopped up into a rather coarse set of sample points. These points are patches, and are what HLRAD uses to do the bounced lighting calculations. A higher chop sacrifices quality for both speed and memory consumption of HLRAD. A lower chop increases the quality at the expense of speed and memory usage.

-circus

Enable 'circus' mode for locating unlit lightmaps. This is a debugging option, which will cause all black pixels in any lightmap to be set to a random fullbright color. It only looks at the direct lighting to make this determination, and ignores any bounced radiosity data for making this determination.

-colourgamma r g b

Sets different gamma values for r, g, b.

-colourjitter r g b

Adds noise, independent colours, for dithering.

-colourscale r g b

Sets different lightscale values for r, g ,b.

-coring #

Set lighting threshold before blackness. This value controls how much light it takes before a surface will be lit with a non-black value.

-customshadowwithbounce

Enable custom shadows for bounced light. By default, the zhlt_customshadow flag does not affect bounced light. Using this switch will enable custom shadows for bounced light. This will only work with greyscale custom shadows. To enable color for the bounced light of custom shadows, use the -rgbtransfers parameter as well.

-dlight #

Set direct lighting threshold. This option is similar to -maxlight, except that it re-normalizes the direct lighting values instead of clipping them if they are too high.

-dscale #

Set direct lighting scale. Due to a bug in the original version of qrad, the direct lighting layer was added into the final lighting twice. The correct thing to do is only have it in there once, but at the time too many maps had been created with this assumption and it was left in there. This has been corrected as a command line switch, to scale the direct lighting by. Using the value of '1' would generate the most correct looking maps. However, since this is configurable it has a few other uses. Using a value of '0' will remove the direct lighting completely from a map and it will only be lit with radiosity lighting. This ends up 'opposite' of -bounce 0, and can be used to check the radiosity lighting for glitches. Using larger values, like 3 or 4, cause extremely harsh direct lighting relation to the shadows and might be of use in desert or arctic maps.

-dump

Dumps light patches to a file for HLRAD debugging info. This is a developer option for ZHLT, to dump out the patch data generated by the chopping/subdividing and make sure it looks alright.

-extra

Turns on 9 point oversampling for lighting, making it look much better. This switch should be used when running final map compiles.

-fade #

Set global fade (larger values = shorter lights). This value adds in an artificial factor into the normal (1 / dist * dist) inverse square falloff calculations, by multiplying the denominator of the scale by the fade value. Point lights can set their own individual fade and falloff values, which override any global setting on the command line. These calculations only affect the direct lighting layer, as the radiosity pass always uses plain inverse square falloff.

-falloff #

Set global falloff mode (1 = inv linear, 2 = inv square). This option can change the normal inverse square falloff of lighting in the direct lighting layer with inverse falloff.

-gamma #

Set global gamma value. This option also occurs after the direct and radiosity layers are added together, and a global gamma correction is calculated and applied to the lighting before it is finalized.

-incremental

Use or create an incremental transfer list file. This is a handy option for tweaking lighting, especially on slow or lower memory machines. BuildVisLeafs, MakeScales, and SwapTransfers can be skipped entirely on subsequent runs of HLRAD. Note that geometry must not change, but lighting can. Using the incremental file requires a simple but important procedure:

1. First HLRAD is run normally with -incremental. In addition to the map being lit normally, it will generate an incremental file, which is essentially the transfer lists dumped to disk.
2. Lights can be changed in any way (moved, brightness changed, color changed, etc).
3. Update the entities in the bsp with an HLCSG -onlyents compile.
4. Re-run rad normally again with the -incremental switch. The exact same options for -extra, -chop, -texchop, -notexscale must be used on all the runs of HLRAD. All the other values may be tweaked.

-jitter r g b

Adds noise, monochromatic, for dithering.

-lights file

Manually specify a RAD file to use. A single .rad file can be added to the compile manually, in addition to the defaults of lights.rad and mapname.rad

-maxlight #

Set maximum light intensity value. This option can be used to cap the bright spots, if you want a map to come out darker overall.

-nodiffuse

Disables light_environment diffuse hack.

-nodynbounce

Turn off bounces for dyanmic lights (overrides -bounce). Prior to ZHLT 1.7, only the static light type (constant brightness, no switching) was used in bounce calculations. This switch activates that older behavior. Benefits include smaller lightdata sizes and a lower probability of a "too many lightstyles" error.

-nolerp

Disable three multi-point interpolation for radiosity patch blending, use nearest point sample instead.

-nomatrix

Disable usage of vismatrix entirely. As the sparse code does some compression, it requires a lot of thread synchronization and does not scale well past 2 CPU's. The -nomatrix switch was added to address this. However the addition of 'opaque brush entities' starting with ZHLT 2.2 hurts the -nomatrix method's performance quite a bit. There is no vismatrix in this method at all, so it essentially reduces the memory requirements to zero for that structure.

-nopaque

Disable all entities using zhlt_lightflags 2 to block light. Using opaque entities slows rad down, and using this option is useful for doing quicker non-final lighting compiles.

-noskyfix

Disable light_environment being global. ZHLT 2.1 added a simpler more manageable system for light_environment's. The new behavior is that a map only needs a single light_environment entity to light up all sky everywhere. The placement of the entity no longer matters. The -noskyfix option turns this feature off and enables the original code which require multiple light_environment's to properly light up an outdoor area.

-nospotpoints

Disables light_spot spherical point sources.

-notexscale #

Do not scale radiosity patches with texture scale. By default, HLRAD will take the texture scale and apply it to the chopping grid which is projected onto it. This option turns that off, and almost always increases the number of patches in a map as most maps have many walls scaled up to 2 and 3.

-rgbtransfers

Enables RGB Transfers (for custom shadows).

-scale #

Set global light scaling value. This option scales the final light values right after the direct lighting layer is added to the radiosity bounced lighting layer. Low values make the world darker, higher values make it brighter.

-sky #

Set ambient sunlight contribution in the shade outside. Many faces have line of sight to sky, but fall in the shadow of some other object. This option affects how much of the normal sky lighting is put into the shadows.

-smooth #

Set smoothing threshold for blending (in degrees). By default HLRAD uses Phong shading on all faces. If the angle between two edges is less than this value, it will be shaded with the Phong smoothing code, otherwise it won't.

Tip:Use info_smoothvalue to define smoothing angles on a per-texture basis.

-softlight r g b d

Scaling values for backwards-light hack.

-sparse

Enable low memory vismatrix algorithm. The original vismatrix algorithm was limited to 65535 patches due to its design. Its memory usage also grew polynomially with the number of patches (patches * patches / 16 bytes). This option enables a compressed vismatrix, which at the cost of extra CPU time, breaks the 65535 limit, and also uses about 10% of the memory the vismatrix would.

-texchop #

Set radiosity patch size for texture light faces. Texture light faces are chopped with a different granularity than the normal faces, primarily so that the lighting looks good. Generally it should be half of the chop value. Adding -extra to HLRAD will automatically divide this value by 2 at runtime.

-limiter #

Set value at which lightmaps should be clamped ^[Clarify]; setting this to 255 will effectively disable clamping. The default value (188) is designed to avoid the chromatic aberration caused by gl_overbright being broken; as gl_use_shaders mostly fixes this renderer bug, this should be set to 255 if targeting the 25th Anniversary Update.

Shared options

-chart

Display bsp statitics. This option will cause the program to print out the bsp statistics right before it writes out the bsp. It is most handy to do -chart with HLRAD and HLVIS at the end of the compiles. The ripent program will alway display the chart.

-dev #

Compile with developer message. Internal ZHLT debugging messages have been slowly added to the tools. This variable sets the 'level' to display. In order (starting with 0 and going up) : Off, Error, Warning, Info, Fluff, Spam, MegaSpam. Generally this option should never be used except at request, to diagnose a compile problem on an end-users machine.

-estimate

Display estimated time during compile. This option replaces the 10...20... style progress indicators with a estimate bar with some estimated completion times, as well as the exact number of the current job and how many jobs there are to do. The three different times remaining factor in varying amounts of historical data to guess how much longer it will take to run. It is good for a ballpark figure, but frequently not much more accurate than that.

-lightdata #

Set custom lightdata maximum (MB). Higher values than the default (6MB) can cause performance issues. You should perform compatability testing before releasing maps if they're over the preset limit.

-low | -high

Run program an altered priority level. Setting the priority of the compile tools to -low is very handy, as you can multitask and do other things without really feeling the drain of the compile programs on the system, provided there is enough memory for the tools and the other programs you use.

-noinfo

Do not show tool configuration information. ZHLT 2.1 added a configuration display for each of the tools as they run, to display the current settings for all configurable options as well as their defaults. This sometimes causes problems with other programs, most notably when compiling within Worldcraft, it likes to crash when too much stuff scrolls into its compile process window.

-nolog

Don't generate the compile logfiles. This option just disables the generation of the .log and .err files which are normally generated whenever the compile tools run.

-texdata #

Alter maximum texture memory limit (in KB). Half-Life was built with a 2MB texture limit, as was Opposing Force. The ZHLT default limit is 4MB. Even 4MB can be a bit much, when combined with model textures, skies, hud graphics, and more. This is especially true of people with older cards (Voodoo 1 and 2's, etc).

-threads #

Manually specify the number of threads to run. This option is generally only necessary on the non-windows versions of the tools, where there is not a standard way to detect the number of processors in the system and auto-set the value. It can be manually set on windows machines, primarily if you wish to use fewer threads than processors.

-verbose

Compile with verbose messages. Many of the tools have 'minor warnings' and informative messages which are displayed when verbose mode is set. As the ZHLT 2.x series developed, many of the developer specific settings have been moved to developer messages, while the mapper-related messages remain as verbose messages.

External links

ZHLT Wiki