Effect Metatags

In Evergine, effects are written in HLSL language, but to automate some tasks, Evergine includes additional tags that you can add to the HLSL code.

Block Metatags

Effect codes are organized into two important kinds of blocks:

Block Tags Description
Resource Layout [Begin_ResourceLayout]
[End_ResourceLayout]		 This block of code defines all resources (Constant Buffers, Structured Buffers, Textures, and Samplers) using all effect passes.
Pass [Begin_Pass:PassName]
[End_Pass]		 This block of code defines a RenderPipeline pass. The DefaultRenderPipeline defines three passes that any effect can define: ZPrePass, Distortion, Default.

Directives Metatags

Inside a resource layout block, you can define the directive set that your custom effect will have. Directives are useful to enable different features of your effect.

A directive can be defined as a two-value On/Off feature or can define a feature with multiple values:
[Directive:Name A_OFF A]
[Directive:Name A_OFF B C D ...]

Example:
[Directive:NormalMapping Normal_OFF, Normal]
[Directive:ShadowFilter Shadow_OFF, ShadowFilter3, ShadowFilter5, ShadowFilter7]

An effect is a set of shaders (known as Uber-shader), and directives help you define this set of shaders. The directives automatically generate multiple shaders when the effects are compiled.

Example:
[Directive:Name A_OFF A] will generate a shader with A enabled and another shader with A disabled.
[Directive:Name A_OFF B C D ...] will generate A, B, C, D ... shaders.

Additionally, if you define several directives, it will multiply the combinations. In that case, if you define two directives:
[Directive:FeatureA A_OFF A]
[Directive:FeatureB B_OFF C D]
It will generate the following shader combinations: A_OFF-B_OFF, A-B_OFF, A_OFF-C, A-C, A_OFF-D, A-D.

The number of combinations is multiplied by the number of effect passes, so a complex effect would have hundreds or thousands of combinations.

The effects can compile their combinations on-demand at runtime or pre-compile combinations beforehand and use them later at runtime without compilation. This allows you to generate a bundle with compiled shader combinations. To know more details, go to this section.

You can shape your effect code with the #if, #else, and #endif preprocessor directives:

#if TEX
    // This code is compiled only if TEX directive is used...
    finalColor = ColorTexture.Sample(ColorSampler, input.Tex); 
#else
    // If TEX directive is not present, this code is reached...
    finalColor = ColorAttribute; 
#endif

Or use any directive combinations:

#if TEX || NORMAL
    // This code is compiled only if TEX and NORMAL directives are used...
    output.texCoord = input.TexCoord; 
#endif

Default Values Metatag

Evergine allows injecting default values into constant buffer attributes automatically using tags.

Default values can be injected directly using the [Default(value)] tag:

cbuffer Parameters : register(b0)
{
    float SpeedFactor : packoffset(c0.x); [Default(1.5)]
    float3 Position   : packoffset(c0.y); [Default(2.3, 3.3, 5.6)]
}

The default value tag supports the following types: int, float, bool, float2, float3, float4.

Inject Engine Parameters

Evergine allows injecting engine data into resource layout resources (Constant Buffers attributes and Textures) automatically using tags.

For example, in the following code, the [WorldViewProjection] metatag is used to inject the object world view projection matrix:

cbuffer PerDrawCall : register(b0)
{
    float4x4 WorldViewProj : packoffset(c0); [WorldViewProjection]
};

List of Parameter Tags

Here you can find a complete list of available parameter tags that you can use in your effects:

Parameters Tag Type Update Policy Description
[FrameID] long PerFrame Gets Frame ID.
[DrawContextID] int PerView Gets draw context ID.
[DrawContextViewIndex] int PerView Gets the view index of this draw context. A draw context can contain several views (cascade shadow, point light shadows, reflection probe, etc.).
[World] Matrix4x4 PerDrawCall Gets the world value of the current render mesh.
[View] Matrix4x4 PerView Gets the view value of the current camera.
[ViewInverse] Matrix4x4 PerView Gets the view inverse value of the current camera.
[Projection] Matrix4x4 PerView Gets the projection value of the current camera.
[UnjitteredProjection] Matrix4x4 PerView Gets the unjittered projection value of the current camera.
[ProjectionInverse] Matrix4x4 PerView Gets the projection inverse value of the current camera.
[ViewProjection] Matrix4x4 PerView Gets the view projection value of the current camera.
[UnjitteredViewProjection] Matrix4x4 PerView Gets the unjittered view projection value of the current camera.
[PreviousViewProjection] Matrix4x4 PerView Gets the view projection value of the current camera in the previous frame.
[WorldViewProjection] Matrix4x4 PerDrawCall Gets the world view projection value of the current camera and mesh.
[UnjitteredWorldViewProjection] Matrix4x4 PerDrawCall Gets the unjittered (TAA) world view projection value of the current camera and mesh.
[WorldInverse] Matrix4x4 PerDrawCall Gets the inverse world value of the current render mesh.
[WorldInverseTranspose] Matrix4x4 PerDrawCall Gets the world inverse transpose of the current mesh.
[Time] float PerFrame Gets the time value since the game has started.
[CameraPosition] Vector3 PerView Gets the position value of the current camera.
[CameraJitter] Vector2 PerView Gets the current frame camera jittering.
[CameraPreviousJitter] Vector2 PerView Gets the previous frame camera jittering.
[CameraRight] Vector3 PerView Gets the right component of the camera orientation.
[CameraUp] Vector3 PerView Gets the up component of the camera orientation.
[CameraForward] Vector3 PerView Gets the forward component of the camera orientation.
[CameraFocalDistance] float PerView Gets the camera focal distance (used with DoF).
[CameraFocalLength] float PerView Gets the camera focal length.
[CameraAperture] float PerView Gets the camera aperture.
[CameraExposure] float PerView Gets the camera exposure.
[CameraFarPlane] float PerView Gets the far plane of the camera.
[CameraNearPlane] float PerView Gets the near plane of the camera.
[ViewProjectionInverse] Matrix4x4 PerView Gets the inverse of the view projection value of the current camera.
[MultiviewCount] int PerView Gets the number of eyes to be rendered.
[MultiviewProjection] Matrix4x4 PerView Gets the stereo camera projection.
[MultiviewView] Matrix4x4 PerView Gets the stereo camera view.
[MultiviewViewProjection] Matrix4x4 PerView Gets the stereo camera view projection.
[MultiviewViewProjectionInverse] Matrix4x4 PerView Gets the stereo camera inverse view projection.
[MultiviewPosition] Vector4 PerView Gets the stereo camera view.
[ForwardLightMask] ulong PerDrawCall Gets the lighting mask, used in Forward passes.
[LightCount] uint PerView Gets the number of lights.
[LightBuffer] IntPtr PerView Gets the light buffer ptr.
[LightBufferSize] uint PerView Gets the light buffer size.
[ShadowViewProjectionBuffer] IntPtr PerView Gets the shadow view projection buffer pointer.
[ShadowViewProjectionBufferSize] uint PerView Gets the shadow view projection buffer size.
[IBLMipMapLevel] uint PerFrame Gets the IBL texture mipmap level.
[IBLLuminance] float PerFrame Gets the IBL luminance.
[IrradianceSH] IntPtr PerFrame Gets the irradiance spherical harmonics buffer ptr.
[IrradianceSHBufferSize] uint PerFrame Gets the irradiance spherical harmonics buffer size.
[EV100] float PerView Gets the Exposition Value at ISO 100.
[Exposure] float PerView Gets the camera exposure.
[SunDirection] Vector3 PerFrame Gets the sun direction.
[SunColor] Vector3 PerFrame Gets the sun color.
[SunIntensity] float PerFrame Gets the sun intensity.
[SkyboxTransform] Matrix4x4 PerFrame Gets the skybox transform.
Texture Tag Description
[Framebuffer] Framebuffer texture.
[DepthBuffer] Depth buffer texture.
[GBuffer] GBuffer texture.
[Lighting] Lighting texture.
[DFGLut] Lookup table for DFG precalculated texture.
[IBLRadiance] IBL Prefiltered Mipmapped radiance environment texture.
[ZPrePass] ZPrePass in forward rendering (Normal + Roughness).
[DistortionPass] Distortion pass in forward rendering.
[IBLIrradiance] IBL diffuse irradiance map.
[TemporalHistory] Temporal AA history texture.
[DirectionalShadowMap] Shadow map array texture.
[SpotShadowMap] Shadow map array texture.
[PunctualShadowMap] Shadow map array cube texture.
[Custom0..N] Custom render pipeline texture.

Pass Settings Metatags

These tags are used inside a pass block code and are useful to configure which settings you want to compile for this pass.

Tag Description
[Profile API_Level] Defines HLSL language version and capabilities. The API level values could be:
  • 9_1: DirectX9.1 HLSL 3.0.
  • 9_2: DirectX 9.2 HLSL 3.0
  • 9_3: DirectX 9.3 HLSL 3.0
  • 10_0: DirectX 10 HLSL 4.0
  • 10_1: DirectX 10.1 HLSL 4.1
  • 11_0: DirectX 11 HLSL 5.0
  • 11_1: DirectX 11 HLSL 5.0
  • 12_0: DirectX 12 HLSL 6.0
  • 12_1: DirectX 12 HLSL 6.1
  • 12_3: DirectX 12 HLSL 6.3 (Raytracing)
[EntryPoints Stage=MethodName] Defines the entry point stage methods of the pass. The valid stage values are:
  • VS: Vertex Shader.
  • HS: Hull Shader.
  • DS: Domain Shader.
  • GS: Geometry Shader.
  • PS: Pixel Shader.
  • CS: Compute Shader.
[Mode value] Defines the compilation mode of the pass. Available mode list: