Material shaders
Material shaders are assigned to parts of models to define how the part will be drawn with each set of shaders.
Some of these declarations are defined directly with these names and some are macro definitions to ensure version compability.
If you rename the VS, GS and PS functions, the engine will not find them.
VS must be a vertex shader taking object space vertices of the type VS_structure as input.
This is the vertex structure that is used in the models.
PS must be a pixel shader returning a four channel color. The alpha channel can be used for alpha filtering if the model use it.
GS is an optional geometry shader that modify the output of your vertex shader on a per triangle level.
If you have geometry shader named GS then PS must take the same input type that was returned by the geometry shader instead of the type returned by the vertex shader.
Using only vertex and pixel shader:
VS_structure -> VS -> YourTypeA -> PS -> float4
Using vertex, geometry and pixel shader:
VS_structure -> VS -> YourTypeA -> GS -> YourTypeB -> PS -> float4
Texture slots
// The model part's 16 textures or overriding surfaces from the instance.
// You can set textures using Model_Part_SetTexture or Model_Part_SetTexture_ByName_InSB but the model editor can do it for you.
// Unused textures may contain a default texture since a default value don't give any clue about what is missing on a model.
// A drawsurface can also be used by using Model_Part_SetTextureOverride and Instance_SetTextureOverride.
// For all shaders.
Texture2D tex_0
...
Texture2D tex_15
// The texture that you have assigned as the global light altas.
// Only for pixel shaders!
Texture2D tex_lightAtlas
// The depth atlas used for depth based shadows.
// Only for pixel shaders!
Texture2D tex_depthAtlas
// A copy of the depth buffer used for soft particles.
// The surface that you draw to must have an extra depth buffer to store the copy.
// Only models using filters may sample this because the copy is created after rendering the fully occluding geometry.
// Only for pixel shaders!
Texture2D tex_depthBufferCopy
Samplers
// Sampling without interpolation.
// For all shaders.
SamplerState samConstant
// Sharp bilinear sampling.
// Only for pixel shaders!
SamplerState samSharp
// Like samConstant but with clamped texture coordinates.
// For all shaders.
SamplerState samClampedConstant
// Like samSharp but with clamped texture coordinates.
// Only for pixel shaders!
SamplerState samClampedSharp
// Anisotropic filtering and mipmaps for high quality sampling.
// Only for pixel shaders!
SamplerState samAnisotropicMipmap
// Mipmap without anisotropic filtering for fast sampling that may be blurred.
// Only for pixel shaders!
SamplerState samMipmap
// 4 point lesser comparison filter used by the light system.
// Only for pixel shaders!
SamplerComparisonState samShadow
Input structure
// This is the type for the input argument in the vertex shader. Use the data for calculation in the vertex shader or just give it to the pixel shader.
struct VS_structure
Containing:
float4 Pos // X,Y,Z,1 The static object space position and padding for matrix multiplication.
float4 Tex // U1,V1,U2,V2 Two sets of UV coordinates for mapping flat textures to 3D models.
float4 Color // CR,CG,CB,CA The vertex color that can be used for other things by using another shader.
float3 Normal // NX,NY,NZ Normal in object or bone space if BDW > -1.
float Selected // Not saved with models but used when editing to show selection.
float4 A // AX,AY,AZ,AW The userdefined A vector that you may use as you wish by modifying the model editor.
float4 B // BX,BY,BZ,BW The userdefined B vector that you may use as you wish by modifying the model editor.
float4 BoneData // BDX,BDY,BDZ,BDW Bone data with a position relative to the start of the bone in BDX..BDZ and the index of the bone in BDW. This can not be used for anything else.
Arguments
// The array of vectors from 0 to 15 given to the instance using Instance_SetUserDefinedData.
// The default value for each vector is float4(0.0f,0.0f,0.0f,0.0f)
// For all shaders.
float4 Arg[0..15]
Matrices
// The instance's matrix for converting positions from object space to world space.
// For all shaders.
float4x4 ObjectToWorld
// The camera's inverse matrix for converting positions from world space to camera space.
// For all shaders.
float4x4 WorldToCamera
// The camera's inverse matrix for converting positions from world space to camera space without refraction.
// For all shaders.
float4x4 WorldToCamera_NoRefraction
// The camera's projection matrix for converting positions from world space to camera space.
// For all shaders.
float4x4 CameraToImage
// CameraToImage * WorldToCamera for faster multiplication when a shader don't use camera space.
// This is used to optimize shadow vertex shaders.
// For all shaders.
float4x4 WorldToImage
Vectors
// RGBA color for the fog and background.
// For all shaders.
float4 FogColor
// This is the color given to the instance using Instance_SetColor.
// The default value is float4(1.0f,1.0f,1.0f,1.0f)
// For all shaders.
float4 InstanceColor
// This is the current camera's position in world space that is used by Engine_GetDiffuseAndSpecularLight.
// For all shaders.
float3 CameraPos_WorldSpace
// The width and height of the output surface just like in the post effect shaders.
// For all shaders.
float2 Dimensions
// The ambient light that is included in the diffuse light.
// For all shaders.
float3 AmbientLight
Scalars
// The camera space depth where pixels are too close to be drawn.
// For all shaders.
float NearClipPlane
// The camera space depth where pixels are too far away to be drawn.
// Also called FogDistance.
// For all shaders.
float FarClipPlane
// A global time variable that you can set using Shader_SetGlobalTime.
// For all shaders.
float GlobalTime
// The distance from the camera where the fog will end.
// Any pixels further away should be clipped to make smooth turning of the camera.
// Also called FarClipPlane.
// For all shaders.
float FogDistance
// The fog ratio at the maximum distance
// For all shaders.
float MaxFogIntensity
// A value from 0 to 2 for low to high detail level.
// Use it for adjusting the triangle count in geometry shaders.
float DetailLevel
// A macro for getting the X scale from the projection matrix called CameraToImage.
float CameraXScale
// A macro for getting the Y scale from the projection matrix called CameraToImage.
float CameraYScale
Macros
// A macro used when rendering reflections and refractions for flat surfaces so that a cutting plane in the camera will cut away all pixels on the negative side of the plane
#define UseCuttingPlane(WORLD_SPACE_POS) if (EnableCuttingPlane > 0.5f) { clip(dot(WORLD_SPACE_POS.xyz,CuttingPlane.xyz) - CuttingPlane.w); }
Methods
// A HLSL subroutine returning the sum of diffuse light from any direction from the engine's light sources.
// Ambient light is included to the diffuse light.
// Pos_WorldSpace is the drawn pixel's position in world space.
// SumOfDiffuseLight is the diffuse result.
// Only for pixel shaders!
void Engine_GetUndirectedLight ( in float3 Pos_WorldSpace, out float3 SumOfDiffuseLight );
// A HLSL subroutine returning the sum of diffuse light from the engine's light sources.
// Ambient light is added to the diffuse light.
// Pos_WorldSpace is the drawn pixel's position in world space.
// Normal_WorldSpace is the draw pixel's normal in world space.
// SumOfDiffuseLight is the diffuse result.
// Only for pixel shaders!
void Engine_GetDiffuseLight ( in float3 Pos_WorldSpace, in float3 Normal_WorldSpace, out float3 SumOfDiffuseLight )
// A HLSL subroutine returning the sums of diffuse and specular light from the engine's light sources.
// Ambient light is added to the diffuse light.
// Pos_WorldSpace is the drawn pixel's position in world space.
// Normal_WorldSpace is the draw pixel's normal in world space.
// SpecularSharpness is used to affect how the specular light is diffused in angles without affecting the maximum intensity.
// A higher value gives a sharper specular reflection.
// SumOfDiffuseLight is the diffuse result.
// SumOfSpecularLight is the specular result.
// To increase the specular level, multiply this result.
// Only for pixel shaders!
void Engine_GetDiffuseAndSpecularLight ( in float3 Pos_WorldSpace, in float3 Normal_WorldSpace, in float SpecularSharpness, out float3 SumOfDiffuseLight, out float3 SumOfSpecularLight )
// A HLSL subroutine returning the bone space to object space matrix for bone number BoneIndex.
// The vertex data in BoneData.w contains a reference number to the bone or -1 for regular bonespace.
// Since Pos in the vertex data is always defined in object space, positions in bone space (relative to the bone's center of rotation) are stored in BoneData.xyz.
// When BoneData.w > -1, you should multiply BoneData.xyz with the bone space to object space matrix returned by this routine with BoneData.w as BoneIndex. Then you have your animated object space position.
// Since storing normals and tangent space in both object space and bone space, they are represented in bone space when attached to a bone and object space otherwise.
// Only for vertex and geometry shaders! Give the result directly to the pixel shader if you need it there since the bone's reference number would get lost on the way to the pixel shader.
void Engine_GetBoneMatrix ( in int BoneIndex, out float4x4 BoneToObject );
// A HLSL subroutine returning the UserData for bone number BoneIndex.
// You can use this for any data that you want to store per bone in both the model's default pose and in animations using the bone frame.
// For example, you can use it for deforming vertices connected to the bone, clip pixels on destroyed bones or fade between skins with different types of damage.
// There is no big cost in using it because the data is stored in the padding of the bone matrix.
// Only for vertex and geometry shaders! Give the result directly to the pixel shader if you need it there since the bone's reference number would get lost on the way to the pixel shader.
void Engine_GetBoneUserData ( in int BoneIndex, out float3 UserData );