An attribute, be it a surface or stage attribute, is an identifier (name) followed by zero or more white-space separated parameters. The parameters are used to pass values specific to the shader to the Quake3 engine, for example a map attribute has a parameter that tells Quake3 what texture map to use. Parameters may be a string or a number. A string is simply a name, for example the name of a file or an identifier, with no spaces in it. Numbers with decimal points do not require a leading zero (i.e. .5 is acceptable and the same as 0.5).
Attributes can be divided up into three types:
Several attributes use parameters in a similar way. To keep explanations concise, parameters with the names given below are assumed to have certain functions.
<tgaName>
The name of a .tga file e.g. textures/liquid/lavahell.tga. Note that even if an image is a .jpg file, for example light.jpg, it is referred to as a .tga file, for example light.tga.
<mapName>
The name of a .tga file or a special map name. Known special map names are $lightmap and $whiteimage. $lightmap is the lightmap of the surface. $whiteimage is pure white. Another special map name, *white, is used, but is untested. The <tgaName> rules for .jpgs apply here as well.
<genFunc> <yOffset> <yScale> <startOffset> <speed>
Genfuncs are a function name followed by four parameters. They are typically used to vary something over time, for example to fade a texture map in and out. See Appendix 4 for more information.
<r> <g> <b>
A colour in RGB format. Given as numbers in the range 0-1. For example, 1 0 1 is purple, .5 .5 .5 medium grey.
?
Parameter use/purpose is unknown.
something?
The something is a guess at the parameters' purpose which has not been confirmed.
In this document shader attribute definitions are laid out like so:
attributeIdentifier identifierParameter <valueParameter> [specialParameter]
Description of the attribute
Example(s)
The attributeIdentifier is the attribute's identifier/name.
An identifierParameter is a name that is always passed exactly as given, usually as part
of a special parameter.
A <valueParameter> is an integer or string value.
A [specialParameter] is one or more identifer or value parameters. This is used where
an attribute may have a variable number of parameters.
cull <cullType>
Controls the culling of the polygon. Every surface in Quake3 has a front and back. Normally, if the back of a surface is facing the player then the polygon is discarded. The process of discarding polygons according to their orientation is known as culling. Possible values for cullType include:
front
Cull the polygon when the front is showing (default).
back
Cull the polygon when the back is showing (default).
backsided
Unknown.
disable
Turn off culling for this surface,
none
Turn off culling for this surface,
twosided
Unknown.
cull backsided cull none
deformVertexes [type]
Deforms the vertexes of a surface. The type of deformation is specified by the type parameter, which can have the following values:
autosprite
Move the vertexes of the surface so that it faces the player at all times.
autosprite2
Similar to autosprite, except that the surface is only rotated along its y axis and scaled depending on the angle of the player to the starting position of the surface. If the player is facing the surface its scaling is unchanged. If the player is looking down or up at an angle of 45 degrees to the surface it is scaled to roughly half its starting size. If the player is looking directly down or up at the surface it is scaled by zero (i.e. is invisible).
bulge
Purpose unknown.
move <x> <y> <z> <genFunc> <yOffset> <yScale> <startOffset> <speed>
At any given time the vertexes are shifted along the given (x, y, z) vector by the value of the given genFunc.
projectionShadow
Used to generate a player's projected shadow (not the blob shadow - the one which is the shape of the player projected onto the ground like q2's gl_shadows)
text0
Purpose unknown. Used for scoreboard names.
text1
Purpose unknown. Used for scoreboard scores.
wave <waveSize> <genFunc> <yOffset> <yScale> <startOffset> <speed>
The position of each vertex is offset along its normal (the line pointing directly away from the surface) by the value of the given graph function. The startOffset parameter of the graph function is modified slightly for each vertex according to its position in order to give a wave effect. The formula for this appears to be something like additionalOffset = (vertex.x+vertex.y+vertex.z)/wavesize.
More than one deformVertexes is allowed per surface definition
deformVertexes autosprite deformVertexes wave 100 sin 0 1 0 1
entityMergable
Purpose unknown. Possibly a flag to tell Quake3 to somehow merge surfaces/entitys together for optimization.
fogGen <genFunc> <yOffset> <yScale> <startOffset> <speed>
Multiplies the density of the fog by the given genFunc.
fogGen sin 0 1 0 1
fogonly
Tells Quake3 that the brush with this shader is fog and nothing else. Shaders with this attribute must not contain any stages.
fogParms ( <r> <g> <b> ) <density>
Sets certain parameters for a fog brush. The rgb triplet is the colour of the fog. The density value is how far the fog goes before reaching maximum density.
fogParms ( 1 0.5 0 ) 100
light 1
Tells Quake3 to render a light flare for this surface.
polygonOffset
Tells Quake3 to add a small forward offset when rendering the surface to the z-buffer. This is used by decals such as blood splats and bullet holes to prevent z-buffer errors rendering them behind the wall they are on.
portal
Specifies that the surface is a portal.
q3map_backshader <shaderName>
Use a different shader for the back of a surface. Untested.
q3map_backsplash ? ?
Purpose unknown. Possibly to do with surface lighting begin projected back on its source. According to gothic_light.shader using q3map_backsplash 0 0 will turn off backsplash.
q3map_globalTexture
Purpose unknown.
q3map_lightImage <tgaName>
Specifies an alternate texture for calculating the colour of the surface light emitted by a texture. This is often used by lights, and the glow texture is generally used.
q3map_lightSubdivide <size>
Specify the size of the qrad light patch. The default is 64. A smaller value will increase the quality of surface lights but will slow compilation dramatically. Larger values are recommended for sky textures.
q3map_sun <r> <g> <b> <intensity> <degrees> <elevation>
Specifies the position, colour and intensity of the sun in a sky shader. Used by qrad to calculate sunlight and by the Quake3 engine to render a sun sprite. The rgb values are normalised (i.e. 1 .5 0 is the same as 256 128 0). For degrees, 0 = east, 90 = north etc. For elevation, 0 = the horizon, 90 = directly overhead.
q3map_sun .473 .243 .314 30 35 78
q3map_surfaceLight <amountOfLight>
Tells q3map how much light the surface emits. This is the same as surface lighting in q2. The algorithm for calculating the colour of the light emitted is unknown (possibly the average colour of the first non-lightmap stage in the shader). See also q3map_lightimage.
qer_editorimage <tganame>
Probably used to specify a .tga to represent the shader in q3radiant.
qer_nocarve
Brush parameter. Possibly used to tell q3radiant not to include this brush in carve operations. Typically used on fog brushes.
qer_trans <x>
Possibly used to tell q3radiant to render the surface as transparent in the editor 3d view (transparency given by x in the range 0-1, 1=opaque).
skyParms envmap1 <height> envmap2
Sets the parameters for the sky. The height is just the apparent height of the sky. The envmaps give the base name for a series of .tgas which Quake3 then uses to generate a 'skybox' (like the sky in Quake2). envmap2 is inoperative in the 1.08 test. There must be six .tgas, ending with _ft, _bk, _lf, _rt, _up and _dn for left, right, back, front, up and down respectively. The start of the .tga name is the value of envmap1/envmap2. So, if the value of envmap1 was env/space the texture for the front of the skybox would be env/space_ft.tga. Any maps in the shader are rendered in front of envmap1. If envmap1/2 are not used they must be replaced with a dash (e.g. skyParms - 512 -).
skyParms - 500 - skyParms unit1 200 -
sort <type>
Purpose unknown. Possible used to specify a different sorting order for a surface (for transparent sprites?). Known possible values for type are additive, nearest, underwater and banner. (* Explained in id shader manual *)
surfaceParm [x]
Turns on a property of a surface, x being a string indicating the property. They are similar to the surface parameters in quake2. Certain parameters define the properties of a brush (where all polygons in brush must share same property) e.g. fog, water. I believe that all parameters except nomipmaps and nopicmip are used by the compile tools only and are not visible to the Quake3 engine. Valid parameters for x include:
alphaShadow
Tells q3map -light to use an alpha channel from one of the stages (* how does it choose? *) to decide whether parts of the surface block light or not.
areaportal
Brush attribute. Possibly the same as areaportal from q2.
clusterPortal
Unknown.
doNotEnter
Unknown. Possibly tell the bots not to enter a brush with this attribute.
fog
Brush attribute. Specify a fog brush.
lava/water/slime
Brush is a liquid of the given type.
lightfilter
Purpose unknown. Possibly obsolete.
metalsteps
Footsteps will be metallic on this surface.
nodamage
No falling damage is caused by falling onto this surface.
nodlight
Possibly tells Quake3 not to cast dynamic lights onto this surface. Untested.
nodraw
Do not draw the (surface? brush?)
nodrop
Unknown.
noimpact
Projectiles do not impact this surface. Used by sky and water.
nolightmap
Don't generate a lightmap for the surface. Used for flames and other fullbright textures.
nomarks
Don't render marks (bullet holes, blood) on the surface.
nomipmap
Use only one mipmap for this surface. Used for some icons and the console background.
nonsolid
Allow player to walk through the brush with this surface property (as mist in q2).
nopicmip
Treat this surface as if r_picmip was zero. Used for status icons.
origin
Brush attribute. Use to specify the centre of a rotating brush.
playerclip
Brush attribute. Player cannot walk through brush.
sky
Surface is sky.
slick
Possibly used to make a surface slippery. It's use in common.shader suggests that it is different from the q2 slick attribute, which was applied to individual surfaces. The Quake3 version appears to be a brush attribute - maybe surfaces within the brush become slick.
structural
Brush attribute. Appears to be used on non-drawing brushes like areaportals and clip and hint brushes. Purpose unknown.
trans
Surface is transparent.
tessSize <n>
Tells qbsp to tesselate the surface (split it into smaller polygons) using n as the size of the tesselation. Generally used to add extra polygons to surfaces that have a deformVertexes wave attribute in order to increase the quality of rippling effect.
alphaFunc <type>
Tells Quake3 to discard pixels in the map with alpha values that do not satisfy the condition. Known possible values for type are GT0 (greater than zero), LT128 (less than 128) and GE128 (greater than/equal to 128). For this comparison alpha values are considered to be in the range 0 to 256, as opposed to the 0 to 1 range used for most other functions. Discarded pixels do not affect the frame or z buffers.
alphaGen [type]
The alpha values of the map are put through the function specified by type before being used. If no alphaGen attribute is explicitly specified then they are implicitly specified with the identity function. Values are clamped to the range 0 to 1.
const <c>
Multiply the value by the given constant value
entity
Multiply the value by the current lighting value of the entity it is a part of. The entity lighting is calculated from the value of the lightmap directly below it plus any dynamic lighting.
exactVertex
Purpose unknown. Used for decals (blood splats, bullet marks).
identity
Leave value unchanged.
identityLighting
Unknown. Used for smoke puffs and blood sprays.
lightingDiffuse
Multiply the value by a value generated by applying gourad shaded directional light to the surface. Used on ammo boxes and weapons.
lightingSpecular
As lightDiffuse, except the lighting value is modified according to the viewer's position. The algorithm used to calculate the value is unknown.
oneMinusEntity
One minus the entity light value (see entity). Use to make explosions fullbright.
portal <fadeDistance>
Multiply the value by the result of the function distanceFromPlayer/fadeDistance clamped to the range 0-1. This effectively means that the map is left unchanged when the player is very close and gradually fades out the further they are away.
vertex
Multiply by vertex lighting values.
wave <genFunc> <yOffset> <yScale> <startOffset> <speed>
Multiply the value by the genFunc given after the wave parameter.
alphaGen const 0.5 alphaGen portal 200 alphaGen wave sin 0 1 0 1
alphaMap <mapName>
Specify a .tga or special map to be used as an alpha channel. Untested and not used in the 1.05 q3test. There is one known special value for alphaMapName, $fromBlack, and its effect is unknown.
animMap <speed> <mapname1> <mapname2> ... <mapnameN>
Specify a series of textures which are animated in sequence. The speed of number of times the entire sequence of textures will cycle per second. Each texture in the animation is gradually blended into the next one. See the flames in q3test1 for an example of this. If a stage does not contain a map, animMap or clampMap attribute then the surface is rendered to the z-buffer only. (* Move last sentence to somehere more visible *)
animMap 2 one.tga two.tga three.tga
blendFunc <srcFunc> <destFunc>
blendFunc <shortFunc>
Blend the stage into the framebuffer using the given OpenGL functions. See Using blendFunc in the Examples section for more detail.
clampMap <mapName>
As map, except that the when a pixel is drawn its value is clamped to the map boundaries rather than wrapping around. If that's gibberish, try it and you'll see what I mean.
clampMap textures/myTexture.tga
depthFunc <type>
Tell the renderer which z-buffer depth testing function to use for this stage. Known possible values for type are less and equal. The default is less.
depthMask
Purpose unknown.
depthWrite
The depthWrite attribute forces the Quake3 engine to render z-buffer information for this stage. If there is no depthWrite attribute in any of the stages in a shader the last stage is rendered with an implicit depthWrite.
map <mapname>
The name of a .tga file to be used as a static texture map. If a stage does not contain a map, animMap or clampMap attribute then the surface is rendered to the z-buffer only.
rgbGen [type]
The rgb values of the stage are put through the function specified by type before being used. If no rgbGen attribute is explicitly specified then they are implicitly specified with the identity function. Values are clamped to the range 0 to 1.
const ( <r> <g> <b> )
Multiply the value by the given RGB triplet.
entity
See alphaGen.
exactVertex
See alphaGen.
identity
See alphaGen.
identityLighting
See alphaGen.
lightingDiffuse
See alphaGen.
lightingSpecular
See alphaGen.
oneMinusEntity
See alphaGen.
portal <fadeDistance>
Multiply the value by the result of the function distanceFromPlayer/fadeDistance clamped to the range 0-1. This effectively means that the alpha is left unchanged when the player is very close and gradually fades out the further they are away. The portal parameter cannot be used with rgbGen.
vertex
See alphaGen.
wave <genFunc> <yOffset> <yScale> <startOffset> <speed>
See alphaGen.
rgbGen const ( 1 0.5 0 )
tcGen [type]
Generate texture coordinates using the specified function. The only known functions are:
environment
Maps the coordinates using environment mapping (also known as chrome mapping). This is used on the bubbles that surround the health items and the quad rune.
vector
Unknown.
tcMod [type]
Modify the texture coordinates of a stage over time. Stages may contain more than one tcMod attribute. Possible types include:
scale <x> <y>
Scale the stage by the given x and y. The formula is n scales the stage along the appropriate axis by 1/n. For example, a value of 2 would scale it by 2^-1 = 0.5 (halve it in size). A value of 0.5 would scale it by 0.5^-1 = 2 (double it in size).
rotate <speed>
Rotate the stage by the given number of degrees per second.
scroll <x> <y>
Continuously scroll the stage by the given x and y offsets per second.
stretch <genFunc> <yOffset> <yScale> <startOffset> <speed>
Stretch the stage over time using the given graph functions.
turb <offset> <scale> <startOffset> <speed>
Ripple the texture in a similar way to the water in Quake1/2. Used for the lava in q3test1. The parameters uses are the same as those for a genFunc.
Sometimes, the attribute depthFunc equal is required to make the tcMod work. The reason for this is unknown.
tcMod scale 2 2 tcMod turb 0 10 0 2 tcMod stretch sin 0 1 0 1