diff options
Diffstat (limited to 'rend2-readme.txt')
| -rw-r--r-- | rend2-readme.txt | 601 |
1 files changed, 601 insertions, 0 deletions
diff --git a/rend2-readme.txt b/rend2-readme.txt new file mode 100644 index 00000000..15376d5d --- /dev/null +++ b/rend2-readme.txt @@ -0,0 +1,601 @@ +Rend2 +<insert ascii art here> + +Rend2 is an alternate renderer for ioquake3. It aims to implement modern +features and technologies into the id tech 3 engine, but without sacrificing +compatibility with existing Quake 3 mods. + + +------------------------------------------------------------------------------- + FEATURES +------------------------------------------------------------------------------- + + - Compatible with most vanilla Quake 3 mods. + - Faster than original renderer on modern GPUs. + - HDR Rendering, and support for HDR lightmaps + - Tone mapping and auto-exposure. + - Cascaded shadow maps. + - Multisample anti-aliasing. + - Texture upsampling. + - Advanced materials support. + - Advanced shading and specular methods. + - sRGB support. + - LATC and BPTC texture compression support. + - Screen-space ambient occlusion. + + +------------------------------------------------------------------------------- + COMPILATION +------------------------------------------------------------------------------- + +For *nix/MinGW: + +1. Download an appropriate version of the ioq3 source code. For version 32 of + Rend2, r2328 should do, though the latest may work as well. For + details on how to do this, see http://ioquake3.org/get-it/source-codes/ . + +2. Copy the patch file (for v32, vbos-glsl-31a.diff) into the directory you put + the ioq3 source code. There should be a README in that directory. + +3. Run 'patch -p0 <vbos-glsl-31a.diff' then 'make'. + +Compiling on different platforms and with different compilers hasn't been +tested. The MSVC project file should work, but it hasn't been tested. + + +------------------------------------------------------------------------------- + INSTALLATION +------------------------------------------------------------------------------- + +For *nix: + +1. This should be identical to installing ioq3. Check their README for more + details. + + +For Win32: + +1. Have a Quake 3 install, fully patched. + +2. Copy the following files into Quake 3's install directory: + + ioquake3.x86.exe + renderer_opengl1_x86.dll + renderer_rend2_x86.dll + + These can be found in build/release-mingw32-x86 after compiling, or bug + someone to release binaries. + + +------------------------------------------------------------------------------- + RUNNING +------------------------------------------------------------------------------- + +1. Start ioquake3. (ioquake3.x86.exe on Win32) + +2. Open the console (default key ~) and type '/cl_renderer rend2; vid_restart' + +3. Enjoy. + + +------------------------------------------------------------------------------- + CVARS +------------------------------------------------------------------------------- + +Cvars for simple rendering features: + r_ext_compressed_textures - Automatically compress textures. + 0 - No texture compression. (default) + 1 - DXT/LATC texture compression if + supported. + 2 - BPTC texture compression if supported. + + r_ext_framebuffer_multisample - Multisample Anti-aliasing. + 0 - None. (default) + 1-16 - Some. + 17+ - Too much! + + r_ssao - Enable screen-space ambient occlusion. + Currently eats framerate and has some + visible artifacts. + 0 - No. (default) + 1 - Yes. + +Cvars for HDR and tonemapping: + r_hdr - Do scene rendering in a framebuffer with + high dynamic range. (Less banding, and + exposure changes look much better) + 0 - No. + 1 - Yes. (default) + + r_cameraExposure - Cheat. Alter brightness, in powers of two. + -2 - 4x as dark. + 0 - Normal. (default) + 0.5 - Sqrt(2)x as bright. + 2 - 4x as bright. + + r_postProcess - Enable post-processing. + 0 - No. + 1 - Yes. (default) + + r_toneMap - Enable tone mapping. Requires + r_hdr and r_postProcess. + 0 - No. + 1 - Yes. (default) + + r_forceToneMap - Cheat. Override built-in and map tonemap + settings and use cvars r_forceToneMapAvg, + r_forceToneMapMin, and r_forceToneMapMax. + 0 - No. (default) + 1 - Yes. + + r_forceToneMapAvg - Cheat. Map average scene luminance to this + value, in powers of two. Requires + r_forceToneMap. + -2.0 - Dark. + -1.0 - Kinda dark. (default). + 2.0 - Too bright. + + r_forceToneMapMin - Cheat. After mapping average, luminance + below this level is mapped to black. + Requires r_forceToneMap. + -5 - Not noticeable. + -3.25 - Normal. (default) + 0.0 - Too dark. + + r_forceToneMapMin - Cheat. After mapping average, luminance + above this level is mapped to white. + Requires r_forceToneMap. + 0.0 - Too bright. + 1.0 - Normal. (default). + 2.0 - Washed out. + + r_autoExposure - Do automatic exposure based on scene + brightness. Hardcoded to -2 to 2 on maps + that don't specify otherwise. Requires + r_hdr, r_postprocess, and r_toneMap. + 0 - No. + 1 - Yes. (default) + + r_forceAutoExposure - Cheat. Override built-in and map auto + exposure settings and use cvars + r_forceAutoExposureMin and + r_forceAutoExposureMax. + 0 - No. (default) + 1 - Yes. + + r_forceAutoExposureMin - Cheat. Set minimum exposure to this value, + in powers of two. Requires + r_forceAutoExpsure. + -3.0 - Dimmer. + -2.0 - Normal. (default) + -1.0 - Brighter. + + r_forceAutoExposureMax - Cheat. Set maximum exposure to this value, + in powers of two. Requires + r_forceAutoExpsure. + 1.0 - Dimmer. + 2.0 - Normal. (default) + 3.0 - Brighter. + + r_srgb - Treat all input textures as sRGB, and do + final rendering in a sRGB framebuffer. Only + required if assets were created with it in + mind. + 0 - No. (default) + 1 - Yes. + +Cvars for advanced material usage: + r_normalMapping - Enable normal mapping for materials that + support it, and also specify advanced + shading techniques. + 0 - No. + 1 - Yes. (default) + 2 - Yes, and use Oren-Nayar reflectance + model. + 3 - Yes, and use tri-Ace's Oren-Nayar + reflectance model. + + r_specularMapping - Enable specular mapping for materials that + support it, and also specify advanced + specular techniques. + 0 - No. + 1 - Yes, and use tri-Ace. (default) + 2 - Yes, and use Blinn-Phong. + 3 - Yes, and use Cook-Torrance. + 4 - Yes, and use Torrance-Sparrow. + + r_deluxeMapping - Enable deluxe mapping. (Map is compiled + with light directions.) Even if the map + doesn't have deluxe mapping compiled in, + an approximation based on the lightgrid + will be used. + 0 - No. + 1 - Yes. (default) + + r_parallaxMapping - Enable parallax mapping for materials that + support it. + 0 - No. (default) + 1 - Yes. + +Cvars for image interpolation and generation: + r_imageUpsample - Use interpolation to artifically increase + the resolution of all textures. Looks good + in certain circumstances. + 0 - No. (default) + 1 - 2x size. + 2 - 4x size. + 3 - 8x size, etc + + r_imageUpsampleMaxSize - Maximum texture size when upsampling + textures. + 1024 - Default. + 2048 - Really nice. + 4096 - Really slow. + 8192 - Crash. + + r_imageUpsampleType - Type of interpolation when upsampling + textures. + 0 - None. (probably broken) + 1 - Bad but fast (default, + FCBI without second derivatives) + 2 - Okay but slow (normal FCBI) + + r_genNormalMaps - Naively generate normal maps for all + textures. + 0 - Don't. (default) + 1 - Do. + +Cvars for the sunlight and cascaded shadow maps: + r_forceSun - Cheat. Force sunlight and shadows, using sun + position from sky material. + 0 - Don't. (default) + 1 - Do. + 2 - Sunrise, sunset. + + r_forceSunMapLightScale - Cheat. Scale map brightness by this factor + when r_forceSun 1. + 0.5 - Default + + r_forceSunLightScale - Cheat. Scale sun brightness by this factor + when r_forceSun 1. + 0.5 - Default + + r_forceSunAmbientScale - Cheat. Scale sun ambient brightness by this + factor when r_forceSun 1. + 0.2 - Default + + r_sunShadows - Enable sunlight and cascaded shadow maps for + it on maps that support it. + 0 - No. + 1 - Yes. (default) + + r_shadowFilter - Enable filtering shadows for a smoother + look. + 0 - No. + 1 - Some. (default) + 2 - Much. + + r_shadowMapSize - Size of each cascaded shadow map. + 256 - 256x256, ugly, probably shouldn't + go below this. + 512 - 512x512, passable. + 1024 - 1024x1024, good. (default) + 2048 - 2048x2048, extreme. + 4096 - 4096x4096, indistinguishable from + 2048. + +Cvars that you probably don't care about or shouldn't mess with: + r_mergeMultidraws - Optimize number of calls to + glMultiDrawElements(). + 0 - Don't. + 1 - Do some. (default) + 2 - Do more than necessary (eats CPU). + + r_mergeLeafSurfaces - Merge surfaces that share common materials + and a common leaf. Speeds up rendering. + 0 - Don't. + 1 - Do. (default) + + r_recalcMD3Normals - Recalculate the normals when loading an MD3. + Fixes normal maps in some cases but looks + ugly in others. + 0 - Don't. (default) + 1 - Do. + + r_depthPrepass - Do a depth-only pass before rendering. + Speeds up rendering in cases where advanced + features are used. Required for + r_sunShadows. + 0 - No. + 1 - Yes. (default) + + r_normalAmbient - Split map light into ambient and directed + portions when doing deluxe mapping. Not + very useful. + 0 - Don't. (default). + 0.3 - 30% ambient, 70% directed. + 1.0 - 100% ambient. + + r_mergeLightmaps - Merge the small (128x128) lightmaps into + 2 or fewer giant (4096x4096) lightmaps. + Easy speedup. + 0 - Don't. + 1 - Do. (default) + + r_shadowCascadeZNear - Near plane for shadow cascade frustums. + 4 - Default. + + r_shadowCascadeZFar - Far plane for shadow cascade frustums. + 3072 - Default. + + r_shadowCascadeZBias - Z-bias for shadow cascade frustums. + -256 - Default. + + +Cvars that have broken bits: + r_dlightMode - Change how dynamic lights look. + 0 - Quake 3 style dlights, fake + brightening. (default) + 1 - Actual lighting, no shadows. + 2 - Light and shadows. (broken) + + r_pshadowDist - Virtual camera distance when creating shadow + maps for projected shadows. Deprecated. + + cg_shadows - Old shadow code. Deprecated. + + +------------------------------------------------------------------------------- + MATERIALS +------------------------------------------------------------------------------- + +Rend2 supports .mtr files, which are basically the same as .shader files, and +are located in the same place, but override existing .shader files if they +exist. This is to allow maps and mods to use the new material features without +breaking the map when using the old renderer. + +Here's an example of a material stored in one, showing off some new features: + + textures/abandon/grass + { + qer_editorimage textures/abandon/grass.jpg + { + map textures/abandon/grass3_256_d.jpg + rgbgen identity + } + { + stage normalparallaxmap + map textures/abandon/grass3_1024_n.png + } + { + stage specularmap + map textures/abandon/grass3_256_s.png + specularReflectance 0.12 + specularExponent 16 + } + { + map $lightmap + blendfunc GL_DST_COLOR GL_ZERO + } + } + +The first thing to notice is that this is basically the same as old Quake 3 +shader files. The next thing to notice are the new keywords. Here is what +they mean: + + stage <type> + - State how this imagemap will be used by Rend2: + diffuseMap - Standard, same as no stage entry + normalMap - Image will be used as a normal map + normalParallaxMap - Image will be used as a normal map with + alpha treated as height for parallax mapping + specularMap - Image will be used as a specular map with + alpha treated as shininess. + + specularReflectance <value> + - State how metallic this material is. Metals typically have a high + specular and a low diffuse, so this is typically high for them, and low + for other materials, such as plastic. For typical values for various + materials, see http://refractiveindex.info , pick a material, then scroll + down to the reflection calculator and look up its reflectance. Default + is 0.04, since most materials aren't metallic. + + specularExponent <value> + - State how shiny this material is. Note that this is modulated by the + alpha channel of the specular map, so if it were set to 16, and the alpha + channel of the specular map was set to 0.5, then the shininess would be + set to 8. Default 256. + +An important note is that normal and specular maps influence the diffuse map +declared before them, so materials like this are possible: + + textures/terrain/grass + { + qer_editorimage textures/terrain/grass.jpg + + { + map textures/terrain/rock.jpg + } + { + stage normalparallaxmap + map textures/terrain/rock_n.png + } + { + stage specularmap + map textures/terrain/rock_s.jpg + } + { + map textures/terrain/grass.jpg + blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA + alphaGen vertex + } + { + stage normalparallaxmap + map textures/terrain/grass_n.png + } + { + stage specularmap + map textures/terrain/grass_s.png + specularReflectance 0.12 + } + { + map $lightmap + blendfunc GL_DST_COLOR GL_ZERO + } + } + +Though note due to the complexity of lighting, dynamic light (including +sunlight with cascaded shadow maps) currently only works 100% on materials like +this, where the second diffuse map doesn't have its own alpha, and only +uses vertex alpha. YMMV. + +Another addition to materials is working normal/specular maps on vertex lit +surfaces. To enable this, make your material look like this: + + textures/vehicles/car + { + qer_editorimage textures/vehicles/car.jpg + + { + map textures/vehicles/car.jpg + rgbGen vertexLit + } + { + stage normalparallaxmap + map textures/vehicles/car_n.jpg + } + { + stage specularmap + map textures/vehicles/car_s.jpg + } + } + +Note the new keyword, 'vertexLit' after rgbGen. This is analogous to +'rgbGen vertex', except a light direction will be determined from the lightgrid +and used with the normal and specular maps. 'exactVertexLit' exists as well, +and is the equivalent for 'exactVertex'. + + +------------------------------------------------------------------------------- + DYNAMIC SUNLIGHT AND CASCADED SHADOW MAPS +------------------------------------------------------------------------------- + +This adds a new keyword to sky materials, q3gl2_sun. The syntax is: + + q3gl2_sun <red> <green> <blue> <intensity> <degrees> <mapLightScale> + <ambientLightScale> + +Note the first six parameters are the same as in q3map_sun or q3map_sunExt, +and the last two indicate scaling factors for the map brightness and an ambient +light of the same color as the sun. + +There are currently two ways to use this in your own (and other people's) maps. + + 1. Create your map as normal and add a 'q3gl2_sun' line after your + 'q3map_sun' line in your sky material, like so: + + textures/skies/bluesky + { + qer_editorimage textures/skies/bluesky.jpg + + surfaceparm nomarks + surfaceparm noimpact + surfaceparm nolightmap + surfaceparm sky + q3map_sunExt 240 238 200 100 195 35 3 16 + q3gl2_sun 240 238 200 50 195 35 3 0.5 0.2 + q3map_skylight 50 16 + q3map_lightimage $whiteimage + + skyparms env/bluesky - - + } + + The advantages with this method are that your map will continue to work + with the old renderer with the sunlight baked into the lightmap, and it + can be used with existing maps without recompilation. The downside is + artifacts like doubled shadows and uneven shadow edges. + + 2. Use 'q3gl2_sun' instead of 'q3map_sun' or 'q3map_sunExt', like so: + + textures/skies/bluesky + { + qer_editorimage textures/skies/bluesky.jpg + + surfaceparm nomarks + surfaceparm noimpact + surfaceparm nolightmap + surfaceparm sky + q3gl2_sun 240 238 200 50 195 35 3 0.5 0.2 + q3map_skylight 50 16 + q3map_lightimage $whiteimage + + skyparms env/bluesky - - + } + + The advantages with this method are that you don't get the artifacts that + characterize the other method, and your map compiles a lot faster without + the sunlight bouncing calculations. The downsides are that your map will + not display properly with the old renderer, and you lose the bounced light + that compiling the map with q3map_sun* in it would have. + + +------------------------------------------------------------------------------- + TONE MAPPING AND AUTO EXPOSURE +------------------------------------------------------------------------------- + +This adds a new keyword to sky materials, q3gl2_tonemap. The syntax is: + + q3gl2_tonemap <toneMapMin> <toneMapAvg> <toneMapMax <autoExposureMin> + <autoExposureMax> + +Each of these settings corresponds to a matching cvar, so you can view and +adjust the effect before settling on fixed settings. + + +------------------------------------------------------------------------------- + THANKS +------------------------------------------------------------------------------- + +I'd like to take this part of the readme to thank the numerous people who +contributed thoughts, ideas, and whole swaths of code to this project. + + - Id Software, for creating Quake 3 and releasing its source code under a + GPL license, without which this project would not be possible. + + - Zachary 'Zakk' Slater, Thilo Schulz, Tim Angus, and the rest of the + ioquake3 team and contributors, for improving massively upon the raw Quake + 3 source, and accepting my and gimhael's modular renderer patch. + + - Robert 'Tr3B' Beckebans and the other contributors to XReaL, for letting me + liberally copy code from you. :) + + - Andrew 'Black Monk' Prosnik, Andrei 'Makro' Drexler, Tomi 'T.T.I.' Isoaho, + Richard 'JBravo' Allen, Walter 'Johnny Rocket' Somol, and the rest of the + Boomstick Studios, for contributing code, feature requests, and testing. + + - Yoshiharu Gotanda, Tatsuya Shoji, and the rest of tri-Ace's R&D Department, + for creating the tri-Ace shading equations and posting their derivations in + simple English. + + - Matthias 'gimhael' Bentrup, for random ideas and bits of code. + + - Evan 'megatog615' Goers, for testing, ideas, and bugging me just enough + that I'd write documentation. :) + + - The folks at #ioquake3, who don't seem to mind when I suddenly drop a + screenshot and insist on talking about it. :) + + - And lots of various other random people, who posted on forums, blogs, and + Wikipedia, who helped in small but numerous ways. + +If I missed you in this section, feel free to drop me a line and I'll add you. + + +------------------------------------------------------------------------------- + CONTACT +------------------------------------------------------------------------------- + +My name is James Canete, and I wrote most of this readme. Also, a renderer. + +If you wish to get in touch with me, try my GMail at use.less01 (you should be +able to solve this), or look for SmileTheory in #ioquake3 on irc.freenode.net. |