View source for Depth buffer

[[File:r_depthoverlay.jpg|thumb|250px|Source's depth buffer is very limited]]

The '''depth buffer''' is a [[texture]] in which each on-screen pixel is assigned a greyscale value depending on its distance from the camera. This allows visual effects to easily alter with distance. It is used for [[Particle_System_Overview|soft particles]].

Source's depth buffer has a very short range of just 192 [[unit]]s, and is also squashed down to fit into a power of two [[render target]] (after having being generated in the alpha channel of the full [[w:backbuffer|backbuffer]]). It can be viewed with <code>r_depthoverlay</code>.

{{bug|hidetested=1|{{as}} <code>r_depthoverlay</code> is broken in Alien Swarm. To fix it, save the line "<code>showz {}</code>" to <code>materials/debug/showz.vmt</code>.}}

Alien Swarm allows you to easily modify the range of the depth buffer with the cvar ''mat_dest_alpha_range'', but the bit-depth and behaviour in regards to alpha tested geometry stays the same.

==Modifying Source's depth buffer texture==
[[File:Source_Depthbuffer_8bit.jpg|thumb|right|250px|Depth buffer with alpha tested geometry and a range of 20000 world units]]
The available output range of the depth buffer can be adjusted in every mod that is utilizing a custom shader library. A requirement is to solely render all opaque and alpha tested geometry in a scene with modified [[shaders]]; this can either be achieved by manually replacing all shaders used in every [[VMT]] file (optimal solution), reloading all materials at runtime (slow) or overriding the actual shader files used by a default shader dll (probably unstable). {{todo|Confirm the last option}}

{{note|Source SDK 2013 contains a procedure originally built for Pyrovision that renders a full depth buffer usable by mod shaders. The code is in viewrender.cpp in a method named <code>CBaseWorldView::SSAO_DepthPass()</code>. For an example of how to modify the source to take advantage of this code, [https://github.com/BSVino/DoubleAction/commit/0ded18e5d52ef199e766f5f703c9ab65ecf649a3 see this commit].}}

The following paragraphs will document how you can alter the public shaders to output a different depth buffer.


===Fixing alpha testing behaviour===
If you want to let alpha tested objects draw depth, you will have to change several things first. The Client copies the depth information from the backbuffer with a call to <code>UpdateFullScreenDepthTexture()</code> defined in view_scene.cpp, by default this happens before any translucents are drawn.

Firstly, navigate to
<source lang=cpp>void CRendering3dView::DrawTranslucentRenderables( bool bInSkybox, bool bShadowDepth )</source>
and move <code>UpdateFullScreenDepthTexture</code> from the switch at the beginning to the end, like this:
<source lang=cpp>	[...]
	// Draw the rest of the surfaces in world leaves
	DrawTranslucentWorldAndDetailPropsInLeaves( iPrevLeaf, 0, nEngineDrawFlags, nDetailLeafCount, pDetailLeafList, bShadowDepth );

	if ( g_CurrentViewID == VIEW_MAIN )
		UpdateFullScreenDepthTexture();

	// Draw any queued-up detail props from previously visited leaves
	DetailObjectSystem()->RenderTranslucentDetailObjects( CurrentViewOrigin(), CurrentViewForward(), CurrentViewRight(), CurrentViewUp(), nDetailLeafCount, pDetailLeafList );

	// Reset the blend state.
	render->SetBlend( 1 );
}</source>
{{tip|This will break soft particles. Instead, you should split the function in half; either draw alpha tested objects first or particles at the very end and do the depth buffer copy in-between.}}


To make alpha tested objects draw to the alpha channel in the first place, you need to modify the implementation and the actual shader file of each shader in question first. The following examples will explain it with the help of the vertexlitgeneric shader:


In <code>vertexlitgeneric_dx9_helper.cpp</code> search for:
<source lang=cpp>			pShaderShadow->EnableAlphaTest( bIsAlphaTested );

			if ( info.m_nAlphaTestReference != -1 && params[info.m_nAlphaTestReference]->GetFloatValue() > 0.0f )
			{
				pShaderShadow->AlphaFunc( SHADER_ALPHAFUNC_GEQUAL, params[info.m_nAlphaTestReference]->GetFloatValue() );
			}</source>
and replace it with:
<source lang=cpp>			pShaderShadow->EnableAlphaTest( bIsAlphaTested );
			if ( bIsAlphaTested  )
				pShaderShadow->AlphaFunc( SHADER_ALPHAFUNC_GREATER, 0 );</source>
This will cause the pixelshader to actually draw unless its alpha output value is exactly null.

Now search for the line:
<source lang=cpp>	pShaderShadow->EnableAlphaWrites( bFullyOpaque );</source>
and change it to:
<source lang=cpp>	pShaderShadow->EnableAlphaWrites( bFullyOpaque || bIsAlphaTested );</source>
This change will allow writing to the alpha channel of the current target for alpha tested materials.


The shader file, in this case SDK_vertexlit_and_unlit_generic_ps2x.fxc, needs to reflect the new behaviour; change the very end to look like this:
<source lang=cpp>	float4 color = FinalOutputConst( float4( result.rgb, alpha ), fogFactor, g_fPixelFogType, TONEMAP_SCALE_LINEAR, g_fWriteDepthToAlpha, i.projPos.z );
	color.a *= round( alpha );
	return color;</source>
This replaces the alpha testing reference, if the actual alpha value from the texture is smaller than 0.5f, we will have transparency at this pixel, otherwise the value stays unmodified and represents the depth range instead.
{{tip|Add a new alpha testing reference per shader constant if you want it to be variable again.}}

===Scaling the depth output===

The depth information drawn to the backbuffer is scaled by the following factor found in <code>src\materialsystem\stdshaders\common_ps_fxc.h</code>:

 <span style="color:blue;">#define</span> <span style="color:brown;">OO_DESTALPHA_DEPTH_RANGE</span> (g_LinearFogColor.w)

Changing the definition of the constant g_LinearFogColor would also result in a different range, but it seems to be inaccessible from the publicly available source code.
The value describes how the homogenous depth is transformed into normalized space, so if one was to describe the whole scene in the alpha channel, the value should be <code>1 / (zFar - zNear)</code>, otherwise you should use <code>1 / desired_range</code> to calculate your constant, keep in mind that your interval starts at zNear (default 7).

====Scaling the depth output to the whole scene====

----

To make this value flexible and automatically describe your whole range, you can add a float rendering parameter to <code>renderparm.h</code>:
<source lang=cpp>//#define MAX_FLOAT_RENDER_PARMS 20
enum RenderParamFloat_t
{
	FLOAT_RENDERPARM_ZDELTA = 0,

	MAX_FLOAT_RENDER_PARMS = 20
};</source>

In <code>viewrender.cpp</code> find the function
<source lang=cpp>void CViewRender::DrawWorldAndEntities( bool bDrawSkybox, const CViewSetup &viewIn, int nClearFlags, ViewCustomVisibility_t *pCustomVisibility )</source>
and add this to the top:
<source lang=cpp>	CMatRenderContextPtr pRenderContext( materials );
	pRenderContext->SetFloatRenderingParameter( FLOAT_RENDERPARM_ZDELTA, (viewIn.zFar - viewIn.zNear) );</source>
Since pixelshader constants are mostly not consistent across individual shaders, you might have to to define a constant for each shader by hand. For <code>SDK_vertexlit_and_unlit_generic_ps2x.fxc</code> it could be done like this:

<code>common_ps_fxc.h</code>
<source lang=cpp>#ifdef DEPTH_GET_CUSTOM_RANGE
#	define OO_DESTALPHA_DEPTH_RANGE DEPTHRANGE_CONSTANT
#else
#	define OO_DESTALPHA_DEPTH_RANGE (g_LinearFogColor.w)
#endif</source>
<code>SDK_vertexlit_and_unlit_generic_ps2x.fxc</code>
<source lang=cpp>#define DEPTH_GET_CUSTOM_RANGE
const float g_DepthRange			: register( c14 ); //you can also add the float to another existing constant this way, depends on the shader
#define DEPTHRANGE_CONSTANT g_DepthRange
#include "common_fxc.h"
</source>
<code>vertexlitgeneric_dx9_helper.cpp</code>
<source lang=cpp>
DYNAMIC_STATE
{
	[...]
	float zDelta = pShaderAPI->GetFloatRenderingParameter( FLOAT_RENDERPARM_ZDELTA );
	float g_const14[4] = { zDelta, 0.0f, 0.0f, 0.0f };
	DynamicCmdsOut.SetPixelShaderConstant( 14, g_const14, 1 );

	DynamicCmdsOut.End();
}
</source>

{{Note|By default the output is compressed to 8-bit precision, this will cause heavy [[w:colour banding|colour banding]] when a long range is used.}}


===Fixing the depth buffer texture===

The rendertarget named <code>_rt_FullFrameDepth</code> is supposed to contain the depth information, it seems to be an internal alias to the texture <code>_rt_PowerOfTwoFB</code> though. For that reason it may be better to create a new seperate rendertarget instead:
In <code>view.cpp</code> navigate to the function:
<source lang=cpp>void CViewRender::Init( void )</source>
You can add this snippet to quickly allocate a new rendertarget:
<source lang=cpp>		ITexture *depthOld = materials->FindTexture( "_rt_FullFrameDepth", TEXTURE_GROUP_RENDER_TARGET );
		static int flags = TEXTUREFLAGS_NOMIP | TEXTUREFLAGS_NOLOD | TEXTUREFLAGS_RENDERTARGET;
		if ( depthOld )
			flags = depthOld->GetFlags();

		int iW, iH;
		materials->GetBackBufferDimensions( iW, iH );
		materials->BeginRenderTargetAllocation();
		ITexture *p = materials->CreateNamedRenderTargetTextureEx(
				"_rt_FullFrameDepth_Alt",
				iW, iH, RT_SIZE_NO_CHANGE,
				IMAGE_FORMAT_A8,
				MATERIAL_RT_DEPTH_NONE,
				flags,
				0);
		materials->EndRenderTargetAllocation();</source>

To reference this new texture properly, open <code>rendertexture.cpp</code> and go to:
<source lang=cpp>	ITexture *GetFullFrameDepthTexture( void )</source>
By default this function searches for <code>_rt_FullFrameDepth</code>; change this string to read <code>_rt_FullFrameDepth_Alt</code> instead.


==INTZ Depth==
[[File:Intz_csgo.jpg|thumb|right|250px|Preview of <code>INTZ</code> Depth in [[CS:GO]], shown on [[mat_texture_list]] ]]
As an alternative, you can unbind Alias and use <code>_rt_FullFrameDepth</code> for its intended purpose, as in [[Counter-Strike: Global Offensive engine branch]], using <code>IMAGE_FORMAT_NV_INTZ</code> for [[Team Fortress 2 engine branch]] and <code>IMAGE_FORMAT_INTZ</code> for [[Counter-Strike: Global Offensive engine branch]]. <code>INTZ</code> is a [https://aras-p.info/texts/D3D9GPUHacks.html D3D9 HACK] that will allow you to write hardware depth as a color texture. You also won't have to rewrite shaders. For example, depth is typically obtained through [https://learn.microsoft.com/en-us/windows/win32/direct3d9/multiple-render-targets Multi Render Target (MRT)], using [[Deferred renderer]]. But <code>INTZ</code> will help you to get depth concisely even without an '''MRT'''. See [https://github.com/ValveSoftware/source-sdk-2013/pull/1914/changes implementation on Source SDK 2013].

<source lang=cpp>
materials->RemoveTextureAlias("_rt_FullFrameDepth"); // _rt_FullFrameDepth is Alias of _rt_PowerOfTwoFB on PC

materials->BeginRenderTargetAllocation();
materials->CreateNamedRenderTargetTextureEx("_rt_FullFrameDepth", 1, 1,
    RT_SIZE_FULL_FRAME_BUFFER,
    IMAGE_FORMAT_NV_INTZ,
    MATERIAL_RT_DEPTH_NONE,
    TEXTUREFLAGS_CLAMPS | TEXTUREFLAGS_CLAMPT | TEXTUREFLAGS_POINTSAMPLE,
    CREATERENDERTARGETFLAGS_NOEDRAM
);
materials->EndRenderTargetAllocation();
</source>

----
[[File:mcv_softblend.jpg|thumb|right|250px|<code>INTZ</code> depth usage for [[Particle_System_Overview|soft particle]] blend from [https://www.dmitrex.com/publications/Enhancing%20the%20looks%20of%20Source%20Engine%20in%20Military%20Conflict%20Vietnam.pdf MC:V White paper] ]]
<code>INTZ</code> pros:
* Soft [[particles]]. It is a very old engine feature. It requires high precision depth buffer which [[Source]] always had problems with. It implemented in {{mcv|2}}.
used high-precision 24-bit hardware <code>INTZ</code> depth buffer with 8 additional bits reserved for stencil.
* Works both with '''Forward rendered''' and [[Deferred renderer]]. This way you can save 1 channel of '''MRT''' texture.
* This will allow you to obtain a depth buffer for shaders without resorting to double-rendering of scene, as in Pyro Vision on <code>_rt_ResolvedFullFrameDepth</code>.


<code>INTZ</code> disadvantages:
* Depth storing without [[MSAA]]. As <code>_rt_ResolvedFullFrameDepth</code> and as any other depth.
* [[MSAA]] is disabled for the main scene. This can be avoided if you're an engine developer. By using <code>NVCS</code> as [https://github.com/NVIDIA/nvapi/blob/9b181ea572f680327fe01a14a0f1f41c78034104/nvapi_interface.h#L228 NvAPI_D3D9_StretchRectEx] from [https://developer.nvidia.com/nvapi/get-started NVAPI SDK]. For Intel and AMD, you can use <code>RESZ</code> texture format.<br>

==Resolved Full Frame Depth==
[[File:Resolvedepth_gmod.jpg|thumb|right|250px|Preview of <code>_rt_ResolvedFullFrameDepth</code> Depth with <code>IMAGE_FORMAT_R32F</code> in [[Garry's Mod]], shown on [[mat_texture_list]] ]]
<code>CBaseWorldView::SSAO_DepthPass()</code> runs extra drawing of scene to store depth, using [[DepthWrite]] with enabled [[$color_depth]] on material, and writes <code>_rt_ResolvedFullFrameDepth</code> as colored depth: {{csgobranch|4}} outputs <code>ProjPosZ / ProjPosW</code>, while {{tf2branch|4}} outputs <code>ProjPosW / 4000</code>. <code>4000</code> is a magic number. By default, <code>_rt_ResolvedFullFrameDepth</code> has the <code>IMAGE_FORMAT_RGBA8888</code> format, which causes banding in usage. Therefore, we need to upgrade the [[VTF_(Valve_Texture_Format)|texture format]] by recreating the [[render target]]. It has only a red channel, so it is acceptable to use <code>IMAGE_FORMAT_R32F</code>.

<source lang=cpp>
materials->BeginRenderTargetAllocation();

materials->CreateNamedRenderTargetTextureEx("_rt_ResolvedFullFrameDepth", 1, 1,
    RT_SIZE_FULL_FRAME_BUFFER,
    IMAGE_FORMAT_R32F,
    MATERIAL_RT_DEPTH_SEPARATE,
    TEXTUREFLAGS_CLAMPS | TEXTUREFLAGS_CLAMPT | TEXTUREFLAGS_POINTSAMPLE,
    CREATERENDERTARGETFLAGS_NOEDRAM
);

materials->EndRenderTargetAllocation();
</source>

Now we can use <code>_rt_ResolvedFullFrameDepth</code> to retrieve <code>ProjPosW</code> in the [[shader]] code as follows:
<source lang=hlsl>
float ProjPosW = tex2D(ResolvedDepth, i.TexCoord).r * 4000.0f; // Removing the division by 4000 from the DepthWrite shader in Source SDK 2013.
float linear_depth = 1.0f / ProjPosW;
</source>
[[Category:Source]]

[[Category:Material System]]