<p align="center"> <img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/logo.png"> </p>

---

<p align="center"> <img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/demo.gif"> </p>

SamGLShaders

A small utility library for using OpenGL 3.3 shaders in vanilla Serious Sam The Second Encounter v1.07 game.

1. Who is this for?
2. Installation
   1. For regular users
   2. For developers
3. Default shaders
4. Basic usage
   1. For regular users
      1. Shader entry point
      2. GLDefaultProfile
      3. Shader profile
      4. Shader description
      5. Shader sources
      6. Default shader uniforms and variables
      7. Custom entities
         1. GLModelHolder
         2. GLModelHolderAnimationChanger
         3. GLCubeMapBaker
      8. Demo level
      9. So how do I create my own shader?
   2. For developers
5. What does not work
6. License
7. 3rd party notice

---

Who is this for?<a name="brief"></a>

This library is usable both for those who are creating custom maps and for those who develop mods using Serious Sam's SDK 1.07 via Visual Studio 6.0 compiler.

This library is not well tested, but has been confirmed to work on multiple NVIDIA cards.

Installation<a name="install"></a>

For regular users<a name="install_regular"></a>

To install this library, go to the releases github page and download the latest zip file. Extract it to your Serious Sam TSE 1.07 root directory. Steam version should work too.

For developers<a name="install_devs"></a>

Clone this repository and place content of Sources directory inside SDK's Sources directory, so that 'GLShaders' directory and, for example, 'EntitiesMP' are on the same level. If you are willing to recompile this library from sources, add GLShaders.dsp project to your workspace as a dependency of EntitiesMP, provide link and include directories for glew and jansson third-party libraries and you are ready to go.

Default shaders<a name="default_shaders_example"></a>

SamGLShaders provides some shaders as example on how to use this library. Here is their description:

• GL3 Base - simple shader that tries to mimic the look and feel of Serious Sam's default Base shader in SKAStudio

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/base.png">

• GL3 Lul - shader that demonstrates usage of sprite in vertex program, and dynamic texture mapping in fragment program

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/lul.png">

• GL3 Reflection - shader that uses cubemaps to render reflections

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/ref.png">

• GL3 Sprite - this shader is meant to show how shader profiles work in terms of directory and file structure

• GL3 SS2 Standard - shader that tries to mimic basic look and feel of Serious Sam 2 model rendering

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/ss2.png">

• GL3 SS3 Standard - shader that tries to mimic basic look and feel of Serious Sam 3 model rendering

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/ss3.png">

• GL3 Water - this shader is an example of how to render a simple water surface

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/water.png">

Basic usage<a name="usage"></a>

For regular users<a name="usage_regular"></a>

SamGLShaders uses SKA models. They are very convenient, mostly because they enable this whole project to work. With SKA models, a 'shader' concept was introduced to the Serious Engine. While default shaders are not shaders at all in our modern sense of this word, they provide a very important property - ability to modify rendering pipeline. SamGLShaders, due to limitations of it being an add-on on top of the vanilla engine, introduces the concept of 'shaders profile'.

A Shader profile is simply a set of 20 shaders. While number 20 is pretty limited and has been picked arbitrarily, the number of profiles is not limited at all.

---

IMPORTANT - Before we continue, it must be noted that SamGLShaders library does NOT use textures that are provided by Serious Engine. Instead, it tries to load .tga source of that texture to support greater resolution. However, regular .tex textures are still required as placeholders for SKAStudio and the engine itself.

---

Here is a structure of Shaders directory, that is used to store your shaders:

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/structure.png">

Shader entry point<a name="entry_point"></a>

Is a simple text file, that defines index of a shader that it describes. Shader entry point is not linked to a particular shader profile, it only tells engine the name of a shader, and its number in currently enabled profile.

Here is a content of GL3 Base.sha file:

Package: TFNM Bin\GLShadersMP.module
Name: Shader_GLShader_1
Info: Shader_Desc_GLShader_1

In general, proper content should strictly follow this pattern:

Package: TFNM Bin\GLShadersMP.module
Name: Shader_GLShader_<NUMBER_BETWEEN_1_AND_20>
Info: Shader_Desc_GLShader_<SAME_NUMBER_AS_ABOVE>

GLDefaultProfile<a name="default_profile"></a>

As stated above, shader entry point is not linked to a profile, the profile itself is bound dynamically by an external entity, like GLModelHolder, which is set up by user. Because SKAStudio cannot have entities and only serves as a model viewer, the contents of this file are interpreted as a name of a profile that should be enabled by default. That means, when you want to create your new custom shader profile (which you should always do to be compatible with all other possible shaders), you should edit this file and make sure that your profile's name is saved in it. While one profile is enabled, SKAStudio CAN NOT work with shaders from other profiles! The game itself works fine though.

Shader profile<a name="shader_profile"></a>

Basically, its a directory that can contain up to 20 shaders. Here is a structure of a typical shader profile:

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/profile.png">

Shader description<a name="shader_descr"></a>

Is a json plain text file, that describes shader and defines is properties. All shader description files should be called by this pattern:

GLShader_<NUMBER_BETWEEN_1_AND_20>.json

Here is a quick overview of what can be written in a typical json for your shader:

<img src="https://raw.githubusercontent.com/SeriousAlexej/SamGLShaders/master/images/shader.png">

Lets look closer at each field:

• vertex_shader - relative path to your vertex shader.

• fragment_shader - relative path to your fragment shader.

• name - shader name, not really used, just a quick description of shader.

• texture_wrapping_x texture_wrapping_y - these two parameters describe how textures are wrapped. Possible values: clamp, repeat

• depth_test - enables depth testing.

• depth_write - enables depth writing.

• depth_func - comparison that determines whether fragment is close enough to be visible. Possible values: never, less, less or equal, equal, not equal, greater or equal, greater, always.

• culling - determines which faces are culled. Possible values: front, back, none.

• alpha_test - if enabled, fragmens with less than half alpha channel are considered transparent.

• blending - enables blending.

• blend_src_mode blend_dst_mode - these two parameters specify coefficients that are applied to blend function. Possible values: one, zero, src color, inv src color, dst color, inv dst color, src alpha, inv src alpha.

• uv_map_1 uv_map_2 - these two parameters describe GLSL uniforms that are used to identify UV maps. Only two UV maps are supported simultaniously. All uniform values are json objects that have two fields:

  • shader_name - name of corresponding variable in your shader source code.
  • name - how it is displayed in SKAStudio GUI.

• custom_floats - number of custom float uniforms, provided for shader. Useful only for programmers, more details about this below.

• custom_vecs - numver of custom vec3 uniforms, provided for shader. Similar to custom_floats.

• textures - array of objects that describe texture uniform variables. Quantity potentially unlimited. Supported texture samplers are: sampler2D, samplerCube.

• floats - array of objects that describe float uniform variables. Quantity potentially unlimited.

• colors - array of objects that describe vec3 uniform variables for colors. Quantity potentially unlimited.

• flags - array of objects that describe boolean uniform variables. Maximum number is 8.

Shader sources<a name="shader_sources"></a>

Are actual GLSL code that does all the job. To learn more about GLSL, please read proper documentation, books, use google, whatever. GLSL help is not provided here and to use this library you have to know how to writ