L. Spiro Shader Language

Documentation for L. Spiro Engine

L. Spiro Shader Language

Postby L. Spiro » Fri Aug 05, 2011 5:44 am

Table of Contents
  • Overview
  • Syntax
    • Variables
    • Flow Control
    • Functions
    • Statements
  • Semantics
  • Intrinsics
  • Preprocessor

L. Spiro Shader Language (LSSL) was created in order to guarantee support for all intended platforms, now and forever. There are no high-level shader languages for Nintendo Wii, for example, so a new language must be made if the engine is to be fully cross-platform. The goal is that the user writes only one shader that simply works on all platforms. System-provided macros do allow platform-specific code, however.
It works by generating a new shader specifically for the current target platform. For OpenGL builds, this means your LSSL code becomes GLSL. For DirectX it becomes HLSL, iOS becomes ESSL or the Metal shading language, etc.

LSSL uses standard shader-language C-like syntax. While LSSL borrows from GLSL, it more closely resembles HLSL, so closely in fact that anyone who can write an HLSL shader can write an LSSL shader.
Declaration Syntax
Code: Select all
[Storage_Class] [Type_Modifier] Type Name[Index]
    [: Semantic]
    [= Initial_Value]

[Storage_Class] wrote:
  • uniform

[Type_Modifier] wrote:
  • const

Type wrote:One of the LSSL datatypes.

Name[Index] wrote:A string identifier that uniquely identifies the variable. To define an optional array, use index for the array size, which is a positive integer ≥ 1.

[: Semantic] wrote:Optional parameter-usage information, used by the compiler to link shader inputs and outputs. Must be one of the predefined semantics.

[= Initial_Value] wrote:Optional initial value(s); the number of values should match the number of components in Type.

Declaration Examples
Code: Select all
float fVar;
float4 vColor;
float fVar = 3.1f;
int iVar[3];
int iVar[3] = { 1, 2, 3 };
uniform float4 g_vDiffuse : MATDIFFUSE;
const float4 vLightDir = { 0, 0, 1 };
const float3 vLightDir : SPOTLIGHTDIR = { 0, 0, 1 };

Data Types
  • sampler1d, sampler2d, sampler3d, samplerCube: Used to sample textures. The TEXUNIT# semantic is used to indicate which texture slot will be sampled by the sampler. Samplers must be uniforms.
Code: Select all
uniform sampler Name : TEXUNIT#;

Declaration and Usage Examples
Code: Select all
uniform sampler2d g_sSampler2dTex0 : TEXUNIT0;

_vOutColor.xyz = tex2d( g_sSampler2dTex0, _vIn2dTex0 ).xyz; // _vIn2dTex0 is a 2D texture coordinate.

  • float, int, uint, bool: Scalars. int and uint will be implemented as float’s on most hardware, used to emulate the functionality of int’s and uint’s. As such, they can be used to index into arrays.
Declaration and Usage Examples
Code: Select all
uniform int g_iTotalDirlights : DIRLIGHTCOUNT;
uint uiCount = 0;
for ( int I = 0; I < iTotal; I++ )
bool bLights;
if ( bLights )
float fCos = dot( g_vLightHalfVectors[_iIndex].xyz, _vNormalInViewSpace );

  • vec2, vec3, vec4, float[2], float[3], float[4], int[2], int[3], int[4], uint[2], uint[3], uint[4], bool[2], bool[3], bool[4]: Vectors. Vectors can contain between 2 and 4 components. Graphics hardware works best with vectors of 4 components, as they are designed to operate on 4 components in parallel. vec2, vec3, and vec4 are shorter forms of float[2], float[3], and float[4], respectively. Operations on vectors with scalars are per-component. That is, the operation takes place on each component of the vector separately.
Declaration and Usage Examples
Code: Select all
uniform vec4 g_vLightVectors[LSE_MAX_LIGHTS] : LIGHTVECTOR;
vec3 vNormalizedNormal = tex2d( LSE_NORMALTEXSAMPLER, LSE_NORMALTEX ).xyz;
vNormalizedNormal = vNormalizedNormal * 2.0f - 1.0f;

  • matrix[X][Y]: Matrices. Matrices are always of type float. X and Y can both be between 2 and 4.
Declaration and Usage Examples
Code: Select all
uniform float[4][4] g_mModelViewMatrix : WORLDVIEW;
_vOutEyePos = mul( g_mModelViewMatrix, vec4( _vInPos, 1.0f ) );

  • void: A return type for functions that have no return value. The Main() function must be of this type.
Declaration and Usage Examples
Code: Select all
void Main( in vec3 _vInPos : POSITION0, out vec4 _vOutPos : POSITION0 )

  • struct/user-defined types: User-defined types are declared with the struct keyword.
Code: Select all
struct Name {
    Type[RxC] MemberName;

Name wrote:
  • An identifier that uniquely names the structure.

Type[RxC] wrote:
  • The member type with an optional row (R) x column (C) array size. The number of rows and columns are unsigned integers between 2 and 4 inclusive.

MemberName wrote:
  • An identifier that uniquely names the member within the structure.

Semantics can be applied to variables to indicate how they are used. Certain semantics are used only with uniforms (global values in a shader) and others are used with inputs and outputs to and from the Main() function. Semantics used anywhere else are invalid.
Semantics are syntactically equal to those of HLSL, but unlike in HLSL, semantics on global uniforms actually have meaning to the engine. That is, applying the WORLDVIEW semantic to a 4×4 matrix in HLSL does not mean that that matrix will actually be updated with the world-view matrix when the shader is used. In L. Spiro Engine, however, all global semantics are updated with their appropriate values at render time, saving the user the trouble of performing the update him- or her- self.
Like in HLSL, semantics on Main() inputs and outputs are used for linking to vertex buffer attributes.
Global Uniforms
  • AMBIENTLIGHT: vec4 type indicating the amount of ambient light.
  • LIGHTCOUNT: int type indicating the number of lights active.
  • DIRLIGHTCOUNT: int type indicating the number of directional lights active. Of the active lights, the first ones are directional.
  • POINTLIGHTCOUNT: int type indicating the number of point lights active. Of the active lights, point lights immediately follow directional lights.
  • SPOTLIGHTCOUNT: int type indicating the number of spot lights active. Of the active lights, spot lights immediately follow point lights.
  • LIGHTVECTOR: vec4[LSE_MAX_LIGHTS] type containing an array of light vectors. For directional lights, this represents the direction of the light. For point and spot lights, this represents the position of the current light.
  • LIGHTHALFVECTOR: vec4[LSE_MAX_LIGHTS] type containing an array of half vectors used with directional lights. Using these values results in a lighting model that assumes that both the light and the viewer are infinitely far away from the object being rendered, and results in a poorer lighting model. It is typically better to calculate the half vector for each lighting calculation.
  • SPOTLIGHTDIR: vec3[LSE_MAX_LIGHTS] type containing the directions of spot lights.
  • LIGHTAMBIENT: vec4[LSE_MAX_LIGHTS] type containing the ambient value of each light.
  • LIGHTDIFFUSE: vec4[LSE_MAX_LIGHTS] type containing the diffuse value of each light.
  • LIGHTSPECULAR: vec4[LSE_MAX_LIGHTS] type containing the specular value of each light.
  • LIGHTATT: vec4[LSE_MAX_LIGHTS] type. Deprecated.
  • SPOTLIGHTRANGE: vec4[LSE_MAX_LIGHTS] type. Deprecated.
  • SKYCOLOR: vec4 type containing the color of the sky. Used in hemisphere lighting.
  • GROUNDCOLOR: vec4 type containing the color of the ground. Used in hemisphere lighting.
  • MATAMBIENT: vec4 type containing the currently set material ambient color.
  • MATDIFFUSE: vec4 type containing the currently set material diffuse color.
  • MATEMISSIVE: vec4 type containing the currently set material emissive color.
  • MATSPECULAR: vec4 type containing the currently set material specular color.
  • MATPOWER: float type containing the currently set material specular power.
  • FOGSTART: float type containing the fog starting distance.
  • FOGEND: float type containing the fog ending distance.
  • FOGCOLOR: vec4 type containing the fog color.
  • SHADOWMAPPING: bool type indicating whether or not shadow-mapping is enabled. If true, the highest texture slot (LSE_MAX_TEXTURE_UNITS-1) will contain a 2D texture intended to be used with shadow-mapping.
  • TEXMATRIX: float[4][4] array of [LSE_MAX_TEXTURE_UNITS] length containing the texture matrices.
  • TEXUNIT#: sampler1d, sampler2d, sampler3d, or samplerCube type indicating from which texture slot the sample will read.
  • NORMALMATRIX: float[3][3] type containing the normal matrix. Used to transform normals into view space. This is equal to the WORLDVIEW matrix cast to a 3×3 matrix. Note that normals are not always guaranteed to be normalized after this operation.
  • VIEW: float[4][4] type containing the view matrix.
  • WORLD: float[4][4] type containing the world matrix.
  • WORLDVIEW: float[4][4] type containing the world-view matrix. Used to transform points into view space—that as, points are transformed first by the world matrix and then by the view matrix.
  • WORLDVIEWPROJ: float[4][4] type containing the world-view-projection matrix. Used to transform points into eye (sometimes called camera) space.
It is amazing how often people try to be unique, and yet they are always trying to make others be like them.
- L. Spiro 2011
L. Spiro
Site Admin
Posts: 54
Joined: Thu Jul 21, 2011 2:59 pm
Location: Tokyo, Japan

Return to Documentation

Who is online

Users browsing this forum: No registered users and 1 guest