Parallax Corrected Cubemaps: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
mNo edit summary
 
(22 intermediate revisions by 11 users not shown)
Line 1: Line 1:
== What Is This? ==
{{LanguageBar|title = Parallax Corrected Cubemaps}}
By default, Source's cubemaps are naively reflected on the ground, and do not follow the player's perspective. This causes an unrealistic-looking reflection for most surfaces. A possible solution can be to parallax-correct the cubemaps based on the player's camera position, using a custom shader and a bounding box trigger for a cubemap. This tutorial, based directly on the work of Brian Charles, will show you how to do just that.


Brian Charles' video that showcases the before and after of this tutorial can be found here: [https://www.youtube.com/watch?v=ZH6s1hbwoQQ Parallax Corrected Cubemaps in the Source Engine]
{{For|2={{ent|parallax_obb}}|1=the third-party Source brush entity responsible for setting cubemap boundaries}}
{{For|2={{ent|env_cubemap_box}}|1=the Source 2 point entity responsible for both creating both the cubemap and parallax bounding box}}


== The Code ==
[[File:PCC comparison.jpg|400px|thumb|right|<center>'''Comparison of PCC'''</center>]]


Before starting, we'll need this file:
==Overview==
{{src|1.bold}}'s native [[cubemap]] implementation does not allow them to follow the player's perspective. While this is passable in most cases, tying the reflections to the player's view can increase realism, especially when using high-resolution reflections. A method to achieve this is called ''parallax correction''.


* [https://gist.github.com/GamerDude27/18bd775198602ddebeee8a9ee1aa8ebf matrixinvert.h]
Parallax-corrected cubemaps use a [[parallax_obb|bounding box]] brush to bake their reflection based on a specified area around them, and a custom [[shader]] to make use of it.


This tutorial is based on the work of Brian Charles. A demonstration video can be found here: {{youtube|ZH6s1hbwoQQ|page=watch|Parallax Corrected Cubemaps in the Source Engine}}.


Which you'll put into '''src/utils/vbsp/'''
==The Code==
First, the file
* [[Parallax Corrected Cubemaps/matrixinvert.h|matrixinvert.h]]


should be added to {{path|<nowiki><src code directory>/src/utils/vbsp/</nowiki>}}.


Now let's jump right into it, shall we?
Next, open the project solution ({{path|everything|sln|icon=file}}) and navigate to {{path|<nowiki>/utils/vbsp/cubemap</nowiki>|cpp}}.


Go into your '''everything.sln''' solution and open '''cubemap.cpp'''
===cubemap.cpp===
Add the following below the <code>SideHasCubemapAndWasntManuallyReferenced( int iSide )</code> function:
<syntaxhighlight lang="cpp">
char *g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];
</syntaxhighlight>


=== cubemap.cpp ===
Then, modify the <code>CubeMap_InsertSample( ... )</code> function declaration as follows:
<syntaxhighlight lang="cpp">
void Cubemap_InsertSample( const Vector &origin, int size, char *pParallaxObbStr = "" )
</syntaxhighlight>


Now add this under (not inside) the '''SideHasCubemapAndWasntManuallyReferenced(...)''' function:
At the top of the function body, add:
<pre>
<syntaxhighlight lang="cpp">
char* g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];
</pre>
 
Then right below, change the '''CubeMap_InsertSample''' function to look like this:
<pre>
void Cubemap_InsertSample( const Vector& origin, int size, char* pParallaxObbStr = "" )
</pre>
And inside that function, at the very top add this:
<pre>
g_pParallaxObbStrs[g_nCubemapSamples] = pParallaxObbStr;
g_pParallaxObbStrs[g_nCubemapSamples] = pParallaxObbStr;
</pre>
</syntaxhighlight>


Now go down to the '''PatchEnvmapForMaterialAndDependents''' function and change it to look like this:
Update the <code>PatchEnvmapForMaterialAndDependents( ... )</code> function declaration to:
<pre>
<syntaxhighlight lang="cpp">
static bool PatchEnvmapForMaterialAndDependents( const char *pMaterialName, const PatchInfo_t &info, const char *pCubemapTexture, const char *pParallaxObbMatrix = "" )
static bool PatchEnvmapForMaterialAndDependents( const char *pMaterialName, const PatchInfo_t &info, const char *pCubemapTexture, const char *pParallaxObbMatrix = "" )
</pre>
</syntaxhighlight>
While in the same function, scroll a tiny bit down to '''if (pDependentMaterial)''' and change the line in it to this:
 
<pre>
Within the <code>if ( pDependentMaterial )</code> statement, change the code to:
bDependentMaterialPatched = PatchEnvmapForMaterialAndDependents( pDependentMaterial, info, pCubemapTexture, pParallaxObbMatrix );
<syntaxhighlight lang="cpp">
</pre>
bDependentMaterialPatched = PatchEnvmapForMaterialAndDependents( pDependentMaterial, info, pCubemapTexture, pParallaxObbMatrix );
Scroll a tiny bit down again until you find this line:
</syntaxhighlight>
<pre>
 
MaterialPatchInfo_t pPatchInfo[2];
Change
</pre>
<syntaxhighlight lang="cpp">
Then just change 2 to 6, like so:
MaterialPatchInfo_t pPatchInfo[2];
<pre>
</syntaxhighlight>
MaterialPatchInfo_t pPatchInfo[6];
to:
</pre>
<syntaxhighlight lang="cpp">
Do another tiny scroll down, and above this line:
MaterialPatchInfo_t pPatchInfo[6];
<pre>
</syntaxhighlight>
char pDependentPatchedMaterialName[1024];
 
</pre>
Above the line
Add:
<syntaxhighlight lang="cpp">
<pre>
char pDependentPatchedMaterialName[1024];
// Parallax cubemap matrix
</syntaxhighlight>
CUtlVector<char *> matRowList;
add:
if ( pParallaxObbMatrix[0] != '\0' )
<syntaxhighlight lang="cpp">
{
// Parallax cubemap matrix
V_SplitString(pParallaxObbMatrix, ";", matRowList);
CUtlVector<char *> matRowList;
if ( pParallaxObbMatrix[0] != '\0' )
{
V_SplitString( pParallaxObbMatrix, ";", matRowList );
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB1";
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB1";
pPatchInfo[nPatchCount].m_pValue = matRowList[0];
pPatchInfo[nPatchCount].m_pValue = matRowList[0];
++nPatchCount;
++nPatchCount;
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB2";
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB2";
pPatchInfo[nPatchCount].m_pValue = matRowList[1];
pPatchInfo[nPatchCount].m_pValue = matRowList[1];
++nPatchCount;
++nPatchCount;
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB3";
pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB3";
pPatchInfo[nPatchCount].m_pValue = matRowList[2];
pPatchInfo[nPatchCount].m_pValue = matRowList[2];
++nPatchCount;
++nPatchCount;
pPatchInfo[nPatchCount].m_pKey = "$envMapOrigin";
pPatchInfo[nPatchCount].m_pKey = "$envMapOrigin";
pPatchInfo[nPatchCount].m_pValue = matRowList[3];
pPatchInfo[nPatchCount].m_pValue = matRowList[3];
++nPatchCount;
++nPatchCount;
}
}
</pre>
</syntaxhighlight>
At the bottom of the function you'll find this line:
 
<pre>
At the bottom of the function, change:
CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_INSERT );
<syntaxhighlight lang="cpp">
</pre>
CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_REPLACE );
Change it to this:
</syntaxhighlight>
<pre>
to:
CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_INSERT );
<syntaxhighlight lang="cpp">
</pre>
CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_INSERT );
Then below that add this:
</syntaxhighlight>
<pre>
 
// Clean up parallax stuff
Then add:
matRowList.PurgeAndDeleteElements();
<syntaxhighlight lang="cpp">
</pre>
// Clean up parallax stuff
matRowList.PurgeAndDeleteElements();
</syntaxhighlight>


Scroll down to the '''Cubemap_CreateTexInfo''' function and change it to this:
Update the <code>Cubemap_CreateTexInfo( ... )</code> function declaration to:
<pre>
<syntaxhighlight lang="cpp">
static int Cubemap_CreateTexInfo( int originalTexInfo, int origin[3], int cubemapIndex )
static int Cubemap_CreateTexInfo( int originalTexInfo, int origin[3], int cubemapIndex )
</pre>
</syntaxhighlight>
Scroll a bit down inside that function and find this line:
<pre>
GeneratePatchedName( "c", info, false, pTextureName, 1024 );
</pre>
Now below that line add this:
<pre>
// Append origin info if this cubemap has a parallax OBB
char originAppendedString[1024] = "";
if (g_pParallaxObbStrs[cubemapIndex][0] != '\0')
{
Q_snprintf(originAppendedString, 1024, "%s;[%d %d %d]", g_pParallaxObbStrs[cubemapIndex], origin[0], origin[1], origin[2]);
}
</pre>
A bit down you'll see this if statement:
<pre>
if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName ) )
</pre>
Change it to:
<pre>
if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName, originAppendedString ) )
</pre>


Scroll down until you find the '''Cubemap_FixupBrushSidesMaterials''' function, and inside it find this line:
After
<pre>
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin );
GeneratePatchedName( "c", info, false, pTextureName, 1024 );
</pre>
</syntaxhighlight>
Change it to this:
add:
<pre>
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin, cubemapID );
// Append origin info if this cubemap has a parallax OBB
</pre>
char originAppendedString[1024] = "";
if ( g_pParallaxObbStrs[cubemapIndex][0] != '\0' )
{
Q_snprintf( originAppendedString, 1024, "%s;[%d %d %d]", g_pParallaxObbStrs[cubemapIndex], origin[0], origin[1], origin[2] );
}
</syntaxhighlight>


Scroll down to the '''Cubemap_AttachDefaultCubemapToSpecularSides''' function, and inside it find this line:
Change
<pre>
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin );
if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName ) )
</pre>
</syntaxhighlight>
Change it to this:
to:
<pre>
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin, iCubemap );
if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName, originAppendedString ) )
</pre>
</syntaxhighlight>


Now we're done with '''cubemap.cpp''', we can now move over to '''vbsp.h'''
In the <code>Cubemap_FixupBrushSidesMaterials( void )</code> function, change:
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin );
</syntaxhighlight>
to:
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin, cubemapID );
</syntaxhighlight>
 
In <code>Cubemap_AttachDefaultCubemapToSpecularSides( void )</code>, change:
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin );
</syntaxhighlight>
to:
<syntaxhighlight lang="cpp">
pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin, iCubemap );
</syntaxhighlight>


=== vbsp.h ===
This completes the changes for {{path|cubemap|cpp}}.


Now find this line:
===vbsp.h===
<pre>
Change the declaration:
<syntaxhighlight lang="cpp">
void Cubemap_InsertSample( const Vector& origin, int size );
void Cubemap_InsertSample( const Vector& origin, int size );
</pre>
</syntaxhighlight>
And change it to this:
to:
<pre>
<syntaxhighlight lang="cpp">
void Cubemap_InsertSample( const Vector& origin, int size, char* pParallaxObbStr );
void Cubemap_InsertSample( const Vector &origin, int size, char *pParallaxObbStr );
</pre>
</syntaxhighlight>
And above that add this:
<pre>
extern char* g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];
</pre>


Now we're done with '''vbsp.h''', now let's go into '''map.cpp'''
Above that, add:
<syntaxhighlight lang="cpp">
extern char *g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];
</syntaxhighlight>


=== map.cpp ===
This completes the changes for {{path|vbsp|h}}.


At the very top, add this include:
===map.cpp===
<pre>
At the top, add:
<syntaxhighlight lang="cpp">
#include "matrixinvert.h"
#include "matrixinvert.h"
</pre>
</syntaxhighlight>
Then scroll down to the '''LoadEntityCallback''' function, then inside it find this line:
<pre>
const char *pSideListStr = ValueForKey( mapent, "sides" );
</pre>
Now below that line, add:
<pre>
char *pParallaxObbStr = ValueForKey( mapent, "parallaxobb" );
</pre>
Then a tiny bit down find this line:
<pre>
Cubemap_InsertSample( mapent->origin, size );
</pre>
And change it to this:
<pre>
Cubemap_InsertSample( mapent->origin, size, pParallaxObbStr);
</pre>
Now below the parent if statement we're in, add this:
<pre>
//
// parallax_obb brushes are removed after the transformation matrix is found and saved into
// the entity's data (ent will be removed after data transferred to patched materials)
//
if (!strcmp("parallax_obb", pClassName))
{
matrix3x4_t obbMatrix, invObbMatrix;
SetIdentityMatrix(obbMatrix);
SetIdentityMatrix(invObbMatrix);


// Get corner and its 3 edges (scaled, local x, y, and z axes)
In the <code>LoadEntityCallback( ... )</code> function, after:
mapbrush_t *brush = &mapbrushes[mapent->firstbrush];
<syntaxhighlight lang="cpp">
Vector corner, x, y, z;
const char *pSideListStr = ValueForKey( mapent, "sides" );
</syntaxhighlight>
add:
<syntaxhighlight lang="cpp">
char *pParallaxObbStr = ValueForKey( mapent, "parallaxobb" );
</syntaxhighlight>


// Find first valid winding (with these whiles, if not enough valid windings then identity matrix is passed through to vmts)
Replace:
int i = 0;
<syntaxhighlight lang="cpp">
while (i < brush->numsides)
Cubemap_InsertSample( mapent->origin, size );
</syntaxhighlight>
with:
<syntaxhighlight lang="cpp">
Cubemap_InsertSample( mapent->origin, size, pParallaxObbStr );
</syntaxhighlight>
 
After the closing bracket of the <code>if</code> statement, add:
<syntaxhighlight lang="cpp">
//
// parallax_obb brushes are removed after the transformation matrix is found and saved into
// the entity's data (ent will be removed after data transferred to patched materials)
//
if ( !strcmp( "parallax_obb", pClassName ) )
{
{
winding_t* wind = brush->original_sides[i].winding;
matrix3x4_t obbMatrix, invObbMatrix;
if (!wind)
SetIdentityMatrix( obbMatrix );
SetIdentityMatrix( invObbMatrix );
 
// Get corner and its 3 edges (scaled, local x, y, and z axes)
mapbrush_t *brush = &mapbrushes[mapent->firstbrush];
Vector corner, x, y, z;
 
// Find first valid winding (with these whiles, if not enough valid windings then identity matrix is passed through to VMTs)
int i = 0;
while ( i < brush->numsides )
{
{
winding_t *wind = brush->original_sides[i].winding;
if ( !wind )
{
i++;
continue;
}
corner = wind->p[0];
y = wind->p[1] - corner;
z = wind->p[3] - corner;
x = CrossProduct( y, z ).Normalized();
i++;
i++;
continue;
break;
}
}


corner = wind->p[0];
// Skip second valid winding (opposite face from first, unusable for finding Z's length)
y = wind->p[1] - corner;
while ( i < brush->numsides )
z = wind->p[3] - corner;
x = CrossProduct(y, z).Normalized();
 
i++;
break;
}
 
// Skip second valid winding (opposite face from first, unusable for finding Z's length)
while (i < brush->numsides)
{
winding_t* wind = brush->original_sides[i].winding;
if (!wind)
{
{
winding_t *wind = brush->original_sides[i].winding;
if ( !wind )
{
i++;
continue;
}
i++;
i++;
continue;
break;
}
}
i++;
break;
}


// Find third valid winding
// Find third valid winding
while (i < brush->numsides)
while ( i < brush->numsides )
{
winding_t* wind = brush->original_sides[i].winding;
if (!wind)
{
{
i++;
winding_t *wind = brush->original_sides[i].winding;
continue;
if ( !wind )
}
{
i++;
continue;
}


// Find length of x
// Find length of X
// Start with diagonal, then scale x by the projection of diag onto x
// Start with diagonal, then scale X by the projection of diag onto X
Vector diag = wind->p[0] - wind->p[2];
Vector diag = wind->p[0] - wind->p[2];
x *= abs(DotProduct(diag, x));
x *= abs( DotProduct( diag, x ) );


// Build transformation matrix (what is needed to turn a [0,0,0] - [1,1,1] cube into this brush)
// Build transformation matrix (what is needed to turn a [0,0,0] - [1,1,1] cube into this brush)
MatrixSetColumn(x, 0, obbMatrix);
MatrixSetColumn( x, 0, obbMatrix );
MatrixSetColumn(y, 1, obbMatrix);
MatrixSetColumn( y, 1, obbMatrix );
MatrixSetColumn(z, 2, obbMatrix);
MatrixSetColumn( z, 2, obbMatrix );
MatrixSetColumn(corner, 3, obbMatrix);
MatrixSetColumn( corner, 3, obbMatrix );


//find inverse (we need the world to local matrix, "transformationmatrix" is kind of a misnomer)
// Find inverse (we need the world to local matrix, "transformationmatrix" is kind of a misnomer)
MatrixInversion(obbMatrix, invObbMatrix);
MatrixInversion( obbMatrix, invObbMatrix );
break;
break;
}
}
char szMatrix[1024];
char szMatrix[1024];
Q_snprintf(szMatrix, 1024, "[%f %f %f %f];[%f %f %f %f];[%f %f %f %f]", invObbMatrix[0][0], invObbMatrix[0][1], invObbMatrix[0][2], invObbMatrix[0][3], invObbMatrix[1][0], invObbMatrix[1][1], invObbMatrix[1][2], invObbMatrix[1][3], invObbMatrix[2][0], invObbMatrix[2][1], invObbMatrix[2][2], invObbMatrix[2][3]);
Q_snprintf( szMatrix, 1024, "[%f %f %f %f];[%f %f %f %f];[%f %f %f %f]", invObbMatrix[0][0], invObbMatrix[0][1], invObbMatrix[0][2], invObbMatrix[0][3], invObbMatrix[1][0], invObbMatrix[1][1], invObbMatrix[1][2], invObbMatrix[1][3], invObbMatrix[2][0], invObbMatrix[2][1], invObbMatrix[2][2], invObbMatrix[2][3] );
SetKeyValue(mapent, "transformationmatrix", szMatrix);
SetKeyValue( mapent, "transformationmatrix", szMatrix );


return (ChunkFile_Ok);
return ( ChunkFile_Ok );
}
</pre>
 
Now scroll down to the '''LoadMapFile''' function, inside it scroll down until you find this line:
<pre>
if ((eResult == ChunkFile_Ok) || (eResult == ChunkFile_EOF))
</pre>
Now above that line, add this:
<pre>
// Fill out parallax obb matrix array
for (int i = 0; i < g_nCubemapSamples; i++)
{
if (g_pParallaxObbStrs[i][0] != '\0')
{
entity_t* obbEnt = EntityByName(g_pParallaxObbStrs[i]);
g_pParallaxObbStrs[i] = ValueForKey(obbEnt, "transformationmatrix");
}
}
}
</syntaxhighlight>


// Remove parallax_obb entities (in a nice slow linear search)
In the <code>LoadMapFile( ... )</code> function, after:
for (int i = 0; i < g_MainMap->num_entities; i++)
<syntaxhighlight lang="cpp">
{
g_LoadingMap->CheckForInstances( pszFileName );
entity_t* mapent = &g_MainMap->entities[i];
</syntaxhighlight>
const char *pClassName = ValueForKey( mapent, "classname" );
add:
if ( !strcmp( "parallax_obb", pClassName ) )
<syntaxhighlight lang="cpp">
if ( g_MainMap == g_LoadingMap )
{
{
mapent->numbrushes = 0;
// Fill out parallax obb matrix array
mapent->epairs = NULL;
for ( int i = 0; i < g_nCubemapSamples; i++ )
{
if ( g_pParallaxObbStrs[i][0] != '\0' )
{
entity_t *obbEnt = EntityByName( g_pParallaxObbStrs[i] );
g_pParallaxObbStrs[i] = ValueForKey( obbEnt, "transformationmatrix" );
}
}
// Remove parallax_obb entities (in a nice slow linear search)
for ( int i = 0; i < g_MainMap->num_entities; i++ )
{
entity_t *mapent = &g_MainMap->entities[i];
const char *pClassName = ValueForKey( mapent, "classname" );
if ( !strcmp( "parallax_obb", pClassName ) )
{
mapent->numbrushes = 0;
mapent->epairs = NULL;
}
}
}
}
}
</syntaxhighlight>
</pre>
 
And that should be it! Try compiling the VBSP project, it should compile without any errors.
 
Now all that's left is moving the freshly compiled '''vbsp.exe''' file to your '''bin''' folder
 
== The Shaders ==
 
Now, the '''fun''' stuff: shader editing! The Parallax Corrected Cubemaps that will now be patched into your materials need a custom LightmappedGeneric shader in order for them to be properly displayed.


Let's start simple. In order to edit shaders, you'll need to open your '''everything.sln''' file. Bonus points if you already had it open!
This completes the changes for {{path|map|cpp}}.  


{{warning|This section is the lengthiest and most tedious, just due to having to compile a custom LightmappedGeneric shader, which can take upwards of 30 minutes per compile, even on beefy computers!}}
The {{vbsp|4}} project should now compile without errors. If errors occur, review the changes for accuracy.


{{note|It's recommended to follow the [[Shader Authoring]] tutorial to get set up with the wonderful DirectX 2008 SDK, and a feel for compiling shaders. This tutorial assumes you're comfortable with that.}}
Once {{code|vbsp.exe}} is compiled, move it to the game's {{path|bin/}} folder (not the mod's {{code|bin/}}; the game's - typically the same one where [[Hammer]] is located).
{{warning|[[Steam]] often replaces custom vbsp.exe with its original version whenever it verifies the file integrity of the game.{{workaround|To prevent the loss of the custom vbsp.exe, rename it, then point to it in [[Hammer]]'s game configuration.}}}}


{{warning|Valve does not like when you override default shaders in the SDK 2013 project. Therefore, we will be creating identical shaders to the lightmappedgeneric one, just with the SDK_ prefix.}}
==The Shaders==
The Parallax Corrected Cubemaps that are now patched into materials require a custom [[LightmappedGeneric]] shader for proper display.


=== Shader C++ Files ===
To edit shaders, open the {{path|everything|sln|icon=file}} file.


Firstly, let's get the LightmappedGeneric shader familiar with the Parallax Corrected bounding boxes you stored in the material.
{{warning|This section is the lengthiest and most tedious, due to the need to compile a custom '''LightmappedGeneric''' shader, which can take upwards of 30 minutes per compile, even on high-end computers.}}


==== lightmappedgeneric_dx9_helper.h ====
{{note|It is recommended to follow the [[Shader Authoring]] tutorial to become familiar with shader compilation. This tutorial assumes a basic understanding of that process.}}


Add the following lines to the end of the '''LightmappedGeneric_DX9_Vars_t''' struct (after the '''int m_nOutlineEnd1;''' member):
===Shader C++ Files===
First, update the '''LightmappedGeneric''' shader to recognize the Parallax Corrected bounding boxes stored in the material.


====lightmappedgeneric_dx9_helper.h====
Add the following lines to the end of the <code>LightmappedGeneric_DX9_Vars_t</code> struct (after the <code>int m_nOutlineEnd1;</code> member):
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
    // Parallax cubemaps
// Parallax cubemaps
    int m_nEnvmapParallaxObb1;
int m_nEnvmapParallaxObb1;
    int m_nEnvmapParallaxObb2;
int m_nEnvmapParallaxObb2;
    int m_nEnvmapParallaxObb3;
int m_nEnvmapParallaxObb3;
    int m_nEnvmapOrigin;
int m_nEnvmapOrigin;
</syntaxhighlight>
</syntaxhighlight>


==== lightmappedgeneric_dx9.cpp ====
====lightmappedgeneric_dx9.cpp====
 
Add the following lines inside the  
As warned about before, we need to turn this into an SDK shader, since compiling a default lightmappedgeneric shader works, but you can't use it in-game. Change the line:
<syntaxhighlight lang="cpp">
 
<pre>
BEGIN_VS_SHADER( LightmappedGeneric, "Help for LightmappedGeneric" )
</pre>
 
to be:
 
<pre>
BEGIN_VS_SHADER( SDK_LightmappedGeneric, "Help for SDK_LightmappedGeneric" )
</pre>
 
Now we need the implementation file to populate these shader parameters. Add the following lines inside of the  
<pre>
BEGIN_SHADER_PARAMS
BEGIN_SHADER_PARAMS
</pre>  
</syntaxhighlight>
block at the top of this file, after the  
block, after the  
<pre>
<syntaxhighlight lang="cpp">
SHADER_PARAM( OUTLINEEND1, SHADER_PARAM_TYPE_FLOAT, "0.0", "outer end value for outline")
SHADER_PARAM( OUTLINEEND1, SHADER_PARAM_TYPE_FLOAT, "0.0", "outer end value for outline")
</pre>  
</syntaxhighlight>
line:
line:
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
        // Parallax cubemaps
// Parallax cubemaps
        SHADER_PARAM(ENVMAPPARALLAXOBB1, SHADER_PARAM_TYPE_VEC4, "[1 0 0 0]", "The first line of the parallax correction OBB matrix")
SHADER_PARAM( ENVMAPPARALLAXOBB1, SHADER_PARAM_TYPE_VEC4, "[1 0 0 0]", "The first line of the parallax correction OBB matrix" )
        SHADER_PARAM(ENVMAPPARALLAXOBB2, SHADER_PARAM_TYPE_VEC4, "[0 1 0 0]", "The second line of the parallax correction OBB matrix")
SHADER_PARAM( ENVMAPPARALLAXOBB2, SHADER_PARAM_TYPE_VEC4, "[0 1 0 0]", "The second line of the parallax correction OBB matrix" )
        SHADER_PARAM(ENVMAPPARALLAXOBB3, SHADER_PARAM_TYPE_VEC4, "[0 0 1 0]", "The third line of the parallax correction OBB matrix")
SHADER_PARAM( ENVMAPPARALLAXOBB3, SHADER_PARAM_TYPE_VEC4, "[0 0 1 0]", "The third line of the parallax correction OBB matrix" )
        SHADER_PARAM(ENVMAPORIGIN, SHADER_PARAM_TYPE_VEC3, "[0 0 0]", "The world space position of the env_cubemap being corrected")
SHADER_PARAM( ENVMAPORIGIN, SHADER_PARAM_TYPE_VEC3, "[0 0 0]", "The world space position of the env_cubemap being corrected" )
</syntaxhighlight>
</syntaxhighlight>


If you did your homework in the [[Shader Authoring]] section, you'll know that this is defining the shader parameters inside of the material file. Now let's assign them to the struct's new members. In the same file, inside of the  
In the same file, inside the
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
void SetupVars( LightmappedGeneric_DX9_Vars_t& info )
void SetupVars( LightmappedGeneric_DX9_Vars_t& info )
</syntaxhighlight>  
</syntaxhighlight>
method, add the following lines at the end of it (after the ''info.m_nOutlineEnd1 = OUTLINEEND1;'' line):
function, add the following lines at the end (after <code>info.m_nOutlineEnd1 = OUTLINEEND1;</code>):
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
        // Parallax cubemaps
// Parallax cubemaps
        info.m_nEnvmapParallaxObb1 = ENVMAPPARALLAXOBB1;
info.m_nEnvmapParallaxObb1 = ENVMAPPARALLAXOBB1;
        info.m_nEnvmapParallaxObb2 = ENVMAPPARALLAXOBB2;
info.m_nEnvmapParallaxObb2 = ENVMAPPARALLAXOBB2;
        info.m_nEnvmapParallaxObb3 = ENVMAPPARALLAXOBB3;
info.m_nEnvmapParallaxObb3 = ENVMAPPARALLAXOBB3;
        info.m_nEnvmapOrigin = ENVMAPORIGIN;
info.m_nEnvmapOrigin = ENVMAPORIGIN;
</syntaxhighlight>
</syntaxhighlight>


Great, now our shader's code knows about our patched parameters. But we still have to do stuff with them!
====lightmappedgeneric_dx9_helper.cpp====
 
Inside
==== lightmappedgeneric_dx9_helper.cpp ====
 
As mentioned before, again, we need to change some prefixes. For your includes, change the lines:
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
#include "lightmappedgeneric_ps20.inc"
void InitParamsLightmappedGeneric_DX9( CBaseVSShader *pShader, IMaterialVar** params, const char *pMaterialName, LightmappedGeneric_DX9_Vars_t &info )
#include "lightmappedgeneric_vs20.inc"
#include "lightmappedgeneric_ps20b.inc"
</syntaxhighlight>
</syntaxhighlight>
 
add the following lines after <code>InitFloatParam( info.m_nOutlineAlpha, params, 1.0 );</code>:
to be:
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
#include "SDK_lightmappedgeneric_ps20.inc"
// Parallax cubemaps
#include "SDK_lightmappedgeneric_vs20.inc"
// Cubemap parallax correction requires all 4 lines (if the 2nd, 3rd, or 4th are undef, undef the first one (checking done on first var)
#include "SDK_lightmappedgeneric_ps20b.inc"
if ( !( params[info.m_nEnvmapParallaxObb2]->IsDefined() && params[info.m_nEnvmapParallaxObb3]->IsDefined() && params[info.m_nEnvmapOrigin]->IsDefined() ) )
{
params[info.m_nEnvmapParallaxObb1]->SetIntValue( 0 );
}
</syntaxhighlight>
</syntaxhighlight>


You'll generate these in a bit, don't worry. But now this will cause some more issues further in the code! You'll need to replace all instances of the code of the default shader to your newly copied SDK one.
In the  
 
For example:
 
<pre>
DECLARE_STATIC_VERTEX_SHADER( lightmappedgeneric_vs20 );
</pre>
 
to:
 
<pre>
DECLARE_STATIC_VERTEX_SHADER( sdk_lightmappedgeneric_vs20 );
</pre>
 
'''DO IT FOR EVERY INSTANCE!''' Changing the imports will help when you come back to compile this module in a bit, as the old '''lightmappedgeneric_*''' shaders will be underlined red, as to help you find where you missed a specific spot.
 
Firstly, let's do a safety check. We need to ensure we have '''all''' the required components for the Parallax Corrected Cubemaps to work properly. Inside of
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
void InitParamsLightmappedGeneric_DX9( CBaseVSShader *pShader, IMaterialVar** params, const char *pMaterialName, LightmappedGeneric_DX9_Vars_t &info )</syntaxhighlight>  
void DrawLightmappedGeneric_DX9_Internal( ... )
near the top of this file, add the following lines of code to the (you guessed it) end of it, after the ''InitFloatParam( info.m_nOutlineAlpha, params, 1.0 );'' line:
</syntaxhighlight>
 
function, after
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
    // Parallax cubemaps
bool hasNormalMapAlphaEnvmapMask = IS_FLAG_SET( MATERIAL_VAR_NORMALMAPALPHAENVMAPMASK );
    //cubemap parallax correction requires all 4 lines (if the 2nd, 3rd, or 4th are undef, undef the first one (checking done on first var)
    if (!(params[info.m_nEnvmapParallaxObb2]->IsDefined() && params[info.m_nEnvmapParallaxObb3]->IsDefined() && params[info.m_nEnvmapOrigin]->IsDefined()))
    {
        params[info.m_nEnvmapParallaxObb1]->SetUndefined();
    }
</syntaxhighlight>
</syntaxhighlight>
 
add:
This allows the parallax-correcting code to not run if there's some issue with your patched materials or something.
 
Next, we need to tell the shader itself whether the above code we added returns true, and if so, to render the parallax corrected cubemap. Inside the
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
void DrawLightmappedGeneric_DX9_Internal(CBaseVSShader *pShader, ...)
// Parallax cubemaps
</syntaxhighlight>
bool hasParallaxCorrection = params[info.m_nEnvmapParallaxObb1]->GetType() == MATERIAL_VAR_TYPE_VECTOR;
method, after the line
<syntaxhighlight lang="cpp">
bool hasNormalMapAlphaEnvmapMask = IS_FLAG_SET( MATERIAL_VAR_NORMALMAPALPHAENVMAPMASK );
</syntaxhighlight>
</syntaxhighlight>


add the following boolean declaration:
Within the <code>if ( g_pHardwareConfig->SupportsPixelShaders_2_b() )</code> block, add before
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
        // Parallax cubemaps
SET_STATIC_PIXEL_SHADER( lightmappedgeneric_ps20b );
        bool hasParallaxCorrection = params[info.m_nEnvmapParallaxObb1]->IsDefined();
</syntaxhighlight>
</syntaxhighlight>
 
the following:
Now let's check this boolean. Further down this gargantuan method, we need to set the combo on the pixel shader. Inside of the  
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
if ( g_pHardwareConfig->SupportsPixelShaders_2_b() )</syntaxhighlight>
// Parallax cubemaps enabled for 2_0b and onwards
block, add the following line '''BEFORE''' the <pre>SET_STATIC_PIXEL_SHADER(sdk_lightmappedgeneric_ps20b);</pre> line:
SET_STATIC_PIXEL_SHADER_COMBO( PARALLAXCORRECT, hasParallaxCorrection );
</syntaxhighlight>


In the <code>else</code> statement for the above, before <code>SET_STATIC_PIXEL_SHADER( lightmappedgeneric_ps20 );</code>, add:
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
// Parallax cubemaps enabled for 2_0b and onwards
// Parallax cubemaps
SET_STATIC_PIXEL_SHADER_COMBO( PARALLAXCORRECT, hasParallaxCorrection );
SET_STATIC_PIXEL_SHADER_COMBO( PARALLAXCORRECT, 0 ); // No parallax cubemaps with ps_2_0 :(
</syntaxhighlight>
</syntaxhighlight>


If you're able to read, you can start to realize what we're going to do next: since Shader Model 2.0 was all the rage for the GoldSource days, and something like parallax corrected cubemaps is a little high-tech for it, we need to enable it only if the graphics card running the engine supports Shader Model 2.0b (and higher). So a little further in this mega-method, inside of the '''else''' statement for the code above, '''RIGHT BEFORE''' the line ''SET_STATIC_PIXEL_SHADER(sdk_lightmappedgeneric_ps20);'', add the following:
Before <code>pContextData->m_SemiStaticCmdsOut.End();</code>, add:
<syntaxhighlight lang="cpp">
// Parallax cubemaps
if ( hasParallaxCorrection )
{
pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant( 21, params[info.m_nEnvmapOrigin]->GetVecValue() );


<syntaxhighlight lang="cpp">
float *vecs[3];
// Parallax cubemaps
vecs[0] = const_cast<float *>( params[info.m_nEnvmapParallaxObb1]->GetVecValue() );
SET_STATIC_PIXEL_SHADER_COMBO(PARALLAXCORRECT, 0); // No parallax cubemaps with ps_2_0 :(
vecs[1] = const_cast<float *>( params[info.m_nEnvmapParallaxObb2]->GetVecValue() );
vecs[2] = const_cast<float *>( params[info.m_nEnvmapParallaxObb3]->GetVecValue() );
float matrix[4][4];
for ( int i = 0; i < 3; i++ )
{
for ( int j = 0; j < 4; j++ )
{
matrix[i][j] = vecs[i][j];
}
}
matrix[3][0] = matrix[3][1] = matrix[3][2] = 0;
matrix[3][3] = 1;
pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant( 22, &matrix[0][0], 4 );
}
</syntaxhighlight>
</syntaxhighlight>


So now our pixel shader (which we're editing next section) knows whether or not it should handle the parallax corrected cubemaps.
===The Shader Files===
 
====lightmappedgeneric_ps2_3_x.h====
Lastly, but certainly not least-ly (I mean come on we still haven't even edited the shader yet!), we need to send the pixel shader the proper value to use to display our parallax-corrected cubemap. So, even further down in this hulking hunk of hot garbage method, RIGHT BEFORE the ''pContextData->m_SemiStaticCmdsOut.End();'' line, add the following block of code:
Below
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
            // Parallax cubemaps
const float4 g_ShadowTweaks : register( c19 );
            if (hasParallaxCorrection)
            {
                pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant(21, params[info.m_nEnvmapOrigin]->GetVecValue());
 
                float* vecs[3];
                vecs[0] = const_cast<float*>(params[info.m_nEnvmapParallaxObb1]->GetVecValue());
                vecs[1] = const_cast<float*>(params[info.m_nEnvmapParallaxObb2]->GetVecValue());
                vecs[2] = const_cast<float*>(params[info.m_nEnvmapParallaxObb3]->GetVecValue());
                float matrix[4][4];
                for (int i = 0; i < 3; i++)
                {
                    for (int j = 0; j < 4; j++)
                    {
                        matrix[i][j] = vecs[i][j];
                    }
                }
                matrix[3][0] = matrix[3][1] = matrix[3][2] = 0;
                matrix[3][3] = 1;
                pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant(22, &matrix[0][0], 4);
            }
</syntaxhighlight>
</syntaxhighlight>
 
add:
Woo! Now our shader has the right data passed into it. Alright, time to put on your DirectX 8 hats on, we're going in!
 
=== The Shader Files ===
 
==== lightmappedgeneric_ps2_3_x.h ====
Now, I know what you're thinking. This isn't anywhere close to a shader file! It's a gosh dang C++ header file! But worry not, this file is included inside of the next file we edit, the actual shader source (FXC) file. So all of this code will actually get compiled into the shader, making it a shader source in disguise!
 
First things first, let's declare us some registers to snag up. If you're wondering why this shader doesn't work with Shader Model 2.0, here is why. Inside this file, right below the <syntaxhighlight lang="cpp">const float4 g_ShadowTweaks : register( c19 );</syntaxhighlight> line, add:
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
// Parallax cubemaps
// Parallax cubemaps
#if (PARALLAXCORRECT)
#if ( PARALLAXCORRECT )
const float3 cubemapPos : register(c21);
const float3 g_CubemapPos : register( c21 );
const float4x4 obbMatrix : register(c22); //through c25
const float4x4 g_ObbMatrix : register( c22 ); // Through c25
#endif
#endif
</syntaxhighlight>
</syntaxhighlight>


Don't worry about that ''PARALLAXCORRECT'', it'll make sense in a bit.
Within the cubemap processing block, after <code>fresnel = fresnel * g_OneMinusFresnelReflection + g_FresnelReflection;</code>, add:
 
Now, let's do the main shader math we need! We can skip further down the file, and find where cubemaps are processed, inside of the <syntaxhighlight lang="cpp">if( bCubemap )</syntaxhighlight> block, add the following block of code after the <syntaxhighlight lang="cpp">fresnel = fresnel * g_OneMinusFresnelReflection + g_FresnelReflection;</syntaxhighlight> line:
 
<syntaxhighlight lang="cpp">
<syntaxhighlight lang="cpp">
        //Parallax correction (2_0b and beyond)
// Parallax correction (2_0b and beyond)
        //Adapted from http://seblagarde.wordpress.com/2012/09/29/image-based-lighting-approaches-and-parallax-corrected-cubemap/
// Adapted from http://seblagarde.wordpress.com/2012/09/29/image-based-lighting-approaches-and-parallax-corrected-cubemap/
#if !(defined(SHADER_MODEL_PS_1_1) || defined(SHADER_MODEL_PS_1_4) || defined(SHADER_MODEL_PS_2_0))
#if !( defined( SHADER_MODEL_PS_1_1 ) || defined( SHADER_MODEL_PS_1_4 ) || defined( SHADER_MODEL_PS_2_0 ) )
#if (PARALLAXCORRECT)
#if ( PARALLAXCORRECT )
        float3 worldPos = i.worldPos_projPosZ.xyz;
float3 worldPos = i.worldPos_projPosZ.xyz;
        float3 positionLS = mul(float4(worldPos, 1), obbMatrix);
float3 positionLS = mul( float4( worldPos, 1 ), g_ObbMatrix );
        float3 rayLS = mul(reflectVect, (float3x3) obbMatrix);
float3 rayLS = mul( reflectVect, (float3x3)g_ObbMatrix );


        float3 firstPlaneIntersect = (float3(1.0f, 1.0f, 1.0f) - positionLS) / rayLS;
float3 firstPlaneIntersect = ( float3( 1.0f, 1.0f, 1.0f ) - positionLS ) / rayLS;
        float3 secondPlaneIntersect = (-positionLS) / rayLS;
float3 secondPlaneIntersect = ( -positionLS ) / rayLS;
        float3 furthestPlane = max(firstPlaneIntersect, secondPlaneIntersect);
float3 furthestPlane = max( firstPlaneIntersect, secondPlaneIntersect );
        float distance = min(furthestPlane.x, min(furthestPlane.y, furthestPlane.z));
float distance = min( furthestPlane.x, min( furthestPlane.y, furthestPlane.z ) );


        // Use distance in WS directly to recover intersection
// Use distance in WS directly to recover intersection
        float3 intersectPositionWS = worldPos + reflectVect * distance;
float3 intersectPositionWS = worldPos + reflectVect * distance;
        reflectVect = intersectPositionWS - cubemapPos;
reflectVect = intersectPositionWS - g_CubemapPos;
#endif
#endif
#endif
#endif
</syntaxhighlight>
</syntaxhighlight>


Wonderful. Our shader will now properly do fancy maths to parallax the cubemap based on the player's position. Onwards to the FXC file!
====lightmappedgeneric_ps2x.fxc====
 
After <code>// STATIC: "FLASHLIGHT" "0..1" [ps20b] [XBOX]</code>, add:
==== A Shader By Any Other Name ====
You'll then need to make a copy of these files:
 
<syntaxhighlight lang="text">
lightmappedgeneric_ps2x.fxc
lightmappedgeneric_ps11.fxc
lightmappedgeneric_vs20.fxc
</syntaxhighlight>
 
And then rename the copies to:
 
<syntaxhighlight lang="text">
SDK_lightmappedgeneric_ps2x.fxc
SDK_lightmappedgeneric_ps11.fxc
SDK_lightmappedgeneric_vs20.fxc
</syntaxhighlight>
 
==== SDK_lightmappedgeneric_ps2x.fxc ====
Heck yeah, here we go, shader file editing! Told you we'd get here! Alright, you ready? Brace yourself, these edits are ''such'' a doozy.
 
Add the following line, after ''// STATIC: "FLASHLIGHT" "0..1" [ps20b] [XBOX]'':
 
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
// STATIC: "PARALLAXCORRECT" "0..1"
// STATIC: "PARALLAXCORRECT" "0..1"
</syntaxhighlight>
</syntaxhighlight>


This is declaring the static combo that our code from the previous section declares. But hold on tight, we still got more!
After <code>// SKIP ($DETAIL_BLEND_MODE == 11 ) && ($BUMPMAP != 0 )</code>, add:
 
We need to optimize the shader to not compile under certain conditions. For example, when shadercompile is working on the Shader Model 2.0 version, we can tell it not to build the version with the Parallax Corrected Cubemaps inside of it. Similarly, if there isn't even a dang cubemap to begin with, we don't want the parallax-correcting code to run! So after the line ''// SKIP ($DETAIL_BLEND_MODE == 11 ) && ($BUMPMAP != 0 )'', add:
 
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
// SKIP: $PARALLAXCORRECT && !$CUBEMAP
// SKIP: $PARALLAXCORRECT && !$CUBEMAP
Line 558: Line 481:
</syntaxhighlight>
</syntaxhighlight>


That's all there is to it! You can open your eyes now. Actually, hopefully they were open for all of this tutorial, because otherwise you will be getting ''very'' interesting results.
===Compile the Shader(s)===
 
Ensure the following shaders are listed in {{path|stdshader_dx9_20b|txt}} (or the custom game file):
=== Compile the Shader(s) ===
{{note|''Psst, if you need extra help with this section, look at the [[Source_SDK_2013:_Your_First_Shader]] page, it's a pretty good resource for compiling shaders!''}}
 
Now we need to compile the shader. Got some coffee to go make? Some meal to go prepare? Some arbitrary 30 minute task? Good! Compiling a custom LightmappedGeneric shader is going to take roughly that time. Any time you need to change anything with the shader, it'll take 30 minutes to fully recompile it! So, hopefully this works in the first try.
 
Inside of your '''stdshader_dx9_20b.txt''' file (or your custom game one, I don't judge), make sure that the following shaders are added:
 
<syntaxhighlight lang="text">
<syntaxhighlight lang="text">
SDK_lightmappedgeneric_ps2x.fxc
lightmappedgeneric_ps2x.fxc
SDK_lightmappedgeneric_ps11.fxc
lightmappedgeneric_ps11.fxc
SDK_lightmappedgeneric_vs20.fxc
lightmappedgeneric_vs20.fxc
</syntaxhighlight>
</syntaxhighlight>


Now, compile. Go do that task I was asking you about. It's gonna take a while because it's a perl script compiling one of the more complex shaders, so it has a lot of combinations to go through. It's going to use all of your resources, too, so don't get spooked. Is it winter? Good, it'll warm up your room.
Compile the shaders. This process may take a significant amount of time. Upon completion, the appropriate {{path|lightmappedgeneric_*|inc|icon=file}} and {{path|lightmappedgeneric_*|vcs|icon=file}} files will be generated. Copy these to the game's {{path|shaders/fxc/}} folder.


When it completes, it will generate the proper ''SDK_lightmappedgeneric_*.inc'' files that your code uses, and you should have your ''SDK_lightmappedgeneric_*.vcs'' files inside of the '''shaders/fxc/''' subdirectory. You can copy these over to your game's '''shaders/fxc/''' folder.
With the new '''[[INC|.inc]]''' files, compile the {{path|game_shader_dx9|sln|icon=file}} project. The resulting {{path|game_shader_dx9|dll|icon=file}} should be copied to the game's {{path|bin/}} folder, alongside the server and client DLLs.


With your new '''.inc''' files, you should be able to compile the ''game_shader_dx9'' project. Ensure the naming of everything matches! If you are missing an SDK_* include, try looking for the file and make sure it's named properly! With the project compiled, you will have a nifty '''game_shader_dx9.dll''' to copy over to your game's bin folder, alongside your server and client DLLs.
==What Next?==


== What Next? ==
===The FGD File===
 
{{CodeBlock|src=parallaxcubes.fgd
=== Using the new SDK_LightmappedGeneric Shader ===
|<nowiki>@include "YOUR FGD HERE. THIS ONE WILL OVERRIDE THE REGULAR ENV_CUBEMAP ENTITY AND ALSO ADD THE PARALLAX_OBB ENTITY. ONLY INCLUDE THIS ONE IN HAMMER."
Now, since Valve doesn't allow the SDK 2013 branch to override the default '''LightmappedGeneric''' shader, you're going to either need to stub the materialsystem and manually replace all of the shaders, or just create/copy VMTs that use the shader.
 
=== The FGD File ===
 
'''parallaxcubes.fgd:'''
<pre>
@include "YOUR FGD HERE. THIS ONE WILL OVERRIDE THE REGULAR ENV_CUBEMAP ENTITY AND ALSO ADD THE PARALLAX_OBB ENTITY. ONLY INCLUDE THIS ONE IN HAMMER."


@PointClass color(0 0 255) sidelist(sides) iconsprite("editor/env_cubemap.vmt") = env_cubemap :  
@PointClass color(0 0 255) sidelist(sides) iconsprite("editor/env_cubemap.vmt") = env_cubemap :  
Line 614: Line 523:
targetname(target_source) : "Name" : : "The name that other entities refer to this entity by."
targetname(target_source) : "Name" : : "The name that other entities refer to this entity by."
]
]
</pre>
</nowiki>}}
 
=== (Optional) Test Map ===
 
{{todo|Coming soon (1.10.2018)}}
 
== Conclusion ==


And that's it, try launching your mod to see if it works!
===(Optional) Test Map===
Instructions for creating Parallax Corrected Cubemaps can be found in the [[{{PAGENAME}}/Creation]] article.


This is currently only tested on the SP branch of Source SDK 2013. The MP branch and Source SDK 2007 remains untested as of writing this article.
{{todo|Test Map coming soon}}


[[Category:Programming]]
==Conclusion==
[[Category:Shaders]]
At this point, the mod should be ready to launch with parallax-corrected cubemaps enabled.
[[Category:Free source code]]

Latest revision as of 11:51, 14 October 2025

English (en)Français (fr)Русский (ru)Translate (Translate)
For the third-party Source brush entity responsible for setting cubemap boundaries, see parallax_obb.
For the Source 2 point entity responsible for both creating both the cubemap and parallax bounding box, see env_cubemap_box.
Comparison of PCC

Overview

Source's native cubemap implementation does not allow them to follow the player's perspective. While this is passable in most cases, tying the reflections to the player's view can increase realism, especially when using high-resolution reflections. A method to achieve this is called parallax correction.

Parallax-corrected cubemaps use a bounding box brush to bake their reflection based on a specified area around them, and a custom shader to make use of it.

This tutorial is based on the work of Brian Charles. A demonstration video can be found here: YouTube logo Parallax Corrected Cubemaps in the Source Engine.

The Code

First, the file

should be added to 🖿<src code directory>/src/utils/vbsp/.

Next, open the project solution (Fileeverything.sln) and navigate to 🖿/utils/vbsp/cubemap.cpp.

cubemap.cpp

Add the following below the SideHasCubemapAndWasntManuallyReferenced( int iSide ) function: 

char *g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];

Then, modify the CubeMap_InsertSample( ... ) function declaration as follows: 

void Cubemap_InsertSample( const Vector &origin, int size, char *pParallaxObbStr = "" )

At the top of the function body, add: 

g_pParallaxObbStrs[g_nCubemapSamples] = pParallaxObbStr;

Update the PatchEnvmapForMaterialAndDependents( ... ) function declaration to: 

static bool PatchEnvmapForMaterialAndDependents( const char *pMaterialName, const PatchInfo_t &info, const char *pCubemapTexture, const char *pParallaxObbMatrix = "" )

Within the if ( pDependentMaterial ) statement, change the code to: 

	bDependentMaterialPatched = PatchEnvmapForMaterialAndDependents( pDependentMaterial, info, pCubemapTexture, pParallaxObbMatrix );

Change 

	MaterialPatchInfo_t pPatchInfo[2];

to: 

	MaterialPatchInfo_t pPatchInfo[6];

Above the line 

	char pDependentPatchedMaterialName[1024];

add: 

	// Parallax cubemap matrix
	CUtlVector<char *> matRowList;
	if ( pParallaxObbMatrix[0] != '\0' )
	{
		V_SplitString( pParallaxObbMatrix, ";", matRowList );
	
		pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB1";
		pPatchInfo[nPatchCount].m_pValue = matRowList[0];
		++nPatchCount;
		pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB2";
		pPatchInfo[nPatchCount].m_pValue = matRowList[1];
		++nPatchCount;
		pPatchInfo[nPatchCount].m_pKey = "$envMapParallaxOBB3";
		pPatchInfo[nPatchCount].m_pValue = matRowList[2];
		++nPatchCount;
		pPatchInfo[nPatchCount].m_pKey = "$envMapOrigin";
		pPatchInfo[nPatchCount].m_pValue = matRowList[3];
		++nPatchCount;
	}

At the bottom of the function, change: 

	CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_REPLACE );

to: 

	CreateMaterialPatch( pMaterialName, pPatchedMaterialName, nPatchCount, pPatchInfo, PATCH_INSERT );

Then add: 

	// Clean up parallax stuff
	matRowList.PurgeAndDeleteElements();

Update the Cubemap_CreateTexInfo( ... ) function declaration to: 

static int Cubemap_CreateTexInfo( int originalTexInfo, int origin[3], int cubemapIndex )

After 

	GeneratePatchedName( "c", info, false, pTextureName, 1024 );

add: 

	// Append origin info if this cubemap has a parallax OBB
	char originAppendedString[1024] = "";
	if ( g_pParallaxObbStrs[cubemapIndex][0] != '\0' )
	{
		Q_snprintf( originAppendedString, 1024, "%s;[%d %d %d]", g_pParallaxObbStrs[cubemapIndex], origin[0], origin[1], origin[2] );
	}

Change 

	if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName ) )

to: 

	if ( !PatchEnvmapForMaterialAndDependents( pMaterialName, info, pTextureName, originAppendedString ) )

In the Cubemap_FixupBrushSidesMaterials( void ) function, change: 

	pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin );

to: 

	pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[cubemapID].origin, cubemapID );

In Cubemap_AttachDefaultCubemapToSpecularSides( void ), change: 

	pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin );

to: 

	pSide->texinfo = Cubemap_CreateTexInfo( pSide->texinfo, g_CubemapSamples[iCubemap].origin, iCubemap );

This completes the changes for 🖿cubemap.cpp.

vbsp.h

Change the declaration: 

void Cubemap_InsertSample( const Vector& origin, int size );

to: 

void Cubemap_InsertSample( const Vector &origin, int size, char *pParallaxObbStr );

Above that, add: 

extern char *g_pParallaxObbStrs[MAX_MAP_CUBEMAPSAMPLES];

This completes the changes for 🖿vbsp.h.

map.cpp

At the top, add: 

#include "matrixinvert.h"

In the LoadEntityCallback( ... ) function, after: 

	const char *pSideListStr = ValueForKey( mapent, "sides" );

add: 

	char *pParallaxObbStr = ValueForKey( mapent, "parallaxobb" );

Replace: 

	Cubemap_InsertSample( mapent->origin, size );

with: 

	Cubemap_InsertSample( mapent->origin, size, pParallaxObbStr );

After the closing bracket of the if statement, add: 

	//
	// parallax_obb brushes are removed after the transformation matrix is found and saved into 
	// the entity's data (ent will be removed after data transferred to patched materials)
	//
	if ( !strcmp( "parallax_obb", pClassName ) )
	{
		matrix3x4_t obbMatrix, invObbMatrix;
		SetIdentityMatrix( obbMatrix );
		SetIdentityMatrix( invObbMatrix );

		// Get corner and its 3 edges (scaled, local x, y, and z axes)
		mapbrush_t *brush = &mapbrushes[mapent->firstbrush];
		Vector corner, x, y, z;

		// Find first valid winding (with these whiles, if not enough valid windings then identity matrix is passed through to VMTs)
		int i = 0;
		while ( i < brush->numsides )
		{
			winding_t *wind = brush->original_sides[i].winding;
			if ( !wind )
			{
				i++;
				continue;
			}

			corner = wind->p[0];
			y = wind->p[1] - corner;
			z = wind->p[3] - corner;
			x = CrossProduct( y, z ).Normalized();

			i++;
			break;
		}

		// Skip second valid winding (opposite face from first, unusable for finding Z's length)
		while ( i < brush->numsides )
		{
			winding_t *wind = brush->original_sides[i].winding;
			if ( !wind )
			{
				i++;
				continue;
			}
			i++;
			break;
		}

		// Find third valid winding
		while ( i < brush->numsides )
		{
			winding_t *wind = brush->original_sides[i].winding;
			if ( !wind )
			{
				i++;
				continue;
			}

			// Find length of X
			// Start with diagonal, then scale X by the projection of diag onto X
			Vector diag = wind->p[0] - wind->p[2];
			x *= abs( DotProduct( diag, x ) );

			// Build transformation matrix (what is needed to turn a [0,0,0] - [1,1,1] cube into this brush)
			MatrixSetColumn( x, 0, obbMatrix );
			MatrixSetColumn( y, 1, obbMatrix );
			MatrixSetColumn( z, 2, obbMatrix );
			MatrixSetColumn( corner, 3, obbMatrix );

			// Find inverse (we need the world to local matrix, "transformationmatrix" is kind of a misnomer)
			MatrixInversion( obbMatrix, invObbMatrix );
			break;
		}
			
		char szMatrix[1024];
		Q_snprintf( szMatrix, 1024, "[%f %f %f %f];[%f %f %f %f];[%f %f %f %f]", invObbMatrix[0][0], invObbMatrix[0][1], invObbMatrix[0][2], invObbMatrix[0][3], invObbMatrix[1][0], invObbMatrix[1][1], invObbMatrix[1][2], invObbMatrix[1][3], invObbMatrix[2][0], invObbMatrix[2][1], invObbMatrix[2][2], invObbMatrix[2][3] );
		SetKeyValue( mapent, "transformationmatrix", szMatrix );

		return ( ChunkFile_Ok );
	}

In the LoadMapFile( ... ) function, after: 

	g_LoadingMap->CheckForInstances( pszFileName );

add: 

	if ( g_MainMap == g_LoadingMap )
	{
		// Fill out parallax obb matrix array
		for ( int i = 0; i < g_nCubemapSamples; i++ )
		{
			if ( g_pParallaxObbStrs[i][0] != '\0' )
			{
				entity_t *obbEnt = EntityByName( g_pParallaxObbStrs[i] );
				g_pParallaxObbStrs[i] = ValueForKey( obbEnt, "transformationmatrix" );
			}
		}
		
		// Remove parallax_obb entities (in a nice slow linear search)
		for ( int i = 0; i < g_MainMap->num_entities; i++ )
		{
			entity_t *mapent = &g_MainMap->entities[i];
			const char *pClassName = ValueForKey( mapent, "classname" );
			if ( !strcmp( "parallax_obb", pClassName ) )
			{
				mapent->numbrushes = 0;
				mapent->epairs = NULL;
			}
		}
	}

This completes the changes for 🖿map.cpp.

The VBSP VBSP project should now compile without errors. If errors occur, review the changes for accuracy.

Once vbsp.exe is compiled, move it to the game's 🖿bin/ folder (not the mod's bin/; the game's - typically the same one where Hammer is located).

Warning.pngWarning:Steam often replaces custom vbsp.exe with its original version whenever it verifies the file integrity of the game.
PlacementTip.pngWorkaround:To prevent the loss of the custom vbsp.exe, rename it, then point to it in Hammer's game configuration.

The Shaders

The Parallax Corrected Cubemaps that are now patched into materials require a custom LightmappedGeneric shader for proper display.

To edit shaders, open the Fileeverything.sln file.

Warning.pngWarning:This section is the lengthiest and most tedious, due to the need to compile a custom LightmappedGeneric shader, which can take upwards of 30 minutes per compile, even on high-end computers.
Note.pngNote:It is recommended to follow the Shader Authoring tutorial to become familiar with shader compilation. This tutorial assumes a basic understanding of that process.

Shader C++ Files

First, update the LightmappedGeneric shader to recognize the Parallax Corrected bounding boxes stored in the material.

lightmappedgeneric_dx9_helper.h

Add the following lines to the end of the LightmappedGeneric_DX9_Vars_t struct (after the int m_nOutlineEnd1; member): 

	// Parallax cubemaps
	int m_nEnvmapParallaxObb1;
	int m_nEnvmapParallaxObb2;
	int m_nEnvmapParallaxObb3;
	int m_nEnvmapOrigin;

lightmappedgeneric_dx9.cpp

Add the following lines inside the 

BEGIN_SHADER_PARAMS

block, after the 

	SHADER_PARAM( OUTLINEEND1, SHADER_PARAM_TYPE_FLOAT, "0.0", "outer end value for outline")

line: 

	// Parallax cubemaps
	SHADER_PARAM( ENVMAPPARALLAXOBB1, SHADER_PARAM_TYPE_VEC4, "[1 0 0 0]", "The first line of the parallax correction OBB matrix" )
	SHADER_PARAM( ENVMAPPARALLAXOBB2, SHADER_PARAM_TYPE_VEC4, "[0 1 0 0]", "The second line of the parallax correction OBB matrix" )
	SHADER_PARAM( ENVMAPPARALLAXOBB3, SHADER_PARAM_TYPE_VEC4, "[0 0 1 0]", "The third line of the parallax correction OBB matrix" )
	SHADER_PARAM( ENVMAPORIGIN, SHADER_PARAM_TYPE_VEC3, "[0 0 0]", "The world space position of the env_cubemap being corrected" )

In the same file, inside the 

void SetupVars( LightmappedGeneric_DX9_Vars_t& info )

function, add the following lines at the end (after info.m_nOutlineEnd1 = OUTLINEEND1;): 

	// Parallax cubemaps
	info.m_nEnvmapParallaxObb1 = ENVMAPPARALLAXOBB1;
	info.m_nEnvmapParallaxObb2 = ENVMAPPARALLAXOBB2;
	info.m_nEnvmapParallaxObb3 = ENVMAPPARALLAXOBB3;
	info.m_nEnvmapOrigin = ENVMAPORIGIN;

lightmappedgeneric_dx9_helper.cpp

Inside 

void InitParamsLightmappedGeneric_DX9( CBaseVSShader *pShader, IMaterialVar** params, const char *pMaterialName, LightmappedGeneric_DX9_Vars_t &info )

add the following lines after InitFloatParam( info.m_nOutlineAlpha, params, 1.0 );: 

	// Parallax cubemaps
	// Cubemap parallax correction requires all 4 lines (if the 2nd, 3rd, or 4th are undef, undef the first one (checking done on first var)
	if ( !( params[info.m_nEnvmapParallaxObb2]->IsDefined() && params[info.m_nEnvmapParallaxObb3]->IsDefined() && params[info.m_nEnvmapOrigin]->IsDefined() ) )
	{
		params[info.m_nEnvmapParallaxObb1]->SetIntValue( 0 );
	}

In the 

void DrawLightmappedGeneric_DX9_Internal( ... )

function, after 

	bool hasNormalMapAlphaEnvmapMask = IS_FLAG_SET( MATERIAL_VAR_NORMALMAPALPHAENVMAPMASK );

add: 

	// Parallax cubemaps
	bool hasParallaxCorrection = params[info.m_nEnvmapParallaxObb1]->GetType() == MATERIAL_VAR_TYPE_VECTOR;

Within the if ( g_pHardwareConfig->SupportsPixelShaders_2_b() ) block, add before 

	SET_STATIC_PIXEL_SHADER( lightmappedgeneric_ps20b );

the following: 

	// Parallax cubemaps enabled for 2_0b and onwards
	SET_STATIC_PIXEL_SHADER_COMBO( PARALLAXCORRECT, hasParallaxCorrection );

In the else statement for the above, before SET_STATIC_PIXEL_SHADER( lightmappedgeneric_ps20 );, add: 

	// Parallax cubemaps
	SET_STATIC_PIXEL_SHADER_COMBO( PARALLAXCORRECT, 0 ); // No parallax cubemaps with ps_2_0 :(

Before pContextData->m_SemiStaticCmdsOut.End();, add: 

	// Parallax cubemaps
	if ( hasParallaxCorrection )
	{
		pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant( 21, params[info.m_nEnvmapOrigin]->GetVecValue() );

		float *vecs[3];
		vecs[0] = const_cast<float *>( params[info.m_nEnvmapParallaxObb1]->GetVecValue() );
		vecs[1] = const_cast<float *>( params[info.m_nEnvmapParallaxObb2]->GetVecValue() );
		vecs[2] = const_cast<float *>( params[info.m_nEnvmapParallaxObb3]->GetVecValue() );
		float matrix[4][4];
		for ( int i = 0; i < 3; i++ )
		{
			for ( int j = 0; j < 4; j++ )
			{
				matrix[i][j] = vecs[i][j];
			}
		}
		matrix[3][0] = matrix[3][1] = matrix[3][2] = 0;
		matrix[3][3] = 1;
		pContextData->m_SemiStaticCmdsOut.SetPixelShaderConstant( 22, &matrix[0][0], 4 );
	}

The Shader Files

lightmappedgeneric_ps2_3_x.h

Below 

const float4 g_ShadowTweaks : register( c19 );

add: 

// Parallax cubemaps
#if ( PARALLAXCORRECT )
const float3 g_CubemapPos : register( c21 );
const float4x4 g_ObbMatrix : register( c22 ); // Through c25
#endif

Within the cubemap processing block, after fresnel = fresnel * g_OneMinusFresnelReflection + g_FresnelReflection;, add: 

	// Parallax correction (2_0b and beyond)
	// Adapted from http://seblagarde.wordpress.com/2012/09/29/image-based-lighting-approaches-and-parallax-corrected-cubemap/
#if !( defined( SHADER_MODEL_PS_1_1 ) || defined( SHADER_MODEL_PS_1_4 ) || defined( SHADER_MODEL_PS_2_0 ) )
#if ( PARALLAXCORRECT )
	float3 worldPos = i.worldPos_projPosZ.xyz;
	float3 positionLS = mul( float4( worldPos, 1 ), g_ObbMatrix );
	float3 rayLS = mul( reflectVect, (float3x3)g_ObbMatrix );

	float3 firstPlaneIntersect = ( float3( 1.0f, 1.0f, 1.0f ) - positionLS ) / rayLS;
	float3 secondPlaneIntersect = ( -positionLS ) / rayLS;
	float3 furthestPlane = max( firstPlaneIntersect, secondPlaneIntersect );
	float distance = min( furthestPlane.x, min( furthestPlane.y, furthestPlane.z ) );

	// Use distance in WS directly to recover intersection
	float3 intersectPositionWS = worldPos + reflectVect * distance;
	reflectVect = intersectPositionWS - g_CubemapPos;
#endif
#endif

lightmappedgeneric_ps2x.fxc

After // STATIC: "FLASHLIGHT" "0..1" [ps20b] [XBOX], add: 

// STATIC: "PARALLAXCORRECT" "0..1"

After // SKIP ($DETAIL_BLEND_MODE == 11 ) && ($BUMPMAP != 0 ), add: 

// SKIP: $PARALLAXCORRECT && !$CUBEMAP
// SKIP: $PARALLAXCORRECT [ps20]

Compile the Shader(s)

Ensure the following shaders are listed in 🖿stdshader_dx9_20b.txt (or the custom game file): 

lightmappedgeneric_ps2x.fxc
lightmappedgeneric_ps11.fxc
lightmappedgeneric_vs20.fxc

Compile the shaders. This process may take a significant amount of time. Upon completion, the appropriate Filelightmappedgeneric_*.inc and Filelightmappedgeneric_*.vcs files will be generated. Copy these to the game's 🖿shaders/fxc/ folder.

With the new .inc files, compile the Filegame_shader_dx9.sln project. The resulting Filegame_shader_dx9.dll should be copied to the game's 🖿bin/ folder, alongside the server and client DLLs.

What Next?

The FGD File

parallaxcubes.fgd
@include "YOUR FGD HERE. THIS ONE WILL OVERRIDE THE REGULAR ENV_CUBEMAP ENTITY AND ALSO ADD THE PARALLAX_OBB ENTITY. ONLY INCLUDE THIS ONE IN HAMMER." @PointClass color(0 0 255) sidelist(sides) iconsprite("editor/env_cubemap.vmt") = env_cubemap : "An entity that creates a sample point for the Cubic Environment Map." [ cubemapsize(choices) : "Cubemap Size" : 0 = [ 0 : "Default" 1 : "1x1" 2 : "2x2" 3 : "4x4" 4 : "8x8" 5 : "16x16" 6 : "32x32" 7 : "64x64" 8 : "128x128" 9 : "256x256" ] sides(sidelist) : "Brush faces": : "(Optional) Brushes faces to directly attach to the env_cubemap. Press Pick then click on faces in the 3D View to select them. Use CTRL while clicking to add or remove from the selection." parallaxobb(target_destination) : "Cubemap Bounds" : : "(Optional) assigns this cubemap a bounding box for parallax correction (brush entity tied to parallax_obb)." ] @SolidClass = parallax_obb [ targetname(target_source) : "Name" : : "The name that other entities refer to this entity by." ]

(Optional) Test Map

Instructions for creating Parallax Corrected Cubemaps can be found in the Parallax Corrected Cubemaps/Creation article.

Todo: Test Map coming soon

Conclusion

At this point, the mod should be ready to launch with parallax-corrected cubemaps enabled.

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Parallax_Corrected_Cubemaps&oldid=490747"