Editing Darkplaces material system/General Keywords

{{navigation title|Darkplaces material system|General Keywords|Special Keywords}}
==surfaceparm==

This is, by the fact, most widely used and most tricky material keyword.

All surfaceparm keywords are preceded by the word ''surfaceparm'' as follows: ''surfaceparm nonsolid'' or ''surfaceparm trans''. Each surfaceparm have corresponding q3map_''surfaceparmname'' keyword ('''q3map_nonsolid''', '''q3map_trans''' etc.) which is only acquired by Q3map2. Surfaceparm keywords change the physical nature of the materials and the brushes that are marked with them. Changing any of these values will likely require the map to be re-compiled. These are global and affect the entire shader.

This document skips all Q3map2 surfaceparms that is not used by Blood Omnicide.

===General surfaceparms===

'''surfaceparm alphashadow'''
:This keyword applied to a side on a brush, patch or model will cause the lighting phase of the Q3Map2 process to use the texture's alpha channel as a mask for casting static shadows in the game world.
:Used by Q3map2 light phase.
:{{design|Alphashadow does not work well with fine line detail on a texture. Fine lines may not cast acceptable shadows. It appears to work best with well-defined silhouettes and wider lines within the texture. It is possible to increase the resolution of the lightmap receiving the shadows with a slight the cost of memory. This can be achieved with the '''q3map_lightmapSampleSize''' keyword on the shadow receiving shader or by creating a [[func_group]] of the shadow receiving brushes and adding the '''_ls''' key with a floating-point value for the scale of the lightmap.}}

'''surfaceparm detail'''
:This surface attribute causes a brush to be ignored by the Q3Map2 process for generating possible break-points in the BSP tree. It functionality is same as marking brush as detail in level editor.
:Used by Q3map2 BSP phase

'''surfaceparm lava'''
:Assigns to the material the game properties set for lava. This affects contents of the brush.
:Used by engine (BIH collision) and q3map2 (bsp phase).
:{{design|This keyword is used on common/ilava material.}}

'''surfaceparm lightfilter'''
:Use the texture's RGB and alpha channels to generate colored alpha shadows in the lightmap. For example, this can be used to create the colored light effect cast by stained glass windows. This can be used with surfaceparm alphashadow.
:Used by Q3map2 light phase.

'''surfaceparm nodraw'''
:Prevents Q3map2 from generating drawsurfaces for this material.
:Used by Q3map2 BSP phase.

'''surfaceparm nomarks'''
:Prevents engine from spawning decals for this surface.
:Used by engine renderer.
:{{design|Use this on any surface with a deformVertexes keyword. Otherwise, the marks will appear on the unmodified surface location of the texture with the surface wriggles and squirms through the marks.}}

'''surfaceparm nolightmap'''
:This surface will have no lightmap generated. This will save some memory and make map compilation faster.
:Used by Q3map2 light phase.
:{{design|This keyword have no effect at vertex-based lighting (lighting calculated for vertices and being saved to their rgba attributes). Surface with no lightmap will be rendered with vertex-based lighting. To disable vertex lignting calculation, use '''q3map_noVertexLight''' keyword.{{

'''surfaceparm nonsolid'''
:Surface does not block the movement of entities in the game world. This affects the content of a brush. This still make q3map2 generate collision surfaces.
:Used by engine ([[BIH]] collision) and q3map2 (bsp phase).

'''surfaceparm slime'''
:Assigns to the material the game properties set for slime. In Blood Omnicide, slime is a swamp.
:Used by engine (BIH collision) and q3map2 (bsp phase). 
:{{design|This keyword is used on common/islime material.}}

'''surfaceparm trans'''
:Tells Q3Map2 that pre-computed visibility should not be blocked by this surface. 
:Used by q3map2 BSP phase. 
:{{design|Any materials that have blendfunc's should be marked as surfaceparm trans (anything behind them will not get culled).}}

'''surfaceparm water'''
:Assigns to the material the game properties set for water. This affects both the surface and the content of a brush.
:Used by engine (BIH collision) and q3map2 (bsp phase).
:{{design|This keyword is used on '''common/iwater''' material.}}

===System surfaceparms===
This is surfaceparms is only used in [[common materials]]. You dont need to specify them on your new materials.

'''surfaceparm hint'''
:When Q3Map2 calculates the vis data, it tries to place portals in places in the map in an attempt to limit the potential viewable set ([[PVS]]). Brushes marked by a hint shader are used to manually place portals to force a break in the PVS.
:Used by Q3map2 BSP phase. This keyword is used on '''common/hint''' material.

'''surfaceparm monsterclip'''
:Surface with this flag will block NPC movement. Should be used with '''surfaceparm nonsolid'''.
:Used by engine (collision). This keyword is used on '''common/monsterclip''' material. You dont need to specify it on your new materials.

'''surfaceparm lightgrid'''
:The min/max bounds of brushes with this material in a map will define the bounds of the map's [[Lightgrid]].
:Used by Q3map2 light phase. This keyword is used on '''common/lightgrid''' material. You dont need to specify it on your new materials.

'''surfaceparm playerclip'''
:Surface with this flag will block player movement. Should be used with '''surfaceparm nonsolid'''.
:Used by engine (collision). This keyword is used on '''common/playerclip''' material.

'''surfaceparm origin'''
:Rotating entities need to contain an origin brush in their construction. The brush must be rectangular (or square). The origin point is the exact center of the origin brush.
:Used by q3map2 BSP phase. This keyword is used on '''common/origin''' material

'''surfaceparm structural'''
:This surface attribute causes a brush to be seen by the Q3Map2 process as a possible break-point in a BSP tree. It is used as a part of common/hint material. Generally speaking, any opaque material not marked as "detail" is, by default, structural, so you shouldn't need to specify this.
:Used by q3map2 BSP phase.

===Custom surfaceparms===

This surface parameters are defined by [[custinfoparms.txt]] and used to assign a game-related properties to material, such as hit effect and step sound.

Blood Omnicide have this game-physics materials:

* grass 
* ice
* dirt
* wood
* oldwood
* ground
* sand
* dullmetal
* brookwater
* glass
* fur
* marble
* hay
* slate
* flesh
* metal
* oldmetal
* stone
* oldstone
* plan

{{important|Blood Omnicide allows only one game-physics surfaceparm per material.}}

==cull none==

Every surface of a polygon has two sides, a front and a back. Typically, we only see the front side. For example, a solid block you only show the front side. In some situations we see both (grates, screens etc.).

To "cull" means to remove. This keyword allows to disable side culling, so both sides of the surfaces would be visible.

{{tip|[[realtime lighting | Realtime lighting]] and lightmaps dont work well with twosided surfaces, caused back side to be lit same as front. To avoid that, should create two one-sided surfaces in game.}}

{{design|When making things like grates and screens with [[Brush | brushes]], put the texture with the cull none property on one face only. On the other faces, use a non-drawing texture.}}

==noPicMip==
This causes the texture to ignore '''r_picmip''' cvar. The image will always be high resolution. Applicate to a small low-resolution textures that will be overblurred with r_picmip. Not used in Blood Omnicide.
{{bug|Darkplaces can crash if texture have DDS file with no mipmap layers generated and allowed for mipmaps in material. Use this keyword to suppress that.}}

==noMipMaps==
Implies noPicMip. Also prevents the generation of any lower resolution mipmaps for use by the 3D card. This saves 25% of memory used to store this texture (both RAM and VRAM).

==deformVertexes==

This function performs a general deformation on the surface's vertexes, changing the actual shape of the surface before drawing the material. You can stack multiple deformVertexes commands to modify positions in more complex ways, making an object move in two dimensions, for instance.

===deformVertexes <nowiki><wave> <div> <func> <base> <amplitude> <phase> <freq></nowiki> ===
:Designed for water surfaces, modifying the values differently at each point. It accepts the standard [[Darkplaces material system/Key Concepts#Waveform_Functions | waveform functions]].
:The "div" parameter is used to control the wave "spread" - a value equal to the tesselation distance (see q3map_tessSize, a subdivision size, in game units, used for the material when seen in the game world).

===deformVertexes normal <nowiki><div> <func> <base> <amplitude ~0.1-~0.5> <frequency ~1.0-~4.0></nowiki>===
:This deformation affects the normals of a vertex without actually moving it, which will effect later material options like lighting (especially specular) and environment mapping (see stage specific keywords for tcGen environment). If the materialdon't use normals in any of their calculations, there will be no visible effect.

:'''IMPORTANT NOTE''': In Darkplaces, offset mapping uses vertex normals for the calculations. deformVertexes normal most likely will mess it up.
:'''Design Notes''': Putting values of 0.1 t o 0.5 in Amplitude and 1.0 to 4.0 in the Frequency can produce some satisfying results.

===deformVertexes bulge <nowiki><bulgeWidth> <bulgeHeight> <bulgeSpeed></nowiki>===
:This forces a bulge to move along the given S and T directions. Designed for use on curved pipes.

===deformVertexes move <nowiki><x> <y> <z> <func> <base> <amplitude> <phase> <freq></nowiki>===
:This keyword is used to make a brush, curve patch or model appear to move together as a unit. The <x> <y> and <z> values are the distance and direction in game units the object appears to move relative to it's point of origin in the map.
:The product of the function modifies the values x, y, and z. Therefore, if you have an amplitude of 5 and an x value of 2, the object will travel 10 units from its point of origin along the x axis. This results in a total of 20 units of motion along the x axis, since the amplitude is the variation both above and below the base.
:It must be noted that an object made with this shader does not actually change position, it only appears to.
:{{design|If an object is made up of surfaces with different shaders, all must have matching deformVertexes move values or the object will appear to tear itself apart.}}

===deformVertexes autosprite===
:This function can be used to make any given triangle quad (pair of triangles that form a square rectangle) automatically behave like a [[sprite]] without having to make it a separate entity. This means that the "sprite" on which the texture is placed will rotate to always appear at right angles to the player's view as a sprite would. Any four-sided brush side, flat patch, or pair of triangles in an .md3 model can have the autosprite effect on it. The brush face containing a texture with this shader keyword must be square.
:{{design|This is best used on objects that would appear the same regardless of viewing angle. An example might be a glowing light flare.}}

===deformVertexes autosprite2===
:Is a slightly modified "sprite" that only rotates around the middle of its longest axis. This allows you to make a pillar of fire that you can walk around, or an energy beam stretched across the room.

===Specific parameter definitions for deform keywords===

'''div'''
:This is roughly defined as the size of the waves that occur. It is measured in game units. Smaller values create a greater density of smaller wave forms occurring in a given area. Larger values create a lesser density of waves, or otherwise put, the appearance of larger waves. To look correct this value should closely correspond to the value (in pixels) set for tessSize (tessellation size) of the texture. A value of 100.0 is a good default value (which means your tessSize should be close to that for things to look "wavelike").

'''func'''
:This is the type of wave form being created. Sin stands for sine wave, a regular smoothly flowing wave. Triangle is a wave with a sharp ascent and a sharp decay. It will make a choppy looking wave forms. A square wave is simply on or off for the period of the frequency with no in between. The sawtooth wave has the ascent of a triangle wave, but has the decay cut off sharply like a square wave. An inversesawtooth wave reverses this.

'''base'''
:This is the distance, in game units that the apparent surface of the texture is displaced from the actual surface of the brush as placed in the editor. A positive value appears above the brush surface. A negative value appears below the brush surface. An example of this is the Quad effect, which essentially is a shell with a positive base value to stand it away from the model surface and a 0 (zero) value for amplitude.

'''amplitude'''
:The distance that the deformation moves away from the base value. See Wave Forms in the introduction for a description of amplitude.

'''phase'''
:See Wave Forms in the introduction for a description of phase.

'''frequency'''
:See Wave Forms in the introduction for a description of frequency.

{{tip|The <nowiki><div></nowiki> and <nowiki><amplitude></nowiki> parameters, when used in conjunction with liquid volumes like water should take into consideration how much the water will be moving. A large ocean area would have have massive swells (big div values) that rose and fell dramatically (big amplitude values). While a small, quiet pool may move very little.}}

==dpMeshCollisions==
Use surface's draw geometry for collision detection instead of generated BSP geometry (some models have no one). This works only if [[BIH]] is enabled.

==dpPolygonOffset &lt;factor&gt; &lt;offset&gt;==
Allows arbitrary offsets of a surface's depth during rendering. Material with this keyword are able to stack over rest of geometry with no [[Radiant Glossary | z-fighting]]. Useful for decals.

Both parameters are optional, if not used, a default factor of 0 and offset -2 is used.

{{tip|mod_q3shader_default_polygonfactor and mod_q3shader_default_polygonoffset controls default values.}}

==dpTransparentSort <nowiki><sort></nowiki>==
Rendering of blended materials requires software sorting to keep the depth order of geometry. This keyword changes default distance sorting to allow for special effects.
* '''distance''' : default distance-based sorting
* '''hud''' : this surface will always be ontop of all another blended materials
* '''sky''' : opposite to hud, this surface will always ve vehing all other blender materials.

==Per-Pixel Lightning==
This keywords controls various parameters used by per-pixel lighting of a surface.

===dpShadow===
Forces this material to be shadow caster even if it's blended or not drawn (blended surfaces by default is not casting shadows).
{{tip|This keyword is useful in creating '''shadow meshes''' a meshes that is invisible (and having lower polycont) but used for shadow casting.}}

===dpNoShadow===
Discards material from shadow casting.

===dpNoRtlight===
Disables any realtime lighting on a surface.

===dpGlossIntensityMod <nowiki><value></nowiki>===
Multiplies [[gloss]] intensity of this material. Default value is 1; 0.5 will halve gloss effect intensity, 2.0 will double it etc. This are used ontop on base gloss intensity set by a texture's _gloss color.

===dpGlossExponentMod <nowiki><value></nowiki>===
Scales gloss exponent for a surface. Gloss exponent controls how sharp gloss effect is. Low values will make surface matte, higher values will make it look like a covered by a plastic film. Just like intensity mod, this is a multiplier to a value in texture's _gloss alpha (if there is no alpha - base gloss exponent is forced to be 1).

Typical values are 0.25 (wood), 2.0 (glass).

===dpRtlightAmbient <nowiki><value></nowiki>===
Smooths out shading of a surface by adding amount of ambient light. This is useful on very grude and lowpoly surfaces (such as grass) because strong shading will show artefacts caused by low detalisation of a mesh.

==Reflection and refraction==
This material keywords allows to add refraction and reflection effects to a surface. All reflective and refractive effects are part of water shader, so they are only visible when '''r_water''' cvar is 1.

===dpReflect <nowiki><distortion> <r> <g> <b> <a></nowiki>===
Make this material reflective. The reflection is alpha blended on the texture with the given alpha, and modulated by the given color. Distort is used in conjunction with the normalmap to simulate a nonplanar water surface.
{{important|This is a 'hard' shader that requires much computation time. Abuse of this will slowdown rendering.}}

===dpRefract <nowiki><distortion> <r> <g> <b></nowiki>===
Works pretty same as reflection and can be combined with it (though it's not good). The refraction replaces the transparency of the texture. Distort is used in conjunction with the normalmap to simulate a nonplanar water surface.

===dpWater <nowiki><reflectmin> <reflectmax>  <refractdistort> <reflectdistort>  <refractR> <refractG> <refractB>  <reflectR> <reflectG> <reflectB>  <alpha></nowiki>===
Add a water shader to a material. This combines the effects of dpreflect and dprefract to simulate a water surface. However, the refraction and the reflection are mixed using a Fresnel equation that makes the amount of reflection slide from reflectmin when looking parallel to the water to reflectmax when looking directly into the water. The result of this reflection/refraction mix is then layered BELOW the texture of the shader, so basically, it "fills up" the alpha values of the water. The alpha value is a multiplicator for the alpha value on the texture (set this to a small value like 0.1) to emphasize the reflection and make the water transparent; but if r_water is 0, alpha isn't used, so the water can be very visible then too.

Typical usage:
 dpwater  0.4 1.0   0.3 1.0   0.28 0.21 0.18   0.80 0.76 0.65   0.0

===dpWaterScroll <nowiki><speedScale> <globalScale></nowiki> ===
Animate surface normalmap in water shader by duplicating it, scrolling, offsetting and multiplying the layers.
{{tip|Globalscale affects speed.}}

===dpCamera===
Flags this surface as camera surface. Used to make portal effects like ones seen in Pray. Not used in Blood Omnicide.

===dpReflectCube <nowiki><cubemap></nowiki>===
Sets static [[cubemap]] texture for reflections. 
{{important|A _reflect [[skinframe]] texture sets local intensity of reflections and should be presented in order effect to work.}}
{{tip|Cubemapped reflections alot faster than realtime ones.}}

Typical usage:

 dpreflectcube textures/environment/reflect1

==Shader Kill==
This keywords are used to hide this material (as if it has no stages) under certain circumstances. Only affects visual appearance of material, not collisions or contents.

===dpShaderKillIfCvar <nowiki><cvar> <operator> <value></nowiki>===
Kills this material is [[CVar | cvar]] matches a value.
 <font color=green>// kill this shader if r_foo is 42</font>
 dpshaderkillifcvar r_foo == 42
Operators are:
* '''==''' - equal
* '''!=''' - not equal
* '''>''' - greater
* '''>=''' - greater or equal
* '''<''' - lesser
* '''<=''' - lesser or equal

===dpNoShaderKillIfCvar <nowiki><cvar> <operator> <value></nowiki>===
Prevents material from being killed. Have a priority over dpshaderkillifcvar.

===dpShaderKillIfCvarZero <nowiki><cvar></nowiki>===
Kills material is supplied cvar's float value is 0.

===dpNoShaderKillIfCvarZero <nowiki><cvar></nowiki>===
Opposite to above.