Shaders ======= Call of Duty uses two types of shaders. .. toctree:: :maxdepth: 1 shader/index shadertype/index .. important:: A texture can only have one type of shader definition. Global Parameters ----------------- These parameters are specified at the shader level (outside of stage blocks). Surface Parameters __________________ Defines the physical and gameplay properties of a surface. **Keyword for declaration**: ``surfaceparm`` Values: nodraw ^^^^^^ Surface is not rendered but still exists for collision. The surface will still block movement and can receive decals/shadows unless other surfaceparms prevent it. nomarks ^^^^^^^ Bullet marks, blood splatters, and other decals won't appear on this surface. nonsolid ^^^^^^^^ Players and entities can pass through this surface. The surface is effectively intangible. water ^^^^^ Surface is treated as water by the game engine. Used for liquid volumes that the player can swim in. sky ^^^ Surface is a skybox. Used for rendering the sky and environment. Sky surfaces are not drawn in reflections and have special rendering behavior. nolightmap ^^^^^^^^^^ Surface doesn't receive or use lightmap lighting. The surface will be rendered with only its base color/texture without baked lighting. noimpact ^^^^^^^^ Projectiles don't collide with or impact this surface. Bullets, grenades, and other projectiles will pass through. playerclip ^^^^^^^^^^ Blocks player movement. Players cannot move through brushes with this surfaceparm. monsterclip ^^^^^^^^^^^ Blocks AI/actor movement. Computer-controlled characters cannot move through this surface. vehicleclip ^^^^^^^^^^^ Blocks vehicle movement. Vehicles cannot pass through this surface. clipmissile ^^^^^^^^^^^ Blocks missile/projectile movement. Missiles and similar projectiles cannot pass through. canshootclip ^^^^^^^^^^^^ Can shoot through clip brushes. Allows projectiles to pass through surfaces that would normally block them. clipshot ^^^^^^^^ Blocks all shots. No projectiles can pass through this surface. itemclip ^^^^^^^^ Blocks item pickup. Players cannot pick up items through this surface. ladder ^^^^^^ Surface is climbable. Players can climb up/down this surface like a ladder. structural ^^^^^^^^^^ Surface is structural (affects BSP compilation). Marking a surface as structural tells the compiler to treat it as load-bearing for the BSP tree. origin ^^^^^^ Surface defines an origin point. Used to specify the origin for entity placement or rotation. areaportal ^^^^^^^^^^ Surface is an area portal for visibility optimization. Area portals divide the map into separate visibility areas, improving rendering performance by culling geometry that cannot be seen through the portal. .. _surfaceparm-portal: portal ^^^^^^ Surface is a portal for visibility optimization. Used for visibility culling to improve rendering performance. nodamage ^^^^^^^^ Surface doesn't cause damage. Players/entities won't take damage from contact with this surface. nodrop ^^^^^^ Items won't drop on this surface. Items cannot be placed on or fall onto this surface. occluder ^^^^^^^^ Surface is an occluder for visibility. Occluders block visibility of geometry behind them, improving rendering performance by preventing overdraw. cushion ^^^^^^^ Surface cushions falls (no fall damage). Characters landing on this surface won't take fall damage. castshadow ^^^^^^^^^^ Surface casts shadows. The surface will project shadows onto other surfaces. alphashadow ^^^^^^^^^^^ Surface casts alpha-tested shadows. Shadows from this surface use alpha testing for transparency. noshadow ^^^^^^^^ Surface doesn't cast shadows. No shadows will be rendered from this surface. glass ^^^^^ Surface is glass. Marking a surface as glass allows for special rendering effects like transparency and refraction. opaqueglass ^^^^^^^^^^^ Surface is opaque glass. Looks like glass but blocks visibility completely (no transparency). wood ^^^^ Surface is wood. Affects footsteps sounds and other material-specific behavior. metal ^^^^^ Surface is metal. Affects footsteps sounds, bullet impacts, and material properties. brick ^^^^^ Surface is brick. Affects footsteps sounds and material properties. concrete ^^^^^^^^ Surface is concrete. Affects footsteps sounds and material properties. gravel ^^^^^^ Surface is gravel. Affects footsteps sounds and material properties. dirt ^^^^ Surface is dirt. Affects footsteps sounds and material properties. rock ^^^^ Surface is rock. Affects footsteps sounds and material properties. grass ^^^^^ Surface is grass. Affects footsteps sounds and typically used with alpha blending for foliage. snow ^^^^ Surface is snow. Affects footsteps sounds and material properties. ice ^^^ Surface is ice. Affects footsteps sounds (slippery) and material properties. mud ^^^ Surface is mud. Affects footsteps sounds and material properties. sand ^^^^ Surface is sand. Affects footsteps sounds and material properties. cloth ^^^^^ Surface is cloth. Affects bullet impacts and material properties (used for flags, curtains, etc.). carpet ^^^^^^ Surface is carpet. Affects footsteps sounds (quiet) and material properties. ceramic ^^^^^^^ Surface is ceramic. Affects material properties and sound. asphalt ^^^^^^^ Surface is asphalt. Affects footsteps sounds and vehicle traction. bark ^^^^ Surface is tree bark. Affects material properties for wooden objects. flesh ^^^^^ Surface is flesh. Affects bullet impacts, blood effects, and material properties. paper ^^^^^ Surface is paper. Affects material properties (thin, tearable surfaces). plaster ^^^^^^^ Surface is plaster. Affects material properties for walls and ceilings. foliage ^^^^^^^ Surface is foliage. Affects collision, sound, and typically used with alpha blending for plants/vegetation. noncolliding ^^^^^^^^^^^^ Surface doesn't collide with anything. Geometry with this surfaceparm will not participate in collision detection. nodlight ^^^^^^^^ Surface doesn't receive dynamic lighting. Dynamic lights won't affect this surface. ai_nosight ^^^^^^^^^^ AI can't see through this surface. AI characters will not have line of sight through surfaces marked with this parameter. Culling Parameters __________________ **Keyword for declaration**: ``cull`` .. _cull-none: none ^^^^ Disables backface culling (both sides visible). Neither side of the polygon is removed. Both sides are drawn in the game. Very useful for making panels or barriers that have no depth, such as grates, screens, metal wire fences, liquid volumes that the player can see from within, energy fields, sprites, and weapon effects. front ^^^^^ Culls front faces. The front or "outside" of the polygon is not drawn in the world. Useful for inverted geometry. back ^^^^ Culls back faces (default). The back or "inside" of a polygon is removed from being drawn in the world. disable ^^^^^^^ Same as :ref:`cull-none` Sorting Parameters __________________ These parameters are used for controlling render order. Mostly used for transparency related effects. **Keyword for declaration**: ``sort`` additive ^^^^^^^^ Additive blending (typically 1-10). Render order for effects that add light/color to the scene. nearest ^^^^^^^ Renders closest to camera first. Used for textures that need to render in z-sort order. seethrough ^^^^^^^^^^ See-through rendering. Used for transparent surfaces that need to render after opaque geometry. underwater ^^^^^^^^^^ Underwater rendering. Special sort for underwater effects and caustics. corona ^^^^^^ Corona/lens flare rendering. Special sort for light flare effects. innerBlend ^^^^^^^^^^ Inner transparency layer. Used for glass and other transparent surfaces that should render in a specific order. outerBlend ^^^^^^^^^^ Outer transparency layer. Used for transparent surfaces that should render after inner blend surfaces. boathull ^^^^^^^^ Boat hull rendering. Special sort for boat/water vehicle hulls. Texture Quality Parameters __________________________ nopicmip ^^^^^^^^ Disables picmipping. Prevents textures from losing detail at a distance, keeping them sharp even when far from the camera. nomipmaps ^^^^^^^^^ Disables mipmapping. The texture will not use lower-resolution mipmap levels, maintaining full resolution at all distances. Can cause aliasing on distant surfaces. Fog Parameters ______________ nofog ^^^^^ Surface is not affected by fog. The surface will render with full clarity regardless of fog settings in the map. Editor Parameters _________________ These parameters affect the properties in the map editor qer_editorimage ^^^^^^^^^^^^^^^ Specifies a different image to display in the editor. Takes a texture path. The editor will display this image instead of the shader name, but the shader itself will use the textures defined in its stages. The editor maps a texture using the size attributes of the TGA file used for the editor image. qer_trans ^^^^^^^^^ Sets transparency in the editor. Takes a value from 0.0 (fully transparent) to 1.0 (fully opaque). This only affects visibility in the editor, not in-game rendering. qer_drawtoggle ^^^^^^^^^^^^^^ Toggleable in the editor. Allows the texture to be shown or hidden in the editor with a visibility toggle. Entity Merging ______________ entityMergable ^^^^^^^^^^^^^^ Allows multiple instances of this shader to be merged together for better rendering performance. Used for particles, decals, and other frequently-used effects. Polygon Offset ______________ polygonOffset ^^^^^^^^^^^^^ Offsets depth values to prevent z-fighting. Pushes the geometry slightly forward in the depth buffer to prevent rendering artifacts when coplanar surfaces overlap. polygonOffset2 ^^^^^^^^^^^^^^ Stronger polygon offset. A more aggressive depth offset than polygonOffset, for surfaces that need more separation. Deformation Parameters ______________________ Deforms the vertices of the surface dynamically. Used for animated effects like waves, flags, and other moving surfaces. Available operations: - ``autosprite``: Always faces camera (billboard). The surface will rotate to always face the camera. - ``autosprite2``: Always faces camera, rotates with entity. Similar to autosprite but respects entity rotation. - ``flap``: Flapping animation (e.g., for flags, banners). Takes the following args: - ``direction`` (s = side, t = top) - ``speed`` animation speed - ``func`` wave function (sin, square, triangle, sawtooth, inversesawtooth, noise) - ``base`` base value - ``amplitude`` wave amplitude - ``phase`` phase offset - ``frequency`` wave frequency - ``wave``: Wave-based alpha. Alpha is animated using wave functions: Wave deformation (e.g., for water surfaces). Takes the following args: - ``div`` division factor - ``func`` - ``base`` - ``amplitude`` - ``phase`` - ``frequency`` - ``syncNormal``: Synchronize normal vectors with vertex deformation. Takes the following args: - ``value`` tessSize ^^^^^^^^ Tessellation size for vertex deformation. Specifies how finely the surface is chopped up into triangles, in game units. Larger values = fewer, larger triangles. Smaller values = more, smaller triangles for smoother deformation. Only applicable to solid brushes that use deformVertexes. Lighting Parameters ___________________ q3map_surfacelight ^^^^^^^^^^^^^^^^^^ Surface emits light (radiosity). Takes an intensity value. The surface will emit light during the Q3MAP lighting phase, acting as a light source that illuminates nearby geometry. q3map_lightimage ^^^^^^^^^^^^^^^^ Light image for surface light. Takes a texture path. Used for projected lights or custom light patterns from the surface. q3map_sun ^^^^^^^^^ Sun light direction and color. Creates the illusion of light cast into a map by a single, infinitely distant light source (sun, moon, etc.). Only processed during the lighting phase of q3map. Takes the following args: - ``r`` - ``g`` - ``b`` - ``intensity`` - ``degrees`` - ``elevation`` q3map_lightsubdivide ^^^^^^^^^^^^^^^^^^^^ Lightmap subdivision size. Takes an integer value. Controls the resolution of lightmaps on this surface. Higher values = finer lightmap detail but more memory usage. q3map_globaltexture ^^^^^^^^^^^^^^^^^^^ Global texture for lighting. Use this when the tcMod scale function is used in later render stages to ensure consistent texture scaling across adjacent brushes. perlight ^^^^^^^^ Stage renders per-light (for dynamic lighting). The stage will be rendered once for each dynamic light affecting it, allowing for dynamic lighting effects. Sky Parameters ______________ skyParms ^^^^^^^^ Takes the following arguments: - ``env_name``: Environment map base name (e.g., "env/test" would look for env/test_rt.tga, env/test_lf.tga, etc.) - ``farbox``: Far box distance, or "-" for none. Specifies the environment box behind all cloud layers. - ``nearbox``: Near box distance, or "-" for none. Specifies a box to be alpha blended on top of the clouds. sunfile ^^^^^^^ Sun configuration file. Takes a filename. Specifies the sun configuration to use for this sky. fogvars ^^^^^^^ Fog color and density. Takes the following arguments: - ``(r g b)`` - ``density`` skyfogvars ^^^^^^^^^^ Sky fog color and density. Takes the following arguments: - ``(r g b)`` - ``density`` Special Parameters __________________ portal ^^^^^^ Portal keyword for special surface effects. This is different from the surfaceparm portal which is for visibility optimization. radialNormals ^^^^^^^^^^^^^ Use radial normal calculation. Causes normals to be calculated radially from the center of the surface, useful for rounded objects like foliage, pillars, or curved surfaces. Stage Parameters ---------------- These parameters are specified within stage blocks ``{ ... }``. Texture Mapping _______________ map ^^^ Primary texture map. Takes a texture path. Specifies the source texture (24 or 32-bit TGA file) used for this stage. May contain alpha channel information. - Can use :ref:`special-textures` such as $lightmap, $whiteimage, $dlight - Texture modifiers (specified right after the ``map`` keyword): - ``clamp`` Prevent texture wrapping - ``clampx`` Prevent texture wrapping on X-axis - ``clampy`` Prevent texture wrapping on Y-axis - ``heightToNormal`` Convert height map to normal map animMap ^^^^^^^ Animated texture sequence. Takes the following arguments: - ``fps`` - ``tex1 tex2... texN`` cubemap ^^^^^^^ Use cubemap environment. Takes a texture path. Uses a cubemap for environment reflection mapping. Texture Coordinate Generation _____________________________ tcGen ^^^^^ Available operations: - ``environment``: Environment mapping. Uses a spherical reflection map for the texture coordinates. - ``reflection``: Reflection mapping. Uses a cubemap for dynamic environment reflections. - ``sunHalfAngle``: Sun half-angle. Used for bump mapping with sun direction. - ``lightmap``: Lightmap coordinates. Uses the precomputed lightmap texture coordinates. - ``vector``: Custom vector projection. Projects texture coordinates using two vectors: - ``(x y z)`` - ``(x y z)`` - ``base``: Base texture coordinates (default). Uses the standard texture coordinates from the mesh/brush. Texture Coordinate Modifiers ____________________________ tcMod ^^^^^ Available operations: - ``scale``: Scale. Multiplies the texture coordinates by the given values: - ``s`` - ``t`` - ``scroll``: Scroll. Animates the texture coordinates over time: - ``s`` Horizontal scroll speed - ``t`` Vertical scroll speed - ``rotate``: Rotate. Spins the texture coordinates around the origin: - ``degrees`` - ``stretch``: Stretch animation. Stretches texture coordinates using a wave function: - ``func`` wave function (sin, square, triangle, sawtooth, inversesawtooth, noise) - ``base`` base value - ``amplitude`` - ``phase`` phase offset - ``frequency`` - ``transform``: Full transformation matrix. Applies a complete 2D transformation: - ``m00`` - ``m01`` - ``m10`` - ``m11`` - ``t0`` - ``t1`` - ``turb``: Turbulence effect. Adds distortion/noise to texture coordinates: - ``base`` - ``amplitude`` - ``frequency`` - ``phase`` - ``bumpmapFrame``: Bump mapping frame calculation. Adjusts texture coordinates for bump mapping effects. Blending Functions __________________ Control how the stage blends with previous stages. Determines the blend mode used to combine this stage with the previous rendering result. blendFunc ^^^^^^^^^ Available operations: - ``blend``: Standard alpha blending. Equivalent to GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA. - ``add``: Additive blending. Equivalent to GL_SRC_ALPHA GL_ONE. Adds the source color to the destination. - ``filter``: Multiplicative blending. Multiplies source and destination colors for darkening effects. - ``GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA``: Standard alpha blending. The most common blend mode for transparency. - ``GL_SRC_ALPHA GL_ONE``: Additive blending. Brightens the destination. - ``GL_ONE GL_ONE``: Full additive. Adds all color components without modulation. - ``GL_DST_COLOR GL_ONE``: Modulate with destination. Multiplies source by destination color. - ``GL_ZERO GL_ONE_MINUS_SRC_COLOR``: Subtract from destination. Darkens the destination by subtracting source. - ``GL_ONE_MINUS_SRC_ALPHA GL_SRC_ALPHA``: Reverse alpha blend. Useful for special effects. RGB Generation ______________ Control how RGB color is generated for the stage. Determines the color source and calculation method. rgbGen ^^^^^^ Available operations: - ``identity``: Use texture colors as-is. The texture is rendered without color modification. - ``identityLighting``: Multiply by global lighting. Applies the global lighting scale to the texture colors. - ``vertex``: Use vertex alpha values. Alpha is taken from the vertex color alpha channel. Use vertex colors. Colors are taken from the vertex color data. - ``exactVertex``: Use exact vertex colors without lighting. Vertex colors are used directly without light calculation. - ``lightingDiffuse``: Apply diffuse lighting. Calculates lighting based on surface normals and light direction. - ``const``: Constant alpha. Uses a fixed alpha value: Constant color. Uses a fixed RGB color value: - ``(r g b)`` Values 0.0-1.0 - ``constLighting``: Constant alpha with lighting. Uses a fixed alpha value modulated by lighting. Constant color with lighting. Uses a fixed color modulated by lighting. - ``(r g b)`` - ``wave``: Wave-based alpha. Alpha is animated using wave functions: Wave-based color. Colors are animated using wave functions: - ``func`` - ``base`` - ``amplitude`` - ``phase`` - ``frequency`` - ``dot``: Dot product with vector. Colors are calculated from the dot product with a specified vector: - ``(r g b)`` - ``entity``: Entity alpha. Uses the alpha value specified on the entity. Entity color. Uses the color specified on the entity. - ``lightingPrecalc``: Pre-calculated lighting. Uses lighting data calculated during compilation. Alpha Generation ________________ Control how alpha is generated for the stage. Determines the alpha source and calculation method. alphaGen ^^^^^^^^ Available operations: - ``vertex``: Use vertex alpha values. Alpha is taken from the vertex color alpha channel. - ``const``: Constant alpha. Uses a fixed alpha value: - ``value`` 0.0-1.0 - ``constLighting``: Constant alpha with lighting. Uses a fixed alpha value modulated by lighting. - ``value`` - ``wave``: Wave-based alpha. Alpha is animated using wave functions: - ``func`` - ``base`` - ``amplitude`` - ``phase`` - ``frequency`` - ``entity``: Entity alpha. Uses the alpha value specified on the entity. - ``portal``: Portal alpha generation. Used in conjunction with the portal surfaceparm. Generates alpha values based on the distance from the viewer to the portal, creating a fade effect. Should be used on the last rendering pass. Alpha Function ______________ Alpha testing for transparency. Tests the alpha value of each pixel and discards those that don't pass the test. alphaFunc ^^^^^^^^^ Available operations: - ``GE128``: Render pixels with alpha >= 128 (0.5). Discards transparent pixels, keeps opaque ones. - ``LT128``: Render pixels with alpha < 128 (0.5). Discards opaque pixels, keeps transparent ones. - ``GT0``: Render pixels with alpha > 0. Renders any pixel that has some transparency. Depth Function ______________ Control depth buffer comparison. Determines when a pixel passes the depth test.. Determines the depth test function used for rendering this stage. depthFunc ^^^^^^^^^ Available operations: - ``equal``: Render only if depth matches. Only pixels at the exact same depth will be rendered. - ``always``: Always render (ignore depth). Pixels are always rendered regardless of depth. - ``less``: Render if closer (default). Renders pixels that are closer to the camera than the current depth buffer value. - ``lequal``: Render if closer or equal. Renders pixels that are at or closer than the current depth buffer value. Depth Writing _____________ depthWrite ^^^^^^^^^^ Write to depth buffer. When enabled, this stage will write its depth values to the depth buffer. When disabled, the depth buffer is unaffected by this stage. Texture Environment Combine ___________________________ Advanced texture combining for multi-texture cards. Allows for complex multi-texture operations using ARB texture env combine extensions. texEnvCombine ^^^^^^^^^^^^^ .. code-block:: shader texEnvCombine { const = (r g b a) rgb = OPERATION(Cp, Ct, Ac) alpha = OPERATION(Af, At) } Operations: - ``REPLACE_ARB``: Replace. Output = constant color. - ``MODULATE``: Multiply. Output = previous * current. - ``ADD``: Add. Output = previous + current. - ``ADD_SIGNED_ARB``: Add with signed bias. Output = previous + current - 0.5. - ``INTERPOLATE_ARB``: Interpolate. Linear interpolation between colors. - ``SUBTRACT_ARB``: Subtract. Output = previous - current. - ``DOT3_RGB_ARB``: Dot product (for bump mapping). Computes diffuse lighting from normal maps. Variables: - ``Cp``: Previous stage color - ``Ct``: Current texture stage color - ``Cc``: Constant color (from const) - ``Ac``: Constant alpha - ``Af``: Fragment alpha (from texture) - ``At``: Texture alpha Bundle System _____________ nextbundle ^^^^^^^^^^ Start a new texture bundle (multi-texturing). Allows multiple textures to be used in a single rendering pass. Textures in a bundle are combined before the final color is computed. Used for lightmaps, dynamic lights, etc. Multiply Image ______________ multiplyImage ^^^^^^^^^^^^^ Available operations: - ``identityLighting``: Multiply by identity lighting Requirements ____________ Require specific hardware/software capabilities for rendering the stage. If the requirements are not met, the stage will be skipped. requires ^^^^^^^^ - ``GL_MAX_TEXTURE_UNITS_ARB == n``: Require exactly n texture units - ``GL_MAX_TEXTURE_UNITS_ARB >= n``: Require at least n texture units - ``GL_ARB_texture_env_add``: Require ARB_texture_env_add extension - ``GL_ARB_texture_env_combine``: Require ARB_texture_env_combine extension - ``GL_ARB_texture_env_dot3``: Require ARB_texture_env_dot3 extension (for bump mapping) - ``GL_ARB_texture_cube_map``: Require ARB_texture_cube_map extension (for cubemap textures) .. _special-textures: Special Texture Variables _________________________ .. csv-table:: :header: "Name", "Description" :align: left "``$lightmap``", "Precomputed lightmap texture. Contains baked lighting information for the level." "``$dlight``", "Dynamic light texture. Contains lighting from moving/dynamic light sources." "``$whiteimage``", "Solid white texture. A plain white texture used for various effects." "``*white``", "Same as ``$whiteimage``" "``$renormalize``", "Renormalization cubemap. Used for normalizing normal vectors in bump mapping." "``$texturename``", "Variable replaced with actual texture name. Used in .stype files to reference the texture the shadertype is applied to."