1# Rend2 2<insert ascii art here> 3 4Rend2 is an alternate renderer for iortcw. It aims to implement modern 5features and technologies into the id tech 3 engine, but without sacrificing 6compatibility with existing RTCW mods. 7 8 9------------------------------------------------------------------------------- 10 FEATURES 11------------------------------------------------------------------------------- 12 13 - Compatible with most vanilla RTCW mods. 14 - HDR Rendering, and support for HDR lightmaps 15 - Tone mapping and auto-exposure. 16 - Cascaded shadow maps. 17 - Multisample anti-aliasing. 18 - Texture upsampling. 19 - Advanced materials support. 20 - Advanced shading and specular methods. 21 - RGTC and BPTC texture compression support. 22 - Screen-space ambient occlusion. 23 24 25------------------------------------------------------------------------------- 26 INSTALLATION 27------------------------------------------------------------------------------- 28 29For *nix: 30 311. This should be identical to installing iortcw. Check their README for more 32 details. 33 34 35For Win32: 36 371. Have a RTCW install, fully patched. 38 392. Copy the following files into RTCW's install directory: 40 41 ioWolfMP.x86.exe 42 ioWolfSP.x86.exe 43 ioWolfDED.x86.exe 44 renderer_mp_opengl1_x86.dll 45 renderer_mp_rend2_x86.dll 46 renderer_sp_opengl1_x86.dll 47 renderer_sp_rend2_x86.dll 48 49 These can be found in build/release-mingw32-x86 after compiling, or bug 50 someone to release binaries. 51 52 53------------------------------------------------------------------------------- 54 RUNNING 55------------------------------------------------------------------------------- 56 571. Start iowolfmp/iowolfsp. (ioWolfMP.x86.exe/ioWolfSP.x86.exe on Win32) 58 592. Open the console (the default key is tilde ~) and type 60`/cl_renderer rend2` and press enter 61`/vid_restart` then press enter again. 62 633. Enjoy. 64 65 66------------------------------------------------------------------------------- 67 CVARS 68------------------------------------------------------------------------------- 69 70Cvars for simple rendering features: 71 72* `r_ext_compressed_textures` - Automatically compress textures. 73 0 - No texture compression. (default) 74 1 - DXT/RGTC texture compression if 75 supported. 76 2 - BPTC texture compression if supported. 77 78* `r_ext_framebuffer_multisample` - Multisample Anti-aliasing. 79 0 - None. (default) 80 1-16 - Some. 81 17+ - Too much! 82 83* `r_ssao` - Enable screen-space ambient occlusion. 84 Currently eats framerate and has some 85 visible artifacts. 86 0 - No. (default) 87 1 - Yes. 88 89Cvars for HDR and tonemapping: 90 91 * `r_hdr` - Do scene rendering in a framebuffer with 92 high dynamic range. (Less banding, and 93 exposure changes look much better) 94 0 - No. 95 1 - Yes. (default) 96 97* `r_cameraExposure` - Cheat. Alter brightness, in powers of two. 98 -2 - 4x as dark. 99 0 - Normal. (default) 100 0.5 - Sqrt(2)x as bright. 101 2 - 4x as bright. 102 103* `r_postProcess` - Enable post-processing. 104 0 - No. 105 1 - Yes. (default) 106 107* `r_toneMap` - Enable tone mapping. Requires 108 r_hdr and r_postProcess. 109 0 - No. 110 1 - Yes. (default) 111 112* `r_forceToneMap` - Cheat. Override built-in and map tonemap settings and use cvars r_forceToneMapAvg, r_forceToneMapMin, and r_forceToneMapMax. 113 0 - No. (default) 114 1 - Yes. 115 116* `r_forceToneMapAvg` - Cheat. Map average scene luminance to this 117 value, in powers of two. Requires 118 r_forceToneMap. 119 -2.0 - Dark. 120 -1.0 - Kinda dark. (default). 121 2.0 - Too bright. 122 123* `r_forceToneMapMin` - Cheat. After mapping average, luminance 124 below this level is mapped to black. 125 Requires r_forceToneMap. 126 -5 - Not noticeable. 127 -3.25 - Normal. (default) 128 0.0 - Too dark. 129 130* `r_forceToneMapMin` - Cheat. After mapping average, luminance 131 above this level is mapped to white. 132 Requires r_forceToneMap. 133 0.0 - Too bright. 134 1.0 - Normal. (default). 135 2.0 - Washed out. 136 137* `r_autoExposure` - Do automatic exposure based on scene 138 brightness. Hardcoded to -2 to 2 on maps 139 that don't specify otherwise. Requires 140 r_hdr, r_postprocess, and r_toneMap. 141 0 - No. 142 1 - Yes. (default) 143 144* `r_forceAutoExposure` - Cheat. Override built-in and map auto 145 exposure settings and use cvars 146 r_forceAutoExposureMin and 147 r_forceAutoExposureMax. 148 0 - No. (default) 149 1 - Yes. 150 151* `r_forceAutoExposureMin` - Cheat. Set minimum exposure to this value, 152 in powers of two. Requires 153 r_forceAutoExpsure. 154 -3.0 - Dimmer. 155 -2.0 - Normal. (default) 156 -1.0 - Brighter. 157 158* `r_forceAutoExposureMax` - Cheat. Set maximum exposure to this value, 159 in powers of two. Requires 160 r_forceAutoExpsure. 161 1.0 - Dimmer. 162 2.0 - Normal. (default) 163 3.0 - Brighter. 164 165Cvars for advanced material usage: 166 167* `r_normalMapping` - Enable normal maps for materials that 168 support it. 169 0 - No. 170 1 - Yes. (default) 171 172* `r_specularMapping` - Enable specular maps for materials that 173 support it. 174 0 - No. 175 1 - Yes. (default) 176 177* `r_deluxeMapping` - Enable deluxe mapping. (Map is compiled 178 with light directions.) Even if the map 179 doesn't have deluxe mapping compiled in, 180 an approximation based on the lightgrid 181 will be used. 182 0 - No. 183 1 - Yes. (default) 184 185* `r_parallaxMapping` - Enable parallax mapping for materials that 186 support it. 187 0 - No. (default) 188 1 - Use parallax occlusion mapping. 189 2 - Use relief mapping. (slower) 190 191* `r_parallaxMapShadows` - Enable self-shadowing on parallax map 192 supported materials. 193 0 - No. (default) 194 1 - Yes. 195 196* `r_baseSpecular` - Set the specular reflectance of materials 197 which don't include a specular map or 198 use the specularReflectance keyword. 199 0 - No. 200 0.04 - Realistic. (default) 201 1.0 - Ack. 202 203* `r_baseGloss` - Set the glossiness of materials which don't 204 include a specular map or use the 205 specularExponent keyword. 206 0 - Rough. 207 0.3 - Default. 208 1.0 - Shiny. 209 210* `r_baseNormalX` - Set the scale of the X values from normal 211 maps when the normalScale keyword is not 212 used. 213 -1 - Flip X. 214 0 - Ignore X. 215 1 - Normal X. (default) 216 2 - Double X. 217 218* `r_baseNormalY` - Set the scale of the Y values from normal 219 maps when the normalScale keyword is not 220 used. 221 -1 - Flip Y. 222 0 - Ignore Y. 223 1 - Normal Y. (default) 224 2 - Double Y. 225 226* `r_baseParallax` - Sets the scale of the parallax effect for 227 materials when the parallaxDepth keyword 228 is not used. 229 0 - No depth. 230 0.01 - Pretty smooth. 231 0.05 - Standard depth. (default) 232 0.1 - Looks broken. 233 234* `r_pbr` - Enable physically based rendering. 235 Experimental, will not look correct without 236 assets meant for it. 237 0 - No. (default) 238 1 - Yes. 239 240Cvars for image interpolation and generation: 241 242* `r_imageUpsample` - Use interpolation to artifically increase 243 the resolution of all textures. Looks good 244 in certain circumstances. 245 0 - No. (default) 246 1 - 2x size. 247 2 - 4x size. 248 3 - 8x size, etc 249 250* `r_imageUpsampleMaxSize` - Maximum texture size when upsampling 251 textures. 252 1024 - Default. 253 2048 - Really nice. 254 4096 - Really slow. 255 8192 - Crash. 256 257* `r_imageUpsampleType` - Type of interpolation when upsampling 258 textures. 259 0 - None. (probably broken) 260 1 - Bad but fast (default, 261 FCBI without second derivatives) 262 2 - Okay but slow (normal FCBI) 263 264* `r_genNormalMaps` - Naively generate normal maps for all 265 textures. 266 0 - Don't. (default) 267 1 - Do. 268 269Cvars for the sunlight and cascaded shadow maps: 270 271* `r_forceSun` - Force sunlight and shadows, using sun position from sky material. 272 0 - Don't. (default) 273 1 - Do. 274 2 - Sunrise, sunset. 275 276* `r_forceSunLightScale` - Cheat. Scale sun brightness by this factor 277 when r_forceSun 1. 278 1.0 - Default 279 280* `r_forceSunAmbientScale` - Cheat. Scale sun ambient brightness by this factor when r_forceSun 1. 0.5 - Default 281 282* `r_sunShadows` - Enable sunlight and cascaded shadow maps for 283 it on maps that support it. 284 0 - No. 285 1 - Yes. (default) 286 287* `r_sunlightMode` - Specify the method used to add sunlight to 288 the scene. 289 0 - No. 290 1 - Multiply lit areas by light scale, and 291 shadowed areas by ambient scale. 292 (default) 293 2 - Add light. Looks better, but is slower 294 and doesn't integrate well with existing 295 maps. 296 297* `r_shadowFilter` - Enable filtering shadows for a smoother 298 look. 299 0 - No. 300 1 - Some. (default) 301 2 - Much. 302 303* `r_shadowMapSize` - Size of each cascaded shadow map. 304 256 - 256x256, ugly, probably shouldn't 305 go below this. 306 512 - 512x512, passable. 307 1024 - 1024x1024, good. (default) 308 2048 - 2048x2048, extreme. 309 4096 - 4096x4096, indistinguishable from 310 2048. 311 312Cvars that you probably don't care about or shouldn't mess with: 313 314* `r_depthPrepass` - Do a depth-only pass before rendering. 315 Speeds up rendering in cases where advanced 316 features are used. Required for 317 r_sunShadows. 318 0 - No. 319 1 - Yes. (default) 320 321* `r_mergeLightmaps` - Merge the small (128x128) lightmaps into 322 2 or fewer giant (4096x4096) lightmaps. 323 Easy speedup. 324 0 - Don't. 325 1 - Do. (default) 326 327* `r_shadowCascadeZNear` - Near plane for shadow cascade frustums. 328 4 - Default. 329 330* `r_shadowCascadeZFar` - Far plane for shadow cascade frustums. 331 3072 - Default. 332 333* `r_shadowCascadeZBias` - Z-bias for shadow cascade frustums. 334 -256 - Default. 335 336Cvars that have broken bits: 337 338* `r_dlightMode` - Change how dynamic lights look. 339 0 - RTCW style dlights, fake 340 brightening. (default) 341 1 - Actual lighting, no shadows. 342 2 - Light and shadows. (broken) 343 344* `r_pshadowDist` - Virtual camera distance when creating shadowmaps for projected shadows. Deprecated. 345 346* `cg_shadows` - Old shadow code. Deprecated. 347 348 349------------------------------------------------------------------------------- 350 MATERIALS 351------------------------------------------------------------------------------- 352 353Rend2 supports .mtr files, which are basically the same as .shader files, and 354are located in the same place, but override existing .shader files if they 355exist. This is to allow maps and mods to use the new material features without 356breaking the map when using the old renderer. 357 358Here's an example of a material stored in one, showing off some new features: 359 360 textures/abandon/grass 361 { 362 qer_editorimage textures/abandon/grass.jpg 363 { 364 map textures/abandon/grass3_256_d.jpg 365 rgbgen identity 366 } 367 { 368 stage normalparallaxmap 369 map textures/abandon/grass3_1024_n.png 370 normalScale 1 1 371 parallaxDepth 0.05 372 } 373 { 374 stage specularmap 375 map textures/abandon/grass3_256_s.png 376 specularReflectance 0.12 377 specularExponent 16 378 } 379 { 380 map $lightmap 381 blendfunc GL_DST_COLOR GL_ZERO 382 } 383 } 384 385The first thing to notice is that this is basically the same as old RTCW 386shader files. The next thing to notice are the new keywords. Here is what 387they mean: 388 389 `stage <type>` 390 - State how this imagemap will be used by Rend2: 391 diffuseMap - Standard, same as no stage entry 392 normalMap - Image will be used as a normal map 393 normalParallaxMap - Image will be used as a normal map with 394 alpha treated as height for parallax mapping 395 specularMap - Image will be used as a specular map with 396 alpha treated as shininess. 397 398 `specularReflectance <value>` 399 - State how metallic this material is. Metals typically have a high 400 specular and a low diffuse, so this is typically high for them, and low 401 for other materials, such as plastic. For typical values for various 402 materials, see http://refractiveindex.info , pick a material, then scroll 403 down to the reflection calculator and look up its reflectance. Default 404 is 0.04, since most materials aren't metallic. 405 406 `specularExponent <value>` 407 - State how shiny this material is. Note that this is modulated by the 408 alpha channel of the specular map, so if it were set to 16, and the alpha 409 channel of the specular map was set to 0.5, then the shininess would be 410 set to 8. Default 256. 411 412 `normalScale <x> <y>` 413 - State the X and Y scales of the normal map. This is useful for increasing 414 or decreasing the "strength" of the normal map, or entering negative values 415 to flip the X and/or Y values. Default 1 1. 416 417 `parallaxDepth <value>` 418 - State the maximum depth of the parallax map. This is a fairly sensitive 419 value, and I recommend the default or lower. Default 0.05. 420 421An important note is that normal and specular maps influence the diffuse map 422declared before them, so materials like this are possible: 423 424 textures/terrain/grass 425 { 426 qer_editorimage textures/terrain/grass.jpg 427 428 { 429 map textures/terrain/rock.jpg 430 } 431 { 432 stage normalparallaxmap 433 map textures/terrain/rock_n.png 434 } 435 { 436 stage specularmap 437 map textures/terrain/rock_s.jpg 438 } 439 { 440 map textures/terrain/grass.jpg 441 blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA 442 alphaGen vertex 443 } 444 { 445 stage normalparallaxmap 446 map textures/terrain/grass_n.png 447 } 448 { 449 stage specularmap 450 map textures/terrain/grass_s.png 451 specularReflectance 0.12 452 } 453 { 454 map $lightmap 455 blendfunc GL_DST_COLOR GL_ZERO 456 } 457 } 458 459Though note due to the complexity of lighting, dynamic light (including 460sunlight with cascaded shadow maps) currently only works 100% on materials like 461this, where the second diffuse map doesn't have its own alpha, and only 462uses vertex alpha. YMMV. 463 464Another addition to materials is working normal/specular maps on vertex lit 465surfaces. To enable this, make your material look like this: 466 467 textures/vehicles/car 468 { 469 qer_editorimage textures/vehicles/car.jpg 470 471 { 472 map textures/vehicles/car.jpg 473 rgbGen vertexLit 474 } 475 { 476 stage normalparallaxmap 477 map textures/vehicles/car_n.jpg 478 } 479 { 480 stage specularmap 481 map textures/vehicles/car_s.jpg 482 } 483 } 484 485Note the new keyword, 'vertexLit' after rgbGen. This is analogous to 486'rgbGen vertex', except a light direction will be determined from the lightgrid 487and used with the normal and specular maps. 'exactVertexLit' exists as well, 488and is the equivalent for 'exactVertex'. 489 490 491------------------------------------------------------------------------------- 492 DYNAMIC SUNLIGHT AND CASCADED SHADOW MAPS 493------------------------------------------------------------------------------- 494 495This adds a new keyword to sky materials, q3gl2_sun. The syntax is: 496 497 q3gl2_sun <red> <green> <blue> <intensity> <degrees> <elevation> <ambientLightScale> 498 499Note the first six parameters are the same as in q3map_sun or q3map_sunExt, 500and the last two indicate scaling factors for the map brightness and an ambient 501light of the same color as the sun. 502 503There are currently two ways to use this in your own (and other people's) maps. 504 505 1. Create your map as normal, set r_sunlightMode to 1, and add a 506 'q3gl2_sun' line after your 'q3map_sun' line in your sky material, like 507 so: 508 509 textures/skies/bluesky 510 { 511 qer_editorimage textures/skies/bluesky.jpg 512 513 surfaceparm nomarks 514 surfaceparm noimpact 515 surfaceparm nolightmap 516 surfaceparm sky 517 q3map_sunExt 240 238 200 100 195 35 3 16 518 q3gl2_sun 240 238 200 50 195 35 0.2 519 q3map_skylight 50 16 520 q3map_lightimage $whiteimage 521 522 skyparms env/bluesky - - 523 } 524 525 The advantages with this method are that your map will continue to work 526 with the old renderer with the sunlight baked into the lightmap, and it 527 can be used with existing maps without recompilation. The downside is 528 artifacts like doubled shadows and uneven shadow edges. 529 530 2. Set r_sunlightMode to 2 and use 'q3gl2_sun' instead of 'q3map_sun' or 531 'q3map_sunExt', like so: 532 533 textures/skies/bluesky 534 { 535 qer_editorimage textures/skies/bluesky.jpg 536 537 surfaceparm nomarks 538 surfaceparm noimpact 539 surfaceparm nolightmap 540 surfaceparm sky 541 q3gl2_sun 240 238 200 50 195 35 0.2 542 q3map_skylight 50 16 543 q3map_lightimage $whiteimage 544 545 skyparms env/bluesky - - 546 } 547 548 The advantages with this method are that you don't get the artifacts that 549 characterize the other method, and your map compiles a lot faster without 550 the sunlight bouncing calculations. The downsides are that your map will 551 not display properly with the old renderer, and you lose the bounced light 552 that compiling the map with q3map_sun* in it would have. 553 554 555------------------------------------------------------------------------------- 556 TONE MAPPING AND AUTO EXPOSURE 557------------------------------------------------------------------------------- 558 559This adds a new keyword to sky materials, q3gl2_tonemap. The syntax is: 560 561 q3gl2_tonemap <toneMapMin> <toneMapAvg> <toneMapMax> <autoExposureMin> <autoExposureMax> 562 563Each of these settings corresponds to a matching cvar, so you can view and 564adjust the effect before settling on fixed settings. 565 566 567------------------------------------------------------------------------------- 568 THANKS 569------------------------------------------------------------------------------- 570 571I'd like to take this part of the readme to thank the numerous people who 572contributed thoughts, ideas, and whole swaths of code to this project. 573 574 - Id Software, for creating RTCW and releasing its source code under a 575 GPL license, without which this project would not be possible. 576 577 - Zachary 'Zakk' Slater, Thilo Schulz, Tim Angus, and the rest of the 578 ioquake3 team and contributors, for improving massively upon the raw Quake 579 3 source, and accepting my and gimhael's modular renderer patch. 580 581 - Robert 'Tr3B' Beckebans and the other contributors to XReaL, for letting me 582 liberally copy code from you. :) 583 584 - Andrew 'Black Monk' Prosnik, Andrei 'Makro' Drexler, Tomi 'T.T.I.' Isoaho, 585 Richard 'JBravo' Allen, Walter 'Johnny Rocket' Somol, and the rest of the 586 Boomstick Studios, for contributing code, feature requests, and testing. 587 588 - Yoshiharu Gotanda, Tatsuya Shoji, and the rest of tri-Ace's R&D Department, 589 for creating the tri-Ace shading equations and posting their derivations in 590 simple English. 591 592 - Matthias 'gimhael' Bentrup, for random ideas and bits of code. 593 594 - Evan 'megatog615' Goers, for testing, ideas, and bugging me just enough 595 that I'd write documentation. :) 596 597 - The folks at #ioquake3, who don't seem to mind when I suddenly drop a 598 screenshot and insist on talking about it. :) 599 600 - And lots of various other random people, who posted on forums, blogs, and 601 Wikipedia, who helped in small but numerous ways. 602 603If I missed you in this section, feel free to drop me a line and I'll add you. 604 605 606------------------------------------------------------------------------------- 607 CONTACT 608------------------------------------------------------------------------------- 609 610My name is James Canete, and I wrote most of this readme. Also, a renderer. 611 612If you wish to get in touch with me, try my GMail at use.less01 (you should be 613able to solve this), or look for SmileTheory in #ioquake3 on irc.freenode.net. 614
