Difference between revisions of "Shader Authoring"

From Valve Developer Community
Jump to: navigation, search
m (Modify buildsdkshaders.bat path)
m (Link latest release)
 
(29 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 +
{{otherlang2
 +
|ru=Shader_Authoring:ru
 +
}}
 
{{shadertut}}
 
{{shadertut}}
  
This document describes how to author shaders in the Source SDK, for further information on what a shader is and how they can be used, please see [[Shader]].
+
This document describes how to author shaders in the Source SDK, for further information on what a shader is and how they can be used, please see [[Shader]].
  
 
==Getting Started==
 
==Getting Started==
Line 7: Line 10:
 
Every material that is used in Source specifies which shader it uses to render itself. The shader contains the logic and equations to take the source artwork and lighting, and produce the final rendered color for every pixel that the shader is used on.
 
Every material that is used in Source specifies which shader it uses to render itself. The shader contains the logic and equations to take the source artwork and lighting, and produce the final rendered color for every pixel that the shader is used on.
  
The Source SDK fully supports Microsoft DirectX [[HLSL]] (High Level Shading Language) and shader assembly languages for writing shaders. It is recommended to use HLSL whenever possible and to only write shader assembly as a last resort.
+
The Source SDK fully supports Microsoft DirectX [[HLSL]] (High-Level Shading Language) and shader assembly languages for writing shaders. It is recommended to use HLSL whenever possible and to only write shader assembly as a last resort.
  
There are a number of external tools required to compile shaders for use in the Source SDK, the following sections detail the tools and provides links for download along with brief instructions on installation and usage.
+
There are a number of external tools required to compile shaders for use in the Source SDK, the following sections detail the tools and provide links for download along with brief instructions on installation and usage.
  
 
The tools used are Perl, the DirectX SDK and make, the following processes, in general, only have to be performed once before the process of compiling shaders can begin.
 
The tools used are Perl, the DirectX SDK and make, the following processes, in general, only have to be performed once before the process of compiling shaders can begin.
  
===Installing Perl and DirectX===
+
==Options==
To install Perl, go to the [http://www.perl.com/download.csp#win32 download page] on http://www.perl.com , download, and install Perl - a recommended version of Perl for windows is [http://www.activeperl.com ActivePerl].
+
===Perl===
 +
To install Perl, go to the [http://www.perl.com/download.csp#win32 download page] on http://www.perl.com/, download, and install Perl - a recommended version of Perl for Windows is [http://strawberryperl.com/ Strawberry Perl].
  
The Orange Box SDK also relies on the non-standard perl package, String-CRC32. If you are using Active Perl, you can install it through the Perl Package Manager which can be launched from <PerlDir>\bin\ppm.bat
+
The Orange Box SDK also relies on the non-standard Perl package, String::CRC32. If you are using Strawberry Perl, you can install it through the CPAN Client which can be launched from <code><StrawberryPerlInstallDir>\perl\bin\cpan.bat</code>
  
To install the latest DirectX SDK, go to [http://www.microsoft.com/windows/directx Microsoft's DirectX site], download, and install the DirectX SDK. Be sure to get the latest possible version of the SDK, if a previous version is installed, remove it and download a more recent version.
+
Enter the following command to install the package: <code>install String::CRC32</code>
  
{{note|Just having DirectX 9.x installed is '''not''' sufficient, the <code>DirectX SDK</code> must be installed!}}
+
====Installing DirectX====
{{note|<b>It is recommended that you use the November 2008 SDK as needed binaries have been removed from newer releases</b>}}
+
To install the November 2008 DirectX SDK, go to [http://www.microsoft.com/windows/directx Microsoft's DirectX site], download, and install the DirectX SDK. Be sure to get the November 2008 version of the SDK.
  
===Setting The Path===
+
You can download the November 2008 SDK from [http://www.microsoft.com/downloads/details.aspx?FamilyId=5493F76A-6D37-478D-BA17-28B1CCA4865A&displaylang=en here].
With Perl and the DirectX SDK installed, make sure your "Path" environmental variable has been updated appropriately.  In Windows, you can check this by right clicking on properties, going to the Advanced tab, and clicking on "Environment Variables".  Assuming that Perl is installed into <code>C:\Perl</code>, and DirectX into <code>C:\DXSDK</code>, your "Path" variable should contain both <code>C:\Perl\bin</code> and <code>C:\DXSDK\Utilities\bin\x86</code> in a semicolon delimited list.
 
  
By setting up the Environmental Variable in this way, you can update the Perl and DirectX sdk as you please without having to copy files. If for some reason you do not wish to do this, you can simply copy the required files into a different directory and add that to your path instead.
+
{{note|Just having DirectX 9.x installed is '''not''' sufficient, the <code>DirectX SDK</code> must be installed!}}
 
+
{{note|<b>It is recommended that you use the November 2008 SDK as needed binaries (psa.exe, vsa.exe) have been removed from newer releases.</b>}}
Note that you may need to restart your computer for these changes to the environment to take full effect.
 
 
 
===Shader compiling with newer DirectX SDKs===
 
Compiling shaders with newer DirectX SDKs from February 2007 and onwards requires a special flag to be set for the fxc.exe file in order to successfully compile shaders.(This is fixes the out of range errors received) And modification to a shader header file.
 
  
In the mod's code directory
+
====Setting The Path====
 +
With Perl and the DirectX SDK installed, make sure your "Path" environmental variable has been updated appropriately.  In Windows, you can check this by right clicking on My Computer -> properties, going to the Advanced tab, and clicking on "Environment Variables".  Assuming that Perl is installed into <code>C:\Perl</code>, and DirectX into <code>C:\DXSDK</code>, your "Path" variable should contain both <code>C:\Perl\bin</code> and <code>C:\DXSDK\Utilities\bin\x86</code> in a semicolon delimited list. 
  
open \src\devtools\bin\fxc_prep.pl
+
By setting up the Environmental Variable in this way, you can update the Perl and DirectX SDK as you please without having to copy files. If for some reason you do not wish to do this, you can simply copy the required files into a different directory and add that to your path instead.
Find:
 
<pre>
 
$cmd .= "/nologo ";
 
</pre>
 
  
Add Below:
+
{{note|You may need to restart your computer for these changes to the environment to take full effect.}}
<pre>
 
$cmd .= "/LD ";
 
</pre>
 
Save the file and it should be all set.
 
  
===Modify buildsdkshaders.bat path===
+
====Modify buildepisodicshaders.bat====
open MyMod\src\materialsystem\stdshaders\buildsdkshaders.bat and set the GAMEDIR AND SDKBINDIR as instructed.
+
Open "MyMod\src\materialsystem\stdshaders\buildepisodicshaders.bat" and set the GAMEDIR AND SDKBINDIR as instructed.
 +
You might also need to modify the call to vsvars32.bat on line 7. If you are using Visual Studio 2013 it should point to %VS120COMNTOOLS% instead.
  
 
<code>
 
<code>
Line 63: Line 56:
 
  set SDKBINDIR= YOUR PATH HERE
 
  set SDKBINDIR= YOUR PATH HERE
 
</code>
 
</code>
 +
 +
===SCell555's ShaderCompile===
 +
To install Scell555's Shader Compile tools, you must download the zip file which they provide with every [https://github.com/SCell555/ShaderCompile/releases/latest release].
 +
 +
Once you have downloaded the zip file, open it up and you should see the following folders:
 +
*bin
 +
*headers
 +
*stdshaders
 +
 +
place "bin" into "devtools\" and place "stdshaders" into "materialsystem\". If you are using visual studio 2013, then place "headers\VS2013\cshader.h" into "puplic\"; I have not tested other versions of Visual Studio, but I assume that you would use "headers\cshader.h" instead.
 +
 +
====Modify buildepisodicshaders.bat====
 +
Open "materialsystem\stdshaders\buildepisodicshaders.bat" and set the GAMEDIR AND SDKBINDIR as instructed.
 +
You might also need to modify the call to vsvars32.bat on line 7 of "buildsdkshaders.bat". If you are using Visual Studio 2013 it should point to %VS120COMNTOOLS% instead.
 +
An Example:
 +
<code>
 +
@echo off
 +
setlocal
 +
rem ================================
 +
rem ==== MOD PATH CONFIGURATIONS ===
 +
rem == Set the absolute path to your mod's game directory here ==
 +
set GAMEDIR="E:\Half Life 2 Zero\Half Life 2 Zero Game"
 +
rem == Set the relative or absolute path to Source SDK Base 2013 Singleplayer\bin ==
 +
set SDKBINDIR="D:\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\bin"
 +
rem ==  Set the Path to your mod's root source code ==
 +
rem This should already be correct, accepts relative paths only!
 +
set SOURCEDIR="E:\Half Life 2 Zero\Half Life 2 Zero Source"
 +
rem ==== MOD PATH CONFIGURATIONS END ===
 +
rem ====================================
 +
call buildsdkshaders.bat
 +
</code>
 +
Note: You must put quotation marks around paths with spaces in.
 +
 +
====Modify stdshader_dx9_20b.txt====
 +
Open up "materialsystem/stdshaders/stdshader_dx9_20b.txt" and comment out all of the lines which compile shaders like so:
 +
<code>
 +
//
 +
// Standard shaders collection
 +
//
 +
//  These shaders are compiled as the following shader models:
 +
//        _ps20.vcs
 +
//        _ps20b.vcs
 +
//        _vs20.vcs
 +
//
 +
//example_model_ps20b.fxc
 +
//example_model_vs20.fxc
 +
//SDK_Bloom_ps2x.fxc
 +
//SDK_screenspaceeffect_vs20.fxc
 +
//SDK_bloomadd_ps2x.fxc
 +
</code>
 +
 +
====Shader Compile====
 +
[[File:compileshadersmd.png|thumb|an example of a successful compile.]]
 +
Click on the path bar in the "materialsystem/stdshaders" folder, and type "cmd". Next, type in the name of the bat file for compiling your shaders; it will probably be "buildepisodicshaders.bat". If you did everything correctly, it should compile with no issues.
  
 
== See also ==
 
== See also ==
 
* You can get more information about HLSL and shader assembly programming in [http://msdn2.microsoft.com/en-us/library/bb509561.aspx the online MSDN docs].
 
* You can get more information about HLSL and shader assembly programming in [http://msdn2.microsoft.com/en-us/library/bb509561.aspx the online MSDN docs].
 
* [[:Category:Material System]] -- for more general information on the usage of shaders in materials.
 
* [[:Category:Material System]] -- for more general information on the usage of shaders in materials.
* [http://www.wraiyth.com/index.php?q=node/5 Wraiyths Shader Tutorials]
 
 
{{otherlang:en}}
 
{{otherlang:en:ru|Shader Authoring:ru}}
 
  
 
[[Category: Programming]]
 
[[Category: Programming]]
 
[[Category: Shaders]]
 
[[Category: Shaders]]
[[Category:Outdated programming articles]]
 

Latest revision as of 13:48, 23 March 2020

Русский

This document describes how to author shaders in the Source SDK, for further information on what a shader is and how they can be used, please see Shader.

Getting Started

Every material that is used in Source specifies which shader it uses to render itself. The shader contains the logic and equations to take the source artwork and lighting, and produce the final rendered color for every pixel that the shader is used on.

The Source SDK fully supports Microsoft DirectX HLSL (High-Level Shading Language) and shader assembly languages for writing shaders. It is recommended to use HLSL whenever possible and to only write shader assembly as a last resort.

There are a number of external tools required to compile shaders for use in the Source SDK, the following sections detail the tools and provide links for download along with brief instructions on installation and usage.

The tools used are Perl, the DirectX SDK and make, the following processes, in general, only have to be performed once before the process of compiling shaders can begin.

Options

Perl

To install Perl, go to the download page on http://www.perl.com/, download, and install Perl - a recommended version of Perl for Windows is Strawberry Perl.

The Orange Box SDK also relies on the non-standard Perl package, String::CRC32. If you are using Strawberry Perl, you can install it through the CPAN Client which can be launched from <StrawberryPerlInstallDir>\perl\bin\cpan.bat

Enter the following command to install the package: install String::CRC32

Installing DirectX

To install the November 2008 DirectX SDK, go to Microsoft's DirectX site, download, and install the DirectX SDK. Be sure to get the November 2008 version of the SDK.

You can download the November 2008 SDK from here.

Note:Just having DirectX 9.x installed is not sufficient, the DirectX SDK must be installed!
Note:It is recommended that you use the November 2008 SDK as needed binaries (psa.exe, vsa.exe) have been removed from newer releases.

Setting The Path

With Perl and the DirectX SDK installed, make sure your "Path" environmental variable has been updated appropriately. In Windows, you can check this by right clicking on My Computer -> properties, going to the Advanced tab, and clicking on "Environment Variables". Assuming that Perl is installed into C:\Perl, and DirectX into C:\DXSDK, your "Path" variable should contain both C:\Perl\bin and C:\DXSDK\Utilities\bin\x86 in a semicolon delimited list.

By setting up the Environmental Variable in this way, you can update the Perl and DirectX SDK as you please without having to copy files. If for some reason you do not wish to do this, you can simply copy the required files into a different directory and add that to your path instead.

Note:You may need to restart your computer for these changes to the environment to take full effect.

Modify buildepisodicshaders.bat

Open "MyMod\src\materialsystem\stdshaders\buildepisodicshaders.bat" and set the GAMEDIR AND SDKBINDIR as instructed. You might also need to modify the call to vsvars32.bat on line 7. If you are using Visual Studio 2013 it should point to %VS120COMNTOOLS% instead.

rem == Set the absolute path to your mod's game directory here ==
rem == Note that this path needs does not support long file/directory names ==
rem == So instead of a path such as "C:\Program Files\Steam\steamapps\mymod" ==
rem == you need to find the 8.3 abbreviation for the directory name using 'dir /x' ==
rem == and set the directory to something like C:\PROGRA~2\Steam\steamapps\sourcemods\mymod ==
set GAMEDIR= YOUR PATH HERE
rem == Set the relative path to SourceSDK\bin\orangebox\bin ==
rem == As above, this path does not support long directory names or spaces ==
rem == e.g. ..\..\..\..\..\PROGRA~2\Steam\steamapps\<USER NAME>\sourcesdk\bin\orangebox\bin ==
set SDKBINDIR= YOUR PATH HERE

SCell555's ShaderCompile

To install Scell555's Shader Compile tools, you must download the zip file which they provide with every release.

Once you have downloaded the zip file, open it up and you should see the following folders:

  • bin
  • headers
  • stdshaders

place "bin" into "devtools\" and place "stdshaders" into "materialsystem\". If you are using visual studio 2013, then place "headers\VS2013\cshader.h" into "puplic\"; I have not tested other versions of Visual Studio, but I assume that you would use "headers\cshader.h" instead.

Modify buildepisodicshaders.bat

Open "materialsystem\stdshaders\buildepisodicshaders.bat" and set the GAMEDIR AND SDKBINDIR as instructed. You might also need to modify the call to vsvars32.bat on line 7 of "buildsdkshaders.bat". If you are using Visual Studio 2013 it should point to %VS120COMNTOOLS% instead. An Example:

@echo off
setlocal
rem ================================
rem ==== MOD PATH CONFIGURATIONS ===
rem == Set the absolute path to your mod's game directory here ==
set GAMEDIR="E:\Half Life 2 Zero\Half Life 2 Zero Game"
rem == Set the relative or absolute path to Source SDK Base 2013 Singleplayer\bin ==
set SDKBINDIR="D:\Steam\steamapps\common\Source SDK Base 2013 Singleplayer\bin"
rem ==  Set the Path to your mod's root source code ==
rem This should already be correct, accepts relative paths only!
set SOURCEDIR="E:\Half Life 2 Zero\Half Life 2 Zero Source"
rem ==== MOD PATH CONFIGURATIONS END ===
rem ====================================
call buildsdkshaders.bat

Note: You must put quotation marks around paths with spaces in.

Modify stdshader_dx9_20b.txt

Open up "materialsystem/stdshaders/stdshader_dx9_20b.txt" and comment out all of the lines which compile shaders like so:

//
// Standard shaders collection
//
//  These shaders are compiled as the following shader models:
//        _ps20.vcs
//        _ps20b.vcs
//        _vs20.vcs
//
//example_model_ps20b.fxc
//example_model_vs20.fxc
//SDK_Bloom_ps2x.fxc
//SDK_screenspaceeffect_vs20.fxc
//SDK_bloomadd_ps2x.fxc

Shader Compile

an example of a successful compile.

Click on the path bar in the "materialsystem/stdshaders" folder, and type "cmd". Next, type in the name of the bat file for compiling your shaders; it will probably be "buildepisodicshaders.bat". If you did everything correctly, it should compile with no issues.

See also