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 fourth 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.
Library	[Begin_Library] [End_Library]	This block of code defines a Library Effect, which is a collection of static variables, constants, directives, and reusable functions. This block is exclusive to Library Effects and cannot be used together with Resource Layout or Pass blocks.
Global	-	All code placed outside of any block will be assigned to the Global section. This can be useful when defining variables that configure a library, such as in the case of FXAA.

Include Metatags

To use a Library Effect in your Graphics or Compute effects, simply include it using the following metatag:

[Include_Library LibraryName LibraryIdentifierNumber]

LibraryName: A human-readable name for your library.
LibraryIdentifierNumber: A unique GUID that identifies the library effect asset.

The advantage of using the GUID is that it remains independent of the asset’s relative path. This means you can move your library assets around the project’s content folders without breaking the references.

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]
};

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: None: Default compilation mode. Debug: Debug mode includes debugging symbols to analyze with shader tools like RenderDoc, PIX, or NVidia Nsight Graphics. See [Profile

Textures Metatags

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.
[Custom`0..N`]	Custom render pipeline texture.

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.

Overridden properties of the RenderLayer tags

These tags allow the pass to modify the render layer properties when the render pipeline runs this pass. To know more details about the RenderLayer properties read this section:

Rasterization Process Tag	Description
[FillMode `Value`]	Determines the fill mode to use when rendering. Available values: WireFrame or Solid
[CullMode `Value`]	Indicates triangles facing the specified direction are not drawn. Available values: None, Front or Back
[FrontCounterClockwise `bool`]	Determines if a triangle is front- or back-facing. If this parameter is true, a triangle will be considered front-facing if its vertices are counter-clockwise on the render target and considered back-facing if they are clockwise. Available values: True or false
[DepthBias `int`]	Depth value added to a given pixel. The value is an integer.
[DepthBiasClamp `float`]	Maximum depth bias of a pixel. The value is a float [0-1].
[SlopeScaledDepthBias `float`]	Scalar on a given pixel's slope. The value is a float.
[DepthClipEnable `bool`]	Enable clipping based on distance. Available values: True or False
[ScissorEnable `bool`]	Enable scissor-rectangle culling. All pixels outside an active scissor rectangle are culled. Available values: True or False
[AntialiasedLineEnable `bool`]	Specifies whether to enable line antialiasing; only applies if doing line drawing and MultisampleEnable is false. Available values: True or _False.

Blend State Tag	Description
[AlphaToCoverageEnable `bool`]	Specifies whether to use alpha-to-coverage as a multisampling technique when setting a pixel to a render target. Available values: True or _False.
[IndependentBlendEnable `bool`]	Specifies whether to enable independent blending in simultaneous render targets. Set to true to enable independent blending. If set to false, only the RenderTarget[0] members are used; RenderTarget[1..7] are ignored. Available values: True or _False.
[RT0BlendEnable `bool`]	Enable (or disable) blending for RenderTarget 0. Available values: True or _False.
[RT0SourceBlendColor `Value`]	This blend option specifies the operation to perform on the RGB value that the pixel shader outputs. The BlendOp member defines how to combine the SrcBlend and DestBlend operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha_ or InverseSecondarySourceAlpha.
[RT0DestinationBlendColor `Value`]	This blend option specifies the operation to perform on the current RGB value in the render target. The BlendOp member defines how to combine the SrcBlend and DestBlend operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha_ or InverseSecondarySourceAlpha.
[RT0BlendOperationColor `Value`]	This blend operation defines how to combine the SrcBlend and DestBlend operations. Available values: Add, Substract, ReverseSubstract, Min or Max.
[RT0SourceBlendAlpha `Value`]	This blend option specifies the operation to perform on the alpha value that the pixel shader outputs. Blend options that end in COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha or InverseSecondarySourceAlpha.
[RT0DestinationBlendAlpha `Value`]	This blend option specifies the operation to perform on the current alpha value in the render target. Blend options that end in COLOR are not allowed. The BlendOpAlpha member defines how to combine the SrcBlendAlpha and DestBlendAlpha operations. Availables values: Zero, One SourceColor, InverseSourceColor, SourceAlpha, InverseSourceAlpha, DestinationAlpha, InverseDesinationAlpha, DestinationColor, InverseDestinatinoColor, SourceAlphaSaturate, BlendFactor, InverseBlendFactor, SecondarySourceColor, InverseSecondarySourceColor, SecondarySourceAlpha or InverseSecondarySourceAlpha.
[RT0BlendOperationAlpha `Value`]	This blend operation defines how to combine the SrcBlendAlpha and DestBlendAlpha operations for RenderTarget 0. Available values: Add, Substract, ReverseSubstract, Min or Max.
[RT0ColorWriteChannels `Value`]	A write mask for Render target 0. Availables values: None, Red, Green, Blue, Alpha or All.

Depth Stencil Tag	Description
[DepthEnable `bool`]	Enable depth testing. Availables values: True or False.
[DepthWriteMask `bool`]	Identify a portion of the depth-stencil buffer that can be modified by depth data. Available values: True or False.
[DepthFunction `Value`]	A function that compares depth data against existing depth data. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[StencilEnable `bool`]	Enable stencil testing. Availables values: True or False.
[StencilReadMask `byte`]	Identify a portion of the depth-stencil buffer for reading stencil data. The value is a byte.
[StencilWriteMask `byte`]	Identify a portion of the depth-stencil buffer for writing stencil data. The value is a byte.
[FrontFaceStencilFailOperation `Value`]	The stencil operation to perform when stencil testing fails in FrontFace Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[FrontFaceStencilDepthFailOperation `Value`]	The stencil operation to perform when stencil testing passes and depth testing fails in FrontFace. Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[FrontFaceStencilPassOperation `Value`]	The stencil operation to perform when stencil testing and depth testing both pass in FrontFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[FrontFaceStencilFunction `Value`]	A function that compares stencil data against existing stencil data in FrontFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[BackFaceStencilFailOperation `Value`]	The stencil operation to perform when stencil testing fails in BackFace Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[BackFaceStencilDepthFailOperation `Value`]	The stencil operation to perform when stencil testing passes and depth testing fails in BackFace. Availables values: Keep, Zero, Replace, IncrementSaturation, DescrementSaturation, Invert, Increment, Decrement.
[BackFaceStencilPassOperation `Value`]	The stencil operation to perform when stencil testing and depth testing both pass in BackFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[BackFaceStencilFunction `Value`]	A function that compares stencil data against existing stencil data in BackFace. Availables values: Never, Less, Equal, LessEqual, Greater, NotEqual, GreaterEqual or Always.
[StencilReference `int`]	The reference value to use when doing a stencil test. The value is a integer.